@vercel/agent-runs 0.0.0-stage → 0.0.1

package/src/agent-run.ts

@@ -0,0 +1,341 @@
+import { randomUUID } from "node:crypto";
+import { otelTelemetry } from "./adapters/otel.js";
+import { aiSdkContentSerializer } from "./adapters/serialization.js";
+import { createScopes, type LiveOperation } from "./core/scopes.js";
+import { currentAgentHandoff } from "./core/delegation.js";
+import { intersectCapture } from "./core/activation.js";
+import { traceSnapshot } from "./core/snapshot.js";
+import { operationHandle, wrappedOperation, type TurnOperation } from "./operations.js";
+import type {
+  AgentTelemetry,
+  Attributes,
+  CaptureDecision,
+  ContentSerializer,
+  ExecutionContext,
+  FrameworkIdentity,
+  RunIdentity,
+  ScopeRecord,
+  TraceCheckpointer,
+  TraceErrorHandler,
+  TraceLink,
+  TraceReference,
+} from "./core/types.js";
+
+export interface AgentRunOptions {
+  /** Span output and context propagation. Defaults to the global OpenTelemetry provider. */
+  readonly telemetry?: AgentTelemetry;
+  /**
+   * Makes turns durable. Each in-flight turn is saved under a library-chosen
+   * key and removed when the turn and its open tool calls complete. Calling
+   * `turn()` again with the same identity, in this or a later process,
+   * continues the saved turn.
+   */
+  readonly checkpointer?: TraceCheckpointer;
+  /** Defaults to the AI SDK content serializer. */
+  readonly serializer?: ContentSerializer;
+  readonly onError?: TraceErrorHandler;
+}
+
+export interface TurnInput {
+  readonly identity: RunIdentity;
+  /** Names the invocation span. Omit for an anonymous agent. */
+  readonly agentName?: string;
+  readonly sequence: number;
+  readonly framework?: FrameworkIdentity;
+  readonly capture?: CaptureDecision;
+  readonly attributes?: Attributes;
+  /**
+   * Adopts a trace and span ID reserved before the turn started, such as one
+   * already returned to a caller. Requires telemetry with stable `ids`.
+   */
+  readonly reference?: TraceReference;
+  /**
+   * Nests the turn under a caller's span in the caller's trace. A local
+   * handoff sets this for the first turn; remote callees start their own trace.
+   */
+  readonly parent?: TraceReference;
+  readonly links?: readonly TraceLink[];
+  readonly startTimeMs?: number;
+  /** Delegation lineage recorded by the host, when it is not carried by a handoff. */
+  readonly lineage?: {
+    readonly parentRunId?: string;
+    readonly parentCallId?: string;
+    readonly agentName?: string;
+  };
+  readonly channel?: { readonly kind?: string; readonly origin?: string };
+  /** Host context for spans this process starts, such as OpenTelemetry baggage. */
+  readonly context?: ExecutionContext;
+}
+
+export interface ResumeInput {
+  readonly identity: RunIdentity;
+  readonly context?: ExecutionContext;
+}
+
+interface MemoryInput<T> {
+  identity: RunIdentity;
+  storeId: string;
+  slot: string;
+  phase: string;
+  capture?: CaptureDecision;
+  /** Defaults to the active operation. */
+  parent?: TraceReference;
+  context?: ExecutionContext;
+  describe?: (value: T) => {
+    recordCount?: number;
+    records?: readonly { id?: string; content: string }[];
+  };
+}
+
+export interface AgentRun {
+  turn: import("./operations.js").WrappedOperation<TurnInput, TurnOperation>;
+  /** Returns a saved durable turn, without starting one. */
+  resume(input: ResumeInput): Promise<TurnOperation | undefined>;
+  memory: AgentMemoryTracing;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+export interface AgentMemoryTracing {
+  search<T>(data: MemoryInput<T>, execute: () => T | PromiseLike<T>): Promise<T>;
+  write<T>(data: MemoryInput<T>, execute: () => T | PromiseLike<T>): Promise<T>;
+}
+
+const METADATA_ONLY: CaptureDecision = { emit: true, recordInputs: false, recordOutputs: false };
+const LIVE_TURNS = 1000;
+
+interface LiveTurn {
+  readonly root: LiveOperation;
+  /** Token of the last checkpoint this process wrote. */
+  revision: string | undefined;
+  writes: number;
+}
+
+export function createAgentRun(input: AgentRunOptions): AgentRun {
+  const telemetry = input.telemetry ?? otelTelemetry();
+  const checkpointer = input.checkpointer;
+  if (checkpointer !== undefined && telemetry.ids === undefined)
+    throw new Error(
+      "Durable agent tracing needs stable span IDs. Pass the AgentSpanIdGenerator installed on your tracer provider to otelTelemetry({ idGenerator }).",
+    );
+  const report: TraceErrorHandler = (error, context) => {
+    try {
+      input.onError?.(error, context);
+    } catch {}
+  };
+  const scopes = createScopes({
+    telemetry,
+    serializer: input.serializer ?? aiSdkContentSerializer,
+    durable: checkpointer !== undefined,
+    onError: input.onError,
+  });
+  // Turns hydrated in this process, so concurrent hooks share one tree. The
+  // checkpoint stays authoritative: another process's write replaces the entry.
+  const live = new Map<string, Promise<LiveTurn | undefined>>();
+
+  function turnKey(identity: RunIdentity): string {
+    if (checkpointer === undefined) return `turn:${randomUUID()}`;
+    return ["turn", identity.runId, identity.turnId].map(encodeURIComponent).join(":");
+  }
+
+  /** Writes are serialized so a slow store never persists an older tree last. */
+  function persistence(key: string, entry: () => LiveTurn | undefined) {
+    let queue = Promise.resolve();
+    return () => {
+      const turn = entry();
+      if (checkpointer === undefined || turn === undefined) return queue;
+      turn.writes++;
+      queue = queue.then(async () => {
+        try {
+          if (turn.root.settled) {
+            live.delete(key);
+            await checkpointer.delete(key);
+          } else {
+            const revision = randomUUID();
+            await checkpointer.set(key, traceSnapshot({ ...turn.root.record(), revision }));
+            turn.revision = revision;
+          }
+        } catch (error) {
+          report(error, { phase: "checkpoint", operation: "activation" });
+        } finally {
+          turn.writes--;
+        }
+      });
+      return queue;
+    };
+  }
+
+  async function loadCheckpoint(key: string): Promise<unknown> {
+    try {
+      return await checkpointer!.get(key);
+    } catch (error) {
+      report(error, { phase: "restore", operation: "activation" });
+      return undefined;
+    }
+  }
+
+  async function hydrate(
+    key: string,
+    cached: LiveTurn | undefined,
+    open: ((onChange: () => Promise<void>) => Promise<LiveOperation>) | undefined,
+    context: ExecutionContext | undefined,
+    capture?: CaptureDecision,
+  ): Promise<LiveTurn | undefined> {
+    const ceiling = currentAgentHandoff()?.capture;
+    capture = capture === undefined ? ceiling : intersectCapture(capture, ceiling);
+    const saved = checkpointer === undefined ? undefined : await loadCheckpoint(key);
+    if (
+      cached !== undefined &&
+      (cached.writes > 0 || (saved as ScopeRecord | undefined)?.revision === cached.revision)
+    ) {
+      if (context !== undefined) cached.root.useContext(context);
+      // A re-entry may decline content the cached turn was allowed to record.
+      if (capture !== undefined) cached.root.narrow(capture);
+      return cached;
+    }
+    let entry: LiveTurn | undefined;
+    const onChange = persistence(key, () => entry);
+    const restored =
+      saved === undefined ? undefined : await scopes.restore(saved, { capture, context, onChange });
+    const root = restored ?? (await open?.(onChange));
+    if (root === undefined) return undefined;
+    entry = { root, revision: (saved as ScopeRecord | undefined)?.revision, writes: 0 };
+    if (restored === undefined) await onChange();
+    return entry;
+  }
+
+  function cache(
+    key: string,
+    load: (cached: LiveTurn | undefined) => Promise<LiveTurn | undefined>,
+  ): Promise<LiveTurn | undefined> {
+    const previous = live.get(key);
+    const loading = (async () =>
+      load(previous === undefined ? undefined : await previous.catch(() => undefined)))();
+    live.set(key, loading);
+    void loading.then(
+      (turn) => {
+        if (turn === undefined || turn.root.settled) live.delete(key);
+      },
+      () => live.delete(key),
+    );
+    if (live.size > LIVE_TURNS) live.delete(live.keys().next().value!);
+    return loading;
+  }
+
+  function startTurn(data: TurnInput, key: string) {
+    return (onChange: () => Promise<void>) => {
+      const handoff = currentAgentHandoff();
+      const capture = intersectCapture(data.capture ?? METADATA_ONLY, handoff?.capture);
+      const first = handoff !== undefined && data.sequence === 0;
+      const parent =
+        data.parent ?? (first && handoff?.remote !== true ? handoff?.caller : undefined);
+      const caller =
+        first && handoff?.remote === true
+          ? [{ relationship: "agent.dispatch", context: handoff.caller }]
+          : [];
+      const links = [...caller, ...(data.links ?? [])];
+      return scopes.start({
+        identity: {
+          ...data.identity,
+          conversationId: handoff?.conversationId ?? data.identity.conversationId,
+          agentName: data.agentName,
+          framework: data.framework,
+        },
+        key,
+        capture,
+        parent,
+        reference: telemetry.ids === undefined ? undefined : data.reference,
+        startTimeMs: data.startTimeMs,
+        data: {
+          type: "activation",
+          options: {
+            sequence: data.sequence,
+            attributes: data.attributes,
+            channel: data.channel,
+            subagent: handoff !== undefined || data.lineage !== undefined,
+            subagentName: handoff?.agentName ?? data.lineage?.agentName,
+            parentRunId: handoff?.parentRunId ?? data.lineage?.parentRunId,
+            parentCallId: handoff?.parentCallId ?? data.lineage?.parentCallId,
+          },
+        },
+        links: links.length === 0 ? undefined : links,
+        context: data.context,
+        onChange,
+      });
+    };
+  }
+
+  function handle(root: LiveOperation): TurnOperation {
+    return operationHandle(
+      root,
+      { type: "activation", options: { sequence: 0 } },
+      input.onError,
+    ) as TurnOperation;
+  }
+
+  async function turnOperation(data: TurnInput): Promise<TurnOperation> {
+    const key = turnKey(data.identity);
+    const turn =
+      checkpointer === undefined
+        ? await hydrate(key, undefined, startTurn(data, key), data.context)
+        : await cache(key, (cached) =>
+            hydrate(key, cached, startTurn(data, key), data.context, data.capture),
+          );
+    return handle(turn!.root);
+  }
+
+  async function resume(data: ResumeInput): Promise<TurnOperation | undefined> {
+    if (checkpointer === undefined) return undefined;
+    const key = turnKey(data.identity);
+    const turn = await cache(key, (cached) => hydrate(key, cached, undefined, data.context));
+    return turn === undefined ? undefined : handle(turn.root);
+  }
+
+  async function lifecycle(callback: () => Promise<void>) {
+    try {
+      await callback();
+    } catch (error) {
+      report(error, { phase: "complete" });
+    }
+  }
+
+  async function memory<T>(
+    operation: "search_memory" | "upsert_memory",
+    data: MemoryInput<T>,
+    execute: () => T | PromiseLike<T>,
+  ): Promise<T> {
+    const active = telemetry.active();
+    const handle = await scopes.start({
+      identity: data.identity,
+      key: `memory:${randomUUID()}`,
+      capture: data.capture ?? active?.capture ?? METADATA_ONLY,
+      parent: data.parent ?? active?.reference,
+      context: data.context,
+      data: {
+        type: "memory",
+        options: { operation, phase: data.phase, slot: data.slot, storeId: data.storeId },
+      },
+    });
+    let value: T;
+    try {
+      value = await handle.run(execute);
+    } catch (error) {
+      await handle.fail(error).catch((tracingError) => report(tracingError, { phase: "complete" }));
+      throw error;
+    }
+    await handle
+      .complete({ outcome: "completed", ...data.describe?.(value) })
+      .catch((error) => report(error, { phase: "complete" }));
+    return value;
+  }
+
+  return {
+    turn: wrappedOperation(turnOperation, undefined, input.onError),
+    resume,
+    memory: {
+      search: (data, execute) => memory("search_memory", data, execute),
+      write: (data, execute) => memory("upsert_memory", data, execute),
+    },
+    forceFlush: () => lifecycle(() => telemetry.forceFlush()),
+    shutdown: () => lifecycle(() => telemetry.shutdown()),
+  };
+}

package/src/ai-sdk.ts

@@ -0,0 +1,7 @@
+/**
+ * AI SDK integration. `aiSdkTelemetry` records `generateText`, `streamText`,
+ * and AI SDK agents as turns; `modelUsage` and `modelContent` convert AI SDK
+ * payloads for hosts that record model calls themselves.
+ */
+export { aiSdkTelemetry, type AiSdkTelemetryOptions } from "./adapters/ai-sdk-telemetry.js";
+export { modelUsage, modelContent } from "./adapters/ai-sdk-payload.js";

package/src/capture.ts

@@ -0,0 +1,13 @@
+import { context, createContextKey } from "@opentelemetry/api";
+import type { CaptureDecision } from "./core/types.js";
+
+const CAPTURE = createContextKey("agent.tracing.capture");
+export function currentCapture(): CaptureDecision | undefined {
+  return context.active().getValue(CAPTURE) as CaptureDecision | undefined;
+}
+export function withCapture<T extends { setValue(key: symbol, value: unknown): T }>(
+  host: T,
+  capture: CaptureDecision,
+): T {
+  return host.setValue(CAPTURE, capture);
+}

package/src/core/activation.ts

@@ -0,0 +1,42 @@
+import type { ActiveOperation, CaptureDecision } from "./types.js";
+
+export function intersectCapture(
+  capture: CaptureDecision,
+  ceiling?: CaptureDecision,
+): CaptureDecision {
+  const emit = capture.emit && (ceiling?.emit ?? true);
+  return {
+    emit,
+    recordInputs: emit && capture.recordInputs && (ceiling?.recordInputs ?? true),
+    recordOutputs: emit && capture.recordOutputs && (ceiling?.recordOutputs ?? true),
+  };
+}
+
+export function activeOperation(
+  operation: ActiveOperation,
+  capture: CaptureDecision,
+): ActiveOperation {
+  const mcp = operation.mcp;
+  return {
+    type: operation.type,
+    reference: operation.reference,
+    capture,
+    mcp:
+      mcp === undefined
+        ? undefined
+        : {
+            update: (input) => mcp.update(input),
+            error: (error, type) =>
+              mcp.error(
+                capture.recordOutputs ? error : undefined,
+                type ?? (error instanceof Error ? error.name : undefined),
+              ),
+            arguments: (value) => {
+              if (capture.recordInputs) mcp.arguments(value);
+            },
+            result: (value) => {
+              if (capture.recordOutputs) mcp.result(value);
+            },
+          },
+  };
+}

package/src/core/attributes.ts

@@ -0,0 +1,85 @@
+import type { AttributeValue, Attributes, FrameworkIdentity, RunIdentity, Usage } from "./types.js";
+const TRACE_SCHEMA_VERSION = 4;
+export const USAGE_FIELDS = {
+  costUsd: "agent.usage.cost_usd",
+  inputTokens: "agent.usage.input_tokens",
+  outputTokens: "agent.usage.output_tokens",
+  cacheReadTokens: "agent.usage.cache_read_tokens",
+  cacheWriteTokens: "agent.usage.cache_write_tokens",
+} as const;
+
+export function identityAttributes(
+  identity: Pick<RunIdentity, "runId" | "conversationId">,
+): Attributes {
+  return {
+    "agent.run.id": identity.runId,
+    "agent.trace.schema.version": TRACE_SCHEMA_VERSION,
+    "gen_ai.conversation.id": identity.conversationId,
+  };
+}
+
+export function namingAttributes(name: string, operation = name): Attributes {
+  return { "operation.name": operation, "resource.name": name };
+}
+
+export function frameworkAttributes(framework?: FrameworkIdentity): Attributes {
+  return {
+    "agent.framework.name": framework?.name || undefined,
+    "agent.framework.version": framework?.version || undefined,
+  };
+}
+
+/** Invocation and model spans use GenAI token counts; structural spans use eve's. */
+export function usageAttributes(usage: Usage, genAi = false): Attributes {
+  if (genAi)
+    return {
+      [USAGE_FIELDS.costUsd]: usage.costUsd,
+      "gen_ai.usage.input_tokens": usage.inputTokens,
+      "gen_ai.usage.output_tokens": usage.outputTokens,
+      "gen_ai.usage.cache_read.input_tokens": usage.inputTokenDetails?.cacheReadTokens,
+      "gen_ai.usage.cache_write.input_tokens": usage.inputTokenDetails?.cacheWriteTokens,
+    };
+  return {
+    [USAGE_FIELDS.costUsd]: usage.costUsd,
+    [USAGE_FIELDS.inputTokens]: usage.inputTokens,
+    [USAGE_FIELDS.outputTokens]: usage.outputTokens,
+    [USAGE_FIELDS.cacheReadTokens]: usage.inputTokenDetails?.cacheReadTokens,
+    [USAGE_FIELDS.cacheWriteTokens]: usage.inputTokenDetails?.cacheWriteTokens,
+  };
+}
+
+export function runtimeContextAttributes(
+  input: Readonly<Record<string, unknown>> | undefined,
+): Attributes {
+  const attributes: Record<string, Exclude<Attributes[string], undefined>> = {};
+  const seen = new WeakSet<object>();
+  let remaining = 256;
+  function visit(key: string, value: unknown, depth: number): void {
+    if (remaining <= 0 || depth > 8 || value == null) return;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      attributes[key] = value;
+      remaining -= 1;
+    } else if (Array.isArray(value)) {
+      if (
+        value.length <= 256 &&
+        value.every(
+          (item) =>
+            typeof item === "string" || typeof item === "number" || typeof item === "boolean",
+        ) &&
+        new Set(value.map((item) => typeof item)).size === 1
+      ) {
+        attributes[key] = value as AttributeValue;
+        remaining -= 1;
+      }
+    } else if (typeof value === "object" && !seen.has(value)) {
+      seen.add(value);
+      for (const keyPart of Object.keys(value)) {
+        if (remaining <= 0) break;
+        visit(`${key}.${keyPart}`, Reflect.get(value, keyPart), depth + 1);
+      }
+      seen.delete(value);
+    }
+  }
+  if (input !== undefined) visit("ai.settings.context", input, 0);
+  return attributes;
+}

