OneRingAI examples

This directory contains runnable TypeScript programs covering agents, tools, streaming, media, connectors, OAuth, search, and MCP. Most examples import the repository source directly; the context-freshness example imports the built package and requires npm run build. Run examples from the repository root after installing dependencies.

Starting with v2: use the five-harness examples, the AMOS runtime cookbook, and the v2 capability map to choose an entry point. The package migration guide covers v1 users.

Most AI and search examples make real, billable API calls. Review the prompt, model, and enabled tools before running them with production credentials.

Setup

npm install
cp .env.example .env
npm run examples:check

Use Node.js 22.13+ or 24+. Add only the credentials needed by the program you want to run, then use its command below. npm run examples:check type-checks every example without making network calls.

Environment variables

Agent Runtime

The Agent Runtime example executes either a native OneRingAI agent or an OpenAI Codex SDK agent through the same specification/session/run workflow. It demonstrates model and reasoning selection, observable autonomous execution, explicit local policy, capability-aware behavior, and teardown. Start with the detailed guide and use the design document for architecture and server plans.

For the separately opt-in, local Codex subscription test suite and the small direct OpenAI API sample, see the live validation record. Its test-only login bootstrap does not change authentication in the examples or AMOS.

Purpose-specific models and shared budgets (Stage 06)

Both programs use public package exports and require npm run build. Their default mode is deterministic and offline; mock answers/usage establish plumbing, not model quality or savings. See the recipe.

npm run test:models:live explicitly makes billable OpenAI/Anthropic/Google calls using all three .env keys. It checks helper/main run and stream, cross-provider explicit rollover and controlled structured repair, plus thinking-enabled Google run/stream accounting and an Anthropic fixed-budget extended-thinking helper (14 live cases, including three controlled evidence-preserving helper repairs). These are functional marker checks, not a quality benchmark. AMOS command examples are in its helper guide.

Text, agents, tools, and infrastructure

The interactive chat can execute JavaScript and read user-selected local images. Its tool calls require approval. The focused Google tool tests below deliberately use autoApproveAll to remain non-interactive; keep that setting confined to trusted demo tools.

Streaming, vision, audio, and provider checks

Search, connectors, and OAuth

MCP

The stdio examples launch demo-server.ts, which exposes only synthetic in-memory files, a resource, and a prompt. They do not grant a child process access to the repository filesystem.

Troubleshooting

• A missing variable causes most examples to fail early with the exact variable name. Add it to .env and rerun.
• A provider can retire a model or reject an expired credential independently of the library. The comparison and focused provider checks identify which provider failed.
• oauth-demo.ts binds an ephemeral loopback port. Run it in an environment that permits local listeners.
• mcp/http-client.ts needs a separately running Streamable HTTP MCP server; the repository only supplies the stdio demo server.
• Delete the three generated MP3 files when you no longer need the audio demo output.

Context freshness (Stage 01)

The context example retrieves native evidence connected to a spilled message result. npm run example:structured-budget runs structured-output-budget.ts after the build, using an injected offline provider: the fitting repair makes two calls and returns { "value": "Done" }; the oversized repair raises CONTEXT_OVERFLOW before a second call. It preserves the main prepared revision and cleans up its agents/connectors. No keys, network, or external services are needed.

After npm run build, run npm run example:context-freshness for the offline compaction demonstration. It shows a refreshed working-memory index, retained pending tool dependencies, and the final estimated budget. It also contrasts a keyless notes lookup (index metadata only) with a keyed lookup that recovers the original source contents. npm run example:amos-context renders the real AMOS budget/breakdown commands without credentials. See context preparation for contracts, failure behavior, and the opt-in billable npm run test:context:live suite.

Tool outcomes and cancellation (Stage 02)

