@ultimat3/ai 2.0.0 → 4.0.0

package/src/agent-job.ts

@@ -0,0 +1,97 @@
+/**
+ * `agentJob()` — an agent as durable, resumable, budgeted background work.
+ *
+ * The bridge `packages/action/src/job-handle.ts` names in its own header and could not build:
+ * `isJobHandle` needs `kind === 'job'` PLUS membership of a WeakMap only `job()` writes, so no
+ * externally-shaped object reaches the registry, the queue or the worker — and `action` and `jobs`
+ * are both tier 3, so neither may import the other. This package is tier 4 and may import both,
+ * which is exactly where that header says the adapter belongs.
+ *
+ * It composes `job()` rather than re-implementing a handle: the returned value IS one `job()`
+ * seated, so `.enqueue()`, the outbox, the worker's cancellation, the dead-letter path,
+ * `x jobs show` and its manifest row all arrive without a line here.
+ */
+
+import type { Action, ActionJobHandle } from '@ultimat3/action';
+import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
+import { job } from '@ultimat3/jobs';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+
+export interface AgentJobOptions<I> {
+  /**
+   * The durable queue key. REQUIRED and never derived from the agent's export name: a job name is
+   * what queued, retrying and dead-lettered rows already carry, so renaming an export must not
+   * move where they are delivered.
+   */
+  readonly name: string;
+  /**
+   * REQUIRED, no default, and the org this run's body acts under. `jobs` states why: every
+   * candidate default is a cross-tenant read waiting for the first job that takes an org id in its
+   * input. `tenant: 'none'` is the explicit statement that this agent touches no tenant-scoped
+   * table, and then every scoped read inside it fails closed.
+   */
+  readonly tenant: JobTenant<I>;
+  /** REQUIRED, no default. A model call fails transiently; how many times is nobody else's guess. */
+  readonly retry: RetryPolicy;
+  readonly queue?: string;
+  /**
+   * Defaults to the action projection's own key — `action:<name>:<fingerprint of input>` — which
+   * is stable across retries and derived from the payload alone.
+   *
+   * **It dedupes the ENQUEUE, never the ATTEMPT.** Two `enqueue` calls with the same payload are
+   * one row; one row that a worker claims, half-runs and loses the lease on is claimed again, and
+   * the agent runs a second time from the top. Combined with `backfill()`, whose `handle` is at
+   * least once by construction, a replayed page re-runs every agent on it.
+   *
+   * What that means for `tools`: **every tool the agent may call has to be idempotent** — an
+   * `upsertAll`, an `updateWhere`, a statement whose second run changes nothing — because a
+   * replayed attempt issues a second `issueRefund` otherwise. The framework does NOT check this and
+   * cannot: `mutates` is not a fact an `action()` declares (`@ultimat3/mcp` sets it to `true` for
+   * every action it projects), so a read-only `lookupOrder` and a destructive `issueRefund` are
+   * indistinguishable here, and a rule refusing both would be a wrong refusal. See the README.
+   */
+  idempotencyKey?(input: I): string;
+}
+
+/**
+ * Wrap an `agent()` — or any action — as a real job handle.
+ *
+ * Both reads of the underlying projection are LAZY, and that is load-bearing: `target.job()` calls
+ * `actionName()`, which throws `X_ACTION_UNREGISTERED` until `registerAction` stamps the export
+ * name at boot — and `agentJob()` is evaluated at module scope, right beside the `agent()` it
+ * wraps. The queue key comes from `options.name` for the same reason it is required.
+ */
+export function agentJob<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
+  target: Action<TInput, TOutput>,
+  options: AgentJobOptions<InferOutput<TInput>>,
+): JobHandle<InferOutput<TInput>> {
+  let projected: ActionJobHandle<TInput, TOutput> | undefined;
+  const bridge = (): ActionJobHandle<TInput, TOutput> => {
+    if (projected === undefined) projected = target.job();
+    return projected;
+  };
+  return job<InferOutput<TInput>>({
+    name: options.name,
+    input: target.input as StandardSchemaV1<unknown, InferOutput<TInput>>,
+    tenant: options.tenant,
+    retry: options.retry,
+    ...(options.queue === undefined ? {} : { queue: options.queue }),
+    idempotencyKey: (input) =>
+      options.idempotencyKey?.(input) ?? bridge().idempotencyKey(asInput<TInput>(input)),
+    // ONE execution path, and it is the action's. `ActionJobHandle.invoke` is `invoke(target,
+    // input, { surface: 'job', ctx })`, so the agent's policy, its input parse, its budget scope
+    // and its span all apply — and `ctx` is the WORKER's, so `ctx.signal` aborting at the attempt
+    // timeout reaches the agent's turn loop.
+    run: ({ input, ctx }) => bridge().invoke(asInput<TInput>(input), ctx),
+  });
+}
+
+/**
+ * The job parsed with the action's OWN schema, so what it hands back is a value that schema
+ * accepts — `invoke` re-parses it regardless, which is what makes this safe rather than merely
+ * convenient. The cast exists because `InferOutput` and `InferInput` are different types wherever a
+ * field has a default, and nothing at this seam can prove they meet.
+ */
+function asInput<TInput extends StandardSchemaV1>(value: InferOutput<TInput>): InferInput<TInput> {
+  return value as InferInput<TInput>;
+}

