@ultimat3/ai 1.2.0 → 3.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,211 @@ 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],          // real actions, each mcp.expose
+  maxTurns: 6,
+  maxToolResultChars: 4_000,
+  budget: { tokensPerRun: 200_000, costPerCall: { minor: 50, currency: 'USD' } },
+  policy: can('order:support'),
+  onTurn: ({ turn, toolCalls, cost }) => progress.push({ turn, toolCalls, cost }),
+});
+```
+
+`tools` takes the `action()` an app already wrote — `[lookupOrder, issueRefund]`, the imports
+themselves. `As of 2026-08`: it took a hand-shaped `ProjectableAction` until then, so the line
+above was a `TS2741` against every real action (issue #124) and the only thing that satisfied it
+was a stand-in written for a test.
+
+An `agent()` returns an action, so **an agent is a tool of another agent** — a supervisor lists a
+sub-agent in its own `tools` and the sub-agent runs under the same actor, through the same policy.
+No `hive()`, no supervisor primitive: it falls out of the factory rule.
+
+| 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 |
+| an aborted `ctx` unwinds the run — at the top of every turn, before every tool batch, and on the socket | the transcript IS the request, so a loop that keeps going after the caller disconnects re-sends it once per remaining turn, runs every remaining side effect and discards the answer. `ctx.signal` rides on `GenerateRequest` too, so a call already in flight is cut rather than paid for |
+| the tools of **one turn** run concurrently, results paired by `tool_use` id | a turn asking for five tools cost 5x wall clock and nothing said so. Order is positional, never by completion; the batch is bounded by what one turn asked for, and each tool is an action with its own `policy` and `rateLimit`, so a second ceiling here would be a throttle competing with those |
+| `onTurn` reports each completed turn as it happens (and an `agent.turn` span event, always) | a 90-second run emitted nothing until it returned. Observation only — it cannot steer the loop, see the transcript or reach the actor — and a throw from it fails the run rather than being swallowed |
+| 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 |
+
+## `hive()` — many members, one action
+
+Fan an action out over many inputs. The fourth factory over a primitive, after `llm()`,
+`backfill()` and `agent()`: a fan-out is still one server-authoritative operation with an input
+schema, an output schema and a policy.
+
+```ts
+import { action, t } from '@ultimat3/action';
+import { hive } from '@ultimat3/ai';
+import { allow } from '@ultimat3/policy';
+
+const summarisePost = action({
+  input: t.object({ postId: t.uuid }),
+  output: t.object({ summary: t.string }),
+  policy: allow(),
+  mcp: { expose: true },
+  handle: ({ input }) => ({ summary: input.postId }),
+});
+
+export const summariseBacklog = hive({
+  input: t.object({ postIds: t.array(t.uuid) }),
+  member: summarisePost,
+  split: ({ input }) => input.postIds.map((postId) => ({ postId })),
+  concurrency: 8,
+  minMembers: 2,
+  onMemberError: 'collect',
+  budget: { tokensPerRun: 500_000 },
+  policy: allow(),
+});
+```
+
+`member` is any action — most usefully an `agent()`, which makes a hive a **supervisor over
+sub-agents** with no supervisor primitive anywhere.
+
+| Rule | Why |
+|---|---|
+| `members` comes back in **split order**, with `index` on every arm | a hand-rolled `Promise.all` reports in completion order, so joining a result back to the row it came from silently depends on nothing having failed |
+| three arms — `ok`, `failed`, `skipped` — never two | *ran and threw* and *never ran* are different facts, and an aborted sibling is the second. Collapsing them makes "the hive stopped early" read as "every remaining item is bad data" |
+| `onMemberError` is **required** | `'abort'` stops and leaves the rest `skipped`; `'collect'` harvests the rest. Both are right for somebody, so neither is a default |
+| the hive **never names an actor** | `split` derives member inputs from `input` and `ctx` and from nothing a model emitted; each member runs through its own callable, so `invoke` applies the member's own policy with `ctx.actor` untouched |
+| `concurrency` bounds the fan-out; one derived ledger bounds the spend | the ceiling holds under parallelism because the budget's root turnstile debits before the call, so three members against a ceiling only one fits leave exactly one `ok` — no hive-specific budget code exists |
+| an empty split is `X_HIVE_EMPTY` | "0 ok, 0 failed" cannot be told apart from a query that returned no rows and nobody noticed |
+| `minMembers` (default 2) stops fanning out, and **drops nothing** | a member's fixed cost dominates trivial work; below the floor every input still runs, serially |
+| an aborted `ctx` unwinds the whole hive with `X_ABORTED` | distinct from `onMemberError: 'abort'`, which is a completed run with a partial harvest worth returning — here there is nobody left to hand it to |
+
+## `agentJob()` — an agent as durable background work
+
+Run an agent over a million rows as resumable, retried, budgeted queue work. `As of 2026-08` this
+is the only way an agent reaches a queue at all: `.job()` hands back `kind: 'action-job'`, and
+`isJobHandle` needs `kind === 'job'` plus membership of a `WeakMap` only `job()` writes, so nothing
+externally shaped has ever reached the registry, the worker or the dead-letter path (issue #125).
+
+```ts
+import { t } from '@ultimat3/action';
+import { agent, agentJob, definePrompt } from '@ultimat3/ai';
+import { allow } from '@ultimat3/policy';
+
+const summarisePost = agent({
+  input: t.object({ postId: t.uuid, orgId: t.uuid }),
+  output: t.object({ summary: t.string }),
+  prompt: definePrompt<{ postId: string }>({
+    id: 'summarise-post',
+    version: '1.0.0',
+    template: 'Summarise post {{postId}}.',
+  }),
+  vars: ({ input }) => ({ postId: input.postId }),
+  tools: [],
+  policy: allow(),
+});
+
+export const summariseBacklog = agentJob(summarisePost, {
+  name: 'summarise-backlog',
+  tenant: (input) => input.orgId,
+  retry: { attempts: 3, backoff: 'exponential' },
+});
+```
+
+It composes `job()` rather than imitating a handle, so `.enqueue()`, the outbox, the worker's
+cancellation, `x jobs show` and its manifest row all arrive for free. Pair it with `backfill()` for
+the sweep and `hive()` for the fan-out inside one page.
+
+| Rule | Why |
+|---|---|
+| `name` is required, and is the queue key | a job name is what queued, retrying and dead-lettered rows already carry, so renaming an export must not move where they are delivered |
+| `tenant` and `retry` are required, no default | `jobs` states it: every candidate default for `tenant` is a cross-tenant read waiting for the first job that takes an org id in its input. `tenant: 'none'` is the explicit statement that it touches no scoped table |
+| the action projection is read **lazily** | `agentJob()` runs at module scope beside the `agent()` it wraps, and names are stamped by `registerAction` at boot — reading `.job()` eagerly makes that ordinary file `X_ACTION_UNREGISTERED` |
+| one execution path, and it is the action's | `run` is `invoke(agent, input, { surface: 'job', ctx })`, so the agent's policy, input parse, budget scope and span all apply — and the `ctx` is the worker's, so an attempt timing out aborts the agent's turn loop |
+| the actor is the worker context's, never the model's | the job body runs with system authority and the org comes from the job's declared `tenant`; nothing a model emits can reach either |
+
+### The at-least-once trap, said plainly
+
+**`idempotencyKey` dedupes the ENQUEUE, never the ATTEMPT.** Two enqueues with the same payload are
+one row. One row that a worker claims, half-runs and loses the lease on is claimed again, and **the
+agent runs a second time from the top** — as does every page a `backfill()` replays, since its
+`handle` is at-least-once by construction.
+
+So every tool the agent may call has to be idempotent: an `upsertAll`, an `updateWhere`, a statement
+whose second run changes nothing. Otherwise a replayed attempt issues a second refund.
+
+**The framework does not check this, and the reason is worth knowing.** `mutates` is not a fact an
+`action()` declares — it exists only in `@ultimat3/mcp`, which sets it to `true` for *every* action
+it projects — so a read-only `lookupOrder` and a destructive `issueRefund` are indistinguishable
+here. A rule refusing every tool that has not declared `idempotent: true` would refuse the reads
+too, and a wrong refusal is worse than a stated obligation. `isMutator` is legible, but `mutator()`
+is the local-first write primitive and catches almost none of the risk while reading as if it
+caught all of it. This is a contract you keep, not one the compiler keeps for you.
+
+## `describeAgents()` — what the manifest can say
+
+```ts
+import { describeAgents } from '@ultimat3/ai';
+
+describeAgents();
+// [{ name: 'supportAgent', prompt: 'support@1.0.0', promptHash: '…', model: 'claude-opus-5',
+//    maxTurns: 6, maxToolResultChars: 4000, tools: ['issueRefund', 'lookupOrder'],
+//    budget: { tokensIn: null, tokensPerRun: 200000, costPerCall: { minor: 50, currency: 'USD' } },
+//    mcp: true }]
+```
+
+An agent projects to an `ActionDescriptor` like any other action, and that descriptor knows nothing
+about turns or tools — so "how far can this loop, and what may it call" had no answer outside the
+source. Names are read when you ask, not when the agent was declared: `registerAction` stamps them
+at boot, long after `agent()` ran at module scope. An agent nothing registered has no row, because
+an action with no name reaches no route, no tool catalogue and no queue.
+
+## 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 +533,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 +576,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 +605,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 +622,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": "3.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,14 @@
     "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": "3.0.0",
+    "@ultimat3/cache": "3.0.0",
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/db": "3.0.0",
+    "@ultimat3/jobs": "3.0.0",
+    "@ultimat3/money": "3.0.0",
+    "@ultimat3/policy": "3.0.0",
+    "@ultimat3/schema": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   }
 }

package/src/agent-facts.ts

@@ -0,0 +1,70 @@
+// What an `agent()` IS, published for the manifest — turns, tools, budget, model, prompt hash.
+//
+// Nothing agent-shaped was visible anywhere before this: an agent projects to `ActionDescriptor`
+// like every other action, and that descriptor deliberately knows nothing about turns or tools,
+// so "which agents does this app have, how far can each one loop, and what may it call" had no
+// answer outside reading the source. Same shape as `describePrompts()` / `describeEvals()`, and
+// deliberately NOT a new `ActionDescriptor` field: @ultimat3/action is tier 3 and knows nothing
+// about models.
+
+import type { AnyAction } from '@ultimat3/action';
+import type { Money } from '@ultimat3/money';
+
+/** The declared ceilings, flattened so a manifest row is plain JSON. `null` is "not declared". */
+export interface AgentBudgetFact {
+  readonly tokensIn: number | null;
+  readonly tokensPerRun: number | null;
+  readonly costPerCall: Money | null;
+}
+
+export interface AgentFact {
+  /** The export name registration stamped — the same name `.tool()` and `tools/call` answer to. */
+  readonly name: string;
+  readonly prompt: string;
+  readonly promptId: string;
+  /**
+   * The prompt's content hash. An agent's behaviour is its prompt, so a row without one records
+   * which agent ran and not which agent it was — the same reason every eval result carries it.
+   */
+  readonly promptHash: string;
+  readonly model: string;
+  readonly maxTurns: number;
+  readonly maxToolResultChars: number;
+  /** Tool names, sorted — the catalogue this agent may call, which is its blast radius. */
+  readonly tools: readonly string[];
+  readonly budget: AgentBudgetFact;
+  /** Whether the agent itself is offered as a tool, so a supervisor could call it. */
+  readonly mcp: boolean;
+}
+
+/**
+ * Keyed by the action, and the facts are a THUNK: every name in a row — the agent's and its
+ * tools' — is stamped by `registerAction` at boot, long after `agent()` ran at module scope.
+ * Reading them here rather than at declaration is what makes a row name what an app can call.
+ */
+const registry = new Map<AnyAction, () => Omit<AgentFact, 'name'>>();
+
+export function registerAgentFact(target: AnyAction, facts: () => Omit<AgentFact, 'name'>): void {
+  registry.set(target, facts);
+}
+
+/**
+ * Every registered agent, by name.
+ *
+ * An agent still carrying no name is left out, and that is not a silent drop: a name is stamped by
+ * `registerAction`, an action without one reaches no route, no tool catalogue and no queue, so
+ * there is no capability for a row to describe. `named()` builds a TWIN rather than naming in
+ * place — registration names in place — so an agent renamed that way is absent for the same
+ * reason. Register it instead: `registerAction('supportAgent', support)`.
+ */
+export function describeAgents(): readonly AgentFact[] {
+  return [...registry.entries()]
+    .filter(([target]) => target.name !== '')
+    .map(([target, facts]) => ({ name: target.name, ...facts() }))
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/** Test-only reset. A module-level registry otherwise leaks between test files. */
+export function resetAgents(): void {
+  registry.clear();
+}

package/src/agent-job.ts

@@ -0,0 +1,97 @@
+/**
+ * `agentJob()` — an agent as durable, resumable, budgeted background work.
+ *
+ * The bridge `packages/action/src/job-handle.ts` names in its own header and could not build:
+ * `isJobHandle` needs `kind === 'job'` PLUS membership of a WeakMap only `job()` writes, so no
+ * externally-shaped object reaches the registry, the queue or the worker — and `action` and `jobs`
+ * are both tier 3, so neither may import the other. This package is tier 4 and may import both,
+ * which is exactly where that header says the adapter belongs.
+ *
+ * It composes `job()` rather than re-implementing a handle: the returned value IS one `job()`
+ * seated, so `.enqueue()`, the outbox, the worker's cancellation, the dead-letter path,
+ * `x jobs show` and its manifest row all arrive without a line here.
+ */
+
+import type { Action, ActionJobHandle } from '@ultimat3/action';
+import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
+import { job } from '@ultimat3/jobs';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+
+export interface AgentJobOptions<I> {
+  /**
+   * The durable queue key. REQUIRED and never derived from the agent's export name: a job name is
+   * what queued, retrying and dead-lettered rows already carry, so renaming an export must not
+   * move where they are delivered.
+   */
+  readonly name: string;
+  /**
+   * REQUIRED, no default, and the org this run's body acts under. `jobs` states why: every
+   * candidate default is a cross-tenant read waiting for the first job that takes an org id in its
+   * input. `tenant: 'none'` is the explicit statement that this agent touches no tenant-scoped
+   * table, and then every scoped read inside it fails closed.
+   */
+  readonly tenant: JobTenant<I>;
+  /** REQUIRED, no default. A model call fails transiently; how many times is nobody else's guess. */
+  readonly retry: RetryPolicy;
+  readonly queue?: string;
+  /**
+   * Defaults to the action projection's own key — `action:<name>:<fingerprint of input>` — which
+   * is stable across retries and derived from the payload alone.
+   *
+   * **It dedupes the ENQUEUE, never the ATTEMPT.** Two `enqueue` calls with the same payload are
+   * one row; one row that a worker claims, half-runs and loses the lease on is claimed again, and
+   * the agent runs a second time from the top. Combined with `backfill()`, whose `handle` is at
+   * least once by construction, a replayed page re-runs every agent on it.
+   *
+   * What that means for `tools`: **every tool the agent may call has to be idempotent** — an
+   * `upsertAll`, an `updateWhere`, a statement whose second run changes nothing — because a
+   * replayed attempt issues a second `issueRefund` otherwise. The framework does NOT check this and
+   * cannot: `mutates` is not a fact an `action()` declares (`@ultimat3/mcp` sets it to `true` for
+   * every action it projects), so a read-only `lookupOrder` and a destructive `issueRefund` are
+   * indistinguishable here, and a rule refusing both would be a wrong refusal. See the README.
+   */
+  idempotencyKey?(input: I): string;
+}
+
+/**
+ * Wrap an `agent()` — or any action — as a real job handle.
+ *
+ * Both reads of the underlying projection are LAZY, and that is load-bearing: `target.job()` calls
+ * `actionName()`, which throws `X_ACTION_UNREGISTERED` until `registerAction` stamps the export
+ * name at boot — and `agentJob()` is evaluated at module scope, right beside the `agent()` it
+ * wraps. The queue key comes from `options.name` for the same reason it is required.
+ */
+export function agentJob<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+  options: AgentJobOptions<InferOutput<TInput>>,
+): JobHandle<InferOutput<TInput>> {
+  let projected: ActionJobHandle<TInput, TOutput> | undefined;
+  const bridge = (): ActionJobHandle<TInput, TOutput> => {
+    if (projected === undefined) projected = target.job();
+    return projected;
+  };
+  return job<InferOutput<TInput>>({
+    name: options.name,
+    input: target.input as StandardSchemaV1<unknown, InferOutput<TInput>>,
+    tenant: options.tenant,
+    retry: options.retry,
+    ...(options.queue === undefined ? {} : { queue: options.queue }),
+    idempotencyKey: (input) =>
+      options.idempotencyKey?.(input) ?? bridge().idempotencyKey(asInput<TInput>(input)),
+    // ONE execution path, and it is the action's. `ActionJobHandle.invoke` is `invoke(target,
+    // input, { surface: 'job', ctx })`, so the agent's policy, its input parse, its budget scope
+    // and its span all apply — and `ctx` is the WORKER's, so `ctx.signal` aborting at the attempt
+    // timeout reaches the agent's turn loop.
+    run: ({ input, ctx }) => bridge().invoke(asInput<TInput>(input), ctx),
+  });
+}
+
+/**
+ * The job parsed with the action's OWN schema, so what it hands back is a value that schema
+ * accepts — `invoke` re-parses it regardless, which is what makes this safe rather than merely
+ * convenient. The cast exists because `InferOutput` and `InferInput` are different types wherever a
+ * field has a default, and nothing at this seam can prove they meet.
+ */
+function asInput<TInput extends StandardSchemaV1>(value: InferOutput<TInput>): InferInput<TInput> {
+  return value as InferInput<TInput>;
+}