oneringai v2

Build agents around your application, and choose who runs them.

OneRingAI is a TypeScript library for agents, authenticated tools, long-term memory, and multimodal AI. Use its own agent loop with multiple model providers, or bind one agent definition to a supported OpenAI or Anthropic harness. Named connectors keep credentials and account access in your application.

Start here: User Guide · Examples · API Reference · AMOS cookbook

AMOS is the complete terminal application: configure connectors, run agents, switch harnesses, inspect activity, and recover saved sessions. Its application guide also covers native OneRingAI mode.

Published v2 beta: oneringai@2.0.0-beta.1, without a scope. Both latest and next currently select this beta. Use the matching package version and retain the preview boundaries below. Existing v1 users must migrate explicitly from @everworker/oneringai. See the v2 changelog, migration, and release readiness.

What changes in v2

Version 2 adds control over long tasks, source retention, model spending, and complete agent harnesses. It builds on the connectors, memory system, tools, context plugins, and media APIs already available in v1.

New policies and features are opt-in unless their guide describes a compatibility fix. Ordinary Agent.create() defaults and existing session contracts remain supported. Native Agent controls do not automatically apply inside external vendor harnesses. The v2 adoption guide records exact availability, limitations, validation, and deferred work.

Quick start

Node.js 22.13+ or 24+ is required. The package provides ESM, CommonJS, and TypeScript declarations. Install the current v2 beta:

npm install oneringai

You can also select npm install oneringai@next or pin oneringai@2.0.0-beta.1. The source checkout/local package workflow remains available for development. Load your own environment configuration before creating connectors; the library does not automatically load your application's .env file.

import { Agent, Connector, Vendor } from 'oneringai';

