@ultimat3/ai 30.8.0 → 31.0.0

package/CLAUDE.md

@@ -32,10 +32,10 @@ Keep `policy` dev-only: tests and `*-fixture.ts` harnesses import `allow`. The
 | `openai-provider.ts` | `openAiProvider()` — the socket, the credential and the errors for any endpoint speaking the OpenAI chat-completions FORMAT |
 | `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]`) |
+| `openai-wire.ts` / `openai-wire-stream.ts` | its response half: one completion and the field readers; `ChatCompletionStream` (fragmented tool calls, trailing usage, `[DONE]`) |
 | `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 |
+| `budget.ts` / `budget-store.ts` | token ledgers per request/actor/org, ALS carrier; the `BudgetStore` contract and `memoryBudgetStore()` |
 | `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 |
@@ -57,10 +57,11 @@ Keep `policy` dev-only: tests and `*-fixture.ts` harnesses import `allow`. The
 | `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, 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 |
+| `llm.ts` / `llm-answer.ts` | `llm()` — the model call, declared as an `action`; one answered turn's span, `onCall`, fit, and what a streamed answer must satisfy |
+| `llm-instrument.ts` | what one `llm()` call reports when it settles: gen_ai usage on the span, `ai.llm` on the bus |
 | `respond.ts` | the `respond` tool for one `output` (a non-object one wrapped in `{ value }`), its reader, and `parseJsonish` |
 | `llm-stream.ts` | `.stream()`'s plumbing: the sink, the ambient mark, the one-turn drive |
-| `agent.ts` | `agent()` — the tool loop, declared as an `action` |
+| `agent.ts` / `agent-tools.ts` | `agent()` — the tool loop, declared as an `action`; one turn's bounded tool fan-out |
 | `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 |
@@ -69,7 +70,7 @@ Keep `policy` dev-only: tests and `*-fixture.ts` harnesses import `allow`. The
 | `agent-per-run.ts` / `agent-run-limits.ts` | one run's `offerTools()`/`model()`/`limits()`, narrow only; `costPerRun` |
 | `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-continue.ts` / `agent-session.ts` / `agent-turn.ts` | the transcript handle and its screen; `.run()` / `.continue()` and their session; 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()` |
@@ -111,6 +112,12 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#bou
 
 ## Invariants — `llm()`
 
+- **Telemetry is semconv's `gen_ai.*`, the rest `ultimate.llm.*`** — never a bare `llm.*` key.
+  `llm-instrument.ts` wraps the run meter (every provider call passes it) and settles ONCE per
+  `llm()` call — answered, cache hit or failed: the run's summed usage onto the `client` span and
+  `ai.llm` onto core's bus (`llm-instrument.test.ts`). `agent()` emits one `ai.llm` per MODEL CALL —
+  each turn and each compaction summary, through `reportedCall` — so the token metric counts agents.
+
 Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm-invariants).
 
 - **`llm()` returns an `action`**, never a ninth primitive; it adds only the model half: render the
@@ -124,7 +131,7 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 - **Semantic scopes are separate cache INSTANCES** (key: prompt hash AND `ctx.locale`); **the
   default scope is the calling ACTOR**; widening is `scope: () => 'global'`; the map is bounded.
   `cache.invalidates` is not on `llm()`: version bump + `ttl` is the invalidation.
-- The gateway is ambient (`configureAi`); absent at call time is `X_AI_GATEWAY_MISSING`.
+- The gateway is the `aiGateway` port: one slot, `installAiGateway` on `./adapter` only (`adapter.test.ts`), never `configureAi` (v31); absent at call time is `X_AI_GATEWAY_MISSING`.
 - **`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.
