@ultimat3/ai 27.8.1 → 27.10.0

package/src/agent.ts

@@ -20,169 +20,73 @@
  * one run's world state to another. Version bump plus the tools' own caching is the story.
  */
 
-import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import type { Action } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
-import type { Ctx, Span } from '@ultimat3/core';
-import { finiteCount, isMcpExposed, throwIfAborted, withSpan } from '@ultimat3/core';
-import type { Money } from '@ultimat3/money';
+import type { Ctx } from '@ultimat3/core';
+import { throwIfAborted, withSpan } from '@ultimat3/core';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
-import type { AgentFact } from './agent-facts';
+import type { AgentAction, TranscriptBinding } from './agent-continue';
+import {
+  claimAgentSession,
+  continued,
+  screenTranscript,
+  sealTranscript,
+  sessionCalls,
+  withTranscript,
+} from './agent-continue';
+import type { AgentBounds } from './agent-declared';
+import { factsOf, limitsOf, SUBJECT, screenBounds } from './agent-declared';
+import type { AgentDef } from './agent-def';
+import { AgentTranscriptInvalidError } from './agent-errors';
 import { registerAgentFact } from './agent-facts';
+import { runDeadline, toolLoopGuard } from './agent-guards';
+import { sameSystem, systemOf } from './agent-system';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
-import type { BudgetLimits } from './budget';
-import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
-import {
-  AgentMaxTurnsError,
-  AgentToolUnexposedError,
-  LlmOutputInvalidError,
-  LlmRefusedError,
-  LlmTruncatedError,
-} from './errors';
-import type { LlmBudget } from './llm';
+import { assertAnswerable, observeTurn } from './agent-turn';
+import { runTotal } from './agent-usage';
+import { LlmTruncatedError } from './answer-errors';
+import { budgetKeysFor, currentBudget, withBudget } from './budget';
+import { AgentMaxTurnsError, AgentToolUnexposedError, LlmOutputInvalidError } from './errors';
 import { answerAttributes } from './llm';
-import { describedModel, type ModelSource, modelForCall } from './model-resolve';
-import type { ModelId } from './models';
-import { moreCapableThan } from './models';
-import type { Prompt, PromptVars } from './prompt';
-import type {
-  AiMessage,
-  GenerateRequest,
-  GenerateResult,
-  StopReason,
-  TokenUsage,
-} from './provider';
+import { modelForCall } from './model-resolve';
+import type { PromptVars } from './prompt';
+import { promptCacheHint } from './prompt-cache';
+import type { AiMessage, GenerateRequest } from './provider';
 import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
 import type { Respond } from './respond';
 import { RESPOND, respondFor } from './respond';
+import { runMeter } from './run-meter';
 import { aiGateway, aiRedactor, installedGateway } from './runtime';
+import type { Sampling } from './sampling';
+import { ignoredSampling, screenSampling } from './sampling';
 import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
