@ultimat3/ai 29.3.2 → 30.0.0

package/src/run-meter.ts

@@ -104,6 +104,10 @@ export function runMeter(): RunMeter {
           unsettled -= 1;
           absorb(error);
           parent?.report(bill);
+        } else {
+          // Never answered: its bill cannot be known, so it travels up as a count. Without this a
+          // caught failure, or one beside a sibling that settled, vanished from the parent's total.
+          parent?.report(UNSETTLED_CALL);
         }
         throw error;
       }
@@ -131,7 +135,36 @@ export function runMeter(): RunMeter {
   };
 }
 
-/** Two bills as one. A cost in another currency cannot be added and is left out of the sum. */
+/**
+ * One bill across every `llm()` and `agent()` call `fn` makes, however deep they nest — what a
+ * job reads to say what its run cost. A throw is rethrown carrying the total on `meta.billed`
+ * (`billedOf(error)`); `billed` is `undefined` when no provider call was ever started. A meter,
+ * not a ledger: it refuses nothing.
+ */
+export async function meteredRun<T>(
+  fn: () => T | Promise<T>,
+): Promise<{ readonly value: T; readonly billed: Billed | undefined }> {
+  const meter = runMeter();
+  try {
+    const value = await meter.within(fn);
+    return { value, billed: meter.billed() };
+  } catch (error) {
+    throw meter.fail(error);
+  }
+}
+
+/** One started call that never reported usage: counted, never priced. */
+const UNSETTLED_CALL: Billed = {
+  usage: ZERO_USAGE,
+  cost: { minor: 0, currency: 'USD' },
+  calls: 0,
+  unsettled: 1,
+};
+
+/**
+ * Two bills as one. A cost in another currency cannot be added and is left out of the sum — except
+ * a zero, which carries no currency worth keeping: an unsettled call's placeholder never decides it.
+ */
 function sum(a: Billed, b: Billed): Billed {
   return {
     usage: {
@@ -140,7 +173,12 @@ function sum(a: Billed, b: Billed): Billed {
       cacheReadTokens: a.usage.cacheReadTokens + b.usage.cacheReadTokens,
       cacheWriteTokens: a.usage.cacheWriteTokens + b.usage.cacheWriteTokens,
     },
-    cost: a.cost.currency === b.cost.currency ? addMoney(a.cost, b.cost) : a.cost,
+    cost:
+      a.cost.currency === b.cost.currency
+        ? addMoney(a.cost, b.cost)
+        : a.cost.minor === 0
+          ? b.cost
+          : a.cost,
     calls: a.calls + b.calls,
     unsettled: a.unsettled + b.unsettled,
   };

package/src/runtime.ts

@@ -9,7 +9,7 @@
 
 import type { SemanticCache } from '@ultimat3/cache';
 import { memorySemanticCache } from '@ultimat3/cache';
-import { cachedFormatter } from '@ultimat3/core';
+import { asyncContext, cachedFormatter } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { hashEmbedder } from './embeddings';
 import { AiGatewayMissingError } from './errors';
@@ -71,15 +71,50 @@ export function configureAi(input: AiRuntimeInput): void {
   caches.clear();
 }
 
-/** The installed gateway. `prompt` names the caller so the miss says what was about to run. */
+/** A tool double an agent eval declares: the model's arguments in, the tool's result out. */
+export type ToolDouble = (input: Readonly<Record<string, unknown>>) => unknown;
+
+/**
+ * An agent eval in flight (`defineEval({ agent })`): the gateway `run` / `assert` was handed, and
+ * the doubles every tool call resolves to. PRIVATE — not exported from the package — because it is
+ * a measurement seam, never a way to swap an agent's tools in production: `agent({ tools })` stays
+ * the one declaration of what an agent may call.
+ */
+export interface EvalScope {
+  readonly eval: string;
+  readonly gateway: Gateway;
+  readonly tools: Readonly<Record<string, ToolDouble>>;
+  /** Every doubled call the run made, in the order the model asked for them. */
+  readonly calls: { name: string; input: Readonly<Record<string, unknown>> }[];
+}
+
+const evalScopes = asyncContext<EvalScope>('an agent eval');
+
+/** Run `fn` as one agent eval case: its model calls reach `scope.gateway`, its tools the doubles. */
+export function withEvalScope<T>(scope: EvalScope, fn: () => T): T {
+  return evalScopes.run(scope, fn);
+}
+
+/** The agent eval in flight, or `undefined` everywhere else. */
+export function currentEvalScope(): EvalScope | undefined {
+  return evalScopes.get();
+}
+
+/**
+ * The installed gateway. `prompt` names the caller so the miss says what was about to run.
+ * Inside an agent eval it is the eval's: the run measures the gateway the test handed over, never
+ * whatever an earlier test file left installed.
+ */
 export function aiGateway(prompt: string): Gateway {
+  const scoped = evalScopes.get()?.gateway;
+  if (scoped !== undefined) return scoped;
   if (runtime === undefined) throw new AiGatewayMissingError({ prompt });
   return runtime.gateway;
 }
 
 /** The installed gateway, or `undefined` — for a caller that may run without one (`hive()`). */
 export function installedGateway(): Gateway | undefined {
-  return runtime?.gateway;
+  return evalScopes.get()?.gateway ?? runtime?.gateway;
 }
 
 export function aiEmbedder(): Embedder {

package/src/scorers.ts

@@ -5,13 +5,36 @@
 // prompt is a versioned artifact and its hash is part of the scorer's name.
 
 import { assert, finiteCount, finiteOption } from '@ultimat3/core';
+import type { AgentRunUsage } from './agent-usage';
 import type { Gateway } from './gateway';
 import type { Prompt } from './prompt';
 
+/** One tool call an agent eval's run made, answered by the eval's double. */
+export interface EvalToolCall {
+  readonly name: string;
+  readonly input: Readonly<Record<string, unknown>>;
+}
+
+/** What an agent eval's run did beside answering — handed to every scorer of the agent arm. */
+export interface EvalRun {
+  readonly turns: number;
+  /** In the order the model asked for them. */
+  readonly toolCalls: readonly EvalToolCall[];
+  readonly usage: AgentRunUsage;
+}
+
+/** What a scorer reads. `run` is present on the agent arm (`defineEval({ agent })`) only. */
+export interface ScorerInput {
+  /** The answer: the model's text, or on the agent arm the validated output as JSON. */
+  readonly output: string;
+  readonly expected?: string;
+  readonly run?: EvalRun;
+}
+
 /** A scorer returns 0..1. Deterministic scorers are preferred; judges are a last resort. */
 export interface Scorer {
   readonly name: string;
-  score(input: { output: string; expected?: string }): Promise<number> | number;
+  score(input: ScorerInput): Promise<number> | number;
 }
 
 /**
@@ -44,6 +67,17 @@ export const contains: Scorer = {
     expected !== undefined && output.toLowerCase().includes(expected.toLowerCase()) ? 1 : 0,
 };
 
+/**
+ * 1 when the agent's run called `tool` at least once, else 0 — and 0 on the prompt arm, which has
+ * no run. Named per tool, so two of them on one eval are two columns rather than one overwritten.
+ */
+export function calledTool(tool: string): Scorer {
+  return {
+    name: `called-tool:${tool}`,
+    score: ({ run }) => (run?.toolCalls.some((call) => call.name === tool) === true ? 1 : 0),
+  };
+}
+
 /** Output parses as JSON. Pairs with a prompt that declares an `output` schema. */
 export const jsonValid: Scorer = {
   name: 'json-valid',

package/src/scripted-provider.ts

@@ -0,0 +1,146 @@
+// `scriptedProvider()`: the test double that answers with turns written in advance — text, one
+// tool call, several, or the `respond` answer — and records every request. Apart from
+// ./echo-provider because echo cannot call a tool, and a loop under test has to be driven by one.
+
+import { UltimateError } from '@ultimat3/core';
+import { costOf, exactCostOf } from './cost';
+import { resolveModel } from './model-resolve';
+import type { ModelId } from './models';
+import { modelIds } from './models';
+import type {
+  GenerateRequest,
+  GenerateResult,
+  Provider,
+  StopReason,
+  StreamChunk,
+  TokenUsage,
+} from './provider';
+import { estimateTextTokens, estimateTokens } from './provider';
+import { RESPOND } from './respond';
+import type { LlmToolCall } from './tools';
+
+/** One tool call a turn makes. `input` defaults to `{}`. */
+export interface ScriptedCall {
+  readonly call: string;
+  readonly input?: Record<string, unknown>;
+}
+
+/**
+ * One model turn. `stop` overrides the stop reason the form implies (`end_turn` for text,
+ * `tool_use` otherwise) — `'max_tokens'` scripts a cut-off turn.
+ */
+export type ScriptedTurn = (
+  | { readonly text: string }
+  | ScriptedCall
+  | { readonly calls: readonly ScriptedCall[] }
+  | { readonly answer: Record<string, unknown> }
+) & { readonly stop?: StopReason };
+
+export interface ScriptedProviderInput {
+  /** Answered in order, one per provider call. One call past the end is `X_AI_SCRIPT_EXHAUSTED`. */
+  readonly turns: readonly ScriptedTurn[];
+  /** Every turn's usage. Absent: estimated from the request and the turn's text, as echo does. */
+  readonly usage?: TokenUsage;
+  /** What the gateway reports as `provider`, and keys its breaker by. Defaults to `scripted`. */
+  readonly name?: string;
+}
+
+export interface ScriptedProvider extends Provider {
+  /** Every request, in the order it arrived — a streamed one included. */
+  readonly seen: readonly GenerateRequest[];
+}
+
+/**
+ * More provider calls than scripted turns. Never answered by repeating the last turn: a loop that
+ * never calls `respond` would then spin to its ceiling on a script that looks like it passed.
+ */
+export class AiScriptExhaustedError extends UltimateError {
+  constructor(input: { turns: number; model: string }) {
+    super({
+      code: 'X_AI_SCRIPT_EXHAUSTED',
+      cause:
+        `scriptedProvider holds ${input.turns} turn${input.turns === 1 ? '' : 's'} and was ` +
+        `asked for turn ${input.turns + 1} (model "${input.model}")`,
+      fix: 'scriptedProvider({ turns: [...turns, { answer: { /* the expected output */ } }] })   # one more turn, or fix the loop that keeps calling the model',
+      meta: { turns: input.turns },
+    });
+  }
+}
+
+/** The scripted test provider. Serves every registered model, read at call time. */
+export function scriptedProvider(config: ScriptedProviderInput): ScriptedProvider {
+  const seen: GenerateRequest[] = [];
+  // `async`, so every refusal is a rejection — never a synchronous throw out of `generate()`.
+  const generate = async (request: GenerateRequest): Promise<GenerateResult> => {
+    // No model of its own, as echo: the gateway resolves before it routes.
+    const model = resolveModel('scripted-provider', request.model);
+    const turn = config.turns[seen.length];
+    seen.push(request);
+    if (turn === undefined) throw new AiScriptExhaustedError({ turns: config.turns.length, model });
+    return resultOf(model, request, turn, seen.length, config.usage);
+  };
+  return {
+    name: config.name ?? 'scripted',
+    // A getter over the whole registry, not a snapshot: a model registered after construction.
+    get models(): readonly ModelId[] {
+      return modelIds();
+    },
+    seen,
+    generate,
+    // Not a generator: the turn is taken when `stream()` is CALLED, in call order with `generate()`.
+    // A lazy one took it at the first read, so two calls in flight could swap their turns.
+    stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
+      const pending = generate(request);
+      // Read or not, a refusal is not an unhandled rejection; a reader still gets the throw.
+      pending.catch(() => undefined);
+      return chunksOf(pending);
+    },
+  };
+}
+
+async function* chunksOf(pending: Promise<GenerateResult>): AsyncIterable<StreamChunk> {
+  const result = await pending;
+  if (result.text !== '') yield { type: 'text', text: result.text };
+  for (const call of result.toolCalls) yield { type: 'tool-call', call };
+  yield { type: 'done', result };
+}
+
+function callsOf(turn: ScriptedTurn, n: number): readonly LlmToolCall[] {
+  if ('answer' in turn) return [{ id: `call-${n}`, name: RESPOND, input: turn.answer }];
+  if ('call' in turn) return [{ id: `call-${n}`, name: turn.call, input: turn.input ?? {} }];
+  if ('calls' in turn) {
+    return turn.calls.map((one, i) => ({
+      id: `call-${n}-${i + 1}`,
+      name: one.call,
+      input: one.input ?? {},
+    }));
+  }
+  return [];
+}
+
+function resultOf(
+  model: ModelId,
+  request: GenerateRequest,
+  turn: ScriptedTurn,
+  n: number,
+  fixed: TokenUsage | undefined,
+): GenerateResult {
+  const text = 'text' in turn ? turn.text : '';
+  const toolCalls = callsOf(turn, n);
+  const usage: TokenUsage = fixed ?? {
+    inputTokens: estimateTokens({ ...request, model }),
+    outputTokens: estimateTextTokens(text === '' ? JSON.stringify(toolCalls) : text),
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+  };
+  return {
+    model,
+    text,
+    toolCalls,
+    stopReason: turn.stop ?? (toolCalls.length > 0 ? 'tool_use' : 'end_turn'),
+    stopDetails: undefined,
+    usage,
+    cost: costOf(model, usage),
+    costExact: exactCostOf(model, usage),
+  };
+}

package/src/tools-gate.ts

@@ -0,0 +1,46 @@
+// The way a projected tool reaches its `run`: the actor half of the policy, then the tool gate
+// `mcpConfirmations` registered for that name, then the tool. Split from `tools.ts`, which adapts
+// and renders. MCP's order, restated because `mcp` is this package's tier, and for the same reason:
+// a caller the tool refuses outright opens no row for a person to look at.
+
+import { toolGateFor } from '@ultimat3/action';
+import type { Actor } from '@ultimat3/core';
+import type { ProjectableAction } from './tools';
+
+/**
+ * What already passes the gate, by its `run`: projecting one twice would ask twice and spend the
+ * approval on the outer pass. Keyed on the function because `{ ...projected, description }` is a
+ * new object carrying the same `run`, and a second gate on it would never let the tool run.
+ */
+const throughGate = new WeakSet<ProjectableAction['run']>();
+
+export const passesToolGate = (tool: ProjectableAction): boolean => throughGate.has(tool.run);
+
+/**
+ * `tool`, with its `run` behind the gate. The gate is looked up per call, because the module declaring
+ * it may evaluate after the agent listing the tool. `admit` throws for a caller the tool's policy
+ * refuses before reading the input. An ungated tool skips it: `invoke` opens with the same question.
+ */
+export function behindToolGate(
+  tool: ProjectableAction,
+  admit?: (actor: Actor) => void,
+): ProjectableAction {
+  const run: ProjectableAction['run'] = async (args) => {
+    const gate = toolGateFor(tool.name);
+    if (gate === undefined) return tool.run(args);
+    admit?.(args.actor);
+    return gate(
+      {
+        tool: tool.name,
+        args: args.input,
+        inputSchema: tool.inputJsonSchema,
+        actor: args.actor,
+      },
+      async () => tool.run(args),
+    );
+  };
+  throughGate.add(run);
+  // Inherits from `tool`, so what a class declares on its prototype still reads; the own fields are
+  // copied as well, so a spread of this copy keeps them and is not a nameless tool.
+  return Object.assign(Object.create(tool), tool, { run });
+}

package/src/tools.ts

@@ -19,13 +19,28 @@
 // boundary error. Both packages describe the same structural contract.
 
 import type { AnyAction } from '@ultimat3/action';
-import { actionName, invoke, isAction } from '@ultimat3/action';
+import {
+  actionName,
+  admitActionCaller,
+  invoke,
+  isAction,
+  parseActionInput,
+} from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
-import { isMcpExposed, tryUseContext } from '@ultimat3/core';
+import {
+  isMcpExposed,
+  isUltimateError,
+  stringField,
+  toolDescription,
+  tryUseContext,
+} from '@ultimat3/core';
 import type { WireJsonSchema } from '@ultimat3/schema';
 import { toWireSchema } from '@ultimat3/schema';
+import { EvalToolUndoubledError } from './eval-errors';
 import { discloseFailure, discloseOwnFailure } from './failure-disclosure';
+import { currentEvalScope } from './runtime';
 import { takeToolIdempotencyKey, withToolIdempotencyKey } from './tool-idempotency';
+import { behindToolGate, passesToolGate } from './tools-gate';
 
 /**
  * The JSON Schema subset the framework emits for tool arguments — `@ultimat3/schema`'s
@@ -77,6 +92,12 @@ export interface ProjectableAction {
   readonly inProcess?: boolean;
   /** In-process only: `false` withholds its refusals as a projected tool's are. Default `true`. */
   readonly discloseErrors?: boolean;
+  /**
+   * The input parse `run` makes before anything executes, alone: the parsed value, or the same
+   * refusal `run` would throw. What an agent eval holds its tool double to, so arguments production
+   * refuses are refused there too. Absent on a hand-built tool: there is no schema to hold it to.
+   */
+  readonly parseInput?: (raw: unknown) => Promise<unknown>;
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
 }
 
@@ -104,33 +125,51 @@ export type AgentTool = AnyAction | ProjectableAction;
  * projectable object it claims to be.
  */
 export function asProjectableAction(listed: AgentTool): ProjectableAction {
-  if (!isAction(listed)) return listed;
-  const mcp = listed.mcp;
+  if (!isAction(listed)) return passesToolGate(listed) ? listed : behindToolGate(listed);
   // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than offering a tool called `''`:
   // a nameless tool is unaddressable by the model, by `runLlmToolCall` and by the author.
   const name = actionName(listed);
+  const mcp = withDeclaredRefusals(listed.mcp, name, listed.errors);
   const wire = toWireSchema(listed.input);
   // `idempotent: true` is honoured here as over MCP and HTTP: the model's key reaches `invoke`,
   // which files it under the action, the caller and the key. Until 25.0.0 this adapter dropped it,
   // so an action an external agent could retry safely was one an in-app agent could not.
   const keyed = listed.describe().idempotent;
-  return {
-    name,
-    ...(mcp === undefined ? {} : { mcp }),
-    ...(mcp?.description === undefined ? {} : { description: mcp.description }),
-    inputJsonSchema: keyed ? withToolIdempotencyKey(name, wire) : wire,
-    // The actor rides in on the options and `invoke` swaps it inside the one execution path —
-    // the action's own `policy` still decides, and its `input:` still parses what the model sent,
-    // which is what drops a `{ actor: 'admin' }` the model invented before any handler sees it.
-    // No `admit`: MCP's is its early gate ahead of ITS argument validation, and this surface has
-    // none — `invoke` asks the same policy before it reads the input, which is the same order.
-    run: keyed
-      ? ({ input: args, actor }) => {
-          const { input, idempotencyKey } = takeToolIdempotencyKey(args);
-          return invoke(listed, input, { surface: 'mcp', actor, idempotencyKey });
-        }
-      : ({ input, actor }) => invoke(listed, input, { surface: 'mcp', actor }),
-  };
+  return behindToolGate(
+    {
+      name,
+      ...(mcp === undefined ? {} : { mcp }),
+      ...(mcp?.description === undefined ? {} : { description: mcp.description }),
+      inputJsonSchema: keyed ? withToolIdempotencyKey(name, wire) : wire,
+      // `invoke`'s own parse and refusal (`parseActionInput`), after the reserved key is taken off.
+      parseInput: (raw) =>
+        parseActionInput(listed.input, keyed ? takeToolIdempotencyKey(raw).input : raw, name),
+      // The actor rides in on the options and `invoke` swaps it inside the one execution path —
+      // the action's own `policy` still decides, and its `input:` still parses what the model sent,
+      // which is what drops a `{ actor: 'admin' }` the model invented before any handler sees it.
+      run: keyed
+        ? ({ input: args, actor }) => {
+            const { input, idempotencyKey } = takeToolIdempotencyKey(args);
+            return invoke(listed, input, { surface: 'mcp', actor, idempotencyKey });
+          }
+        : ({ input, actor }) => invoke(listed, input, { surface: 'mcp', actor }),
+    },
+    admitActionCaller(listed, name),
+  );
+}
+
+/**
+ * A declared `errors:` ends the description — core's `toolDescription`, the one `@ultimat3/mcp`'s
+ * `exposureOf` calls (held equal by `scripts/ai-mcp-tool-parity.test.ts`). With none written,
+ * its default lead is spelled out before the list.
+ */
+function withDeclaredRefusals<M extends { readonly description?: string }>(
+  mcp: M | undefined,
+  name: string,
+  errors: readonly string[] | undefined,
+): M | undefined {
+  if (mcp === undefined || errors === undefined || errors.length === 0) return mcp;
+  return { ...mcp, description: toolDescription({ name, mcp }, errors) };
 }
 
 /**
@@ -148,8 +187,7 @@ const EMPTY_SCHEMA: JsonSchema = { type: 'object', properties: {}, additionalPro
 export function toLlmTool(action: ProjectableAction): LlmTool {
   return {
     name: action.name,
-    description:
-      action.mcp?.description ?? action.description ?? `Run the "${action.name}" action.`,
+    description: toolDescription(action),
     input_schema: action.inputJsonSchema ?? EMPTY_SCHEMA,
     strict: true,
   };
@@ -188,12 +226,18 @@ export async function runLlmToolCall(
   /** `discloseErrors: false` withholds every in-process tool's refusal (`agent({ discloseToolErrors })`). */
   options: { readonly discloseErrors?: boolean } = {},
 ): Promise<LlmToolResult> {
-  const action = actions.find((a) => a.name === call.name && isOfferedTool(a));
-  if (action === undefined) {
+  const found = actions.find((a) => a.name === call.name && isOfferedTool(a));
+  if (found === undefined) {
     return { toolUseId: call.id, content: `unknown tool: ${call.name}`, isError: true };
   }
+  // This function is exported and documented, so a hand-built tool can arrive unprojected. Its one
+  // pass through the gate is decided here, where the model's call actually runs.
+  const action = asProjectableAction(found);
+  // Outside the `try`: an undoubled call inside an agent eval ends the run, never reaches the model
+  // as a tool result it could route around.
+  const run = evalDoubleFor(action, call);
   try {
-    const output = await action.run({ input: call.input, actor });
+    const output = await run({ input: call.input, actor });
     return resultOf(call.id, output);
   } catch (error) {
     // A policy denial is an outcome the model should read and react to, not a crash.
@@ -202,6 +246,31 @@ export async function runLlmToolCall(
   }
 }
 
+/**
+ * Inside an agent eval (`defineEval({ agent })`) a call resolves to the eval's double and the real
+ * tool never runs: an eval in CI cannot write. A tool with no double is `X_EVAL_TOOL_UNDOUBLED`.
+ * Everywhere else, the tool itself.
+ */
+function evalDoubleFor(tool: ProjectableAction, call: LlmToolCall): ProjectableAction['run'] {
+  const scope = currentEvalScope();
+  if (scope === undefined) return (args) => tool.run(args);
+  const double = Object.hasOwn(scope.tools, call.name) ? scope.tools[call.name] : undefined;
+  if (double === undefined) {
+    throw new EvalToolUndoubledError({
+      eval: scope.eval,
+      tool: call.name,
+      doubled: Object.keys(scope.tools),
+    });
+  }
+  return async ({ input }) => {
+    // Inside the caller's `try`: a refused input is answered to the model exactly as production
+    // answers it, and the double — like the tool's handler — never sees it.
+    const parsed = tool.parseInput === undefined ? input : await tool.parseInput(input);
+    scope.calls.push({ name: call.name, input: call.input });
+    return double(parsed as Readonly<Record<string, unknown>>);
+  };
+}
+
 /**
  * One tool's return value as the `tool_result` text. `content` is typed `string` and the agent
  * loop TRUNCATES it, so anything else ends the run in a `TypeError` two frames away — and the
@@ -266,5 +335,10 @@ function describeFailure(error: unknown, tool: ProjectableAction, disclose: bool
     });
   }
   const line = `${shown.code}: ${shown.cause ?? HIDDEN_TOOL_CAUSE}`;
-  return shown.fix === undefined ? line : `${line} (fix: ${shown.fix})`;
+  // The model is a caller: an error we built that says what a caller does says it here, as an app's
+  // MCP server does (`errorAudience: 'caller'`). `x policy explain` is not a command a model can run,
+  // and a pending confirmation's developer fix tells it to call a decision action it is not offered.
+  const callerFix = isUltimateError(error) ? stringField(error, 'callerFix') : undefined;
+  const fix = callerFix ?? shown.fix;
+  return fix === undefined ? line : `${line} (fix: ${fix})`;
 }

package/src/wire.ts

@@ -215,17 +215,25 @@ export class MessageStream {
   }
 
   private payloadOf(frame: SseFrame): Record<string, unknown> {
+    let parsed: unknown;
     try {
-      const parsed: unknown = JSON.parse(frame.data);
-      const record = asRecord(parsed);
-      if (record === undefined) throw new SyntaxError('frame data is not an object');
-      return record;
+      parsed = JSON.parse(frame.data);
     } catch (error) {
       throw new AiTransportError({
         provider: 'anthropic',
         detail: `unreadable "${frame.event}" frame: ${renderThrowable(error)}`,
       });
     }
+    const record = asRecord(parsed);
+    if (record === undefined) {
+      // The same coded refusal the catch above produces, thrown where the frame is known: a bare
+      // `SyntaxError` in shipped source carries no code, no cause and no fix.
+      throw new AiTransportError({
+        provider: 'anthropic',
+        detail: `unreadable "${frame.event}" frame: frame data is not an object`,
+      });
+    }
+    return record;
   }
 
   private onMessageStart(payload: Record<string, unknown>): readonly StreamChunk[] {