C1's outcome-aware-tools.ts uses the public createOutcomeTool() helper. Build, then run npm run example:outcome-aware-tools; expect the same frozen raw payload with declined_lookup succeeded and unavailable_lookup failed. No keys, network or external effects are required; the manager is destroyed in finally. npm run example:amos-outcome-tools renders these actual outcomes through AMOS. The separately opt-in, billable npm run test:outcome-tools:live uses OpenAI/Anthropic/Google .env keys for run/stream with synthetic local tools. See the recipe.

After npm run build, run npm run example:tool-outcomes for tool-outcomes-and-cancellation.ts. No keys are required. It demonstrates preserved domain/failure payloads, cooperative and noncooperative deadlines, a correctly correlated late success, and host cancellation during a loopback HTTP body read. The server binds an ephemeral localhost port; there are no external service calls or writes. Managers, connector, and server are cleaned up. Expect unknown completion at the timeout and a separate late diagnostic.

npm run example:amos-tool-outcomes renders these real local outcomes through AMOS, including an explicit warning that a timed-out operation may still finish. npm run test:tools:live is a separate, billable opt-in check using .env OpenAI, Anthropic, and Google credentials with local tools. Missing or rejected credentials fail the selected provider check. See the guide and corrective validation record.

Stage 02's tool-outcomes-and-cancellation.ts also demonstrates invocation selection: an admitted call retains its original implementation during a plugin wait, and the next call uses the replacement registration. Run after building; setup requires no keys. The example destroys its manager and closes its local HTTP server.

With ANTHROPIC_API_KEY in .env, opt in to npm run example:tool-outcomes -- --live-anthropic. After the offline demonstrations, it makes billable Anthropic calls in both run() and stream() modes using a named connector and in-place before:llm options. Expect domain_probe=succeeded followed by failure_probe=failed in each mode, with both original markers recovered. Agents and the example-owned connector are cleaned up. The library narrows explicit Anthropic named-tool requests and rejects mismatched provider calls before local execution; see the selection contract.

Durable evidence (Stage 03, development branch)

Build the library first. These examples need no credentials or network and clean all temporary resources:

• npm run example:durable-evidence — durable-tool-evidence.ts projects a 92 KB synthetic result, preserves status/IDs, evicts scratch, rolls over history, restores a saved context, and verifies exact recovery in a separate Node process. Output labels ordinary-restart acknowledgement explicitly.
• npm run example:ambiguous-evidence — ambiguous-action-evidence.ts simulates one write whose response never arrives. Cancellation records unknown completion without repeating the action; storage is explicitly process-local.
• npm run example:evidence-recovery — evidence-recovery.ts retains a successful local action's observation during a storage outage, rejects receipt-only acknowledgement, repairs storage, and permits rollover after exact result recovery. Pending delivery-only results survive file session save/load; the optional outcome is omitted deliberately. The action executes once; a custom backend uses an explicit serialization budget and requires no new adapter methods.
• npm run example:evidence-interruption — evidence-stream-interruption.ts closes a synthetic stream at tool completion, saves the unstored observation, rejects receipt-only admission, then restores a checkpoint after acknowledgement and recovers exact data. One tool action and one synthetic model call; no keys or network. Temporary session files are cleaned; evidence is process-local.
• npm run example:amos-evidence — exercises the real AMOS runner and /context evidence command with a synthetic provider. Lists metadata and explicitly previews at most 1024 characters, showing the next offset.

npm run test:evidence:live is separately opt-in and billable, using .env OpenAI/Anthropic/Google credentials with local synthetic tools. It verifies managed run/stream source retrieval and raw fallback after a controlled storage failure. Read setup, bounds, failure recovery and durability.

Context strategies (Stage 07)

After building, run npm run example:context-strategies or add -- --held-out for the six retained synthetic regression variants sharing one lookup scaffold. The CLI also demonstrates three fitting critical preparations with a full evidence store, unchanged history and zero source writes/helper calls under each new policy. Algorithmic, masking and summaries use the same local read-only environment; a common bounded reader retrieves source fields by evidence ID or exact working-memory key. Offline providers and usage are scripted. Expected: exact answer/account/status, no repeated action, all completion predicates pass. Owned agents/connectors are destroyed and evidence is process-local.