-import { asProjectableAction, runLlmToolCall, toLlmTools, toolLabel } from './tools';
-
-/**
- * Turn ceiling when the declaration omits one. Low on purpose: a loop that needs more than this
- * is usually a loop with no exit condition, and every turn re-sends the whole transcript, so cost
- * grows quadratically in turns rather than linearly.
- */
-const DEFAULT_MAX_TURNS = 8;
-
-/** Output ceiling per turn when the declaration omits one. Same reasoning as `llm()`'s. */
-const DEFAULT_MAX_TOKENS = 4_096;
-
-/**
- * Characters of ONE tool result the model may read. A tool that returns a 2MB row set otherwise
- * spends the whole context window on turn two and every later turn re-sends it — the transcript
- * is the request, so an untruncated result is billed once per remaining turn.
- */
-const DEFAULT_TOOL_RESULT_CHARS = 4_000;
-
-/** Named in every bound refusal, so the fix names the key the declaration carries. */
-const SUBJECT = 'agent';
-
-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>;
-  /**
-   * 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;
-  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>;
-}
+import { asProjectableAction, isOfferedTool, runLlmToolCall, toLlmTools, toolLabel } from './tools';
 
-/** 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;
-}
+export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent-def';
 
 export function agent<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
->(def: AgentDef<TInput, TOutput, V>): Action<TInput, TOutput> {
+>(def: AgentDef<TInput, TOutput, V>): AgentAction<TInput, TOutput> {
   const respond = respondFor(def.output);
   // At declaration, because the tools are values by then and a run that discovers this at the
   // first request has already been declared, registered and projected as if it worked. Asked of
   // the DECLARATION rather than of the projection: `isMcpExposed` needs no name, and a real
   // `action()` beside this one in the same module has none until `registerActions` runs at boot.
-  const unexposed = def.tools.filter((tool) => !isMcpExposed(tool.mcp));
+  const unexposed = def.tools.filter((tool) => !isOfferedTool(tool));
   if (unexposed.length > 0) {
     throw new AgentToolUnexposedError({
       agent: def.prompt.ref,
       tools: unexposed.map(toolLabel),
     });
   }
-  // The three loop bounds, screened at DECLARATION for the same reason the tool check above is:
-  // the values are here, and an `agent()` runs at module scope, so a bound that is not one fails
-  // the boot instead of the ninetieth second of a run. None of them is checked by what it lands
-  // on — `turn <= NaN` is false on the FIRST comparison, so the loop takes zero turns and reports
-  // `X_AGENT_MAX_TURNS` about a model that was never called; `slice(0, NaN)` is `''`, so every
-  // tool result reaches the model empty while the run keeps paying for turns; and `maxTokens`
-  // becomes the pre-flight estimate, where a `NaN` disables the ledger for the whole process.
-  finiteCount(SUBJECT, 'maxTurns', def.maxTurns ?? DEFAULT_MAX_TURNS, 1);
-  finiteCount(
-    SUBJECT,
-    'maxToolResultChars',
-    def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
-    1,
-  );
-  finiteCount(SUBJECT, 'maxTokens', def.maxTokens ?? DEFAULT_MAX_TOKENS, 1);
+  const bounds = screenBounds(def);
+  // This declaration's identity for `.run()` / `.continue()` sessions (`claimAgentSession`).
+  const owner = {};
+  const sampling = screenSampling(SUBJECT, def);
   // Projected on FIRST RUN, memoised, for the reason above: `agent()` is evaluated at module
   // scope and a tool's name is stamped by `registerAction` at boot, so naming it here would make
   // the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
@@ -196,48 +100,27 @@ export function agent<
     output: def.output,
     policy: def.policy,
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
-    handle: (args) => run(def, respond, adapt(), args),
+    handle: (args) => run(def, respond, adapt(), { ...bounds, sampling, owner }, args),
   });
   // A thunk, resolved when the manifest asks: every name in the row is stamped at boot, and this
   // line runs at module scope.
   registerAgentFact(built, () => factsOf(def));
-  return built;
+  return continuable(built, owner);
 }
 
-// `null`, not `undefined`, for a row naming no model yet: the row is a published fact, and an
-// absent key reads as a reader that forgot to ask.
-const modelFact = (described: {
-  readonly model: string | undefined;
-  readonly from: ModelSource | undefined;
-}): Pick<AgentFact, 'model' | 'modelFrom'> => ({
-  model: described.model ?? null,
-  modelFrom: described.from ?? null,
-});
-
-function factsOf<
-  TInput extends StandardSchemaV1,
-  TOutput extends StandardSchemaV1,
-  V extends PromptVars,
->(def: AgentDef<TInput, TOutput, V>): Omit<AgentFact, 'name'> {
-  const budget = def.budget;
-  return {
-    prompt: def.prompt.ref,
-    promptId: def.prompt.id,
-    promptHash: def.prompt.hash,
-    // The run's own precedence, so the row names the model a call would use NOW: read when the
-    // facts are, at describe time, like every name in the row. `modelFrom` says which place
-    // answered — `gateway` (or `null`, none yet) depends on the gateway installed at that moment.
-    ...modelFact(describedModel(def.model, def.prompt.model, installedGateway()?.defaultModel)),
-    maxTurns: def.maxTurns ?? DEFAULT_MAX_TURNS,
-    maxToolResultChars: def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
-    tools: [...def.tools.map(toolLabel)].sort(),
-    budget: {
-      tokensIn: budget?.tokensIn ?? null,
-      tokensPerRun: budget?.tokensPerRun ?? null,
-      costPerCall: budget?.costPerCall ?? null,
-    },
-    mcp: isMcpExposed(def.mcp),
-  };
+/**
+ * Attach `.run()` and `.continue()` IN PLACE, for the reason `llm()`'s `streamable` gives: the
+ * object an app exported is the one the registry names, and `named()`'s twin gets them too.
+ */
+function continuable<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+  owner: object,
+): AgentAction<TInput, TOutput> {
+  const rename = target.named.bind(target);
+  return Object.assign(target, {
+    ...sessionCalls(target, owner),
+    named: (next: string): AgentAction<TInput, TOutput> => continuable(rename(next), owner),
+  });
 }
 
 /** The tools as `runLlmToolCall` consumes them, and as the request offers them. One projection. */
