sdac-get-conversation-history

Purpose

Retrieves the most recent conversation turns for a session from SDAC.fact_ConversationHistory. Use this to reconstruct context at the start of a multi-turn chat or after a page reload so the agent can refer to prior messages.

Tool type

Deterministic (read-only)

Tool ID

sdac-get-conversation-history

Inputs

• conversationId (string, required) -- Session ID returned by sdac-start-conversation
• maxTurns (number, optional, default: 10) -- Maximum number of recent turns to retrieve (1-50)

Outputs

• turns (array) -- Conversation turns in chronological order
  • turnNumber (number)
  • role (user | assistant | system)
  • content (string)
  • timestamp (string) -- ISO 8601
  • personnelId (number | null) -- Set if the turn relates to a specific personnel record
  • ruleId (string | null) -- Set if the turn relates to a specific validation rule
• totalTurns (number) -- Total turn count for the conversation (may exceed maxTurns)
• reportId (string) -- Cost report ID associated with the conversation
• isExpired (boolean) -- True if the conversation is 90+ days old

Example output

{
  "turns": [
    {
      "turnNumber": 1,
      "role": "user",
      "content": "Provide the fringe analysis.",
      "timestamp": "2026-05-08T14:20:00.000Z",
      "personnelId": null,
      "ruleId": null
    },
    {
      "turnNumber": 2,
      "role": "assistant",
      "content": "The fringe increase appears proportional to salary.",
      "timestamp": "2026-05-08T14:20:02.000Z",
      "personnelId": null,
      "ruleId": "FRINGE_VARIANCE"
    }
  ],
  "totalTurns": 2,
  "reportId": "SDAC-2024-Q2-001",
  "isExpired": false
}

Functional details

• Returns an empty turns array (not an error) when the conversation is not found or has expired.
• Also exported as historyToMessages() helper to convert turns into the { role, content } message format expected by agent generate() calls.
• Expired conversations return isExpired: true with turns: [] and the last known reportId.

Usage notes

• Call at the start of a chat handler to hydrate agent context from prior turns.
• Filter out role: system turns before passing history to the LLM (the exported helper does this automatically).
• Part of the session management trio: sdac-start-conversation → sdac-get-conversation-history → sdac-log-conversation-turn.

Implementation details

• Reads from SDAC.fact_ConversationHistory via getConversationHistory and getConversationMetadata DB helpers.

Code Location: packages/domain-sdac/src/tools/session/get-conversation-history.tool.ts