9router Living-Agent Framework

9router is an experimental, TypeScript-first framework for building arbitrary living-agent systems. It provides typed agent definitions, stable logical identity, private state, concurrent Runs, child agents, plugins, traces, a fast local runtime, a local chat and trace flight deck, and an Elixir/OTP semantic kernel.

The framework does not force a support-agent workflow or require an LLM. Developers can build assistants, coordinators, simulations, automations, games, background systems, or new patterns that do not fit those labels.

Status

This repository is a working prototype, not a production runtime or managed cloud service.

Implemented today:

• 9router for the concise single-package agent, local runtime, and flight deck API.
• @9router/protocol for addresses, messages, envelopes, Runs, traces, state snapshots, and capability manifests.
• @9router/agents for typed definitions, lifecycle hooks, state handles, messaging, child agents, timers, signals, tracing, and plugins.
• @9router/tracing for redacted trace storage, chronological and tree projections, summaries, NDJSON, and a serialized capability registry.
• @9router/runtime-local for in-process development, concurrent waiting Runs, lifecycle behavior, mailbox policies, child lifetimes, plugins, and inspection.
• @9router/dev-server for a loopback local UI with chat, state, Runs, and trajectory views.
• @9router/cli for project scaffolding, project checks, template discovery, and trace inspection.
• runtime/beam for the dependency-free Elixir/OTP semantic kernel prototype.
• Three validated starter templates, three focused examples, and one complete launch-room sample application.
• A searchable VitePress documentation site plus repository guidance and reusable skills for coding agents.

Read docs/LIMITATIONS.md before using the prototype for sensitive or production work.

Create a project

From this repository:

bun install
bun run packages/cli/src/index.ts create ./my-agent --template basic
cd ./my-agent
bun install
bun run check
bun run start
bun run dev

Open http://127.0.0.1:3000 after bun run dev. The generated flight deck talks to the real in-process agent runtime and shows state, Runs, and traces.

The basic scaffold starts with one import and either authoring style:

import { agent } from "9router";

export default agent("greeter", message => `Hello ${message}`);

Every concise agent requires a stable name because its identity survives individual Runs. Use agent({ name, state, handle }) when the agent needs configuration or private state. Use defineAgent(...) for several independently typed message handlers.

Available templates:

• basic for one stateful agent
• coordinator for a parent that creates and asks workers
• world for multiple living instances of one definition

Work on this repository

bun install
bun run check
bun run example:counter
bun run example:coordinator
bun run example:world
bun run sample:launch-room
bun run sample:launch-room:test
bun run comparison:research-approval:test
bun run comparison:research-approval
bun run docs:build

Examples write NDJSON traces in the current directory. Set TRACE_FILE to choose another path.

TRACE_FILE=counter.ndjson bun run example:counter
bun run trace counter.ndjson tree

Start reading

• Documentation site source
• Getting started
• Launch room sample
• Coding-agent guide
• Concepts
• TypeScript API
• Local runtime
• Local developer server
• BEAM runtime
• Plugins
• Tracing
• CLI
• Testing
• 9router vs Mastra
• Limitations

Repository map

• packages/protocol: shared identifiers, envelopes, Runs, traces, and capability schemas
• packages/sdk: the concise 9router package entry point
• packages/core: the @9router/agents authoring API
• packages/tracing: trace ledger and capability registry
• packages/runtime-local: in-memory local runtime
• packages/dev-server: typed local HTTP adapter and flight deck server
• packages/cli: scaffolding, checks, template listing, and trace inspection
• apps/dev-ui: React/Vite local flight deck adapted from the MIT-licensed DeepSeek Harness frontend
• runtime/beam: Elixir/OTP semantic runtime
• examples: focused repository demos
• examples/launch-room: complete multi-agent sample with tests and a local flight deck
• comparisons/research-approval: the same deterministic approval agent implemented and tested in 9router and Mastra
• .agents/skills: reusable application-building, framework-extension, and verification skills
• docs: VitePress website content and theme
• templates: generated starter projects
• docs/research: design research and primary-source notes

Design rules

• Logical agent identity is separate from its current runtime process.
• A Run is one execution, not the whole agent.
• A waiting Run does not have to block unrelated work. Use parallel or keyed concurrency when that behavior is required.
• State belongs to the addressed agent instance. Agents share data only through explicit messages, tools, or developer-defined capabilities.
• Features are replaceable capabilities, not hardcoded product assumptions.
• Current behavior is documented as current behavior. Future managed-platform plans are labeled as future work.

Contributing

See CONTRIBUTING.md, SECURITY.md, and docs/TESTING.md. All code files must carry a short purpose header and an Updated: YYYY-MM-DD line, except formats that cannot contain comments.