@ultimat3/ai 27.9.0 → 27.10.1

package/src/agent-turn.ts

@@ -0,0 +1,54 @@
+// Single responsibility: what the loop does with ONE completed model turn before it acts on it —
+// report it, and refuse the two stops that are not an answer. Split from ./agent at its line
+// ceiling.
+
+import type { Span } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { AgentDef, AgentTurn } from './agent-def';
+import { LlmRefusedError } from './errors';
+import { moreCapableThan } from './models';
+import type { PromptVars } from './prompt';
+import type { GenerateRequest, GenerateResult } from './provider';
+
+/**
+ * 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.
+ */
+export 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,
+    'agent.turn.repair': event.repairOf !== undefined,
+    // What the provider's prompt cache did for this turn — the two numbers that say whether the
+    // stable prefix is really stable.
+    'llm.cache.read_tokens': event.usage.cacheReadTokens,
+    'llm.cache.write_tokens': event.usage.cacheWriteTokens,
+  });
+  await def.onTurn?.(event);
+}
+
+/** Refuse before the answer is read, for the reason `llm()` does: a refusal is a 200 with no answer. */
+export 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,
+  });
+}

package/src/agent-usage.ts

@@ -1,27 +1,63 @@
-// Single responsibility: a run's running token and money total, across its turns.
+// Single responsibility: a run's running token and money total, across its turns and its
+// continuations.
 
 import type { Money } from '@ultimat3/money';
+import type { Billed } from './billed';
+import { addMoney, costOf, exactCostOf, roundUpCost } from './cost';
+import type { ModelId } from './models';
 import type { GenerateResult, TokenUsage } from './provider';
-import { costOf } from './provider';
 
 /** The run so far, this turn included. */
 export interface AgentRunUsage {
   readonly usage: TokenUsage;
+  /** In the currency's minor units, rounded up ONCE over the whole run — never a sum of turns. */
   readonly cost: Money;
+  /** The same figure exactly, as `Money` at a finer `scale` (`exactCostOf`). */
+  readonly costExact: Money;
+}
+
+const ZERO: TokenUsage = {
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+};
+
+const plus = (a: TokenUsage, b: TokenUsage): TokenUsage => ({
+  inputTokens: a.inputTokens + b.inputTokens,
+  outputTokens: a.outputTokens + b.outputTokens,
+  cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+  cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+});
+
+/** `usage` on `model`, priced once: each turn's own cost is rounded up, and ten round-ups is not the price of the run. */
+const priced = (model: ModelId, usage: TokenUsage): AgentRunUsage => ({
+  usage,
+  cost: costOf(model, usage),
+  costExact: exactCostOf(model, usage),
+});
+
+/** The run's total after one more turn, re-priced from the summed usage. */
+export function addUsage(total: AgentRunUsage | undefined, result: GenerateResult): AgentRunUsage {
+  return priced(result.model, plus(total?.usage ?? ZERO, result.usage));
 }
 
 /**
- * The run's total after one more turn. The cost is re-priced from the summed usage rather than
- * summed per turn: each turn's cost is rounded UP to a minor unit, and ten round-ups is not the
- * price of the run.
+ * A run's total across its continuations: what the handle already held plus what this call used,
+ * priced once from the sum.
  */
