@ultimat3/ai 27.8.1 → 27.10.0

package/CLAUDE.md

@@ -9,18 +9,13 @@ does), `jobs` (`agentJob()`), `money`, `policy`, `schema`, `time`.
 
 `jobs` is declared for `agentJob()`: the action→job bridge has to live at tier 4+.
 
-`mcp` is the same tier, so the LLM-tool projection is restated structurally in `tools.ts`
-rather than imported. Same contract, two wire formats — and the same *decision*: `toLlmTools` and
-`runLlmToolCall` ask `isMcpExposed` from `@ultimat3/core` (tier 0, reachable by both), never a
-local `=== true`. An in-app agent and an external one must be offered exactly the same tools.
-
-**And the same NAME**: `toLlmTool` passes `action.name` through untouched (the export name
-`@ultimat3/mcp` serves); `llm()` and `agent()` tool names are verbatim too. Never derive one.
-
-**And the same TOOL**: `asProjectableAction` and mcp's `primitiveFromAction` are two copies the
-tier table forces; `scripts/ai-mcp-tool-parity.test.ts` holds them equal — name, description,
-exposure, the whole input schema (an idempotent action's reserved `idempotencyKey` argument,
-`tool-idempotency.ts`), the policy verdict and the replay. A field one adds, the other adds.
+`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.
 
 ## Owns
 
@@ -28,8 +23,8 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 |---|---|
 | `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()`), as an app's `models.ts` would. Not shipped (`!src/**/*-fixture.ts`) |
-| `provider.ts` | `Provider` interface, the request half, the money arithmetic, `anthropicProvider()` |
+| `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 |
 | `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` |
@@ -57,13 +52,21 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 | `rag.ts` | chunker, retriever, reranker, budgeted context assembler |
 | `tools.ts` | action → LLM tool definition; the `AgentTool` union and `asProjectableAction`; `runLlmToolCall` |
 | `tool-idempotency.ts` | an idempotent action's reserved `idempotencyKey` tool argument — MCP's, restated (same tier), held equal by the parity test |
-| `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 as code, name and stack frames — never its message or cause |
+| `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 |
+| `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` |
 | `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-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-blocks.ts` | the Anthropic wire's marks (chat-completions': `openai-messages.ts`) |
+| `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: nothing reads it yet, because `manifest` is tier 4 like this package and the consumer has to be `cli` at tier 5 |
+| `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` |
@@ -71,87 +74,69 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 | `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` |
 | `llm-cache.ts` | the semantic cache half of `llm()`: what a declaration may partition on, and the store it reaches |
-| `llm-fixture.ts` | the harness `llm.test.ts` and `llm-cache.test.ts` share. Not shipped (`!src/**/*-fixture.ts`) |
-| `bounds-fixture.ts` | the one `refusal`/`asyncRefusal` every numeric-bound suite here asserts through. Not shipped, same rule |
-| `agent-bounds.test.ts` | the agent loop's ceilings (split from `agent.test.ts`, at its line ceiling) |
+| `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 |
-| `fix-line-fixture.ts` / `fix-line.evals-fixture.ts` / `fix-line.v1.baseline.json` / `fix-line.eval.test.ts` | the package's dogfood eval — proof the baseline convention fails a build |
+| `fix-line*` | the package's dogfood eval — proof the baseline convention fails a build |
 
 ## Invariants — bounds and budget
 
