@vercel/agent-runs 0.0.0-stage → 0.0.0

package/src/adapters/otel-error.ts

@@ -0,0 +1,34 @@
+import { SpanStatusCode, type Span } from "@opentelemetry/api";
+import { boundedTraceError } from "./serialization.js";
+import { truncateTelemetryText } from "./serialization.js";
+import { contentAttribute, textContentAttribute } from "./serialization.js";
+
+/** Call with policy-projected errors; undefined retains failure status without content. */
+export function recordAgentSpanError(span: Span, error: unknown, errorType?: string): void {
+  span.setAttribute(
+    "error.type",
+    truncateTelemetryText(errorType ?? (error instanceof Error ? error.name : "_OTHER"), 128),
+  );
+  // A thrown Error keeps its own name; a wrapped value takes the error type.
+  const wrapped = error !== undefined && !(error instanceof Error);
+  if (wrapped) {
+    const serialized = contentAttribute(error);
+    const message =
+      typeof error === "object" && error !== null ? Reflect.get(error, "message") : undefined;
+    const detail =
+      typeof error === "string"
+        ? textContentAttribute(error)
+        : typeof message === "string"
+          ? textContentAttribute(serialized === undefined ? message : `${message}\n${serialized}`)
+          : serialized;
+    if (detail !== undefined) error = new Error(detail);
+  }
+  if (error instanceof Error) {
+    const bounded = boundedTraceError(error);
+    if (wrapped && errorType !== undefined) bounded.name = truncateTelemetryText(errorType, 128);
+    span.recordException(bounded);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: bounded.message });
+  } else {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+  }
+}

package/src/adapters/otel-ids.ts

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+
+/**
+ * ID generator installed by the host OTel provider for reserved-ID emission. A span
+ * whose lifetime crosses durable worker boundaries (`invoke_agent`) is emitted
+ * at its terminal; priming the next span id lets that span carry the
+ * pre-allocated id its descendants already parented to.
+ */
+export class AgentSpanIdGenerator {
+  #primedSpanId: string | undefined;
+  #primedTraceId: string | undefined;
+
+  /** Reserves a span id for a span emitted later via {@link withSpanId}. */
+  allocateSpanId(): string {
+    return randomHexId(16);
+  }
+
+  /** Derives one span id for a replay-stable instrumentation event. */
+  deriveSpanId(key: string): string {
+    return deriveAgentSpanId(key);
+  }
+
+  deriveTraceId(key: string): string {
+    const traceId = createHash("sha256").update(key).digest("hex").slice(0, 32);
+    return /^0+$/u.test(traceId) ? "00000000000000000000000000000001" : traceId;
+  }
+
+  generateSpanId(): string {
+    const primed = this.#primedSpanId;
+    if (primed !== undefined) {
+      this.#primedSpanId = undefined;
+      return primed;
+    }
+    return randomHexId(16);
+  }
+
+  generateTraceId(): string {
+    const primed = this.#primedTraceId;
+    if (primed !== undefined) {
+      this.#primedTraceId = undefined;
+      return primed;
+    }
+    return randomHexId(32);
+  }
+
+  /** Runs `startSpan` so the next span started carries `spanId`. */
+  withSpanId<T>(spanId: string, startSpan: () => T): T {
+    this.#primedSpanId = spanId;
+    try {
+      return startSpan();
+    } finally {
+      this.#primedSpanId = undefined;
+    }
+  }
+
+  withTraceId<T>(traceId: string, startSpan: () => T): T {
+    this.#primedTraceId = traceId;
+    try {
+      return startSpan();
+    } finally {
+      this.#primedTraceId = undefined;
+    }
+  }
+}
+
+function deriveAgentSpanId(key: string): string {
+  const spanId = createHash("sha256").update(key).digest("hex").slice(0, 16);
+  return /^0+$/u.test(spanId) ? "0000000000000001" : spanId;
+}
+
+const HEX_DIGITS = "0123456789abcdef";
+
+function randomHexId(length: number): string {
+  let id: string;
+  do {
+    id = "";
+    for (let index = 0; index < length; index += 1) {
+      id += HEX_DIGITS[Math.trunc(Math.random() * 16)];
+    }
+  } while (!/[1-9a-f]/u.test(id));
+  return id;
+}

package/src/adapters/otel.ts