@@ -194,7 +201,7 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 - **`embedBatched` enforces the `Embedder` arity per batch** (`X_AI_EMBEDDER_INVALID` with both
   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.
+  `openai-wire-stream.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
   `echoProvider()`'s `replies` use `Object.hasOwn`.
 
@@ -207,12 +214,14 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
   - `tools` takes a real `action()` (`AgentTool = AnyAction | ProjectableAction`,
     `asProjectableAction`); projection happens on the FIRST RUN, memoised. An agent can be another
     agent's tool.
-  - A tool is an exposed action or an `inProcessTool()` (`isOfferedTool`); anything else is
+  - A tool is an action core's `isAgentOffered` admits (exposed, or `agents: true`) or an
+    `inProcessTool()` (`isOfferedTool`); anything else is
     `X_AGENT_TOOL_UNEXPOSED` at DECLARATION. An in-process tool is never an action, never projected
     to MCP, has no policy (the agent's decides) and parses its own input.
   - `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.
+  - One turn's tools run concurrently, at most `maxToolConcurrency` (default 8, `agent-tools.ts`),
+    results paired by index; no tool STARTS after an abort or the deadline.
   - **`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.
@@ -263,13 +272,13 @@ retrieval is hybrid only; an unbound store read under an org actor is `X_VECTOR_
 ## Commands
 
 ```
-bun test packages/ai
+bun test ./packages/ai/
 bun run --filter @ultimat3/ai typecheck
 
 # the live vector suite — needs the extension, not just a Postgres
 docker run -d -e POSTGRES_PASSWORD=ultimate -p 5432:5432 pgvector/pgvector:pg17
 TEST_DATABASE_URL=postgres://postgres:ultimate@localhost:5432/postgres \
-  bun test packages/ai/src/pg-vector.live.test.ts
+  bun test ./packages/ai/src/pg-vector.live.test.ts
 ```
 
 Why each rule above is shaped the way it is: [`docs/history/ai.md`](../../docs/history/ai.md).

package/README.md

@@ -15,7 +15,6 @@ example).
 ```ts
 import {
   budgetKeysFor,
-  configureAi,
   providerGateway,
   openAiProvider,
   registerModel,
@@ -39,7 +38,8 @@ export const ai = providerGateway({
   budget: { request: 40_000, actor: 500_000, org: 20_000_000 },  // tokens
   cache: memoCache,
 });
-configureAi({ gateway: ai });
+// apps/web/runtime.ts — the boot installs it: `aiGateway` is the one way a gateway arrives.
+export const runtime = { aiGateway: ai };
 
 // Budgets are scoped, and every nested call inside the scope shares one ledger. `llm()`, `agent()`
 // and `hive()` open one keyed on their caller (`budgetKeysFor(ctx.actor)`) without being asked.
@@ -148,13 +148,13 @@ default store at `replicas: 6` is six ledgers of twenty million, which is a budg
 | 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 |
 | A local refusal is never collected into `X_AI_PROVIDER_UNAVAILABLE` | `X_AI_KEY_MISSING` and `X_AI_REQUEST_INVALID` are raised before the request leaves; retrying them across providers burns attempts on the same answer and discards the runnable `fix:`. `generate()` and `stream()` therefore answer the same misconfiguration the same way |
-| 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 |
+| 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 `gen_ai.provider.name`, 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, 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 |
+| `retry` is **core's `RetryPolicy`**; the default is full jitter (`DEFAULT_GATEWAY_RETRY`: `{ attempts: 3, base: 500, max: 8_000, jitter: 'full' }`) | synchronised retries from N workers reproduce the rate limit. `backoffMs` is `@ultimat3/core`'s `backoffDelay` over the policy, `timeBudgetMs` bounds the whole call across providers, 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 |
 
@@ -216,7 +216,7 @@ registerModel({
   reasoning: { effort: false, adaptive: false, disableThinkingUpTo: undefined },
 });
 
-configureAi({ gateway: providerGateway({ providers: [new InternalGatewayProvider()] }) });
+export const runtime = { aiGateway: providerGateway({ providers: [new InternalGatewayProvider()] }) };
 ```
 
 Two optional per-model rows: `sampling: { temperature: true, seed: true }` (the model takes the `temperature` / `seed` an `llm()` or `agent()` declares — absent, they are not sent) and `forcedToolChoice: false` (the model rejects a forced `tool_choice`, so `llm()`'s one `respond` tool is offered under the endpoint's default).
@@ -318,7 +318,7 @@ 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
+  name: 'acme-gateway',            // what `result.provider` and `gen_ai.provider.name` will say
   headers: { 'x-team': 'platform' },
 });
 
