@ultimat3/ai 27.9.0 → 27.10.1

package/src/agent-continue.ts

@@ -0,0 +1,434 @@
+// Single responsibility: continuing an `agent()` run — the transcript handle a finished run
+// leaves, the screen it passes when an app hands it back, the one user turn a continuation
+// appends, and `.run()` / `.continue()` on the action.
+//
+// It exists because the alternative is a whole new run: repairing one section of an article
+// re-pays the transcript and every tool result, and the model starts from nothing. A continuation
+// re-SENDS the transcript (a provider has no session), but byte-for-byte, so the provider's prompt
+// cache reads the prefix back at the cache rate, and no tool runs twice.
+//
+// The handle is DATA: JSON, stored by the app, version-stamped, bound to one agent, size-capped
+// and re-validated block by block on the way in — a tool_use nothing answers is a 400 from every
+// provider, and a handle is exactly where one would come from. It carries what the model was
+// SENT (already redacted) and what the tools answered, so it is stored like the tool results are.
+
+import type { Action, InvokeOptions } from '@ultimat3/action';
+import {
+  asyncContext,
+  CURSOR_SECRET_FIX,
+  CURSOR_SECRET_KEY,
+  canonicalJson,
+  currentSigningSecret,
+  fingerprint,
+  isProduction,
+  isUltimateError,
+  usesDevCursorSecret,
+} from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { AgentTranscriptInvalidError } from './agent-errors';
+import type { AgentRunUsage } from './agent-usage';
+import type { AiContentBlock, AiMessage, TokenUsage } from './provider';
+import { RESPOND } from './respond';
+
+/** The handle's format. A handle of another version is refused, never migrated in place. */
+export const TRANSCRIPT_VERSION = 1;
+
+/**
+ * The most a handle may weigh, in characters of its JSON. Every continuation re-sends all of it,
+ * so this is a spend ceiling as much as a storage one: 2,000,000 characters is about 500k tokens
+ * of input per turn. A run that outgrew it starts a new run.
+ */
+export const MAX_TRANSCRIPT_CHARS = 2_000_000;
+
+/**
+ * A run, as the next call needs it. OPAQUE to an app — store the value (it is JSON), pass it back
+ * to `.continue()`; the fields are this package's and may change with `v`.
+ *
+ * SIGNED, and bound to what must not change between the run and its continuation. The handle
+ * carries the run's own ceilings (`turns`, `usage`) and its transcript, and it travels through an
+ * app's storage — so every field is under an HMAC, and a handle anyone edited is refused.
+ */
+export interface AgentTranscript {
+  readonly v: typeof TRANSCRIPT_VERSION;
+  /** The agent's prompt ref (`id@version`). A handle continues the agent that wrote it, only. */
+  readonly agent: string;
+  /** The model the run was on. A transcript is not carried to another one. */
+  readonly model: string;
+  /** A fingerprint of the tool names the agent declared when the handle was written. */
+  readonly tools: string;
+  /** The tenant of the actor the run was FOR, or `null`. Another org's actor is refused. */
+  readonly org: string | null;
+  /** Everything sent and answered so far. */
+  readonly messages: readonly AiMessage[];
+  /** Model turns taken across the run and every continuation — what `maxTurns` counts. */
+  readonly turns: number;
+  /** Usage across the run and every continuation — what `budget.tokensPerRun` counts. */
+  readonly usage: TokenUsage;
+  /** HMAC-SHA256 over the canonical JSON of every field above (`sealTranscript`). */
+  readonly sig: string;
+}
+
+/** What a handle is bound to: read off the DECLARATION and the request, never off the handle. */
+export interface TranscriptBinding {
+  readonly agent: string;
+  readonly model: string;
+  /** Every tool name the agent offers, `respond` included. */
+  readonly tools: readonly string[];
+  readonly org: string | null;
+}
+
+/** What `.run()` and `.continue()` resolve to: the validated answer and the handle to go on from. */
+export interface AgentRun<TOutput> {
+  readonly output: TOutput;
+  readonly transcript: AgentTranscript;
+  /** Turns taken so far, continuations included. */
+  readonly turns: number;
+  /** Usage and cost so far, continuations included — priced once, from the summed usage. */
+  readonly usage: AgentRunUsage;
+}
+
+export interface AgentContinuation {
+  /** The handle a previous `.run()` or `.continue()` returned. */
+  readonly transcript: AgentTranscript;
+  /** The one user turn to append: what to change, what was wrong. Redacted like the prompt. */
+  readonly user: string;
+}
+
+/** An `agent()` action, plus the two calls that keep the transcript. */
+export interface AgentAction<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>
+  extends Action<TInput, TOutput> {
+  /**
+   * The SAME action — same policy, audit, rate limit, budget — returning the transcript handle
+   * beside the answer. A plain call returns the answer alone and keeps nothing.
+   */
+  run(input: InferInput<TInput>, opts?: InvokeOptions): Promise<AgentRun<InferOutput<TOutput>>>;
+  /**
+   * Resume a finished run with one more user turn. `input` is the run's own input again (the
+   * policy and `system()` read it); the prompt is NOT re-rendered — the transcript holds it.
+   * `maxTurns` and `budget.tokensPerRun` count the run and every continuation together;
+   * `deadlineMs` and `maxRepeatedToolCalls` are per call.
+   */
+  continue(
+    input: InferInput<TInput>,
+    resume: AgentContinuation,
+    opts?: InvokeOptions,
+  ): Promise<AgentRun<InferOutput<TOutput>>>;
+  named(name: string): AgentAction<TInput, TOutput>;
+}
+
+/** One `.run()` / `.continue()` in flight: what to resume from, and where the loop leaves its run. */
+export interface AgentSession {
+  /**
+   * Which DECLARATION this session was opened for. The session rides the async context, so every
+   * agent that runs underneath — a tool that calls another agent — can see it; only the one whose
+   * token this is may take it, and only once.
+   */
+  readonly owner: object;
+  claimed: boolean;
+  readonly resume: AgentContinuation | undefined;
+  finished: Omit<AgentRun<unknown>, 'output'> | undefined;
+}
+
+// Core's lazy seam, like `llm-stream.ts`'s sink: the mark rides the invocation, so the action a
+// continuation calls is the one object the registry, the policy and the audit record know.
+const sessions = asyncContext<AgentSession>('an agent session');
+
+/**
+ * The session of THIS run, taken — or `undefined` for a plain call, and for any other agent
+ * running under somebody else's `.run()` / `.continue()`: a nested agent starts fresh.
+ */
+export function claimAgentSession(owner: object): AgentSession | undefined {
+  const session = sessions.get();
+  if (session === undefined || session.owner !== owner || session.claimed) return undefined;
+  session.claimed = true;
+  return session;
+}
+
+/** `.run()` and `.continue()` for one action: each invokes THAT action inside a session. */
+export function sessionCalls<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+  /** The declaration's own token: `named()` twins share it, no other agent has it. */
+  owner: object,
+): Pick<AgentAction<TInput, TOutput>, 'run' | 'continue'> {
+  const invoke = async (
+    input: InferInput<TInput>,
+    resume: AgentContinuation | undefined,
+    opts: InvokeOptions | undefined,
+  ): Promise<AgentRun<InferOutput<TOutput>>> => {
+    const session: AgentSession = { owner, claimed: false, resume, finished: undefined };
+    const output = await sessions.run(session, () => target(input, opts ?? {}));
+    const finished = session.finished;
+    if (finished === undefined) {
+      // The action answered without the loop running: something wrapped it and short-circuited.
+      throw new AgentTranscriptInvalidError({
+        agent: target.name ?? 'agent',
+        reason: 'the action returned without running the agent loop, so there is no transcript',
+      });
+    }
+    return { output, ...finished };
+  };
+  return {
+    run: (input, opts) => invoke(input, undefined, opts),
+    continue: (input, resume, opts) => invoke(input, resume, opts),
+  };
+}
+
+/**
+ * The transcript with ONE user turn appended. Every `tool_use` the last assistant turn left open is
+ * answered first — the accepted `respond` call among them, which the API insists on seeing
+ * answered like any other — and the instruction follows as text.
+ *
+ * A handle from a FAILED call ends on a user message (the request the failed turn was answering).
+ * Roles must alternate, so the instruction joins that message as one more text block.
+ */
+export function continued(transcript: AgentTranscript, user: string): readonly AiMessage[] {
+  const { messages } = transcript;
+  const last = messages.at(-1);
+  const text = { type: 'text' as const, text: user };
+  if (last === undefined) return [{ role: 'user', content: user }];
+  if (last.role === 'user') {
+    const blocks =
+      typeof last.content === 'string'
+        ? [{ type: 'text' as const, text: last.content }]
+        : last.content;
+    return [...messages.slice(0, -1), { role: 'user', content: [...blocks, text] }];
+  }
+  const open =
+    typeof last.content === 'string' ? [] : last.content.filter((b) => b.type === 'tool_use');
+  if (open.length === 0) return [...messages, { role: 'user', content: user }];
+  const answers = open.map((call) => ({
+    type: 'tool_result' as const,
+    tool_use_id: call.id,
+    content:
+      call.name === RESPOND ? 'Accepted as the answer so far.' : 'Not run: the turn had ended.',
+  }));
+  return [...messages, { role: 'user', content: [...answers, text] }];
+}
+
+/** Domain separation: this key signs transcripts and nothing else the same secret signs. */
+const PURPOSE = 'ultimate.ai.agent-transcript.v1';
+
+const toolsMark = (names: readonly string[]): string => fingerprint([...names].sort());
+
+function signatureOf(fields: Omit<AgentTranscript, 'sig'>): string {
+  // The framework's one signing secret (`ULTIMATE_CURSOR_SECRET`), under this file's own label.
+  return new Bun.CryptoHasher('sha256', currentSigningSecret())
+    .update(`${PURPOSE}\n${canonicalJson(fields)}`)
+    .digest('hex');
+}
+
+/** A handle for `state`, bound and signed. The one place a transcript is written. */
+export function sealTranscript(
+  binding: TranscriptBinding,
+  state: Pick<AgentTranscript, 'messages' | 'turns' | 'usage'>,
+): AgentTranscript {
+  const fields: Omit<AgentTranscript, 'sig'> = {
+    v: TRANSCRIPT_VERSION,
+    agent: binding.agent,
+    model: binding.model,
+    tools: toolsMark(binding.tools),
+    org: binding.org,
+    messages: state.messages,
+    turns: state.turns,
+    usage: state.usage,
+  };
+  return { ...fields, sig: signatureOf(fields) };
+}
+
+/** The `meta` key a failed `.run()` / `.continue()` carries its handle under. */
+export const TRANSCRIPT_META = 'transcript';
+
+/**
+ * The handle a FAILED `.run()` / `.continue()` left: the transcript up to the request the failed
+ * turn was answering, with `turns` and `usage` counting everything the failed call was billed. A
+ * job stores THIS one — continuing from the handle it started with forgets that spend, and is
+ * then bounded by the actor and org ceilings alone. `undefined` when the failure left none.
+ */
+export function transcriptOf(error: unknown): AgentTranscript | undefined {
+  if (!isUltimateError(error)) return undefined;
+  const raw = recordOf(error.meta?.[TRANSCRIPT_META]);
+  return raw !== undefined && typeof raw['sig'] === 'string'
+    ? (raw as unknown as AgentTranscript)
+    : undefined;
+}
+
+/** `error`, carrying `transcript` on `meta.transcript` — written in place, as its bill is. */
+export function withTranscript(error: unknown, transcript: AgentTranscript): unknown {
+  if (isUltimateError(error)) {
+    try {
+      Reflect.set(error, 'meta', { ...error.meta, [TRANSCRIPT_META]: transcript });
+    } catch {
+      // A frozen error keeps the meta it was thrown with.
+    }
+  }
+  return error;
+}
+
+/**
+ * A handle an app handed back, screened — before anything is loaded, reserved or sent. In order:
+ * its weight; its SIGNATURE (so `turns`, `usage` and every message are the ones this process
+ * wrote); what it is bound to — the agent, the model, the declared tools, the actor's tenant; and
+ * then its shape anyway, because a signed handle from an older build is still an older build's.
+ */
+export function screenTranscript(binding: TranscriptBinding, raw: unknown): AgentTranscript {
+  const { agent } = binding;
+  const refuse = (reason: string, fix?: string): never => {
+    throw new AgentTranscriptInvalidError({ agent, reason, ...(fix === undefined ? {} : { fix }) });
+  };
+  // A handle signed with the shipped development key is one anybody can forge.
+  if (isProduction() && usesDevCursorSecret()) {
+    refuse(
+      `this process signs with the shipped development key, so a handle cannot be trusted — set ${CURSOR_SECRET_KEY}`,
+      CURSOR_SECRET_FIX,
+    );
+  }
+  const handle = recordOf(raw) ?? refuse('it is not an object');
+  if (handle['v'] !== TRANSCRIPT_VERSION) {
+    refuse(`it is version ${String(handle['v'])}, and this build reads ${TRANSCRIPT_VERSION}`);
+  }
+  let weight: number;
+  try {
+    weight = JSON.stringify(handle).length;
+  } catch {
+    return refuse('it is not JSON');
+  }
+  if (weight > MAX_TRANSCRIPT_CHARS) {
+    refuse(`it is ${weight} characters, over the ${MAX_TRANSCRIPT_CHARS} a handle may weigh`);
+  }
+  const { sig, ...fields } = handle;
+  let expected: string;
+  try {
+    expected = signatureOf(fields as unknown as Omit<AgentTranscript, 'sig'>);
+  } catch {
+    return refuse('it is not JSON');
+  }
+  if (typeof sig !== 'string' || !sameText(sig, expected)) {
+    refuse('its signature does not match — it was edited, or the signing secret rotated');
+  }
+  if (handle['agent'] !== agent) refuse(`it was written by agent "${String(handle['agent'])}"`);
+  if (handle['model'] !== binding.model) {
+    refuse(
+      `it was written on model "${String(handle['model'])}", and this call is on "${binding.model}"`,
+    );
+  }
+  if (handle['tools'] !== toolsMark(binding.tools)) {
+    refuse('the agent declared a different set of tools when it was written');
+  }
+  if (handle['org'] !== binding.org) refuse('it was written for another tenant');
+  const turns = handle['turns'];
+  if (typeof turns !== 'number' || !Number.isInteger(turns) || turns < 0) {
+    refuse('its turn count is not a whole number');
+  }
+  const usage = usageOf(handle['usage']) ?? refuse('its usage is not four token counts');
+  const messages = Array.isArray(handle['messages']) ? handle['messages'] : refuse('no messages');
+  if (messages.length < 1) refuse('it holds no message');
+  const declared = new Set(binding.tools);
+  let open: ReadonlySet<string> = new Set();
+  const screened = messages.map((entry: unknown, index: number): AiMessage => {
+    const message = recordOf(entry) ?? refuse(`messages[${index}] is not an object`);
+    const role = index % 2 === 0 ? 'user' : 'assistant';
+    if (message['role'] !== role) refuse(`messages[${index}] is not a ${role} message`);
+    const content = contentOf(message['content']) ?? refuse(`messages[${index}] has no content`);
+    const blocks = typeof content === 'string' ? [] : content;
+    const answered = new Set(
+      blocks.flatMap((b) => (b.type === 'tool_result' ? [b.tool_use_id] : [])),
+    );
+    for (const id of open) {
+      if (!answered.has(id)) refuse(`messages[${index}] does not answer tool call "${id}"`);
+    }
+    if (role === 'user' && answered.size > open.size) {
+      refuse(`messages[${index}] answers a tool call nothing made`);
+    }
+    if (role === 'user' && blocks.some((b) => b.type === 'tool_use')) {
+      refuse(`messages[${index}] is a user message carrying a tool call`);
+    }
+    if (role === 'assistant' && answered.size > 0) {
+      refuse(`messages[${index}] is an assistant message carrying a tool result`);
+    }
+    for (const block of blocks) {
+      if (block.type === 'tool_use' && !declared.has(block.name)) {
+        refuse(`messages[${index}] calls "${block.name}", which this agent does not declare`);
+      }
+    }
+    open = new Set(blocks.flatMap((b) => (b.type === 'tool_use' ? [b.id] : [])));
+    return { role, content };
+  });
+  return {
+    v: TRANSCRIPT_VERSION,
+    agent,
+    model: binding.model,
+    tools: handle['tools'] as string,
+    org: binding.org,
+    messages: screened,
+    turns: turns as number,
+    usage,
+    sig: sig as string,
+  };
+}
+
+/** Constant-time over equal lengths: a signature check must not say how much of it matched. */
+function sameText(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i += 1) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+const COUNTERS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'] as const;
+
+function usageOf(raw: unknown): TokenUsage | undefined {
+  const record = recordOf(raw);
+  if (record === undefined) return undefined;
+  const count = (key: (typeof COUNTERS)[number]): number | undefined => {
+    const value = record[key];
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+  };
+  const [input, output, read, write] = COUNTERS.map(count);
+  if (input === undefined || output === undefined || read === undefined || write === undefined) {
+    return undefined;
+  }
+  return {
+    inputTokens: input,
+    outputTokens: output,
+    cacheReadTokens: read,
+    cacheWriteTokens: write,
+  };
+}
+
+/** A message's content, rebuilt field by field: a string, or the three block kinds a loop writes. */
+function contentOf(raw: unknown): string | readonly AiContentBlock[] | undefined {
+  if (typeof raw === 'string') return raw === '' ? undefined : raw;
+  if (!Array.isArray(raw) || raw.length === 0) return undefined;
+  const blocks: AiContentBlock[] = [];
+  for (const entry of raw) {
+    const block = recordOf(entry);
+    const built = block === undefined ? undefined : blockOf(block);
+    if (built === undefined) return undefined;
+    blocks.push(built);
+  }
+  return blocks;
+}
+
+function blockOf(block: Record<string, unknown>): AiContentBlock | undefined {
+  const { type, text, id, name, tool_use_id: answers, content } = block;
+  if (type === 'text' && typeof text === 'string' && text !== '') return { type, text };
+  const input = recordOf(block['input']);
+  if (type === 'tool_use' && typeof id === 'string' && typeof name === 'string' && input) {
+    return { type, id, name, input };
+  }
+  if (type === 'tool_result' && typeof answers === 'string' && typeof content === 'string') {
+    return {
+      type,
+      tool_use_id: answers,
+      content,
+      ...(block['is_error'] === true ? { is_error: true } : {}),
+    };
+  }
+  return undefined;
+}

