@zhin.js/agent 1.1.31 → 1.1.33

package/lib/trace/turn-trace-registry.js

@@ -0,0 +1,62 @@
+const activeCollectors = new Map();
+const eventScopes = new WeakMap();
+/** Journal port that feeds the collector before delegating to the real journal. */
+export function createTracingJournal(journal, collector) {
+    return Object.freeze({
+        append(event) {
+            const scope = eventScopes.get(event);
+            const target = scope && scope.turnId !== collector.turnId
+                ? collector.child(scope.turnId, scope.sessionKey)
+                : collector;
+            try {
+                target.record(event);
+            }
+            catch {
+                // Tracing is a projection; it must never fail the turn.
+            }
+            return journal.append(event);
+        },
+    });
+}
+/** Journal port for a sub-agent turn: tags events with the child turn id. */
+export function createScopedTraceJournal(journal, scope) {
+    const frozen = Object.freeze({ turnId: scope.turnId, sessionKey: scope.sessionKey });
+    return Object.freeze({
+        append(event) {
+            if (!eventScopes.has(event))
+                eventScopes.set(event, frozen);
+            return journal.append(event);
+        },
+    });
+}
+/** Turn id a sub-agent journal tagged this event with, if any. */
+export function traceScopeTurnId(event) {
+    return eventScopes.get(event)?.turnId;
+}
+/** Makes a root collector reachable for trace notes until the returned release runs. */
+export function registerTurnTrace(collector) {
+    activeCollectors.set(collector.turnId, collector);
+    return () => {
+        if (activeCollectors.get(collector.turnId) === collector)
+            activeCollectors.delete(collector.turnId);
+    };
+}
+/**
+ * Records a non-event fact (budget extension, auto-continuation) on the turn
+ * with this id, including nested `<parent>:subagent:<n>` turns. No-op when
+ * the turn is not traced.
+ */
+export function noteTurnTrace(turnId, note) {
+    if (!turnId)
+        return;
+    const rootId = turnId.split(':subagent:')[0] ?? turnId;
+    const root = activeCollectors.get(rootId);
+    const target = root?.find(turnId) ?? (root && turnId !== rootId ? root.child(turnId) : undefined);
+    try {
+        target?.note(note);
+    }
+    catch {
+        // Projection only.
+    }
+}
+//# sourceMappingURL=turn-trace-registry.js.map

package/lib/trace/turn-trace-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-trace-registry.js","sourceRoot":"","sources":["../../src/trace/turn-trace-registry.ts"],"names":[],"mappings":"AAkBA,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA8B,CAAC;AAC/D,MAAM,WAAW,GAAG,IAAI,OAAO,EAAsB,CAAC;AAEtD,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAAC,OAAwB,EAAE,SAA6B;IAC1F,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,CAAC,KAAgB;YACrB,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACrC,MAAM,MAAM,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM;gBACvD,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,CAAC;gBACjD,CAAC,CAAC,SAAS,CAAC;YACd,IAAI,CAAC;gBACH,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,wDAAwD;YAC1D,CAAC;YACD,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,wBAAwB,CACtC,OAAwB,EACxB,KAAuD;IAEvD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;IACrF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,CAAC,KAAgB;YACrB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;gBAAE,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC5D,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,gBAAgB,CAAC,KAAgB;IAC/C,OAAO,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;AACxC,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAAC,SAA6B;IAC7D,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAClD,OAAO,GAAG,EAAE;QACV,IAAI,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,SAAS;YAAE,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACtG,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAA0B,EAAE,IAAmB;IAC3E,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IACvD,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClG,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,mBAAmB;IACrB,CAAC;AACH,CAAC"}

package/lib/trace/turn-trace-store.d.ts

