@ultimat3/ai 1.2.0 → 2.0.0

package/README.md

@@ -25,6 +25,46 @@ const answer = await ai.scope({ actorKey: actor.id, orgKey: actor.orgId }, async
 });
 ```
 
+## Budgets — and which of the three is fleet-wide
+
+`request` is one call chain. `actor` and `orgs` are counters across calls, so where they live
+decides what they mean:
+
+| `budgetStore` | `actor` / `org` counts | Right for |
+|---|---|---|
+| omitted — `MemoryBudgetStore` (the default) | **per process**, and reset on every deploy | `x dev`, tests, a single-replica app |
+| your own `BudgetStore` | fleet-wide | anything with more than one replica |
+
+```ts
+import { AnthropicProvider, type BudgetStore, createGateway } from '@ultimat3/ai';
+
+declare const redis: {
+  incrby(key: string, by: number): Promise<number>;
+  del(key: string): Promise<unknown>;
+  flushdb(): Promise<unknown>;
+};
+
+const sharedBudget: BudgetStore = {
+  spent: (key) => redis.incrby(key, 0),
+  add: async (key, tokens) => {
+    await redis.incrby(key, tokens);
+  },
+  reset: async (key) => {
+    await (key === undefined ? redis.flushdb() : redis.del(key));
+  },
+};
+
+export const sharedGateway = createGateway({
+  providers: [new AnthropicProvider()],
+  budget: { request: 40_000, actor: 500_000, org: 20_000_000 },
+  budgetStore: sharedBudget,
+});
+```
+
+Three methods, and `add` takes a **negative** `tokens` — releasing a reservation the call never
+spent is a credit, so a store that clamps at zero leaks the ceiling. `org: 20_000_000` on the
+default store at `replicas: 6` is six ledgers of twenty million, which is a budget that is not one.
+
 ## Rules the gateway enforces
 
 | Rule | Why |
@@ -38,6 +78,10 @@ const answer = await ai.scope({ actorKey: actor.id, orgKey: actor.orgId }, async
 | A control the model lacks is **refused**, never dropped | a declaration reading `effort: 'max'` that quietly runs at the default is the failure nobody can see |
 | A control nobody asked for is **omitted**, never defaulted | a default sent as a request is indistinguishable on the wire from one that was declared |
 | A refusal is `X_LLM_REFUSED`, not a schema failure | it is a 200 with no answer in it, and a repair turn buys the same refusal again |
+| The refusal's `alternative` is only ever a **more capable** model | registration order is most-capable-first and `moreCapableThan` walks it upward; retrying a refusal on a weaker model is the one retry that cannot help, so an unbeatable model gets no suggestion at all |
+| Fallback is across **providers serving one model**, never across models | a silent model swap changes what answered, what it cost and which eval baseline the answer belongs to; the gateway stamps `result.provider`, and `llm()` puts it on the span as `llm.provider`, so the fallback that does exist is never silent |
+| The repair turn replays the tool call's arguments, never an empty `text` | an answer through the `respond` tool leaves `text` empty, and an empty text block is a 400 — the repair came back as `X_AI_PROVIDER_UNAVAILABLE` |
+| `reserve()` **debits** the estimate and takes a turn | three concurrent calls otherwise read the same `spent()`, all pass, and all three record against a ceiling only one of them fitted; `record` reconciles and `release` gives it back |
 | A refusal is never cached | a cached one keeps serving a classifier decision after the prompt was fixed |
 | Retries use **full jitter** | synchronised retries from N workers reproduce the rate limit |
 | A 4xx is never retried | the same body gets the same rejection and burns the budget |
@@ -80,7 +124,36 @@ Vectors are L2-normalised on arrival, so `cosine` stays a dot product. A width o
 declared `dimension` is `X_VECTOR_DIM_MISMATCH` **before** anything reaches a store — a store
 half-written at the wrong width has no error to report, only worse answers.
 
-Models, `As of 2026-08`:
+## The model catalogue is open
+
+`ModelId` is a **`string`**, and the catalogue is a registry. Your own gateway, Bedrock, Azure,
+Vertex, a fine-tune, a negotiated rate — all expressible, none needing a fork.
+
+```ts
+registerModel({
+  id: 'llama-internal-70b',
+  contextWindow: 128_000,
+  maxOutput: 8_192,
+  inputPerMillion:  { minor: 20, currency: 'USD' },   // YOUR price, integer minor units
+  outputPerMillion: { minor: 40, currency: 'USD' },
+  cacheMinimumTokens: 0,
+  reasoning: { effort: false, adaptive: false, disableThinkingUpTo: undefined },
+});
+
+configureAi({ gateway: createGateway({ providers: [new InternalGatewayProvider()] }) });
+```
+
+**The three built-ins register through this same call.** There is one way to put a model in the
+catalogue, and the default path is the app's path. Re-registering an id replaces its spec and keeps
+its rung — which is how a negotiated enterprise rate is expressed, and why there is no second
+`overrideModel` call. An id nothing registered is `X_AI_MODEL_UNKNOWN` at the first read, naming
+the registered set; that check is what replaced the closed union, so a wrong id is still caught
+without making a right one inexpressible.
+
+Registration order is the capability ladder, most capable first — `moreCapableThan` is its only
+reader, and `X_LLM_REFUSED`'s fix line the only thing that acts on it.
+
+Built in, `As of 2026-08`:
 
 | Model | Context | Max output | Input / MTok | Output / MTok | `effort` | adaptive thinking |
 |---|---|---|---|---|---|---|
@@ -90,6 +163,76 @@ Models, `As of 2026-08`:
 
 The last two columns are data on the spec, not prose: `body()` builds the reasoning half from
 them, so a downgrade for price cannot become a request the provider rejects.
+`AnthropicProvider.models` is its own list, never the registry's — your internal model is not
+routed to Anthropic.
+
+## The OpenAI **format** — Azure, vLLM, Ollama, your own gateway
+
+`openAiProvider()` speaks the OpenAI chat-completions **wire format**, not one vendor. Azure
+OpenAI, vLLM, Ollama, LiteLLM, OpenRouter, Together and most self-hosted company gateways serve
+that format, so "point Ultimate at our internal model gateway" is a `baseUrl` and a `models` list.
+
+```ts
+import { openAiProvider, OPENAI_MODEL_IDS, createGateway, configureAi } from '@ultimat3/ai';
+
+// OpenAI itself. `apiKey` takes a `Secret`; OPENAI_API_KEY is read when it is omitted.
+openAiProvider({ apiKey: env.OPENAI_API_KEY, models: [...OPENAI_MODEL_IDS] });
+
+// Azure OpenAI — the deployment URL as written, api-version query and all. `models` are
+// DEPLOYMENT names on Azure, and the key rides in `api-key`, not `Authorization`.
+openAiProvider({
+  apiKey: env.AZURE_OPENAI_KEY,
+  auth: 'api-key',
+  baseUrl: 'https://acme.openai.azure.com/openai/deployments/prod?api-version=2026-05-01',
+  models: ['prod'],
+});
+
+// vLLM / your own gateway, on the cluster. Register the model first — nothing can price an id
+// the catalogue has never heard of.
+openAiProvider({
+  apiKey: env.GATEWAY_TOKEN,
+  baseUrl: 'https://llm.acme.internal/v1',
+  models: ['llama-internal-70b'],
+  name: 'acme-gateway',            // what `result.provider` and `llm.provider` will say
+  headers: { 'x-team': 'platform' },
+});
+
+// Ollama, on a laptop. The key is required and ignored, exactly as Ollama's own docs have it.
+openAiProvider({ apiKey: 'ollama', baseUrl: 'http://localhost:11434/v1', models: ['qwen3'] });
+```
+
+Priced built-ins — list price from `developers.openai.com/api/docs/pricing`, read **2026-08-16**:
+
+| Model | Context | Max output | Input / MTok | Output / MTok | `reasoning_effort` |
+|---|---|---|---|---|---|
+| `gpt-5.6-sol` | 1.05M | 128K | $5 | $30 | yes |
+| `gpt-5.6-terra` | 1.05M | 128K | $2 | $12 | yes |
+| `gpt-5.6-luna` | 1.05M | 128K | $0.20 | $1.20 | yes |
+
+Three, and no more, on purpose: `gpt-4o` and the `o1` family cache at **0.5x** input where `costOf`
+assumes 0.1x, and the `pro` tiers publish no cached rate at all. A wrong price is worse than a
+missing one — `costOf` answers confidently either way, and the missing entry says so with
+`X_AI_MODEL_UNKNOWN`. Register those yourself, at the rate your own contract names.
+
+| Rule | Why |
+|---|---|
+| **Structured output is the `respond` tool**, never `response_format` | `llm()` already projects `output` into one tool and reads the answer out of the tool call; `json_schema` + `strict` would be a second structured-output path (axiom 1) and is the one feature most OpenAI-*compatible* servers do not implement |
+| `tool_choice` is forced when the request offers **exactly one** tool | one tool is nothing to choose between, and that is precisely `llm()`'s shape. A tool loop (`agent()`) is never forced — that would decide the model's next step for it |
+| `strict: true` is claimed only when the schema **can keep the promise** | on this wire `strict` is checked by the server: one optional field and the request is a 400. The flag is derived from the projected schema, never forwarded |
+| `max_completion_tokens`, never `max_tokens` | the old field is rejected outright by every current reasoning model |
+| `stream_options: { include_usage: true }` on every streamed call | without it the final chunk carries no `usage`, and the budget reconciles a real call against nothing |
+| Usage absent anyway → **estimated**, never zero | a compatible server that ignores `stream_options` would otherwise refund the whole reservation |
+| `prompt_tokens` minus `cached_tokens` is the input count | this format counts the cached prefix inside `prompt_tokens`; Anthropic's excludes it, and reporting it as-is bills the cached half twice |
+| Tool-call deltas are merged by `tool_calls[].index` | id and name arrive on the first fragment only — merging by array position builds one call per chunk |
+| A tool call is emitted **whole**, at the finish reason | there is no per-block stop event here, and a fragment is not an argument list |
+| `role: 'system'`, not `developer` | every other server in the family knows only `system`, and OpenAI accepts it |
+| A refusal (`message.refusal`, or `finish_reason: 'content_filter'`) is `X_LLM_REFUSED` | it is a 200 with no answer in it, exactly as on the Anthropic path |
+| The API key is revealed as late as possible, and scrubbed out of error detail | a proxy that echoes request headers into its 4xx body is the one path by which a key reaches a log index |
+
+`thinking` maps onto the one field this format has: `'disabled'` is `reasoning_effort: 'none'`,
+`effort` is `reasoning_effort` as written, and asking for both is `X_AI_REQUEST_INVALID` rather
+than a silent pick. A model registered with `reasoning: { effort: false }` refuses both locally, so
+a llama behind vLLM never gets a field it would reject.
 
 ## `llm()` — a model call, declared as an action
 
@@ -124,7 +267,73 @@ summarize.contract();    // the contract tests
 | `budget` | reserved against the worst case **before** the provider is reached — nothing spent, nothing truncated |
 | `cache.semantic` | one store per scope, keyed by embedding; a prompt version bump reaches a different store, so the bump *is* the invalidation |
 | `policy` | the same object every surface evaluates — an MCP call and an HTTP call are denied identically |
-| `vars` | the one declared place a model call loads data, so a reader can see what was sent |
+| `vars` | the one declared place a model call loads data, so a reader can see what was sent — and the one place a redactor sees it, and where a `Secret` is refused |
+
+### Streaming is the same action
+
+```ts
+for await (const chunk of summarize.stream({ postId }, { ctx })) {
+  if (chunk.type === 'text') write(chunk.text);
+  if (chunk.type === 'done') save(chunk.value);   // validated against `output`
+}
+```
+
+Policy, input parse, budget scope, semantic cache, span, audit and `.tool()` all still apply: the
+invocation is an ordinary one, marked so the model half streams. Two consequences worth knowing:
+
+| Decision | Why |
+|---|---|
+| the `done` chunk carries the validated value; text increments are **unvalidated** | a schema cannot be checked until the last token has landed |
+| **no repair turn** — a bad shape is `X_LLM_STREAM_INVALID` | the consumer has already read the tokens; a second answer over the top is two answers to one question. The fix names the non-streaming call |
+| the budget is reserved **before the first token** and reconciled at `done` | unchanged from `generate()`; a stream that throws or is abandoned releases in a `finally` |
+| no `respond` tool is offered | a tool call is emitted whole, so forcing one leaves nothing to stream — the answer is prose, and its JSON parse is what a non-string `output` validates |
+| lazy | nothing is authorised, budgeted or sent until the first pull |
+
+## `agent()` — the tool loop, also an action
+
+The second half of "no ninth primitive": a tool-using run is still one server-authoritative
+operation with an input schema, an output schema and a policy.
+
+```ts
+export const support = agent({
+  input:  t.object({ orderId: t.string }),
+  output: t.object({ answer: t.string }),
+  prompt: supportPrompt,
+  vars:   ({ input }) => ({ orderId: input.orderId }),
+  tools:  [lookupOrder, issueRefund],          // actions, each mcp.expose
+  maxTurns: 6,
+  maxToolResultChars: 4_000,
+  budget: { tokensPerRun: 200_000, costPerCall: { minor: 50, currency: 'USD' } },
+  policy: can('order:support'),
+});
+```
+
+| Rule | Why |
+|---|---|
+| the actor is **`ctx.actor`**, read once, never from the model | this is the mistake a hand-rolled loop ships, and the reason the loop belongs in the framework |
+| a tool that is not `mcp: { expose: true }` is `X_AGENT_TOOL_UNEXPOSED` **at declaration** | a silently dropped tool reads as offered and is not; `isMcpExposed` is the one predicate, so an in-app agent and an external MCP client see the same catalogue |
+| running out of turns is `X_AGENT_MAX_TURNS`, never a partial answer | a half-finished transcript returned as a result is working notes presented as a decision |
+| `budget.tokensPerRun` caps the **whole run** | a single call is bounded by `maxTokens`; a loop is bounded by nothing until this is set |
+| a tool result is truncated, and says so | the transcript IS the request, so an untruncated result is re-billed once per remaining turn |
+| **no semantic cache** | similar prompts do not have similar answers once the answer depends on what `lookupOrder` returned this second |
+
+## Redaction: one declared seam
+
+`vars()` is the one place a model call loads data, so it is the one place anything can sit between
+the row and a third-party endpoint.
+
+```ts
+configureAi({ gateway, redact: (text) => scrubPatientIdentifiers(text) });
+```
+
+The redactor sees the whole rendered prompt and the system prompt — template as well as values,
+because a redactor shown only the values cannot tell a name in a data slot from the same name in an
+instruction. Whether it changed anything is on the span as `llm.redacted`.
+
+**What** to remove is yours: a PII classifier is a model choice, so the framework ships the seam
+and not the classifier. The one rule it does enforce, redactor or not: a `Secret` among the
+variables is `X_AI_PROMPT_SECRET`. Not a leak — `Secret` renders `[redacted]` by value — but a
+prompt that reads fine, means something else, and costs full price.
 
 The gateway is ambient, installed once at boot — a declaration is evaluated at module scope,
 long before a provider exists:
@@ -186,7 +395,7 @@ X_EVAL_THRESHOLD: an eval scored below its tolerance
   cause: eval "summarize" scored 0.667 against a recorded baseline of 1.000
          (tolerance 0.050) on prompt version summarize@1.0.0 (a3f1…);
          regressed: overall 0.67 ← 1.00, refund 0.00 ← 1.00
-  fix:   x test summarize to see per-case scores, then fix the prompt — or
+  fix:   x test eval --filter summarize to see per-case scores, then fix the prompt — or
          ULTIMATE_EVAL_RECORD=1 x test eval to accept the new numbers as a reviewed diff
 ```
 
