@zhin.js/agent 1.1.31 → 1.1.33

package/lib/trace/context-budget.js

@@ -0,0 +1,102 @@
+/**
+ * Context budget report (#729, M2.1): how many prompt tokens each part of a
+ * turn's first model request costs, so context work is driven by data.
+ *
+ * Numbers are estimates (CJK ≈ 1 token per character, other text ≈ 4
+ * characters per token), computed from what the harness actually sends. The
+ * provider's real `prompt_tokens` stays in the trace's model calls for
+ * comparison. Only sizes are kept; prompt text never enters the report.
+ */
+import { estimateAgentMessagesTokens } from '@zhin.js/ai';
+import { estimatePromptTokens } from '../prompt/estimate-tokens.js';
+import { AGENT_CATALOG_HEADING, DEFERRED_TOOL_INDEX_HEADING, SKILL_CATALOG_HEADING } from '../skill/capability-catalog.js';
+/** Prompt segments, in the order the report lists them. */
+export const CONTEXT_BUDGET_SEGMENTS = [
+    'system',
+    'tool_schemas',
+    'tool_index',
+    'skill_catalog',
+    'agent_catalog',
+    'active_skills',
+    'memory',
+    'bootstrap',
+    'history',
+    'user',
+];
+/** Segments that are paid on every request regardless of the conversation. */
+export const FIXED_CONTEXT_SEGMENTS = new Set([
+    'system',
+    'tool_schemas',
+    'tool_index',
+    'skill_catalog',
+    'agent_catalog',
+    'memory',
+    'bootstrap',
+]);
+export { estimatePromptTokens };
+const SECTION_SEGMENT = {
+    '§8_skills': 'skill_catalog',
+    '§5e_memory_instructions': 'memory',
+    '§11_bootstrap': 'bootstrap',
+};
+function toolSchemaTokens(tools) {
+    return tools.reduce((sum, tool) => sum + estimatePromptTokens(JSON.stringify({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    })), 0);
+}
+/** Text of the block that starts at `heading` and runs to the next `## ` heading. */
+function headedBlock(text, heading) {
+    const start = text.indexOf(heading);
+    if (start < 0)
+        return '';
+    const next = text.indexOf('\n## ', start + heading.length);
+    return text.slice(start, next < 0 ? text.length : next);
+}
+function sectionTokens(section) {
+    return section.approxTokens ?? Math.ceil(section.approxChars / 4);
+}
+export function buildContextBudgetReport(input) {
+    const systemTokens = estimatePromptTokens(input.systemPrompt);
+    const sections = (input.sections ?? [])
+        .map((section) => Object.freeze({ id: section.id, tokens: sectionTokens(section) }))
+        .sort((left, right) => right.tokens - left.tokens);
+    const segments = Object.fromEntries(CONTEXT_BUDGET_SEGMENTS.map((segment) => [segment, 0]));
+    for (const section of sections) {
+        const segment = SECTION_SEGMENT[section.id];
+        if (segment)
+            segments[segment] += section.tokens;
+    }
+    // The plugin runtime renders skill/agent catalogs into the bootstrap block.
+    const bootstrap = input.bootstrapContext ?? '';
+    if (bootstrap && segments.bootstrap > 0) {
+        const skillCatalog = estimatePromptTokens(headedBlock(bootstrap, SKILL_CATALOG_HEADING));
+        const agentCatalog = estimatePromptTokens(headedBlock(bootstrap, AGENT_CATALOG_HEADING));
+        const attributed = Math.min(segments.bootstrap, skillCatalog + agentCatalog);
+        segments.skill_catalog += Math.min(skillCatalog, attributed);
+        segments.agent_catalog += attributed - Math.min(skillCatalog, attributed);
+        segments.bootstrap -= attributed;
+    }
+    // The deferred tool index is appended to the system prompt after assembly.
+    segments.tool_index = estimatePromptTokens(headedBlock(input.systemPrompt, DEFERRED_TOOL_INDEX_HEADING));
+    const attributedSystem = segments.tool_index + segments.skill_catalog + segments.agent_catalog + segments.memory + segments.bootstrap;
+    segments.system = Math.max(0, systemTokens - attributedSystem);
+    segments.tool_schemas = toolSchemaTokens(input.loadedTools);
+    segments.history = estimateAgentMessagesTokens([...input.historyMessages]);
+    const userTokens = estimateAgentMessagesTokens([...input.userMessages]);
+    segments.active_skills = Math.min(estimatePromptTokens(input.activeSkillsContext ?? ''), userTokens);
+    segments.user = userTokens - segments.active_skills;
+    const total = CONTEXT_BUDGET_SEGMENTS.reduce((sum, segment) => sum + segments[segment], 0);
+    const fixed = CONTEXT_BUDGET_SEGMENTS
+        .filter((segment) => FIXED_CONTEXT_SEGMENTS.has(segment))
+        .reduce((sum, segment) => sum + segments[segment], 0);
+    return Object.freeze({
+        total_tokens: total,
+        fixed_tokens: fixed,
+        segments: Object.freeze(segments),
+        sections: Object.freeze(sections),
+        tools: Object.freeze({ loaded: input.loadedTools.length, deferred: input.deferredToolCount }),
+    });
+}
+//# sourceMappingURL=context-budget.js.map