@@ -259,22 +142,50 @@ async function run<
   def: AgentDef<TInput, TOutput, V>,
   respond: Respond,
   adapted: Adapted,
+  bounds: AgentBounds & { readonly sampling: Sampling; readonly owner: object },
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
   const name = prompt.ref;
+  // A `.continue()` in flight: its handle is the app's stored data, so it is screened before
+  // anything is loaded, reserved or sent.
+  const session = claimAgentSession(bounds.owner);
+  const resume = session?.resume;
+  if (resume !== undefined && resume.user.trim() === '') {
+    throw new AgentTranscriptInvalidError({ agent: name, reason: 'the user turn is empty' });
+  }
   // Screened first: a bad declaration is refused whether or not a gateway exists.
-  const limits = limitsOf(def);
+  limitsOf(def);
   // The declaration, its prompt, then the gateway's `defaultModel` — the app's three places.
   const model = modelForCall('agent', name, def.model, prompt.model);
-  const vars = await def.vars({ input: args.input, ctx: args.ctx });
-  assertNoSecrets(name, vars);
+  // What a handle is bound to, read off the declaration and the request — never off the handle.
+  const binding: TranscriptBinding = {
+    agent: name,
+    model,
+    tools: [...adapted.tools.map((tool) => tool.name), RESPOND],
+    org: args.ctx.actor.orgId ?? null,
+  };
+  const prior = resume === undefined ? undefined : screenTranscript(binding, resume.transcript);
+  const limits = limitsOf(def, prior?.usage);
+  // Armed before anything is loaded: `vars()` is part of the run a deadline bounds.
+  const deadline = runDeadline(name, def.deadlineMs, args.ctx.signal);
   const redact = aiRedactor();
-  const rawPrompt = prompt.render(vars);
+  // A continuation does not render the prompt again: the transcript holds what was sent, and
+  // `vars()` — the load — is not run a second time. Its own turn is the caller's text.
+  let rawPrompt = resume?.user;
+  if (rawPrompt === undefined) {
+    const vars = await deadline.guard(Promise.resolve(def.vars(args)));
+    assertNoSecrets(name, vars);
+    rawPrompt = prompt.render(vars);
+  }
   const rendered = redact(rawPrompt);