@@ -229,7 +438,14 @@ RRF fuses by *rank*, so the two score scales never have to be reconciled.
 `PgVectorStore` is the production path: pgvector cosine (`<=>`, HNSW) and Postgres FTS
 (`websearch_to_tsquery` + `ts_rank_cd`, GIN) in **the same Postgres**, fused by `1/(k+rank)` in
 one statement. `MemoryVectorStore` is the dev twin — BM25 instead of `ts_rank_cd`, the same RRF,
-the same envelope. `store.ddl()` prints the table and both indexes; `x db gen` emits it.
+the same envelope.
+
+`store.ddl()` returns one string: `create extension if not exists vector`, the table, and the
+three indexes (hnsw on `embedding`, GIN on `tsv`, GIN on `metadata`). **No command emits it,
+`As of 2026-08`** — `x db gen <name>` diffs `describeEntities()`, a vector store is not an
+`entity()`, and no CLI file references `PgVectorStore` or `ddl()` at all. Split it and paste each
+statement into its own file under `packages/db/migrations/`, exactly as `AUTH_TABLES` is applied,
+then `x db migrate`.
 
 ### The scope is the leak-proofing
 
@@ -251,12 +467,14 @@ nothing. `scoped()` only ever **tightens** — re-scoping to a different tenant
 ## Tools: the same projection as MCP
 
 ```ts
+// `ProjectableAction` — `{ name, mcp?, inputJsonSchema?, run }`, the projection SEAM.
 const tools = toLlmTools([publishPost, suspendUser]);   // only those with mcp.expose
 const result = await runLlmToolCall(actions, call, actor);
 ```
 
