@kindgi/agents 0.0.0-bootstrap.0 → 0.1.1

package/src/handlers/errors.ts

@@ -0,0 +1,282 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { EvaluationResult } from '@kindgi/guardrails';
+import type { PolicyKind } from '@kindgi/policy-contract';
+
+import type { AgentError } from '../errors.js';
+import type {
+  GuardrailViolationError,
+  HitlRequiredError,
+  UnresolvedGuardrailError,
+} from '../guardrails-gate.js';
+
+/** Structured error returned to the caller when an agent turn fails. */
+export type InvokeAgentError =
+  | AgentError
+  | UnresolvedToolError
+  | ToolVersionUnresolvableError
+  | CapabilityRoutingError
+  | ModelInvocationError
+  | ToolInvocationError
+  | BudgetExceededError
+  | AgentTurnAbortedError
+  | HitlRequiredError
+  | GuardrailViolationError
+  | UnresolvedGuardrailError
+  | OutputSchemaViolationError
+  | TenantPolicyUnavailableError;
+
+/**
+ * A tenant policy the turn must apply couldn't be: its spec doesn't
+ * validate, or the policy registry failed. The turn doesn't run without
+ * it — skipping a tenant's `hitl` policy would skip its approvals.
+ */
+export interface TenantPolicyUnavailableError {
+  readonly code: 'tenant-policy-unavailable';
+  readonly message: string;
+  readonly policyKind: PolicyKind;
+}
+
+export interface UnresolvedToolError {
+  readonly code: 'unresolved-tool';
+  readonly message: string;
+  readonly toolId: string;
+  /**
+   * Failed tool calls sent back to the model this turn before this one
+   * ended it (see `Agent.toolErrors`). Present when the failure is a
+   * kind the turn retries and its retries ran out.
+   */
+  readonly toolRetries?: number;
+}
+
+/**
+ * The agent references a tool that is registered but whose semver range
+ * does not match any registered version, or whose range is grammatically
+ * broken. Distinct from `unresolved-tool` (no id registered).
+ */
+export interface ToolVersionUnresolvableError {
+  readonly code: 'tool-version-unresolvable';
+  readonly message: string;
+  readonly toolId: string;
+  readonly requestedRange: string;
+  readonly availableVersions?: readonly string[];
+}
+
+export interface CapabilityRoutingError {
+  readonly code: 'capability-routing-failed';
+  readonly message: string;
+  readonly cause: unknown;
+}
+
+export interface ModelInvocationError {
+  readonly code: 'model-invocation-failed';
+  readonly message: string;
+  readonly cause: unknown;
+}
+
+export interface ToolInvocationError {
+  readonly code: 'tool-invocation-failed';
+  readonly message: string;
+  readonly toolId: string;
+  readonly cause: unknown;
+  /**
+   * When the inner failure was an AJV input-schema validation, the
+   * validator's `errors[]` array. Hoisted from `cause` to the top
+   * level so it survives `toWireError` (which filters `cause` to
+   * avoid Error-instance / cycle serialization hazards). Consumers
+   * inspecting *which* field failed *how* read this; `fromWire` in
+   * `@kindgi/client` projects it back onto the client-side error.
+   */
+  readonly validationIssues?: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * The exact payload the model produced that failed validation.
+   * Included so authors debugging LLM-tool-arg drift can see whether
+   * the model sent `{}`, `{ location: "" }`, `{ city: "…" }`
+   * (wrong field name), etc. without instrumenting their handler.
+   * Size-capped at ~4KiB stringified — larger payloads truncate
+   * with a trailing `…`; sensitive tools should sanitize inputs
+   * upstream.
+   */
+  readonly receivedInput?: unknown;
+  /**
+   * Failed tool calls sent back to the model this turn before this one
+   * ended it (see `Agent.toolErrors`). Present when the failure is a
+   * kind the turn retries and its retries ran out.
+   */
+  readonly toolRetries?: number;
+}
+
+export interface BudgetExceededError {
+  readonly code: 'budget-exceeded';
+  readonly message: string;
+  readonly kind: 'steps' | 'cost' | 'wall-time';
+  readonly limit: number;
+  readonly observed: number;
+}
+
+/**
+ * The agent declares an `output` schema and its final answer still
+ * didn't fit after the allowed repairs. `errors` lists the last
+ * attempt's problems; `attempts` counts the answers checked.
+ */
+export interface OutputSchemaViolationError {
+  readonly code: 'output-schema-violation';
+  readonly message: string;
+  readonly errors: readonly string[];
+  readonly attempts: number;
+}
+
+export interface AgentTurnAbortedError {
+  readonly code: 'agent-turn-aborted';
+  readonly message: string;
+  readonly reason: 'external' | 'timeout';
+}
+
+/**
+ * Thrown by a node handler when a precondition fails or a runtime step
+ * short-circuits with a structured error. The kernel captures
+ * `Error.message` into `step.failed.payload.message`; we serialize the
+ * full structured error as JSON so `projectRunResult` can recover the
+ * discriminated union shape on the way out.
+ *
+ * Deliberately narrowed to `Error` subclass so `cause` becomes a plain
+ * property (JSON-round-trippable) instead of the native ErrorOptions
+ * behavior.
+ */
+export class AgentTurnFailure extends Error {
+  readonly payload: InvokeAgentError;
+  constructor(payload: InvokeAgentError) {
+    super(serializeError(payload));
+    this.name = 'AgentTurnFailure';
+    this.payload = payload;
+  }
+}
+
+const FAILURE_SENTINEL = '__agent_turn_failure__' as const;
+
+interface SerializedFailure {
+  readonly [FAILURE_SENTINEL]: true;
+  readonly error: InvokeAgentError;
+}
+
+/**
+ * Encode an `InvokeAgentError` as a JSON string carried in an Error's
+ * message. The sentinel field lets `parseFailureMessage` distinguish
+ * our structured failures from other error messages that happen to be
+ * JSON-shaped.
+ *
+ * `cause` fields on inner errors are downgraded to their message form
+ * so the payload is JSON-safe.
+ */
+function serializeError(error: InvokeAgentError): string {
+  return JSON.stringify(
+    {
+      [FAILURE_SENTINEL]: true as const,
+      error: stripCauseFunctions(error),
+    } satisfies SerializedFailure,
+    (_key, value) => {
+      if (value instanceof Error) {
+        return { code: (value as { code?: string }).code, message: value.message };
+      }
+      return value;
+    },
+  );
+}
+
+function stripCauseFunctions(error: InvokeAgentError): InvokeAgentError {
+  // JSON.stringify replacer above handles Error instances; nothing more
+  // to do here. A pass-through hook for error variants that embed
+  // callbacks.
+  return error;
+}
+
+/**
+ * Attempt to reconstruct a structured `InvokeAgentError` from a run's
+ * `failureMessage`. Returns `undefined` when the message is not one of
+ * ours (e.g. a raw kernel-level exception message).
+ */
+export function parseFailureMessage(raw: string | undefined): InvokeAgentError | undefined {
+  if (raw === undefined || raw.length === 0) return undefined;
+  // Fast path: the raw message IS the single serialized failure (one
+  // step.failed for the whole turn, which is the common case).
+  const whole = tryParseChunk(raw);
+  if (whole !== undefined) return whole;
+  // Fallback: the kernel joins multiple step.failed messages with '; '.
+  // Recover by extracting balanced-brace substrings and trying each.
+  for (const chunk of extractJsonCandidates(raw)) {
+    const parsed = tryParseChunk(chunk);
+    if (parsed !== undefined) return parsed;
+  }
+  return undefined;
+}
+
+/**
+ * Extract substrings that look like well-formed JSON objects by
+ * scanning for balanced braces. Only single-level scan — inner strings
+ * are respected. Cheap parser used for the rare multi-failure case.
+ */
+function extractJsonCandidates(raw: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < raw.length; i++) {
+    const ch = raw[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === '{') {
+      if (depth === 0) start = i;
+      depth += 1;
+    } else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0 && start >= 0) {
+        out.push(raw.slice(start, i + 1));
+        start = -1;
+      }
+    }
+  }
+  return out;
+}
+
+function tryParseChunk(chunk: string): InvokeAgentError | undefined {
+  const trimmed = chunk.trim();
+  if (!trimmed.startsWith('{')) return undefined;
+  try {
+    const doc = JSON.parse(trimmed) as SerializedFailure | Record<string, unknown>;
+    if (
+      typeof doc === 'object' &&
+      doc !== null &&
+      (doc as SerializedFailure)[FAILURE_SENTINEL] === true
+    ) {
+      return (doc as SerializedFailure).error;
+    }
+  } catch {
+    // Not our JSON — probably a raw JS Error.message. Fall through.
+  }
+  return undefined;
+}
+
+/** Helper for handlers to short-circuit with a structured error. */
+export function throwAgentTurnFailure(error: InvokeAgentError): never {
+  throw new AgentTurnFailure(error);
+}
+
+/**
+ * Placeholder to satisfy TS-strict "declared but unused" on
+ * `EvaluationResult` in ambient imports elsewhere; the type is used
+ * transitively via `GuardrailViolationError`.
+ */
+export type _EvaluationResultAlias = EvaluationResult;

