oneringai AGENTS.md

OneRingAI Agent Guide

This is the canonical, vendor-neutral guide for coding agents that use or modify @everworker/oneringai. It is written for OpenAI Codex, Claude Code, custom coding agents, and humans delegating integration work to them.

Read this file before generating OneRingAI code. For exhaustive detail, follow the documentation links near the end instead of guessing an API.

Fast facts

• Package: @everworker/oneringai
• Runtime: Node.js 22.13+ or 24+
• Language: strict TypeScript
• Package format: ESM with ESM and CJS build outputs
• Public API: import from @everworker/oneringai unless a documented subpath is explicitly required
• Architecture: connector-first, plugin-first context, one shared tool manager

Determine your operating mode

Using OneRingAI as a dependency

• Import only from the package's public exports.
• Do not import src/**, dist/**, or undocumented implementation paths.
• Read the installed package's README.md, AGENTS.md, USER_GUIDE.md, and API_REFERENCE.md when they are available under node_modules/@everworker/oneringai/.
• Prefer runnable patterns from examples/ in the repository over invented method names or provider-specific SDK calls.

Modifying the OneRingAI repository

• Preserve the connector-first and plugin-first invariants below.
• Relative TypeScript imports include the .js extension.
• Use export type { X } for types and export { X } for runtime values.
• Use errors from src/domain/errors/AIErrors.ts where applicable.
• Do not hand-edit generated registries. Run the relevant generator.
• Keep changes focused and validate them with the commands at the end.

The mental model

Application
  -> named Connector (credentials + service identity)
  -> Agent (model + instructions + tools + context)
  -> provider implementation

AgentContextNextGen
  -> context plugins (state, memory, catalog, workspace)
  -> one ToolManager shared by agent and context
  -> compaction and persistence