@@ -0,0 +1,15 @@
+import { type TurnTrace } from './turn-trace.js';
+export declare const DEFAULT_TURN_TRACE_LIMIT = 50;
+export interface TurnTraceStore {
+    save(trace: TurnTrace): Promise<void>;
+    /** Oldest first. */
+    list(): Promise<readonly TurnTrace[]>;
+    latest(): Promise<TurnTrace | undefined>;
+    /** Exact turn id, or a unique prefix of one. */
+    find(turnId: string): Promise<TurnTrace | undefined>;
+}
+export declare function defaultTurnTraceFile(projectRoot: string): string;
+export declare function createFileTurnTraceStore(file: string, options?: Readonly<{
+    limit?: number;
+}>): TurnTraceStore;
+//# sourceMappingURL=turn-trace-store.d.ts.map

package/lib/trace/turn-trace-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-trace-store.d.ts","sourceRoot":"","sources":["../../src/trace/turn-trace-store.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErE,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,oBAAoB;IACpB,IAAI,IAAI,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IACtC,MAAM,IAAI,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;IACzC,gDAAgD;IAChD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;CACtD;AAOD,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GACzC,cAAc,CAoDhB"}

package/lib/trace/turn-trace-store.js

@@ -0,0 +1,67 @@
+/**
+ * Lightweight store of the most recent N TurnTraces in one JSON file
+ * (`data/agent-traces/recent.json`). Written by the running bot, read by
+ * `zhin trace`. Full persistence with retention is #728.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { TURN_TRACE_VERSION } from './turn-trace.js';
+export const DEFAULT_TURN_TRACE_LIMIT = 50;
+export function defaultTurnTraceFile(projectRoot) {
+    return join(projectRoot, 'data', 'agent-traces', 'recent.json');
+}
+export function createFileTurnTraceStore(file, options = {}) {
+    const limit = Number.isInteger(options.limit) && Number(options.limit) > 0
+        ? Number(options.limit)
+        : DEFAULT_TURN_TRACE_LIMIT;
+    let tail = Promise.resolve();
+    const read = async () => {
+        let raw;
+        try {
+            raw = await readFile(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed.traces) ? parsed.traces : [];
+        }
+        catch {
+            // A torn or hand-edited file must not break the bot or the CLI.
+            return [];
+        }
+    };
+    const write = async (traces) => {
+        await mkdir(dirname(file), { recursive: true });
+        const temporary = `${file}.${process.pid}.tmp`;
+        const body = { version: TURN_TRACE_VERSION, traces };
+        await writeFile(temporary, `${JSON.stringify(body)}\n`, 'utf8');
+        await rename(temporary, file);
+    };
+    return Object.freeze({
+        save(trace) {
+            const operation = tail.then(async () => {
+                const existing = (await read()).filter(item => item.turn_id !== trace.turn_id);
+                await write([...existing, trace].slice(-limit));
+            });
+            tail = operation.catch(() => undefined);
+            return operation;
+        },
+        list: read,
+        async latest() {
+            return (await read()).at(-1);
+        },
+        async find(turnId) {
+            const traces = await read();
+            const exact = traces.find(trace => trace.turn_id === turnId);
+            if (exact)
+                return exact;
+            const matches = traces.filter(trace => trace.turn_id.startsWith(turnId));
+            return matches.length === 1 ? matches[0] : undefined;
+        },
+    });
+}
+//# sourceMappingURL=turn-trace-store.js.map

package/lib/trace/turn-trace-store.js.map

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

package/lib/trace/turn-trace.d.ts

@@ -0,0 +1,147 @@
+/**
+ * TurnTrace — one readable, redacted record of what happened in a single
+ * Agent turn: who asked, every model call and its tokens, every tool call
+ * with an argument summary, duration and result size, approval denials,
+ * budget extensions, nested sub-agent turns and how the turn ended.
+ *
+ * The collector only folds TurnEvents (plus a few trace notes), so it never
+ * influences execution. Persisted JSON uses snake_case keys.
+ */
+import type { TurnEvent } from '../event/turn-event.js';
+import type { ContextBudgetReport } from './context-budget.js';
+export declare const TURN_TRACE_VERSION = 1;
+export type TurnTraceStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'budget_exceeded' | 'unknown';
+export type TurnTraceToolStatus = 'running' | 'ok' | 'failed' | 'denied' | 'cancelled';
+export interface TurnTracePrincipal {
+    readonly subject_id: string;
+    readonly display_name?: string;
+    readonly roles: readonly string[];
+    /** Initiator trust level (#726); every tool call in this trace ran under it. */
+    readonly trust_level?: string;
+}
+export interface TurnTraceModelCall {
+    readonly index: number;
+    readonly prompt_tokens: number;
+    readonly completion_tokens: number;
+    readonly total_tokens: number;
+    /** Prompt tokens served from the provider cache (#730). */
+    readonly cache_read_tokens?: number;
+    /** Completion tokens spent on reasoning (e.g. Gemini thoughtsTokenCount). */
+    readonly reasoning_tokens?: number;
+}
+export interface TurnTraceToolCall {
+    readonly tool_use_id: string;
+    readonly tool_name: string;
+    readonly args_summary: string;
+    readonly status: TurnTraceToolStatus;
+    /** Milliseconds since the turn started. */
+    readonly started_at_ms: number;
+    readonly duration_ms?: number;
+    /** Size of the tool output in characters (output itself is never stored). */
+    readonly result_size?: number;
+    readonly error?: string;
+    /** Policy that denied the call, for `denied`. */
+    readonly policy?: string;
+}
+export interface TurnTraceBudgetExtension {
+    readonly from: number;
+    readonly to: number;
+    readonly at_ms: number;
+}
+export interface TurnTraceSubagentTask {
+    readonly task_id: string;
+    readonly agent_name?: string;
+    readonly description: string;
+    readonly status: 'running' | 'ok' | 'error';
+    readonly result_summary?: string;
+}
+export interface TurnTraceTimelineEntry {
+    readonly at_ms: number;
+    readonly kind: string;
+    readonly detail: string;
+}
+export interface TurnTraceTermination {
+    readonly status: TurnTraceStatus;
+    readonly code?: string;
+    readonly reason?: string;
+}
+export interface TurnTrace {
+    readonly version: typeof TURN_TRACE_VERSION;
+    readonly turn_id: string;
+    readonly session_key: string;
+    readonly principal?: TurnTracePrincipal;
+    /** Epoch milliseconds. */
+    readonly started_at: number;
+    readonly ended_at?: number;
+    readonly duration_ms?: number;
+    readonly model_calls: readonly TurnTraceModelCall[];
+    readonly usage: Readonly<{
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    }>;
+    /** Estimated prompt cost by segment for the turn's first model request (#729). */
+    readonly context_budget?: ContextBudgetReport;
+    readonly tool_calls: readonly TurnTraceToolCall[];
+    readonly budget: Readonly<{
+        extensions: readonly TurnTraceBudgetExtension[];
+        continuations: number;
+    }>;
+    readonly subagent_tasks: readonly TurnTraceSubagentTask[];
+    /** Nested sub-agent turns (`<parent>:subagent:<n>`). */
+    readonly subagents: readonly TurnTrace[];
+    readonly timeline: readonly TurnTraceTimelineEntry[];
+    readonly termination: TurnTraceTermination;
+    /** Entries dropped because a bounded list was full. */
+    readonly dropped: number;
+}
+/** Facts that are not TurnEvents but belong in the trace. */
+export type TurnTraceNote = Readonly<{
+    kind: 'budget_extended';
+    from: number;
+    to: number;
+}> | Readonly<{
+    kind: 'continuation';
+    index: number;
+}> | Readonly<{
+    kind: 'context_budget';
+    report: ContextBudgetReport;
+}>
+/** How the turn was admitted behind other turns of its session (#725). */
+ | Readonly<{
+    kind: 'admission';
+    queued_ms: number;
+    merged_messages: number;
+    superseded_previous: boolean;
+}>;
+export interface TurnTraceInit {
+    readonly turnId: string;
+    readonly sessionKey: string;
+    readonly principal?: Readonly<{
+        subjectId: string;
+        displayName?: string;
+        roles: readonly string[];
+        trustLevel?: string;
+    }>;
+}
+/** Folds the events of one turn (and its sub-agent turns) into a TurnTrace. */
+export declare class TurnTraceCollector {
+    #private;
+    readonly turnId: string;
+    readonly sessionKey: string;
+    constructor(init: TurnTraceInit, now?: () => number);
+    get finished(): boolean;
+    /** Nested collector for a sub-agent turn; created on first use. */
+    child(turnId: string, sessionKey?: string): TurnTraceCollector;
+    /** Finds this collector or a nested one by turn id. */
+    find(turnId: string): TurnTraceCollector | undefined;
+    note(note: TurnTraceNote): void;
+    record(event: TurnEvent): void;
+    /** Closes the trace when the turn ended without a terminal event. */
+    finalize(fallback?: TurnTraceTermination): void;
+    snapshot(): TurnTrace;
+}
+export declare function summarizeArgs(args: unknown): string;
+/** Masks credentials that appear inline in free text (error messages, string args). */
+export declare function scrubSecrets(text: string): string;
+//# sourceMappingURL=turn-trace.d.ts.map