@@ -448,7 +448,7 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 |---|---|
 | 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 |
+| the tools of **one turn** run concurrently, at most `maxToolConcurrency` at once (default 8), results paired by `tool_use` id | a turn asking for five tools cost 5x wall clock and nothing said so; a turn asking for fifty — a confused or injected model — was fifty concurrent invocations and pool checkouts. Order is positional, never by completion; a call waiting for a slot never starts after an abort or the deadline. `maxToolConcurrency: 1` runs a turn serially |
 | `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** |
@@ -780,7 +780,7 @@ the sweep and `hive()` for the fan-out inside one page.
 |---|---|
 | `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` |
+| the action projection is read **lazily** | `agentJob()` runs at module scope beside the `agent()` it wraps, and names are stamped by `defineApi` 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 org comes from the job's declared `tenant`; nothing a model emits can reach the identity. In a served app the worker's actor is the **anonymous** one, so a member policy refuses it `X_UNAUTHENTICATED` — declare `actor` |
 | `actor({ input, ctx })` resolves who the run acts FOR, on every attempt | the jobs rule — a job acting for a user takes the user's id in its input and re-authorises it in the body — for a body that is the agent's. Load the member under the job's tenant; the swap is core's `impersonate`, so the worker stays on the record as `onBehalfOf`. An actor in another org than `tenant` is `X_JOB_TENANT_MISMATCH` before the agent starts — terminal, so it dead-letters on attempt 1 |
@@ -831,7 +831,7 @@ the rows are real; wait for `x manifest` to carry them and you will wait. Same f
 
 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
+source. Names are read when you ask, not when the agent was declared: `defineApi` 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.
 
@@ -842,25 +842,58 @@ runs — and the redactor sits on both, between the row and a third-party endpoi
 `vars()` alone until 2026-09-23, so an agent's tool results left the process unredacted.
 
 ```ts