package/lib/trace/context-budget.js.map

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

package/lib/trace/index.d.ts

@@ -0,0 +1,12 @@
+export { TURN_TRACE_VERSION, TurnTraceCollector, summarizeArgs, scrubSecrets, } from './turn-trace.js';
+export type { TurnTrace, TurnTraceInit, TurnTraceNote, TurnTraceStatus, TurnTraceToolStatus, TurnTracePrincipal, TurnTraceModelCall, TurnTraceToolCall, TurnTraceBudgetExtension, TurnTraceSubagentTask, TurnTraceTimelineEntry, TurnTraceTermination, } from './turn-trace.js';
+export { createTracingJournal, createScopedTraceJournal, registerTurnTrace, noteTurnTrace, } from './turn-trace-registry.js';
+export { DEFAULT_TURN_TRACE_LIMIT, createFileTurnTraceStore, defaultTurnTraceFile, } from './turn-trace-store.js';
+export type { TurnTraceStore } from './turn-trace-store.js';
+export { DEFAULT_TRACE_MAX_BYTES, DEFAULT_TRACE_RETENTION_DAYS, createTurnTraceArchive, dayKey, defaultTurnTraceDir, redactStrings, resolveTraceArchiveOptions, } from './turn-trace-archive.js';
+export type { TurnTraceArchive, TurnTraceArchiveOptions, TurnTraceQuery, TurnTraceSessionSummary, } from './turn-trace-archive.js';
+export { formatTurnTrace, formatTurnTraceList } from './turn-trace-format.js';
+export type { FormatTurnTraceOptions } from './turn-trace-format.js';
+export { CONTEXT_BUDGET_SEGMENTS, FIXED_CONTEXT_SEGMENTS, buildContextBudgetReport, estimatePromptTokens, } from './context-budget.js';
+export type { ContextBudgetReport, ContextBudgetSection, ContextBudgetSegment, ContextBudgetInput, } from './context-budget.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/trace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,aAAa,GACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,sBAAsB,EACtB,MAAM,EACN,mBAAmB,EACnB,aAAa,EACb,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,cAAc,EACd,uBAAuB,GACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/lib/trace/index.js

@@ -0,0 +1,7 @@
+export { TURN_TRACE_VERSION, TurnTraceCollector, summarizeArgs, scrubSecrets, } from './turn-trace.js';
+export { createTracingJournal, createScopedTraceJournal, registerTurnTrace, noteTurnTrace, } from './turn-trace-registry.js';
+export { DEFAULT_TURN_TRACE_LIMIT, createFileTurnTraceStore, defaultTurnTraceFile, } from './turn-trace-store.js';
+export { DEFAULT_TRACE_MAX_BYTES, DEFAULT_TRACE_RETENTION_DAYS, createTurnTraceArchive, dayKey, defaultTurnTraceDir, redactStrings, resolveTraceArchiveOptions, } from './turn-trace-archive.js';
+export { formatTurnTrace, formatTurnTraceList } from './turn-trace-format.js';
+export { CONTEXT_BUDGET_SEGMENTS, FIXED_CONTEXT_SEGMENTS, buildContextBudgetReport, estimatePromptTokens, } from './context-budget.js';
+//# sourceMappingURL=index.js.map

