agentos: Instructions file for Codex

AGENTS.md

Instructions for coding agents working in this repository. People contributing by hand: see CONTRIBUTING.md.

What this is

@framers/agentos is an open-source TypeScript runtime for AI agents: cognitive memory, optional HEXACO personality, multi-agent orchestration, runtime tool forging and one interface across LLM providers. It is published to npm as an ESM package under Apache-2.0.

Repository map

• src/api/: the high-level API (generateText, streamText, agent(), agency()) and its runtime
• src/core/: LLM providers (src/core/llm/providers/), API-key pools (src/core/providers/), conversation, embeddings, guardrails, rate limiting, storage, streaming, tools, vector stores
• src/cognition/: memory, RAG, emergent behavior, skills, web search
• src/orchestration/: planners, the compiler, workflows, checkpoints, human-in-the-loop
• src/io/: channels, speech, the voice pipeline, vision, avatars
• src/safety/: guardrails, auth, sandbox, provenance, validation
• src/extensions/: extension pack loading
• src/agents/, src/config/, src/logging/, src/utils/
• tests/ and src/**/__tests__/: vitest suites
• docs/: guides; docs/publication-manifest.cjs decides which pages docs.agentos.sh publishes
• examples/: runnable examples (.mjs and .ts)
• scripts/: build and release helpers

Toolchain

CI uses Node 22 and pnpm 10. TypeScript with Bundler module resolution; the package is ESM ("type": "module").

Commands

CI runs the commands below, and its result decides. Run any of them locally to check a change before you push; the parts that run only on GitHub Actions are named where they occur.

CI runs (job "Test & Lint" in .github/workflows/ci.yml), in order:

1. pnpm install
2. node --test scripts/curated-extensions-peer.test.mjs (checks that the lockfile and the install resolve the AgentOS peer of the extensions registry and of every curated extension to this checkout, and that the lockfile resolves every other first-party peer of a curated package inside its range; see Conventions)
3. pnpm run build (cleans dist, compiles, then rewrites path aliases and import specifiers in dist)
4. pnpm run verify:exports (checks that every non-wildcard exports target exists in the build; on GitHub Actions it then installs the packed package into an empty project, where the meeting channel, safety runtime and checked egress entries compile and import with network access refused, and the release's prepublishOnly runs that same candidate check again before publishing; a CI run dispatched by hand on a release tag checks the published package of that version instead, after matching its tarball to the registry's integrity. Run locally, the command checks the exports map alone: the install checks are skipped off GitHub Actions)
5. pnpm run lint
6. pnpm run typecheck
7. pnpm run test:coverage, the whole suite with coverage on, which fails below the thresholds in vitest.config.ts (Postgres-backed tests run only when AGENTOS_TEST_POSTGRES_URL is set; CI provides a Postgres service. The Moonshine browser provider's integration test runs only when AGENTOS_TEST_MOONSHINE_DIR is set, and is skipped with a note naming the file when the folder it names lacks one of the model's files or the clip, or holds one empty; CI fetches them before this step)