-  const system = prompt.system === undefined ? undefined : redact(prompt.system);
-  const maxTurns = def.maxTurns ?? DEFAULT_MAX_TURNS;
-  const chars = def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS;
+  const extra =
+    def.system === undefined ? {} : await deadline.guard(Promise.resolve(def.system(args)));
+  const rawSystem = systemOf(prompt.system, extra, (text) => text);
+  const system = systemOf(prompt.system, extra, redact);
+  const promptCache = promptCacheHint(def.promptCache, 'auto', args);
+  const repeated = toolLoopGuard(name, bounds.maxRepeatedToolCalls);
+  const { maxTurns, maxToolResultChars: chars } = bounds;
 
   return withSpan('ai.agent', async (span) => {
     span.setAttributes({
@@ -283,7 +194,13 @@ async function run<
       'agent.prompt.hash': prompt.hash,
       'agent.tools': adapted.offered.length,
       'agent.max_turns': maxTurns,
-      'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
+      'llm.redacted': rendered !== rawPrompt || !sameSystem(system, rawSystem),
+      'llm.prompt_cache': promptCache !== undefined,
+      'llm.sampling.ignored': ignoredSampling(
+        model,
+        bounds.sampling,
+        installedGateway()?.samplingWires?.(model),
+      ).join(','),
     });
 
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
@@ -295,31 +212,54 @@ async function run<
     const base: GenerateRequest = {
       model,
       ...(system === undefined ? {} : { system }),
+      ...(promptCache === undefined ? {} : { promptCache }),
       messages: [],
-      maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
+      maxTokens: bounds.maxTokens,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
+      ...bounds.sampling,
       tools: [...adapted.offered, respond.tool],
       // The caller's own signal, forwarded to the transport. A disconnect has to reach the socket,
       // not just the top of the next turn: a provider call already in flight is the expensive one.
-      signal: args.ctx.signal,
+      // The run's deadline is folded into the same signal, so it reaches the socket too.
+      signal: deadline.signal,
     };
 
-    return withBudget(ledger, async () => {
+    // Every provider call below goes through the meter, so whatever ends the run — a ceiling, a
+    // deadline, a truncated turn, the caller leaving — is thrown carrying what the run was billed.
+    const meter = runMeter();
+    const disclosure = { discloseErrors: def.discloseToolErrors !== false };
+    // Where a failure would resume from: the request in flight, and the turns answered so far.
+    const at = { messages: [] as readonly AiMessage[], turns: prior?.turns ?? 0 };
+    const loop = async (): Promise<InferOutput<TOutput>> => {
       // The actor is read ONCE, from the context the request established, and is the only
       // identity any tool runs as. Nothing below reads an actor out of `result` — a model cannot
       // name the identity it acts as, and a loop that let it would be an escalation primitive.
       const { actor } = args.ctx;
-      let messages: readonly AiMessage[] = [{ role: 'user', content: rendered }];
+      let messages: readonly AiMessage[] =
+        prior === undefined ? [{ role: 'user', content: rendered }] : continued(prior, rendered);
       let calls = 0;
       let issues: string | undefined;
+      // The issues of the answer the turn in flight is repairing — `onTurn`'s `repairOf`.
+      let rejected: readonly string[] | undefined;
 
-      for (let turn = 1; turn <= maxTurns; turn += 1) {
+      // `maxTurns` counts the run AND its continuations: a handle that used them all takes none.
+      for (let turn = at.turns + 1; turn <= maxTurns; turn += 1) {
+        at.messages = messages;
         // The caller is gone, so unwind instead of finishing. Every turn re-sends the WHOLE
         // transcript, so a loop that keeps going after a disconnect spends the rest of the run's
         // budget, runs every remaining tool's side effects, and discards the answer.
         throwIfAborted(args.ctx);
-        const result = await gateway.generate({ ...base, messages });
+        deadline.check();
+        const result = await deadline
+          .guard(meter.call(gateway.generate({ ...base, messages })))
+          .catch((error: unknown) => {
+            // The caller left mid-call: the aborted socket reads as a provider failure, which is
+            // RETRYABLE. Say what happened instead.
+            throwIfAborted(args.ctx);
+            throw error;
+          });
+        at.turns = turn;
         const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
         // The same turn's `respond` calls, kept rather than forgotten: they are never RUN, but
         // `assistantTurn` replays them, and every replayed `tool_use` has to be answered.
@@ -337,8 +277,22 @@ async function run<
           stopReason: result.stopReason,
           usage: result.usage,
           cost: result.cost,
+          ...(result.costExact === undefined ? {} : { costExact: result.costExact }),
+          ...(rejected === undefined ? {} : { repairOf: rejected }),
+          run: runTotal(result.model, prior?.usage, meter.total(), meter.below()),
         });
         assertAnswerable(result, name, base);
+        // Before a tool runs and before the answer is read: a turn cut off at the ceiling carries
+        // arguments that stop wherever the ceiling fell — `{}` on both wires for a call that never
+        // reached its first byte — so running a tool on them is a side effect the model did not
+        // ask for, and validating them accepts an empty answer for any `output` of optional keys.
+        if (isTruncated(result.stopReason)) {
+          throw new LlmTruncatedError({
+            prompt: name,
+            maxTokens: base.maxTokens,
+            subject: SUBJECT,
+          });
+        }
 
         if (requested.length > 0) {
           // Concurrent, and deliberately unbounded WITHIN one turn: the batch is what a single
@@ -352,10 +306,20 @@ async function run<
           // result carries the `tool_use` id `runLlmToolCall` was handed, so a fast tool answering
           // first cannot be paired with a slow tool's call.
           throwIfAborted(args.ctx);
-          const results: readonly LlmToolResult[] = await Promise.all(
-            requested.map((call) => runLlmToolCall(adapted.tools, call, actor)),
+          deadline.check();
+          const results: readonly LlmToolResult[] = await deadline.guard(
+            // Inside the deadline's scope, so each tool's own `ctx.signal` carries it.
+            deadline.scope(() =>
+              Promise.all(
+                requested.map((call) => runLlmToolCall(adapted.tools, call, actor, disclosure)),
+              ),
+            ),
           );
           calls += requested.length;
+          rejected = undefined;
+          // Before the next turn is bought: the same calls with the same results cannot lead
+          // anywhere a further turn would not also lead.
+          repeated(requested, results);
           messages = [
             ...messages,
             assistantTurn(result),
@@ -370,79 +334,55 @@ async function run<
         }
 
         const parsed = await validateAsync(def.output, respond.read(result));
-        if (parsed.issues === undefined) return parsed.value;
+        if (parsed.issues === undefined) {
+          // Kept only for `.run()` / `.continue()`: a plain call leaves nothing behind.
+          if (session !== undefined) {
+            const usage = runTotal(result.model, prior?.usage, meter.total(), meter.below());
+            session.finished = {
+              transcript: sealTranscript(binding, {
+                messages: [...messages, assistantTurn(result)],
+                turns: turn,
+                usage: usage.usage,
+              }),
+              turns: turn,
+              usage,
+            };
+          }
+          return parsed.value;
+        }
         // A wrong shape gets another turn like any other, because unlike `llm()` this loop has
         // turns left by construction — and unlike a tool result, the correction is the message.
-        issues = formatIssues(parsed.issues).join('; ');
-        if (isTruncated(result.stopReason)) {
-          throw new LlmTruncatedError({ prompt: name, maxTokens: base.maxTokens });
-        }
+        rejected = formatIssues(parsed.issues);
+        issues = rejected.join('; ');
         messages = [...messages, assistantTurn(result), repairTurn(answers, issues)];
       }
 
+      at.messages = messages;
       // Two different exhaustions, so two different causes: a loop that kept calling tools and
       // never answered is not the same event as one that answered the wrong shape every time.
       if (issues !== undefined) {
-        throw new LlmOutputInvalidError({ prompt: name, attempts: maxTurns, issues });
+        throw new LlmOutputInvalidError({
+          prompt: name,
+          attempts: maxTurns,
+          issues,
+          ...(rejected === undefined ? {} : { list: rejected }),
+        });
       }
       throw new AgentMaxTurnsError({ agent: name, turns: maxTurns, calls });
-    });
-  });
-}
-
-/**
- * One turn, reported twice: onto the span every run already opens, and to the declaration's own
- * hook. The span event is free — nothing to install, and a trace is where a stalled run is
- * actually diagnosed — and the hook is what a progress indicator or a per-turn spend line reads.
- *
- * Awaited, and not guarded: a throw from `onTurn` fails the run. It is the app's code on the run's
- * path, and an observer that quietly stopped working reads exactly like one that is fine.
- */
-async function observeTurn<
-  TInput extends StandardSchemaV1,
-  TOutput extends StandardSchemaV1,
-  V extends PromptVars,
->(def: AgentDef<TInput, TOutput, V>, span: Span, event: AgentTurn): Promise<void> {
-  span.addEvent('agent.turn', {
-    'agent.turn': event.turn,
-    'agent.turn.tool_calls': event.toolCalls.length,
-    'llm.stop': event.stopReason,
-    'llm.cost.minor': event.cost.minor,
-  });
-  await def.onTurn?.(event);
-}
-
-/** Refuse before the answer is read, for the reason `llm()` does: a refusal is a 200 with no answer. */
-function assertAnswerable(result: GenerateResult, name: string, request: GenerateRequest): void {
-  if (result.stopReason !== 'refusal') return;
-  throw new LlmRefusedError({
-    prompt: name,
-    model: result.model,
-    alternative: moreCapableThan(result.model, request),
-    category: result.stopDetails?.category,
-    explanation: result.stopDetails?.explanation,
+    };
+    return withBudget(ledger, () =>
+      meter.within(loop).catch((error: unknown) => {
+        const failed = meter.fail(error);
+        // A failed `.run()` / `.continue()` leaves a handle too: the transcript up to the request
+        // the failed turn was answering, with `turns` and `usage` counting what this call was
+        // billed. Without it a retry resumes from the OLD handle, which never heard of that spend
+        // — six truncated continuations billed six times against a ceiling that saw none of them.
+        if (session !== undefined && at.messages.length > 0) {
+          const { usage } = runTotal(model, prior?.usage, meter.billed());
+          withTranscript(failed, sealTranscript(binding, { ...at, usage }));
+        }
+        throw failed;
+      }),
+    );
   });
 }
