@zhin.js/agent 1.1.30 → 1.1.32

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":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAQpC,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAC/G,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEvF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2DAA2D;IAC3D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,kBAAkB,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,0BAA0B;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrG,kFAAkF;IAClF,QAAQ,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;QAAE,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtG,QAAQ,CAAC,cAAc,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1D,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,SAAS,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GACrB,QAAQ,CAAC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,GAC/D,QAAQ,CAAC;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GACjD,QAAQ,CAAC;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,CAAC;AACnE,0EAA0E;GACxE,QAAQ,CAAC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE9G,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC;QAC5B,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC,CAAC;CACJ;AAcD,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAgBhB,IAAI,EAAE,aAAa,EAAE,GAAG,GAAE,MAAM,MAAiB;IAe7D,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,mEAAmE;IACnE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,SAAgC,GAAG,kBAAkB;IAarF,uDAAuD;IACvD,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IASpD,IAAI,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAkB/B,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IA2G9B,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,GAAE,oBAA4C,GAAG,IAAI;IAMtE,QAAQ,IAAI,SAAS;CAwFtB;AAUD,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAKnD;AAeD,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD"}

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

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

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

package/lib/turn/execute-agent-turn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute-agent-turn.d.ts","sourceRoot":"","sources":["../../src/turn/execute-agent-turn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIlE,MAAM,WAAW,sBAAsB;IACrC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,WAAW,KACd,cAAc,CAAC,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAQ3E;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAqEtB"}
+{"version":3,"file":"execute-agent-turn.d.ts","sourceRoot":"","sources":["../../src/turn/execute-agent-turn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,wBAAwB,CAAC;AAC3E,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAKlE,MAAM,WAAW,sBAAsB;IACrC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,WAAW,KACd,cAAc,CAAC,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC,CAAC;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAQ3E;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,WAAW,CAAC,CA8EtB"}

package/lib/turn/execute-agent-turn.js

@@ -1,5 +1,6 @@
 import { TurnTerminalGate } from './turn-terminal.js';
 import { TurnJournalCommitError } from './journal-integrity.js';
+import { journalFeedOf } from './journal-feed.js';
 const emptyUsage = Object.freeze({
     prompt_tokens: 0,
     completion_tokens: 0,
@@ -14,6 +15,10 @@ export async function executeAgentTurn(turn, run, observe) {
     const gate = new TurnTerminalGate();
     let observedUsage = emptyUsage;
     let stream;
+    // When the journal carries a feed, observers read committed journal facts
+    // (including authority tool events) instead of the raw engine stream.
+    const feed = journalFeedOf(turn.ports.journal);
+    const closeFeed = feed?.open();
     try {
         stream = run(turn);
         while (true) {
@@ -27,16 +32,21 @@ export async function executeAgentTurn(turn, run, observe) {
             catch (error) {
                 return failedOutcome('turn_journal_commit_failed', error, true, observedUsage);
             }
-            if (!gate.accept(event))
-                continue;
-            if (event.type === 'usage')
-                observedUsage = addUsage(observedUsage, event.usage);
-            try {
-                await observe?.(event);
-            }
-            catch {
-                // Observers are projections. Once an event is accepted by the terminal
-                // gate, projection failure cannot rewrite the execution fact.
+            const committed = feed ? feed.drain() : [event];
+            for (const fact of committed) {
+                if (!gate.accept(fact))
+                    continue;
+                if (fact.type === 'usage')
+                    observedUsage = addUsage(observedUsage, fact.usage);
+                try {
+                    await observe?.(fact);
+                }
+                catch {
+                    // Observers are projections. Once an event is accepted by the terminal
+                    // gate, projection failure cannot rewrite the execution fact.
+                }
+                if (gate.terminal)
+                    break;
             }
             if (gate.terminal) {
                 try {
@@ -75,6 +85,7 @@ export async function executeAgentTurn(turn, run, observe) {
         return commitSyntheticTerminal(turn, gate, terminal, observedUsage);
     }
     finally {
+        closeFeed?.();
         try {
             await stream?.return(undefined);
         }

package/lib/turn/execute-agent-turn.js.map

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

package/lib/turn/inbound-media.d.ts

@@ -5,9 +5,14 @@
  * 策略（`ai.multimodal`）：
  * 每个输入媒体必须产生 accepted / derived / unsupported / rejected / failed
  * 之一；失败不得伪装成已经被模型识别的媒体占位。
+ *
+ * 当前模型收不了的媒体：音频先走 STT（`[语音转写]`）；配置了
+ * `ai.multimodal.perception` 时，图片 / 视频 / PDF 由感知模型描述后以
+ * untrusted 文本注入（`[图片描述]` 等），失败或超出单回合上限时保持原占位。
  */
 import { type MediaContentBlock, type ModelInputModality } from '@zhin.js/ai';
 import type { AudioTranscriptionPort } from '../media/media-types.js';
+import { type MediaPerceptionPort } from '../media/perception.js';
 import type { ReferencePort, TurnMedia } from './turn-ingress.js';
 export interface InboundMediaInjection {
     /** 挂到当前 turn UserMessage.media 的媒体块 */
@@ -21,12 +26,22 @@ export interface InboundMediaOutcome {
     readonly kind: TurnMedia['kind'];
     readonly status: 'accepted' | 'derived' | 'unsupported' | 'rejected' | 'failed';
     readonly code: string;
+    /** Where derived text came from (perception pre-pass); the text is untrusted external content. */
+    readonly provenance?: InboundMediaProvenance;
+}
+export interface InboundMediaProvenance {
+    readonly source: 'media_perception';
+    readonly provider: string;
+    readonly model: string;
+    readonly cached: boolean;
 }
 export interface ResolveTurnMediaOptions {
     readonly references?: ReferencePort;
     readonly signal?: AbortSignal;
     readonly providerInput?: readonly ModelInputModality[];
     readonly transcriber?: AudioTranscriptionPort;
+    /** `ai.multimodal.perception`: describes media the turn's model cannot take. Absent = placeholders. */
+    readonly perception?: MediaPerceptionPort;
 }
 export declare function resolveTurnMediaInjection(turnMedia: readonly TurnMedia[] | undefined, options?: ResolveTurnMediaOptions): Promise<InboundMediaInjection>;
 /**