@ultimat3/ai 2.0.0 → 3.0.0

package/src/hive-result.ts

@@ -0,0 +1,96 @@
+// What a hive run answers, as a TYPE and as a SCHEMA built from the member's own `output`.
+//
+// It is a schema and not a plain interface because `hive()` returns an `action`, and an action's
+// `output:` is what drives `validateOutput`, the OpenAPI response body, the typed client, the MCP
+// tool and the manifest row. A hand-written interface would give the type and none of the six
+// projections — the whole reason a hive is a factory over `action()` rather than a helper.
+
+import type { Money } from '@ultimat3/money';
+import type { AnySchema, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+
+/**
+ * One member's outcome. THREE arms, not two: a member that ran and threw and a member that never
+ * ran at all are different facts, and the second one is what an aborted sibling is. Collapsing
+ * them would make "the hive stopped early" indistinguishable from "every remaining item is bad
+ * data", which is the difference between retrying the tail and fixing the source.
+ *
+ * `index` is the position in `split`'s output on every arm, so a caller can join a result back to
+ * the row it came from without depending on array position surviving a filter.
+ */
+export type HiveMember<O> =
+  | { readonly status: 'ok'; readonly index: number; readonly value: O }
+  | {
+      readonly status: 'failed';
+      readonly index: number;
+      /** The `UltimateError` code the member threw, or `'unknown'` for a foreign throw. */
+      readonly code: string;
+      readonly reason: string;
+    }
+  | { readonly status: 'skipped'; readonly index: number; readonly reason: string };
+
+export interface HiveResult<O> {
+  /** In SPLIT order, always — never completion order, and never with the failures filtered out. */
+  readonly members: readonly HiveMember<O>[];
+  readonly ok: number;
+  readonly failed: number;
+  /**
+   * Published beside `ok` and `failed` rather than left to be derived: three arms and two counters
+   * means `members.length - ok - failed`, and a caller who writes that once writes it wrong once.
+   */
+  readonly skipped: number;
+  /** Tokens the whole run debited, every member counted, from the hive's own derived ledger. */
+  readonly tokens: number;
+  readonly cost: Money;
+}
+
+/** The declared shape of `hive()`'s output, given the member action's own `output`. */
+export type HiveOutput<MOut extends AnySchema> = StandardSchemaV1<
+  unknown,
+  HiveResult<InferOutput<MOut>>
+>;
+
+/** What a member failure means for its siblings. No default: both answers are somebody's bug. */
+export type HiveMemberError =
+  /** Stop. Siblings that have not started are `skipped`; ones in flight see the aborted signal. */
+  | 'abort'
+  /** Record it as `failed` and keep going — a partial harvest is the point of a hive. */
+  | 'collect';
+
+export const SKIPPED_ABORTED = 'a sibling failed and onMemberError is abort';
+
+/**
+ * The OTHER way a member never runs, and a different fact: `split` produced nothing at this
+ * index. Its own string because `SKIPPED_ABORTED` named a cause that did not happen — a caller
+ * reading it retries the tail against a hive that stopped early, when the split is what to fix.
+ */
+export const SKIPPED_NO_INPUT = 'split produced no input at this index';
+
+/**
+ * The member's `output` embedded verbatim in the `ok` arm, so a hive over `summarisePost` publishes
+ * a summary in its OpenAPI response and its MCP `outputSchema` — not an opaque object.
+ *
+ * A DISCRIMINATED union, not a plain one: `status` routes the parse, so a malformed `ok` reports
+ * that arm's issues instead of all three arms' at once.
+ */
+export function hiveResultSchema(output: AnySchema): AnySchema {
+  const member = t.discriminatedUnion(
+    'status',
+    t.object({ status: t.literal('ok'), index: t.number.int(), value: output }),
+    t.object({
+      status: t.literal('failed'),
+      index: t.number.int(),
+      code: t.string,
+      reason: t.string,
+    }),
+    t.object({ status: t.literal('skipped'), index: t.number.int(), reason: t.string }),
+  );
+  return t.object({
+    members: t.array(member),
+    ok: t.number.int(),
+    failed: t.number.int(),
+    skipped: t.number.int(),
+    tokens: t.number.int(),
+    cost: t.money,
+  });
+}

package/src/hive.ts

@@ -0,0 +1,177 @@
+/**
+ * `hive()` — one action fanned out over many inputs, declared as an `action`.
+ *
+ * The fourth instance of the framework's factory rule, after `llm()`, `backfill()` and `agent()`:
+ * a fan-out is still one server-authoritative operation with an input schema, an output schema and
+ * a policy, so this returns an `action` and inherits `.tool()`, `.openapi()`, `.client()`,
+ * `.job()`, `.contract()` and its manifest row without a line here.
+ *
+ * It exists because the alternative is a hand-rolled `Promise.all` over `agent()` calls, and that
+ * loop gets four things wrong every time: it takes the actor from somewhere other than the request,
+ * it reports results in completion order, it cannot tell "ran and failed" from "never ran", and it
+ * has no ceiling — so the first bad split spends the whole budget in parallel.
+ */
+
+import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import { action, actionName } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import { throwIfAborted, withSpan } from '@ultimat3/core';
+import type { AnySchema, InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { BudgetLimits } from './budget';
+import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { HiveEmptyError } from './hive-errors';
+import { runPool } from './hive-pool';
+import type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
+import { hiveResultSchema } from './hive-result';
+import type { LlmBudget } from './llm';
+
+/**
+ * Members in flight at once when the declaration omits one. Small and deliberately arbitrary — it
+ * is a floor to start from, not a number measured off any run: the framework cannot know a
+ * provider's concurrency allowance, and a default read off one benchmark would be wrong for
+ * everybody else's account. Raise it in the declaration once the run demonstrably fits.
+ */
+const DEFAULT_CONCURRENCY = 4;
+
+/**
+ * Below this many members the split is not fanned out at all. A member carries a fixed cost — a
+ * child context, a derived ledger, a whole model call's handshake — and paying it in parallel for
+ * one or two items buys nothing but a second way for the run to fail.
+ */
+const DEFAULT_MIN_MEMBERS = 2;
+
+export interface HiveSplitArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface HiveDef<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+> {
+  readonly input: TInput;
+  /**
+   * The action every member runs — an `agent()`, an `llm()`, or any action at all. Its own
+   * `policy` decides every member call and its own `input:` parses every member payload, which is
+   * what keeps a hive from being a second authz system.
+   */
+  readonly member: Action<MIn, MOut>;
+  /**
+   * The one declared place a run decides what the members are. Derived from `input` and `ctx` and
+   * from NOTHING a model emitted — that boundary is the same one `agent()` holds, and the reason
+   * both belong in the framework rather than in a loop somebody writes per feature.
+   */
+  split(
+    args: HiveSplitArgs<TInput>,
+  ): readonly InferInput<MIn>[] | Promise<readonly InferInput<MIn>[]>;
+  /** Members in flight at once. */
+  readonly concurrency?: number;
+  /** Below this many members the split runs serially instead of fanning out. */
+  readonly minMembers?: number;
+  readonly onMemberError: HiveMemberError;
+  /** Ceilings for the WHOLE fan-out. `tokensPerRun` is the run's, every member counted. */
+  readonly budget?: LlmBudget & { readonly tokensPerRun?: number };
+  readonly policy: ActionPolicy;
+  readonly mcp?: ActionMcp;
+}
+
+export function hive<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+>(def: HiveDef<TInput, MIn, MOut>): Action<TInput, HiveOutput<MOut>> {
+  // The one cast in this file, and it narrows nothing at runtime: `hiveResultSchema` builds the
+  // shape `HiveResult<InferOutput<MOut>>` describes, and this restates that in the type system
+  // rather than making the caller infer it back out of a nested `t.discriminatedUnion`.
+  const output = hiveResultSchema(def.member.output) as HiveOutput<MOut>;
+  return action<TInput, HiveOutput<MOut>>({
+    input: def.input,
+    output,
+    policy: def.policy,
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    handle: (args) => run(def, args),
+  });
+}
+
+async function run<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+>(
+  def: HiveDef<TInput, MIn, MOut>,
+  args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
+): Promise<HiveResult<InferOutput<MOut>>> {
+  const name = actionName(def.member);
+  const inputs = await def.split({ input: args.input, ctx: args.ctx });
+  if (inputs.length === 0) throw new HiveEmptyError({ member: name });
+
+  const floor = def.minMembers ?? DEFAULT_MIN_MEMBERS;
+  // A split below the floor still runs every input it produced — dropping one would be silent
+  // data loss — it just stops paying for a pool to do it.
+  const width =
+    inputs.length < floor
+      ? 1
+      : Math.max(1, Math.min(def.concurrency ?? DEFAULT_CONCURRENCY, inputs.length));
+
+  return withSpan('ai.hive', async (span) => {
+    span.setAttributes({
+      'hive.member': name,
+      'hive.members': inputs.length,
+      'hive.concurrency': width,
+      'hive.on_member_error': def.onMemberError,
+    });
+    const ledger = (currentBudget() ?? new BudgetLedger({ limits: {} })).derive(limitsOf(def));
+    const result = await withBudget(ledger, () =>
+      runPool<InferInput<MIn>, InferOutput<MOut>>({
+        inputs,
+        width,
+        ctx: args.ctx,
+        onMemberError: def.onMemberError,
+        member: (payload) => def.member(payload),
+      }),
+    );
+    // The caller went away DURING the fan-out. Distinct from `onMemberError: 'abort'`, which is a
+    // completed run that stopped early and has a partial harvest worth returning: here there is
+    // nobody left to hand it to, so unwind the way every other abort in this package does.
+    throwIfAborted(args.ctx);
+    const report = await ledger.report();
+    const counts = tally(result);
+    span.setAttributes({ ...counts, 'hive.tokens': report.requestTokens });
+    return {
+      members: result,
+      ok: counts['hive.ok'],
+      failed: counts['hive.failed'],
+      skipped: counts['hive.skipped'],
+      tokens: report.requestTokens,
+      cost: report.cost,
+    };
+  });
+}
+
+function tally<O>(members: readonly HiveMember<O>[]): {
+  'hive.ok': number;
+  'hive.failed': number;
+  'hive.skipped': number;
+} {
+  return {
+    'hive.ok': members.filter((one) => one.status === 'ok').length,
+    'hive.failed': members.filter((one) => one.status === 'failed').length,
+    'hive.skipped': members.filter((one) => one.status === 'skipped').length,
+  };
+}
+
+function limitsOf<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+>(def: HiveDef<TInput, MIn, MOut>): BudgetLimits {
+  const budget = def.budget;
+  return {
+    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+    // The ledger's `request` scope accumulates across every call made under it, which for a hive
+    // under `withBudget` is every member's every turn.
+    ...(budget?.tokensPerRun === undefined ? {} : { request: budget.tokensPerRun }),
+  };
+}

package/src/index.ts

@@ -4,8 +4,12 @@
 /** Re-exported so an `llm` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
-export type { AgentBudget, AgentDef, AgentVarsArgs } from './agent';
+export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent';
 export { agent } from './agent';
+export type { AgentBudgetFact, AgentFact } from './agent-facts';
+export { describeAgents, resetAgents } from './agent-facts';
+export type { AgentJobOptions } from './agent-job';
+export { agentJob } from './agent-job';
 export type {
   BudgetLedgerInput,
   BudgetLimits,
@@ -89,6 +93,10 @@ export {
 } from './evals';
 export type { CreateGatewayInput, Gateway, GatewayCache, RetryPolicy } from './gateway';
 export { backoffMs, cacheKeyFor, createGateway, DEFAULT_RETRY, isRetryable } from './gateway';
+export type { HiveDef, HiveSplitArgs } from './hive';
+export { hive } from './hive';
+export { HiveEmptyError } from './hive-errors';
+export type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
 export type {
   LlmAction,
   LlmBudget,
@@ -201,13 +209,14 @@ export {
   numericTolerance,
 } from './scorers';
 export type {
+  AgentTool,
   JsonSchema,
   LlmTool,
   LlmToolCall,
   LlmToolResult,
   ProjectableAction,
 } from './tools';
-export { runLlmToolCall, toLlmTool, toLlmTools } from './tools';
+export { asProjectableAction, runLlmToolCall, toLlmTool, toLlmTools } from './tools';
 export type {
   HybridSearchInput,
   MemoryVectorStoreInput,

package/src/openai-provider.ts

@@ -114,14 +114,22 @@ class OpenAiProvider implements Provider {
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     if (requiresStreaming(request)) return this.assemble(request);
     const model = this.modelOf(request);
-    const response = await this.send(chatCompletionBody({ request, model, stream: false }), false);
+    const response = await this.send(
+      chatCompletionBody({ request, model, stream: false }),
+      false,
+      request.signal,
+    );
     const answer = parseChatCompletion((await response.json()) as unknown, this.name);
     return this.result(request, model, answer);
   }
 
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = this.modelOf(request);
-    const response = await this.send(chatCompletionBody({ request, model, stream: true }), true);
+    const response = await this.send(
+      chatCompletionBody({ request, model, stream: true }),
+      true,
+      request.signal,
+    );
     if (response.body === null) {
       throw new AiTransportError({
         provider: this.name,
@@ -183,7 +191,11 @@ class OpenAiProvider implements Provider {
    * its status, because the gateway decides whether to retry from that status and a body parsed as
    * if it were a message would read as an empty, successful answer.
    */
-  private async send(body: Record<string, unknown>, streaming: boolean): Promise<Response> {
+  private async send(
+    body: Record<string, unknown>,
+    streaming: boolean,
+    signal: AbortSignal | undefined,
+  ): Promise<Response> {
     const apiKey = this.apiKey();
     const doFetch = this.config.fetch ?? fetch;
     const response = await doFetch(this.url(), {
@@ -199,6 +211,8 @@ class OpenAiProvider implements Provider {
         ...this.config.headers,
       },
       body: JSON.stringify(body),
+      // Attached only when the caller has one — same rule, same reason, as the Anthropic half.
+      ...(signal === undefined ? {} : { signal }),
     });
     if (!response.ok) {
       throw new AiTransportError({

package/src/provider.ts

@@ -73,6 +73,15 @@ export interface GenerateRequest {
   readonly thinking?: ThinkingMode;
   readonly tools?: readonly LlmTool[];
   readonly stopSequences?: readonly string[];
+  /**
+   * The caller's abort signal, forwarded to the socket by every provider in this package.
+   *
+   * Deliberately absent from `cacheKeyFor` and from every estimate: it says whether a request was
+   * ABANDONED, never what it asked for, so two calls that differ only in it are the same call and
+   * must share a cache entry. Omitted means the call runs to completion — there is no ambient
+   * default, because a timeout the caller did not ask for is a truncated answer nothing reports.
+   */
+  readonly signal?: AbortSignal;
 }
 
 export interface TokenUsage {
@@ -216,7 +225,7 @@ export class AnthropicProvider implements Provider {
    */
   async generate(request: GenerateRequest): Promise<GenerateResult> {
     if (requiresStreaming(request)) return this.assemble(request);
-    const response = await this.send({ ...this.body(request), stream: false });
+    const response = await this.send({ ...this.body(request), stream: false }, request.signal);
     const raw = (await response.json()) as Record<string, unknown>;
     return parseMessage(request.model ?? DEFAULT_MODEL, raw);
   }
@@ -239,7 +248,7 @@ export class AnthropicProvider implements Provider {
    */
   async *stream(request: GenerateRequest): AsyncIterable<StreamChunk> {
     const model = request.model ?? DEFAULT_MODEL;
-    const response = await this.send({ ...this.body(request), stream: true });
+    const response = await this.send({ ...this.body(request), stream: true }, request.signal);
     if (response.body === null) {
       throw new AiTransportError({
         provider: this.name,
@@ -286,7 +295,10 @@ export class AnthropicProvider implements Provider {
    * carrying its status, because the gateway decides whether to retry from that status and a
    * body parsed as if it were a message would read as an empty, successful answer.
    */
-  private async send(body: Record<string, unknown>): Promise<Response> {
+  private async send(
+    body: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+  ): Promise<Response> {
     const apiKey = this.config.apiKey ?? Bun.env[API_KEY_ENV];
     if (apiKey === undefined || apiKey === '') {
       throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
@@ -302,6 +314,9 @@ export class AnthropicProvider implements Provider {
         accept: body['stream'] === true ? 'text/event-stream' : 'application/json',
       },
       body: JSON.stringify(body),
+      // Attached only when the caller has one: `exactOptionalPropertyTypes`, and an explicit
+      // `signal: undefined` is a different value to some fetch implementations.
+      ...(signal === undefined ? {} : { signal }),
     });
     if (!response.ok) {
       throw new AiTransportError({

package/src/tools.ts

@@ -8,13 +8,20 @@
 // `run` below is `ProjectableAction`'s — the projection SEAM, which is what carries `invoke`.
 // It is not a member of the action facade: an `action()` is `as`/`tool`/`openapi`/`job`/
 // `contract` and the callable itself, and this header claimed `action.run` until 2026-08.
+// `asProjectableAction` is what BUILDS that seam out of a real `action()`, so an app writes
+// `agent({ tools: [publishPost] })` and never a hand-shaped stand-in — the same union
+// @ultimat3/mcp's `ListedPrimitive` accepts, adapted at this package's own edge because the two
+// wire formats want different schemas (issue #124).
 //
 // The JSON Schema type and the projectable-primitive shape are declared here rather than
 // imported from @ultimat3/mcp: that package is the same tier, so importing it would be a
 // boundary error. Both packages describe the same structural contract.
 
+import type { AnyAction } from '@ultimat3/action';
+import { actionName, invoke, isAction } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
+import { isMcpExposed, stringField } from '@ultimat3/core';
+import { toMcpInputSchema } from '@ultimat3/schema';
 
 /** The JSON Schema subset the framework emits for tool arguments. */
 export interface JsonSchema {
@@ -68,6 +75,57 @@ export interface ProjectableAction {
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
 }
 
+/**
+ * What `agent({ tools })` accepts: the real primitive an app writes, or a pre-projected one.
+ *
+ * The real `action()` comes first because it is what an app has. Until 2026-08 this list took
+ * `ProjectableAction` alone, which no `action()` structurally satisfies — an action carries
+ * `as`/`tool`/`openapi`/`job`/`contract` and never `run` — so the documented shape
+ * `agent({ tools: [publishPost] })` was a `TS2741` and every test in this package hand-built a
+ * stand-in, which is why the suite stayed green over an API that did not compile (issue #124).
+ * `ProjectableAction` stays in the union for a surface that builds its catalog programmatically
+ * and for a test that projects a fake.
+ */
+export type AgentTool = AnyAction | ProjectableAction;
+
+/**
+ * Adapt whatever the author listed. The same shape @ultimat3/mcp's `asProjectable` produces, from
+ * the same `invoke` — an in-app agent and an external MCP client end at one execution path, so one
+ * policy decides both. It is not shared code and cannot be: `mcp` is this package's own tier, and
+ * the two projections narrow the schema differently on purpose (`toWireSchema` publishes only what
+ * that server's arg validator will hold a call to; this one publishes the tool schema the Messages
+ * API reads).
+ *
+ * `isAction` is structural against @ultimat3/action's PRIVATE declaration store, so a look-alike
+ * carrying `kind: 'action'` cannot take the first branch — it falls through as the already
+ * projectable object it claims to be.
+ */
+export function asProjectableAction(listed: AgentTool): ProjectableAction {
+  if (!isAction(listed)) return listed;
+  const mcp = listed.mcp;
+  return {
+    // 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.
+    name: actionName(listed),
+    ...(mcp === undefined ? {} : { mcp }),
+    ...(mcp?.description === undefined ? {} : { description: mcp.description }),
+    inputJsonSchema: toMcpInputSchema(listed.input),
+    // 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: ({ input, actor }) => invoke(listed, input, { surface: 'mcp', actor }),
+  };
+}
+
+/**
+ * The tool's name for an error message, before anything is registered. Never `actionName()`:
+ * `X_AGENT_TOOL_UNEXPOSED` is raised at declaration, where an action beside it in the same module
+ * has no name yet, and a naming failure there would hide the exposure failure being reported.
+ */
+export function toolLabel(listed: AgentTool): string {
+  return listed.name === '' ? '(an unregistered action)' : listed.name;
+}
+
 const EMPTY_SCHEMA: JsonSchema = { type: 'object', properties: {}, additionalProperties: false };
 
 /** One action → one LLM tool definition. Opt-in via `mcp.expose`, same flag as MCP. */
@@ -108,18 +166,47 @@ export async function runLlmToolCall(
   }
   try {
     const output = await action.run({ input: call.input, actor });
-    return { toolUseId: call.id, content: JSON.stringify(output) };
+    return resultOf(call.id, output);
   } catch (error) {
     // A policy denial is an outcome the model should read and react to, not a crash.
     return { toolUseId: call.id, content: describeFailure(error), isError: true };
   }
 }
 
+/**
+ * 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
+ * value is an app's, so neither of `JSON.stringify`'s two other answers can be assumed away:
+ * `undefined` for a handler that returns nothing, and a throw on a bigint, a cycle or a `toJSON`
+ * of its own. A throw is reported as what it is — the call SUCCEEDED and its value cannot be
+ * read — never as a failure, because a model told the tool failed calls it again and buys its
+ * side effects twice.
+ */
+function resultOf(toolUseId: string, output: unknown): LlmToolResult {
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(output);
+  } catch {
+    return {
+      toolUseId,
+      content:
+        'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — do not call it again',
+      isError: true,
+    };
+  }
+  return { toolUseId, content: text ?? 'null' };
+}
+
+/**
+ * The thrown value, read STRUCTURALLY and totally. `stringField` from `@ultimat3/core`, never
+ * `typeof e.code === 'string'`: the value is whatever an app's handler, its driver or its SDK
+ * threw, so each read is a getter call or a `Proxy` trap — and it runs inside the catch block
+ * that has nothing left to answer the model with if the probe itself raises.
+ */
 function describeFailure(error: unknown): string {
-  if (typeof error !== 'object' || error === null) return 'tool failed';
-  const e = error as { code?: unknown; cause?: unknown; fix?: unknown };
-  if (typeof e.code !== 'string') return 'tool failed';
-  const cause = typeof e.cause === 'string' ? e.cause : 'unknown';
-  const fix = typeof e.fix === 'string' ? e.fix : '';
-  return fix === '' ? `${e.code}: ${cause}` : `${e.code}: ${cause} (fix: ${fix})`;
+  const code = stringField(error, 'code');
+  if (code === undefined) return 'tool failed';
+  const cause = stringField(error, 'cause') ?? 'unknown';
+  const fix = stringField(error, 'fix') ?? '';
+  return fix === '' ? `${code}: ${cause}` : `${code}: ${cause} (fix: ${fix})`;
 }