package/src/agent-declared.ts

@@ -0,0 +1,157 @@
+// Single responsibility: what an `agent()` declaration AMOUNTS to before a run exists — its
+// defaults, the screen its bounds pass at declaration, the budget limits one call runs under, and
+// the row `describeAgents()` publishes. Split from ./agent at its line ceiling.
+
+import { finiteCount, isMcpExposed } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { AgentDef } from './agent-def';
+import type { AgentFact } from './agent-facts';
+import { DEFAULT_MAX_REPEATED_TOOL_CALLS } from './agent-guards';
+import type { BudgetLimits } from './budget';
+import { screenedMoney } from './budget';
+import { AiBudgetExceededError, AiRequestInvalidError } from './errors';
+import { describedModel, type ModelSource } from './model-resolve';
+import type { PromptVars } from './prompt';
+import type { TokenUsage } from './provider';
+import { totalTokens } from './provider';
+import { installedGateway } from './runtime';
+import { 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.
+ */
+export const DEFAULT_MAX_TURNS = 8;
+
+/** Output ceiling per turn when the declaration omits one. Same reasoning as `llm()`'s. */
+export 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.
+ */
+export const DEFAULT_TOOL_RESULT_CHARS = 4_000;
+
+/** Named in every bound refusal, so the fix names the key the declaration carries. */
+export const SUBJECT = 'agent';
+
+/** The loop's bounds with their defaults applied — read by the run from HERE, never re-defaulted. */
+export interface AgentBounds {
+  readonly maxTurns: number;
+  readonly maxToolResultChars: number;
+  readonly maxTokens: number;
+  readonly maxRepeatedToolCalls: number;
+}
+
+/** The loop bounds, screened at DECLARATION: `agent()` runs at module scope, so a bad one fails the boot. */
+export function screenBounds<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>): AgentBounds {
+  // 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.
+  const maxTurns = finiteCount(SUBJECT, 'maxTurns', def.maxTurns ?? DEFAULT_MAX_TURNS, 1);
+  const maxToolResultChars = finiteCount(
+    SUBJECT,
+    'maxToolResultChars',
+    def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
+    1,
+  );
+  const maxTokens = 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);
+  return { maxTurns, maxToolResultChars, maxTokens, maxRepeatedToolCalls: repeats };
+}
+
+// `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,
+});
+
+export 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),
+  };
+}
+
+export function limitsOf<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>, used?: TokenUsage): 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: leftOf(finiteCount(SUBJECT, 'budget.tokensPerRun', budget.tokensPerRun), used),
+        }),
+  };
+}
+
+/**
+ * `tokensPerRun` for THIS call: the declared ceiling less what the run's earlier calls used. Never
+ * a debit on the ledger — that would bill the actor and org scopes a second time for tokens they
+ * were already charged — so the remainder is the ceiling, and none left is refused before a call.
+ */
+function leftOf(limit: number, used: TokenUsage | undefined): number {
+  const spent = used === undefined ? 0 : totalTokens(used);
+  if (spent < limit) return limit - spent;
+  throw new AiBudgetExceededError({ scope: 'request', requested: 1, remaining: 0, limit });
+}

