@ultimat3/ai 27.8.0 → 27.9.0

package/CLAUDE.md

@@ -28,7 +28,7 @@ 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`) |
+| `model-fixture.ts` | the rows this package's own suites register (`useFixtureModels()`). Not shipped |
 | `provider.ts` | `Provider` interface, the request half, the money arithmetic, `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 |
@@ -62,6 +62,10 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 | `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-system.ts` / `agent-usage.ts` | the declaration's types; the system one run sends; its running usage |
+| `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-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-job.ts` | `agentJob()` — an agent as a real `JobHandle`, composed from `job()` |
@@ -71,37 +75,30 @@ 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.
+- **Every numeric option is screened; `??` is not the screen** (`finiteOption`/`finiteCount`;
+  `bun run finite-bounds` is the ratchet, blind to a required option, a default parameter and a
+  cross-field product). **`maxTokens` is the worst**: it IS the budget's pre-flight estimate, and a
+  `NaN` switches every ceiling off — the gateway, `registerModel` (`maxOutput`) and `llm()`/`agent()`
+  (at DECLARATION) each screen theirs.
 - **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.
+- **`reserve` debits, then checks — never a read-then-write across an `await`.** The store's scopes
+  go through `BudgetStore.take(key, tokens, limit)`: REQUIRED, atomic (never `spent` + `add`). 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`).
+  `memoryBudgetStore()` has no window and no eviction (a ceiling bypass); 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.
+  — the gateway's ceilings, keyed `actor:<kind>:<id>` / `org:<orgId>` (none for an empty org).
+  `callLedger` is required on `Gateway`; `hive()` asks `installedGateway()`.
 - **`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.
@@ -131,10 +128,9 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
 - The gateway is ambient (`configureAi`); absent at call time is `X_AI_GATEWAY_MISSING`, never a
   default provider.
 - **`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; budget
+  reserved before the provider, reconciled at `done`. 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.
 - **Fallback is across PROVIDERS serving one model, never across models**; `GenerateResult.provider`
@@ -145,7 +141,7 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
   each hold half) — never deletes, never touches a template-only closer. The
   fences are read once at `definePrompt`; no hash moves.
 - `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
 
@@ -160,18 +156,14 @@ 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`. Every other
+  code but the two agent stops stays 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 (`asToolInput`); the credential is scrubbed from `detail`.
 - 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`.
@@ -188,11 +180,9 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
   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).
+- **Every provider serves the app's list**: `anthropicProvider({ models })` / `openAiProvider({ models })`
+  require a non-empty one (`X_AI_REQUEST_INVALID`); `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 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;
@@ -228,7 +218,8 @@ 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.
@@ -249,12 +240,11 @@ exposure, the whole input schema (an idempotent action's reserved `idempotencyKe
     rule a hive member's `reason` follows too. Never a second copy.
 - **`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,16 +253,30 @@ 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.
+  mean AND per case, both sides rounded as the baseline is written (`X_EVAL_BASELINE_MISSING` /
+  `X_EVAL_BASELINE_INVALID`). `baseline` is `import.meta.resolve('./…')`. Every prompt is named by an
+  eval (`X_EVAL_MISSING`). `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.
 - 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.

package/README.md

@@ -435,10 +435,81 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 | `onTurn` reports each completed turn as it happens (and an `agent.turn` span event, always) | a 90-second run emitted nothing until it returned. Observation only — it cannot steer the loop, see the transcript or reach the actor — and a throw from it fails the run rather than being swallowed |
 | a tool that is not `mcp: { expose: true }` is `X_AGENT_TOOL_UNEXPOSED` **at declaration** | a silently dropped tool reads as offered and is not; `isMcpExposed` is the one predicate, so an in-app agent and an external MCP client see the same catalogue |
 | running out of turns is `X_AGENT_MAX_TURNS`, never a partial answer | a half-finished transcript returned as a result is working notes presented as a decision |
+| 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 |
 
