Skip to main content

sdac-log-conversation-turn

Purpose​

Logs a single conversation turn (user message or assistant response) to SDAC.fact_ConversationHistory. Provides a durable audit trail of every exchange in a review session and makes history available for context hydration via sdac-get-conversation-history.

Tool type​

Deterministic (write)

Tool ID​

sdac-log-conversation-turn

Inputs​

  • conversationId (string, required) -- Session ID from sdac-start-conversation
  • reportId (string, required, UUID) -- Cost report ID
  • userId (string, required) -- User identifier
  • role (user | assistant, required) -- Message role
  • messageContent (string, required) -- Message text content
  • turnNumber (number, optional) -- Specific turn number; auto-incremented from the last logged turn if omitted
  • personnelId (number, optional) -- If the turn relates to a specific personnel record
  • ruleId (string, optional) -- If the turn relates to a specific validation rule
  • modelUsed (string, optional) -- AI model used for assistant responses (for analytics)
  • promptTokens (number, optional) -- Prompt token count
  • completionTokens (number, optional) -- Completion token count

Outputs​

  • logged (boolean) -- Always true on success
  • conversationSK (number) -- Database primary key of the inserted record
  • turnNumber (number) -- The turn number that was assigned

Example output​

{
  "logged": true,
  "conversationSK": 1289,
  "turnNumber": 5
}

Functional details​

  • If turnNumber is omitted, the tool reads the current maximum turn number for the conversation and increments by 1.
  • totalTokens is computed as promptTokens + completionTokens when both are provided.
  • The returned conversationSK can be passed to sdac-store-feedback to anchor user feedback to a specific turn.

Usage notes​

  • Log both sides of every exchange: call once for the user message and once for the assistant response.
  • Include modelUsed and token counts on assistant turns for cost and performance analytics.
  • Part of the session management trio: sdac-start-conversation → sdac-get-conversation-history → sdac-log-conversation-turn.

Implementation details​

  • Writes to SDAC.fact_ConversationHistory via the insertConversationTurn DB helper.

Code Location: packages/domain-sdac/src/tools/session/log-conversation-turn.tool.ts