package/src/agent-transcript.ts

@@ -0,0 +1,94 @@
+/**
+ * The transcript one agent turn leaves behind: the assistant message replaying what the model
+ * emitted, and the user message answering it. One file because the Messages API's rule spans both
+ * halves — every `tool_use` block replayed here must be answered by a `tool_result` in the very
+ * next message — and a rule split across two call sites is a rule one of them will miss.
+ */
+
+import { RESPOND } from './llm';
+import type { AiContentBlock, AiMessage, GenerateResult } from './provider';
+import type { LlmToolCall, LlmToolResult } from './tools';
+
+/**
+ * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
+ * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
+ * because it has no `tool_result` to follow them with, and the API demands one.
+ */
+export function assistantTurn(result: GenerateResult): AiMessage {
+  const blocks: AiContentBlock[] = [];
+  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
+  for (const call of result.toolCalls) {
+    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
+  }
+  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
+  return blocks.length === 0
+    ? { role: 'assistant', content: '(no answer)' }
+    : { role: 'assistant', content: blocks };
+}
+
+/**
+ * What the model is told when it answered in the same turn it asked for a tool. Parallel tool use
+ * is normal, and the answer that comes with it was written before the tool result existed — so it
+ * is superseded, not wrong, and saying which is what stops the next turn repeating it verbatim.
+ */
+const SUPERSEDED = `This answer arrived in the same turn as the tool calls above, so it was written before their results existed. Read the results in this message, then call the "${RESPOND}" tool again.`;
+
+/**
+ * The tool results of one turn, plus a `tool_result` for every `respond` call the loop did not
+ * accept. The second half is not optional: `respond` is filtered out of the calls that get RUN,
+ * but it is replayed as a `tool_use` like any other, and a `tool_use` the next message does not
+ * answer is a 400 (`tool_use ids were found without tool_result blocks`) — the whole run lost to
+ * an `X_AI_PROVIDER_UNAVAILABLE` because the model did the ordinary thing.
+ *
+ * Real results stay first: they are what the model asked for, and the rejection reads as the
+ * instruction that follows them.
+ */
+export function toolResultTurn(
+  results: readonly LlmToolResult[],
+  chars: number,
+  unaccepted: readonly LlmToolCall[],
+): AiMessage {
+  return {
+    role: 'user',
+    content: [
+      ...results.map((result) => ({
+        type: 'tool_result' as const,
+        tool_use_id: result.toolUseId,
+        content: truncate(result.content, chars),
+        // A denial or a failure is an outcome the model should read and react to, flagged so it
+        // does not read as data.
+        ...(result.isError === true ? { is_error: true } : {}),
+      })),
+      ...rejections(unaccepted, SUPERSEDED),
+    ],
+  };
+}
+
+/**
+ * The correction after an answer that failed its schema, in whichever shape the turn it corrects
+ * demands: a `tool_result` when the answer came through `respond` (the dominant path, and a
+ * `tool_use` the API insists on seeing answered), a plain user message when the model answered in
+ * prose and there is no id to name. Framework text, so never truncated by `maxToolResultChars`.
+ */
+export function repairTurn(unaccepted: readonly LlmToolCall[], issues: string): AiMessage {
+  const text = `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
+  return unaccepted.length === 0
+    ? { role: 'user', content: text }
+    : { role: 'user', content: rejections(unaccepted, text) };
+}
+
+/** A `tool_result` saying an answer was not taken, flagged so the model does not read it as data. */
+function rejections(calls: readonly LlmToolCall[], text: string): readonly AiContentBlock[] {
+  return calls.map((call) => ({
+    type: 'tool_result' as const,
+    tool_use_id: call.id,
+    content: text,
+    is_error: true,
+  }));
+}
+
+/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
+function truncate(text: string, chars: number): string {
+  if (text.length <= chars) return text;
+  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
+}

package/src/agent.ts

@@ -20,10 +20,14 @@
 
 import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
-import type { Ctx } from '@ultimat3/core';
-import { withSpan } from '@ultimat3/core';
+import type { Ctx, Span } from '@ultimat3/core';
+import { isMcpExposed, throwIfAborted, withSpan } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
+import type { AgentFact } from './agent-facts';
+import { registerAgentFact } from './agent-facts';
+import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import type { BudgetLimits } from './budget';
 import { BudgetLedger, currentBudget, withBudget } from './budget';
 import {
@@ -38,11 +42,17 @@ import { answerAttributes, RESPOND, respondToolFor, structuredOutputOf } from '.
 import type { ModelId } from './models';
 import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
-import type { AiContentBlock, AiMessage, GenerateRequest, GenerateResult } from './provider';
+import type {
+  AiMessage,
+  GenerateRequest,
+  GenerateResult,
+  StopReason,
+  TokenUsage,
+} from './provider';
 import { assertNoSecrets } from './redaction';
 import { aiGateway, aiRedactor } from './runtime';
-import type { LlmTool, LlmToolResult, ProjectableAction } from './tools';
-import { runLlmToolCall, toLlmTools } from './tools';
+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
@@ -91,7 +101,7 @@ export interface AgentDef<
    * 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 ProjectableAction[];
+  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;
@@ -100,6 +110,36 @@ export interface AgentDef<
   readonly mcp?: ActionMcp;
   /** Enforced completion ceiling PER TURN. The model never sees it. */
   readonly maxTokens?: number;
+  /**
+   * Called once per completed model turn, before the answer or the tool calls are acted on. The
+   * one thing a multi-turn run could not do until 2026-08: a 90-second loop emitted nothing until
+   * it returned, so a progress indicator, a per-turn spend line and a transcript log all had to be
+   * hand-rolled outside the framework — which is exactly the loop `agent()` exists to replace.
+   *
+   * Observation only: it cannot steer the loop, cannot see the transcript and cannot reach the
+   * actor. A throw from it FAILS the run rather than being swallowed — it is the app's code on the
+   * run's own path, and an observer that silently stopped working would be indistinguishable from
+   * one that is fine. The same facts land on the span as an `agent.turn` event, so a run that
+   * declares no hook is still readable in a trace.
+   *
+   * NOT `.stream()`. Tokens on a screen is a different contract, and `llm()`'s streamed half is
+   * one turn deep by construction; this is per TURN.
+   */
+  onTurn?(event: AgentTurn): void | Promise<void>;
+}
+
+/** One completed model turn, as an observer sees it. Facts only — no transcript, no actor. */
+export interface AgentTurn {
+  /** 1-based, so `turn === maxTurns` is the last one this run will take. */
+  readonly turn: number;
+  readonly maxTurns: number;
+  readonly model: ModelId;
+  /** Tools this turn asked for, in the order the model emitted them. `respond` is not one. */
+  readonly toolCalls: readonly string[];
+  readonly stopReason: StopReason;
+  readonly usage: TokenUsage;
+  /** This turn's cost alone, integer minor units — never the run's running total. */
+  readonly cost: Money;
 }
 
 export function agent<
@@ -109,21 +149,69 @@ export function agent<
 >(def: AgentDef<TInput, TOutput, V>): Action<TInput, TOutput> {
   const respond = respondToolFor(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.
-  const offered = toLlmTools(def.tools);
-  if (offered.length !== def.tools.length) {
+  // 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));
+  if (unexposed.length > 0) {
     throw new AgentToolUnexposedError({
       agent: def.prompt.ref,
-      tools: def.tools.filter((a) => !offered.some((o) => o.name === a.name)).map((a) => a.name),
+      tools: unexposed.map(toolLabel),
     });
   }
-  return action<TInput, TOutput>({
+  // 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`.
+  let adapted: Adapted | undefined;
+  const adapt = (): Adapted => {
+    if (adapted === undefined) adapted = project(def.tools);
+    return adapted;
+  };
+  const built = action<TInput, TOutput>({
     input: def.input,
     output: def.output,
     policy: def.policy,
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
-    handle: (args) => run(def, respond, offered, args),
+    handle: (args) => run(def, respond, adapt(), 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;
+}
+
+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,
+    model: def.model ?? def.prompt.model ?? DEFAULT_MODEL,
+    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),
+  };
+}
+
+/** The tools as `runLlmToolCall` consumes them, and as the request offers them. One projection. */
+interface Adapted {
+  readonly tools: readonly ProjectableAction[];
+  readonly offered: readonly LlmTool[];
+}
+
+function project(tools: readonly AgentTool[]): Adapted {
+  const projected = tools.map(asProjectableAction);
+  return { tools: projected, offered: toLlmTools(projected) };
 }
 
 async function run<