+### 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` vs the ledger | `AgentTurn.run.cost` is summed usage priced once; `gateway.spent()` adds each turn's cost, rounded up per turn (input and output halves), so it can be higher by under 2 minor units per turn. Budgets are enforced on the ledger; report `run.cost` |
+| 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
@@ -883,6 +954,8 @@ fail-closed `terminal` default.
 | `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_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 |
@@ -896,7 +969,9 @@ 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` |
 | `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "27.8.0",
+  "version": "27.9.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.0",
-    "@ultimat3/cache": "27.8.0",
-    "@ultimat3/core": "27.8.0",
-    "@ultimat3/db": "27.8.0",
-    "@ultimat3/http": "27.8.0",
-    "@ultimat3/jobs": "27.8.0",
-    "@ultimat3/money": "27.8.0",
-    "@ultimat3/policy": "27.8.0",
-    "@ultimat3/schema": "27.8.0",
-    "@ultimat3/time": "27.8.0"
+    "@ultimat3/action": "27.9.0",
+    "@ultimat3/cache": "27.9.0",
+    "@ultimat3/core": "27.9.0",
+    "@ultimat3/db": "27.9.0",
+    "@ultimat3/http": "27.9.0",
+    "@ultimat3/jobs": "27.9.0",
+    "@ultimat3/money": "27.9.0",
+    "@ultimat3/policy": "27.9.0",
+    "@ultimat3/schema": "27.9.0",
+    "@ultimat3/time": "27.9.0"
   }
 }

package/src/agent-def.ts

@@ -0,0 +1,111 @@
+// Single responsibility: what an `agent()` DECLARATION is — its options, and the one event its
+// observer is handed. Types only; ./agent owns the loop that reads them.
+
+import type { ActionMcp, ActionPolicy } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { AgentSystem } from './agent-system';
+import type { AgentRunUsage } from './agent-usage';
+import type { LlmBudget } from './llm';
+import type { ModelId } from './models';
+import type { Prompt, PromptVars } from './prompt';
+import type { PromptCacheOption } from './prompt-cache';
+import type { StopReason, TokenUsage } from './provider';
+import type { AgentTool } from './tools';
+
+export interface AgentBudget extends LlmBudget {
+  /**
+   * Token ceiling for the WHOLE run, every turn counted. The one ceiling `llm()` does not need:
+   * a single call is bounded by `maxTokens`, a loop is bounded by nothing until this is set.
+   */
+  readonly tokensPerRun?: number;
+}
+
+export interface AgentVarsArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface AgentDef<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+> {
+  readonly model?: ModelId;
+  readonly input: TInput;
+  readonly output: TOutput;
+  readonly prompt: Prompt<V>;
+  /** Same contract as `llm()`: the one declared place a run loads data. */
+  vars(args: AgentVarsArgs<TInput>): V | Promise<V>;
+  /**
+   * System text loaded at RUN time, beside the prompt's static `system`: a knowledge-base index,
+   * today's date. Redacted like the prompt. Not part of the prompt's hash, exactly as `vars` is not.
+   */
+  system?(args: AgentVarsArgs<TInput>): AgentSystem | Promise<AgentSystem>;
+  /**
+   * Provider prompt caching. Default `'auto'`: every turn's request asks the provider to cache its
+   * prefix (the stable system block, then the transcript up to its tail), so turn N+1 reads turn
+   * N's prefix at the cache rate instead of paying input for it again. `'off'` sends no mark.
+   * `{ session }` is `'auto'` plus a key for hosts that route by one. `PROMPT_CACHE_RULES` decides
+   * what each wire is sent; a host that caches implicitly is sent nothing either way.
+   */
+  readonly promptCache?: PromptCacheOption<AgentVarsArgs<TInput>>;
+  /**
+   * The actions the model may call. Each must be `mcp: { expose: true }` — the same predicate an
+   * external MCP client is filtered by, so an in-app agent and an external one are offered
+   * exactly the same tools. Listing one that is not exposed is refused at declaration rather than
+   * dropped, because a tool that reads as offered and silently is not is the worst of both.
+   */
+  readonly tools: readonly AgentTool[];
+  /** Hard ceiling on model turns. Reaching it is `X_AGENT_MAX_TURNS`, never a partial answer. */
+  readonly maxTurns?: number;
+  readonly maxToolResultChars?: number;
+  /**
+   * Consecutive turns that may make the SAME tool calls and read the SAME results. Reaching it is
+   * `X_AGENT_TOOL_LOOP`. Default 3.
+   */
+  readonly maxRepeatedToolCalls?: 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.
+   */
+  readonly deadlineMs?: number;
+  readonly budget?: AgentBudget;
+  readonly policy: ActionPolicy;
+  readonly mcp?: ActionMcp;
+  /** Enforced completion ceiling PER TURN. The model never sees it. */
+  readonly maxTokens?: number;
+  /**
+   * Called once per completed model turn, before the answer or the tool calls are acted on. The
+   * one thing a multi-turn run could not do until 2026-08: a 90-second loop emitted nothing until
+   * it returned, so a progress indicator, a per-turn spend line and a transcript log all had to be
+   * hand-rolled outside the framework — which is exactly the loop `agent()` exists to replace.
+   *
+   * Observation only: it cannot steer the loop, cannot see the transcript and cannot reach the
+   * actor. A throw from it FAILS the run rather than being swallowed — it is the app's code on the
+   * run's own path, and an observer that silently stopped working would be indistinguishable from
+   * one that is fine. The same facts land on the span as an `agent.turn` event, so a run that
+   * declares no hook is still readable in a trace.
+   *
+   * NOT `.stream()`. Tokens on a screen is a different contract, and `llm()`'s streamed half is
+   * one turn deep by construction; this is per TURN.
+   */
+  onTurn?(event: AgentTurn): void | Promise<void>;
+}
+
+/** One completed model turn, as an observer sees it. Facts only — no transcript, no actor. */
+export interface AgentTurn {
+  /** 1-based, so `turn === maxTurns` is the last one this run will take. */
+  readonly turn: number;
+  readonly maxTurns: number;
+  readonly model: ModelId;
+  /** Tools this turn asked for, in the order the model emitted them. `respond` is not one. */
+  readonly toolCalls: readonly string[];
+  readonly stopReason: StopReason;
+  readonly usage: TokenUsage;
+  /** This turn's cost alone, integer minor units — never the run's running total. */
+  readonly cost: Money;
+  /** The running total, this turn included — on the last turn, the whole run. */
+  readonly run: AgentRunUsage;
+}

package/src/agent-errors.ts

@@ -0,0 +1,50 @@
+// The two X_AGENT_* codes an UNATTENDED run needs, apart from ./errors only because one file has
+// one job and that catalogue is at its ceiling — the split `hive-errors.ts` made. The codes, their
+// titles and the single `registerErrorCodes` call stay in ./errors.
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * The loop asked for the same tool calls and read the same results, turn after turn.
+ *
+ * Call AND result, never the call alone: polling one tool with one argument is legitimate while
+ * what comes back keeps changing, and it stops being progress the moment it does not. A turn that
+ * repeats both can only be followed by a turn that repeats both, so every further turn buys the
+ * same non-answer over a transcript that is one turn longer.
+ */
+export class AgentToolLoopError extends UltimateError {
+  constructor(input: {
+    agent: string;
+    /** Laps of the cycle. */
+    repeats: number;
+    /** Turns in one lap: 1 is the same turn over and over, 2 is A,B,A,B. */
+    cycle: number;
+    tools: readonly string[];
+  }) {
+    super({
+      code: 'X_AGENT_TOOL_LOOP',
+      cause:
+        input.cycle === 1
+          ? `agent "${input.agent}" made the same tool calls (${input.tools.join(', ')}) and read the same results ${input.repeats} turns in a row`
+          : `agent "${input.agent}" went round the same ${input.cycle} tool turns (${input.tools.join(', ')}), reading the same results, ${input.repeats} times in a row`,
+      fix: 'maxRepeatedToolCalls: 5   # on the agent, ONLY for a tool that is polled and answers identically while it waits — otherwise tell the template what to do when a tool result does not change, then bump its version',
+      meta: { agent: input.agent, repeats: input.repeats, cycle: input.cycle, tools: input.tools },
+    });
+  }
+}
+
+/**
+ * The run was still going when its declared `deadlineMs` elapsed. Distinct from `X_ABORTED` — the
+ * caller did not leave, the declaration ran out — and from `X_AGENT_MAX_TURNS`, because the fix is
+ * about wall clock: a slow tool or a slow model, not a loop with no exit.
+ */
+export class AgentDeadlineError extends UltimateError {
+  constructor(input: { agent: string; deadlineMs: number }) {
+    super({
+      code: 'X_AGENT_DEADLINE',
+      cause: `agent "${input.agent}" was still running after its ${input.deadlineMs}ms deadline; whatever was in flight (setup, a model call or a tool) was signalled to stop, and no further turn or tool was started`,
+      fix: 'deadlineMs: 300_000   # on the agent, only once a trace shows the run converging — otherwise lower maxTurns, or shorten the slow tool the agent.turn span events name',
+      meta: { agent: input.agent, deadlineMs: input.deadlineMs },
+    });
+  }
+}

package/src/agent-guards.ts

@@ -0,0 +1,114 @@
+// Single responsibility: the two guards that let an `agent()` run with nobody watching — the
+// repeated-turn detector and the per-run deadline. Apart from ./agent so the loop reads as a loop.
+
+import { fingerprint, withChildContext } from '@ultimat3/core';
+import { AgentDeadlineError, AgentToolLoopError } from './agent-errors';
+import type { LlmToolCall, LlmToolResult } from './tools';
+
+/**
+ * Consecutive identical turns an agent may take when the declaration omits a number. Three: one
+ * repeat is a model re-checking, two is a model that has not read the answer, and nothing a third
+ * identical turn returns can make the fourth differ.
+ */
+export const DEFAULT_MAX_REPEATED_TOOL_CALLS = 3;
+
+/** The longest cycle looked for: A,B,C,A,B,C. A longer one is `maxTurns`' to stop. */
+const MAX_CYCLE = 3;
+
+/**
+ * Called once per TOOL turn, with what the model asked for and what it was told. Throws
+ * `X_AGENT_TOOL_LOOP` when the most recent tool turns are one cycle of up to `MAX_CYCLE` turns
+ * gone round `limit` times — the same turn `limit` times, or A,B,A,B… — where "the same" is the
+ * calls, their arguments, the results AND whether each failed. A changed result is progress and
+ * breaks the cycle. A fingerprint, not the text: one result can be megabytes before truncation.
+ *
+ * A repair turn (a wrong-shaped answer; no tool ran) is not a tool turn, so it neither counts nor
+ * resets: the correction is about the answer's shape and tells the model nothing new about a tool.
+ */
+export function toolLoopGuard(
+  agent: string,
+  limit: number,
+): (calls: readonly LlmToolCall[], results: readonly LlmToolResult[]) => void {
+  const window = MAX_CYCLE * limit;
+  let recent: readonly { readonly shape: string; readonly tools: readonly string[] }[] = [];
+  return (calls, results) => {
+    const shape = fingerprint({
+      calls: calls.map((call) => [call.name, call.input]),
+      results: results.map((result) => [result.content, result.isError === true]),
+    });
+    recent = [...recent, { shape, tools: calls.map((call) => call.name) }].slice(-window);
+    for (let cycle = 1; cycle <= MAX_CYCLE; cycle += 1) {
+      const laps = recent.slice(-cycle * limit);
+      if (laps.length < cycle * limit) break;
+      const repeats = (turn: (typeof laps)[number], index: number): boolean =>
+        index < cycle || isSameTurn(turn.shape, laps[index - cycle]?.shape);
+      if (!laps.every(repeats)) continue;
+      const tools = [...new Set(laps.slice(0, cycle).flatMap((turn) => turn.tools))];
+      throw new AgentToolLoopError({ agent, repeats: limit, cycle, tools });
+    }
+  };
+}
+
+const isSameTurn = (one: string, other: string | undefined): boolean => one === other;
+
+export interface RunDeadline {
+  /** The caller's signal and the deadline as one — what every provider call is handed. */
+  readonly signal: AbortSignal;
+  /** Throws `X_AGENT_DEADLINE` once the deadline has passed. Called before each turn and batch. */
+  check(): void;
+  /**
+   * Await `work`, but no longer than the deadline, and report a failure the deadline caused AS the
+   * deadline: the aborted socket surfaces as a transport error, which would otherwise read as the
+   * provider's fault. Work that outlives the race is left to finish — a tool has no signal to hear.
+   */
+  guard<T>(work: Promise<T>): Promise<T>;
+  /**
+   * Run `fn` with the deadline on the ambient `ctx.signal`, so a tool — an `action()` reading its
+   * own `ctx.signal`, a `fetch(url, { signal })` inside it — hears the deadline and can stop. A
+   * tool that never reads the signal still runs to its own end after the run has been refused.
+   */
+  scope<T>(fn: () => T): T;
+}
+
+/** `ms` undefined is no deadline: the caller's signal, and two no-ops. */
+export function runDeadline(
+  agent: string,
+  ms: number | undefined,
+  caller: AbortSignal,
+): RunDeadline {
+  if (ms === undefined) {
+    return { signal: caller, check: () => {}, guard: (work) => work, scope: (fn) => fn() };
+  }
+  const timer = AbortSignal.timeout(ms);
+  const expired = (): AgentDeadlineError => new AgentDeadlineError({ agent, deadlineMs: ms });
+  // The caller leaving first stays `X_ABORTED`: it is the truer account of why the run stopped.
+  const byDeadline = (): boolean => timer.aborted && !caller.aborted;
+  return {
+    signal: AbortSignal.any([caller, timer]),
+    scope: (fn) => withChildContext({ signal: timer }, fn),
+    check: () => {
+      if (byDeadline()) throw expired();
+    },
+    guard: async (work) => {
+      if (byDeadline()) {
+        // Abandoned before it was awaited; its own rejection must not go unhandled.
+        work.catch(() => {});
+        throw expired();
+      }
+      let stop = (): void => {};
+      const timeout = new Promise<never>((_, reject) => {
+        stop = () => reject(expired());
+        timer.addEventListener('abort', stop, { once: true });
+      });
+      try {
+        return await Promise.race([work, timeout]);
+      } catch (error) {
+        work.catch(() => {});
+        if (byDeadline()) throw expired();
+        throw error;
+      } finally {
+        timer.removeEventListener('abort', stop);
+      }
+    },
+  };
+}