@@ -0,0 +1,232 @@
+import {
+  ROOT_CONTEXT,
+  SpanKind,
+  SpanStatusCode,
+  context,
+  trace,
+  createTraceState,
+  createContextKey,
+  type SpanContext,
+  type Context as OtelContext,
+  type TracerProvider,
+} from "@opentelemetry/api";
+import { recordAgentSpanError } from "./otel-error.js";
+import { AgentSpanIdGenerator } from "./otel-ids.js";
+import type {
+  Attributes,
+  AgentTelemetry,
+  OutputMapping,
+  PreparedSpan,
+  SpanWriter,
+  TraceReference,
+  ExecutionContext,
+  ActiveOperation,
+} from "../core/types.js";
+import { activeOperation, intersectCapture } from "../core/activation.js";
+import { withCapture } from "../capture.js";
+
+type Context = OtelContext;
+const ACTIVE_OPERATION = createContextKey("agent.tracing.active-operation");
+const SUPPRESS_TRACING_KEY = createContextKey("OpenTelemetry SDK Context Key SUPPRESS_TRACING");
+
+export function withErrorContent<T extends { setValue(key: symbol, value: unknown): T }>(
+  context: T,
+  allowed: boolean,
+): T {
+  return withCapture(context, { emit: true, recordInputs: allowed, recordOutputs: allowed });
+}
+
+function suppressTracing(context: Context): Context {
+  return context.setValue(SUPPRESS_TRACING_KEY, true);
+}
+
+export function activeTraceOperation(
+  host: Pick<Context, "getValue"> = context.active(),
+): ActiveOperation | undefined {
+  return typeof host.getValue === "function"
+    ? (host.getValue(ACTIVE_OPERATION) as ActiveOperation | undefined)
+    : undefined;
+}
+
+function parentContext(reference: TraceReference | undefined, host?: ExecutionContext): Context {
+  const base = (host as Context | undefined) ?? ROOT_CONTEXT;
+  return reference === undefined
+    ? base
+    : trace.setSpan(base, trace.wrapSpanContext(otelReference(reference)));
+}
+
+function otelReference(reference: TraceReference): SpanContext {
+  return {
+    ...reference,
+    traceState:
+      reference.tracestate === undefined ? undefined : createTraceState(reference.tracestate),
+  };
+}
+
+function portableReference(reference: SpanContext): TraceReference {
+  return {
+    traceId: reference.traceId,
+    spanId: reference.spanId,
+    traceFlags: reference.traceFlags,
+    isRemote: reference.isRemote,
+    tracestate: reference.traceState?.serialize(),
+  };
+}
+
+function mappedAttributes(
+  mapping: OutputMapping | undefined,
+  span: PreparedSpan,
+  attributes: Attributes,
+): Attributes {
+  return mapping?.attributes(span, attributes) ?? attributes;
+}
+
+/**
+ * Applied when the host passes no mapping. On Vercel it adds the session ID
+ * Agent Runs uses to find a run's spans.
+ */
+const DEFAULT_MAPPING: OutputMapping = {
+  attributes(_span, attributes) {
+    const runId = attributes["agent.run.id"];
+    return onVercel() && typeof runId === "string" && attributes["vercel.session_id"] === undefined
+      ? { ...attributes, "vercel.session_id": runId }
+      : attributes;
+  },
+  link: (_span, link) => ({ "agent.link.type": link.relationship }),
+};
+
+function onVercel(): boolean {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process
+    ?.env;
+  return env?.VERCEL_ENV !== undefined;
+}
+
+export interface OtelTelemetryOptions {
+  /** Defaults to the global tracer provider. */
+  readonly provider?: TracerProvider;
+  /**
+   * Generator installed on `provider`. Required for durable tracing so a span
+   * started in a later process carries the ID its children already reference.
+   */
+  readonly idGenerator?: AgentSpanIdGenerator;
+  /** Defaults to recording every trace. */
+  readonly samplesTrace?: (
+    traceId: string,
+    operation: { name: string; attributes: Attributes },
+  ) => boolean;
+  /** Replaces the default mapping, which adds `vercel.session_id` on Vercel. */
+  readonly mapping?: OutputMapping;
+  readonly tracerName?: string;
+  /** Recorded as the spans' instrumentation scope version. */
+  readonly tracerVersion?: string;
+  /** Override the provider's lifecycle, for example to flush metric readers too. */
+  readonly forceFlush?: () => Promise<void>;
+  readonly shutdown?: () => Promise<void>;
+}
+
+/** OpenTelemetry implementation of {@link AgentTelemetry}. */
+export function otelTelemetry(options: OtelTelemetryOptions = {}): AgentTelemetry {
+  const provider = options.provider ?? trace.getTracerProvider();
+  const tracer = provider.getTracer(options.tracerName ?? "agent.tracing", options.tracerVersion);
+  const mapping = options.mapping ?? DEFAULT_MAPPING;
+  const idGenerator = options.idGenerator;
+  function lifecycle(method: "forceFlush" | "shutdown"): () => Promise<void> {
+    return (
+      options[method] ??
+      (async () => {
+        const callback = (
+          provider as TracerProvider & { forceFlush?(): Promise<void>; shutdown?(): Promise<void> }
+        )[method];
+        if (callback === undefined)
+          throw new Error(`The tracer provider does not support ${method}.`);
+        await callback.call(provider);
+      })
+    );
+  }
+  function start(span: PreparedSpan, executionContext?: ExecutionContext): SpanWriter {
+    const recorded = tracer.startSpan(
+      span.name,
+      {
+        attributes: mappedAttributes(mapping, span, span.attributes),
+        kind: span.kind === undefined ? undefined : SpanKind[span.kind],
+        root: span.root,
+        startTime: span.startTimeMs,
+        links: span.links?.map((link) => ({
+          context: otelReference(link.context),
+          attributes: mapping?.link(span, link) ?? { "agent.link.type": link.relationship },
+        })),
+      },
+      parentContext(span.root ? undefined : span.parent, executionContext),
+    );
+    return {
+      reference: portableReference(recorded.spanContext()),
+      setAttribute(key, value) {
+        for (const [name, mapped] of Object.entries(
+          mappedAttributes(mapping, span, { [key]: value }),
+        )) {
+          if (mapped !== undefined) recorded.setAttribute(name, mapped);
+        }
+      },
+      addEvent: (name, attributes, timeMs) => {
+        recorded.addEvent(name, attributes, timeMs);
+      },
+      fail: (error, errorType) => recordAgentSpanError(recorded, error, errorType),
+      setStatus: (code) => {
+        recorded.setStatus({ code: SpanStatusCode[code] });
+      },
+      end: (timeMs) => {
+        recorded.end(timeMs);
+      },
+    };
+  }
+  return {
+    startSpan(span, { reference, context: host } = {}) {
+      if (reference === undefined || idGenerator === undefined) return start(span, host);
+      const writer = idGenerator.withTraceId(reference.traceId, () =>
+        idGenerator.withSpanId(reference.spanId, () => start(span, host)),
+      );
+      if (
+        writer.reference.spanId !== reference.spanId ||
+        writer.reference.traceId !== reference.traceId
+      ) {
+        throw new Error("The tracer provider must use the telemetry's ID generator.");
+      }
+      return writer;
+    },
+    active: () => activeTraceOperation(),
+    suppressed<T>(execute: () => T): T {
+      return context.with(withErrorContent(suppressTracing(ROOT_CONTEXT), false), execute);
+    },
+    run(operation, execute, executionContext) {
+      let capture = intersectCapture(operation.capture, activeTraceOperation()?.capture);
+      // Retain baggage and host context while replacing the semantic parent span.
+      let active = trace.setSpan(
+        (executionContext as Context | undefined) ?? context.active(),
+        trace.wrapSpanContext(otelReference(operation.reference)),
+      );
+      capture = intersectCapture(
+        capture,
+        (active.getValue(ACTIVE_OPERATION) as ActiveOperation | undefined)?.capture,
+      );
+      active = active.setValue(ACTIVE_OPERATION, activeOperation(operation, capture));
+      active = withCapture(active, capture);
+      if (!capture.emit || (operation.reference.traceFlags & 1) === 0)
+        active = suppressTracing(active);
+      return context.with(active, execute);
+    },
+    samples: (traceId, span) =>
+      options.samplesTrace?.(traceId, {
+        name: span.name,
+        attributes: mappedAttributes(mapping, span, span.attributes),
+      }) ?? true,
+    ids:
+      idGenerator === undefined
+        ? undefined
+        : {
+            traceId: (key) => idGenerator.deriveTraceId(key),
+            spanId: (key) => idGenerator.deriveSpanId(key),
+          },
+    forceFlush: lifecycle("forceFlush"),
+    shutdown: lifecycle("shutdown"),
+  };
+}