package/src/handlers/evaluate-guardrails.ts

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { NodeHandler } from '@kindgi/handler';
+import type { Timestamp } from '@kindgi/types';
+
+import {
+  buildRunTrace,
+  categorizeOutcomes,
+  describeBlockingViolations,
+  evaluateGate,
+} from '../guardrails-gate.js';
+import { emitTurnEvent } from '../streaming.js';
+import type { ConversationMessage } from '../types.js';
+
+import type { TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+import { finalIteration } from './final-iteration.js';
+import { parseJsonAnswer } from './structured-output.js';
+
+/**
+ * Guardrail gate on the turn's final response, before it is stored.
+ * Receives the agent loop's output. A failed guardrail whose action is
+ * `halt` throws, so the run fails and the response never reaches the
+ * conversation; failures with any other action are stashed on `ctx` for
+ * `compose-result` to surface in `AgentTurnResult.violations`. Every
+ * failure emits a `guardrail.violated` event. Also records the
+ * response's `model-output` provenance node, which the guardrail checks
+ * link to.
+ */
+export function buildEvaluateGuardrailsHandler(ctx: TurnContext): NodeHandler {
+  return async (input: unknown, kctx) => {
+    if (ctx.guardrails === undefined) {
+      throwAgentTurnFailure({
+        code: 'model-invocation-failed',
+        message: 'evaluate-guardrails invoked before setup completed',
+        cause: null,
+      });
+    }
+    const final = finalIteration(input, 'evaluate-guardrails');
+    const evaluatedAt = new Date().toISOString() as Timestamp;
+    // The response as it would be stored; not persisted yet.
+    const response: ConversationMessage = {
+      sequence: -1,
+      role: 'agent',
+      content: final.message.content ?? '',
+      createdAt: evaluatedAt,
+      actor: ctx.input.agent.id,
+    };
+
+    if (ctx.provenance !== undefined) {
+      ctx.provenance.addNode({
+        id: `model-output:${ctx.usage.steps}`,
+        kind: 'model-output',
+        timestamp: evaluatedAt,
+        modelVersion: `${final.provider.id}/${final.provider.model}`,
+      });
+      ctx.provenance.addEdge({
+        from: `model-output:${ctx.usage.steps}`,
+        to: `model-call:${ctx.usage.steps}`,
+        kind: 'produced',
+      });
+    }
+
+    const finalUsage = {
+      steps: ctx.usage.steps,
+      promptTokens: ctx.usage.promptTokens,
+      completionTokens: ctx.usage.completionTokens,
+      totalCostUsd: ctx.usage.totalCostUsd,
+      durationMs: Date.now() - ctx.startedAt,
+    };
+    const structured =
+      ctx.input.agent.output !== undefined && !kctx.dryRun
+        ? parseJsonAnswer(final.message.content)
+        : undefined;
+    const trace = buildRunTrace({
+      runId: kctx.runId,
+      tenantId: ctx.input.tenantId,
+      projectId: ctx.input.projectId,
+      conversationId: ctx.input.conversationId,
+      turnNumber: (ctx.conversation?.turnCount ?? 0) + 1,
+      agent: ctx.input.agent,
+      userMessage: ctx.input.userMessage,
+      ...(ctx.input.input !== undefined && { stepInput: ctx.input.input }),
+      ...(structured?.kind === 'ok' && { structuredOutput: structured.value }),
+      appended: ctx.appended,
+      finalResponse: response,
+      usage: finalUsage,
+    });
+    const outcomes = await evaluateGate(
+      ctx.guardrails,
+      trace,
+      ctx.bindings,
+      ctx.tenantPolicy,
+      ctx.turnAbort.signal,
+    );
+    const categorized = categorizeOutcomes(outcomes);
+
+    const allViolations = [...categorized.blocking, ...categorized.warnings, ...categorized.other];
+    for (const v of allViolations) {
+      await emitTurnEvent(ctx.bindings.onEvent, {
+        kind: 'guardrail.violated',
+        action: v.action,
+        severity: v.severity,
+        guardrailId: v.guardrailId,
+        ...(v.result.reason !== undefined && { reason: v.result.reason }),
+      });
+      if (ctx.provenance !== undefined) {
+        ctx.provenance.addNode({
+          id: `guardrail-check:${v.guardrailId}`,
+          kind: 'guardrail-check',
+          timestamp: v.at,
+          attributes: {
+            guardrailId: v.guardrailId,
+            action: v.action,
+            severity: v.severity,
+            passed: false,
+            ...(v.result.reason !== undefined && { reason: v.result.reason }),
+          },
+        });
+        ctx.provenance.addEdge({
+          from: `guardrail-check:${v.guardrailId}`,
+          to: `model-output:${ctx.usage.steps}`,
+          kind: 'influenced-by',
+        });
+      }
+    }
+
+    if (categorized.blocking.length > 0) {
+      const message = describeBlockingViolations(categorized.blocking);
+      await emitTurnEvent(ctx.bindings.onEvent, {
+        kind: 'turn.failed',
+        conversationId: ctx.input.conversationId,
+        errorCode: 'guardrail-violation',
+        message,
+      });
+      throwAgentTurnFailure({
+        code: 'guardrail-violation',
+        message,
+        violations: categorized.blocking,
+        evaluationErrors: categorized.errors,
+      });
+    }
+
+    ctx.nonBlockingViolations = [...categorized.warnings, ...categorized.other];
+
+    return {
+      blocking: categorized.blocking.length,
+      warnings: categorized.warnings.length,
+      other: categorized.other.length,
+    };
+  };
+}

package/src/handlers/final-iteration.ts

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { LoopNodeOutput } from '@kindgi/handler';
+
+import type { AgentTurnIterationOutput } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/**
+ * The agent loop's final iteration — the response the turn ends with.
+ * `nodeName` names the reading node in the failure message.
+ */
+export function finalIteration(loopOutput: unknown, nodeName: string): AgentTurnIterationOutput {
+  const output = loopOutput as LoopNodeOutput<AgentTurnIterationOutput> | undefined;
+  if (output === undefined) {
+    throwAgentTurnFailure({
+      code: 'model-invocation-failed',
+      message: `${nodeName} received undefined loop output`,
+      cause: null,
+    });
+  }
+  if (output.finalOutput === undefined) {
+    throwAgentTurnFailure({
+      code: 'model-invocation-failed',
+      message: `${nodeName} received loop output without finalOutput`,
+      cause: null,
+    });
+  }
+  return output.finalOutput;
+}

package/src/handlers/index.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { HandlerRegistry, NodeHandler } from '@kindgi/handler';
+import type { NodeId } from '@kindgi/types';
+
+import {
+  AGENT_LOOP_NODE,
+  BUDGET_CHECK_NODE,
+  BUILD_INITIAL_MESSAGES_NODE,
+  COMPOSE_RESULT_NODE,
+  DISPATCH_TOOLS_NODE,
+  EVALUATE_GUARDRAILS_NODE,
+  MODEL_CALL_NODE,
+  PERSIST_FINAL_MESSAGE_NODE,
+  PERSIST_PROVENANCE_NODE,
+  PERSIST_USER_MESSAGE_NODE,
+  RENDER_PROMPT_NODE,
+  RUN_RETRIEVALS_NODE,
+  SETUP_NODE,
+} from '../agent-turn-flow.js';
+
+import { buildBudgetCheckHandler } from './budget-check.js';
+import { buildBuildInitialMessagesHandler } from './build-initial-messages.js';
+import { buildComposeResultHandler } from './compose-result.js';
+import type { TurnContext } from './context.js';
+import { buildDispatchToolsHandler } from './dispatch-tools.js';
+import { buildEvaluateGuardrailsHandler } from './evaluate-guardrails.js';
+import { buildModelCallHandler } from './model-call.js';
+import { buildPersistFinalMessageHandler } from './persist-final-message.js';
+import { buildPersistProvenanceHandler } from './persist-provenance.js';
+import { buildPersistUserMessageHandler } from './persist-user-message.js';
+import { buildRenderPromptHandler } from './render-prompt.js';
+import { buildRunRetrievalsHandler } from './run-retrievals.js';
+import { buildSetupHandler } from './setup.js';
+
+// `agent-loop` is a kernel loop node — the executor dispatches it
+// internally; only body-node handlers are registered.
+export function buildHandlers(ctx: TurnContext): HandlerRegistry {
+  const entries: [NodeId, NodeHandler][] = [
+    [SETUP_NODE as NodeId, buildSetupHandler(ctx)],
+    [RENDER_PROMPT_NODE as NodeId, buildRenderPromptHandler(ctx)],
+    [PERSIST_USER_MESSAGE_NODE as NodeId, buildPersistUserMessageHandler(ctx)],
+    [RUN_RETRIEVALS_NODE as NodeId, buildRunRetrievalsHandler(ctx)],
+    [BUILD_INITIAL_MESSAGES_NODE as NodeId, buildBuildInitialMessagesHandler(ctx)],
+    [MODEL_CALL_NODE as NodeId, buildModelCallHandler(ctx)],
+    [DISPATCH_TOOLS_NODE as NodeId, buildDispatchToolsHandler(ctx)],
+    [BUDGET_CHECK_NODE as NodeId, buildBudgetCheckHandler(ctx)],
+    [PERSIST_FINAL_MESSAGE_NODE as NodeId, buildPersistFinalMessageHandler(ctx)],
+    [EVALUATE_GUARDRAILS_NODE as NodeId, buildEvaluateGuardrailsHandler(ctx)],
+    [PERSIST_PROVENANCE_NODE as NodeId, buildPersistProvenanceHandler(ctx)],
+    [COMPOSE_RESULT_NODE as NodeId, buildComposeResultHandler(ctx)],
+  ];
+  // Assert `agent-loop` isn't accidentally registered — the runtime's
+  // flow executor rejects handlers for internal-dispatch nodes at load
+  // time. Sanity check for regressions.
+  if (entries.some(([id]) => id === (AGENT_LOOP_NODE as NodeId))) {
+    throw new Error('agent-loop must not have a handler — it is dispatched by the kernel');
+  }
+  return new Map(entries);
+}
+
+export type { TurnContext };

package/src/handlers/model-call.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ModelCallInput, ModelMessage } from '@kindgi/capabilities';
+import type { NodeHandler } from '@kindgi/handler';
+
+import { emitTurnEvent } from '../streaming.js';
+
+import type { AgentTurnIterationOutput, TurnContext } from './context.js';
+import { throwAgentTurnFailure } from './errors.js';
+
+/**
+ * Loop-body node #1. Invoke the model with the current
+ * `nextMessages` accumulator. Emits `model.call.started` +
+ * `model.call.completed`, records provenance for the model-call node,
+ * and accumulates usage on `ctx.usage`.
+ *
+ * Output is a partial `AgentTurnIterationOutput` — `dispatch-tools`
+ * receives it and finishes composing the iteration output.
+ */
+export function buildModelCallHandler(ctx: TurnContext): NodeHandler {
+  return async (input: unknown, kctx) => {
+    if (ctx.provider === undefined || ctx.model === undefined || ctx.tools === undefined) {
+      throwAgentTurnFailure({
+        code: 'model-invocation-failed',
+        message: 'model-call invoked before setup completed',
+        cause: null,
+      });
+    }
+    const shaped = input as { readonly nextMessages?: readonly ModelMessage[] } | undefined;
+    const nextMessages: readonly ModelMessage[] = shaped?.nextMessages ?? [];
+
+    ctx.usage.steps += 1;
+
+    await emitTurnEvent(ctx.bindings.onEvent, {
+      kind: 'model.call.started',
+      step: ctx.usage.steps,
+      providerId: ctx.provider.metadata.id,
+      model: ctx.model.name,
+    });
+
+    let callResult: Awaited<ReturnType<typeof ctx.provider.invoke>>;
+    if (kctx.dryRun) {
+      // Dry-run: skip the network call. Return a schema-conformant
+      // mock indicating the model would have terminated cleanly. The
+      // mock requests no tools, so a dry run does not preview tool
+      // planning.
+      callResult = {
+        finishReason: 'stop',
+        message: { role: 'assistant', content: '[dry-run: model call skipped]' },
+        usage: { promptTokens: 0, completionTokens: 0 },
+        costUsd: 0,
+        durationMs: 0,
+        provider: { id: ctx.provider.metadata.id, model: ctx.model.name },
+      };
+    } else {
+      const callInput: ModelCallInput = {
+        model: ctx.model.name,
+        messages: nextMessages,
+        ...(ctx.tools.definitions.length > 0 && {
+          tools: ctx.tools.definitions,
+        }),
+        abortSignal: ctx.turnAbort.signal,
+      };
+
+      try {
+        callResult = await ctx.provider.invoke(callInput);
+      } catch (cause) {
+        if (ctx.turnAbort.signal.aborted) {
+          throwAgentTurnFailure({
+            code: 'agent-turn-aborted',
+            message: `Agent turn aborted: ${cause instanceof Error ? cause.message : String(cause)}`,
+            reason: ctx.abortReason ?? 'timeout',
+          });
+        }
+        // The provider's own words (a 401's "invalid x-api-key", a 429)
+        // are what the caller needs; they're in `cause` too, but callers
+        // show `message`.
+        throwAgentTurnFailure({
+          code: 'model-invocation-failed',
+          message: `Model call to ${ctx.provider.metadata.id} (${ctx.model.name}) failed: ${describeCause(cause)}`,
+          cause,
+        });
+      }
+    }
+
+    ctx.usage.promptTokens += callResult.usage.promptTokens;
+    ctx.usage.completionTokens += callResult.usage.completionTokens;
+    ctx.usage.totalCostUsd += callResult.costUsd;
+    ctx.lastProvider = callResult.provider;
+
+    await emitTurnEvent(ctx.bindings.onEvent, {
+      kind: 'model.call.completed',
+      step: ctx.usage.steps,
+      finishReason: callResult.finishReason,
+      promptTokens: callResult.usage.promptTokens,
+      completionTokens: callResult.usage.completionTokens,
+      costUsd: callResult.costUsd,
+      durationMs: callResult.durationMs,
+    });
+
+    if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
+      const modelCallNodeId = `model-call:${ctx.usage.steps}`;
+      ctx.provenance.addNode({
+        id: modelCallNodeId,
+        kind: 'model-call',
+        timestamp: new Date().toISOString() as never,
+        modelVersion: `${callResult.provider.id}/${callResult.provider.model}`,
+        attributes: {
+          step: ctx.usage.steps,
+          promptTokens: callResult.usage.promptTokens,
+          completionTokens: callResult.usage.completionTokens,
+          costUsd: callResult.costUsd,
+          finishReason: callResult.finishReason,
+        },
+      });
+      ctx.provenance.addEdge({
+        from: modelCallNodeId,
+        to: `input:${ctx.userMessage.sequence}`,
+        kind: 'caused-by',
+      });
+    }
+
+    // Partial iteration output — `dispatch-tools` finishes it.
+    const partial: Omit<AgentTurnIterationOutput, 'iterationAppended' | 'finishedTurn'> & {
+      readonly step: number;
+    } = {
+      step: ctx.usage.steps,
+      finishReason: callResult.finishReason,
+      message: callResult.message,
+      iterationUsage: {
+        promptTokens: callResult.usage.promptTokens,
+        completionTokens: callResult.usage.completionTokens,
+        costUsd: callResult.costUsd,
+      },
+      provider: callResult.provider,
+      nextMessages,
+    };
+    return partial;
+  };
+}
+
+/** Longest cause text a failure message carries. */
+const MAX_CAUSE_CHARS = 500;
+
+/** A thrown value's message on one line, at most `MAX_CAUSE_CHARS` long. */
+function describeCause(cause: unknown): string {
+  const text = (cause instanceof Error ? cause.message : String(cause)).replace(/\s+/g, ' ').trim();
+  if (text.length === 0) return cause instanceof Error ? cause.name : 'no detail';
+  return text.length > MAX_CAUSE_CHARS ? `${text.slice(0, MAX_CAUSE_CHARS - 1)}…` : text;
+}