-- **Every numeric option is screened; `??` is not the screen.** `finiteOption`/`finiteCount` from
-  `@ultimat3/core` are the one form; `bun run finite-bounds` is the ratchet, and it cannot see a
-  required option with no `??`, a default parameter or a cross-field product. **`maxTokens` is the
-  worst**: it IS the budget's pre-flight estimate, and a `NaN` switches every actor and org ceiling
-  off. `Gateway.generate`/`stream` screen it at the one seam, `registerModel` screens `maxOutput`, and
-  `llm()`/`agent()` screen theirs at DECLARATION.
-- **A bound is screened under the key the DECLARATION uses** (`budget.tokensPerRun` in `limitsOf`
-  before the ledger's `request`; `retrieve()`'s own `k`; `remoteEmbedder()`'s `maxResponseBytes`).
-- A per-call budget `derive`s from the ambient ledger and only TIGHTENS. **A derived ledger reports
-  back up the chain** (every debit on every ancestor; `reserve` checks each `request` scope); the
-  STORE is written once, by the ledger the call was made on.
-- **`reserve` debits, then checks — never a read-then-write across an `await`.** The in-memory scopes
-  check and debit synchronously; the store's go through `BudgetStore.take(key, tokens, limit)`, which
-  is REQUIRED and must be atomic (no default over `spent` + `add` — that pair is the race). A refusal
-  at a later scope gives back what the earlier ones took.
-- **The store is touched only for a scope whose ceiling is DECLARED** (`takeScope`, `meteredKeys`):
-  every call carries keys, so a write per key grew the default store by one entry per caller.
-  `memoryBudgetStore()` has no window and no eviction (eviction is a ceiling bypass); a counter back
-  at zero is deleted.
+Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#bounds-and-budget).
+
+- **Every numeric option is screened; `??` is not the screen** (`finiteOption`/`finiteCount`;
+  `bun run finite-bounds`). **`maxTokens` is the worst**: it IS the pre-flight estimate, and a `NaN`
+  switches every ceiling off — screened by the gateway, `registerModel` and `llm()`/`agent()`.
+- **A bound is screened under the key the DECLARATION uses** (`budget.tokensPerRun`, not `request`).
+- A per-call budget `derive`s from the ambient ledger and only TIGHTENS; a derived ledger reports
+  back up the chain; the STORE is written once, by the ledger the call was made on.
+- **`reserve` debits, then checks — never a read-then-write across an `await`**:
+  `BudgetStore.take(key, tokens, limit)` is REQUIRED and atomic; a later refusal gives back.
+- **The store is touched only for a scope whose ceiling is DECLARED**; `memoryBudgetStore()` has no
+  window and no eviction; a zero counter is deleted.
 - **`llm()`, `agent()`, `hive()` root as `currentBudget() ?? gateway.callLedger(budgetKeysFor(ctx.actor))`**
-  — the gateway's ceilings, keyed `actor:<kind>:<id>` / `org:<orgId>` (none for an `undefined`/`null`/`''`
-  org — the `orgless` test `query`'s cache uses). `callLedger` is required on
-  `Gateway`; `hive()` asks `installedGateway()` so a hive of plain actions needs none.
-- **`BudgetStore` is where `actor` and `org` live; the default is per PROCESS**
-  (`providerGateway({ budgetStore })`). `add` takes a negative `tokens` for a release — a store that
-  clamps at zero leaks the ceiling.
-- Cost is `Money` (integer minor units), rounded **up**. A budget throws `X_AI_BUDGET_EXCEEDED`
-  **before** the provider call. Never truncate. List price over-reserves (no introductory prices).
-- **`Gateway.stream` routes BEFORE it reserves**, and `settled = true` comes after
-  `await ledger.record(...)`.
+  (`actor:<kind>:<id>` / `org:<orgId>`). `callLedger` is required on `Gateway`.
+- **`BudgetStore` is where `actor` and `org` live; the default is per PROCESS**; `add` takes a
+  negative `tokens` for a release — a store that clamps at zero leaks the ceiling.
+- A budget throws `X_AI_BUDGET_EXCEEDED` **before** the provider call. Never truncate. List price
+  over-reserves.
+- **Cost is exact in bigint (`cost.ts`, `Money` at `costScale`), rounded UP once**: per call by
+  `costOf`, per ledger at `report()`, per run from the summed usage — never a sum of round-ups. A
+  price may state a `scale` (≤ `PRICE_SCALE_DIGITS` finer); it is always read through `minorAt`.
+- **`Gateway.stream` routes BEFORE it reserves**; `settled = true` comes after `ledger.record`.
 
 ## Invariants — `llm()`
 
+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
-  prompt, project `output` into the one `respond` tool, reserve the budget, consult the semantic cache.
-- **A non-object `output` is wrapped in `{ value }` and unwrapped** (`respond.ts`) — a tool's input is
-  an object; never refused, because `.stream()` serves `output: t.string`. `parseJsonish` is two
-  `indexOf` scans, never a backtracking pattern.
+  prompt, project `output` into the one `respond` tool, reserve the budget, consult the cache.
+- **A non-object `output` is wrapped in `{ value }` and unwrapped** (`respond.ts`), never refused;
+  `parseJsonish` is two `indexOf` scans, never a backtracking pattern.
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim** (`index.test.ts`).
 - One repair turn, then `X_LLM_OUTPUT_INVALID`. A refusal (a 200 with no answer) is `X_LLM_REFUSED`
-  before the parse, carrying `stopDetails.category`; a truncated invalid answer is `X_LLM_TRUNCATED`.
-  The gateway never caches a refusal.
-- **Semantic scopes are separate cache INSTANCES**; the instance key carries the prompt hash AND
-  `ctx.locale` (in the unconditional half). **The default scope is the calling ACTOR**
-  (`JSON.stringify([actor.kind, actor.id, actor.orgId ?? null])`); `scope` receives
-  `{ input, ctx }`; widening is `scope: () => 'global'`. The instance map is bounded
-  (core's `MAX_CACHED_FORMATTERS`).
-- `cache.invalidates` is not on `llm()`: a `SemanticCache` is not a `CacheTier`. Version bump + `ttl`
-  is the invalidation.
-- The gateway is ambient (`configureAi`); absent at call time is `X_AI_GATEWAY_MISSING`, never a
-  default provider.
+  before the parse; a truncated turn is `X_LLM_TRUNCATED` before the schema AND before any tool
+  runs (a cut `respond` reads `{}`). The gateway never caches a refusal.
+- **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`.
 - **`llm()` forwards `ctx.signal`** onto `GenerateRequest`; `.stream()` inherits it.
-- **`.stream()` is the SAME action**, marked with an ambient sink: it yields UNVALIDATED text and one
-  final `done` with the value that satisfied `output`; no repair turn (`X_LLM_STREAM_INVALID`); the
-  budget is reserved before the provider, debited on the first pull, reconciled at `done`; no
-  `respond` tool; a cache hit yields `done` alone. LAZY. `named()` is re-narrowed so the twin still streams.
+- **`.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.
 - **`configureAi({ redact })` is the one seam between `vars()` and the provider**; a `Secret` in
-  `vars()` is `X_AI_PROMPT_SECRET` regardless. The `llm.redacted` span attribute records it.
+  `vars()` is `X_AI_PROMPT_SECRET` regardless.
 - **Fallback is across PROVIDERS serving one model, never across models**; `GenerateResult.provider`
-  is stamped by the gateway and put on the span as `llm.provider`.
-- Server-side `fallbacks` (beta) are never sent — the stable `2023-06-01` surface only.
-- **A slot inside a tag pair is DATA** (`prompt-fence.ts`, #689): `render` breaks, in the ASSEMBLED
-  prompt, every fence closer a fenced value wrote any character of (never per value: two slots can
-  each hold half) — never deletes, never touches a template-only closer. The
-  fences are read once at `definePrompt`; no hash moves.
+  is stamped by the gateway. Server-side `fallbacks` (beta) are never sent.
+- **A slot inside a tag pair is DATA** (`prompt-fence.ts`, #689): `render` breaks every fence closer
+  a fenced value wrote, in the ASSEMBLED prompt — never deletes, never touches a template's own.
 - `definePrompt` refuses a re-registered version whose hash moved; the hash is over core's
-  `canonicalJson` (`prompt.test.ts` pins one hash literally); an absent schema hashes as `''`.
+  `canonicalJson`; an absent schema hashes as `''`.
 
 ## Invariants — providers and the gateway
 
 - **The response cache key is core's `fingerprint` over the request, each tool WHOLE** (every `llm()`
   tool is `respond`); a throwing `cache.set` is logged (`ai.cache.write_failed`), never a failure.
-- **An unknown stop/finish reason FAILS CLOSED as `max_tokens` on both formats**, streamed or not.
+- **An unknown stop reason FAILS CLOSED as `max_tokens` on the Anthropic wire; on chat-completions
+  it is UNKNOWN** (`readFinishReason`): a whole turn is a stop, else `X_AI_PROVIDER_UNEXPECTED`.
 - **One failure-body reader** (`error-body.ts`'s `detailOf`, bounded at `READ_LIMIT`) and one
   `withoutKey` scrub — the embedder included.
 - **`attempt` collects TRANSPORT failures only**: an `UltimateError` other than
@@ -160,39 +145,37 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 - **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`. Every other code
-  stays UNREGISTERED on purpose.
+  `AiProviderUnavailableError({ unserved: true })` carries a per-instance `terminal`. Six
+  deterministic failures are `terminal` (`errors-retry.ts`); the rest stay UNREGISTERED on purpose.
 - **The retry SCHEDULE is core's (`backoffDelay`, `isRetryableStatus`); the LOOP is this package's** —
-  core's `retry()` retries unclassified throws, and every value here is an app `Provider`'s plain
-  object, so it would retry a 400. `gateway-backoff.test.ts`. `RetryPolicy`/`DEFAULT_GATEWAY_RETRY` keep the
-  field names an app writes.
+  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 body throws (`throwInBandError`, `wire.ts`); a `refusal` stop detail forces
-  `stopReason: 'refusal'`; a tool call's `input` is parsed (`asToolInput`); the credential is scrubbed
-  from `detail` (`error-body.ts`'s `withoutKey`/`detailOf`). The status tables and the OpenAI
-  `estimatedUsage` fallback are asserted as differences.
+  `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`.
+- **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`).
+- **Every throw of `llm()`/`agent()` after a provider call STARTED carries `meta.billed`**
+  (`meter.fail`): answered calls summed, `unsettled` counted and never priced.
 - A stream ending without `message_stop` throws. **`readSse` caps the unterminated buffer**
   (`MAX_FRAME_CHARS`); `provider` is required so a transport error names its endpoint.
 - A tool call is emitted whole. Thinking chunks are never appended to `text`.
-- Anthropic body: no `temperature`/`top_p`/`top_k`, no `budget_tokens`, `effort` inside
-  `output_config`. Model IDs are exact aliases, never date-suffixed.
-- **Apps bring their own models and providers (M12, 25.0.0): no vendor choice, no vendor data.** No
-  default model, no catalogue row, no id list ships; the registry starts EMPTY and `resetModels()`
-  empties it. A model resolves declaration → prompt → `Gateway.defaultModel` through `resolveModel`
-  / `modelForCall` only; none is `X_AI_MODEL_UNRESOLVED` naming all three (with no gateway and nothing
-  declared, `X_AI_GATEWAY_MISSING` — the third place does not exist yet). `vendor-neutral.test.ts`
-  proves it in a fresh process; no fix line names a vendor id.
+- 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.
 - **`ModelId` is `string`; the catalogue is an open registry** — `modelSpec(id)` refuses an
-  unregistered id (`X_AI_MODEL_UNKNOWN`, fix `registerModel(…)`) at `costOf`, the budget estimate and
-  the body builders, before a socket or a reservation. **Re-registering REPLACES the spec and keeps
-  its rung** (negotiated rates). **Registration order is the ladder within a `family`**, read only by
-  `moreCapableThan`, over the APP's rows; `X_LLM_REFUSED`'s fix names a rung ABOVE or nothing.
-- **Every provider serves the app's list**: `anthropicProvider({ models })` and
-  `openAiProvider({ models })` require a non-empty one (`X_AI_REQUEST_INVALID`, a missing config
-  too); `echoProvider().models` reads the registry. **No provider has a model of its own**: a direct
-  call naming none is `X_AI_MODEL_UNRESOLVED` from all three — the list is what it serves, never a
-  fourth place (`vendor-neutral.test.ts`, one parity case).
+  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.
+- **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;
@@ -207,12 +190,13 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 - **`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;
+    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`; `isComplete()` accepts `[DONE]` or a finish reason,
-    except `[DONE]` with pending tool fragments, which is refused;
+  - 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`.
@@ -228,11 +212,14 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 
 - **`agent()` returns an action** (listed in `PRIMITIVE_FACTORIES`). `ctx.actor` is read once and is
   the only identity any tool runs as — never taken from the model's output. Bounded by `maxTurns`
-  (`X_AGENT_MAX_TURNS`), `budget.tokensPerRun` and `maxToolResultChars`.
+  (`X_AGENT_MAX_TURNS`), `budget.tokensPerRun`, `maxToolResultChars`, `maxRepeatedToolCalls`
+  (`X_AGENT_TOOL_LOOP`) and `deadlineMs` (`X_AGENT_DEADLINE`).
   - `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 not `mcp: { expose: true }` is `X_AGENT_TOOL_UNEXPOSED` at DECLARATION.
+  - A tool is an exposed action 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.
@@ -246,15 +233,21 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
   - **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.
+    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.
+- **`.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`).
 - **`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 (the reservation holds
-  it); a member's throw is recorded through `discloseFailure` — a 5xx cause or an uncoded throw's
-  message becomes `HIDDEN_MEMBER_CAUSE`, logged as facts only; `skipped` reasons
-  `SKIPPED_ABORTED` / `SKIPPED_NO_INPUT`; `onMemberError` is required; `concurrency` 4, `minMembers`
-  2 (a below-floor split still runs serially); an empty split is `X_HIVE_EMPTY`; an aborted `ctx`
-  unwinds with `X_ABORTED`.
+  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`.
 - **`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
@@ -263,30 +256,37 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
   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`.
 
+## 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`).
+
 ## Invariants — evals, retrieval, fix lines
 
-- **No fix line may name `x ai`** (planned). An eval is selected with `x test eval --filter <name>`;
-  `eval-errors.test.ts` asserts every `x test <word>` is one of the six types.
-- Every eval result carries the prompt hash. An eval gates on the DROP from its recorded baseline,
-  mean AND per case, both sides rounded as the baseline is written. Never-recorded is `X_EVAL_BASELINE_MISSING`, corrupt is `X_EVAL_BASELINE_INVALID`.
-  `baseline` is `import.meta.resolve('./…')`. Every prompt is named by an eval (`X_EVAL_MISSING`, by
-  prompt ID). `ULTIMATE_EVAL_RECORD=1` records; a deliberately-worse test calls `run`, never
-  `assert`; `x verify` with the flag is `X_EVAL_RECORDING` and runs no eval. The gate asks for a
-  recorded baseline, not only a declaration.
-- Retrieval is hybrid by default; no vector-only path. **`chunk()` hard-wraps**, the overlap
-  carry stops at `buffer.length - 1` and yields to a next unit it does not fit beside (no chunk over
-  `size`); `metadata.source` is written AFTER the caller's spread. `VectorStore.prune` is required.
-- **A store with no tenant bound, read inside a request whose actor has an `orgId`, is
-  `X_VECTOR_UNSCOPED`** (`assertTenantRead`, both stores, every read). `scope: UNSCOPED`
-  (`crossTenant: true`) is the named opt-in; an omitted scope is `UNBOUND`.
-- `postgresVectorStore()` is the only production vector path (pgvector + FTS in the app's Postgres);
-  `memoryVectorStore()` enforces the same envelope. **`pg-vector.live.test.ts` refuses to skip** on a
-  Postgres without the extension (CI uses `pgvector/pgvector:pg17`).
-- The distance ordering lives in an ascending raw subquery (the only shape hnsw answers), pinned by a
-  plan assertion. hnsw scopes after the scan — assert rows, never the node; `analyze` after a backfill.
-- Tenant and policy filters are in SQL on every statement (`conditionsSql`), on BOTH fusion halves.
-  `(tenant, id)` is the primary key. `scoped()` only TIGHTENS (`X_VECTOR_SCOPE_WIDENED`). Metadata is
-  bound `::text::jsonb`.
+Full text of each rule: [`docs/history/ai.md`](../../docs/history/ai.md#evals-retrieval-fix-lines).
+
+- **No fix line may name `x ai`** (planned); an eval is selected with `x test eval --filter <name>`.
+- Every eval result carries the prompt hash; an eval gates on the DROP from its recorded baseline,
+  mean AND per case (`X_EVAL_BASELINE_MISSING` / `_INVALID`); every prompt is named by an eval
+  (`X_EVAL_MISSING`); `ULTIMATE_EVAL_RECORD=1` records, and `x verify` with it is `X_EVAL_RECORDING`.
+- Retrieval is hybrid by default, no vector-only path. `chunk()` hard-wraps (no chunk over `size`);
+  `metadata.source` is written AFTER the caller's spread; `VectorStore.prune` is required.
+- **An unbound store read inside a request whose actor has an `orgId` is `X_VECTOR_UNSCOPED`**
+  (both stores, every read); `scope: UNSCOPED` is the named opt-in, an omitted scope is `UNBOUND`.
+- `postgresVectorStore()` is the only production vector path; `pg-vector.live.test.ts` refuses to
+  skip without the extension. Distance ordering is an ascending raw subquery (the shape hnsw
+  answers), pinned by a plan assertion. Tenant and policy filters are in SQL on every statement and
+  BOTH fusion halves; `(tenant, id)` is the key; `scoped()` only TIGHTENS (`X_VECTOR_SCOPE_WIDENED`).
 
 ## Commands
 

package/README.md

@@ -205,7 +205,7 @@ registerModel({
   id: 'llama-internal-70b',
   contextWindow: 128_000,
   maxOutput: 8_192,
-  inputPerMillion:  { minor: 20, currency: 'USD' },   // YOUR price, integer minor units
+  inputPerMillion:  { minor: 20, currency: 'USD' },   // YOUR price, integer minor units — or finer: { minor: 75, currency: 'USD', scale: 3 } is $0.075
   outputPerMillion: { minor: 40, currency: 'USD' },
   cacheMinimumTokens: 0,
   reasoning: { effort: false, adaptive: false, disableThinkingUpTo: undefined },
@@ -214,6 +214,8 @@ registerModel({
 configureAi({ gateway: 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).
+
 **The framework registers no model.** `registerModel` is the one way into the catalogue and only the
 app calls it — at boot, by convention in its own `models.ts`, each row with the page and the date its
 numbers were read from, so a stale price is a diff in the app's repo rather than a framework release.
@@ -433,12 +435,91 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 | 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 |
+| 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 |
 | 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` |
+| both stops are registered `terminal` | an `agentJob()` dead-letters on attempt one instead of buying the same run per attempt |
+| every turn asks the provider to cache its prefix (`promptCache`, default `'auto'`) | the transcript IS the request, so an uncached run pays for its stable prefix once per turn — [below](#provider-prompt-caching) |
 | `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 |
 
+### What a call cost
+
+`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.
+
+### 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).
+
+### Provider prompt caching
+
+Not the gateway's response cache and not `llm()`'s semantic one: this asks the **provider** to keep
+a request's prefix, so the next request reads it at the cache rate.
+
+```ts
+import { agent, definePrompt, t } from '@ultimat3/ai';
+import { can } from '@ultimat3/policy';
+
+const kbPrompt = definePrompt<{ question: string }>({
+  id: 'kb',
+  version: '1.0.0',
+  system: 'Answer from the knowledge base only.', // starts the stable block
+  template: 'Question: {{question}}',
+});
+
+export const kbAgent = agent({
+  input: t.object({ question: t.string, index: t.string }),
+  output: t.object({ answer: t.string }),
+  prompt: kbPrompt,
+  vars: ({ input }) => ({ question: input.question }),
+  // `stable` joins prompt.system in the block every run shares; `run` follows it
+  system: ({ input }) => ({ stable: input.index, run: `Question length: ${input.question.length}` }),
+  promptCache: { session: 'kb-agent' }, // 'auto' (default) | 'off' | { session }
+  tools: [],
+  policy: can('kb:ask'),
+  onTurn: ({ usage, run }) => {
+    console.log(usage.cacheReadTokens, usage.cacheWriteTokens, run.cost.minor);
+  },
+});
+```
+
+| Shape | Meaning |
+|---|---|
+| `GenerateRequest.system: string \| { stable, run? }` | `stable` is byte-identical across runs and is sent first, as its own block; `run` follows it |
+| `GenerateRequest.promptCache?: { session? }` | present: mark the stable system part and the transcript's tail, per `PROMPT_CACHE_RULES`. Absent: nothing is marked |
+| `agent({ promptCache })` | default `'auto'` — every turn carries the hint |
+| `llm({ promptCache })` | default `'off'` — a one-shot call would pay the write premium for a cache nothing reads |
+| `AgentTurn.usage` / `AgentTurn.run` | per turn, and the running total: `cacheReadTokens`, `cacheWriteTokens`, and `run.cost` priced once from the summed usage |
+
+`PROMPT_CACHE_RULES` (`src/prompt-cache.ts`, sources quoted in its header), first match wins:
+
+| Wire | Host | Model prefix | Marks | `session` |
+|---|---|---|---|---|
+| Anthropic Messages | any | any | stable system block + last block of the last two messages (3 of 4 breakpoints) | — |
+| chat completions | `openrouter.ai` | `anthropic/` | stable system part + the tail message's last part (2) | `x-session-id` header |
+| chat completions | `openrouter.ai` | any other | none (implicit caching; a mark on Gemini is a paid write) | `x-session-id` header |
+| chat completions | `api.openai.com` | any | none (automatic) | `prompt_cache_key` |
+| chat completions | anything else | any | none | — |
+
+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
+row's `cacheReadPerMillion` / `cacheWritePerMillion` (absent: 0.1x / 1.25x input). A token budget
+counts all four counters, one token each. The gateway's pre-flight estimate prices the prompt as a
+write only when a provider serving the model would mark it (`Provider.marksPromptCache`), at the
+dearer of the write and input rates. No `provider` routing object and no `usage: { include }` is
+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 |
+| 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 |
+
 ## `hive()` — many members, one action
 
 Fan an action out over many inputs. A factory over a primitive, like `llm()`, `backfill()` and
@@ -854,6 +935,8 @@ 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.
 
+`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
 `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,
@@ -882,13 +965,17 @@ fail-closed `terminal` default.
 | `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_AGENT_TOOL_UNEXPOSED` | an `agent()` lists a tool that is neither in-process nor an MCP-exposed action |
+| `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_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 |
 | `X_VECTOR_UNSCOPED` | a store with no tenant bound was read inside a request acting for an org; `scope: UNSCOPED` is the named opt-out |
 | `X_NOT_IMPLEMENTED` | a remote driver with no key or transport; the fix names the env var |
 
+A failure thrown after a provider call was started carries what the run was billed on `meta.billed` (`billedOf(error)` → `{ usage, cost, calls, unsettled }`); `unsettled` counts the calls whose bill cannot be known. [Agents → Unattended runs](https://github.com/developerz-ai/ultimate/wiki/Agents#unattended-runs).
+
 ### Error classes
 
 Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
@@ -896,7 +983,10 @@ a job boundary the class is gone and the `code` is what survives — match on th
 
 | Class | Code | Declared in |
 |---|---|---|
+| `AgentDeadlineError` | `X_AGENT_DEADLINE` | `src/agent-errors.ts` |
 | `AgentMaxTurnsError` | `X_AGENT_MAX_TURNS` | `src/errors.ts` |
+| `AgentToolLoopError` | `X_AGENT_TOOL_LOOP` | `src/agent-errors.ts` |
+| `AgentTranscriptInvalidError` | `X_AGENT_TRANSCRIPT_INVALID` | `src/agent-errors.ts` |
 | `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` |
@@ -919,7 +1009,8 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `LlmOutputInvalidError` | `X_LLM_OUTPUT_INVALID` | `src/errors.ts` |
 | `LlmRefusedError` | `X_LLM_REFUSED` | `src/errors.ts` |
 | `LlmStreamInvalidError` | `X_LLM_STREAM_INVALID` | `src/errors.ts` |
-| `LlmTruncatedError` | `X_LLM_TRUNCATED` | `src/errors.ts` |
+| `LlmToolArgumentsError` | `X_LLM_TOOL_ARGUMENTS_INVALID` | `src/answer-errors.ts` |
+| `LlmTruncatedError` | `X_LLM_TRUNCATED` | `src/answer-errors.ts` |
 | `VectorDimMismatchError` | `X_VECTOR_DIM_MISMATCH` | `src/errors.ts` |
 | `VectorScopeWidenedError` | `X_VECTOR_SCOPE_WIDENED` | `src/errors.ts` |
 | `VectorUnscopedError` | `X_VECTOR_UNSCOPED` | `src/vector-scope.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "27.8.1",
+  "version": "27.10.0",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -32,15 +32,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.8.1",
-    "@ultimat3/cache": "27.8.1",
-    "@ultimat3/core": "27.8.1",
-    "@ultimat3/db": "27.8.1",
-    "@ultimat3/http": "27.8.1",
-    "@ultimat3/jobs": "27.8.1",
-    "@ultimat3/money": "27.8.1",
-    "@ultimat3/policy": "27.8.1",
-    "@ultimat3/schema": "27.8.1",
-    "@ultimat3/time": "27.8.1"
+    "@ultimat3/action": "27.10.0",
+    "@ultimat3/cache": "27.10.0",
+    "@ultimat3/core": "27.10.0",
+    "@ultimat3/db": "27.10.0",
+    "@ultimat3/http": "27.10.0",
+    "@ultimat3/jobs": "27.10.0",
+    "@ultimat3/money": "27.10.0",
+    "@ultimat3/policy": "27.10.0",
+    "@ultimat3/schema": "27.10.0",
+    "@ultimat3/time": "27.10.0"
   }
 }