package/src/adapters/serialization.ts

@@ -0,0 +1,338 @@
+/**
+ * Serializes model and tool payloads into span content attributes for the
+ * local trace viewer: prompt messages, the system prompt, responses, and
+ * tool arguments/results. Everything is capped so a giant payload cannot
+ * bloat a span segment past the reader's per-file limit, and message
+ * payloads stay valid JSON through every truncation path.
+ */
+
+/** Content attributes are capped so a giant payload cannot bloat a span segment. */
+export const CONTENT_ATTRIBUTE_LIMIT = 32 * 1024;
+import type { ContentSerializer, InputMessagesContent } from "../core/types.js";
+
+export const aiSdkContentSerializer: ContentSerializer = {
+  json: contentAttribute,
+  text: textContentAttribute,
+  inputMessages: (messages) =>
+    genAiInputMessagesAttribute(messages, (value) =>
+      typeof value === "string" ? value : undefined,
+    ),
+  instructions: genAiSystemInstructionsAttribute,
+  toolDefinitions: genAiToolDefinitionsAttribute,
+  outputMessages: genAiOutputMessagesAttribute,
+  toolResults: toolResultsContentAttribute,
+};
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const MARKER = "... [truncated]";
+
+export function telemetryByteLength(text: string): number {
+  return encoder.encode(text).length;
+}
+
+export function truncateTelemetryText(text: string, maxBytes: number): string {
+  const prefix = text.slice(0, maxBytes + 1);
+  const bytes = encoder.encode(prefix);
+  if (prefix.length === text.length && bytes.length <= maxBytes) return text;
+  const marker = MARKER.slice(0, maxBytes);
+  let end = Math.max(0, maxBytes - marker.length);
+  while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return decoder.decode(bytes.subarray(0, end)) + marker;
+}
+
+export function boundedPrincipalId(value: unknown): string | undefined {
+  return typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= 1024 &&
+    telemetryByteLength(value) <= 1024
+    ? value
+    : undefined;
+}
+
+export function boundedTraceError(value: Error): Error {
+  const error = new Error(truncateTelemetryText(value.message, 4096));
+  error.name = truncateTelemetryText(value.name, 128);
+  error.stack = value.stack === undefined ? undefined : truncateTelemetryText(value.stack, 8192);
+  return error;
+}
+
+/** Serializes one payload value as capped JSON. */
+export function contentAttribute(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  let json: string | undefined;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    return undefined;
+  }
+  if (json === undefined) return undefined;
+  return textContentAttribute(json);
+}
+
+/** Serializes model messages using the OpenTelemetry GenAI message schema. */
+export function genAiInputMessagesAttribute(
+  messages: unknown,
+  messageKind?: (value: unknown) => string | undefined,
+): InputMessagesContent | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  const formatted = messages.flatMap((message) => {
+    if (!isRecord(message) || message.role === "system" || typeof message.role !== "string") {
+      return [];
+    }
+    const parts = semanticParts(message.content);
+    if (parts.length === 0) return [];
+    const kind = message.role === "user" ? messageKind?.(message.kind) : undefined;
+    return [
+      kind === undefined ? { parts, role: message.role } : { kind, parts, role: message.role },
+    ];
+  });
+  for (let start = 0; start < formatted.length; start += 1) {
+    const json = semanticJsonAttribute(formatted.slice(start));
+    if (json !== undefined) return { json, omitted: start };
+  }
+  const newest = truncateSingleSemanticMessage(formatted);
+  if (newest !== undefined) return { json: newest, omitted: formatted.length - 1 };
+  return { json: "[]", omitted: formatted.length };
+}
+
+/** Serializes the system prompt using the OpenTelemetry GenAI instruction schema. */
+export function genAiSystemInstructionsAttribute(instructions: unknown): string | undefined {
+  const text = systemPromptText(instructions);
+  if (text === undefined) return undefined;
+  return fitSemanticText(text, (content) => [{ content, type: "text" }]);
+}
+
+/** Serializes one model response using the OpenTelemetry GenAI message schema. */
+export function genAiOutputMessagesAttribute(
+  content: readonly unknown[],
+  finishReason: string,
+): string | undefined {
+  const parts = semanticParts(content);
+  const reason = finishReason === "tool-calls" ? "tool_call" : finishReason;
+  const message = (messageParts: unknown) => [
+    { finish_reason: reason, parts: messageParts, role: "assistant" },
+  ];
+  // An oversized response keeps a truncated text form, as an oversized prompt does.
+  return (
+    semanticJsonAttribute(message(parts)) ??
+    fitSemanticText(
+      semanticMessageText(parts),
+      (text) => message([{ content: text, type: "text" }]),
+      true,
+    )
+  );
+}
+
+/** Serializes memory records using the OpenTelemetry GenAI memory-records schema. */
+export function genAiMemoryRecordsAttribute(records: readonly unknown[]): string | undefined {
+  return semanticJsonAttribute(records);
+}
+
+/**
+ * Serializes provider-executed tool results, keeping the attribute valid
+ * JSON under the cap: when the full payload is too big, each entry's input
+ * and output collapse to capped text at progressively smaller budgets
+ * instead of cutting the JSON mid-string.
+ */
+export function toolResultsContentAttribute(
+  results: readonly Record<string, unknown>[],
+): string | undefined {
+  if (results.length === 0) return undefined;
+  const full = stringifyContent(results);
+  if (full !== undefined && full.length <= CONTENT_ATTRIBUTE_LIMIT) return full;
+  for (let cap = CONTENT_ATTRIBUTE_LIMIT; cap >= 0; cap = cap >= 256 ? Math.floor(cap / 2) : -1) {
+    const json = stringifyContent(results.map((entry) => cappedToolResult(entry, cap)));
+    if (json !== undefined && json.length <= CONTENT_ATTRIBUTE_LIMIT) return json;
+  }
+  return undefined;
+}
+
+function cappedToolResult(entry: Record<string, unknown>, cap: number): Record<string, unknown> {
+  const out: Record<string, unknown> = { toolName: entry.toolName };
+  for (const key of ["input", "output", "error"]) {
+    if (!(key in entry)) continue;
+    const value = entry[key];
+    const text = typeof value === "string" ? value : (stringifyContent(value) ?? "");
+    out[key] = text.length <= cap ? text : `${text.slice(0, cap)}… [truncated]`;
+  }
+  return out;
+}
+
+/** Serializes tool definitions, dropping trailing entries to keep the JSON whole. */
+export function genAiToolDefinitionsAttribute(tools: unknown): string | undefined {
+  if (!Array.isArray(tools)) return undefined;
+  const definitions = tools.flatMap((tool): Record<string, unknown>[] => {
+    if (!isRecord(tool) || typeof tool.name !== "string") return [];
+    const definition: Record<string, unknown> = { name: tool.name };
+    if (typeof tool.description === "string") definition.description = tool.description;
+    if (tool.inputSchema !== undefined) definition.parameters = tool.inputSchema;
+    return [definition];
+  });
+  if (definitions.length === 0) return undefined;
+
+  const serialized: string[] = [];
+  let length = 2;
+  for (const definition of definitions) {
+    const json = stringifyContent(definition);
+    if (json === undefined) break;
+    const nextLength = length + (serialized.length === 0 ? 0 : 1) + json.length;
+    if (nextLength > CONTENT_ATTRIBUTE_LIMIT) break;
+    serialized.push(json);
+    length = nextLength;
+  }
+  return `[${serialized.join(",")}]`;
+}
+
+/** Normalizes the AI SDK's `instructions` prompt to plain text. */
+function systemPromptText(instructions: unknown): string | undefined {
+  if (typeof instructions === "string") return instructions.length === 0 ? undefined : instructions;
+  if (!isRecord(instructions) && !Array.isArray(instructions)) return undefined;
+  const messages = Array.isArray(instructions) ? instructions : [instructions];
+  const texts: string[] = [];
+  for (const message of messages) {
+    if (!isRecord(message)) continue;
+    if (typeof message.content === "string") texts.push(message.content);
+    else if (Array.isArray(message.content))
+      for (const part of message.content)
+        if (isRecord(part) && part.type === "text" && typeof part.text === "string")
+          texts.push(part.text);
+  }
+  const joined = texts.join("\n\n").trim();
+  return joined.length === 0 ? undefined : joined;
+}
+
+/** Caps plain text, marking the cut. */
+export function textContentAttribute(text: string): string | undefined {
+  if (text.length === 0) return undefined;
+  return text.length <= CONTENT_ATTRIBUTE_LIMIT
+    ? text
+    : `${text.slice(0, CONTENT_ATTRIBUTE_LIMIT)}… [truncated]`;
+}
+
+function stringifyContent(value: unknown): string | undefined {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return undefined;
+  }
+}
+
+function semanticJsonAttribute(value: unknown): string | undefined {
+  const json = stringifyContent(value);
+  return json !== undefined && json.length <= CONTENT_ATTRIBUTE_LIMIT ? json : undefined;
+}
+
+function truncateSingleSemanticMessage(
+  messages: readonly Record<string, unknown>[],
+): string | undefined {
+  const message = messages.at(-1);
+  if (message === undefined || typeof message.role !== "string") return undefined;
+  const text = semanticMessageText(message.parts);
+  const base =
+    typeof message.kind === "string"
+      ? { kind: message.kind, role: message.role }
+      : { role: message.role };
+  return fitSemanticText(
+    text,
+    (content) => [{ ...base, parts: [{ content, type: "text" }] }],
+    true,
+  );
+}
+
+function fitSemanticText(
+  text: string,
+  wrap: (content: string) => unknown,
+  alwaysMark = false,
+): string | undefined {
+  if (!alwaysMark && text.length <= CONTENT_ATTRIBUTE_LIMIT) {
+    const full = semanticJsonAttribute(wrap(text));
+    if (full !== undefined) return full;
+  }
+  for (let length = Math.min(text.length, CONTENT_ATTRIBUTE_LIMIT); length > 0; length -= 256) {
+    const json = semanticJsonAttribute(wrap(`${text.slice(0, length)}… [truncated]`));
+    if (json !== undefined) return json;
+  }
+  return semanticJsonAttribute(wrap("… [truncated]"));
+}
+
+function semanticMessageText(parts: unknown): string {
+  if (!Array.isArray(parts)) return "";
+  let text = "";
+  for (const part of parts) {
+    if (!isRecord(part) || part.type !== "text" || typeof part.content !== "string") continue;
+    const separator = text.length === 0 ? "" : "\n";
+    const remaining = CONTENT_ATTRIBUTE_LIMIT + 1 - text.length - separator.length;
+    if (remaining <= 0) break;
+    text += separator + part.content.slice(0, remaining);
+  }
+  return text;
+}
+
+function semanticParts(content: unknown): Record<string, unknown>[] {
+  if (typeof content === "string") return [{ content, type: "text" }];
+  if (!Array.isArray(content)) return [];
+  const parts: Record<string, unknown>[] = [];
+  for (const part of content) {
+    const formatted = semanticPart(part);
+    if (formatted !== undefined) parts.push(formatted);
+  }
+  return parts;
+}
+
+function semanticPart(value: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(value) || typeof value.type !== "string") return undefined;
+  switch (value.type) {
+    case "text":
+    case "reasoning": {
+      const content = typeof value.text === "string" ? value.text : value.content;
+      return typeof content === "string" ? { content, type: value.type } : undefined;
+    }
+    case "tool-call":
+      return {
+        arguments: value.input,
+        id: stringValue(value.toolCallId) ?? stringValue(value.callId) ?? null,
+        name: value.toolName,
+        type: "tool_call",
+      };
+    case "tool-result":
+      return {
+        id: stringValue(value.toolCallId) ?? stringValue(value.callId) ?? null,
+        response: toolResponse(value.output),
+        type: "tool_call_response",
+      };
+    case "tool-error":
+      return {
+        id: stringValue(value.toolCallId) ?? stringValue(value.callId) ?? null,
+        response: value.error instanceof Error ? value.error.message : value.error,
+        type: "tool_call_response",
+      };
+    default:
+      return { type: value.type };
+  }
+}
+
+function toolResponse(output: unknown): unknown {
+  if (!isRecord(output)) return output;
+  if (
+    (output.type === "text" ||
+      output.type === "error-text" ||
+      output.type === "json" ||
+      output.type === "error-json") &&
+    "value" in output
+  ) {
+    return output.value;
+  }
+  if (output.type === "execution-denied") {
+    return { denied: true, reason: output.reason };
+  }
+  return output;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}