package/lib/trace/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AAezB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,iBAAiB,EACjB,aAAa,GACd,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,sBAAsB,EACtB,MAAM,EACN,mBAAmB,EACnB,aAAa,EACb,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AAOjC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE9E,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,49 @@
+import { type TurnTrace } from './turn-trace.js';
+import type { TurnTraceStore } from './turn-trace-store.js';
+export declare const DEFAULT_TRACE_RETENTION_DAYS = 7;
+export declare const DEFAULT_TRACE_MAX_BYTES: number;
+export interface TurnTraceQuery {
+    /** Exact session key. */
+    readonly sessionKey?: string;
+    /** Epoch ms, inclusive, on `started_at`. */
+    readonly since?: number;
+    /** Epoch ms, exclusive, on `started_at`. */
+    readonly until?: number;
+    /** Newest N matching traces (returned oldest first). */
+    readonly limit?: number;
+}
+export interface TurnTraceSessionSummary {
+    readonly session_key: string;
+    readonly turns: number;
+    readonly first_started_at: number;
+    readonly last_started_at: number;
+    readonly last_status: string;
+    readonly total_tokens: number;
+}
+export interface TurnTraceArchive extends TurnTraceStore {
+    query(query?: TurnTraceQuery): Promise<readonly TurnTrace[]>;
+    sessions(query?: Omit<TurnTraceQuery, 'sessionKey'>): Promise<readonly TurnTraceSessionSummary[]>;
+    /** Delete day files past retention, then oldest days until under the size cap. Returns deleted file names. */
+    prune(): Promise<readonly string[]>;
+}
+export interface TurnTraceArchiveOptions {
+    readonly retentionDays?: number;
+    readonly maxBytes?: number;
+    /** Exact values masked on write (default: secret-looking environment variables). */
+    readonly secrets?: readonly string[];
+    readonly now?: () => number;
+    /** Legacy recent-N file read as a fallback (traces not yet in the archive). */
+    readonly legacyFile?: string;
+}
+export declare function defaultTurnTraceDir(projectRoot: string): string;
+export declare function createTurnTraceArchive(dir: string, options?: TurnTraceArchiveOptions): TurnTraceArchive;
+/** UTC day key `YYYY-MM-DD` for an epoch ms. */
+export declare function dayKey(epochMs: number): string;
+/** Second redaction pass on write: inline credential patterns and exact secret values in every string. */
+export declare function redactStrings<T>(value: T, secrets?: readonly string[]): T;
+/**
+ * Retention / size overrides from the environment:
+ * `ZHIN_TRACE_RETENTION_DAYS` and `ZHIN_TRACE_MAX_MB`.
+ */
+export declare function resolveTraceArchiveOptions(env?: Readonly<Record<string, string | undefined>>): Pick<TurnTraceArchiveOptions, 'retentionDays' | 'maxBytes'>;
+//# sourceMappingURL=turn-trace-archive.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"turn-trace-archive.d.ts","sourceRoot":"","sources":["../../src/trace/turn-trace-archive.ts"],"names":[],"mappings":"AAYA,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAKxD,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,KAAK,CAAC,KAAK,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAAC;IAClG,8GAA8G;IAC9G,KAAK,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CAgJ3G;AAED,gDAAgD;AAChD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,0GAA0G;AAC1G,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,GAAE,SAAS,MAAM,EAAO,GAAG,CAAC,CAc7E;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAAG,IAAI,CAAC,uBAAuB,EAAE,eAAe,GAAG,UAAU,CAAC,CAOvK"}

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