-
-function limitsOf<
-  TInput extends StandardSchemaV1,
-  TOutput extends StandardSchemaV1,
-  V extends PromptVars,
->(def: AgentDef<TInput, TOutput, V>): BudgetLimits {
-  const budget = def.budget;
-  return {
-    // Screened under the names the DECLARATION uses, not the ledger's: `tokensPerRun` arrives at
-    // `BudgetLimits` as `request`, and a fix line naming a key the app never wrote is not a fix.
-    ...(budget?.tokensIn === undefined
-      ? {}
-      : { tokensIn: finiteCount(SUBJECT, 'budget.tokensIn', budget.tokensIn) }),
-    ...(budget?.costPerCall === undefined
-      ? {}
-      : { costPerCall: screenedMoney(SUBJECT, 'budget.costPerCall', budget.costPerCall) }),
-    // The ledger's `request` scope accumulates across every call made under one ledger, which for
-    // a run under `withBudget` is exactly "the whole run".
-    ...(budget?.tokensPerRun === undefined
-      ? {}
-      : { request: finiteCount(SUBJECT, 'budget.tokensPerRun', budget.tokensPerRun) }),
-  };
-}

package/src/answer-errors.ts

@@ -0,0 +1,88 @@
+// The two failures of an answer that ARRIVED and cannot be used: cut off at the ceiling, or a tool
+// call whose arguments do not parse. Apart from ./errors only because one file has one job and
+// that catalogue is at its line ceiling — the split `hive-errors.ts` and `agent-errors.ts` made.
+// The codes, their titles and the single `registerErrorCodes` call stay in ./errors.
+
+import { UltimateError } from '@ultimat3/core';
+import type { Billed } from './billed';
+import { BILLED_META } from './billed';
+
+/**
+ * The answer was cut off at the enforced ceiling. Thrown BEFORE the answer is read, and instead of
+ * a repair turn: a cut-off `respond` call arrives with no arguments, which both wires read as `{}`
+ * and an `output` of optional keys accepts — and the ceiling does not move between attempts, so a
+ * second answer truncates at exactly the same place and only spends money.
+ */
+export class LlmTruncatedError extends UltimateError {
+  constructor(input: {
+    prompt: string;
+    maxTokens: number;
+    /** The factory whose declaration carries the ceiling. */
+    subject?: 'llm' | 'agent';
+  }) {
+    super({
+      code: 'X_LLM_TRUNCATED',
+      cause: `prompt "${input.prompt}" was cut off at its ${input.maxTokens}-token ceiling`,
+      fix: `maxTokens: ${input.maxTokens * 2}   # on the ${input.subject ?? 'llm'}() declaration — or drop fields from its output schema`,
+      meta: { prompt: input.prompt, maxTokens: input.maxTokens },
+    });
+  }
+}
+
+/**
+ * The model finished its turn and the arguments of a tool call it made are not JSON. Not a
+ * transport failure: the provider answered, the answer was billed, and asking the next provider
+ * (or the same one three more times) buys the same request again. So it is its own code, the
+ * gateway does not retry it, and it carries the bill.
+ *
+ * The cause never quotes the arguments. They are the model's text, and for `respond` they are the
+ * answer — which is where whatever the prompt loaded ends up.
+ */
+export class LlmToolArgumentsError extends UltimateError {
+  constructor(input: {
+    provider: string;
+    model: string;
+    tool: string;
+    chars: number;
+    billed: Billed;
+    /** Fragments with no index and no id: two calls merged, not one call broken. */
+    unkeyed?: boolean;
+  }) {
+    super({
+      code: 'X_LLM_TOOL_ARGUMENTS_INVALID',
+      cause:
+        input.unkeyed === true
+          ? `provider "${input.provider}" streamed tool-call fragments for model "${input.model}" with no index and no id, and more than one of them named a tool — the calls cannot be told apart, so none was run`
+          : `model "${input.model}" on provider "${input.provider}" finished its turn calling tool "${input.tool}" with ${input.chars} characters of arguments that are not JSON`,
+      fix: `maxTokens: 8192   # on the declaration, if the arguments were long — and shorten or split the string fields in the input schema of "${input.tool}", the place a model breaks JSON. Terminal for a job: to run the same request once more, catch this code and re-enqueue it deliberately`,
+      meta: {
+        provider: input.provider,
+        model: input.model,
+        tool: input.tool,
+        [BILLED_META]: input.billed,
+      },
+    });
+  }
+}
+
+/**
+ * A chat-completions endpoint finished a turn with a reason this build does not know, and the turn
+ * is not whole — a tool call whose arguments do not parse — or the reason was `error`. Not
+ * truncation (nothing says the ceiling was reached) and not a transport failure (the endpoint
+ * answered, and billed): its own code, carrying the reason and the bill.
+ */
+export class AiProviderUnexpectedError extends UltimateError {
+  constructor(input: { provider: string; model: string; reason: string; billed: Billed }) {
+    super({
+      code: 'X_AI_PROVIDER_UNEXPECTED',
+      cause: `provider "${input.provider}" finished a turn of model "${input.model}" with the finish reason ${JSON.stringify(input.reason.slice(0, 64))}, which this build does not know, and the answer is not complete`,
+      fix: "x doctor --json   # then check what the endpoint means by the reason in cause: a truncation needs a higher maxTokens on the declaration, anything else is the endpoint's to explain",
+      meta: {
+        provider: input.provider,
+        model: input.model,
+        reason: input.reason.slice(0, 64),
+        [BILLED_META]: input.billed,
+      },
+    });
+  }
+}