package/src/core/content-policy.ts

@@ -0,0 +1,116 @@
+/**
+ * Which span attributes carry conversation content, and in which direction.
+ *
+ * Two vocabularies land on the same spans: the ones the library sets on its own
+ * `agent.*` spans, and the ones the AI SDK's OpenTelemetry integration sets on
+ * the model-call spans beneath them. A destination that declined content has to
+ * be rid of both, so both are listed here rather than in the module that writes
+ * each.
+ *
+ * Listed by name rather than by prefix because the prefixes are shared with
+ * metadata that must survive: `ai.response.finish_reason` and
+ * `gen_ai.tool.name` say what happened, not what was said. The cost is that a
+ * new content attribute in a dependency is not covered until it is added here.
+ */
+
+/** Prompts, instructions, tool arguments — what went in. */
+const INPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([
+  "agent.channel.delivery.input",
+  "agent.session.title",
+  "agent.approval.request",
+  "ai.documents",
+  "ai.prompt",
+  "ai.prompt.toolChoice",
+  "ai.prompt.tools",
+  "ai.value",
+  "ai.values",
+  "gen_ai.input.messages",
+  "gen_ai.memory.records",
+  "gen_ai.system_instructions",
+  "gen_ai.tool.call.arguments",
+  "gen_ai.tool.definitions",
+]);
+
+/**
+ * Responses, reasoning, tool results — what came out.
+ *
+ * `ai.toolCall.args` is here rather than above because the AI SDK gates it on
+ * `recordOutputs`; matching that is what keeps one destination's view coherent.
+ */
+const OUTPUT_CONTENT_ATTRIBUTES: ReadonlySet<string> = new Set([
+  "agent.approval.response",
+  "ai.embedding",
+  "ai.embeddings",
+  "ai.ranking",
+  "ai.response.files",
+  "ai.response.object",
+  "ai.response.reasoning",
+  "ai.response.text",
+  "ai.response.toolCalls",
+  "ai.response.tool_calls",
+  "ai.response.tool_results",
+  "ai.toolCall.args",
+  "ai.toolCall.result",
+  "gen_ai.output.messages",
+  "gen_ai.tool.call.result",
+]);
+
+const INPUT_POLICY_ATTRIBUTE = "agent.trace.content.input";
+const OUTPUT_POLICY_ATTRIBUTE = "agent.trace.content.output";
+
+/** What one destination is willing to receive. */
+export interface ResolvedContentOptions {
+  readonly recordInputs: boolean;
+  readonly recordOutputs: boolean;
+}
+
+function isDeclined(key: string, content: ResolvedContentOptions): boolean {
+  if (!content.recordInputs && INPUT_CONTENT_ATTRIBUTES.has(key)) return true;
+  return !content.recordOutputs && OUTPUT_CONTENT_ATTRIBUTES.has(key);
+}
+
+function narrowsContentPolicy(
+  attributes: Readonly<Record<string, unknown>>,
+  content: ResolvedContentOptions,
+): boolean {
+  return (
+    (!content.recordInputs && attributes[INPUT_POLICY_ATTRIBUTE] === true) ||
+    (!content.recordOutputs && attributes[OUTPUT_POLICY_ATTRIBUTE] === true)
+  );
+}
+
+function exportedAttributeValue(
+  key: string,
+  value: unknown,
+  content: ResolvedContentOptions,
+): unknown {
+  if (key === INPUT_POLICY_ATTRIBUTE && value === true && !content.recordInputs) return false;
+  if (key === OUTPUT_POLICY_ATTRIBUTE && value === true && !content.recordOutputs) return false;
+  return value;
+}
+
+/**
+ * The attributes with the declined content removed, or `undefined` when there
+ * was none to remove.
+ *
+ * The `undefined` return is what lets the caller forward the original span
+ * untouched in the common case, so a destination that declined a direction the
+ * span never carried costs one pass over its keys and no allocation.
+ */
+export function withoutDeclinedContent(
+  attributes: Readonly<Record<string, unknown>>,
+  content: ResolvedContentOptions,
+): Record<string, unknown> | undefined {
+  const keys = Object.keys(attributes);
+  if (!keys.some((key) => isDeclined(key, content)) && !narrowsContentPolicy(attributes, content)) {
+    return undefined;
+  }
+
+  const kept: Record<string, unknown> = {};
+  for (const key of keys) {
+    if (!isDeclined(key, content)) {
+      kept[key] = exportedAttributeValue(key, attributes[key], content);
+    }
+  }
+  return kept;
+}

