Capture conversation traces

A trace describes one execution or conversation. Send the full original history available at each capture point, using the same id until that execution ends. Create a new ID for a new execution, including after restarting your process.

import { randomUUID } from "node:crypto";
import type { CanonicalTrace } from "mirrors-sdk";

const trace: CanonicalTrace = {
  id: randomUUID(),
  messages: [
    { role: "system", content: "Answer questions using the order lookup tool." },
    { role: "user", content: "Has order 123 shipped?" },
    {
      role: "assistant",
      content: [{
        type: "tool-call",
        callId: "lookup-1",
        name: "lookup_order",
        arguments: { orderId: "123" },
      }],
    },
    {
      role: "tool",
      content: [{
        type: "tool-result",
        callId: "lookup-1",
        name: "lookup_order",
        value: { status: "shipped" },
        error: false,
      }],
    },
    { role: "assistant", content: "Order 123 has shipped." },
  ],
};

This is an illustrative completed conversation. Map your application’s actual history into this format; do not substitute the example for real evidence.

Preserve the source

Messages support system, user, assistant, and tool roles. Content can be a string or ordered blocks: text, reasoning, tool-call, tool-result, or media. Preserve tool-call IDs and their corresponding results, including error flags. Include reasoning only when it is already present in the source history. Do not invent missing messages, flatten tool results into unrelated text, mutate original history, or capture Mirrors-added context as an original instruction. If the source is incomplete, use the trace’s completeness fields to describe that fact rather than representing it as a complete execution. Keep completeness, model, and entryPoint unchanged for a trace across capture and context requests. Use final and terminal to report live completion; these metadata fields are not a progress indicator. The SDK rejects malformed evidence and limits a canonical snapshot to 1,000,000 encoded bytes and 10,000 messages. Do not silently truncate data to fit. Decide which conversations can be captured faithfully and inspect dropped receipts.

Capture and completion

captureTrace({ trace, final: false }) queues background capture without waiting for the model. On completion, send the full final snapshot with final: true and the appropriate terminal status. Accepted final captures queue ingestion when the history supports analysis. A receipt with ingestion unsupported_history has no analysis job; inspect the original message structure and supported content.

Receipt	Meaning
`pending`	The SDK has not settled delivery.
`accepted`	The server accepted the request. Inspect ingestion separately.
`dropped`	The SDK rejected or could not queue the request; inspect `reason`.
`unconfirmed`	Transport did not establish acceptance. The write may still have committed.

Inspect ticket.receipt, or await ticket.done outside model execution. Capture uses bounded in-memory queues; it does not promise durable delivery after a crash. At shutdown, flush waits for tickets pending when it was called, then dispose stops the client.

Get started

Guides

SDK

Capture conversation traces

Preserve the source

Capture and completion

​Preserve the source

​Capture and completion

Preserve the source

Capture and completion