Connector.create({
  name: 'openai-main',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

const agent = Agent.create({
  connector: 'openai-main',
  model: 'gpt-5.6-terra',
  instructions: 'Be accurate, concise, and explicit about uncertainty.',
});

try {
  const response = await agent.run('Explain connector-first architecture.');
  console.log(response.output_text);
} finally {
  agent.destroy();
}

Register an Anthropic, Google, xAI, or other supported connector and change the agent's connector/model to use another provider. Your task code and tools stay the same; model capabilities and provider-specific request boundaries still apply.

The User Guide explains setup and response shapes; the examples guide gives exact commands, credentials, expected behavior, side effects, and cleanup.

Connectors: one authentication system

Connectors are named credential and service identities. Multiple API keys, accounts, and vendors can coexist. AI connectors declare an explicit Vendor; external-service connectors use serviceType and endpoint configuration.

import { Agent, Connector, Services } from 'oneringai';

// Reuses the AI connector from the quick start.
Connector.create({
  name: 'github-work',
  serviceType: Services.Github,
  auth: { type: 'api_key', apiKey: process.env.GITHUB_TOKEN! },
  baseURL: 'https://api.github.com',
});

const assistant = Agent.create({
  connector: 'openai-main',
  model: 'gpt-5.6-terra',
  identities: [{ connector: 'github-work' }],
  permissions: {
    onApprovalRequired: async request => ({
      approved: request.toolName === 'github-work_api' && request.args.method === 'GET',
    }),
  },
});

try {
  await assistant.run('List open issues in owner/repository.');
} finally {
  assistant.destroy();
}

There are 50 authentication templates, plus a generic authenticated API tool for configured connectors with a baseURL. Specialized packs cover GitHub, Slack, Microsoft Graph, Google Workspace, Telegram, Twilio, Zoom, search, scraping, and AI media. Not every template has a specialized pack. Use ConnectorTools.for(name) when composing tool lists explicitly.

OAuth supports per-user/account tokens, refresh, encrypted storage, and multiple flows. Connector.fetch() provides direct authenticated requests with configurable timeouts, retry, circuit breakers, and diagnostics. Scoped registries and identity filters compose with host authorization; setting userId alone does not establish tenant isolation or grant access.

See the complete connector and tool catalog, authentication guide, OAuth guide, and scoped registries.

Memory: knowledge beyond conversation history

The standalone MemorySystem represents knowledge as entities and provenance-aware facts. Use it directly in an application, connect it to agents, or feed it through a signal-ingestion pipeline.

Enable context.features.memory for profile injection and six read tools. Add memoryWrite for six write tools, or use background ingestion with a retrieval-only agent. Configure a trusted owner and explicit visibility policy for multi-user applications. The compatibility default permits public reads.

Memory differs from working notes, conversation checkpoints, and execution evidence: each has its own scope, lifecycle, and purpose.

Start with the Memory Guide and agent integration walkthrough. Detailed references cover the API, permissions, predicates, and signals.

Tools and context that compose

An Agent and its AgentContextNextGen share one ToolManager: agent.tools === agent.context.tools. Tools can come from application functions, generated built-ins, context plugins, connectors, or MCP servers. Register, enable, disable, and organize them through the same manager.

Context plugins own their instructions, prompt data, tools, compaction, and saved state. Disabled features contribute no tools or prompt content.

The tool pipeline supports permission policies, user rules, execution plugins, timeouts, circuit breakers, cancellation, outcomes, and observation. Shell, desktop, generated-code, and remote tools require deliberate host policies. Serializing tool state does not serialize executable functions or authorization.

See tools, permissions, context, MCP, and session persistence.

One definition, multiple agent harnesses

AgentRuntime separates a logical definition from its execution binding. The harness is explicit; a model name never selects it.

The following assumes the named OpenAI connector from the quick start and the optional peer npm install @openai/codex-sdk:

import { AgentRuntime, LocalExecutionBackend } from 'oneringai/agent-runtime';
import { CodexSdkDriver } from 'oneringai/agent-runtime/codex';

const runtime = new AgentRuntime({
  backend: new LocalExecutionBackend({ drivers: [new CodexSdkDriver()] }),
});
const assistant = runtime.createAgent({
  id: 'project-assistant',
  instructions: 'Inspect the project and explain your findings.',
});

try {
  const options = {
    execution: {
      driver: 'openai.codex.sdk', connector: 'openai-main', model: 'gpt-6.1-sol',
    },
    context: { userId: 'authenticated-owner' },
    environment: { type: 'local-directory' as const, path: process.cwd() },
    policy: {
      filesystem: 'read-only' as const, commands: 'sandboxed' as const,
      sandboxNetwork: 'denied' as const, providerWebSearch: 'denied' as const,
      approvals: 'deny' as const,
    },
  };
  console.log(await assistant.inspect(options));
  const session = await assistant.openSession(options);
  const run = await session.run('Explain this project.', { requestId: 'overview-1' });
  for await (const event of run.events()) console.log(event.type);
  console.log((await run.result).outputText);
} finally {
  await runtime.destroy();
}

Register another driver and bind the same definition with its connector, model, policy, and supported environment. For selected application tools, supply a host-owned resolver; see the five-harness example. Capabilities reject unsupported requirements before execution. Managed recovery uses scoped references and original request IDs rather than replaying uncertain input. File transfer is a separate host-authorized operation.

Runtime status: preview. All five adapters have deterministic offline coverage. A bounded Codex subscription test and small OpenAI model-call sample are recorded in live validation. Production API-key Codex, Claude SDK, and both managed agent APIs still need their live/platform gates. Production drivers require named API-key connectors; the subscription test used an explicit test-only bootstrap and adds no public subscription-login feature.

Follow the runtime guide and AMOS runtime cookbook for controls, authentication, continuation, files, cancellation, durability, and cleanup. App Server interactivity, distributed isolation, and A2A remain deferred.

Models, media, and provider APIs

Text adapters support OpenAI, Anthropic, Google Gemini, Google Vertex AI, xAI, DeepSeek, Groq, Together, Mistral, Perplexity, Ollama, and custom compatible deployments. Feature support depends on the actual model, endpoint, and adapter. Use registries and capability inspection instead of a provider-wide checkbox.

Provider-hosted tools have separate execution and data-handling boundaries from local ToolFunctions. Media APIs are not available from every text provider. Retired compatibility entries, including OpenAI Sora, remain discoverable as historical metadata and must not be offered as active generation options. Registry cost calculations are estimates; missing pricing or usage remains unknown. Check the registry audit and provider sources linked there for access, lifecycle, and billing details.

Applications and examples

• AMOS — MIT terminal application with connectors, tools, native Agent commands, and an opt-in harness-neutral runtime mode.
• Hosea — MIT Electron application with a reusable monochrome design system and a local design-preview launcher. Its backend integration is preserved and disabled by default. Desktop packaging has separate validation gates.
• Examples index — basic integrations, memory, context strategies, verified workflows, runtime bindings, and recovery.

From a checkout with development dependencies, these demonstrations use synthetic providers and require no API credentials:

npm install
npm run build
npm run example:agentic-baseline
npm run example:context-strategies
npm run example:model-routing
npm run example:agent-runtime-swappable
npm run example:agent-runtime-recovery
npm run example:amos-runtime

The examples index documents live opt-ins separately. They can make billable requests; ordinary offline examples do not establish provider access.

Documentation

Repository documentation links are relative so they follow the checkout's branch. The following two links are the deliberate npm landing-page version navigation exception: legacy v1 documentation and v2 documentation on main. main is the v2 development line; version1 retains legacy maintenance and documentation. Use this checkout's relative links for its matching documentation.

Development

npm run build
npm run typecheck
npm run lint
npm run test:unit
npm run examples:check
npm run test:agentic:compat
npm run docs
npm run docs:check

See Contributing for the development workflow. Use public exports in consumer code; generated registries and API documentation are regenerated from source. Integration/live suites require explicit setup and are separate from the offline release checks.

License

The library, AMOS, and Hosea source are MIT licensed, Copyright © 2025–2026 Anton Antic (anton.antich@gmail.com). See LICENSE and Licensing for scope and third-party terms.

Questions and bug reports: GitHub issues.