package/src/agent-def.ts

@@ -52,12 +52,19 @@ export interface AgentDef<
    */
   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.
+   * What the model may call: an `action()` that is `mcp: { expose: true }` — the same predicate an
+   * external MCP client is filtered by, so both are offered the same actions — or an
+   * `inProcessTool()`, which only this process's agents ever see. Anything else is refused at
+   * declaration rather than dropped: a tool that reads as offered and silently is not is the worst
+   * of both.
    */
   readonly tools: readonly AgentTool[];
+  /**
+   * `false` withholds the refusals of EVERY in-process tool this agent runs, as a projected tool's
+   * are — for an agent whose transcript leaves the tenant it ran for. Default `true`; one tool
+   * opts out with `inProcessTool({ discloseErrors: false })`.
+   */
+  readonly discloseToolErrors?: boolean;
   /** Hard ceiling on model turns. Reaching it is `X_AGENT_MAX_TURNS`, never a partial answer. */
   readonly maxTurns?: number;
   readonly maxToolResultChars?: number;
@@ -76,6 +83,15 @@ export interface AgentDef<
   readonly mcp?: ActionMcp;
   /** Enforced completion ceiling PER TURN. The model never sees it. */
   readonly maxTokens?: number;
+  /**
+   * `temperature` (0 to 2) and `seed` (a whole number), for a call that should answer the same way
+   * twice — a verifier, a classifier. Sent only to a model whose row takes them
+   * (`registerModel({ sampling })`); to any other they are NOT sent, because a reasoning model
+   * answers one with a 400 — the `llm.sampling.ignored` span attribute names what was left out.
+   * `seed` exists on the chat-completions wire only, and is best effort where it exists.
+   */
+  readonly temperature?: number;
+  readonly seed?: 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
@@ -104,8 +120,15 @@ export interface AgentTurn {
   readonly toolCalls: readonly string[];
   readonly stopReason: StopReason;
   readonly usage: TokenUsage;
-  /** This turn's cost alone, integer minor units — never the run's running total. */
+  /** This turn's cost alone, integer minor units, rounded up — never the run's running total. */
   readonly cost: Money;
+  /** This turn's cost exactly (`Money` at a finer `scale`); absent when the provider stated none. */
+  readonly costExact?: Money;
+  /**
+   * Set on a REPAIR turn: the schema issues of the previous turn's answer, which is what the
+   * model was told to fix before it produced this one. Absent on every other turn.
+   */
+  readonly repairOf?: readonly string[];
   /** The running total, this turn included — on the last turn, the whole run. */
   readonly run: AgentRunUsage;
 }

