Agent Runtime.

This is the L3 operating manual. It is read front-to-back once per quarter and consulted point-by-point during every sprint. It tells the Agent Engineer which model to call, where state lives, how prompts are versioned, how observability lands on the state sheet, and which deployment target to use. It is the first doc to update when the underlying tooling changes — Anthropic ships a new model, a new MCP server enters the inventory, a workflow graduates from Sheets to a real database.

This doc is not a tutorial on Claude or the API — Anthropic’s documentation is the canonical reference for that. This is the Studio’s opinionated slice: how we choose, what we pair things with, and what we refuse to do.

Every Lighthouse Sprint deploys the same shape, regardless of the client’s domain. There are three runtime layers and they never vary: the model layer, the orchestration layer, and the state layer. Clients change; wrapper shapes change; this does not.

Every agent spec declares a default model tier in its front matter. That choice is reviewed at the Redesign gate. Tier is the single largest cost and latency lever in the entire runtime — the wrong default blows the variable-cost line within a week.

Actual numbers depend on prompt length, output length, tool-call fan-out, and Anthropic’s current pricing — check the docs before rebuilding a variable-cost model. The shape of the tradeoff is what matters for spec-write decisions.

MCP is how agents reach the world. A Studio agent almost never calls an external API directly — it calls a Model Context Protocol server that wraps the API with a tool interface, an auth scope, and observable boundaries. This section names the servers we rely on, the rules for when to build a custom one, and where they run.

We default to an official or community-published MCP server whenever one exists and fits. We write a custom server only when the task is load-bearing enough to own or when no public server covers it.

The spreadsheet-as-state-machine pattern (USP-009) is not a nostalgia play. Google Sheets + Apps Script is the Studio’s default workflow substrate because it gets four things right that bespoke databases get wrong on sprint timelines: the client can see the state live, atomic-enough row locking exists, audit history is free, and rollback is a copy-paste.

Apps Script has row-level concurrency gotchas. The Studio’s sheets-state MCP server wraps a lock-row primitive that uses LockService.getDocumentLock() plus a lock_token column. Every agent that claims a row writes its token; every release clears it. Stale tokens older than a timeout are reaped by a janitor trigger.

Graduation is a move to Airtable (hosted, richer API, still visible to humans) or Supabase / Postgres (real DB, structured schemas, SQL, RLS). One of the five §07 pressures from the master must apply. We do not graduate because a spreadsheet “feels unprofessional.”

Prompts are code. We treat them like code — they live in the repo, they version with semver, they have tests, they land through PRs. The Studio’s refusal to let prompts live in a prompt-store SaaS is deliberate: vendor lock-in on the most valuable artifact in an agent system is unacceptable (P-01).

Each versioned file has front matter: model_tier, temperature, max_tokens, tools, created_at, author, changelog. The body is the prompt itself — in Markdown, with sectioned instructions and examples as headings.

The CURRENT.md symlink is what the agent runtime loads. Rolling back is ln -sf v1.1.0.md CURRENT.md and a deploy. This is the cheapest rollback we have.

Every prompt with ≥ 10 production runs has at least five golden cases in evals/<agent>/cases/. A golden case is an input + an expected shape of output (not a string match — a judge-prompt or a structural check). The eval runner replays every golden case against CURRENT.md and reports pass/fail.

Rules: major bumps require all goldens pass. Minor bumps require goldens in the affected section to pass. Patch bumps require no regressions on any golden. Any golden marked load-bearing in its front matter is non-negotiable at every bump.

Observability is P-04 in action: governance is a column, not a tool. Every agent run produces signals that land in one of three places — the state sheet, the cloud logs, and an alert channel. We instrument every agent against this three-target discipline; nothing gets promoted to production without it.

Three runtime targets handle every workload we build. Each has a narrow niche. Misplacing a workload between them is the second most common cost-drift cause after model-tier choice.

Runaway agent loops are the single most expensive accidental behavior in the Studio’s runtime. Every agent is wrapped in three levels of cap: per-run, per-day, per-sprint. When any cap fires, the harness halts the agent and writes a SEV-2 alert. Caps are non-negotiable.

The harness checks caps before each API call and after each tool call. On breach, it halts, writes the audit row with outcome=fail and an error that names the cap, appends a row to alerts, and sends the email. A human clears the alert only after the root cause is understood — caps do not auto-reset.