-export function addUsage(total: AgentRunUsage | undefined, result: GenerateResult): AgentRunUsage {
-  const before = total?.usage;
-  const usage: TokenUsage = {
-    inputTokens: (before?.inputTokens ?? 0) + result.usage.inputTokens,
-    outputTokens: (before?.outputTokens ?? 0) + result.usage.outputTokens,
-    cacheReadTokens: (before?.cacheReadTokens ?? 0) + result.usage.cacheReadTokens,
-    cacheWriteTokens: (before?.cacheWriteTokens ?? 0) + result.usage.cacheWriteTokens,
+export function runTotal(
+  model: ModelId,
+  prior: TokenUsage | undefined,
+  own: { readonly usage: TokenUsage } | undefined,
+  /** What runs underneath were billed (`RunMeter.below`): another model's price, so ADDED, never re-priced. */
+  below?: Billed,
+): AgentRunUsage {
+  const base = priced(model, plus(prior ?? ZERO, own?.usage ?? ZERO));
+  if (below === undefined || below.cost.currency !== base.cost.currency) return base;
+  return {
+    usage: plus(base.usage, below.usage),
+    cost: addMoney(base.cost, roundUpCost(below.cost)),
+    costExact: addMoney(base.costExact, below.cost),
   };
-  return { usage, cost: costOf(result.model, usage) };
 }

package/src/agent.ts

@@ -22,61 +22,47 @@
 
 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 { 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 { AgentDef, AgentTurn } from './agent-def';
-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 { DEFAULT_MAX_REPEATED_TOOL_CALLS, runDeadline, toolLoopGuard } from './agent-guards';
+import { runDeadline, toolLoopGuard } from './agent-guards';
 import { sameSystem, systemOf } from './agent-system';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
-import type { AgentRunUsage } from './agent-usage';
-import { addUsage } from './agent-usage';
-import type { BudgetLimits } from './budget';
-import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
-import {
-  AgentMaxTurnsError,
-  AgentToolUnexposedError,
-  AiRequestInvalidError,
-  LlmOutputInvalidError,
-  LlmRefusedError,
-  LlmTruncatedError,
-} from './errors';
+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 { moreCapableThan } from './models';
+import { modelForCall } from './model-resolve';
 import type { PromptVars } from './prompt';
 import { promptCacheHint } from './prompt-cache';
-import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
+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 { ignoredSamplingAttribute, 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';
+import { asProjectableAction, isOfferedTool, runLlmToolCall, toLlmTools, toolLabel } from './tools';
 
 export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent-def';
 
@@ -84,49 +70,23 @@ 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 repeats = finiteCount(
-    SUBJECT,
-    'maxRepeatedToolCalls',
-    def.maxRepeatedToolCalls ?? DEFAULT_MAX_REPEATED_TOOL_CALLS,
-    1,
-  );
-  if (repeats < 2) {
-    // One "repeat" is the first tool turn of every run: the agent could never use a tool.
-    throw new AiRequestInvalidError({
-      detail: `agent maxRepeatedToolCalls is ${repeats}, which would stop every run at its first tool turn`,
-      fix: 'maxRepeatedToolCalls: 3   # on the agent — at least 2; it counts consecutive identical turns, the first included',
-    });
-  }
-  // `AbortSignal.timeout(NaN)` throws a RangeError mid-run; `0` aborts before turn one.
-  if (def.deadlineMs !== undefined) finiteCount(SUBJECT, 'deadlineMs', def.deadlineMs, 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`.
@@ -140,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. */
@@ -203,29 +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);
+  // 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 vars = await deadline.guard(Promise.resolve(def.vars(args)));
-  assertNoSecrets(name, vars);
   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 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, def.maxRepeatedToolCalls ?? DEFAULT_MAX_REPEATED_TOOL_CALLS);
-  const maxTurns = def.maxTurns ?? DEFAULT_MAX_TURNS;
-  const chars = def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS;
+  const repeated = toolLoopGuard(name, bounds.maxRepeatedToolCalls);
+  const { maxTurns, maxToolResultChars: chars } = bounds;
 
   return withSpan('ai.agent', async (span) => {
     span.setAttributes({
@@ -237,6 +197,14 @@ async function run<
       'llm.redacted': rendered !== rawPrompt || !sameSystem(system, rawSystem),
       'llm.prompt_cache': promptCache !== undefined,
     });
+    // Read when the run ends, not here: the gateway may be what registers the model's row.
+    const reportSampling = (): void => {
+      span.setAttributes(
+        ignoredSamplingAttribute(model, bounds.sampling, () =>
+          installedGateway()?.samplingWires?.(model),
+        ),
+      );
+    };
 
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
@@ -249,9 +217,10 @@ async function run<
       ...(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.
@@ -259,31 +228,41 @@ async function run<
       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;
-      let total: AgentRunUsage | 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);
         deadline.check();
         const result = await deadline
-          .guard(gateway.generate({ ...base, messages }))
+          .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;
           });
-        total = addUsage(total, result);
+        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.
@@ -301,9 +280,22 @@ async function run<
           stopReason: result.stopReason,
           usage: result.usage,
           cost: result.cost,
-          run: total,
+          ...(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
@@ -321,10 +313,13 @@ async function run<
           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))),
+              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);
@@ -342,83 +337,58 @@ 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,
-    // What the provider's prompt cache did for this turn — the two numbers that say whether the
-    // stable prefix is really stable.
-    'llm.cache.read_tokens': event.usage.cacheReadTokens,
-    'llm.cache.write_tokens': event.usage.cacheWriteTokens,
-  });
-  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;
+        })
+        .finally(reportSampling),
+    );
   });
 }
-
-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) }),
-  };
-}