> ## 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.

# SDK reference

> The public mirrors-sdk methods for context retrieval and trace delivery.

This reference covers `mirrors-sdk@0.6.2`. Start with the [quickstart](/docs/quickstart)
for integration code.

## Constructor

`new Mirrors({ apiUrl, apiKey, agentId })` creates a client for one agent. Reuse it
across that agent's conversations. Keep keys in server secrets. Node.js 22 or later
is required; ES modules and CommonJS are supported.

## Context retrieval

`getContext({ trace }, { signal?, timeoutMs? })` returns a promise for:

| Field | Meaning |
| - | - |
| `context` | Plain text for the system prompt; empty on no-match or fallback. |
| `mode` | `active`, `shadow`, or `off`. |
| `delivery` | `accepted`, `unconfirmed`, or `canceled`. |
| `reason` | Server decision reason or local fallback reason. |
| `elapsedMs` | Time spent in retrieval. |
| `freshness` | Request, trace, decision, mode-version, issue-time, and expiry bindings; otherwise null. |

The call's `timeoutMs` may shorten the total 1,000 ms wait budget to 1–1,000 ms.
The SDK allows up to 16 concurrent context waits. A newer retrieval for the same
trace supersedes the older pending wait. Changed captured evidence, finalization,
release, local disable, and shutdown invalidate pending retrievals.

`accepted` means a server decision was received. It does not report that your
application applied the context or that the agent succeeded.

## Trace capture

`captureTrace({ trace, final, terminal? })` returns a delivery ticket immediately.
It captures original history in the background without returning context.

`ticket.receipt` is the current delivery status. `ticket.done` resolves with the
settled receipt. Observe it outside the model execution path. A final capture can
queue ingestion; queued analysis is not completed analysis.

The optional `terminal` value is `completed`, `failed`, or `canceled` and is valid
only on final capture. See [trace capture](/docs/guides/trace-capture) for the schema.

## Lifecycle

| Method | Purpose |
| - | - |
| `releaseTrace(traceId)` | Release local execution state when no final evidence is available. Does not claim server completion. |
| `flush({ timeoutMs })` | Wait for captures pending at call time. Returns a `complete` boolean and accepted, dropped, unconfirmed, and pending counts. |
| `diagnostics()` | Inspect local delivery and execution counters. |
| `setEnabled(false)` | Locally disable the client and invalidate pending optional work. |
| `setEnabled(true)` | Re-enable a locally disabled client. |
| `dispose()` | Permanently stop the client, including heartbeat and optional work. |

Never reuse a released or completed execution ID. Call `flush` before `dispose`
when you want an explicit bounded capture drain.

## Existing integrations

`sendTrace`, `prefetchTrace`, `submitTrace`, `injectSystemPrompt`, and `close` remain
available for compatibility. Awaiting legacy `sendTrace` does not wait for fresh
context. New integrations should use `getContext` and `captureTrace` directly.


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