oh-my-knowledge 0.47.0 → 0.49.0

package/dist/observability/trace-attribution.js

@@ -21,16 +21,17 @@ const BUSINESS_ACTION_CMD_RE = /<[a-z][\w.-]*-cmd\b[^>]*\bname=["']([^"']+)["'][
 const COMMAND_ENVELOPE_RE = /<command-(?:name|message)>[\s\S]*?<\/command-(?:name|message)>/g;
 // cc 内置 CLI 命令(不是 skill)。dogfood 数据中这些词频繁以 <command-name> 出现,
 // 必须过滤掉才能得到真实 skill 分布。列表基于实测 + cc 常规命令集。
-const CC_BUILTIN_COMMANDS = new Set([
+const CLAUDE_BUILTIN_COMMANDS = new Set([
     'clear', 'exit', 'quit', 'help', 'fast', 'effort', 'model',
     'plugin', 'stats', 'doctor', 'compact', 'cost', 'agents', 'init',
     'config', 'permissions', 'resume', 'continue', 'memory',
 ]);
+const UNSAFE_SKILL_NAMES = new Set(['__proto__', 'constructor', 'prototype']);
+const SKILL_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/;
 /**
- * 归一化 skill 名: 去掉 plugin 前缀, 过滤 cc 内置命令。
+ * 归一化 skill 名：去掉 plugin 前缀并校验稳定身份。
  * - "impeccable:audit" → "audit"
  * - "pbakaus/impeccable:audit" → "audit"
- * - "clear" / "exit" 等 → null(表示不是 skill)
  */
 export function normalizeSkillName(raw) {
     return parseSkillRef(raw)?.skillName ?? null;
@@ -41,10 +42,12 @@ export function parseSkillRef(raw) {
         return null;
     // plugin-prefixed: pbakaus/impeccable:audit / impeccable:audit → 取最后一段
     const colonIdx = trimmed.lastIndexOf(':');
-    const name = colonIdx >= 0 ? trimmed.slice(colonIdx + 1) : trimmed;
-    if (CC_BUILTIN_COMMANDS.has(name))
+    const name = (colonIdx >= 0 ? trimmed.slice(colonIdx + 1) : trimmed).trim();
+    if (!SKILL_NAME_RE.test(name)
+        || UNSAFE_SKILL_NAMES.has(name.toLowerCase()))
         return null;
-    const pluginName = colonIdx >= 0 ? trimmed.slice(0, colonIdx) : undefined;
+    const rawPluginName = colonIdx >= 0 ? trimmed.slice(0, colonIdx).trim() : undefined;
+    const pluginName = rawPluginName && rawPluginName.length <= 256 ? rawPluginName : undefined;
     return {
         skillName: name,
         rawSkillRef: trimmed,
@@ -83,7 +86,11 @@ export function extractCommandSkillRef(record) {
             }
         }
     }
-    return raw ? parseSkillRef(raw) : null;
+    return raw && !isClaudeBuiltinCommand(raw) ? parseSkillRef(raw) : null;
+}
+export function isClaudeBuiltinCommand(raw) {
+    const trimmed = raw.trim();
+    return !trimmed.includes(':') && CLAUDE_BUILTIN_COMMANDS.has(trimmed.toLowerCase());
 }
 /**
  * 从 OpenClaw user message 的业务动作标签里提取 skill 名字(信号 4)。
@@ -140,13 +147,207 @@ export function extractAttributionSkill(record) {
 export function extractAttributionSkillRef(record) {
     return record.attributionSkill ? parseSkillRef(record.attributionSkill) : null;
 }
-// OpenClaw traces may point at either workspace root; both layouts store skills under <workspace>/skills.
-const SKILL_READ_FILE_RE = /(?:\.claude\/skills|\.openclaw\/workspace(?:-main)?\/skills)\/([^/]+)\/SKILL\.md$/;
-const SKILL_SCRIPT_PATH_RE = /(?:^|[\s"'`(\[{:,])(?:~|\.|\/)?[^\s"'`]*\/skills\/([^/\s"'`]+)\/scripts\/[^\s"'`]*/;
+// Only installed runtime roots count as attribution evidence. Repository examples
+// such as `examples/foo/skills/bar/SKILL.md` are knowledge artifacts under review,
+// not proof that the `bar` skill was active in the session.
+const SKILL_READ_PATH_RE = /(?:^|[\s"'`(\[{:,])([^\s"'`]*\/skills\/(?:\.system\/)?[^/\s"'`]+\/SKILL\.md)\b/g;
+const INSTALLED_SKILL_PATH_RES = [
+    /(?:^|\/)\.(?:agents|claude|codex)\/skills\/([^/]+)\/SKILL\.md$/,
+    /(?:^|\/)\.codex\/skills\/\.system\/([^/]+)\/SKILL\.md$/,
+    /(?:^|\/)\.codex\/plugins\/cache\/.+\/skills\/([^/]+)\/SKILL\.md$/,
+    /(?:^|\/)\.openclaw\/workspace(?:-main)?\/skills\/([^/]+)\/SKILL\.md$/,
+];
+const SKILL_SCRIPT_PATH_RE = /(?:^|[\s"'`(\[{:,])(?:~|\.|\/)?[^\s"'`]*\/skills\/(?:\.system\/)?([^/\s"'`]+)\/scripts\/[^\s"'`]*/;
+export function isInstalledSkillAssetPath(value, skillName) {
+    if (!value || !skillName)
+        return false;
+    const normalized = value.replaceAll('\\', '/');
+    const segments = normalized.split('/');
+    for (let index = 0; index < segments.length; index++) {
+        if (segments[index] !== 'skills')
+            continue;
+        const nameIndex = segments[index + 1] === '.system' ? index + 2 : index + 1;
+        if (segments[nameIndex] !== skillName || nameIndex + 1 >= segments.length)
+            continue;
+        const installationPrefix = segments.slice(0, index);
+        if (installationPrefix.some((segment) => segment === '.agents'
+            || segment === '.claude'
+            || segment === '.codex'
+            || segment === '.openclaw'))
+            return true;
+    }
+    return false;
+}
+function extractInstalledSkillReadRef(text) {
+    const normalized = text.replaceAll('\\', '/');
+    for (const match of normalized.matchAll(SKILL_READ_PATH_RE)) {
+        const path = match[1];
+        if (!path)
+            continue;
+        for (const pattern of INSTALLED_SKILL_PATH_RES) {
+            const installed = path.match(pattern);
+            if (installed?.[1])
+                return parseSkillRef(installed[1]);
+        }
+    }
+    return null;
+}
+function skipJsString(source, start) {
+    const quote = source[start];
+    let index = start + 1;
+    while (index < source.length) {
+        if (source[index] === '\\') {
+            index += 2;
+            continue;
+        }
+        if (source[index] === quote)
+            return index + 1;
+        index += 1;
+    }
+    return source.length;
+}
+function skipJsTrivia(source, start) {
+    let index = start;
+    while (index < source.length) {
+        if (/\s/.test(source[index])) {
+            index += 1;
+            continue;
+        }
+        if (source.startsWith('//', index)) {
+            const newline = source.indexOf('\n', index + 2);
+            return newline < 0 ? source.length : skipJsTrivia(source, newline + 1);
+        }
+        if (source.startsWith('/*', index)) {
+            const end = source.indexOf('*/', index + 2);
+            return end < 0 ? source.length : skipJsTrivia(source, end + 2);
+        }
+        break;
+    }
+    return index;
+}
+function extractExecCommandLiteral(source, callStart) {
+    let index = skipJsTrivia(source, callStart + 'tools.exec_command'.length);
+    if (source[index] !== '(')
+        return null;
+    index = skipJsTrivia(source, index + 1);
+    if (source[index] !== '{')
+        return null;
+    let depth = 1;
+    index += 1;
+    while (index < source.length && depth > 0) {
+        index = skipJsTrivia(source, index);
+        const char = source[index];
+        if (char === '"' || char === "'" || char === '`') {
+            index = skipJsString(source, index);
+            continue;
+        }
+        if (char === '{') {
+            depth += 1;
+            index += 1;
+            continue;
+        }
+        if (char === '}') {
+            depth -= 1;
+            index += 1;
+            continue;
+        }
+        if (depth === 1
+            && source.startsWith('cmd', index)
+            && !/[\w$]/.test(source[index - 1] ?? '')
+            && !/[\w$]/.test(source[index + 3] ?? '')) {
+            let valueStart = skipJsTrivia(source, index + 3);
+            if (source[valueStart] !== ':') {
+                index += 3;
+                continue;
+            }
+            valueStart = skipJsTrivia(source, valueStart + 1);
+            const quote = source[valueStart];
+            if (quote !== '"' && quote !== "'" && quote !== '`')
+                return null;
+            const end = skipJsString(source, valueStart);
+            return source.slice(valueStart + 1, Math.max(valueStart + 1, end - 1));
+        }
+        index += 1;
+    }
+    return null;
+}
+function extractExecCommandLiterals(source) {
+    const commands = [];
+    let index = 0;
+    while (index < source.length) {
+        index = skipJsTrivia(source, index);
+        const char = source[index];
+        if (char === '"' || char === "'" || char === '`') {
+            index = skipJsString(source, index);
+            continue;
+        }
+        if (source.startsWith('tools.exec_command', index)
+            && !/[\w$.]/.test(source[index - 1] ?? '')
+            && !/[\w$]/.test(source[index + 'tools.exec_command'.length] ?? '')) {
+            const command = extractExecCommandLiteral(source, index);
+            if (command)
+                commands.push(command);
+            index += 'tools.exec_command'.length;
+            continue;
+        }
+        index += 1;
+    }
+    return commands;
+}
+function splitShellCommandSegments(command) {
+    const segments = [];
+    let start = 0;
+    let quote = null;
+    let index = 0;
+    while (index < command.length) {
+        const char = command[index];
+        if (char === '\\') {
+            index += 2;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            index += 1;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            index += 1;
+            continue;
+        }
+        const separatorLength = command.startsWith('&&', index) || command.startsWith('||', index)
+            ? 2
+            : char === ';' || char === '|' || char === '\n'
+                ? 1
+                : 0;
+        if (separatorLength > 0) {
+            segments.push(command.slice(start, index));
+            index += separatorLength;
+            start = index;
+            continue;
+        }
+        index += 1;
+    }
+    segments.push(command.slice(start));
+    return segments;
+}
+const SHELL_FILE_READER_RE = /^(?:(?:env\s+)?(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)*)?(?:(?:command|sudo)\s+)*(?:[\w./-]+\/)?(?:cat|sed|head|tail|less|more|bat|awk|wc)\b/;
+function extractShellSkillReadRef(command) {
+    for (const segment of splitShellCommandSegments(command)) {
+        const normalized = segment.trim();
+        if (!SHELL_FILE_READER_RE.test(normalized))
+            continue;
+        const skillRef = extractInstalledSkillReadRef(normalized);
+        if (skillRef)
+            return skillRef;
+    }
+    return null;
+}
 /**
- * 从 assistant message 的 Read tool_use 里提取 skill 名字(信号 3, fallback)。
- * 匹配 file_path 形如 ".claude/skills/<name>/SKILL.md"
- * 或 ".openclaw/workspace/skills/<name>/SKILL.md" 的模式。
+ * 从 assistant message 的 Read / Bash tool_use 里提取 skill 名字(信号 3, fallback)。
+ * Codex 通常用 shell 读取 `.agents/skills/<name>/SKILL.md`，Claude Code 与
+ * OpenClaw 则更常用结构化 Read tool；两种形式统一识别。
  * 返回 null 表示没命中。
  */
 export function extractSkillReadFile(record) {
@@ -158,9 +359,27 @@ export function extractSkillReadFileRef(record) {
         if (part.type === 'tool_use' && part.name === 'Read') {
             const filePath = part.input?.file_path;
             if (typeof filePath === 'string') {
-                const m = SKILL_READ_FILE_RE.exec(filePath);
-                if (m)
-                    return parseSkillRef(m[1]);
+                const skillRef = extractInstalledSkillReadRef(filePath);
+                if (skillRef)
+                    return skillRef;
+            }
+        }
+        if (part.type === 'tool_use'
+            && (part.name === 'Bash'
+                || part.name?.toLowerCase() === 'exec'
+                || part.name?.toLowerCase() === 'js')) {
+            const rawCommand = part.name === 'Bash'
+                ? part.input?.command
+                : part.input?.input ?? part.input?.code ?? part.input?.command;
+            const commands = typeof rawCommand !== 'string'
+                ? []
+                : part.name === 'Bash'
+                    ? [rawCommand]
+                    : extractExecCommandLiterals(rawCommand);
+            for (const command of commands) {
+                const skillRef = extractShellSkillReadRef(command);
+                if (skillRef)
+                    return skillRef;
             }
         }
     }
@@ -184,16 +403,91 @@ export function extractSkillScriptCommandRef(record) {
                 texts.push(part.text);
             }
             else if (part.type === 'tool_use') {
-                const command = part.input?.command;
-                if (typeof command === 'string')
-                    texts.push(command);
+                const rawCommand = part.name?.toLowerCase() === 'exec'
+                    ? part.input?.input ?? part.input?.code ?? part.input?.command
+                    : part.input?.code ?? part.input?.command;
+                if (typeof rawCommand === 'string') {
+                    texts.push(...(part.name?.toLowerCase() === 'exec'
+                        ? extractExecCommandLiterals(rawCommand)
+                        : [rawCommand]));
+                }
             }
         }
     }
     for (const text of texts) {
         const match = SKILL_SCRIPT_PATH_RE.exec(text);
-        if (match?.[1])
-            return parseSkillRef(match[1]);
+        if (match?.[1]) {
+            const ref = parseSkillRef(match[1]);
+            if (ref && isInstalledSkillAssetPath(match[0], ref.skillName))
+                return ref;
+        }
+    }
+    return null;
+}
+export function extractCommandSkillRefFromEvent(event) {
+    const match = COMMAND_NAME_RE.exec(event.text);
+    const raw = match?.[1];
+    if (!raw)
+        return null;
+    return parseSkillRef(raw);
+}
+export function extractBusinessActionSkillRefFromEvent(event) {
+    const match = BUSINESS_ACTION_CMD_RE.exec(event.text);
+    const raw = match?.[1];
+    return raw && isStableSkillSlug(raw) ? parseSkillRef(raw) : null;
+}
+export function extractAttributionSkillRefFromEvent(event) {
+    return event.attributionSkill ? parseSkillRef(event.attributionSkill) : null;
+}
+export function extractSkillToolUseRefFromEvent(event) {
+    if (event.tool.name !== 'Skill')
+        return null;
+    const skill = event.input.skill;
+    return typeof skill === 'string' ? parseSkillRef(skill) : null;
+}
+export function extractSkillReadFileRefFromEvent(event) {
+    if (event.tool.name === 'Read') {
+        const filePath = event.input.file_path;
+        return typeof filePath === 'string' ? extractInstalledSkillReadRef(filePath) : null;
+    }
+    if (event.tool.name !== 'Bash'
+        && event.tool.name.toLowerCase() !== 'exec'
+        && event.tool.sourceName?.toLowerCase() !== 'exec'
+        && event.tool.name !== 'node_repl.js'
+        && event.tool.name.toLowerCase() !== 'js'
+        && event.tool.sourceName?.toLowerCase() !== 'js')
+        return null;
+    const rawCommand = event.input.command ?? event.input.input ?? event.input.code;
+    if (typeof rawCommand !== 'string')
+        return null;
+    const sourceName = event.tool.sourceName?.toLowerCase();
+    const isOrchestrationWrapper = sourceName === 'exec'
+        || sourceName === 'js'
+        || event.tool.name === 'node_repl.js'
+        || event.tool.name.toLowerCase() === 'js';
+    const commands = isOrchestrationWrapper
+        ? extractExecCommandLiterals(rawCommand)
+        : [rawCommand];
+    for (const command of commands) {
+        const skillRef = extractShellSkillReadRef(command);
+        if (skillRef)
+            return skillRef;
+    }
+    return null;
+}
+export function extractSkillScriptCommandRefFromEvent(event) {
+    const texts = event.eventKind === 'message'
+        ? [event.text]
+        : typeof (event.input.command ?? event.input.input ?? event.input.code) === 'string'
+            ? [String(event.input.command ?? event.input.input ?? event.input.code)]
+            : [];
+    for (const text of texts) {
+        const match = SKILL_SCRIPT_PATH_RE.exec(text);
+        if (match?.[1]) {
+            const ref = parseSkillRef(match[1]);
+            if (ref && isInstalledSkillAssetPath(match[0], ref.skillName))
+                return ref;
+        }
     }
     return null;
 }

package/dist/observability/trace-ingestion.d.ts

@@ -0,0 +1,9 @@
+import type { TraceIngestionSummary } from '../types/index.js';
+export interface TraceIngestionNotice {
+    level: 'warning' | 'info';
+    text: string;
+}
+export declare function emptyTraceIngestionSummary(fileCount?: number): TraceIngestionSummary;
+export declare function mergeTraceIngestionSummaries(summaries: TraceIngestionSummary[]): TraceIngestionSummary;
+export declare function parseTraceIngestionSummary(value: unknown): TraceIngestionSummary | null;
+export declare function traceIngestionNotices(summary: TraceIngestionSummary | undefined, lang: 'zh' | 'en'): TraceIngestionNotice[];

package/dist/observability/trace-ingestion.js

@@ -0,0 +1,80 @@
+import { sumRecordCounts } from '../shared/record-count.js';
+export function emptyTraceIngestionSummary(fileCount = 0) {
+    return {
+        fileCount,
+        sourceRecordCount: 0,
+        parsedRecordCount: 0,
+        malformedRecordCount: 0,
+        ignoredValueCount: 0,
+        unknownEventCount: 0,
+        filteredSessionCount: 0,
+    };
+}
+export function mergeTraceIngestionSummaries(summaries) {
+    return summaries.reduce((total, summary) => ({
+        fileCount: sumRecordCounts(total.fileCount, summary.fileCount),
+        sourceRecordCount: sumRecordCounts(total.sourceRecordCount, summary.sourceRecordCount),
+        parsedRecordCount: sumRecordCounts(total.parsedRecordCount, summary.parsedRecordCount),
+        malformedRecordCount: sumRecordCounts(total.malformedRecordCount, summary.malformedRecordCount),
+        ignoredValueCount: sumRecordCounts(total.ignoredValueCount, summary.ignoredValueCount),
+        unknownEventCount: sumRecordCounts(total.unknownEventCount, summary.unknownEventCount),
+        filteredSessionCount: sumRecordCounts(total.filteredSessionCount, summary.filteredSessionCount),
+    }), emptyTraceIngestionSummary());
+}
+export function parseTraceIngestionSummary(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const keys = [
+        'fileCount',
+        'sourceRecordCount',
+        'parsedRecordCount',
+        'malformedRecordCount',
+        'ignoredValueCount',
+        'unknownEventCount',
+        'filteredSessionCount',
+    ];
+    if (!keys.every((key) => isCount(record[key])))
+        return null;
+    const summary = record;
+    let classifiedRecordCount;
+    try {
+        classifiedRecordCount = sumRecordCounts(summary.parsedRecordCount, summary.malformedRecordCount, summary.ignoredValueCount);
+    }
+    catch {
+        return null;
+    }
+    if (classifiedRecordCount !== summary.sourceRecordCount
+        || (summary.fileCount === 0 && (summary.sourceRecordCount > 0
+            || summary.unknownEventCount > 0
+            || summary.filteredSessionCount > 0)))
+        return null;
+    return summary;
+}
+export function traceIngestionNotices(summary, lang) {
+    if (!summary)
+        return [];
+    const notices = [];
+    if (summary.malformedRecordCount > 0
+        || summary.ignoredValueCount > 0
+        || summary.unknownEventCount > 0) {
+        notices.push({
+            level: 'warning',
+            text: lang === 'zh'
+                ? `注意：摄取时发现 ${summary.malformedRecordCount} 条格式损坏记录、${summary.ignoredValueCount} 个非对象值、${summary.unknownEventCount} 个未识别事件；请确认本次观测覆盖是否完整。`
+                : `Note: ingestion found ${summary.malformedRecordCount} malformed records, ${summary.ignoredValueCount} non-object values, and ${summary.unknownEventCount} unrecognized events; review whether this observation is complete.`,
+        });
+    }
+    if (summary.filteredSessionCount > 0) {
+        notices.push({
+            level: 'info',
+            text: lang === 'zh'
+                ? `已过滤 ${summary.filteredSessionCount} 个运行时守护会话，不计入知识载体观测。`
+                : `Filtered ${summary.filteredSessionCount} runtime guardian session(s) from knowledge-artifact observation.`,
+        });
+    }
+    return notices;
+}
+function isCount(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}

package/dist/observability/trace-ir.d.ts

@@ -0,0 +1,113 @@
+import type { ToolCallStatus, ToolCallStatusSource, TraceIngestionSummary, TraceSourceMetadata } from '../types/index.js';
+import type { TraceSourceKind } from '../types/trace.js';
+import type { NormalizedToolIdentity } from '../shared/tool-identity.js';
+export type { TraceSourceKind } from '../types/trace.js';
+export type TraceRole = 'standalone' | 'main' | 'subagent';
+export type TraceMessageRole = 'user' | 'assistant' | 'system';
+export type TraceMessageOrigin = 'human' | 'runtime' | 'skill-context' | 'synthetic';
+export type TraceToolStatus = ToolCallStatus;
+export type TraceToolStatusSource = ToolCallStatusSource;
+/** Source-neutral tool identity, including provider namespaces when present. */
+export type TraceToolRef = NormalizedToolIdentity;
+interface TraceEventBase {
+    eventId: string;
+    /** Source-native record/message id, when the source exposes one. */
+    sourceEventId?: string;
+    sourceIndex: number;
+    sourceType: string;
+    timestamp?: string;
+    turnId?: string;
+}
+export interface TraceMessageEvent extends TraceEventBase {
+    eventKind: 'message';
+    role: TraceMessageRole;
+    origin: TraceMessageOrigin;
+    text: string;
+    model?: string;
+    attributionSkill?: string;
+}
+export interface TraceToolCallEvent extends TraceEventBase {
+    eventKind: 'tool_call';
+    callId: string;
+    callInstanceId?: string;
+    tool: TraceToolRef;
+    input: Record<string, unknown>;
+    model?: string;
+}
+export interface TraceToolResultEvent extends TraceEventBase {
+    eventKind: 'tool_result';
+    callId: string;
+    callInstanceId?: string;
+    output: string;
+    status: TraceToolStatus;
+    statusSource: TraceToolStatusSource;
+}
+export interface TraceUsageEvent extends TraceEventBase {
+    eventKind: 'usage';
+    model?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens?: number;
+}
+export interface TraceLifecycleEvent extends TraceEventBase {
+    eventKind: 'lifecycle';
+    phase: 'session_started' | 'session_ended' | 'turn_started' | 'turn_completed' | 'turn_aborted' | 'turn_interrupted';
+    reason?: string;
+    durationMs?: number;
+}
+export interface TraceUnknownEvent extends TraceEventBase {
+    eventKind: 'unknown';
+    raw?: unknown;
+}
+export type TraceEvent = TraceMessageEvent | TraceToolCallEvent | TraceToolResultEvent | TraceUsageEvent | TraceLifecycleEvent | TraceUnknownEvent;
+export interface TraceSession {
+    /** Concrete source run/thread identifier. */
+    runId: string;
+    /** Root run shared by a main trace and its descendants. */
+    rootRunId: string;
+    parentRunId?: string;
+    /** Unique evidence stream identifier. */
+    traceId: string;
+    groupPath: string;
+    role: TraceRole;
+    label: string;
+    sourcePath: string;
+    sourceKind: TraceSourceKind;
+    events: TraceEvent[];
+    cwd?: string;
+    gitBranch?: string;
+    entrypoint?: string;
+    sourceMetadata?: TraceSourceMetadata;
+    startTimestamp?: string;
+    endTimestamp?: string;
+}
+export interface TraceCorpus {
+    sessions: TraceSession[];
+    ingestion: TraceIngestionSummary;
+}
+/**
+ * Build a deterministic, transport-safe identity for one physical evidence
+ * stream. Source paths remain available as provenance; the identifier itself
+ * stays opaque so it can safely cross JSON, HTML, URLs, and review-state keys.
+ */
+export declare function createTraceId(input: {
+    sourceKind: TraceSourceKind;
+    runId: string;
+    sourcePath: string;
+    streamId?: string;
+}): string;
+export declare function traceEventTimestamp(event: TraceEvent): string | undefined;
+export declare function normalizeTraceTimestamp(value: unknown): string | undefined;
+export declare function traceTimestampBounds(values: Iterable<unknown>): {
+    startTimestamp?: string;
+    endTimestamp?: string;
+};
+export declare function traceToolDisplayName(tool: TraceToolRef): string;
+/**
+ * Correlate one concrete call occurrence with its result without treating a
+ * source-native callId as globally unique. FIFO is the only source-neutral
+ * assumption available when a runtime reuses call IDs.
+ */
+export declare function correlateTraceToolEvents(events: TraceEvent[]): TraceEvent[];

package/dist/observability/trace-ir.js

@@ -0,0 +1,87 @@
+import { createHash } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { normalizeRfc3339Timestamp } from '../shared/timestamp.js';
+/**
+ * Build a deterministic, transport-safe identity for one physical evidence
+ * stream. Source paths remain available as provenance; the identifier itself
+ * stays opaque so it can safely cross JSON, HTML, URLs, and review-state keys.
+ */
+export function createTraceId(input) {
+    const stable = [
+        input.sourceKind,
+        input.runId,
+        canonicalTraceSourcePath(input.sourcePath),
+        input.streamId ?? '',
+    ].join('\u0000');
+    return `trace:${createHash('sha256').update(stable).digest('hex').slice(0, 32)}`;
+}
+function canonicalTraceSourcePath(sourcePath) {
+    try {
+        return realpathSync(sourcePath);
+    }
+    catch {
+        return resolve(sourcePath);
+    }
+}
+export function traceEventTimestamp(event) {
+    return event.timestamp;
+}
+export function normalizeTraceTimestamp(value) {
+    return normalizeRfc3339Timestamp(value);
+}
+export function traceTimestampBounds(values) {
+    let startTimestamp;
+    let endTimestamp;
+    for (const value of values) {
+        const timestamp = normalizeTraceTimestamp(value);
+        if (!timestamp)
+            continue;
+        if (!startTimestamp || timestamp < startTimestamp)
+            startTimestamp = timestamp;
+        if (!endTimestamp || timestamp > endTimestamp)
+            endTimestamp = timestamp;
+    }
+    return { startTimestamp, endTimestamp };
+}
+export function traceToolDisplayName(tool) {
+    return tool.displayName ?? tool.name;
+}
+/**
+ * Correlate one concrete call occurrence with its result without treating a
+ * source-native callId as globally unique. FIFO is the only source-neutral
+ * assumption available when a runtime reuses call IDs.
+ */
+export function correlateTraceToolEvents(events) {
+    const pending = new Map();
+    return events.map((event) => {
+        if (event.eventKind === 'tool_call') {
+            const callInstanceId = event.callInstanceId ?? event.eventId;
+            const correlated = { ...event, callInstanceId };
+            const queue = pending.get(event.callId) ?? [];
+            queue.push(correlated);
+            pending.set(event.callId, queue);
+            return correlated;
+        }
+        if (event.eventKind === 'tool_result') {
+            const queue = pending.get(event.callId);
+            const matchingIndex = event.callInstanceId
+                ? queue?.findIndex((candidate) => candidate.callInstanceId === event.callInstanceId)
+                : undefined;
+            const call = matchingIndex !== undefined && matchingIndex >= 0
+                ? queue?.splice(matchingIndex, 1)[0]
+                : event.callInstanceId
+                    ? undefined
+                    : queue?.shift();
+            if (queue?.length === 0)
+                pending.delete(event.callId);
+            return {
+                ...event,
+                callInstanceId: event.callInstanceId
+                    ?? call?.callInstanceId
+                    ?? `orphan:${event.eventId}`,
+            };
+        }
+        return event;
+    });
+}