npm run example:context-strategies -- --live --held-out loads .env and makes billable OpenAI gpt-4o main / gpt-4o-mini helper calls, two repetitions per task and strategy in seeded shuffled order. Set CONTEXT_STRATEGY_REPORT_PATH to save actual usage, helper/repair attempts, returned models, source reads, failures and latency. No external writes. This is a bounded functional pilot, not statistical proof of non-inferiority or general cost reduction. Both new strategies remain experimental and opt-in; algorithmic stays the default.

npm run example:amos-context-strategies uses the actual AMOS runner/command with synthetic responses, a local file evidence store and temporary persisted settings. It demonstrates real masking, diagnostics and policy switching without recreating the agent or repeating its original read. Actual ConfigManager also demonstrates failed selection restoring an absent setting through a later unrelated save/reload. Selection and rollback make no model call; files, agent and connector are cleaned up. No keys/network are required. Read the complete recipe for setup and support boundaries.

Protected task-state workflow

After npm run build, run npm run example:task-state (task-state-workflow.ts). No keys or network are needed. It keeps a host correction and unconfirmed proposal distinct, records one simulated accepted action, suspends through rollover/checkpoint/restart, verifies recovery in a separate Node process, then records host-confirmed remote completion. Expected: one submission, corrected 40 EUR constraint, preserved pending state, and no LLM calls. Temporary session/evidence files are removed.

npm run example:amos-task-state uses the actual AMOS runner and /context task commands with one synthetic provider call. It demonstrates validated edits, stale revision rejection, session reload and model command text remaining data. npm run test:task-state:live explicitly makes billable OpenAI/Anthropic/Google synthetic run/stream/restart and extractor calls using .env. Read Task State for host authority, capacities and limitations.

The Stage 04 corrective walkthrough also reclaims old notes, reuses a pruned ID and checks a second file checkpoint without another submission. The actual AMOS walkthrough fills 100 task records, displays an actionable capacity error, uses resolve-prune, adds a constraint and verifies checkpoint recovery with one total synthetic provider call. The live task-state probes additionally validate ID reuse and explicit atomic host recovery after their model response, without additional model/action calls. No real remote completion or fresh quality benchmark is claimed.

The second corrective pass preserves legacy resolved-feature and external-plugin configuration types. After building, npm run test:agentic:compat compiles pinned legacy consumers through the root and /types exports without spreading current defaults. Both task-state walkthroughs remain applicable and pass unchanged.

Bounded recovery and completion (Stage 10)

Build the library first. These examples are offline and require no .env keys:

All examples destroy agents/connectors; the AMOS example removes its temporary session directory. examples/agent-loop/scripted-provider.ts is a deterministic model simulation that throws if its script is exhausted, not a production provider. Hard ModelTask bounds use its explicit single-attempt host attestation. npm run test:loop:live explicitly opts into real billable OpenAI, Anthropic and Google run/stream recovery/blocked and stopped-history/formatting checks using .env. Tools are synthetic reads; there are no real external writes. Read Loop Policies for defaults, uncertainty, persistence and intentional run/stream differences.

The offline purpose-specific-models.ts example now starts with a shape-valid empty answer and uses optional validationSchema to require content. Its one existing repair retains the exact source marker and shares task accounting. The structured-compaction live gate additionally injects the recorded empty Google summary after a real call, then requires a real Google repair, source retrieval and exact final constraints without masking fallback. All fault injection is labeled in the report and uses synthetic source data.

Stage 12: opt-in presets and capability inspection

Build first, then npm run example:agentic-presets runs agentic-presets.ts without keys/network: plain Agent, research/workflow compositions, explicit host evidence scope, workflow completion override, resolved settings and unavailable-feature diagnostics. It verifies call counts, accepts getter-backed host scopes, demonstrates a rejected shared resume retaining blocked-tool authority/checkpoint A and JSON-converting plugin recovery, and destroys all agents/contexts and temporary files. npm run example:amos-presets runs the AMOS selection/persistence/inspection walkthrough, verifies rejected-load checkpoint protection and removes temporary files. npm run test:presets:live is a separate billable OpenAI/Anthropic/Google gate using .env; it also verifies original-history continuation after the three session recovery paths on every provider. No external writes. See the recipe.