@@ -0,0 +1,208 @@
+/**
+ * Persistent TurnTrace archive (#728 M1.2): one JSONL file per UTC day under
+ * `data/agent-traces/`, with a retention period (default 7 days), a total
+ * size cap, and a redaction pass on write. Written by the running bot; read by
+ * `zhin trace` and the Console trace page, so nobody has to open bot.db.
+ *
+ * It implements {@link TurnTraceStore}, so it drops in where the recent-N
+ * `recent.json` store was used. That legacy file is still read as a fallback.
+ */
+import { appendFile, mkdir, readdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { collectEnvironmentSecrets } from '../security/outbound-leak-guard.js';
+import { scrubSecrets } from './turn-trace.js';
+export const DEFAULT_TRACE_RETENTION_DAYS = 7;
+export const DEFAULT_TRACE_MAX_BYTES = 64 * 1024 * 1024;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const PRUNE_INTERVAL_MS = 60 * 60 * 1000;
+const DAY_FILE = /^(\d{4}-\d{2}-\d{2})\.jsonl$/;
+export function defaultTurnTraceDir(projectRoot) {
+    return join(projectRoot, 'data', 'agent-traces');
+}
+export function createTurnTraceArchive(dir, options = {}) {
+    const retentionDays = positive(options.retentionDays, DEFAULT_TRACE_RETENTION_DAYS);
+    const maxBytes = positive(options.maxBytes, DEFAULT_TRACE_MAX_BYTES);
+    const now = options.now ?? Date.now;
+    const secrets = [...(options.secrets ?? collectEnvironmentSecrets())].filter(Boolean).sort((a, b) => b.length - a.length);
+    let tail = Promise.resolve();
+    let lastPrune = Number.NEGATIVE_INFINITY;
+    const serialize = (operation) => {
+        const next = tail.then(operation);
+        tail = next.catch(() => undefined);
+        return next;
+    };
+    const dayFiles = async () => {
+        try {
+            return (await readdir(dir)).filter((name) => DAY_FILE.test(name)).sort();
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    };
+    const readDay = async (name) => {
+        let raw;
+        try {
+            raw = await readFile(join(dir, name), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const traces = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed && typeof parsed.turn_id === 'string')
+                    traces.push(parsed);
+            }
+            catch {
+                // A torn last line (crash mid-append) must not hide the rest of the day.
+            }
+        }
+        return traces;
+    };
+    const readLegacy = async () => {
+        if (!options.legacyFile)
+            return [];
+        try {
+            const parsed = JSON.parse(await readFile(options.legacyFile, 'utf8'));
+            return Array.isArray(parsed.traces) ? parsed.traces : [];
+        }
+        catch {
+            return [];
+        }
+    };
+    /** All traces oldest first; a re-saved turn keeps its latest record. */
+    const readAll = async (days) => {
+        const byId = new Map();
+        for (const trace of await readLegacy())
+            byId.set(trace.turn_id, trace);
+        for (const name of days ?? await dayFiles()) {
+            for (const trace of await readDay(name)) {
+                byId.delete(trace.turn_id);
+                byId.set(trace.turn_id, trace);
+            }
+        }
+        return [...byId.values()].sort((a, b) => a.started_at - b.started_at);
+    };
+    const query = async (q = {}) => {
+        const sinceDay = q.since === undefined ? undefined : dayKey(q.since);
+        const untilDay = q.until === undefined ? undefined : dayKey(q.until);
+        const days = (await dayFiles()).filter((name) => {
+            const day = name.slice(0, 10);
+            return (sinceDay === undefined || day >= sinceDay) && (untilDay === undefined || day <= untilDay);
+        });
+        const matching = (await readAll(days)).filter((trace) => (q.sessionKey === undefined || trace.session_key === q.sessionKey)
+            && (q.since === undefined || trace.started_at >= q.since)
+            && (q.until === undefined || trace.started_at < q.until));
+        const limit = positive(q.limit, Number.POSITIVE_INFINITY);
+        return Number.isFinite(limit) ? matching.slice(-limit) : matching;
+    };
+    const prune = () => serialize(async () => {
+        lastPrune = now();
+        const deleted = [];
+        const cutoff = dayKey(now() - retentionDays * DAY_MS);
+        const files = await dayFiles();
+        const kept = [];
+        for (const name of files) {
+            if (name.slice(0, 10) < cutoff) {
+                await rm(join(dir, name), { force: true });
+                deleted.push(name);
+            }
+            else {
+                kept.push({ name, size: (await stat(join(dir, name)).catch(() => ({ size: 0 }))).size });
+            }
+        }
+        let total = kept.reduce((sum, file) => sum + file.size, 0);
+        // Never delete today's file for size: it is the one being written.
+        while (total > maxBytes && kept.length > 1) {
+            const oldest = kept.shift();
+            await rm(join(dir, oldest.name), { force: true });
+            deleted.push(oldest.name);
+            total -= oldest.size;
+        }
+        return deleted;
+    });
+    return Object.freeze({
+        async save(trace) {
+            await serialize(async () => {
+                await mkdir(dir, { recursive: true });
+                const line = JSON.stringify(redactStrings(trace, secrets));
+                await appendFile(join(dir, `${dayKey(trace.started_at || now())}.jsonl`), `${line}\n`, 'utf8');
+            });
+            if (now() - lastPrune >= PRUNE_INTERVAL_MS)
+                await prune();
+        },
+        list: () => query(),
+        async latest() {
+            return (await query()).at(-1);
+        },
+        async find(turnId) {
+            const traces = await query();
+            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;
+        },
+        query,
+        async sessions(q = {}) {
+            const bySession = new Map();
+            for (const trace of await query(q)) {
+                const previous = bySession.get(trace.session_key);
+                bySession.set(trace.session_key, {
+                    session_key: trace.session_key,
+                    turns: (previous?.turns ?? 0) + 1,
+                    first_started_at: previous?.first_started_at ?? trace.started_at,
+                    last_started_at: trace.started_at,
+                    last_status: trace.termination?.status ?? 'unknown',
+                    total_tokens: (previous?.total_tokens ?? 0) + (trace.usage?.total_tokens ?? 0),
+                });
+            }
+            return [...bySession.values()].sort((a, b) => b.last_started_at - a.last_started_at);
+        },
+        prune,
+    });
+}
+/** UTC day key `YYYY-MM-DD` for an epoch ms. */
+export function dayKey(epochMs) {
+    return new Date(epochMs).toISOString().slice(0, 10);
+}
+/** Second redaction pass on write: inline credential patterns and exact secret values in every string. */
+export function redactStrings(value, secrets = []) {
+    const visit = (item) => {
+        if (typeof item === 'string') {
+            let text = scrubSecrets(item);
+            for (const secret of secrets)
+                if (text.includes(secret))
+                    text = text.split(secret).join('[redacted]');
+            return text;
+        }
+        if (Array.isArray(item))
+            return item.map(visit);
+        if (item && typeof item === 'object') {
+            return Object.fromEntries(Object.entries(item).map(([key, entry]) => [key, visit(entry)]));
+        }
+        return item;
+    };
+    return visit(value);
+}
+/**
+ * Retention / size overrides from the environment:
+ * `ZHIN_TRACE_RETENTION_DAYS` and `ZHIN_TRACE_MAX_MB`.
+ */
+export function resolveTraceArchiveOptions(env = process.env) {
+    const days = Number(env.ZHIN_TRACE_RETENTION_DAYS);
+    const mb = Number(env.ZHIN_TRACE_MAX_MB);
+    return {
+        ...(Number.isFinite(days) && days > 0 ? { retentionDays: days } : {}),
+        ...(Number.isFinite(mb) && mb > 0 ? { maxBytes: Math.round(mb * 1024 * 1024) } : {}),
+    };
+}
+function positive(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+//# sourceMappingURL=turn-trace-archive.js.map

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

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

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

@@ -0,0 +1,10 @@
+/** Human-readable terminal rendering of a TurnTrace for `zhin trace`. */
+import type { TurnTrace } from './turn-trace.js';
+export interface FormatTurnTraceOptions {
+    /** Include the chronological timeline (default true). */
+    readonly timeline?: boolean;
+}
+export declare function formatTurnTrace(trace: TurnTrace, options?: FormatTurnTraceOptions): string;
+/** One line per trace, newest last. */
+export declare function formatTurnTraceList(traces: readonly TurnTrace[]): string;
+//# sourceMappingURL=turn-trace-format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"turn-trace-format.d.ts","sourceRoot":"","sources":["../../src/trace/turn-trace-format.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,KAAK,EAAE,SAAS,EAAqB,MAAM,iBAAiB,CAAC;AAoBpE,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAE9F;AAED,uCAAuC;AACvC,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAUxE"}

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

@@ -0,0 +1,132 @@
+import { CONTEXT_BUDGET_SEGMENTS } from './context-budget.js';
+const STATUS_LABEL = {
+    running: '进行中',
+    completed: '完成',
+    failed: '失败',
+    cancelled: '已取消',
+    budget_exceeded: '超出预算',
+    unknown: '未知',
+};
+const TOOL_MARK = {
+    running: '…',
+    ok: '✓',
+    failed: '✗',
+    denied: '⊘',
+    cancelled: '-',
+};
+export function formatTurnTrace(trace, options = {}) {
+    return renderTrace(trace, '', options.timeline ?? true).join('\n');
+}
+/** One line per trace, newest last. */
+export function formatTurnTraceList(traces) {
+    if (traces.length === 0)
+        return '还没有记录到任何回合。';
+    return traces.map(trace => [
+        new Date(trace.started_at).toLocaleString(),
+        STATUS_LABEL[trace.termination.status],
+        trace.turn_id,
+        trace.session_key,
+        `${trace.tool_calls.length} tools`,
+        `${trace.usage.total_tokens} tokens`,
+    ].join('  ')).join('\n');
+}
+function renderTrace(trace, indent, withTimeline) {
+    const lines = [];
+    const termination = trace.termination;
+    const failingTool = trace.tool_calls.find(tool => tool.status === 'failed' || tool.status === 'denied');
+    lines.push(`${indent}回合 ${trace.turn_id}  [${STATUS_LABEL[termination.status]}]`);
+    lines.push(`${indent}  会话: ${trace.session_key}`);
+    if (trace.principal) {
+        const name = trace.principal.display_name ? ` (${trace.principal.display_name})` : '';
+        lines.push(`${indent}  发起人: ${trace.principal.subject_id}${name}  角色: ${trace.principal.roles.join(', ') || '-'}`
+            + (trace.principal.trust_level ? `  信任级别: ${trace.principal.trust_level}` : ''));
+    }
+    lines.push(`${indent}  开始: ${new Date(trace.started_at).toLocaleString()}  耗时: ${formatDuration(trace.duration_ms)}`);
+    if (termination.code || termination.reason) {
+        lines.push(`${indent}  结束原因: ${[termination.code, termination.reason].filter(Boolean).join(' — ')}`);
+    }
+    if (failingTool) {
+        lines.push(`${indent}  首个失败步骤: ${failingTool.tool_name} ${failingTool.status}${failingTool.error ? ` — ${failingTool.error}` : ''}`);
+    }
+    lines.push(`${indent}  模型调用 ${trace.model_calls.length} 次，tokens 输入 ${trace.usage.prompt_tokens} / 输出 ${trace.usage.completion_tokens} / 合计 ${trace.usage.total_tokens}`);
+    const cached = trace.model_calls.reduce((sum, call) => sum + (call.cache_read_tokens ?? 0), 0);
+    if (cached > 0 && trace.usage.prompt_tokens > 0) {
+        lines.push(`${indent}  提示缓存命中 ${cached} tokens（占输入 ${Math.round((cached / trace.usage.prompt_tokens) * 100)}%）`);
+    }
+    for (const call of trace.model_calls) {
+        const cache = call.cache_read_tokens ? ` cache=${call.cache_read_tokens}` : '';
+        const reasoning = call.reasoning_tokens ? ` reasoning=${call.reasoning_tokens}` : '';
+        lines.push(`${indent}    #${call.index} in=${call.prompt_tokens} out=${call.completion_tokens}${cache}${reasoning}`);
+    }
+    if (trace.context_budget)
+        lines.push(...renderContextBudget(trace.context_budget, indent));
+    lines.push(`${indent}  工具调用 ${trace.tool_calls.length} 次`);
+    for (const tool of trace.tool_calls) {
+        const details = [
+            tool.duration_ms !== undefined ? `${tool.duration_ms}ms` : undefined,
+            tool.result_size !== undefined ? `${tool.result_size} 字符` : undefined,
+            tool.policy ? `策略 ${tool.policy}` : undefined,
+        ].filter(Boolean).join(', ');
+        lines.push(`${indent}    ${TOOL_MARK[tool.status]} ${tool.tool_name}${details ? ` (${details})` : ''} ${tool.args_summary}`.trimEnd());
+        if (tool.error)
+            lines.push(`${indent}      ${tool.error}`);
+    }
+    if (trace.budget.extensions.length > 0 || trace.budget.continuations > 0) {
+        const extensions = trace.budget.extensions.map(item => `${item.from}→${item.to}`).join(', ');
+        lines.push(`${indent}  预算: 延长 ${trace.budget.extensions.length} 次${extensions ? ` (${extensions})` : ''}，自动续跑 ${trace.budget.continuations} 次`);
+    }
+    for (const task of trace.subagent_tasks) {
+        lines.push(`${indent}  子任务 ${task.task_id} [${task.status}] ${task.description}`);
+    }
+    for (const child of trace.subagents) {
+        lines.push(`${indent}  子 agent:`);
+        lines.push(...renderTrace(child, `${indent}    `, false));
+    }
+    if (withTimeline && trace.timeline.length > 0) {
+        lines.push(`${indent}  时间线:`);
+        for (const entry of trace.timeline) {
+            lines.push(`${indent}    +${formatDuration(entry.at_ms).padStart(7)}  ${entry.kind.padEnd(14)} ${entry.detail}`.trimEnd());
+        }
+    }
+    if (trace.dropped > 0)
+        lines.push(`${indent}  (有 ${trace.dropped} 条记录因超出上限被省略)`);
+    return lines;
+}
+const SEGMENT_LABEL = {
+    system: '系统提示',
+    tool_schemas: '工具 schema',
+    tool_index: '按需工具索引',
+    skill_catalog: '技能目录',
+    agent_catalog: '专家 agent 目录',
+    active_skills: '已加载技能',
+    memory: '记忆',
+    bootstrap: 'bootstrap',
+    history: '历史消息',
+    user: '本轮输入',
+};
+const TOP_SECTIONS = 5;
+/** Estimated prompt cost of the first model request, by segment. */
+function renderContextBudget(budget, indent) {
+    const parts = CONTEXT_BUDGET_SEGMENTS
+        .filter(segment => budget.segments[segment] > 0)
+        .map(segment => `${SEGMENT_LABEL[segment]} ${budget.segments[segment]}`);
+    const lines = [
+        `${indent}  上下文估算 ~${budget.total_tokens} tokens（固定开销 ~${budget.fixed_tokens}；工具 ${budget.tools.loaded} 个常驻 / ${budget.tools.deferred} 个按需）`,
+    ];
+    if (parts.length > 0)
+        lines.push(`${indent}    ${parts.join(' · ')}`);
+    const top = budget.sections.slice(0, TOP_SECTIONS).filter(section => section.tokens > 0);
+    if (top.length > 0)
+        lines.push(`${indent}    最大的提示段: ${top.map(section => `${section.id} ${section.tokens}`).join(', ')}`);
+    return lines;
+}
+function formatDuration(ms) {
+    if (ms === undefined)
+        return '-';
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
+}
+//# sourceMappingURL=turn-trace-format.js.map

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

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

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

@@ -0,0 +1,30 @@
+/**
+ * Process-local wiring between running turns and their TurnTraceCollector.
+ *
+ * Every TurnEvent of a turn — engine stream events and the tool events that
+ * TurnToolRuntime writes straight to the journal (see #740) — passes through
+ * the turn's journal port, so wrapping that port is the one place that sees
+ * the whole turn. Sub-agent turns share the parent's journal; their events
+ * are tagged with the child turn id so the parent trace can nest them.
+ */
+import type { TurnEvent } from '../event/turn-event.js';
+import type { TurnJournalPort } from '../turn/turn-ingress.js';
+import type { TurnTraceCollector, TurnTraceNote } from './turn-trace.js';
+/** Journal port that feeds the collector before delegating to the real journal. */
+export declare function createTracingJournal(journal: TurnJournalPort, collector: TurnTraceCollector): TurnJournalPort;
+/** Journal port for a sub-agent turn: tags events with the child turn id. */
+export declare function createScopedTraceJournal(journal: TurnJournalPort, scope: Readonly<{
+    turnId: string;
+    sessionKey: string;
+}>): TurnJournalPort;
+/** Turn id a sub-agent journal tagged this event with, if any. */
+export declare function traceScopeTurnId(event: TurnEvent): string | undefined;
+/** Makes a root collector reachable for trace notes until the returned release runs. */
+export declare function registerTurnTrace(collector: TurnTraceCollector): () => void;
+/**
+ * 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 declare function noteTurnTrace(turnId: string | undefined, note: TurnTraceNote): void;
+//# sourceMappingURL=turn-trace-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"turn-trace-registry.d.ts","sourceRoot":"","sources":["../../src/trace/turn-trace-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAUzE,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,kBAAkB,GAAG,eAAe,CAe7G;AAED,6EAA6E;AAC7E,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,QAAQ,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GACtD,eAAe,CAQjB;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAErE;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAK3E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAUnF"}