-configureAi({ gateway, redact: (text) => scrubPatientIdentifiers(text) });
+configureAi({ 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`.
+instruction. Whether it changed anything is on the span as `ultimate.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 `aiGateway` port
+
 The gateway is ambient, installed once at boot — a declaration is evaluated at module scope,
-long before a provider exists:
+long before a provider exists. One way in (31.0.0): `aiGateway` in `apps/<app>/runtime.ts`.
 
 ```ts
-configureAi({ gateway: providerGateway({ providers: [yourProvider], defaultModel: 'house-large' }) });
+// apps/web/runtime.ts
+export const runtime = {
+  aiGateway: providerGateway({ providers: [yourProvider], defaultModel: 'house-large' }),
+};
 ```
 
+The boot installs it through `installAiGateway(gateway): () => void`, on `@ultimat3/ai/adapter`
+only — with the `Gateway` interface, its request/answer types and the errors a gateway driver
+throws (`AiProviderUnavailableError`, `AiKeyMissingError`, `AiModelUnknownError`,
+`AiRequestInvalidError`). A test swaps the gateway the same way and calls the release to put the
+previous one back.
+
+The embedder and the semantic cache are ports the same way — `embedder` (an `Embedder`; default
+`hashEmbedder()`, offline and lexical) and `semanticCache` (a `SemanticCacheFactory`,
+`(scope) => SemanticCache`; default a `memorySemanticCache()` per scope), installed with
+`installAiEmbedder` / `installSemanticCache` from `@ultimat3/ai/adapter`. Each install clears the
+per-scope caches: vectors from two embedders are not comparable. Prove one with
+`embedderConformance` / `semanticCacheFactoryConformance` (`@ultimat3/testing/conformance`).
+
+```ts
+// apps/web/runtime.ts
+import { remoteEmbedder } from '@ultimat3/ai';
+import { memorySemanticCache } from '@ultimat3/cache';
+
+export const runtime = {
+  embedder: remoteEmbedder({ name: 'voyage-3', dimension: 1_024 }),  // EMBEDDINGS_API_KEY
+  // One cache per scope; a pgvector-backed factory of your own takes the same shape.
+  semanticCache: () => memorySemanticCache({ threshold: 0.95 }),
+};
+```
+
+`configureAi` configures the rest — `redact` only — and takes no `gateway`, `embedder` or
+`semanticCache` (31.0.0).
+
 Missing at call time is `X_AI_GATEWAY_MISSING`, never a silent default provider.
 
 ## Evals are a test type
@@ -1124,7 +1157,7 @@ fail-closed `terminal` default.
 |---|---|
 | `X_AI_PROVIDER_UNAVAILABLE` | every provider for the model was unreachable; lists what each said. A TRANSPORT failure only — a coded refusal raised before the socket opens (`X_AI_KEY_MISSING`, `X_AI_REQUEST_INVALID`) reaches the caller as itself, `As of 2026-08-23`, because the same rejection waits on every provider and every attempt and its `fix:` is the whole point of it |
 | `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_GATEWAY_MISSING` | an `llm()` action ran with no `aiGateway` installed |
 | `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_CONTENT_UNSUPPORTED` | an image or document block the role, the model's `input` row or the wire format cannot take; names which, refused before the socket |
@@ -1162,23 +1195,15 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `AgentToolUnexposedError` | `X_AGENT_TOOL_UNEXPOSED` | `src/errors.ts` |
 | `AiBudgetExceededError` | `X_AI_BUDGET_EXCEEDED` | `src/errors.ts` |
 | `AiContentUnsupportedError` | `X_AI_CONTENT_UNSUPPORTED` | `src/content-errors.ts` |
-| `AiGatewayMissingError` | `X_AI_GATEWAY_MISSING` | `src/errors.ts` |
-| `AiKeyMissingError` | `X_AI_KEY_MISSING` | `src/errors.ts` |
-| `AiModelUnknownError` | `X_AI_MODEL_UNKNOWN` | `src/errors.ts` |
-| `AiPromptRenderError` | `X_AI_PROMPT_VERSION` | `src/errors.ts` |
-| `AiPromptSecretError` | `X_AI_PROMPT_SECRET` | `src/errors.ts` |
-| `AiPromptVersionError` | `X_AI_PROMPT_VERSION` | `src/errors.ts` |
 | `AiProviderUnavailableError` | `X_AI_PROVIDER_UNAVAILABLE` | `src/errors.ts` |
 | `AiRequestInvalidError` | `X_AI_REQUEST_INVALID` | `src/errors.ts` |
 | `AiTransportError` | `X_AI_PROVIDER_UNAVAILABLE` | `src/errors.ts` |
 | `EmbedderDimMismatchError` | `X_VECTOR_DIM_MISMATCH` | `src/errors.ts` |
-| `EvalBaselineInvalidError` | `X_EVAL_BASELINE_INVALID` | `src/eval-errors.ts` |
 | `EvalBaselineMissingError` | `X_EVAL_BASELINE_MISSING` | `src/eval-errors.ts` |
 | `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` |
 | `LlmStreamInvalidError` | `X_LLM_STREAM_INVALID` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "30.8.0",
+  "version": "31.0.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "keywords": [
     "ultimate",
@@ -26,7 +26,8 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts"
   },
   "files": [
     "src",
@@ -44,17 +45,17 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.8.0",
-    "@ultimat3/cache": "30.8.0",
-    "@ultimat3/core": "30.8.0",
-    "@ultimat3/db": "30.8.0",
-    "@ultimat3/http": "30.8.0",
-    "@ultimat3/jobs": "30.8.0",
-    "@ultimat3/money": "30.8.0",
-    "@ultimat3/schema": "30.8.0",
-    "@ultimat3/time": "30.8.0"
+    "@ultimat3/action": "31.0.0",
+    "@ultimat3/cache": "31.0.0",
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/db": "31.0.0",
+    "@ultimat3/http": "31.0.0",
+    "@ultimat3/jobs": "31.0.0",
+    "@ultimat3/money": "31.0.0",
+    "@ultimat3/schema": "31.0.0",
+    "@ultimat3/time": "31.0.0"
   },
   "devDependencies": {
-    "@ultimat3/policy": "30.8.0"
+    "@ultimat3/policy": "31.0.0"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,21 @@
+// `@ultimat3/ai/adapter` — the `aiGateway`, `embedder` and `semanticCache` ports: the interfaces
+// an adapter implements, the shapes a gateway speaks, the errors a driver throws, and the boot's
+// installers. Installers live here and never on the `.` barrel; the boot fills them from
+// `apps/<app>/runtime.ts`.
+
+export type { SemanticCache } from '@ultimat3/cache';
+export type { BudgetKeys, BudgetLedger } from './budget';
+export type { Embedder } from './embeddings';
+export {
+  AiEmbedderInvalidError,
+  AiKeyMissingError,
+  AiModelUnknownError,
+  AiProviderUnavailableError,
+  AiRequestInvalidError,
+} from './errors';
+export type { Gateway } from './gateway';
+export type { ModelId } from './models';
+export type { GenerateRequest, GenerateResult, StreamChunk } from './provider';
+export type { SemanticCacheFactory } from './runtime';
+export { installAiEmbedder, installAiGateway, installSemanticCache } from './runtime';
+export type { SamplingWire } from './sampling';

package/src/agent-compact.ts

@@ -22,6 +22,7 @@ import { blocksOf, COMPACTED_MARK, summaryCall } from './agent-compact-request';
 import { AgentContextExhaustedError } from './agent-errors';
 import type { RunDeadline } from './agent-guards';
 import type { Gateway } from './gateway';
+import { reportedCall } from './llm-instrument';
 import type { ModelId } from './models';
 import { modelSpec } from './models';
 import type { AiMessage, GenerateRequest, GenerateResult, TokenUsage } from './provider';
@@ -118,7 +119,7 @@ export function compactor(input: CompactorInput): Compactor {
             'agent.compact.clipped_turns': event.clipped ?? 0,
             'agent.compact.omitted_turns': event.omitted ?? 0,
           }),
-      ...(event.cost === undefined ? {} : { 'llm.cost.minor': event.cost.minor }),
+      ...(event.cost === undefined ? {} : { 'ultimate.llm.cost.minor': event.cost.minor }),
     });
     await input.onCompact?.(event);
   };