The Stage 12 AMOS preset walkthrough also demonstrates candidate-first handoff, failed-candidate preservation, and title retention across named/unnamed saves. The actual app/session command and timer-backed autosave paths are covered by latest corrective validation.

Stage 05: selective context and cache-aware layout

Build first. npm run example:context-selection compares an overflowing legacy whiteboard/source view with budgeted selection, retaining the exact stored entries and printing selection reasons, exact omitted-source recovery and stale-account admission rejection. npm run example:context-dispatch-safety demonstrates one bounded refresh for hook-edited input, rejection of superseded-prompt JSON repair and last-request wrap-up accounting using local scripted providers. It also formats before a real default algorithmic spill and persists one coherent structured suspension without repeating its local action. Its checkpoint is process-local and its temporary correlation file is removed during cleanup; no restart durability is implied. Expected output includes formattingBeforeSpill and structuredSuspension. npm run example:cache-aware-context demonstrates stable instruction prefixes with late dynamic data and unknown provider counters. npm run example:amos-context-selection executes the real AMOS runner and breakdown, including a forced local read/wrap-up, then destroys its Agent and removes temporary files. All four default to offline and label synthetic usage explicitly.

npm run test:context-assembly:live explicitly bills OpenAI/Anthropic/Google calls using .env, checks run/stream in both layouts with local reads, and reports actual cache usage without requiring hits. It also checks final hook edits, ordinary/stale JSON repair and actual per-request wrap-up accounting. STAGE05_PROVIDER=openai|anthropic|google npm run example:cache-aware-context -- --live runs a separate two-call provider observation. No service writes or general cache/cost/quality claim. See setup and boundaries.

Plugin/native compaction (Stage 16A)

Build first; all five default programs are offline protocol fixtures, with cleanup of owned agents/connectors/tasks and temporary files. They do not measure LLM quality.

Selected live native models are gpt-6-astra and claude-sonnet-4-6. Native callability does not guarantee reduction. Sources stay scoped; never repeat a write to repair context. See the native recipe for limits and actual adoption guidance.

Managed model routing (Stage 14A)

Build first. These default programs are offline, require no credentials, assert their functional contracts and clean up owned agents/connectors/tasks/temp files.

npm run example:model-routing -- --live=openai (or anthropic/google) loads .env, requires that provider key and makes at most eight generation attempts within 120 seconds. npm run test:model-routing:live bills the complete routing contract suite and small fixed quality/cost pilot across all three providers. Synthetic usage makes no quality/cost claim; the real pilot is not a general benchmark. See the recipe for setup, model fixtures, limits, native ownership, failure semantics and validation evidence.

The Google pilot explicitly disables thinking on supported Gemini 2.5 Flash GenerateContent models. The converter now sends the required zero budget; the original exact-answer and minimum savings checks are unchanged. This is a measured fixture comparison rather than a promise that every routed workload costs less.

Explicit shared accounting (C2)

After npm run build, run npm run example:composite-binding. This deterministic offline recipe makes three synthetic managed/direct/helper calls on one ModelTask, prints purposes and total usage, and cleans up all resources. No keys are needed. Managed cancellation uses the task; direct/helper APIs also take explicit signals. The verified routine facade and AMOS operation controls are delivered in C3.

Verified routines (C3)

After npm run build, run npm run example:routine-stores for an offline demonstration of actual unified store calls, map output and fold accumulation. Expected result: [2,3] becomes [4,6], then 10, with six deterministic model calls and complete agent/connector cleanup. No keys, network or live LLM are used. See the example and the routine guide.