package/src/core/context.ts

@@ -0,0 +1,34 @@
+import type { ActiveOperation, AgentTelemetry, ExecutionContext } from "./types.js";
+
+/** Runs `execute` exactly once, even when the telemetry cannot enter the context. */
+export function runTraceContext<T>(
+  telemetry: Pick<AgentTelemetry, "run" | "suppressed">,
+  operation: ActiveOperation,
+  execute: () => T,
+  host?: ExecutionContext,
+): T {
+  let entered = false;
+  try {
+    return telemetry.run(
+      operation,
+      () => {
+        entered = true;
+        return execute();
+      },
+      host,
+    );
+  } catch (error) {
+    if (entered) throw error;
+    if (telemetry.suppressed !== undefined) {
+      try {
+        return telemetry.suppressed(() => {
+          entered = true;
+          return execute();
+        });
+      } catch (error) {
+        if (entered) throw error;
+      }
+    }
+    return execute();
+  }
+}

package/src/core/delegation.ts

@@ -0,0 +1,20 @@
+import { context, createContextKey } from "@opentelemetry/api";
+import type { CaptureDecision, TraceReference } from "./types.js";
+
+export interface AgentHandoff {
+  readonly caller: TraceReference;
+  readonly conversationId: string;
+  readonly parentRunId: string;
+  readonly parentCallId: string;
+  readonly agentName: string;
+  readonly capture: CaptureDecision;
+  /** Set when the handoff crossed a process boundary; the callee then starts its own trace. */
+  readonly remote?: boolean;
+}
+
+const HANDOFF = createContextKey("agent.tracing.handoff");
+export const currentAgentHandoff = () =>
+  context.active().getValue(HANDOFF) as AgentHandoff | undefined;
+export function withAgentHandoff<T>(handoff: AgentHandoff, execute: () => T): T {
+  return context.with(context.active().setValue(HANDOFF, handoff), execute);
+}