> ## Documentation Index
> Fetch the complete documentation index at: https://mirrors.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Capture conversation traces

> Preserve original history, tool associations, and completion state.

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.

```ts theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.