Skip to main content
This reference covers the published mirrors-sdk gem 0.2.0, for Ruby 3.3 or later. Start with the Ruby quickstart to connect your model loop. The gem has no runtime dependencies beyond Ruby’s standard libraries.

Client and context

Require "mirrors_sdk" and create MirrorsSDK::Mirrors.new(api_url: ..., api_key: ..., agent_id: ...) once per agent configuration. Keep the key in server secrets. Create clients after processes fork; an inherited client returns forked_process and must be replaced in the child. get_context(trace, timeout_ms: 1000, cancel: nil) synchronously returns a ContextResult with these attributes: The total foreground budget is 1–1,000 ms from method entry, including copying and scheduling. Retrieval sends current history independently of capture uploads. Scheduling delays can exceed the budget. The method blocks its calling thread; there is no Ruby async retrieval API. Use returned text promptly for the same model request. If dispatch is delayed, check result.freshness.expires_at; if history changes, retrieve again. A newer retrieval, changed evidence, finalization, release, mode change, expiry, disable, or disposal invalidates pending context. Text already returned cannot be recalled. accepted confirms a response arrived, not that your application used it. Unknown or expired mode returns empty fallback immediately. Confirmed shadow also returns empty while evaluating in the background; off performs no retrieval. Capture continues in every server mode. See runtime modes.

Cancellation

Pass a MirrorsSDK::Cancellation token and call its cancel method from your application’s cancellation hook:
application_cancellation_error is your existing exception, not an SDK class. Preserve your application’s cancellation check before calling its model provider. A canceled retrieval returns empty context with delivery == "canceled"; the SDK does not cancel a provider call or raise your application’s exception.

Trace capture

capture_trace(trace, final: false, terminal: nil) returns a DeliveryTicket without waiting for network delivery. Use full original snapshots, excluding Mirrors-added context. Canonical hashes use string keys with the JSON field names: "conversationId", "conversationRevision", "entryPoint", and "callId". Do not convert keys to symbols or snake_case. Only builtin JSON values are accepted; custom objects, cycles, and malformed or oversized data are rejected without coercion or truncation. Accepted input is copied. After all model calls, tools, and response streaming end, capture the final history with final: true and terminal: "completed", "failed", or "canceled". Each new user turn needs a fresh execution ID. See trace capture for message structure and conversation IDs. Receipt statuses are pending, accepted, dropped, and unconfirmed. When ingestion is present, receipt.ingestion["status"] == "queued" means analysis was queued, not completed. unsupported_history means no analysis job was queued. An unconfirmed request may already have committed. Final delivery can retry once within its original deadline using identical request bytes and identity. Ticket waits accept 0–30 seconds; other SDK timeout arguments use milliseconds.

System prompt

Optionally include the application’s original system prompt on final capture:
The object requires exactly one string field. An empty string explicitly means no prompt; omission means unknown. The prompt permits at most 100,000 UTF-16 code units, and the complete object permits 262,144 UTF-8 JSON bytes within the snapshot limit. Capture the prompt before appending Mirrors context. Intermediate captures and retrieval may also include this object. Include it again on final capture to retain it; earlier values are never inherited. Preserve original system messages without adding duplicates. Upgrading from 0.1.0 requires removing agentContext.skills; 0.2.0 rejects it with or without a prompt.

Optional user and turn timing

  • "user": { "id" => opaque_internal_id, "segment" => cohort }. Use an internal ID, not an email; segment is optional. Trimmed limits are 1–256 UTF-16 code units for the ID and 1–64 for the segment, without control characters. The final value is retained.
  • "turnLatencyMs": whole-turn duration on final captures only. Start turn = mirrors.start_turn when the message is accepted, before retrieval. Call turn.finish after models, tools, retries, and streaming finish; its first result freezes elapsed milliseconds. Omit unknown duration.
Never send turnLatencyMs in a non-final capture or get_context call. Conversation identity requires both conversationId and conversationRevision; allocate and persist each new execution’s revision atomically, and keep the pair fixed through that execution. See the conversation identity rules.

Lifecycle

FlushResult has accepted, dropped, unconfirmed, and pending counts. complete? (also complete) is true only when all covered tickets were accepted, or none were pending at entry. Already-settled tickets and later captures are excluded. Retain individual receipts when their outcomes matter. At shutdown, stop admitting turns and finish active work before calling close. The client owns bounded background worker threads, which do not keep a finished Ruby process alive. Capture queues are in memory and cannot survive a crash. Use fresh execution IDs after finalization, release, restart, or re-enabling.

Limits

Use HTTPS except for loopback development addresses. Redirects are refused. Bounded queues and deadlines limit optional work; they do not provide durable delivery or hard real-time scheduling guarantees.