The Open Framework for Building Agents
import { randomBytes } from "node:crypto";
import { boundedTraceError } from "../adapters/serialization.js";
import { createSpanWriter, type TraceOperation } from "./writer.js";
import { usageAttributes } from "./attributes.js";
import {
completeScope,
capturedScopeData as capturedData,
prepareScope,
parentKinds,
applyAttributes,
} from "./span-kinds.js";
import { mcpLifecycle, type McpLifecycle } from "./mcp.js";
import { intersectCapture } from "./activation.js";
import { snapshotRecord, traceSnapshot, validSnapshot, boundedSerializer } from "./snapshot.js";
import { withAgentHandoff } from "./delegation.js";
import { withoutDeclinedContent } from "./content-policy.js";
import { runTraceContext } from "./context.js";
import type {
AgentTelemetry,
Attributes,
CaptureDecision,
ContentSerializer,
ExecutionContext,
Operation,
ScopeData,
ScopeIdentity,
ScopeRecord,
ScopeTerminal,
TraceErrorHandler,
TraceLink,
TraceReference,
Usage,
} from "./types.js";
const UNFINISHED_CHILDREN = 10000;
const NO_CAPTURE: CaptureDecision = { emit: false, recordInputs: false, recordOutputs: false };
interface Construction extends Partial<ScopeRecord> {
readonly key: string;
readonly deferred?: boolean;
readonly executionContext?: ExecutionContext;
/** Applies sampling to a host-supplied root reference. */
readonly sample?: boolean;
}
export interface ChildOptions {
readonly links?: readonly TraceLink[];
readonly startTimeMs?: number;
}
export interface LiveOperation extends Operation {
child(data: ScopeData, key?: string, options?: ChildOptions): Promise<LiveOperation>;
/** Returns an unsettled child with this identity, without starting one. */
find(data: ScopeData): LiveOperation | undefined;
/** Unsettled children, in start order. */
readonly children: readonly LiveOperation[];
usage(usage: Usage, key?: string): Promise<void>;
/** Carries a model call's messages up to its turn: the first input and the latest output. */
turnContent(content: { readonly input?: string; readonly output?: string }): void;
error(error?: unknown, type?: string): void;
/** Replaces the host context for this operation and its descendants. */
useContext(context: ExecutionContext): void;
/** Fills in a deferred operation's details from a later call with the same identity. */
refine(data: ScopeData, startTimeMs?: number): void;
/** Lowers capture for this operation and its children, and drops retained content it no longer allows. */
narrow(capture: CaptureDecision): void;
/** Completes this operation, or closes the open descendants of a finished one. */
release(result: ScopeTerminal): Promise<void>;
/** Finished, with no unfinished descendants. */
readonly settled: boolean;
readonly callId?: string;
readonly mcp: McpLifecycle;
record(): ScopeRecord;
}
/** Durable trees reserve stable IDs and defer spans whose lifetime can cross processes. */
const DEFERRED_WHEN_DURABLE: ReadonlySet<ScopeData["type"]> = new Set([
"activation",
"tool",
"approval",
]);
/** Durable work a successful attempt or turn leaves open, such as a tool awaiting approval. */
const OUTLIVES_ATTEMPT: ReadonlySet<ScopeData["type"]> = new Set(["tool", "approval"]);
function segment(value: string | number): string {
return encodeURIComponent(String(value));
}
/** Children with a stable identity hydrate on re-entry; the rest are numbered. */
function semanticKey(data: ScopeData): string | undefined {
switch (data.type) {
case "step":
return `step:${segment(data.options.index)}:${segment(data.options.attempt ?? 0)}`;
case "tool":
return `tool:${segment(data.options.callId)}`;
case "approval":
return `approval:${segment(data.options.requestId)}`;
default:
return undefined;
}
}
function terminalOf(result: ScopeTerminal & { errorType?: string; result?: unknown }) {
const failed = result.failed || result.outcome === "failed";
return {
...result,
model: "result" in result ? result.result : result.model,
failed,
errorCode: "errorType" in result ? result.errorType : result.errorCode,
} as ScopeTerminal;
}
export function createScopes(input: {
readonly telemetry: AgentTelemetry;
readonly serializer: ContentSerializer;
readonly durable: boolean;
readonly onError?: TraceErrorHandler;
}) {
const telemetry = input.telemetry;
const serializer = boundedSerializer(input.serializer, input.onError);
const engine = createSpanWriter({ telemetry, onError: input.onError });
const report: TraceErrorHandler = (error, context) => {
try {
input.onError?.(error, context);
} catch {}
};
function snapshotContent(value: unknown): unknown {
const json = serializer.json(value);
try {
return json === undefined ? undefined : JSON.parse(json);
} catch {
return undefined;
}
}
function reserve(
data: ScopeData,
key: string,
parent: TraceReference | undefined,
prepared: ReturnType<typeof prepareScope>,
capture: CaptureDecision,
): TraceReference | undefined {
const ids = telemetry.ids;
if (!input.durable || ids === undefined) return undefined;
// Re-executed model calls and memory reads are new work and get new IDs.
if (data.type === "model" || data.type === "memory") return undefined;
if (data.type === "activation" && parent !== undefined)
return {
traceId: parent.traceId,
spanId: ids.spanId(key),
traceFlags: capture.emit ? parent.traceFlags & 1 : 0,
};
if (data.type === "activation") {
const traceId = ids.traceId(key);
return {
traceId,
spanId: ids.spanId(key),
traceFlags: capture.emit && (telemetry.samples?.(traceId, prepared) ?? true) ? 1 : 0,
};
}
return parent === undefined
? undefined
: { ...parent, spanId: ids.spanId(key), isRemote: false };
}
async function construct(
identity: ScopeIdentity,
capture: CaptureDecision,
data: ScopeData,
parent: LiveOperation | undefined,
attempt: ScopeRecord["attempt"],
binding: Construction,
onChange: () => Promise<void>,
): Promise<LiveOperation> {
try {
return await constructOperation(identity, capture, data, parent, attempt, binding, onChange);
} catch (error) {
report(error, { phase: "start", operation: data.type, reference: binding.reference });
return constructOperation(
identity,
NO_CAPTURE,
capturedData(data, NO_CAPTURE),
parent,
attempt,
{
...binding,
sample: false,
reference: {
traceId:
binding.reference?.traceId ??
parent?.reference.traceId ??
binding.parent?.traceId ??
randomBytes(16).toString("hex"),
spanId: binding.reference?.spanId ?? randomBytes(8).toString("hex"),
traceFlags: 0,
},
},
onChange,
);
}
}
async function constructOperation(
identity: ScopeIdentity,
capture: CaptureDecision,
data: ScopeData,
parent: LiveOperation | undefined,
attempt: ScopeRecord["attempt"],
binding: Construction,
onChange: () => Promise<void>,
): Promise<LiveOperation> {
if (
binding.terminal?.error !== null &&
typeof binding.terminal?.error === "object" &&
!(binding.terminal.error instanceof Error) &&
"message" in binding.terminal.error &&
typeof binding.terminal.error.message === "string"
) {
const error = new Error(binding.terminal.error.message);
error.name = binding.terminal.errorCode ?? "Error";
binding = { ...binding, terminal: { ...binding.terminal, error } };
}
const key = binding.key;
let startTimeMs = binding.startTimeMs ?? Date.now();
// A restored record keeps its saved parent; a nested activation names its own.
const parentReference = binding.parent ?? parent?.reference;
if (capture.emit) capture = intersectCapture(capture, telemetry.active()?.capture);
let actualCapture = capture;
let actualData = capturedData(data, actualCapture);
let prepared = prepareScope(
{
identity,
data: actualData,
attempt,
capture: actualCapture,
key,
parent: parentReference,
startTimeMs,
links: binding.links,
},
serializer,
);
prepared = { ...prepared, attributes: { ...prepared.attributes, ...binding.attributes } };
actualData = snapshotRecord(
{
key,
identity,
data: actualData,
capture: actualCapture,
reference: binding.reference ?? {
traceId: "0".repeat(32),
spanId: "0".repeat(16),
traceFlags: 0,
},
startTimeMs,
},
serializer,
).data;
const deferred =
binding.deferred ?? (input.durable && DEFERRED_WHEN_DURABLE.has(actualData.type));
let host = binding.executionContext;
let reference =
binding.reference ?? reserve(data, key, parentReference, prepared, actualCapture);
// A nested turn joins its parent's sampling decision; a root turn asks the sampler.
if (binding.sample === true && reference !== undefined)
reference = {
...reference,
traceFlags:
(reference.traceFlags & 1) !== 0 &&
actualCapture.emit &&
(parentReference !== undefined ||
(telemetry.samples?.(reference.traceId, prepared) ?? true))
? 1
: 0,
};
let operation: TraceOperation | undefined = deferred
? undefined
: engine.start(prepared, actualCapture, host, reference);
const retainedReference = reference ?? operation?.reference;
if (retainedReference === undefined)
throw new Error("A deferred trace scope requires a reserved reference.");
const sampled = (retainedReference.traceFlags & 1) !== 0;
actualCapture = {
emit: actualCapture.emit && sampled,
recordInputs: actualCapture.emit && sampled && actualCapture.recordInputs,
recordOutputs: actualCapture.emit && sampled && actualCapture.recordOutputs,
};
actualData = capturedData(actualData, actualCapture);
let finished = binding.finished ?? false;
let terminalResult = binding.terminal;
const children = new Map<string, LiveOperation>();
const pending = new Set<Promise<void>>();
let childSequence = binding.childSequence ?? 0;
let totalUsage = binding.usage;
const usageKeys = new Set(binding.usageKeys ?? []);
const enrichment: Record<string, Attributes[string]> = {};
const callId = actualData.type === "tool" ? actualData.options.callId : undefined;
function changed(): void {
void onChange();
}
/** Content arriving now is held to any narrower run ceiling in force. */
function current(): CaptureDecision {
return intersectCapture(actualCapture, telemetry.active()?.capture);
}
async function child(
childData: ScopeData,
childKey: string,
options: ChildOptions = {},
): Promise<LiveOperation> {
const existing = children.get(childKey);
if (input.durable && existing !== undefined && !existing.settled) {
existing.refine(childData, options.startTimeMs);
return existing;
}
if (finished) throw new Error("The operation is not permitted in this trace scope.");
for (const [previousKey, previous] of children)
if (previous.settled) children.delete(previousKey);
let childCapture = actualCapture;
if (children.size >= UNFINISHED_CHILDREN) {
report(new Error("Trace unfinished-child limit reached."), {
phase: "start",
operation: childData.type,
reference: retainedReference,
});
childCapture = NO_CAPTURE;
}
if (childData.type === "model" && operation !== undefined)
applyAttributes(operation, { "agent.model.id": childData.options.modelId });
const next = await construct(
identity,
childCapture,
childData,
runtime,
childData.type === "step"
? { index: childData.options.index, attempt: childData.options.attempt ?? 0 }
: attempt,
{
key: childKey,
executionContext: host,
links: options.links,
startTimeMs: options.startTimeMs,
},
onChange,
);
if (childCapture.emit || children.size < UNFINISHED_CHILDREN) children.set(childKey, next);
await onChange();
return next;
}
async function closeChildren(result: ScopeTerminal, all: boolean): Promise<void> {
const container = actualData.type === "step" || actualData.type === "activation";
for (const next of children.values())
if (all || !container || !OUTLIVES_ATTEMPT.has(next.type))
await next.release({ failed: result.failed, error: result.error, outcome: "abandoned" });
}
async function finish(result: ScopeTerminal): Promise<void> {
if (pending.size > 0) await Promise.allSettled(pending);
if (finished) return;
const capture = current();
if (!capture.recordOutputs) result = { ...result, error: undefined };
// A call whose work already failed cannot finish as completed.
if (terminalResult?.failed)
result = {
...result,
outcome: result.outcome === "completed" ? "failed" : result.outcome,
failed: true,
error: terminalResult.error,
errorCode: result.errorCode ?? terminalResult.errorCode,
};
finished = true;
terminalResult = result;
await closeChildren(result, result.failed === true || !input.durable);
operation ??= engine.start(prepared, actualCapture, host, retainedReference);
const terminal =
actualData.type === "activation" && result.usage === undefined
? { ...result, usage: totalUsage }
: result;
try {
completeScope(
operation,
actualData,
terminal,
{ ...capture, emit: actualCapture.emit },
startTimeMs,
serializer,
);
} catch (error) {
report(error, {
phase: "complete",
operation: actualData.type,
reference: retainedReference,
});
}
applyAttributes(operation, enrichment);
if (actualData.type === "model" && result.model !== undefined) {
await parent?.usage(result.model.usage, key);
const content = result.model.content;
if (capture.recordOutputs && actualCapture.recordOutputs && content !== undefined) {
const output = serializer.outputMessages(content, result.model.finishReason);
if (output !== undefined) parent?.turnContent({ output });
}
}
operation.end(result.endTimeMs);
await onChange();
}
const runtime: LiveOperation = {
waitUntil(completion) {
pending.add(completion);
parent?.waitUntil(completion);
void completion.then(
() => pending.delete(completion),
() => pending.delete(completion),
);
},
snapshot: () => traceSnapshot(runtime.record()),
attributes: (attributes) => runtime.update({ attributes }),
modelCall: (options, key) => runtime.child({ type: "model", options }, key),
fail(error) {
runtime.error(error);
return runtime.complete({ outcome: "failed", failed: true });
},
update(update) {
if (finished) return;
const attributes = (withoutDeclinedContent(update.attributes ?? {}, current()) ??
update.attributes) as Attributes;
if (actualData.type === "activation")
actualData = {
...actualData,
options: {
...actualData.options,
attributes: { ...actualData.options.attributes, ...attributes },
},
};
prepared = {
...prepared,
attributes: { ...prepared.attributes, ...attributes },
links: update.links ?? prepared.links,
};
if (operation !== undefined) applyAttributes(operation, attributes);
changed();
},
useContext(context) {
host = context;
for (const next of children.values()) next.useContext(context);
},
refine(next, earlierStart) {
if (finished || operation !== undefined) return;
if (earlierStart !== undefined && earlierStart < startTimeMs) startTimeMs = earlierStart;
if (next.type === "tool" && actualData.type === "tool") {
const known = actualData.options;
actualData = capturedData(
{
type: "tool",
options: {
...known,
kind: known.kind ?? next.options.kind,
// Earlier arguments were recorded with consent; new ones need it now.
arguments:
known.arguments ??
(current().recordInputs ? snapshotContent(next.options.arguments) : undefined),
},
},
actualCapture,
);
}
const again = prepareScope(
{
identity,
data: actualData,
attempt,
capture: actualCapture,
key,
parent: parentReference,
startTimeMs,
links: prepared.links,
},
serializer,
);
const defined = Object.fromEntries(
Object.entries(again.attributes).filter(([, value]) => value !== undefined),
);
prepared = {
...prepared,
name: again.name,
kind: again.kind,
startTimeMs,
attributes: { ...prepared.attributes, ...defined },
};
changed();
},
narrow(next) {
const narrowed = intersectCapture(actualCapture, next);
actualCapture = { ...narrowed, emit: actualCapture.emit };
actualData = capturedData(actualData, actualCapture);
const kept = (withoutDeclinedContent(prepared.attributes, actualCapture) ??
prepared.attributes) as Attributes;
prepared = {
...prepared,
attributes:
actualData.type === "activation"
? {
...kept,
"agent.trace.content.input": actualCapture.recordInputs,
"agent.trace.content.output": actualCapture.recordOutputs,
}
: kept,
};
const permitted = withoutDeclinedContent(enrichment, actualCapture) ?? enrichment;
for (const key of Object.keys(enrichment)) if (!(key in permitted)) delete enrichment[key];
if (!actualCapture.recordOutputs && terminalResult?.error !== undefined)
terminalResult = { ...terminalResult, error: undefined };
operation?.narrow(actualCapture);
for (const child of children.values()) child.narrow(actualCapture);
changed();
},
async release(result) {
if (finished) await closeChildren(result, result.failed === true || !input.durable);
else await finish(terminalOf(result));
},
record() {
return snapshotRecord(
{
version: 1,
finished,
terminal: terminalResult,
usage: totalUsage,
usageKeys: [...usageKeys],
attributes: { ...prepared.attributes, ...enrichment },
childSequence,
children: [...children.values()]
.filter((child) => !child.settled)
.map((child) => child.record()),
key,
identity,
data: actualData,
capture: actualCapture,
reference: retainedReference,
parent: parentReference,
startTimeMs,
attempt,
links: prepared.links,
},
serializer,
);
},
get parent() {
return parentReference;
},
get startTimeMs() {
return startTimeMs;
},
child(data, childKey, options) {
if (!parentKinds(data).includes(actualData.type))
throw new Error("The operation is not permitted in this trace scope.");
const name =
childKey === undefined
? ((input.durable ? semanticKey(data) : undefined) ?? `${data.type}:${childSequence++}`)
: `${data.type}:${segment(childKey)}`;
return child(data, `${key}/${name}`, options);
},
find(data) {
const name = semanticKey(data);
const found = name === undefined ? undefined : children.get(`${key}/${name}`);
return found === undefined || found.settled ? undefined : found;
},
get children() {
return [...children.values()].filter((next) => !next.settled);
},
type: actualData.type,
reference: retainedReference,
callId,
get capture() {
return actualCapture;
},
mcp: mcpLifecycle({
serializer,
...actualCapture,
write(attributes) {
const permitted = (withoutDeclinedContent(attributes, current()) ??
attributes) as Attributes;
Object.assign(enrichment, permitted);
if (operation !== undefined) applyAttributes(operation, permitted);
},
error(error, type) {
runtime.error(error, type);
},
}),
get finished() {
return finished;
},
get settled() {
return finished && [...children.values()].every((next) => next.settled);
},
run(execute, ceiling) {
if (finished) throw new Error("The trace scope has already finished.");
// The ceiling governs work inside this run, not what the operation already recorded.
const scoped = intersectCapture(
intersectCapture(actualCapture, ceiling),
telemetry.active()?.capture,
);
const delegation =
actualData.type === "tool" &&
(actualData.options.kind === "subagent-call" ||
actualData.options.kind === "remote-agent-call")
? actualData.options
: undefined;
const callback =
delegation === undefined
? execute
: () =>
withAgentHandoff(
{
caller: retainedReference,
conversationId: identity.conversationId,
parentRunId: identity.runId,
parentCallId: delegation.callId,
agentName: delegation.name,
capture: scoped,
},
execute,
);
return runTraceContext(
telemetry,
{ type: runtime.type, reference: retainedReference, capture: scoped, mcp: runtime.mcp },
callback,
host,
);
},
async complete(result = terminalResult ?? {}) {
if (finished) return;
await finish(terminalOf(result));
},
async usage(usage, callKey) {
if (callKey !== undefined && usageKeys.has(callKey)) return;
if (callKey !== undefined) usageKeys.add(callKey);
if (operation !== undefined) applyAttributes(operation, usageAttributes(usage));
totalUsage = {
inputTokens:
usage.inputTokens === undefined
? totalUsage?.inputTokens
: (totalUsage?.inputTokens ?? 0) + usage.inputTokens,
outputTokens:
usage.outputTokens === undefined
? totalUsage?.outputTokens
: (totalUsage?.outputTokens ?? 0) + usage.outputTokens,
costUsd:
usage.costUsd === undefined
? totalUsage?.costUsd
: (totalUsage?.costUsd ?? 0) + usage.costUsd,
};
await parent?.usage(usage, callKey);
},
turnContent(content) {
if (actualData.type !== "activation") return parent?.turnContent(content);
if (finished) return;
const attributes: Record<string, Attributes[string]> = {};
if (
content.input !== undefined &&
prepared.attributes["gen_ai.input.messages"] === undefined
)
attributes["gen_ai.input.messages"] = content.input;
if (content.output !== undefined) attributes["gen_ai.output.messages"] = content.output;
if (Object.keys(attributes).length > 0) runtime.update({ attributes });
},
error(error, errorType) {
terminalResult = {
...terminalResult,
failed: true,
error: current().recordOutputs
? error instanceof Error
? boundedTraceError(error)
: snapshotContent(error)
: undefined,
errorCode: errorType ?? (error instanceof Error ? error.name : undefined),
};
if (operation !== undefined) operation.fail(terminalResult.error, terminalResult.errorCode);
changed();
},
};
for (const saved of binding.children ?? [])
children.set(
saved.key,
await construct(
saved.identity,
intersectCapture(saved.capture, actualCapture),
saved.data,
runtime,
saved.attempt,
{ ...saved, deferred: true, executionContext: host },
onChange,
),
);
if (!finished && operation !== undefined && actualData.type === "step")
operation.addEvent("step.started", undefined, startTimeMs);
const inputMessages = prepared.attributes["gen_ai.input.messages"];
if (!finished && actualData.type === "model" && typeof inputMessages === "string")
parent?.turnContent({ input: inputMessages });
return runtime;
}
return {
/** Starts a turn tree. Durable turns reserve their IDs from `key`. */
start(facts: {
identity: ScopeIdentity;
key: string;
capture: CaptureDecision;
data: ScopeData;
parent?: TraceReference;
reference?: TraceReference;
startTimeMs?: number;
links?: readonly TraceLink[];
context?: ExecutionContext;
onChange?: () => Promise<void>;
}): Promise<LiveOperation> {
return construct(
facts.identity,
facts.capture,
facts.data,
undefined,
undefined,
{
key: facts.key,
parent: facts.parent,
reference: facts.reference,
sample: facts.reference !== undefined && facts.data.type === "activation",
startTimeMs: facts.startTimeMs,
links: facts.links,
executionContext: facts.context,
},
facts.onChange ?? (() => Promise.resolve()),
);
},
/** Rebuilds a tree from a checkpoint, or returns `undefined` for an unusable one. */
async restore(
snapshot: unknown,
options: {
capture?: CaptureDecision;
context?: ExecutionContext;
onChange?: () => Promise<void>;
} = {},
): Promise<LiveOperation | undefined> {
if (!validSnapshot(snapshot)) {
report(new Error("Invalid tracing checkpoint."), { phase: "restore" });
return undefined;
}
return construct(
snapshot.identity,
intersectCapture(snapshot.capture, options.capture),
snapshot.data,
undefined,
snapshot.attempt,
{ ...snapshot, deferred: true, executionContext: options.context },
options.onChange ?? (() => Promise.resolve()),
);
},
};
}