@@ -193,7 +194,9 @@ export function compactor(input: CompactorInput): Compactor {
     try {
       // Its own meter, inside the run's: the bill reaches the run as a nested call's does — on the
       // same ledger, in `tokensPerRun` and `costPerRun`, priced at the summary model's own rates.
-      result = await input.deadline.guard(runMeter().call(input.gateway.generate(request)));
+      result = await input.deadline.guard(
+        runMeter().call(reportedCall(request.model ?? writer, input.gateway.generate(request))),
+      );
     } catch (error) {
       throwIfAborted(input.ctx);
       const code = stringField(error, 'code');

package/src/agent-continue.ts

@@ -1,6 +1,6 @@
 // Single responsibility: continuing an `agent()` run — the transcript handle a finished run
-// leaves, the screen it passes when an app hands it back, the one user turn a continuation
-// appends, and `.run()` / `.continue()` on the action.
+// leaves, the screen it passes when an app hands it back, and the one user turn a continuation
+// appends. `.run()` / `.continue()` themselves are ./agent-session.
 //
 // It exists because the alternative is a whole new run: repairing one section of an article
 // re-pays the transcript and every tool result, and the model starts from nothing. A continuation
@@ -14,7 +14,6 @@
 
 import type { Action, InvokeOptions } from '@ultimat3/action';
 import {
-  asyncContext,
   CURSOR_SECRET_FIX,
   CURSOR_SECRET_KEY,
   canonicalJson,
@@ -23,6 +22,7 @@ import {
   hmac,
   isProduction,
   isUltimateError,
+  timingSafeEqual,
   usesDevCursorSecret,
 } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
@@ -136,63 +136,6 @@ export interface AgentAction<TInput extends StandardSchemaV1, TOutput extends St
   named(name: string): AgentAction<TInput, TOutput>;
 }
 
-/** One `.run()` / `.continue()` in flight: what to resume from, and where the loop leaves its run. */
-export interface AgentSession {
-  /**
-   * Which DECLARATION this session was opened for. The session rides the async context, so every
-   * agent that runs underneath — a tool that calls another agent — can see it; only the one whose
-   * token this is may take it, and only once.
-   */
-  readonly owner: object;
-  claimed: boolean;
-  readonly resume: AgentContinuation | undefined;
-  finished: Omit<AgentRun<unknown>, 'output'> | undefined;
-}
-
-// Core's lazy seam, like `llm-stream.ts`'s sink: the mark rides the invocation, so the action a
-// continuation calls is the one object the registry, the policy and the audit record know.
-const sessions = asyncContext<AgentSession>('an agent session');
-
-/**
- * The session of THIS run, taken — or `undefined` for a plain call, and for any other agent
- * running under somebody else's `.run()` / `.continue()`: a nested agent starts fresh.
- */
-export function claimAgentSession(owner: object): AgentSession | undefined {
-  const session = sessions.get();
-  if (session === undefined || session.owner !== owner || session.claimed) return undefined;
-  session.claimed = true;
-  return session;
-}
-
-/** `.run()` and `.continue()` for one action: each invokes THAT action inside a session. */
-export function sessionCalls<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
-  target: Action<TInput, TOutput>,
-  /** The declaration's own token: `named()` twins share it, no other agent has it. */
-  owner: object,
-): Pick<AgentAction<TInput, TOutput>, 'run' | 'continue'> {
-  const invoke = async (
-    input: InferInput<TInput>,
-    resume: AgentContinuation | undefined,
-    opts: InvokeOptions | undefined,
-  ): Promise<AgentRun<InferOutput<TOutput>>> => {
-    const session: AgentSession = { owner, claimed: false, resume, finished: undefined };
-    const output = await sessions.run(session, () => target(input, opts ?? {}));
-    const finished = session.finished;
-    if (finished === undefined) {
-      // The action answered without the loop running: something wrapped it and short-circuited.
-      throw new AgentTranscriptInvalidError({
-        agent: target.name ?? 'agent',
-        reason: 'the action returned without running the agent loop, so there is no transcript',
-      });
-    }
-    return { output, ...finished };
-  };
-  return {
-    run: (input, opts) => invoke(input, undefined, opts),
-    continue: (input, resume, opts) => invoke(input, resume, opts),
-  };
-}
-
 /**
  * The transcript with ONE user turn appended. Every `tool_use` the last assistant turn left open is
  * answered first — the accepted `respond` call among them, which the API insists on seeing
@@ -321,7 +264,7 @@ export function screenTranscript(binding: TranscriptBinding, raw: unknown): Agen
   } catch {
     return refuse('it is not JSON');
   }
-  if (typeof sig !== 'string' || !sameText(sig, expected)) {
+  if (typeof sig !== 'string' || !timingSafeEqual(sig, expected)) {
     refuse('its signature does not match — it was edited, or the signing secret rotated');
   }
   if (handle['agent'] !== agent) refuse(`it was written by agent "${String(handle['agent'])}"`);
@@ -393,14 +336,6 @@ export function screenTranscript(binding: TranscriptBinding, raw: unknown): Agen
   };
 }
 
-/** Constant-time over equal lengths: a signature check must not say how much of it matched. */
-function sameText(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
-  return diff === 0;
-}
-
 function recordOf(value: unknown): Record<string, unknown> | undefined {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)

package/src/agent-def.ts

@@ -127,6 +127,11 @@ export interface AgentDef<
    * `X_AGENT_TOOL_LOOP`. Default 3.
    */
   readonly maxRepeatedToolCalls?: number;
+  /**
+   * Tool calls of ONE turn in flight at once; the rest wait for a slot, and results keep the order
+   * the model emitted them. Default 8 (`DEFAULT_TOOL_CONCURRENCY`); `1` runs a turn's tools serially.
+   */
+  readonly maxToolConcurrency?: number;
   /**
    * Wall-clock ceiling for the whole run, in milliseconds. Passing it aborts the model call in
    * flight and is `X_AGENT_DEADLINE`. No default: a timeout nobody declared is a lost answer.
@@ -147,7 +152,7 @@ export interface AgentDef<
    * `temperature` (0 to 2) and `seed` (a whole number), for a call that should answer the same way
    * twice — a verifier, a classifier. Sent only to a model whose row takes them
    * (`registerModel({ sampling })`); to any other they are NOT sent, because a reasoning model
-   * answers one with a 400 — the `llm.sampling.ignored` span attribute names what was left out.
+   * answers one with a 400 — the `ultimate.llm.sampling.ignored` span attribute names what was left out.
    * `seed` exists on the chat-completions wire only, and is best effort where it exists.
    */
   readonly temperature?: number;

package/src/agent-session.ts

@@ -0,0 +1,66 @@
+// Single responsibility: `.run()` / `.continue()` on an agent's action — the ambient session a call
+// opens, the one claim the declaring agent may make on it, and the two calls themselves. Split
+// from ./agent-continue (the handle) and ./agent (the loop) at their line ceilings.
+
+import type { Action, InvokeOptions } from '@ultimat3/action';
+import { asyncContext } from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { AgentAction, AgentContinuation, AgentRun } from './agent-continue';
+import { AgentTranscriptInvalidError } from './agent-errors';
+
+/** One `.run()` / `.continue()` in flight: what to resume from, and where the loop leaves its run. */
+export interface AgentSession {
+  /**
+   * Which DECLARATION this session was opened for. The session rides the async context, so every
+   * agent that runs underneath — a tool that calls another agent — can see it; only the one whose
+   * token this is may take it, and only once.
+   */
+  readonly owner: object;
+  claimed: boolean;
+  readonly resume: AgentContinuation | undefined;
+  finished: Omit<AgentRun<unknown>, 'output'> | undefined;
+}
+
+// Core's lazy seam, like `llm-stream.ts`'s sink: the mark rides the invocation, so the action a
+// continuation calls is the one object the registry, the policy and the audit record know.
+const sessions = asyncContext<AgentSession>('an agent session');
+
+/**
+ * The session of THIS run, taken — or `undefined` for a plain call, and for any other agent
+ * running under somebody else's `.run()` / `.continue()`: a nested agent starts fresh.
+ */
+export function claimAgentSession(owner: object): AgentSession | undefined {
+  const session = sessions.get();
+  if (session === undefined || session.owner !== owner || session.claimed) return undefined;
+  session.claimed = true;
+  return session;
+}
+
+/** `.run()` and `.continue()` for one action: each invokes THAT action inside a session. */
+export function sessionCalls<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+  /** The declaration's own token: `named()` twins share it, no other agent has it. */
+  owner: object,
+): Pick<AgentAction<TInput, TOutput>, 'run' | 'continue'> {
+  const invoke = async (
+    input: InferInput<TInput>,
+    resume: AgentContinuation | undefined,
+    opts: InvokeOptions | undefined,
+  ): Promise<AgentRun<InferOutput<TOutput>>> => {
+    const session: AgentSession = { owner, claimed: false, resume, finished: undefined };
+    const output = await sessions.run(session, () => target(input, opts ?? {}));
+    const finished = session.finished;
+    if (finished === undefined) {
+      // The action answered without the loop running: something wrapped it and short-circuited.
+      throw new AgentTranscriptInvalidError({
+        agent: target.name ?? 'agent',
+        reason: 'the action returned without running the agent loop, so there is no transcript',
+      });
+    }
+    return { output, ...finished };
+  };
+  return {
+    run: (input, opts) => invoke(input, undefined, opts),
+    continue: (input, resume, opts) => invoke(input, resume, opts),
+  };
+}

package/src/agent-system.ts

@@ -32,6 +32,6 @@ export function systemOf(
   return fixed === undefined && stable === '' ? undefined : stable;
 }
 
-/** Whether two composed prompts are the same text — what `llm.redacted` compares. */
+/** Whether two composed prompts are the same text — what `ultimate.llm.redacted` compares. */
 export const sameSystem = (a: SystemPrompt | undefined, b: SystemPrompt | undefined): boolean =>
   JSON.stringify(a) === JSON.stringify(b);