-An in-app agent and an external MCP agent both end at `action.run`, so they authorize
-identically. The actor comes from the request context, never from the model.
+An in-app agent and an external MCP agent both end at the same `invoke` — `run` is the seam that
+carries it, and an action facade has no `.run` of its own. So they authorize identically. The
+actor comes from the request context, never from the model.
 
 ## Errors
 
@@ -266,7 +484,12 @@ identically. The actor comes from the request context, never from the model.
 | `X_AI_BUDGET_EXCEEDED` | refused pre-flight, naming the scope and what remains |
 | `X_AI_GATEWAY_MISSING` | an `llm()` action ran before `configureAi` |
 | `X_AI_PROMPT_VERSION` | version drift, or a render missing a declared variable |
+| `X_AI_MODEL_UNKNOWN` | a model id nothing called `registerModel` for; names the registered set |
+| `X_AI_PROMPT_SECRET` | `vars()` returned a `Secret`, which would render `[redacted]` into the prompt |
 | `X_LLM_OUTPUT_INVALID` | the model failed its `output` schema on the answer and on the repair turn |
+| `X_LLM_STREAM_INVALID` | a streamed answer failed its schema, and a stream cannot take a repair turn |
+| `X_AGENT_MAX_TURNS` | an `agent()` used every turn without answering |
+| `X_AGENT_TOOL_UNEXPOSED` | an `agent()` lists an action no MCP surface exposes |
 | `X_EVAL_THRESHOLD` | an eval scored below its bar |
 | `X_VECTOR_DIM_MISMATCH` | a vector's length disagrees with the store |
 | `X_VECTOR_SCOPE_WIDENED` | a derived vector scope tried to leave the tenant it was bound to |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "1.2.0",
