Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx agentmods add agents/ambient-code/platform/runner.specgit clone --depth 1 https://github.com/ambient-code/platformWhat it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5 | $0.00000 | $0.05589 |
| Opus 5 | $0.00000 | $0.02795 |
| Sonnet 5 | $0.00000 | $0.01118 |
| Haiku 4.5 | $0.00000 | $0.00559 |
Grade A, and why
runner.spec scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 505 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Ambient Runner Spec
Date: 2026-04-05
Status: Living Document — current state documented
Related: ../control-plane/control-plane.spec.md — CP provisioning, token endpoint, start context assembly
Overview
The Ambient Runner is a Python FastAPI application that runs inside each session pod. It is the execution engine for one session: it owns the Claude Code subprocess lifecycle, bridges between the AG-UI HTTP protocol and the gRPC message store, streams results in real time, and exposes a local SSE tap for live event observation.
One runner pod runs per session. The pod is ephemeral — created by the CP when a session starts, deleted when the session ends.
CP creates runner pod
│ env vars (SESSION_ID, INITIAL_PROMPT, AMBIENT_GRPC_URL, ...)
▼
Runner Pod (FastAPI + uvicorn)
│
├── gRPC listener ←── WatchSessionMessages (api-server)
│ │
│ └──► bridge.run() ──► Claude Code subprocess
│ │
│ ├──► PushSessionMessage (api-server) ← durable record
│ └──► _active_streams[thread_id] queue ← SSE tap
│
└── HTTP endpoints
├── GET /events/{thread_id} ← live SSE tap (drained by backend proxy)
├── POST / ← AG-UI run (HTTP path, backup)
├── POST /interrupt
└── GET /health
What the Runner Is
The runner is a bridge. It translates between three different message-passing systems:
| System | Protocol | Direction | Purpose |
|---|---|---|---|
| api-server gRPC | WatchSessionMessages |
inbound | User messages that trigger Claude turns |
| Claude Agent SDK | subprocess stdin/stdout | bidirectional | Drives Claude Code execution |
| api-server gRPC | PushSessionMessage |
outbound | Durable conversation record (assistant turns) |
| SSE tap | GET /events/{thread_id} |
outbound | Live event stream for the frontend and CLI |
The runner has no database. All persistent state (session messages, session phase) lives in the api-server.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- yesterday First seen · 505 lines · 0 tokens per session scan A 9475d9742c18
runner.spec is an agent published in the GitHub repository ambient-code/platform (129 stars, last pushed 2d ago), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 5,589 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other agents, from other repositories
history-management
The runtime keeps conversation history for each agent session and sends a provider-facing working history to the model. Two complementary limits operate on different representations.
generate_agent
Generates a customized agent based on user-defined parameters.
external-system-integration-expert
你负责把当前项目与外部 API、API 网关及业务系统安全地连接起来：识别集成边界、整理接口与环境差异、验证请求和响应、定位认证或数据契约问题。.
ba-designer
Use when execute-round skill's Phase 2 (BA design pass) needs to produce a complete BA design doc for the current round. Generates D-1..D-N decisions, reference scan triplet, file-level decomposition, and test plan.
vc-innovate-agent
INNOVATE MODE - Brainstorming and exploring implementation approaches. Discusses possibilities without making decisions. Use after research is complete.
design-reviewer
Design lead + expert design critic. Two modes: Mode A — authors the project's root DESIGN.md (design identity) at project start. Mode B — reviews built UI against DESIGN.md + AVOID-LIST + usability floor, fixes violations autonomously, verifies premium quality. Delegate when: a UI project has no DESIGN.md yet, UI…