@ultimat3/ai 29.4.0 → 30.1.0

package/CLAUDE.md

@@ -9,13 +9,9 @@ Shipped: `action` (`llm()`), `cache`, `core`, `db` (pgvector), `http` (`statusFo
 Keep `policy` dev-only: tests and `*-fixture.ts` harnesses import `allow`. The
 `!src/**/*-fixture.ts` exclusion keeps harnesses unpublished; their imports still need a declaration.
 
-`mcp` is the same tier, so the LLM-tool projection is restated structurally in `tools.ts`, never
-imported: same contract, same *decision* (`isMcpExposed` from `@ultimat3/core`, never a local
-`=== true`), same NAME (`action.name` verbatim, never derived) and the same TOOL —
-`asProjectableAction` and mcp's `primitiveFromAction` are two copies the tier table forces, held
-equal by `scripts/ai-mcp-tool-parity.test.ts` (name, description, exposure, the whole input schema
-incl. `tool-idempotency.ts`'s reserved `idempotencyKey`, the policy verdict, the replay). A field
-one adds, the other adds.
+`mcp` is the same tier, so the LLM-tool projection is restated in `tools.ts`, never imported —
+`asProjectableAction` and mcp's `primitiveFromAction` held equal by
+`scripts/ai-mcp-tool-parity.test.ts`; a field one adds, the other adds. Full rule: `docs/history/ai.md`.
 
 ## Owns
 
@@ -24,10 +20,12 @@ one adds, the other adds.
 | `models.ts` | the model REGISTRY: `registerModel`, limits, prices, the reasoning controls each one accepts — and NO row of its own |
 | `model-resolve.ts` | `resolveModel` / `modelForCall` — declaration → prompt → gateway `defaultModel`, none is `X_AI_MODEL_UNRESOLVED` naming all three; `describedModel` for a published fact |
 | `model-fixture.ts` | the rows this package's own suites register (`useFixtureModels()`). Not shipped |
-| `provider.ts` | `Provider` interface, the request half, `anthropicProvider()` |
-| `echo-provider.ts` | `echoProvider()`, the deterministic double — split from `provider.ts` at its line ceiling |
+| `provider.ts` | `Provider` interface, the request half; re-exports the Anthropic names |
+| `anthropic-provider.ts` | `anthropicProvider()`, its stream-only rule (`requiresStreaming`) and message parse |
+| `echo-provider.ts` | `echoProvider()`, the deterministic double — split from `provider.ts` at its line ceiling. A fixture that needs a tool call uses `scriptedProvider`, never a hand-rolled `Provider` |
+| `scripted-provider.ts` | `scriptedProvider()`, the scripted double that calls tools, and `X_AI_SCRIPT_EXHAUSTED`: one call past the script is refused, never answered with the last turn again |
 | `content-blocks.ts` | the `image` / `document` block shapes, the screen every request runs them through, their token estimate |
-| `content-errors.ts` | the `X_AI_CONTENT_UNSUPPORTED` class; its code and title belong in `errors.ts` |
+| `content-errors.ts` | the `X_AI_CONTENT_UNSUPPORTED` class; its code and title belong in `error-codes.ts` |
 | `wire.ts` | the response half: `usage` / `stop_reason` shapes, and the SSE `MessageStream` |
 | `error-body.ts` | what a failure body SAYS (`detailOf`) and what must never survive into it (`withoutKey`) — one copy, both transports |
 | `sse.ts` | Server-Sent Events framing — protocol only, knows nothing about Anthropic |
@@ -35,13 +33,16 @@ one adds, the other adds.
 | `openai-messages.ts` | the format mapping's request half: `AiMessage` blocks → OpenAI messages, `LlmTool` → functions, `tool_choice` |
 | `openai-body.ts` | one chat-completions body, and the per-model reasoning mapping |
 | `openai-wire.ts` | its response half: one completion, and `ChatCompletionStream` (fragmented tool calls, trailing usage, `[DONE]`) |
-| `gateway.ts` | routing, retries, cache, budget wiring |
+| `gateway.ts` | routing, cache, budget wiring |
+| `gateway-providers.ts` | the retry loop across providers, `backoffMs`, `isRetryable`, the breakers |
 | `budget.ts` | token ledgers per request/actor/org, ALS carrier |
 | `prompt.ts` | `definePrompt`, `promptHash`, version registry |
 | `prompt-fence.ts` | a template's data fences: which tag pairs enclose each slot (`promptFences`), and the closer-breaking `render` applies inside one |
 | `embeddings.ts` | `Embedder`, `hashEmbedder()`, cosine helpers |
 | `remote-embedder.ts` | `remoteEmbedder()` — the production `/v1/embeddings` client |
 | `evals.ts` | `defineEval`, the run, the baseline gate, prompt coverage |
+| `eval-agent.ts` | the agent arm of `defineEval`: one case is one `agent.run()` in the eval scope; `agentPrompt` reads the prompt off `agentFactsOf` |
+| `eval-agent-fixture.ts` | the agent-arm suites' harness. Not shipped |
 | `eval-baseline.ts` | the recorded scores: path, read/write, what counts as a regression |
 | `scorers.ts` | what a `Scorer` is, the built-in ones, and `llmJudge` |
 | `vector.ts` | `VectorStore`, in-memory cosine + BM25, RRF hybrid |
@@ -51,9 +52,10 @@ one adds, the other adds.
 | `pg-vector.ts` | `postgresVectorStore()` — the production store |
 | `rag.ts` | chunker, retriever, reranker, budgeted context assembler |
 | `tools.ts` | action → LLM tool definition; the `AgentTool` union and `asProjectableAction`; `runLlmToolCall` |
+| `tools-gate.ts` | a tool's way to `run`: actor half, the name's gate, the tool |
 | `tool-idempotency.ts` | an idempotent action's reserved `idempotencyKey` tool argument — MCP's, restated (same tier), held equal by the parity test |
 | `tool-arguments.ts` / `answer-errors.ts` | one argument-string reader for both wires and what an unreadable one means (`assertToolArguments`); `X_LLM_TRUNCATED` + `X_LLM_TOOL_ARGUMENTS_INVALID` |
-| `billed.ts` / `run-meter.ts` | `meta.billed` + `billedOf`; the meter every `llm()`/`agent()` provider call goes through |
+| `billed.ts` / `run-meter.ts` | `meta.billed` + `billedOf`; the meter every `llm()`/`agent()` provider call goes through, and `meteredRun`, its one public total (`RunMeter` stays internal) |
 | `failure-disclosure.ts` | `discloseFailure` — the ONE rule for what of a throw a remote reader sees (tool result, hive member); the withheld half is logged, never its message or cause |
 | `llm.ts` | `llm()` — the model call, declared as an `action`; and what a streamed answer must satisfy |
 | `respond.ts` | the `respond` tool for one `output` (a non-object one wrapped in `{ value }`), its reader, and `parseJsonish` |
@@ -62,22 +64,24 @@ one adds, the other adds.
 | `agent-def.ts` / `agent-declared.ts` / `agent-system.ts` / `agent-usage.ts` | the declaration's types; its defaults, bound screen, limits and fact row; the system one run sends; its running usage |
 | `llm-def.ts` / `cost.ts` | `llm()`'s declaration types and `LlmCall`; the money arithmetic (`costOf`, `exactCostOf`) |
 | `agent-guards.ts` / `agent-errors.ts` | the repeated-turn detector and the run deadline; their two classes |
-| `prompt-cache.ts` | PROVIDER prompt caching: `SystemParts`, `PromptCacheHint`, `PROMPT_CACHE_RULES` (sources in its header) |
+| `prompt-cache.ts` / `-rows.ts` | PROVIDER prompt caching, `PROMPT_CACHE_RULES` (sources in its header); the provider-rows screen |
 | `prompt-cache-blocks.ts` | the Anthropic wire's marks (chat-completions': `openai-messages.ts`) |
 | `agent-per-run.ts` / `agent-run-limits.ts` | one run's `offerTools()`/`model()`/`limits()`, narrow only; `costPerRun` |
-| `agent-compact-def.ts` / `agent-compact.ts` | `compact`'s declaration and event; the trigger, the cut, the summary call |
+| `agent-compact{,-def,-measure,-request,-text}.ts` | trigger, cut; `compact`'s option and event; the token ratio; the summary request, as text when too long |
+| `agent-send.ts` / `context-overflow.ts` / `agent-checkpoint.ts` | a turn sent, an overflow compacted once; `X_AI_CONTEXT_OVERFLOW`'s phrases; `onCheckpoint` |
 | `agent-continue.ts` / `agent-turn.ts` | `.run()` / `.continue()`, the transcript handle and its screen; one turn's report and refusals |
 | `agent-transcript.ts` | what one turn leaves in the transcript: the assistant replay, the tool results, the correction |
 | `agent-facts.ts` | `describeAgents()` — the agent registry, and the row a manifest WOULD publish (its consumer has to be `cli`, tier 5) |
 | `agent-job.ts` | `agentJob()` — an agent as a real `JobHandle`, composed from `job()` |
 | `hive.ts` | `hive()` — one action fanned out over many inputs, declared as an `action` |
 | `hive-result.ts` | `HiveMember` / `HiveResult`, and the SCHEMA built from the member's own `output` |
-| `hive-errors.ts` | the `X_HIVE_*` class; its code and title stay in `errors.ts` |
+| `hive-errors.ts` | the `X_HIVE_*` class; its code and title stay in `error-codes.ts` |
 | `redaction.ts` | the one gate between `vars()` and the provider: a `Secret` never reaches a prompt |
-| `eval-errors.ts` | the five `X_EVAL_*` classes; their codes and titles stay in `errors.ts` |
+| `eval-errors.ts` | the six `X_EVAL_*` classes; their codes and titles stay in `error-codes.ts` |
+| `error-codes.ts` | the codes this package owns, their titles and the one `registerErrorCodes` call (`new-error-code --package ai` writes here); `errors.ts` holds the core classes |
 | `llm-cache.ts` | the semantic cache half of `llm()`: what a declaration may partition on, and the store it reaches |
 | `llm-fixture.ts` / `bounds-fixture.ts` | the `llm()` harness; the one `refusal`/`asyncRefusal` of every bound suite. Not shipped (`!src/**/*-fixture.ts`) |
-| `runtime.ts` | the ambient gateway / embedder / semantic caches an `llm()` reaches |
+| `runtime.ts` | the ambient gateway / embedder / semantic caches an `llm()` reaches, and the private agent-eval scope (`withEvalScope`): `aiGateway`/`installedGateway` read its gateway first; `runLlmToolCall` resolves its doubles |
 | `fix-line*` | the package's dogfood eval — proof the baseline convention fails a build |
 
 ## Invariants — bounds and budget
@@ -124,6 +128,9 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 - **`llm()` forwards `ctx.signal`** onto `GenerateRequest`; `.stream()` inherits it.
 - **`.stream()` is the SAME action**, marked with an ambient sink: UNVALIDATED text, then one `done`
   with the validated value; no repair turn (`X_LLM_STREAM_INVALID`), no `respond` tool. LAZY.
+- **`llm()` streams over its own route** (`stream: LlmTextChunk`, exported): `text/event-stream`
+  gets `{ type: 'text' }` frames, then `done`; `thinking` NEVER crosses the wire. Drained
+  (`chunksRead()` false: JSON, MCP, `.job()`) it is the ordinary call, repair turn included.
 - **`configureAi({ redact })` is the one seam between `vars()` and the provider**; a `Secret` in
   `vars()` is `X_AI_PROMPT_SECRET` regardless.
 - **Fallback is across PROVIDERS serving one model, never across models**; `GenerateResult.provider`
@@ -147,14 +154,16 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 - **The gateway's reads of a provider's throw are total**: `isRetryable` fails closed; the line goes
   through `renderThrowable`.
 - **`X_AI_PROVIDER_UNAVAILABLE` is the one code classified `retryable`** (`AI_ERROR_RETRY`);
-  `AiProviderUnavailableError({ unserved: true })` carries a per-instance `terminal`. Six
+  `AiProviderUnavailableError({ unserved: true })` carries a per-instance `terminal`. Nine
   deterministic failures are `terminal` (`errors-retry.ts`); the rest stay UNREGISTERED on purpose.
+- **One breaker per provider** (`gateway-providers.ts`, `DEFAULT_GATEWAY_BREAKER` `{ failures: 5,
+  cooldownMs: 30_000 }`, `breaker: 'off'` declines). Every settle carries the `admit()`
+  ticket. Full rule: `docs/history/ai.md`.
 - **The retry SCHEDULE is core's (`backoffDelay`, `isRetryableStatus`); the LOOP is this package's** —
   core's `retry()` retries unclassified throws, so it would retry a 400 (`gateway-backoff.test.ts`).
-- Every non-2xx and every in-band `error` frame is `AiTransportError` with a real `status`.
-- **Both wire formats answer the same question the same way** (`provider-parity.test.ts`): an in-band
-  `error` in a 200 throws (`throwInBandError`); a `refusal` detail forces `stopReason: 'refusal'`; a
-  tool call's `input` is parsed (`parseToolArguments`); the credential is scrubbed from `detail`.
+- Every non-2xx and in-band `error` frame is `AiTransportError` with a real `status` — but a
+  window overflow (`providerFailure`).
+- **Both wire formats answer the same question the same way** (`provider-parity.test.ts`). Full rule: `docs/history/ai.md`.
 - **Arguments that are not JSON are never thrown by a wire reader**: recorded as `malformed`, and
   the PROVIDER decides once usage is known — dropped on a truncated turn, else
   `X_LLM_TOOL_ARGUMENTS_INVALID` with `meta.billed`, which the gateway RECORDS (`settleFailure`).
@@ -165,46 +174,25 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 - A tool call is emitted whole. Thinking chunks are never appended to `text`.
 - Anthropic body: no `top_p`/`top_k`, no `budget_tokens`, `effort` inside `output_config`. Model
   IDs are exact aliases, never date-suffixed.
-- **`temperature`/`seed` (`sampling.ts`) are sent ONLY to a row with `sampling: { … : true }`** —
-  else left out (never refused; `llm.sampling.ignored`); no `seed` on the Anthropic wire; in
-  `promptCacheKey` only when set.
-- **Apps bring their own models and providers (M12, 25.0.0): no vendor choice, no vendor data.** The
-  registry starts EMPTY; a model resolves declaration → prompt → `Gateway.defaultModel`
-  (`resolveModel` / `modelForCall`), none is `X_AI_MODEL_UNRESOLVED` (no gateway at all:
-  `X_AI_GATEWAY_MISSING`). `vendor-neutral.test.ts` proves it; no fix line names a vendor id.
+- **`temperature`/`seed` (`sampling.ts`) are sent ONLY to a row with `sampling: { … : true }`**, else
+  left out, never refused. Full rule: `docs/history/ai.md`.
+- **Apps bring their own models and providers: no vendor choice, no vendor data.** The registry
+  starts EMPTY (`vendor-neutral.test.ts`); resolution is `model-resolve.ts`'s. Full rule: `docs/history/ai.md`.
 - **`ModelId` is `string`; the catalogue is an open registry** — `modelSpec(id)` refuses an
-  unregistered id (`X_AI_MODEL_UNKNOWN`) before a socket or a reservation. Re-registering REPLACES
-  the spec and keeps its rung; registration order is the ladder within a `family`
-  (`moreCapableThan`); `X_LLM_REFUSED`'s fix names a rung ABOVE or nothing.
+  unregistered id (`X_AI_MODEL_UNKNOWN`) before a socket or a reservation. Full rule: `docs/history/ai.md`.
 - **Every provider serves the app's list** (`{ models }` required, non-empty); no provider has a
   model of its own.
 - **The reasoning controls are PER MODEL (`models.ts`)**: an unasked control is omitted; an asked
-  control the model lacks is `X_AI_REQUEST_INVALID`, never dropped. Adding a model is a row the app
-  registers. `disableThinkingUpTo: 'never'` refuses `thinking: 'disabled'` at every effort;
-  `disabledThinking: 'between_tools'` is the wire spelling of the same declaration
-  (`model-rules.test.ts`, over the fixture rows).
-- **Media blocks are screened once, by `assertMediaContent`, at the top of BOTH body builders** —
-  malformed is `X_AI_REQUEST_INVALID`, untakeable (role, the row's `input`, the wire) is
-  `X_AI_CONTENT_UNSUPPORTED`; never dropped, never approximated (`provider-parity-content.test.ts`).
+  control the model lacks is `X_AI_REQUEST_INVALID`, never dropped. Full rule: `docs/history/ai.md`.
+- **Media blocks are screened once, by `assertMediaContent`, at the top of BOTH body builders**;
+  never dropped, never approximated. Full rule: `docs/history/ai.md`.
 - `generate()` above `STREAM_ONLY_MAX_TOKENS` runs the streaming transport.
 - **Every provider and embedder is built by its factory** (`anthropicProvider()`, `echoProvider()`,
   `hashEmbedder()`, `remoteEmbedder()`); the classes are type exports only (`bun run factory-names`).
 - **`openAiProvider()` is a FORMAT, not a vendor** — `baseUrl`, `auth`, `headers` are the
-  differences; never a second class per vendor:
-  - structured output is the `respond` tool, never `response_format`; `tool_choice` names the tool
-    only when the request offers exactly one and the row is not `forcedToolChoice: false`;
-  - `strict: true` only when `satisfiesStrictMode` says the schema qualifies;
-  - `max_completion_tokens`; `role: 'system'`; `stream_options: { include_usage: true }` and an
-    ESTIMATE when usage never arrives; subtract `cached_tokens` from `prompt_tokens`;
-  - tool-call deltas merge by `tool_calls[].index`, a differing `id` starting a new call; calls are
-    read at `end()` (`[DONE]` or socket close), never at the finish reason; `isComplete()` accepts
-    `[DONE]` or a finish reason, except `[DONE]` with pending tool fragments, which is refused;
-  - no code of its own (a media refusal is the shared `X_AI_CONTENT_UNSUPPORTED`);
-    `AiTransportError` takes the provider's `envVar`; the key is revealed late,
-    never stored, scrubbed from `detail`.
+  differences; never a second class per vendor. Wire rules: [history](../../docs/history/ai.md#openaiprovider-wire-rules).
 - **`embedBatched` enforces the `Embedder` arity per batch** (`X_AI_EMBEDDER_INVALID` with both
-  counts). One `remoteEmbedder()` for every vendor; vectors L2-normalised; a wrong width is
-  `X_VECTOR_DIM_MISMATCH`.
+  counts). Full rule: `docs/history/ai.md`.
 - **A caught value is read with `renderThrowable`** (`remote-embedder.ts`, `wire.ts`,
   `openai-wire.ts`) — `scripts/error-render.ts` cannot see `catch` bindings.
 - **A caller's string is never an object KEY**: the wire tables are `Map`s; `prompt.render` and
@@ -225,60 +213,43 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
   - `ctx.signal` is read at the top of every turn, before every tool batch, and forwarded to
     `fetch`; `X_ABORTED` is core's.
   - One turn's tools run concurrently, results paired by index; no tool STARTS after an abort.
+  - **`mcpConfirmations({ tools })` holds a tool here**, one pass each however it arrives
+    (`tools-gate.ts`). Proof: `scripts/ai-tool-confirmation.test.ts`.
   - `onTurn` reports facts only (also an `agent.turn` span event); a throw from it fails the run.
-    `.stream()` on `agent()` is deliberately not shipped. No semantic cache.
+    Streams per turn on its route (`stream: AgentChunk`). No semantic cache.
   - Every replayed `tool_use` is answered by a `tool_result` in the very next message
     (`agent-transcript.ts`); an unaccepted `respond` comes back as an `is_error` `tool_result`
     ("superseded").
   - A tool result is rendered totally (`'null'` for `undefined`; a non-JSON result reported as such,
     never as a failure); the throw is read with `stringField`.
-  - **A 5xx code's cause reaches the model only when core's `hasPublicCause` allows it** (status from
-    `@ultimat3/http`'s `statusFor`) — else `CODE: HIDDEN_TOOL_CAUSE`, plus a branded `callerFix`. The
-    same verdict a problem document and `@ultimat3/mcp` give, from `failure-disclosure.ts` — the
-    rule a hive member's `reason` follows too. Never a second copy. One widening, for an
-    `inProcess` tool only (`discloseOwnFailure`): a branded error under a code with NO declared
-    status is shown as `{ error: { code, cause, fix } }`; `discloseErrors: false` opts out.
+  - **A 5xx code's cause reaches the model only when core's `hasPublicCause` allows it**, else
+    `CODE: HIDDEN_TOOL_CAUSE` plus a branded `callerFix` (`failure-disclosure.ts`, never a second
+    copy). Full rule: `docs/history/ai.md`.
 - **A run only NARROWS its declaration**: `offerTools()` ⊆ declared names (`X_AGENT_TOOL_UNDECLARED`),
   `model()` via `modelSpec`, `limits()` screened and ≤ declared (`X_AI_REQUEST_INVALID`); all
   before `vars()`. The handle binds the run's model and OFFERED subset; `costPerRun` is checked per turn.
 - **`.run()`/`.continue()` are the SAME action**, marked by an ambient session only the declaring
-  agent may claim, once (a nested agent starts fresh). The handle is SIGNED (`sealTranscript`: the
-  cursor secret, own label) and bound to agent, model, tool names and `orgId`; screened before
-  anything is loaded. `maxTurns`/`tokensPerRun` are cumulative — the remainder is the ceiling,
-  NEVER a ledger debit. A failure seals an updated handle onto the error (`transcriptOf`).
-- **`compact` (default `'auto'`) acts BEFORE a turn, never after a 400**: the summary call is the
-  run's own request up to a cut BETWEEN turns (the cached prefix, same session), billed, not a turn;
-  system, tools, kept turns byte-identical; failed → whole, or `X_AGENT_CONTEXT_EXHAUSTED`, never
-  truncated ([why](../../docs/history/ai.md#auto-compaction-2026-10)).
+  agent may claim, once (a nested agent starts fresh). The handle is SIGNED (`sealTranscript`)
+  and bound to agent, model, tool names and `orgId`. Full rule: `docs/history/ai.md`.
+- **`compact` (default `'auto'`) acts BEFORE a turn on the MEASURED estimate; an overflow gets one
+  forced compaction and a re-send**;
+  never truncated (`X_AGENT_CONTEXT_EXHAUSTED`). Full rule: `docs/history/ai.md`.
+- **A summary request too long for its writer goes as TEXT** (`agent-compact-request.ts`,
+  `agent-compact-text.ts`): oldest tool results clipped to `SUMMARY_CLIP_CHARS` (2,000, head +
+  tail), then left out; a turn is never dropped. Reported on `AgentCompaction`: `summaryInput`
+  (`'messages' | 'text'`), `clipped`, `omitted`.
 - **`hive()` is a fan-out action** (`PRIMITIVE_FACTORIES`): `HiveResult` is a SCHEMA from the
-  member's `output`; three arms (`ok`/`failed`/`skipped`) and three counters; `members` in SPLIT
-  order with `index`; the hive never names an actor; no hive budget code; a member's throw goes
-  through `discloseFailure` (`HIDDEN_MEMBER_CAUSE`);
-  `skipped` reasons `SKIPPED_ABORTED` / `SKIPPED_NO_INPUT`; `onMemberError` is required;
-  `concurrency` 4, `minMembers` 2 (a below-floor split runs serially); an empty split is
-  `X_HIVE_EMPTY`; an aborted `ctx` is `X_ABORTED`.
+  member's `output`; a member's throw goes through `discloseFailure`; the hive never names an actor.
+  Full rule: `docs/history/ai.md`.
 - **`describeAgents()` / `registeredModels()` are offered, not published** — their only legal consumer
   is `@ultimat3/cli`. The facts are a THUNK; an unnamed agent has no row.
 - **`agentJob()` composes `job()`** (never an imitation). `name`, `tenant`, `retry` are
-  REQUIRED; both reads of `target.job()` are LAZY. No result is kept: wrap an ACTION that runs the
-  agent and writes, target bound from its input — never a model-aimed write tool; every write
-  idempotent (unenforceable). **`actor`** re-resolves who it acts FOR each attempt (a served worker:
-  ANONYMOUS) via `impersonate`; off-tenant is TERMINAL `X_JOB_TENANT_MISMATCH`.
+  REQUIRED; both reads of `target.job()` are LAZY. No result is kept; `actor` re-resolves
+  each attempt via `impersonate` (off-tenant: `X_JOB_TENANT_MISMATCH`). Full rule: `docs/history/ai.md`.
 
 ## Invariants — provider prompt caching
 
-- **`GenerateRequest.promptCache` is the one switch; what it sends is a ROW in `PROMPT_CACHE_RULES`**
-  (wire, host, model prefix → marks, session carrier), never an `if`. An unnamed endpoint gets
-  NOTHING. At most 3 `cache_control`, a caller's own counted first (cap 4), never on a blank text
-  block; never a `provider` routing object.
-- **`agent()` defaults `'auto'`, `llm()` `'off'`.** The stable system part (`prompt.system` +
-  `system().stable`) is sent FIRST; the mark follows the tail. The hint is not in `promptCacheKey`.
-- **Usage**: chat-completions `prompt_tokens` INCLUDES read and written tokens; both are subtracted,
-  clamped. A budget debits all four counters; the estimate prices a WRITE only where a provider
-  would mark (`marksPromptCache`), at the dearer rate.
-- **`maxRepeatedToolCalls` compares calls AND results over cycles of 1–3 turns**; `deadlineMs` has no
-  default and rides the request's AND each tool's signal; both stops are `terminal`
-  (`errors-retry.ts`).
+One switch (`GenerateRequest.promptCache`), `promptCacheRule`: provider rows, then `PROMPT_CACHE_RULES`, then nothing. An app's own endpoint is a row ON ITS PROVIDER (`promptCache: { rules }`, `ProviderCacheRow`, first match wins), screened at construction against the wire (`prompt-cache-rows.ts`, `X_AI_REQUEST_INVALID`); `agent()` defaults `'auto'`, `llm()` `'off'`. In full: [`docs/history/ai.md`](../../docs/history/ai.md#moved-out-2026-11-03-plan-101-wave-3-the-claudemd-ceiling).
 
 ## Invariants — evals, retrieval, fix lines
 
@@ -287,6 +258,8 @@ In brief ([full text](../../docs/history/ai.md#evals-retrieval-fix-lines)): no f
 retrieval is hybrid only; an unbound store read under an org actor is `X_VECTOR_UNSCOPED`;
 `postgresVectorStore()` filters tenant and policy in SQL on every statement; `scoped()` TIGHTENS.
 
+- **An eval never runs a real tool**: no double is `X_EVAL_TOOL_UNDOUBLED` (history, 2026-11-06).
+
 ## Commands
 
 ```

package/README.md

@@ -3,6 +3,8 @@
 The LLM gateway primitive. Every model call in an Ultimate app goes through it, so budgets
 and cost accounting cannot be bypassed by a stray `fetch`.
 
+`bun add @ultimat3/ai` · guide: [MCP And AI](https://github.com/developerz-ai/ultimate/wiki/MCP-And-AI)
+
 **Register your models, pick your provider.** The framework ships the mechanism — the `Provider`
 contract, two wire-format adapters, the gateway, budgets, `registerModel` — and no vendor choice
 and no vendor data: no default model, no catalogue row, no price. Which models an app runs, at what
@@ -71,6 +73,7 @@ provider whose `models` lists it.
 | `X_LLM_REFUSED`'s "a more capable model" | a rung above, in the same `family`, among the rows the APP registered — or no suggestion at all |
 | a direct provider call naming no model | `X_AI_MODEL_UNRESOLVED` from every shipped provider — `anthropicProvider()`, `openAiProvider()` and `echoProvider()` alike; a provider's `models` list is what it serves, never a fallback |
 | `echoProvider()` | serves whatever the app registered, and has no model of its own |
+| `scriptedProvider({ turns, usage?, name? })` | the test double that calls tools: each provider call answers the next turn — `{ text }`, `{ call, input? }`, `{ calls: [...] }` or `{ answer }` (a `respond` call), each with an optional `stop` — and `.seen` keeps every request. Serves whatever the app registered. One call past the last turn is `X_AI_SCRIPT_EXHAUSTED`, never the last turn again: a loop must not look like a pass |
 
 ## Budgets — and which of the three is fleet-wide
 
@@ -150,7 +153,9 @@ default store at `replicas: 6` is six ledgers of twenty million, which is a budg
 | `reserve()` **debits, then checks** | the in-memory scopes check and debit with no `await` between, the store's through its atomic `take`; a read-then-write let concurrent calls — one request per scope racing one org key — all read the same `spent()` and all pass. `record` reconciles and `release` gives it back |
 | The cache key is every tool **whole**, through core's `fingerprint` | every `llm()` tool is named `respond`, so a key over names served an answer shaped for an old `output` schema; a cache `set` that throws is logged, never turned into a failure of a call already paid for |
 | A refusal is never cached | a cached one keeps serving a classifier decision after the prompt was fixed |
+| A cache hit reads zero `usage`, `cost` and `costExact`, in the same currency | it is not debited, so a meter summing the stored figures read more than the budget beside it |
 | Retries use **full jitter**, from core's one curve | synchronised retries from N workers reproduce the rate limit. `backoffMs` is `@ultimat3/core`'s `backoffDelay` with the gateway's field names mapped onto it, and the roll is `providerGateway({ random })` — injectable, so the schedule is a unit test rather than a range |
+| **One breaker per provider**, on by default: `{ failures: 5, cooldownMs: 30_000 }` (`DEFAULT_GATEWAY_BREAKER`) | a provider that ran out its retries five passes in a row is skipped, no call and no sleep, until one probe after the cooldown answers; without it every call re-spent every attempt on a dead provider. `providerGateway({ breaker })` takes `GatewayBreakerOption`, `((provider) => Breaker) \| 'off'`: your own core `breaker({ … })` per provider, or `'off'` for the old behaviour. A stream goes to the first provider whose breaker admits it |
 | A 4xx is never retried **except 408, 409 and 425** | the same body gets the same rejection and burns the budget — but a request the server stopped reading (408), a round a concurrent writer won (409) and a handshake that had not finished (425) are transient by construction, and core's `isRetryableStatus` is the one table that says so |
 
 ## Streaming
@@ -401,6 +406,16 @@ invocation is an ordinary one, marked so the model half streams. Two consequence
 | 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 |
 
+### Streaming on the wire
+
+`llm()` declares `stream: LlmTextChunk` (`{ type: 'text', text }`), so its own route answers
+`text/event-stream` to the typed client's `summarize.stream(input)`: each text increment as the
+provider sends it, then `done` with the value that satisfied `output`. Same policy, budget, cache
+and span; the streamed turn is the one-attempt turn server-side `.stream()` takes. `thinking` never
+crosses the wire. Every other caller (JSON, MCP, `.job()`) gets the non-streamed call, repair turn
+included. `agent()` declares `stream: AgentChunk` the same way: per turn, `text`, `tool_call`,
+`tool_result` and `turn` facts, then `done`.
+
 ## `agent()` — the tool loop, also an action
 
 The second half of "no ninth primitive": a tool-using run is still one server-authoritative
@@ -436,6 +451,7 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 | 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 is an `mcp: { expose: true }` action or an `inProcessTool()`; anything else is `X_AGENT_TOOL_UNEXPOSED` **at declaration** | a silently dropped tool reads as offered and is not; `isMcpExposed` is the one predicate for ACTIONS, so an in-app agent and an external MCP client see the same catalogue of them — and a tool no MCP client may see is declared as one that is this process's alone |
+| a tool in `mcpConfirmations({ tools })` answers `X_MCP_CONFIRMATION_PENDING` until a person approves | one list for both surfaces, so no option an author can forget. The decision action declares no `mcp.expose`, so listing it is `X_AGENT_TOOL_UNEXPOSED`: **exposing it hands an in-app agent, whose actor is the user, its own approval** |
 | 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 |
 | a cycle of 1 to 3 tool turns — same calls, arguments, results and failures — gone round `maxRepeatedToolCalls` (default 3) times is `X_AGENT_TOOL_LOOP` | such a turn can only be followed by another like it; a changed result is progress; a repair turn neither counts nor resets |
 | `deadlineMs` (no default) is the run's wall-clock ceiling: `X_AGENT_DEADLINE` | the in-flight model call is aborted on the socket and every tool's `ctx.signal` fires; a tool that ignores it still finishes late. A caller that leaves first is still `X_ABORTED` |
@@ -452,10 +468,48 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 
 `cost` is the currency's minor units, rounded up once per call; `costExact` beside it is the same figure exactly (`Money` at a finer `scale`, from `exactCostOf`). `agent()` reports both per turn and for the run in `onTurn`; `llm()` per provider call in `onCall`; a ledger sums exact costs and rounds once when read. `repairOf` on either event is what a repair turn was told to fix.
 
+One total across several calls — a job that runs two `llm()` calls and an `agent()` — is
+`meteredRun(fn)` → `{ value, billed }`: every provider call `fn` makes, however deeply nested, summed
+once (`Billed`, `undefined` when none started). A throw is rethrown with that total on `meta.billed`,
+so `billedOf(error)` reads it. A meter, not a ledger: it refuses nothing.
+
 ### Continuing a run
 
 `agent()` returns an `AgentAction`: the action, plus `.run(input, opts)` → `{ output, transcript, turns, usage }` and `.continue(input, { transcript, user }, opts)`, which appends one user turn to a stored transcript and resumes the loop. The transcript is re-sent byte for byte (the provider's prompt cache reads it back; no tool re-runs); `maxTurns` and `budget.tokensPerRun` are cumulative; the handle is signed, bound to the agent, model, tools and tenant, and screened (`X_AGENT_TRANSCRIPT_INVALID`); a failed call leaves an updated one on the error (`transcriptOf(error)`), which is the one a job stores. Full contract: [Agents → Continuing a run](https://github.com/developerz-ai/ultimate/wiki/Agents#continuing-a-run-run--continue).
 
+`onCheckpoint(event, { input, ctx })` hands the app the same signed handle **between** turns — after a
+turn's tool results (or its correction) land, before the next turn is bought, never after the answer
+(`.run()` returns that one). Store `event.transcript` on the run's own row; the next attempt calls
+`.continue(input, { transcript, user })` and pays only for the turns left. Awaited; a throw fails
+the run; sealed only when declared. A worker dying DURING a tool batch re-asks that turn, so its
+tools may run again — at-least-once still binds.
+
+```ts
+import type { AgentAction, AgentTranscript } from '@ultimat3/ai';
+import type { Ctx } from '@ultimat3/core';
+import { stringField } from '@ultimat3/core';
+import type { t } from '@ultimat3/schema';
+
+type Review = ReturnType<typeof t.object<{ verdict: typeof t.string }>>;
+type In = ReturnType<typeof t.object<{ postId: typeof t.string }>>;
+// Declared with onCheckpoint: ({ transcript }, { input }) => saveProgress(input.postId, transcript)
+declare const reviewer: AgentAction<In, Review>;
+declare function progress(postId: string): Promise<AgentTranscript | undefined>;
+
+// The action an agentJob() runs: resume from the stored handle, else start.
+export async function review(ctx: Ctx, input: { postId: string }) {
+  const stored = await progress(input.postId);
+  try {
+    if (stored === undefined) return await reviewer.run(input, { ctx });
+    return await reviewer.continue(input, { transcript: stored, user: 'Carry on.' }, { ctx });
+  } catch (error) {
+    // A prompt bump or a model change invalidates a stored handle by design: start fresh.
+    if (stringField(error, 'code') !== 'X_AGENT_TRANSCRIPT_INVALID') throw error;
+    return reviewer.run(input, { ctx });
+  }
+}
+```
+
 ### Auto-compaction
 
 ```ts
@@ -480,15 +534,17 @@ export const researcher = agent({
 });
 ```
 
-Before each turn, the gateway's estimate of that turn's request is compared with the model row's
-`contextWindow` less `maxTokens`. Over `at` of it, ONE model call summarises every turn older than
+Before each turn, the gateway's estimate of that turn's request — scaled by what the provider
+reported for the last one — is compared with the model row's `contextWindow` less `maxTokens`. Over `at` of it, ONE model call summarises every turn older than
 the last `keepTurns`; the summary joins the first user message (after the prompt, verbatim, marked
 `[compacted: …]`), the kept turns follow byte for byte, and the turn is sent.
 
 | Rule | Why |
 |---|---|
 | default **`'auto'`**; `'off'` never compacts and never checks | a summary changes what the model sees, but only above `at` of the window, where the alternative is a run lost to a 400 after every turn was paid for. Below it a run is byte-identical to `'off'` — requests and handle — and it is never silent: `onCompact`, the `agent.compact` span event, the handle's `compacted` |
-| triggered on the **estimate of the next request** — the gateway's prompt estimate plus the tool definitions — over `at` × (`contextWindow` − `maxTokens`), before the call | after a 400 there is no request left to fix; `maxTokens` is reserved because the completion shares the window |
+| triggered on the **estimate of the next request** — the gateway's prompt estimate plus the tool definitions — over `at` × (`contextWindow` − `maxTokens`), before the call | `maxTokens` is reserved because the completion shares the window |
+| the estimate is **scaled by the measurement**: after each turn, `max(1, (inputTokens + cacheReadTokens + cacheWriteTokens) / estimate)` of that turn's request; `before`/`after` report the scaled figure | four characters a token is wrong by 3x on dense JSON and non-Latin text, and a run walked past the window it was meant to compact before. A turn reporting zero keeps the last ratio (a provider that never reports compacts where it always did); below 1 is ignored; per run, never signed — a continuation's first turn estimates plainly |
+| a provider that refuses the turn anyway (**`X_AI_CONTEXT_OVERFLOW`**) gets **one forced compaction** and the same turn re-sent; a second refusal, a compaction that cannot be had, or `compact: 'off'` is `X_AGENT_CONTEXT_EXHAUSTED` with the provider's text on `meta.refused` | the loop still holds the transcript after that 400. The refusal billed nothing (`meta.billed` at zero), is not a turn, and is never retried by the gateway: the same request overflows on every provider |
 | the system prompt, its stable block and the tools are **never touched** | a provider cache is a prefix match over tools → system → messages: they are the part every turn and every run shares, so they are still read at the cache rate after a compaction. Only the messages are rewritten, once |
 | the summary call is the run's **own request** up to the cut, plus one instruction — same gateway, tools, system and `promptCache` hint | it reads the prefix the turn that ended at the cut already cached instead of paying for it again; on OpenRouter the same `x-session-id` routes it to the provider holding that cache (`compact.model` trades that read for a cheaper writer) |
 | the cut falls **between turns**: the prompt and the last `keepTurns` (4, at least 1) turns are verbatim | a turn is an assistant message and the user message answering every `tool_use` in it, so no call is ever separated from its result (a 400 on every provider); the model keeps its task as written and the results it just asked for |
@@ -501,7 +557,8 @@ the last `keepTurns`; the summary joins the first user message (after the prompt
 
 | Limit | Detail |
 |---|---|
-| the estimate | ~4 characters a token, which is why `at` defaults below 1 |
+| the estimate | ~4 characters a token until the first turn reports, which is why `at` defaults below 1 |
+| the forced compaction | its summary call is the refused request less the kept turns: with a tiny `keepTurns` it may not fit either — `compact.model` with a larger window is the way out |
 | `tools: []` on the chat-completions wire | only `respond` is offered, so it is forced, the summary call answers no text and the run falls back to whole |
 | per run | `compact` is the declaration's; `limits()` does not take it, `describeAgents()` does not publish it |
 
@@ -555,6 +612,15 @@ export const kbAgent = agent({
 | chat completions | `api.openai.com` | any | none (automatic) | `prompt_cache_key` |
 | chat completions | anything else | any | none | — |
 
+An endpoint the table does not know is the app's to declare, on its provider:
+`openAiProvider({ baseUrl, models, promptCache: { rules: [{ model: 'anthropic/', marks: 'parts', session: 'x-session-id' }] } })`
+marks for a company gateway; `anthropicProvider({ baseUrl, models, promptCache: { rules: [{ model: '', marks: 'none', session: 'none' }] } })`
+stops marks to a proxy that rejects `cache_control`. A row (`ProviderCacheRow`) is `{ model, marks,
+session }`, read before the table, first match by model prefix; the pre-flight estimate follows it.
+The Messages wire speaks `blocks` or `none` and no session; chat-completions `parts` or `none`, and
+`x-session-id`, `prompt_cache_key` or `none`. Anything else is `X_AI_REQUEST_INVALID` when the
+provider is built.
+
 Usage: the chat-completions reader takes `prompt_tokens_details.cached_tokens` and
 `.cache_write_tokens` out of `prompt_tokens` (which includes both) and reports them as
 `cacheReadTokens` / `cacheWriteTokens`; a missing field is zero. `costOf` prices them at the model
@@ -567,7 +633,7 @@ ever sent.
 | Limit | Detail |
 |---|---|
 | `run.cost` and the ledger | one contract: cost is computed exactly and rounded up once. `AgentTurn.run.cost` is the run's summed usage priced once; `gateway.spent()` / `BudgetLedger.report().cost` is the exact cost of every recorded call summed, rounded once when read (`costExact` beside it). They agree for a run on built-in providers; a `Provider` that states no `costExact` is summed from its rounded `cost`. Budgets are enforced against the ledger |
-| the Anthropic row matches any host | an `anthropicProvider({ baseUrl })` behind a proxy still sends marks |
+| the Anthropic row matches any host | an `anthropicProvider({ baseUrl })` behind a proxy still sends marks, unless it declares a `marks: 'none'` row |
 | more than about 9 tool calls in one turn, on OpenRouter | only the tail is marked there and the provider looks back 20 blocks, so that turn's transcript is rewritten, not read |
 | a mark never lands on an empty or whitespace-only text block, and never makes a fifth | it moves back a block or is dropped; a raw caller's own marks are counted first |
 | `session` | OpenRouter header: 1 to 256 printable ASCII, else `X_AI_REQUEST_INVALID`. OpenAI `prompt_cache_key`: over 64 characters it is sent as `h:` + 62 hex of its SHA-256 |
@@ -854,7 +920,46 @@ X_EVAL_THRESHOLD: an eval scored below its tolerance
 
 Built-in scorers: `exact`, `contains`, `jsonValid`, `jsonSchemaValid(keys)`,
 `numericTolerance(t)`, `llmJudge({ judge })` — the judge prompt is itself versioned, so a
-judge that drifts is a measuring instrument that lies, and its hash is in the scorer name.
+judge that drifts is a measuring instrument that lies, and its hash is in the scorer name —
+and `calledTool(name)`, 1 when an agent run called that tool.
+
+### The agent arm
+
+`DefineEvalInput` is a union: `PromptEvalInput` (`prompt` + `cases[].vars`) or `AgentEvalInput`
+(`agent` + `cases[].input` + `tools`). Narrow with `'prompt' in input`. The agent arm runs
+`agent.run(input, { actor })` per case — default actor `serviceActor({ id: 'eval' })` — with the
+gateway handed to `run` / `assert` and every tool answered by its double in `tools`:
+
+```ts
+import {
+  calledTool,
+  defineEval,
+  type EvaluatedAgent,
+  providerGateway,
+  type ScriptedTurn,
+  scriptedProvider,
+} from '@ultimat3/ai';
+
+declare const supportAgent: EvaluatedAgent<{ question: string }>; // your registered agent()
+declare const turns: ScriptedTurn[];
+
+const supportEval = defineEval({
+  name: 'support.answer',
+  agent: supportAgent,
+  cases: [{ name: 'where-is-o-1', input: { question: 'Where is o-1?' } }],
+  tools: { lookupOrder: () => ({ status: 'shipped' }) },
+  scorers: [calledTool('lookupOrder')],
+  baseline: import.meta.resolve('./support.baseline.json'),
+  tolerance: 0.05,
+});
+await supportEval.assert(providerGateway({ providers: [scriptedProvider({ turns })] }));
+```
+
+An undoubled call is `X_EVAL_TOOL_UNDOUBLED` (`EvalToolUndoubledError`) and ends the eval: an eval
+never runs a real tool. Any other failed run scores 0 and records its code in `cases[].failed`.
+Scorers get `run: { turns, toolCalls, usage }` (`EvalRun`, `EvalToolCall`, `ScorerInput`); the
+baseline is the same file, keyed by the agent's prompt hash. Exported types: `AgentEvalCase`,
+`AgentEvalInput`, `EvaluatedAgent`, `PromptEvalInput`, `ToolDouble`.
 
 ## Prompts are versioned artifacts
 
@@ -987,9 +1092,19 @@ An in-app agent and an external MCP agent both end at the same `invoke` — `run
 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.
 
+A tool in `mcpConfirmations({ tools })` waits for a person here too. `run` asks the policy's actor
+half, then the gate registered for that name (read per call), then `invoke`; `asProjectableAction`
+puts a hand-built tool behind the same gate, and `runLlmToolCall` projects whatever it is handed, so
+it is one pass whichever way a tool arrives. The model reads `X_MCP_CONFIRMATION_PENDING`, reports
+through `output`, and a later user turn repeats the call. No new run outcome. The gate binds a tool's
+**name**, never what it reaches: `inProcessTool({ name: 'refundNow', execute: () => invoke(refundOrder, …) })`
+is not gated by `refundOrder`'s row, so list `refundNow` in `tools`.
+[Agents → A tool that waits for a person](https://github.com/developerz-ai/ultimate/wiki/Agents#a-tool-that-waits-for-a-person).
+
 `inProcessTool({ name, description, input, execute })` is a tool that is this process's alone: no `mcp`, no policy of its own (the agent's decides), in no catalogue but the agent's. Its own typed refusal reads back as `{"error":{"code","cause","fix"}}`. [Agents → In-process tools](https://github.com/developerz-ai/ultimate/wiki/Agents#in-process-tools).
 
-A failed tool reads back as `CODE: cause (fix: …)` — except a 5xx code whose cause core's
+A failed tool reads back as `CODE: cause (fix: …)`, the fix being the error's `callerFix` when it
+declares one — except a 5xx code whose cause core's
 `hasPublicCause` does not declare public, which reads `CODE: ` plus a fixed sentence (and a
 `callerFix`, when the `UltimateError` declared one): the rule a production problem document follows,
 and the one `@ultimat3/mcp` applies. The model's provider keeps every request it is sent, so a
@@ -1021,7 +1136,8 @@ fail-closed `terminal` default.
 | `X_AGENT_TOOL_UNDECLARED` | an `agent()` run's `offerTools()` named a tool its declaration does not list |
 | `X_AGENT_TOOL_LOOP` | an `agent()` made the same tool calls and read the same results `maxRepeatedToolCalls` turns in a row |
 | `X_AGENT_DEADLINE` | an `agent()` outlived its declared `deadlineMs` |
-| `X_AGENT_CONTEXT_EXHAUSTED` | an `agent()`'s next request would not fit its model's context window, and compaction could not bring it under; refused before it is sent |
+| `X_AGENT_CONTEXT_EXHAUSTED` | an `agent()`'s next request would not fit its model's context window, and compaction could not bring it under — refused before it is sent, or after the provider refused it twice (`meta.refused`) |
+| `X_AI_CONTEXT_OVERFLOW` | a provider answered 400/413 saying the prompt outgrew the model's window; never retried, `terminal` for a job. `llm()` and `generate()` raise it as itself; `agent()` compacts once first |
 | `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 |
@@ -1061,6 +1177,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `EvalMissingError` | `X_EVAL_MISSING` | `src/eval-errors.ts` |
 | `EvalRecordingError` | `X_EVAL_RECORDING` | `src/eval-errors.ts` |
 | `EvalThresholdError` | `X_EVAL_THRESHOLD` | `src/eval-errors.ts` |
+| `EvalToolUndoubledError` | `X_EVAL_TOOL_UNDOUBLED` | `src/eval-errors.ts` |
 | `HiveEmptyError` | `X_HIVE_EMPTY` | `src/hive-errors.ts` |
 | `LlmOutputInvalidError` | `X_LLM_OUTPUT_INVALID` | `src/errors.ts` |
 | `LlmRefusedError` | `X_LLM_REFUSED` | `src/errors.ts` |

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@ultimat3/ai",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "ai",
+    "llm",
+    "agents",
+    "evals",
+    "rag",
+    "embeddings"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/MCP-And-AI",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -32,17 +44,17 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "29.4.0",
-    "@ultimat3/cache": "29.4.0",
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/db": "29.4.0",
-    "@ultimat3/http": "29.4.0",
-    "@ultimat3/jobs": "29.4.0",
-    "@ultimat3/money": "29.4.0",
-    "@ultimat3/schema": "29.4.0",
-    "@ultimat3/time": "29.4.0"
+    "@ultimat3/action": "30.1.0",
+    "@ultimat3/cache": "30.1.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/db": "30.1.0",
+    "@ultimat3/http": "30.1.0",
+    "@ultimat3/jobs": "30.1.0",
+    "@ultimat3/money": "30.1.0",
+    "@ultimat3/schema": "30.1.0",
+    "@ultimat3/time": "30.1.0"
   },
   "devDependencies": {
-    "@ultimat3/policy": "29.4.0"
+    "@ultimat3/policy": "30.1.0"
   }
 }