package/lib/trace/turn-trace.d.ts.map

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

package/lib/trace/turn-trace.js

@@ -0,0 +1,341 @@
+import { redactTraceValue } from '../plugin-runtime/agent-trace-runtime.js';
+export const TURN_TRACE_VERSION = 1;
+const MAX_TOOL_CALLS = 200;
+const MAX_TIMELINE_ENTRIES = 300;
+const MAX_SUBAGENTS = 20;
+const ARGS_SUMMARY_LENGTH = 200;
+const TEXT_SUMMARY_LENGTH = 300;
+/** Folds the events of one turn (and its sub-agent turns) into a TurnTrace. */
+export class TurnTraceCollector {
+    turnId;
+    sessionKey;
+    #principal;
+    #now;
+    #startedAt;
+    #endedAt;
+    #termination = { status: 'running' };
+    #modelCalls = [];
+    #toolCalls = new Map();
+    #extensions = [];
+    #continuations = 0;
+    #contextBudget;
+    #subagentTasks = new Map();
+    #children = new Map();
+    #timeline = [];
+    #dropped = 0;
+    constructor(init, now = Date.now) {
+        this.turnId = init.turnId;
+        this.sessionKey = init.sessionKey;
+        this.#now = now;
+        this.#startedAt = now();
+        if (init.principal) {
+            this.#principal = Object.freeze({
+                subject_id: init.principal.subjectId,
+                ...(init.principal.displayName ? { display_name: init.principal.displayName } : {}),
+                roles: Object.freeze([...init.principal.roles]),
+                ...(init.principal.trustLevel ? { trust_level: init.principal.trustLevel } : {}),
+            });
+        }
+    }
+    get finished() {
+        return this.#endedAt !== undefined;
+    }
+    /** Nested collector for a sub-agent turn; created on first use. */
+    child(turnId, sessionKey = `${this.sessionKey}#subagent`) {
+        const existing = this.#children.get(turnId);
+        if (existing)
+            return existing;
+        const created = new TurnTraceCollector({ turnId, sessionKey, principal: this.#principalInit() }, this.#now);
+        if (this.#children.size >= MAX_SUBAGENTS) {
+            this.#dropped += 1;
+            return created;
+        }
+        this.#children.set(turnId, created);
+        this.#addTimeline('subagent_turn', turnId);
+        return created;
+    }
+    /** Finds this collector or a nested one by turn id. */
+    find(turnId) {
+        if (turnId === this.turnId)
+            return this;
+        for (const child of this.#children.values()) {
+            const found = child.find(turnId);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    note(note) {
+        const at = this.#elapsed();
+        if (note.kind === 'budget_extended') {
+            this.#extensions.push(Object.freeze({ from: note.from, to: note.to, at_ms: at }));
+            this.#addTimeline('budget_extended', `${note.from} → ${note.to} steps`);
+        }
+        else if (note.kind === 'context_budget') {
+            // Keep the first request's report: it is the fixed cost of the turn.
+            if (this.#contextBudget)
+                return;
+            this.#contextBudget = note.report;
+            this.#addTimeline('context_budget', `~${note.report.total_tokens} tokens (fixed ~${note.report.fixed_tokens})`);
+        }
+        else if (note.kind === 'continuation') {
+            this.#continuations = Math.max(this.#continuations, note.index);
+            this.#addTimeline('continuation', `#${note.index}`);
+        }
+        else {
+            this.#addTimeline('admission', describeAdmission(note));
+        }
+    }
+    record(event) {
+        switch (event.type) {
+            case 'turn_start':
+            case 'chunk':
+            case 'thinking':
+                return;
+            case 'iteration_start':
+                this.#addTimeline('iteration', `${event.iteration}/${event.maxIterations}`);
+                return;
+            case 'usage': {
+                const call = Object.freeze({
+                    index: this.#modelCalls.length + 1,
+                    prompt_tokens: event.usage.promptTokens,
+                    completion_tokens: event.usage.completionTokens,
+                    total_tokens: event.usage.totalTokens,
+                    ...(event.usage.cacheReadTokens ? { cache_read_tokens: event.usage.cacheReadTokens } : {}),
+                    ...(event.usage.reasoningTokens ? { reasoning_tokens: event.usage.reasoningTokens } : {}),
+                });
+                this.#modelCalls.push(call);
+                this.#addTimeline('model_call', `#${call.index} in=${call.prompt_tokens} out=${call.completion_tokens}`);
+                return;
+            }
+            case 'tool_call':
+                this.#startTool(event.toolUseId, event.toolName, summarizeArgs(event.args));
+                this.#addTimeline('tool_call', `${event.toolName} ${summarizeArgs(event.args)}`);
+                return;
+            case 'tool_result': {
+                const tool = this.#tool(event.toolUseId, event.toolName);
+                if (!tool)
+                    return;
+                tool.status = 'ok';
+                tool.duration_ms = Math.round(event.durationMs);
+                tool.result_size = outputSize(event.output);
+                this.#addTimeline('tool_result', `${event.toolName} ok ${tool.duration_ms}ms ${tool.result_size} chars`);
+                return;
+            }
+            case 'tool_failed': {
+                const tool = this.#tool(event.toolUseId, event.toolName);
+                if (!tool)
+                    return;
+                tool.status = 'failed';
+                tool.duration_ms = Math.round(event.durationMs);
+                tool.error = summarizeText(event.error);
+                this.#addTimeline('tool_failed', `${event.toolName}: ${tool.error}`);
+                return;
+            }
+            case 'tool_denied': {
+                const tool = this.#tool(event.toolUseId, event.toolName);
+                if (!tool)
+                    return;
+                tool.status = 'denied';
+                tool.policy = event.policy;
+                tool.error = summarizeText(event.reason);
+                this.#addTimeline('tool_denied', `${event.toolName} (${event.policy}): ${tool.error}`);
+                return;
+            }
+            case 'tool_cancelled': {
+                const tool = this.#tool(event.toolUseId, event.toolName);
+                if (!tool)
+                    return;
+                tool.status = 'cancelled';
+                tool.duration_ms = Math.round(event.durationMs);
+                tool.error = summarizeText(event.reason);
+                this.#addTimeline('tool_cancelled', `${event.toolName}: ${tool.error}`);
+                return;
+            }
+            case 'subagent_start':
+                this.#subagentTasks.set(event.taskId, Object.freeze({
+                    task_id: event.taskId,
+                    ...(event.agentName ? { agent_name: event.agentName } : {}),
+                    description: summarizeText(event.description),
+                    status: 'running',
+                }));
+                this.#addTimeline('subagent_start', `${event.taskId} ${summarizeText(event.description, 80)}`);
+                return;
+            case 'subagent_progress':
+                this.#addTimeline('subagent_progress', `${event.taskId} ${summarizeText(event.summary, 80)}`);
+                return;
+            case 'subagent_end': {
+                const task = this.#subagentTasks.get(event.taskId);
+                this.#subagentTasks.set(event.taskId, Object.freeze({
+                    task_id: event.taskId,
+                    ...(task?.agent_name ? { agent_name: task.agent_name } : {}),
+                    description: task?.description ?? '',
+                    status: event.status,
+                    ...(event.result ? { result_summary: summarizeText(event.result) } : {}),
+                }));
+                this.#addTimeline('subagent_end', `${event.taskId} ${event.status}`);
+                return;
+            }
+            case 'turn_end':
+                this.#finish({ status: 'completed' });
+                return;
+            case 'error':
+                this.#finish({
+                    status: 'failed',
+                    ...(event.code ? { code: event.code } : {}),
+                    reason: summarizeText(event.error?.message ?? String(event.error)),
+                });
+                return;
+            case 'turn_cancelled':
+                this.#finish({ status: 'cancelled', code: event.code, reason: summarizeText(event.reason) });
+                return;
+            case 'budget_exceeded':
+                this.#finish({ status: 'budget_exceeded', code: event.budget });
+                return;
+            default:
+                this.#addTimeline(event.type, summarizeText(JSON.stringify(redactTraceValue(withoutType(event))), 120));
+        }
+    }
+    /** Closes the trace when the turn ended without a terminal event. */
+    finalize(fallback = { status: 'unknown' }) {
+        for (const child of this.#children.values())
+            child.finalize();
+        if (this.finished)
+            return;
+        this.#finish(fallback);
+    }
+    snapshot() {
+        const usage = this.#modelCalls.reduce((total, call) => ({
+            prompt_tokens: total.prompt_tokens + call.prompt_tokens,
+            completion_tokens: total.completion_tokens + call.completion_tokens,
+            total_tokens: total.total_tokens + call.total_tokens,
+        }), { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 });
+        return Object.freeze({
+            version: TURN_TRACE_VERSION,
+            turn_id: this.turnId,
+            session_key: this.sessionKey,
+            ...(this.#principal ? { principal: this.#principal } : {}),
+            started_at: this.#startedAt,
+            ...(this.#endedAt !== undefined
+                ? { ended_at: this.#endedAt, duration_ms: this.#endedAt - this.#startedAt }
+                : {}),
+            model_calls: Object.freeze([...this.#modelCalls]),
+            usage: Object.freeze(usage),
+            ...(this.#contextBudget ? { context_budget: this.#contextBudget } : {}),
+            tool_calls: Object.freeze([...this.#toolCalls.values()].map(tool => Object.freeze({ ...tool }))),
+            budget: Object.freeze({
+                extensions: Object.freeze([...this.#extensions]),
+                continuations: this.#continuations,
+            }),
+            subagent_tasks: Object.freeze([...this.#subagentTasks.values()]),
+            subagents: Object.freeze([...this.#children.values()].map(child => child.snapshot())),
+            timeline: Object.freeze([...this.#timeline]),
+            termination: Object.freeze({ ...this.#termination }),
+            dropped: this.#dropped,
+        });
+    }
+    #startTool(toolUseId, toolName, argsSummary) {
+        if (this.#toolCalls.size >= MAX_TOOL_CALLS && !this.#toolCalls.has(toolUseId)) {
+            this.#dropped += 1;
+            return undefined;
+        }
+        const existing = this.#toolCalls.get(toolUseId);
+        if (existing)
+            return existing;
+        const created = {
+            tool_use_id: toolUseId,
+            tool_name: toolName,
+            args_summary: argsSummary,
+            status: 'running',
+            started_at_ms: this.#elapsed(),
+        };
+        this.#toolCalls.set(toolUseId, created);
+        return created;
+    }
+    /** Result/denial events may arrive without a prior tool_call (e.g. pre-call denial). */
+    #tool(toolUseId, toolName) {
+        return this.#toolCalls.get(toolUseId) ?? this.#startTool(toolUseId, toolName, '');
+    }
+    #finish(termination) {
+        if (this.finished)
+            return;
+        this.#termination = Object.freeze(termination);
+        this.#endedAt = this.#now();
+        for (const tool of this.#toolCalls.values()) {
+            if (tool.status === 'running')
+                tool.status = 'cancelled';
+        }
+        this.#addTimeline('end', [termination.status, termination.code, termination.reason].filter(Boolean).join(' '));
+    }
+    #addTimeline(kind, detail) {
+        if (this.#timeline.length >= MAX_TIMELINE_ENTRIES) {
+            this.#dropped += 1;
+            return;
+        }
+        this.#timeline.push(Object.freeze({ at_ms: this.#elapsed(), kind, detail }));
+    }
+    #elapsed() {
+        return Math.max(0, this.#now() - this.#startedAt);
+    }
+    #principalInit() {
+        if (!this.#principal)
+            return undefined;
+        return {
+            subjectId: this.#principal.subject_id,
+            ...(this.#principal.display_name ? { displayName: this.#principal.display_name } : {}),
+            roles: this.#principal.roles,
+            ...(this.#principal.trust_level ? { trustLevel: this.#principal.trust_level } : {}),
+        };
+    }
+}
+/** Redacted, single-line, length-bounded summary of tool arguments. */
+function describeAdmission(note) {
+    const parts = [`queued ${Math.round(note.queued_ms)}ms`];
+    if (note.merged_messages > 1)
+        parts.push(`merged ${note.merged_messages} messages`);
+    if (note.superseded_previous)
+        parts.push('replaced the sender\'s unanswered turn');
+    return parts.join(', ');
+}
+export function summarizeArgs(args) {
+    if (args == null)
+        return '';
+    const redacted = redactTraceValue(args);
+    const text = typeof redacted === 'string' ? redacted : JSON.stringify(redacted);
+    return clip(scrubSecrets(text ?? ''), ARGS_SUMMARY_LENGTH);
+}
+function summarizeText(value, max = TEXT_SUMMARY_LENGTH) {
+    const redacted = redactTraceValue(value);
+    const text = typeof redacted === 'string' ? redacted : JSON.stringify(redacted) ?? '';
+    return clip(scrubSecrets(text.replace(/\s+/g, ' ').trim()), max);
+}
+const INLINE_SECRET_RULES = [
+    [/\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, '$1 [redacted]'],
+    [/\b(?:sk|pk|rk)-[A-Za-z0-9_-]{12,}/g, '[redacted]'],
+    [/\b(?:ghp|gho|ghs|github_pat|xox[abpr])[_-][A-Za-z0-9_-]{12,}/g, '[redacted]'],
+    [/("?(?:api[_-]?key|access[_-]?token|refresh[_-]?token|password|secret)"?\s*[:=]\s*"?)[^"\s,}]+/gi, '$1[redacted]'],
+];
+/** Masks credentials that appear inline in free text (error messages, string args). */
+export function scrubSecrets(text) {
+    return INLINE_SECRET_RULES.reduce((current, [pattern, replacement]) => current.replace(pattern, replacement), text);
+}
+function outputSize(output) {
+    if (output == null)
+        return 0;
+    if (typeof output === 'string')
+        return output.length;
+    try {
+        return JSON.stringify(output)?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function clip(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+function withoutType(event) {
+    const { type: _type, ...rest } = event;
+    return rest;
+}
+//# sourceMappingURL=turn-trace.js.map