After npm run build, run npm run example:verified-routines (offline, no credentials). It submits one synthetic action, waits for a host check, resumes the same cursor and verifies an artifact created by a post-step. All agents/tasks/connectors are cleaned up. See the recipe for source archival and live test opt-in.

Enhanced connectors (C4)

Build, then run npm run example:enhanced-connectors. It uses temporary local HTTP servers and an evidence directory, with zero LLM calls/external writes. Expected: two safe-read attempts, complete allowed source recovered after rollover, one synthetic mutation despite HTTP 503, no legacy aliases, same-origin redirects followed and cross-origin redirects blocked before credentials leave the configured origin. It cleans up all resources. See the connector recipe for explicitly opt-in live validation.

Connector collection pages (C5)

Build, then run npm run example:connector-pages. No credentials are needed. A local server over-returns, includes an empty intermediate page and ends with a partial page: expected 49 exact IDs across 14 logical pages/HTTP requests and zero LLM calls. The example verifies the stable ID hash, source recovery from a reopened FileEvidenceStorage, catalog reload/context rollover, rejection by a fresh manager, and cleanup. See the page recipe; opt-in live tests use real models and synthetic local provider pages only.

Complete factory orchestration

After building, npm run example:orchestrator-factory runs orchestrator-factory.ts offline. It asserts actual distinct root/worker requests, shared operation accounting across delegation/monitoring and cleanup; expected output includes passed: true and two shared-operation calls plus an independent root configuration probe. No keys or external writes. See the recipe for real connector setup and retained-source recovery.

• Remote tool outcomes: npm run example:remote-outcomes. Offline authenticated transport; exact chunked sources, business declines, uncertain synthetic write and receipt recovery with one submission. Concurrent receipt polls reuse the same acknowledged record without consuming more quota. No keys or network needed. Opt-in real-provider checks: npm run test:remote-outcomes:live.

• Composed meeting preparation: npm run example:composition-evaluation runs six offline local/remote cases, host verification, exact source hashing and temporary artifact cleanup.

• npm run example:amos-composition exercises actual AMOS routine inspection and same-process confirmation with a synthetic provider and no credentials.

• Endpoint capabilities: npm run example:endpoint-capabilities. Offline root/shared metadata, documented constraints and explicit unknowns.

• Parameter policy: npm run example:parameter-policy. Actual mocked Responses bodies, omission versus supported zero, raw strictness, bounded decisions and saved configuration preserved. No network or keys.

• Vendor presentation: npm run example:vendor-presentation. Immutable browser-safe catalog, host label override, explicit unknown fallback and identity/presentation separation. No network or keys.

Agent runtime harness examples

Build the public package first. These examples import only documented public exports and subpaths. The defaults are offline: synthetic model/CLI/HTTP transports, actual adapters/SDK serialization, no provider account. Install both optional local SDK peers for the five-harness examples. MCP examples need an authenticated loopback socket.

The existing agent-runtime-local.ts oneringai|codex commands preserve explicitly selected real/billable behavior and are excluded from offline runs. The Claude and managed examples' --live path additionally requires ONERINGAI_ALLOW_LIVE=1 and the vendor API key (optional trusted Anthropic workspace). These gates are prepared but unrun: live LLM/native agent testing remains paused. Managed example failure retains its recovery reference/private control directory; keep these for repair rather than submitting the task again. No subscription credentials are read. See the canonical guide and delivery ledger.

For an interactive application, the AMOS cookbook uses runtime-host.ts. It selects any of five actual adapters using AMOS_RUNTIME_DRIVER, defaults to offline transports, saves the current locator atomically, and isolates control/workspace/transfers. Real provider mode requires both explicit live gates and named Connector credentials; it remains unrun under the live-testing pause. The cookbook covers every command, per-run endpoint restrictions, file setup, failed recovery/persistence and owned cleanup. Mock managed service state does not survive a CLI restart; use the dedicated independent mock-service restart example for that scenario. Prior local SDK history requires a trusted native checkpoint verifier, which the sample does not replace with a no-op.