package/src/agent-errors.ts

@@ -1,4 +1,4 @@
-// The two X_AGENT_* codes an UNATTENDED run needs, apart from ./errors only because one file has
+// The X_AGENT_* codes an UNATTENDED run needs, and the one a continuation's handle is refused by, 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.
 
@@ -48,3 +48,22 @@ export class AgentDeadlineError extends UltimateError {
     });
   }
 }
+
+/**
+ * A transcript handle handed to `.continue()` did not pass its screen. The handle is data an app
+ * stored and read back, so it is refused BEFORE anything is loaded, reserved or sent: a transcript
+ * with a tool call nothing answers is a 400 from every provider, and one from another agent or
+ * another format would resume a conversation this declaration never had.
+ */
+export class AgentTranscriptInvalidError extends UltimateError {
+  constructor(input: { agent: string; reason: string; fix?: string }) {
+    super({
+      code: 'X_AGENT_TRANSCRIPT_INVALID',
+      cause: `agent "${input.agent}" cannot continue from the transcript it was given: ${input.reason}`,
+      fix:
+        input.fix ??
+        'agent.run(input, { ctx })   # start a new run and store ITS transcript — pass back exactly the value .run() or .continue() returned, from the same agent and prompt version',
+      meta: { agent: input.agent },
+    });
+  }
+}