-    "@ultimat3/cache": "1.2.0",
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/db": "1.2.0",
-    "@ultimat3/money": "1.2.0",
-    "@ultimat3/policy": "1.2.0",
-    "@ultimat3/schema": "1.2.0",
-    "@ultimat3/time": "1.2.0"
+    "@ultimat3/action": "2.0.0",
+    "@ultimat3/cache": "2.0.0",
+    "@ultimat3/core": "2.0.0",
+    "@ultimat3/db": "2.0.0",
+    "@ultimat3/money": "2.0.0",
+    "@ultimat3/policy": "2.0.0",
+    "@ultimat3/schema": "2.0.0",
+    "@ultimat3/time": "2.0.0"
   }
 }

package/src/agent.ts

@@ -0,0 +1,287 @@
+/**
+ * `agent()` — a multi-turn tool-using model call, declared as an `action`.
+ *
+ * The third instance of the framework's rule, after `llm()` and `backfill()`: a new capability
+ * arrives as a FACTORY over an existing primitive, never as a ninth kind. A tool-using run is
+ * still one server-authoritative operation with an input schema, an output schema and a policy —
+ * so this returns an `action`, and inherits `.tool()`, `.openapi()`, `.client()`, `.job()`,
+ * `.contract()` and its manifest row without a line here.
+ *
+ * It exists because the alternative is a hand-rolled loop outside the framework, and a hand-rolled
+ * loop is where the dangerous mistake lives: taking the ACTOR from the model's output. Here the
+ * actor is `ctx.actor` and nothing the model emits can reach it — `runLlmToolCall` is handed an
+ * identity the request established, and the tool it runs is an ordinary action whose own policy
+ * decides. There is no "LLM permissions" concept, because there is no second authz system.
+ *
+ * Deliberately NOT here: a semantic cache. Similar prompts do not have similar answers once the
+ * answer depends on what `lookupOrder` returned this second, and a cache over that would serve
+ * one run's world state to another. Version bump plus the tools' own caching is the story.
+ */
+
+import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import { action } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import { withSpan } from '@ultimat3/core';
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { formatIssues, validateAsync } from '@ultimat3/schema';
+import type { BudgetLimits } from './budget';
+import { BudgetLedger, currentBudget, withBudget } from './budget';
+import {
+  AgentMaxTurnsError,
+  AgentToolUnexposedError,
+  LlmOutputInvalidError,
+  LlmRefusedError,
+  LlmTruncatedError,
+} from './errors';
+import type { LlmBudget } from './llm';
+import { answerAttributes, RESPOND, respondToolFor, structuredOutputOf } from './llm';
+import type { ModelId } from './models';
+import { DEFAULT_MODEL, moreCapableThan } from './models';
+import type { Prompt, PromptVars } from './prompt';
+import type { AiContentBlock, AiMessage, GenerateRequest, GenerateResult } from './provider';
+import { assertNoSecrets } from './redaction';
+import { aiGateway, aiRedactor } from './runtime';
+import type { LlmTool, LlmToolResult, ProjectableAction } from './tools';
+import { runLlmToolCall, toLlmTools } from './tools';
+
+/**
+ * Turn ceiling when the declaration omits one. Low on purpose: a loop that needs more than this
+ * is usually a loop with no exit condition, and every turn re-sends the whole transcript, so cost
+ * grows quadratically in turns rather than linearly.
+ */
+const DEFAULT_MAX_TURNS = 8;
+
+/** Output ceiling per turn when the declaration omits one. Same reasoning as `llm()`'s. */
+const DEFAULT_MAX_TOKENS = 4_096;
+
+/**
+ * Characters of ONE tool result the model may read. A tool that returns a 2MB row set otherwise
+ * spends the whole context window on turn two and every later turn re-sends it — the transcript
+ * is the request, so an untruncated result is billed once per remaining turn.
+ */
+const DEFAULT_TOOL_RESULT_CHARS = 4_000;
+
+export interface AgentBudget extends LlmBudget {
+  /**
+   * Token ceiling for the WHOLE run, every turn counted. The one ceiling `llm()` does not need:
+   * a single call is bounded by `maxTokens`, a loop is bounded by nothing until this is set.
+   */
+  readonly tokensPerRun?: number;
+}
+
+export interface AgentVarsArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface AgentDef<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+> {
+  readonly model?: ModelId;
+  readonly input: TInput;
+  readonly output: TOutput;
+  readonly prompt: Prompt<V>;
+  /** Same contract as `llm()`: the one declared place a run loads data. */
+  vars(args: AgentVarsArgs<TInput>): V | Promise<V>;
+  /**
+   * The actions the model may call. Each must be `mcp: { expose: true }` — the same predicate an
+   * external MCP client is filtered by, so an in-app agent and an external one are offered
+   * exactly the same tools. Listing one that is not exposed is refused at declaration rather than
+   * dropped, because a tool that reads as offered and silently is not is the worst of both.
+   */
+  readonly tools: readonly ProjectableAction[];
+  /** Hard ceiling on model turns. Reaching it is `X_AGENT_MAX_TURNS`, never a partial answer. */
+  readonly maxTurns?: number;
+  readonly maxToolResultChars?: number;
+  readonly budget?: AgentBudget;
+  readonly policy: ActionPolicy;
+  readonly mcp?: ActionMcp;
+  /** Enforced completion ceiling PER TURN. The model never sees it. */
+  readonly maxTokens?: number;
+}
+
+export function agent<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>): Action<TInput, TOutput> {
+  const respond = respondToolFor(def.output);
+  // At declaration, because the tools are values by then and a run that discovers this at the
+  // first request has already been declared, registered and projected as if it worked.
+  const offered = toLlmTools(def.tools);
+  if (offered.length !== def.tools.length) {
+    throw new AgentToolUnexposedError({
+      agent: def.prompt.ref,
+      tools: def.tools.filter((a) => !offered.some((o) => o.name === a.name)).map((a) => a.name),
+    });
+  }
+  return action<TInput, TOutput>({
+    input: def.input,
+    output: def.output,
+    policy: def.policy,
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    handle: (args) => run(def, respond, offered, args),
+  });
+}
+
+async function run<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(
+  def: AgentDef<TInput, TOutput, V>,
+  respond: LlmTool,
+  offered: readonly LlmTool[],
+  args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
+): Promise<InferOutput<TOutput>> {
+  const { prompt } = def;
+  const name = prompt.ref;
+  const model = def.model ?? prompt.model ?? DEFAULT_MODEL;
+  const vars = await def.vars({ input: args.input, ctx: args.ctx });
+  assertNoSecrets(name, vars);
+  const redact = aiRedactor();
+  const rawPrompt = prompt.render(vars);
+  const rendered = redact(rawPrompt);
+  const system = prompt.system === undefined ? undefined : redact(prompt.system);
+  const maxTurns = def.maxTurns ?? DEFAULT_MAX_TURNS;
+  const chars = def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS;
+
+  return withSpan('ai.agent', async (span) => {
+    span.setAttributes({
+      'agent.model': model,
+      'agent.prompt': name,
+      'agent.prompt.hash': prompt.hash,
+      'agent.tools': offered.length,
+      'agent.max_turns': maxTurns,
+      'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
+    });
+
+    const ledger = (currentBudget() ?? new BudgetLedger({ limits: {} })).derive(limitsOf(def));
+    const gateway = aiGateway(name);
+    const base: GenerateRequest = {
+      model,
+      ...(system === undefined ? {} : { system }),
+      messages: [],
+      maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
+      ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
+      ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
+      tools: [...offered, respond],
+    };
+
+    return withBudget(ledger, async () => {
+      // The actor is read ONCE, from the context the request established, and is the only
+      // identity any tool runs as. Nothing below reads an actor out of `result` — a model cannot
+      // name the identity it acts as, and a loop that let it would be an escalation primitive.
+      const { actor } = args.ctx;
+      let messages: readonly AiMessage[] = [{ role: 'user', content: rendered }];
+      let calls = 0;
+      let issues: string | undefined;
+
+      for (let turn = 1; turn <= maxTurns; turn += 1) {
+        const result = await gateway.generate({ ...base, messages });
+        span.setAttributes({
+          'agent.turns': turn,
+          'agent.tool_calls': calls,
+          ...answerAttributes(result),
+        });
+        assertAnswerable(result, name);
+
+        const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
+        if (requested.length > 0) {
+          const results: LlmToolResult[] = [];
+          for (const call of requested) results.push(await runLlmToolCall(def.tools, call, actor));
+          calls += requested.length;
+          messages = [...messages, assistantTurn(result), toolResults(results, chars)];
+          continue;
+        }
+
+        const parsed = await validateAsync(def.output, structuredOutputOf(result));
+        if (parsed.issues === undefined) return parsed.value;
+        // A wrong shape gets another turn like any other, because unlike `llm()` this loop has
+        // turns left by construction — and unlike a tool result, the correction is the message.
+        issues = formatIssues(parsed.issues).join('; ');
+        if (result.stopReason === 'max_tokens') {
+          throw new LlmTruncatedError({ prompt: name, maxTokens: base.maxTokens });
+        }
+        messages = [...messages, assistantTurn(result), { role: 'user', content: repair(issues) }];
+      }
+
+      // Two different exhaustions, so two different causes: a loop that kept calling tools and
+      // never answered is not the same event as one that answered the wrong shape every time.
+      if (issues !== undefined) {
+        throw new LlmOutputInvalidError({ prompt: name, attempts: maxTurns, issues });
+      }
+      throw new AgentMaxTurnsError({ agent: name, turns: maxTurns, calls });
+    });
+  });
+}
+
+/** Refuse before the answer is read, for the reason `llm()` does: a refusal is a 200 with no answer. */
+function assertAnswerable(result: GenerateResult, name: string): void {
+  if (result.stopReason !== 'refusal') return;
+  throw new LlmRefusedError({
+    prompt: name,
+    model: result.model,
+    alternative: moreCapableThan(result.model),
+    category: result.stopDetails?.category,
+    explanation: result.stopDetails?.explanation,
+  });
+}
+
+/**
+ * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
+ * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
+ * because it has no `tool_result` to follow them with, and the API demands one.
+ */
+function assistantTurn(result: GenerateResult): AiMessage {
+  const blocks: AiContentBlock[] = [];
+  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
+  for (const call of result.toolCalls) {
+    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
+  }
+  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
+  return blocks.length === 0
+    ? { role: 'assistant', content: '(no answer)' }
+    : { role: 'assistant', content: blocks };
+}
+
+function toolResults(results: readonly LlmToolResult[], chars: number): AiMessage {
+  return {
+    role: 'user',
+    content: results.map((result) => ({
+      type: 'tool_result' as const,
+      tool_use_id: result.toolUseId,
+      content: truncate(result.content, chars),
+      // A denial or a failure is an outcome the model should read and react to, flagged so it
+      // does not read as data.
+      ...(result.isError === true ? { is_error: true } : {}),
+    })),
+  };
+}
+
+/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
+function truncate(text: string, chars: number): string {
+  if (text.length <= chars) return text;
+  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
+}
+
+function repair(issues: string): string {
+  return `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
+}
+
+function limitsOf<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>): BudgetLimits {
+  const budget = def.budget;
+  return {
+    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+    // The ledger's `request` scope accumulates across every call made under one ledger, which for
+    // a run under `withBudget` is exactly "the whole run".
+    ...(budget?.tokensPerRun === undefined ? {} : { request: budget.tokensPerRun }),
+  };
+}