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 aMirrorsSDK::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: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;segmentis 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. Startturn = mirrors.start_turnwhen the message is accepted, before retrieval. Callturn.finishafter models, tools, retries, and streaming finish; its first result freezes elapsed milliseconds. Omit unknown duration.
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.