@@ -133,7 +221,7 @@ async function run<
 >(
   def: AgentDef<TInput, TOutput, V>,
   respond: LlmTool,
-  offered: readonly LlmTool[],
+  adapted: Adapted,
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
@@ -153,7 +241,7 @@ async function run<
       'agent.model': model,
       'agent.prompt': name,
       'agent.prompt.hash': prompt.hash,
-      'agent.tools': offered.length,
+      'agent.tools': adapted.offered.length,
       'agent.max_turns': maxTurns,
       'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
     });
@@ -167,7 +255,10 @@ async function run<
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
-      tools: [...offered, respond],
+      tools: [...adapted.offered, respond],
+      // 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,
     };
 
     return withBudget(ledger, async () => {
@@ -180,20 +271,57 @@ async function run<
       let issues: string | undefined;
 
       for (let turn = 1; turn <= maxTurns; turn += 1) {
+        // 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 });
+        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.
+        const answers = result.toolCalls.filter((call) => call.name === RESPOND);
         span.setAttributes({
           'agent.turns': turn,
           'agent.tool_calls': calls,
           ...answerAttributes(result),
         });
+        await observeTurn(def, span, {
+          turn,
+          maxTurns,
+          model: result.model,
+          toolCalls: requested.map((call) => call.name),
+          stopReason: result.stopReason,
+          usage: result.usage,
+          cost: result.cost,
+        });
         assertAnswerable(result, name);
 
-        const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
         if (requested.length > 0) {
-          const results: LlmToolResult[] = [];
-          for (const call of requested) results.push(await runLlmToolCall(def.tools, call, actor));
+          // Concurrent, and deliberately unbounded WITHIN one turn: the batch is what a single
+          // model turn asked for, each entry is an ordinary `action` carrying its own policy and
+          // its own `rateLimit`, and a second ceiling here would be a throttle competing with
+          // those. A tool that calls a model still queues on the ledger's root turnstile, so the
+          // budget holds. Serial cost 5x wall clock for a turn that asked for 5 tools, and nothing
+          // in the types or the docs ever said so.
+          //
+          // Order is by INDEX, not by completion: `Promise.all` resolves positionally and each
+          // 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)),
+          );
           calls += requested.length;
-          messages = [...messages, assistantTurn(result), toolResults(results, chars)];
+          messages = [
+            ...messages,
+            assistantTurn(result),
+            // Parallel tool use — one turn asking for a tool AND answering — is normal, and the
+            // answer is speculative: it was written before the result it asked for existed. So
+            // the loop continues, and the answer is REJECTED on the wire rather than dropped,
+            // because a replayed `respond` block with no `tool_result` is a 400 and the whole run
+            // becomes an `X_AI_PROVIDER_UNAVAILABLE`.
+            toolResultTurn(results, chars, answers),
+          ];
           continue;
         }
 
@@ -205,7 +333,7 @@ async function run<
         if (result.stopReason === 'max_tokens') {
           throw new LlmTruncatedError({ prompt: name, maxTokens: base.maxTokens });
         }
-        messages = [...messages, assistantTurn(result), { role: 'user', content: repair(issues) }];
+        messages = [...messages, assistantTurn(result), repairTurn(answers, issues)];
       }
 
       // Two different exhaustions, so two different causes: a loop that kept calling tools and
@@ -218,6 +346,28 @@ async function run<
   });
 }
 
