@agent-ledger/sdk-ts 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,31 @@
 # @agent-ledger/sdk-ts
 
-Official TypeScript client for Agent Ledger. The SDK instruments your agents so you can stream sessions, log LLM/tool activity, and enforce budget guardrails against the Agent Ledger API.
+Official TypeScript client for Agent Ledger. Use it to instrument any Node.js/Edge agent with structured telemetry, stream session events, and receive immediate feedback when budget guardrails block spending.
+
+Portal: https://agent-ledger.thabo.xyz/
+
+## Table of contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Runtime requirements](#runtime-requirements)
+4. [Getting started](#getting-started)
+5. [Session lifecycle](#session-lifecycle)
+6. [Event reference](#event-reference)
+7. [API reference](#api-reference)
+8. [Error handling](#error-handling)
+9. [Configuration & environments](#configuration--environments)
+10. [Recipes](#recipes)
+11. [Testing & local dev](#testing--local-dev)
+12. [License](#license)
+
+## Features
+
+- Minimal, dependency-free client that speaks directly to the Agent Ledger REST API (`/v1/sessions` and `/v1/events`).
+- First-class TypeScript typings for every event structure (`LlmCallEvent`, `ToolCallEvent`, `ToolResultEvent`).
+- Built-in budget guardrail awareness through `BudgetGuardrailError` so you can halt expensive runs immediately.
+- Works anywhere `fetch` is available (Node.js 18+, Bun, Deno, Edge runtimes, or browsers talking to your own proxy).
+- Simple abstractions so you can reuse the same instrumentation across CLI scripts, background workers, or serverless functions.
 
 ## Installation
 
@@ -8,77 +33,202 @@ Official TypeScript client for Agent Ledger. The SDK instruments your agents so
 pnpm add @agent-ledger/sdk-ts
 # or
 npm install @agent-ledger/sdk-ts
+# or
+yarn add @agent-ledger/sdk-ts
 ```
 
-## Quick start
+## Runtime requirements
+
+- Node.js 18 or newer (for the built-in `fetch` implementation). If you run older Node versions, polyfill `fetch` before importing the SDK.
+- An Agent Ledger API key generated from the dashboard (Settings → API Keys).
+- Outbound HTTPS access to `https://agent-ledger-api.azurewebsites.net` (or your self-hosted instance).
+
+## Getting started
 
 ```ts
-import { AgentLedgerClient } from "@agent-ledger/sdk-ts";
+import {
+  AgentLedgerClient,
+  BudgetGuardrailError,
+  withSession,
+  instrumentTool,
+} from "@agent-ledger/sdk-ts";
 
 const ledger = new AgentLedgerClient({
   apiKey: process.env.AGENT_LEDGER_API_KEY!,
-  // baseUrl is optional. Defaults to the production Agent Ledger API.
 });
 
-async function runAgent() {
-  const sessionId = await ledger.startSession("support-bot");
-  try {
-    await ledger.logLLMCall(sessionId, {
-      stepIndex: 0,
-      model: "gpt-4o",
-      provider: "openai",
-      prompt: "Draft a welcome email",
-      response: "Hello ...",
-      tokensIn: 120,
-      tokensOut: 98,
-      latencyMs: 2300,
-    });
+export async function runSupportAgent(prompt: string) {
+  return withSession(ledger, "support-bot", async ({ sessionId, steps }) => {
+    try {
+      // 1. Run your own LLM logic
+      const response = await callModel(prompt);
+
+      // 2. Log the LLM call (Agent Ledger auto-computes spend from provider/model/tokens)
+      await ledger.logLLMCall(sessionId, {
+        stepIndex: steps.next(),
+        provider: "openai",
+        model: "gpt-4o-mini",
+        prompt,
+        response: response.text,
+        tokensIn: response.usage.inputTokens,
+        tokensOut: response.usage.outputTokens,
+        latencyMs: response.latencyMs,
+      });
+
+      // 3. Example tool wrapper (automatically logs tool_call + tool_result)
+      await instrumentTool({
+        ledger,
+        sessionId,
+        stepIndex: steps.next(),
+        toolName: "weather",
+        toolInput: { city: "Boston" },
+        run: async () => fetchWeather("Boston"),
+      });
+
+      return response.text;
+    } catch (err) {
+      if (err instanceof BudgetGuardrailError) {
+        console.warn("Budget exceeded", err.details);
+      }
+      throw err;
+    }
+  });
+}
+```
+
+## Session lifecycle
+
+1. **Start sessions** early with `startSession(agentName)` to capture every downstream event.
+2. **Log events** whenever you call an LLM or tool:
+   - `logLLMCall` for prompts/responses.
+   - `logToolCall` for tool invocations (store the inputs).
+   - `logToolResult` for tool responses (store outputs/latency).
+   - `logEvents` if you need to batch arbitrary event objects.
+3. **End sessions** with `endSession(sessionId, "success" | "error", { errorMessage? })` so the dashboard knows whether the run finished cleanly.
+
+Tip: keep a simple helper that wraps this flow so every agent in your repo emits consistent telemetry.
+
+## Event reference
+
+| Event | Required fields | Optional fields | Notes |
+| --- | --- | --- | --- |
+| `LlmCallEvent` | `stepIndex`, `model`, `provider`, `prompt`, `response`, `tokensIn`, `tokensOut`, `latencyMs` | — | `logLLMCall` automatically sets `type` to `llm_call` and lets the backend price the call based on provider/model. |
+| `ToolCallEvent` | `stepIndex`, `toolName`, `toolInput` | — | Capture the structured input you sent to an internal or external tool. |
+| `ToolResultEvent` | `stepIndex`, `toolName`, `toolOutput`, `latencyMs` | — | Use together with `ToolCallEvent` to understand tool latency and result size. |
+| Custom | Whatever your workflow needs plus `type` | — | Supply via `logEvents` if you want to store derived signals (examples: `session_start`, `session_end`, `guardrail_trigger`). |
+
+Conventions:
+
+- `stepIndex` is a zero-based counter that makes it easy to diff runs. Increment it in the order events happen, even if multiple tools share the same LLM output.
+- Keep prompts/responses under 64 KB per event so they render nicely in the dashboard diff view.
+- All numeric values are stored as numbers (no strings) so the API can aggregate cost statistics.
+
+## API reference
+
+### `new AgentLedgerClient(options)`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `apiKey` | `string` (required) | Workspace API key from the dashboard. |
+
+### `startSession(agentName: string): Promise<string>`
+
+Creates a session row and returns its UUID. `agentName` should match how you identify the workflow in the dashboard (e.g., `support-bot`, `retrieval-worker`).
 
-    // ...additional tool calls/events...
+### `endSession(sessionId, status, opts?)`
 
-    await ledger.endSession(sessionId, "success");
-  } catch (err) {
-    await ledger.endSession(sessionId, "error", { errorMessage: (err as Error).message });
-    throw err;
+Marks the session closed. Pass `{ errorMessage }` for failures so the UI shows context next to the run.
+
+### `logEvents(sessionId, events)`
+
+Lowest-level ingestion helper. Accepts an array of plain objects, so you can batch multiple events into a single network call. Events must include a `type` string (e.g., `llm_call`).
+
+### `logLLMCall(sessionId, event)` / `logToolCall` / `logToolResult`
+
+Typed helpers that:
+
+- Fill the `type` automatically.
+- Validate required fields at compile time.
+- Call `logEvents` under the hood.
+
+### Types exported
+
+`AgentLedgerClient`, `AgentLedgerClientOptions`, `BudgetGuardrailError`, `BudgetGuardrailDetails`, `LlmCallEvent`, `ToolCallEvent`, `ToolResultEvent`, `AnyEvent`, `EventType`.
+
+## Error handling
+
+- **`BudgetGuardrailError`** (HTTP 429): thrown when the backend refuses the event because the agent exceeded its daily limit. Inspect `error.details`:
+
+  ```ts
+  {
+    agentName: string;
+    dailyLimitUsd: number;
+    spentTodayUsd: number;
+    attemptedCostUsd: number;
+    projectedCostUsd: number;
+    remainingBudgetUsd: number;
   }
-}
-```
+  ```
 
-## API surface
+- **Generic `Error`**: wraps any other non-2xx response (`startSession`, `endSession`, `logEvents`). The `.message` contains the server-provided text when available.
 
-- `new AgentLedgerClient({ apiKey, baseUrl? })`
-- `startSession(agentName)` → session ID
-- `endSession(sessionId, status, { errorMessage? })`
-- `logEvents(sessionId, events)` (low-level entry point)
-- `logLLMCall`, `logToolCall`, `logToolResult` (typed helpers)
+Recommended practice: catch errors where you call `logEvents` so your business logic can continue (or at least emit a structured failure) even when the telemetry call is rejected.
 
-All helpers eventually POST to the Agent Ledger REST API using the API key supplied in the constructor.
+## Configuration & environments
 
-### Budget guardrail errors
+- Provide `AGENT_LEDGER_API_KEY` (or load it from your preferred secrets manager) and the SDK connects to the hosted API automatically.
+- Default endpoint → `https://agent-ledger-api.azurewebsites.net`.
+- For local API experiments, keep the SDK untouched and proxy traffic through your own tooling (MSW, mock servers, etc.).
 
-If Agent Ledger blocks an event because of a per-agent budget limit, the SDK throws `BudgetGuardrailError`. Catch it to inspect the `details` payload and react accordingly:
+Because the client is stateless, you can instantiate one per agent type or share a singleton across the entire app.
+
+## Recipes
+
+### Streaming agents / multi-step workflows
+
+Reuse a monotonically increasing `stepIndex` while you stream partial responses. You can emit interim tool calls before the final LLM response lands to visualize branching logic.
+
+### Custom tool instrumentation
 
 ```ts
-import { BudgetGuardrailError } from "@agent-ledger/sdk-ts";
+async function callWeather(sessionId: string, city: string, stepIndex: number) {
+  await ledger.logToolCall(sessionId, {
+    stepIndex,
+    toolName: "weather",
+    toolInput: { city },
+  });
+
+  const result = await fetchWeather(city);
+
+  await ledger.logToolResult(sessionId, {
+    stepIndex,
+    toolName: "weather",
+    toolOutput: result,
+    latencyMs: result.latencyMs,
+  });
+}
+```
 
+### Handling guardrail blocks
+
+```ts
 try {
-  await ledger.logEvents(sessionId, events);
+  await ledger.logLLMCall(sessionId, event);
 } catch (err) {
   if (err instanceof BudgetGuardrailError) {
-    console.warn("Budget exceeded", err.details);
+    await ledger.endSession(sessionId, "error", {
+      errorMessage: `Budget exceeded: remaining ${err.details.remainingBudgetUsd}`,
+    });
+    return;
   }
+  throw err;
 }
 ```
 
-### Environment overrides
-
-- `baseUrl` option overrides the API host per client.
-- When omitted, the SDK looks for `process.env.AGENT_LEDGER_BASE_URL` and falls back to `https://agent-ledger-api.azurewebsites.net`.
-- For local testing, set `AGENT_LEDGER_BASE_URL=http://localhost:3000` (or your tunnel URL) before instantiating the client.
-
-## TypeScript support
+## Testing & local dev
 
-This package ships its own `.d.ts` files (generated from `src/index.ts`). No additional typings are required.
+- The SDK performs real HTTP requests. For unit tests, stub `global.fetch` or intercept calls with tools like [MSW](https://mswjs.io/).
+- When running the Agent Ledger API locally, ensure your test key exists in the development database and export it via `AGENT_LEDGER_API_KEY`.
 
 ## License
 

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export type EventType = "llm_call" | "tool_call" | "tool_result" | "session_star
 export interface AgentLedgerClientOptions {
     apiKey: string;
     baseUrl?: string;
+    fetch?: typeof fetch;
+    defaultHeaders?: Record<string, string>;
 }
 export type BudgetGuardrailDetails = {
     agentName: string;
@@ -18,12 +20,14 @@ export declare class BudgetGuardrailError extends Error {
 export declare class AgentLedgerClient {
     private apiKey;
     private baseUrl;
+    private fetchImpl;
+    private defaultHeaders;
     constructor(opts: AgentLedgerClientOptions);
     startSession(agentName: string): Promise<string>;
     endSession(sessionId: string, status: "success" | "error", opts?: {
         errorMessage?: string;
     }): Promise<void>;
-    logEvents(sessionId: string, events: any[]): Promise<void>;
+    logEvents(sessionId: string, events: AnyEvent[] | Array<Record<string, any>>): Promise<void>;
     logLLMCall(sessionId: string, e: Omit<LlmCallEvent, "type">): Promise<void>;
     logToolCall(sessionId: string, e: Omit<ToolCallEvent, "type">): Promise<void>;
     logToolResult(sessionId: string, e: Omit<ToolResultEvent, "type">): Promise<void>;
@@ -53,3 +57,22 @@ export type ToolResultEvent = {
     latencyMs: number;
 };
 export type AnyEvent = LlmCallEvent | ToolCallEvent | ToolResultEvent;
+export type StepCounter = {
+    next: () => number;
+    peek: () => number;
+    reset: (value?: number) => void;
+};
+export declare function createStepCounter(startAt?: number): StepCounter;
+export declare function withSession<T>(ledger: AgentLedgerClient, agentName: string, fn: (ctx: {
+    sessionId: string;
+    steps: StepCounter;
+}) => Promise<T>): Promise<T>;
+export declare function instrumentTool<TInput, TOutput>(opts: {
+    ledger: AgentLedgerClient;
+    sessionId: string;
+    stepIndex: number;
+    toolName: string;
+    toolInput: TInput;
+    run: () => Promise<TOutput> | TOutput;
+    captureLatencyMs?: boolean;
+}): Promise<TOutput>;

package/dist/index.js

@@ -18,16 +18,23 @@ export class BudgetGuardrailError extends Error {
 }
 export class AgentLedgerClient {
     constructor(opts) {
-        this.apiKey = opts.apiKey;
+        const key = (opts.apiKey ?? "").trim();
+        if (!key) {
+            throw new Error("AgentLedgerClient: apiKey is required");
+        }
+        this.apiKey = key;
         const resolvedBaseUrl = resolveBaseUrl(opts.baseUrl).trim();
         this.baseUrl = resolvedBaseUrl.replace(/\/$/, "");
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.defaultHeaders = { ...(opts.defaultHeaders ?? {}) };
     }
     async startSession(agentName) {
-        const res = await fetch(`${this.baseUrl}/v1/sessions`, {
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "x-api-key": this.apiKey
+                "x-api-key": this.apiKey,
+                ...this.defaultHeaders,
             },
             body: JSON.stringify({ agentName })
         });
@@ -39,11 +46,12 @@ export class AgentLedgerClient {
         return data.id;
     }
     async endSession(sessionId, status, opts) {
-        const res = await fetch(`${this.baseUrl}/v1/sessions/${sessionId}/end`, {
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions/${sessionId}/end`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "x-api-key": this.apiKey
+                "x-api-key": this.apiKey,
+                ...this.defaultHeaders,
             },
             body: JSON.stringify({ status, errorMessage: opts?.errorMessage ?? null })
         });
@@ -53,11 +61,12 @@ export class AgentLedgerClient {
         }
     }
     async logEvents(sessionId, events) {
-        const res = await fetch(`${this.baseUrl}/v1/events`, {
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/events`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
-                "x-api-key": this.apiKey
+                "x-api-key": this.apiKey,
+                ...this.defaultHeaders,
             },
             body: JSON.stringify({ sessionId, events })
         });
@@ -90,4 +99,70 @@ export class AgentLedgerClient {
         return this.logEvents(sessionId, [event]);
     }
 }
+export function createStepCounter(startAt = 0) {
+    let value = startAt;
+    return {
+        next: () => value++,
+        peek: () => value,
+        reset: (v = 0) => {
+            value = v;
+        },
+    };
+}
+export async function withSession(ledger, agentName, fn) {
+    const sessionId = await ledger.startSession(agentName);
+    const steps = createStepCounter(0);
+    try {
+        const result = await fn({ sessionId, steps });
+        await ledger.endSession(sessionId, "success");
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            await ledger.endSession(sessionId, "error", { errorMessage: message });
+        }
+        catch {
+            // ignore telemetry failures on shutdown
+        }
+        throw err;
+    }
+}
+export async function instrumentTool(opts) {
+    await opts.ledger.logToolCall(opts.sessionId, {
+        stepIndex: opts.stepIndex,
+        toolName: opts.toolName,
+        toolInput: opts.toolInput,
+    });
+    const started = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+    try {
+        const output = await opts.run();
+        const ended = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const latencyMs = Math.max(0, Math.round(ended - started));
+        await opts.ledger.logToolResult(opts.sessionId, {
+            stepIndex: opts.stepIndex,
+            toolName: opts.toolName,
+            toolOutput: output,
+            latencyMs: opts.captureLatencyMs === false ? 0 : latencyMs,
+        });
+        return output;
+    }
+    catch (err) {
+        const ended = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+        const latencyMs = Math.max(0, Math.round(ended - started));
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            await opts.ledger.logToolResult(opts.sessionId, {
+                stepIndex: opts.stepIndex,
+                toolName: opts.toolName,
+                toolOutput: { error: message },
+                latencyMs: opts.captureLatencyMs === false ? 0 : latencyMs,
+            });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-ledger/sdk-ts",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -8,6 +8,8 @@ export type EventType =
 export interface AgentLedgerClientOptions {
   apiKey: string;
   baseUrl?: string;
+  fetch?: typeof fetch;
+  defaultHeaders?: Record<string, string>;
 }
 
 const PROD_BASE_URL = "https://agent-ledger-api.azurewebsites.net";
@@ -45,19 +47,29 @@ export class BudgetGuardrailError extends Error {
 export class AgentLedgerClient {
   private apiKey: string;
   private baseUrl: string;
+  private fetchImpl: typeof fetch;
+  private defaultHeaders: Record<string, string>;
 
   constructor(opts: AgentLedgerClientOptions) {
-    this.apiKey = opts.apiKey;
+    const key = (opts.apiKey ?? "").trim();
+    if (!key) {
+      throw new Error("AgentLedgerClient: apiKey is required");
+    }
+    this.apiKey = key;
     const resolvedBaseUrl = resolveBaseUrl(opts.baseUrl).trim();
     this.baseUrl = resolvedBaseUrl.replace(/\/$/, "");
+
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.defaultHeaders = { ...(opts.defaultHeaders ?? {}) };
   }
 
   async startSession(agentName: string): Promise<string> {
-    const res = await fetch(`${this.baseUrl}/v1/sessions`, {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "x-api-key": this.apiKey
+        "x-api-key": this.apiKey,
+        ...this.defaultHeaders,
       },
       body: JSON.stringify({ agentName })
     });
@@ -76,11 +88,12 @@ export class AgentLedgerClient {
     status: "success" | "error",
     opts?: { errorMessage?: string }
   ) {
-    const res = await fetch(`${this.baseUrl}/v1/sessions/${sessionId}/end`, {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/sessions/${sessionId}/end`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "x-api-key": this.apiKey
+        "x-api-key": this.apiKey,
+        ...this.defaultHeaders,
       },
       body: JSON.stringify({ status, errorMessage: opts?.errorMessage ?? null })
     });
@@ -91,12 +104,13 @@ export class AgentLedgerClient {
     }
   }
 
-  async logEvents(sessionId: string, events: any[]) {
-    const res = await fetch(`${this.baseUrl}/v1/events`, {
+  async logEvents(sessionId: string, events: AnyEvent[] | Array<Record<string, any>>) {
+    const res = await this.fetchImpl(`${this.baseUrl}/v1/events`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "x-api-key": this.apiKey
+        "x-api-key": this.apiKey,
+        ...this.defaultHeaders,
       },
       body: JSON.stringify({ sessionId, events })
     });
@@ -171,4 +185,90 @@ export type ToolResultEvent = {
   latencyMs: number;
 };
 
-export type AnyEvent = LlmCallEvent | ToolCallEvent | ToolResultEvent;
+export type AnyEvent = LlmCallEvent | ToolCallEvent | ToolResultEvent;
+
+export type StepCounter = {
+  next: () => number;
+  peek: () => number;
+  reset: (value?: number) => void;
+};
+
+export function createStepCounter(startAt = 0): StepCounter {
+  let value = startAt;
+  return {
+    next: () => value++,
+    peek: () => value,
+    reset: (v = 0) => {
+      value = v;
+    },
+  };
+}
+
+export async function withSession<T>(
+  ledger: AgentLedgerClient,
+  agentName: string,
+  fn: (ctx: { sessionId: string; steps: StepCounter }) => Promise<T>
+): Promise<T> {
+  const sessionId = await ledger.startSession(agentName);
+  const steps = createStepCounter(0);
+  try {
+    const result = await fn({ sessionId, steps });
+    await ledger.endSession(sessionId, "success");
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+      await ledger.endSession(sessionId, "error", { errorMessage: message });
+    } catch {
+      // ignore telemetry failures on shutdown
+    }
+    throw err;
+  }
+}
+
+export async function instrumentTool<TInput, TOutput>(opts: {
+  ledger: AgentLedgerClient;
+  sessionId: string;
+  stepIndex: number;
+  toolName: string;
+  toolInput: TInput;
+  run: () => Promise<TOutput> | TOutput;
+  captureLatencyMs?: boolean;
+}): Promise<TOutput> {
+  await opts.ledger.logToolCall(opts.sessionId, {
+    stepIndex: opts.stepIndex,
+    toolName: opts.toolName,
+    toolInput: opts.toolInput,
+  });
+
+  const started = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+  try {
+    const output = await opts.run();
+    const ended = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+    const latencyMs = Math.max(0, Math.round(ended - started));
+
+    await opts.ledger.logToolResult(opts.sessionId, {
+      stepIndex: opts.stepIndex,
+      toolName: opts.toolName,
+      toolOutput: output,
+      latencyMs: opts.captureLatencyMs === false ? 0 : latencyMs,
+    });
+
+    return output;
+  } catch (err) {
+    const ended = typeof performance !== "undefined" && performance.now ? performance.now() : Date.now();
+    const latencyMs = Math.max(0, Math.round(ended - started));
+    const message = err instanceof Error ? err.message : String(err);
+    try {
+      await opts.ledger.logToolResult(opts.sessionId, {
+        stepIndex: opts.stepIndex,
+        toolName: opts.toolName,
+        toolOutput: { error: message },
+        latencyMs: opts.captureLatencyMs === false ? 0 : latencyMs,
+      });
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+}