+/**
+ * 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): void {
   if (result.stopReason !== 'refusal') return;
@@ -230,47 +380,6 @@ function assertAnswerable(result: GenerateResult, name: string): void {
   });
 }
 
-/**
- * The model's turn, replayed as the transcript the next request needs. `tool_use` blocks survive
- * as themselves here — unlike `llm()`'s repair turn, which flattens them to text precisely
- * because it has no `tool_result` to follow them with, and the API demands one.
- */
-function assistantTurn(result: GenerateResult): AiMessage {
-  const blocks: AiContentBlock[] = [];
-  if (result.text !== '') blocks.push({ type: 'text', text: result.text });
-  for (const call of result.toolCalls) {
-    blocks.push({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
-  }
-  // A turn with neither text nor a tool call would be an empty content array, which is a 400.
-  return blocks.length === 0
-    ? { role: 'assistant', content: '(no answer)' }
-    : { role: 'assistant', content: blocks };
-}
-
-function toolResults(results: readonly LlmToolResult[], chars: number): AiMessage {
-  return {
-    role: 'user',
-    content: results.map((result) => ({
-      type: 'tool_result' as const,
-      tool_use_id: result.toolUseId,
-      content: truncate(result.content, chars),
-      // A denial or a failure is an outcome the model should read and react to, flagged so it
-      // does not read as data.
-      ...(result.isError === true ? { is_error: true } : {}),
-    })),
-  };
-}
-
-/** Truncation says so. A silently shortened tool result is a model reasoning over half a table. */
-function truncate(text: string, chars: number): string {
-  if (text.length <= chars) return text;
-  return `${text.slice(0, chars)}\n[truncated: ${text.length - chars} more characters]`;
-}
-
-function repair(issues: string): string {
-  return `That answer failed its schema: ${issues}. Call the "${RESPOND}" tool with a value that satisfies it. Answer only through the tool.`;
-}
-
 function limitsOf<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,

package/src/errors.ts

@@ -18,6 +18,7 @@ export const AI_ERROR_CODES = [
   'X_LLM_STREAM_INVALID',
   'X_AGENT_MAX_TURNS',
   'X_AGENT_TOOL_UNEXPOSED',
+  'X_HIVE_EMPTY',
   'X_EVAL_THRESHOLD',
   'X_EVAL_BASELINE_MISSING',
   'X_EVAL_BASELINE_INVALID',
@@ -45,6 +46,7 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_LLM_STREAM_INVALID: 'a streamed answer failed its output schema, and a stream cannot repair',
   X_AGENT_MAX_TURNS: 'an agent hit its turn ceiling without answering',
   X_AGENT_TOOL_UNEXPOSED: 'an agent lists a tool that is not an MCP-exposed action',
+  X_HIVE_EMPTY: 'a hive split produced no members, so the run did nothing',
   X_EVAL_THRESHOLD: 'an eval scored below its tolerance',
   X_EVAL_BASELINE_MISSING: 'an eval has no recorded baseline to gate against',
   X_EVAL_BASELINE_INVALID: 'a recorded baseline cannot be read',

package/src/fetch-seam.ts

@@ -0,0 +1,15 @@
+// Single responsibility: the one injectable HTTP call every transport in this package takes.
+//
+// Shared by all three rather than declared three times: both chat providers and the embedder hand
+// a URL and a `RequestInit` to something that answers a `Response`, and three separate spellings
+// of that is three places a test double has to be kept assignable to.
+
+/**
+ * Just the call. `typeof fetch` also carries `preconnect`, which no test double should have to —
+ * and none can supply, so every fake written against `typeof fetch` here needed
+ * `as unknown as typeof fetch` to compile: an option no caller could fill without a double cast.
+ *
+ * The same seam `@ultimat3/cache` (`PurgeFetch`), `@ultimat3/auth` (`OAuthFetch`),
+ * `@ultimat3/mail` (`MailFetch`) and `@ultimat3/scraping` (`ScrapeFetch`) already name.
+ */
+export type AiFetch = (input: string, init: RequestInit) => Promise<Response>;

package/src/gateway.ts

@@ -4,6 +4,7 @@
 // budgeted, and cost-accounted in integer minor units. Everything an app does with a model
 // goes through here, so budgets and accounting cannot be bypassed by a stray fetch.
 
+import { renderThrowable } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { BudgetLimits, BudgetStore } from './budget';
 import { BudgetLedger, currentBudget, estimateSpend, withBudget } from './budget';
@@ -126,8 +127,14 @@ class GatewayImpl implements Gateway {
     const ledger = currentBudget();
     const reservation = await ledger?.reserve(estimateSpend(resolved));
 
-    // A stream is not retried mid-flight: the consumer has already seen tokens, and
-    // replaying from the top would duplicate them. Only the handshake retries.
+    // The streaming path does not retry AT ALL — not mid-flight, and not on the handshake either.
+    // Mid-flight is the obvious one: the consumer has already been handed tokens, and replaying
+    // from the top would duplicate them. The handshake is not separable from it here, because
+    // `provider.stream()` is one call that yields — there is no point at which the connection is
+    // open and no chunk has been delivered for a retry to hide behind. So `providerFor` picks the
+    // single provider serving this model and that call stands or throws; `attempt`'s backoff and
+    // its fallback across providers belong to `generate` alone. A caller that wants either uses
+    // `generate`, or reconnects itself and knows what it has already shown.
     const provider = this.providerFor(model);
     let settled = false;
     try {
@@ -183,7 +190,11 @@ class GatewayImpl implements Gateway {
         try {
           return { ...(await call(provider)), provider: provider.name };
         } catch (error) {
-          failures.push(`${provider.name}#${attempt}: ${messageOf(error)}`);
+          // `renderThrowable`, never `error.message` or `String(error)`: this line becomes the
+          // `cause` of `X_AI_PROVIDER_UNAVAILABLE`, and a renderer that throws replaces the coded
+          // refusal with a `TypeError` nothing downstream can catch by code. It bounds the text
+          // too — a provider's 1MB body is not a cause.
+          failures.push(`${provider.name}#${attempt}: ${renderThrowable(error)}`);
           if (!isRetryable(error) || attempt === this.retry.attempts) break;
           await this.sleep(backoffMs(this.retry, attempt));
         }
@@ -205,14 +216,17 @@ export function backoffMs(policy: RetryPolicy, attempt: number): number {
  */
 export function isRetryable(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
-  const e = error as { status?: unknown; code?: unknown };
-  if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
-  return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
-}
-
-function messageOf(error: unknown): string {
-  if (error instanceof Error) return error.message;
-  return String(error);
+  // A `Provider` is the APP's object, so the value it rejected with is one the framework did not
+  // build: `e.status` is a getter call and, on a `Proxy`, a trap. A value that fights being read
+  // cannot be SHOWN to be retryable, and this runs inside the catch block that has nothing left
+  // to answer with — so it fails closed rather than raising.
+  try {
+    const e = error as { status?: unknown; code?: unknown };
+    if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
+    return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/hive-errors.ts

@@ -0,0 +1,30 @@
+// The X_HIVE_* codes, apart from ./errors only because one file has one job and that catalogue is
+// already at its ceiling — the same split `eval-errors.ts` made. The codes, their titles and the
+// single `registerErrorCodes` call stay in ./errors: one owner, one registration, one place a
+// duplicate can surface.
+
+import { UltimateError } from '@ultimat3/core';
+import type { AiErrorCode } from './errors';
+
+const docsFor = (code: AiErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/**
+ * `split` handed back an empty list, so the hive fanned out to nobody and would have reported a
+ * successful run of zero members.
+ *
+ * Refused rather than returned, because the two readings of "0 ok, 0 failed" are "there was
+ * genuinely nothing to do" and "the query behind `split` returned no rows and nobody noticed",
+ * and only the caller can tell them apart. A hive whose empty case is legitimate says so by not
+ * being called: guard the `split` source at the call site, where the emptiness is visible.
+ */
+export class HiveEmptyError extends UltimateError {
+  constructor(input: { member: string }) {
+    super({
+      code: 'X_HIVE_EMPTY',
+      cause: `the hive over "${input.member}" split into 0 members, so no member ran`,
+      fix: `return at least one member input from the hive's split() over "${input.member}", or skip the hive call when the source is empty — a hive reporting 0 ok and 0 failed cannot be told apart from one whose query returned no rows`,
+      docs: docsFor('X_HIVE_EMPTY'),
+      meta: { member: input.member },
+    });
+  }
+}