oh-my-knowledge 0.51.2 → 0.52.0

package/dist/observability/codex-conversation-index.js

@@ -0,0 +1,566 @@
+import { closeSync, openSync, readSync, statSync } from 'node:fs';
+import { codexUserDisplayText, codexUserMessageOrigin } from './codex-protocol.js';
+import { codexRuntimeToolOutcomeFromPayload, codexToolOutputOutcome, } from './codex-tool-status.js';
+const READ_CHUNK_BYTES = 256 * 1024;
+const MAX_RECORD_BYTES = 32 * 1024 * 1024;
+const INDEX_SCHEMA_VERSION = 11;
+const MAX_CURRENT_INDEX_ATTEMPTS = 4;
+/**
+ * Build a compact byte-range index without retaining the rollout. Only records
+ * needed for turn boundaries and list metrics are parsed.
+ */
+export function buildCodexRolloutIndex(sourcePath, sourceThreadId) {
+    const sourceStat = statSync(sourcePath);
+    const state = scanCodexRolloutIndex(sourcePath, sourceThreadId, {
+        tasks: [],
+        sourceRecordCount: 0,
+        malformedRecordCount: 0,
+        indexedSize: 0,
+        indexedLineCount: 0,
+        indexedEndsWithNewline: true,
+    }, 0, sourceStat.size, 0);
+    return indexFromState(sourcePath, sourceThreadId, sourceStat, state);
+}
+/**
+ * Extend an append-only rollout index from its last byte boundary. If the
+ * source was replaced or truncated, rebuild so callers never observe a mixed
+ * index from two different files.
+ */
+export function extendCodexRolloutIndex(sourcePath, sourceThreadId, previous) {
+    const sourceStat = statSync(sourcePath);
+    if (!isReusableCodexRolloutIndex(previous, sourcePath)
+        || previous.sourceThreadId !== sourceThreadId
+        || sourceStat.size < previous.sourceSize) {
+        return buildCodexRolloutIndex(sourcePath, sourceThreadId);
+    }
+    const normalizedPrevious = normalizeCodexRolloutIndex(previous);
+    if (sourceStat.size === previous.sourceSize && sourceStat.mtimeMs === previous.sourceMtimeMs) {
+        return normalizedPrevious;
+    }
+    const tasks = normalizedPrevious.tasks.map((task) => ({ ...task }));
+    const resume = resumeAppendCursor(sourcePath, normalizedPrevious, sourceStat.size);
+    if (!resume)
+        return buildCodexRolloutIndex(sourcePath, sourceThreadId);
+    completeTailTaskDelimiter(tasks, normalizedPrevious.indexedSize, resume.indexedSize);
+    const lastTask = tasks.at(-1);
+    const active = lastTask?.status === 'open'
+        ? mutableTask(tasks.pop(), normalizedPrevious.activeToolOutcomeState)
+        : undefined;
+    const state = {
+        tasks,
+        active,
+        sessionMeta: normalizedPrevious.sessionMeta,
+        sessionMetaLine: normalizedPrevious.sessionMetaLine,
+        sourceRecordCount: normalizedPrevious.sourceRecordCount,
+        malformedRecordCount: normalizedPrevious.malformedRecordCount,
+        indexedSize: resume.indexedSize,
+        indexedLineCount: normalizedPrevious.indexedLineCount,
+        indexedEndsWithNewline: resume.indexedEndsWithNewline,
+    };
+    const extended = resume.indexedSize < sourceStat.size
+        ? scanCodexRolloutIndex(sourcePath, sourceThreadId, state, resume.indexedSize, sourceStat.size, normalizedPrevious.indexedLineCount)
+        : state;
+    return indexFromState(sourcePath, sourceThreadId, sourceStat, extended);
+}
+/**
+ * Catch an append-only rollout up to a snapshot that is still current after
+ * indexing. Returning a stale prefix here would violate current-read callers.
+ */
+export function synchronizeCurrentCodexRolloutIndex(sourcePath, sourceThreadId, initial) {
+    let index = initial
+        && initial.sourceThreadId === sourceThreadId
+        && isReusableCodexRolloutIndex(initial, sourcePath)
+        ? normalizeCodexRolloutIndex(initial)
+        : buildCodexRolloutIndex(sourcePath, sourceThreadId);
+    for (let attempt = 0; attempt < MAX_CURRENT_INDEX_ATTEMPTS; attempt += 1) {
+        if (isCurrentCodexRolloutIndex(index, sourcePath))
+            return index;
+        index = extendCodexRolloutIndex(sourcePath, sourceThreadId, index);
+    }
+    if (isCurrentCodexRolloutIndex(index, sourcePath))
+        return index;
+    throw new Error('Codex 对话日志持续写入，暂时无法形成当前索引快照');
+}
+function resumeAppendCursor(sourcePath, previous, sourceSize) {
+    if (previous.indexedEndsWithNewline) {
+        return {
+            indexedSize: previous.indexedSize,
+            indexedEndsWithNewline: true,
+        };
+    }
+    const fd = openSync(sourcePath, 'r');
+    const buffer = Buffer.allocUnsafe(Math.min(4_096, Math.max(1, sourceSize - previous.indexedSize)));
+    let offset = previous.indexedSize;
+    try {
+        while (offset < sourceSize) {
+            const bytesRead = readSync(fd, buffer, 0, Math.min(buffer.length, sourceSize - offset), offset);
+            if (bytesRead === 0)
+                break;
+            for (let index = 0; index < bytesRead; index += 1) {
+                const byte = buffer[index];
+                if (byte === 0x0a) {
+                    return {
+                        indexedSize: offset + index + 1,
+                        indexedEndsWithNewline: true,
+                    };
+                }
+                if (byte !== 0x09 && byte !== 0x0d && byte !== 0x20)
+                    return undefined;
+            }
+            offset += bytesRead;
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    return {
+        indexedSize: sourceSize,
+        indexedEndsWithNewline: false,
+    };
+}
+function completeTailTaskDelimiter(tasks, previousIndexedSize, indexedSize) {
+    if (indexedSize <= previousIndexedSize)
+        return;
+    const tailTask = tasks.at(-1);
+    if (tailTask?.endOffset === previousIndexedSize)
+        tailTask.endOffset = indexedSize;
+}
+/**
+ * A single Codex rollout is sequential: once a newer task starts, an older
+ * task without a terminal record can no longer be live. Normalize historical
+ * caches in memory so an omitted task_complete never becomes a permanent
+ * "running" conversation.
+ */
+export function normalizeCodexRolloutIndex(index) {
+    let changed = false;
+    const tasks = index.tasks.map((task, taskIndex) => {
+        if (task.status !== 'open' || taskIndex === index.tasks.length - 1)
+            return task;
+        changed = true;
+        return {
+            ...task,
+            status: 'unknown',
+            endTimestamp: task.endTimestamp ?? index.tasks[taskIndex + 1]?.startTimestamp,
+        };
+    });
+    return changed ? { ...index, tasks } : index;
+}
+function scanCodexRolloutIndex(sourcePath, sourceThreadId, state, startOffset, endOffset, startLine) {
+    const scanned = forEachJsonlLine(sourcePath, (record) => {
+        state.sourceRecordCount += 1;
+        const relevant = isIndexRelevantLine(record.text);
+        if (!relevant) {
+            includeRecord(state.active, record);
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(record.text);
+        }
+        catch {
+            state.malformedRecordCount += 1;
+            includeRecord(state.active, record);
+            return;
+        }
+        const raw = objectValue(parsed);
+        if (!raw)
+            return;
+        const recordType = stringValue(raw.type);
+        const payload = objectValue(raw.payload) ?? {};
+        const payloadType = stringValue(payload.type);
+        const timestamp = stringValue(raw.timestamp);
+        if (recordType === 'session_meta' && state.sessionMeta === undefined) {
+            state.sessionMeta = parsed;
+            state.sessionMetaLine = record.line;
+            return;
+        }
+        if (recordType === 'event_msg' && payloadType === 'task_started') {
+            if (state.active) {
+                state.tasks.push(finalizeSupersededTask(state.active, record.startOffset, record.line - 1, timestamp));
+            }
+            const nativeTurnId = stringValue(payload.turn_id);
+            state.active = newMutableTask(nativeTurnId ?? `turn:${sourceThreadId}:${record.line}`, record, timestamp);
+            return;
+        }
+        includeRecord(state.active, record);
+        if (isUserPromptRecord(recordType, payloadType, payload)) {
+            const message = userPromptText(payload)?.trim();
+            const displayText = message && codexUserMessageOrigin(message) === 'human'
+                ? codexUserDisplayText(message)?.trim()
+                : undefined;
+            if (!displayText)
+                return;
+            state.active ??= newMutableTask(`turn:${sourceThreadId}:${record.line}`, record, timestamp);
+            const titlePriority = userPromptPriority(recordType, payloadType);
+            if (titlePriority > state.active.titlePriority) {
+                state.active.title = compactTitle(displayText);
+                state.active.titlePriority = titlePriority;
+            }
+            return;
+        }
+        if (!state.active)
+            return;
+        if (recordType === 'response_item' && isToolCallPayload(payloadType)) {
+            recordToolCall(state.active, record, payload);
+        }
+        recordToolOutcome(state.active, record, recordType, payloadType, payload);
+        if (recordType === 'event_msg' && payloadType === 'task_complete') {
+            state.active.status = 'completed';
+            state.active.endTimestamp = timestamp;
+            if (state.active.titlePriority === 0) {
+                const fallback = stringValue(payload.last_agent_message)?.trim();
+                if (fallback)
+                    state.active.title = compactTitle(fallback);
+            }
+            state.tasks.push(stripMutable(state.active));
+            state.active = undefined;
+            return;
+        }
+        if (recordType === 'event_msg' && (payloadType === 'turn_aborted' || payloadType === 'turn_interrupted')) {
+            state.active.status = payloadType === 'turn_aborted' ? 'aborted' : 'interrupted';
+            state.active.endTimestamp = timestamp;
+            state.tasks.push(stripMutable(state.active));
+            state.active = undefined;
+        }
+    }, startOffset, endOffset, startLine);
+    state.indexedSize = scanned.indexedSize;
+    state.indexedLineCount = scanned.indexedLineCount;
+    state.indexedEndsWithNewline = scanned.indexedEndsWithNewline;
+    return state;
+}
+function indexFromState(sourcePath, sourceThreadId, sourceStat, state) {
+    const tasks = state.active
+        ? [...state.tasks, stripMutable(state.active)]
+        : state.tasks;
+    return {
+        schemaVersion: INDEX_SCHEMA_VERSION,
+        sourcePath,
+        sourceSize: sourceStat.size,
+        sourceMtimeMs: sourceStat.mtimeMs,
+        indexedSize: state.indexedSize,
+        indexedLineCount: state.indexedLineCount,
+        indexedEndsWithNewline: state.indexedEndsWithNewline,
+        sourceThreadId,
+        sessionMeta: state.sessionMeta,
+        sessionMetaLine: state.sessionMetaLine,
+        tasks,
+        activeToolOutcomeState: state.active
+            ? serializeToolOutcomeTracker(state.active.toolOutcomeTracker)
+            : undefined,
+        sourceRecordCount: state.sourceRecordCount,
+        malformedRecordCount: state.malformedRecordCount,
+    };
+}
+function newMutableTask(turnId, record, startTimestamp) {
+    return {
+        turnId,
+        title: '未命名任务',
+        titlePriority: 0,
+        startTimestamp,
+        status: 'open',
+        sourceRecordCount: 1,
+        toolCallCount: 0,
+        toolFailureCount: 0,
+        startOffset: record.startOffset,
+        endOffset: record.endOffset,
+        startLine: record.line,
+        endLine: record.line,
+        toolOutcomeTracker: createToolOutcomeTracker(),
+    };
+}
+function mutableTask(task, activeToolOutcomeState) {
+    return {
+        ...task,
+        titlePriority: task.title === '未命名任务' ? 0 : 1,
+        toolOutcomeTracker: createToolOutcomeTracker(activeToolOutcomeState),
+    };
+}
+export function isCurrentCodexRolloutIndex(value, sourcePath) {
+    const candidate = objectValue(value);
+    if (!candidate || candidate.schemaVersion !== INDEX_SCHEMA_VERSION || candidate.sourcePath !== sourcePath)
+        return false;
+    const sourceSize = numberValue(candidate.sourceSize);
+    const indexedSize = numberValue(candidate.indexedSize);
+    const indexedLineCount = numberValue(candidate.indexedLineCount);
+    if (sourceSize === undefined || indexedSize === undefined || indexedLineCount === undefined
+        || typeof candidate.indexedEndsWithNewline !== 'boolean')
+        return false;
+    if (indexedSize > sourceSize || !Array.isArray(candidate.tasks))
+        return false;
+    try {
+        const current = statSync(sourcePath);
+        return sourceSize === current.size
+            && candidate.sourceMtimeMs === current.mtimeMs
+            && indexedSize <= current.size;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Codex rollouts are append-only while a conversation is active. A prefix
+ * index remains internally consistent even after newer records are appended.
+ */
+export function isReusableCodexRolloutIndex(value, sourcePath) {
+    const candidate = objectValue(value);
+    if (!candidate || candidate.schemaVersion !== INDEX_SCHEMA_VERSION || candidate.sourcePath !== sourcePath)
+        return false;
+    if (!Array.isArray(candidate.tasks))
+        return false;
+    try {
+        const current = statSync(sourcePath);
+        const sourceSize = numberValue(candidate.sourceSize);
+        const sourceMtimeMs = numberValue(candidate.sourceMtimeMs);
+        const indexedSize = numberValue(candidate.indexedSize);
+        const indexedLineCount = numberValue(candidate.indexedLineCount);
+        if (sourceSize === undefined || sourceMtimeMs === undefined
+            || indexedSize === undefined || indexedLineCount === undefined
+            || typeof candidate.indexedEndsWithNewline !== 'boolean')
+            return false;
+        if (indexedSize > sourceSize || sourceSize > current.size)
+            return false;
+        if (current.size === sourceSize)
+            return current.mtimeMs === sourceMtimeMs;
+        return current.size > sourceSize && current.mtimeMs >= sourceMtimeMs;
+    }
+    catch {
+        return false;
+    }
+}
+export function readCodexTaskRecords(index, task) {
+    const records = [];
+    if (index.sessionMeta !== undefined && index.sessionMetaLine !== undefined) {
+        records[index.sessionMetaLine] = index.sessionMeta;
+    }
+    const lines = [];
+    let malformedRecordCount = 0;
+    forEachJsonlLine(index.sourcePath, (record) => {
+        if (record.endOffset <= task.startOffset || record.startOffset >= task.endOffset)
+            return;
+        lines.push(record);
+        try {
+            records[record.line] = JSON.parse(record.text);
+        }
+        catch {
+            malformedRecordCount += 1;
+        }
+    }, task.startOffset, task.endOffset, task.startLine);
+    return { records, lines, malformedRecordCount };
+}
+function finalizeSupersededTask(task, endOffset, endLine, endTimestamp) {
+    return stripMutable({
+        ...task,
+        status: 'unknown',
+        endTimestamp: task.endTimestamp ?? endTimestamp,
+        endOffset: Math.max(task.endOffset, endOffset),
+        endLine: Math.max(task.endLine, endLine),
+    });
+}
+function stripMutable({ titlePriority: _titlePriority, toolOutcomeTracker: _toolOutcomeTracker, ...task }) {
+    return task;
+}
+function includeRecord(task, record) {
+    if (!task)
+        return;
+    task.sourceRecordCount += 1;
+    task.endOffset = record.endOffset;
+    task.endLine = record.line;
+}
+function isIndexRelevantLine(line) {
+    return line.includes('"type":"session_meta"')
+        || line.includes('"type":"task_started"')
+        || line.includes('"type":"task_complete"')
+        || line.includes('"type":"turn_aborted"')
+        || line.includes('"type":"turn_interrupted"')
+        || line.includes('"type":"user_message"')
+        || line.includes('"type":"message"')
+        || line.includes('"type":"function_call"')
+        || line.includes('"type":"custom_tool_call"')
+        || line.includes('"type":"local_shell_call"')
+        || line.includes('"type":"function_call_output"')
+        || line.includes('"type":"custom_tool_call_output"')
+        || line.includes('"type":"mcp_tool_call_end"')
+        || line.includes('"type":"patch_apply_end"');
+}
+function isToolCallPayload(payloadType) {
+    return payloadType === 'function_call'
+        || payloadType === 'custom_tool_call'
+        || payloadType === 'local_shell_call';
+}
+function isUserPromptRecord(recordType, payloadType, payload) {
+    return (recordType === 'event_msg' && payloadType === 'user_message')
+        || (recordType === 'response_item' && payloadType === 'message' && payload.role === 'user');
+}
+function userPromptPriority(recordType, payloadType) {
+    return recordType === 'event_msg' && payloadType === 'user_message' ? 2 : 1;
+}
+function userPromptText(payload) {
+    const direct = stringValue(payload.message) ?? stringValue(payload.content);
+    if (direct)
+        return direct;
+    if (!Array.isArray(payload.content))
+        return undefined;
+    const parts = payload.content.flatMap((value) => {
+        const item = objectValue(value);
+        const text = item ? stringValue(item.text) : undefined;
+        return text ? [text] : [];
+    });
+    return parts.length > 0 ? parts.join('\n') : undefined;
+}
+function recordToolOutcome(task, record, recordType, payloadType, payload) {
+    if (recordType === 'response_item'
+        && (payloadType === 'function_call_output' || payloadType === 'custom_tool_call_output')) {
+        const callId = stringValue(payload.call_id) ?? stringValue(payload.id) ?? `result:${record.line}`;
+        const occurrence = takeToolOccurrence(task.toolOutcomeTracker.resultOccurrences, callId);
+        updateToolOutcome(task, toolOccurrenceKey(callId, occurrence), 'outputStatus', codexToolOutputOutcome(payload.output, payload.status).status);
+        return;
+    }
+    if (recordType !== 'event_msg'
+        || (payloadType !== 'mcp_tool_call_end' && payloadType !== 'patch_apply_end'))
+        return;
+    const callId = stringValue(payload.call_id) ?? stringValue(payload.id) ?? `runtime:${record.line}`;
+    const occurrence = takeToolOccurrence(task.toolOutcomeTracker.runtimeOccurrences, callId);
+    ensureRepresentedToolCall(task, callId, occurrence);
+    const outcome = codexRuntimeToolOutcomeFromPayload(payloadType, payload);
+    if (!outcome.present)
+        return;
+    updateToolOutcome(task, toolOccurrenceKey(callId, occurrence), 'runtimeStatus', outcome.status);
+}
+function recordToolCall(task, record, payload) {
+    const callId = stringValue(payload.call_id) ?? stringValue(payload.id) ?? `call:${record.line}`;
+    takeToolOccurrence(task.toolOutcomeTracker.callOccurrences, callId);
+    task.toolCallCount += 1;
+}
+/** Match Trace IR's contract: a standalone runtime end still represents one tool call. */
+function ensureRepresentedToolCall(task, callId, occurrence) {
+    const representedCount = task.toolOutcomeTracker.callOccurrences.get(callId) ?? 0;
+    const requiredCount = occurrence + 1;
+    if (representedCount >= requiredCount)
+        return;
+    task.toolOutcomeTracker.callOccurrences.set(callId, requiredCount);
+    task.toolCallCount += requiredCount - representedCount;
+}
+function updateToolOutcome(task, key, source, status) {
+    const previous = task.toolOutcomeTracker.outcomes.get(key) ?? {};
+    const wasFailure = resolvedToolStatus(previous) === 'failure';
+    const next = { ...previous, [source]: status };
+    task.toolOutcomeTracker.outcomes.set(key, next);
+    const isFailure = resolvedToolStatus(next) === 'failure';
+    if (wasFailure !== isFailure)
+        task.toolFailureCount += isFailure ? 1 : -1;
+}
+function resolvedToolStatus(outcome) {
+    return outcome.runtimeStatus ?? outcome.outputStatus ?? 'unknown';
+}
+function takeToolOccurrence(counts, callId) {
+    const occurrence = counts.get(callId) ?? 0;
+    counts.set(callId, occurrence + 1);
+    return occurrence;
+}
+function toolOccurrenceKey(callId, occurrence) {
+    return `${callId}\u0000${occurrence}`;
+}
+function createToolOutcomeTracker(state) {
+    return {
+        callOccurrences: new Map(state?.callOccurrences ?? []),
+        resultOccurrences: new Map(state?.resultOccurrences ?? []),
+        runtimeOccurrences: new Map(state?.runtimeOccurrences ?? []),
+        outcomes: new Map(state?.outcomes ?? []),
+    };
+}
+function serializeToolOutcomeTracker(tracker) {
+    return {
+        callOccurrences: [...tracker.callOccurrences],
+        resultOccurrences: [...tracker.resultOccurrences],
+        runtimeOccurrences: [...tracker.runtimeOccurrences],
+        outcomes: [...tracker.outcomes],
+    };
+}
+function compactTitle(value) {
+    return (codexUserDisplayText(value) ?? '').replace(/\s+/gu, ' ').trim().slice(0, 180);
+}
+function objectValue(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function forEachJsonlLine(filePath, visit, startOffset = 0, endOffset = Number.POSITIVE_INFINITY, startLine = 0) {
+    const fd = openSync(filePath, 'r');
+    const buffer = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+    let absoluteOffset = startOffset;
+    let lineStartOffset = startOffset;
+    let lineNumber = startLine;
+    let indexedSize = startOffset;
+    let indexedLineCount = startLine;
+    let indexedEndsWithNewline = true;
+    let fragments = [];
+    try {
+        while (absoluteOffset < endOffset) {
+            const requestBytes = Math.min(buffer.length, endOffset - absoluteOffset);
+            const bytesRead = readSync(fd, buffer, 0, requestBytes, absoluteOffset);
+            if (bytesRead === 0)
+                break;
+            let cursor = 0;
+            for (let index = 0; index < bytesRead; index += 1) {
+                if (buffer[index] !== 0x0a)
+                    continue;
+                const tail = buffer.subarray(cursor, index);
+                const lineBuffer = fragments.length > 0
+                    ? Buffer.concat([...fragments, tail])
+                    : tail;
+                const nextOffset = absoluteOffset + index + 1;
+                emitLine(lineBuffer, lineNumber, lineStartOffset, nextOffset, visit);
+                indexedSize = nextOffset;
+                indexedLineCount = lineNumber + 1;
+                indexedEndsWithNewline = true;
+                fragments = [];
+                cursor = index + 1;
+                lineStartOffset = nextOffset;
+                lineNumber += 1;
+            }
+            if (cursor < bytesRead)
+                fragments.push(Buffer.from(buffer.subarray(cursor, bytesRead)));
+            if (fragments.reduce((sum, item) => sum + item.length, 0) > MAX_RECORD_BYTES) {
+                throw new Error(`Codex JSONL 单条记录超过 ${MAX_RECORD_BYTES} 字节上限：${filePath}`);
+            }
+            absoluteOffset += bytesRead;
+        }
+        if (fragments.length > 0) {
+            const trailing = Buffer.concat(fragments);
+            if (isCompleteJsonRecord(trailing)) {
+                emitLine(trailing, lineNumber, lineStartOffset, absoluteOffset, visit);
+                indexedSize = absoluteOffset;
+                indexedLineCount = lineNumber + 1;
+                indexedEndsWithNewline = false;
+            }
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    return { indexedSize, indexedLineCount, indexedEndsWithNewline };
+}
+function isCompleteJsonRecord(buffer) {
+    const text = buffer.toString('utf8').trim();
+    if (!text)
+        return false;
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function emitLine(buffer, line, startOffset, endOffset, visit) {
+    const text = buffer.toString('utf8').trim();
+    if (!text)
+        return;
+    visit({ text, line, startOffset, endOffset });
+}

package/dist/observability/codex-protocol.d.ts

@@ -0,0 +1,12 @@
+/** Stable inventory of Codex rollout record shapes understood by OMK. */
+export declare function isCodexResponseItemType(value: string | undefined): boolean;
+export declare function isCodexEventMessageType(value: string | undefined): boolean;
+/** Preserve source text separately while removing Codex UI transport envelopes from semantic display. */
+export declare function codexUserDisplayText(text: string): string | undefined;
+export declare function codexUserMessageOrigin(text: string): 'human' | 'runtime';
+/**
+ * Records consumed by correlation or retained only as source provenance do not
+ * emit a standalone Trace IR event. Keeping this inventory explicit preserves
+ * `unknown` as a forward-compatibility warning.
+ */
+export declare function isCodexRecordConsumedWithoutDirectEvent(recordType: unknown, payloadType: string | undefined): boolean;

package/dist/observability/codex-protocol.js

@@ -0,0 +1,78 @@
+/** Stable inventory of Codex rollout record shapes understood by OMK. */
+const RESPONSE_ITEM_TYPES = new Set([
+    'message',
+    'reasoning',
+    'tool_search_call',
+    'tool_search_output',
+    'web_search_call',
+    'image_generation_call',
+    'function_call',
+    'custom_tool_call',
+    'function_call_output',
+    'custom_tool_call_output',
+    'agent_message',
+]);
+const EVENT_MESSAGE_TYPES = new Set([
+    'token_count',
+    'task_started',
+    'task_complete',
+    'turn_aborted',
+    'turn_interrupted',
+    'user_message',
+    'agent_message',
+    'mcp_tool_call_end',
+    'patch_apply_end',
+    'agent_reasoning',
+    'thread_settings_applied',
+    'web_search_end',
+    'context_compacted',
+    'image_generation_end',
+    'thread_goal_updated',
+    'sub_agent_activity',
+]);
+const IN_APP_BROWSER_CONTEXT_RE = /<in-app-browser-context\b[^>]*>[\s\S]*?<\/in-app-browser-context>/gi;
+const CODEX_RUNTIME_MESSAGE_RE = /^# AGENTS\.md instructions\b|^<(?:app-context|environment_context|permissions instructions|collaboration_mode|apps_instructions|plugins_instructions|skills_instructions|recommended_plugins)>/i;
+export function isCodexResponseItemType(value) {
+    return value !== undefined && RESPONSE_ITEM_TYPES.has(value);
+}
+export function isCodexEventMessageType(value) {
+    return value !== undefined && EVENT_MESSAGE_TYPES.has(value);
+}
+/** Preserve source text separately while removing Codex UI transport envelopes from semantic display. */
+export function codexUserDisplayText(text) {
+    const requestHeading = /^## My request for Codex:\s*$/im;
+    const requestMatch = requestHeading.exec(text);
+    const request = requestMatch
+        ? text.slice(requestMatch.index + requestMatch[0].length)
+        : text;
+    const visible = request
+        .replace(IN_APP_BROWSER_CONTEXT_RE, ' ')
+        .replace(/<image\b[^>]*>[\s\S]*?<\/image>/gi, ' ')
+        .replace(/\[Image\s+#\d+\]/gi, ' ')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return visible || undefined;
+}
+export function codexUserMessageOrigin(text) {
+    const trimmed = text.trimStart();
+    if (CODEX_RUNTIME_MESSAGE_RE.test(trimmed))
+        return 'runtime';
+    if (/^<in-app-browser-context\b/i.test(trimmed) && !codexUserDisplayText(text))
+        return 'runtime';
+    return 'human';
+}
+/**
+ * Records consumed by correlation or retained only as source provenance do not
+ * emit a standalone Trace IR event. Keeping this inventory explicit preserves
+ * `unknown` as a forward-compatibility warning.
+ */
+export function isCodexRecordConsumedWithoutDirectEvent(recordType, payloadType) {
+    if (recordType === 'world_state')
+        return true;
+    if (recordType === 'inter_agent_communication_metadata')
+        return true;
+    if (recordType !== 'event_msg')
+        return false;
+    return payloadType === 'web_search_end'
+        || payloadType === 'image_generation_end';
+}

package/dist/observability/codex-tool-status.d.ts

@@ -0,0 +1,16 @@
+import type { TraceToolStatus } from './trace-ir.js';
+export interface CodexToolOutcome {
+    status: TraceToolStatus;
+    present: boolean;
+}
+/** Normalize Codex status values before source adapters project Trace IR. */
+export declare function codexToolStatusFromValue(value: unknown): TraceToolStatus;
+/** Runtime end records are authoritative even when they only expose an Ok/Err envelope. */
+export declare function codexRuntimeToolOutcome(end: {
+    status?: unknown;
+    isError?: boolean;
+} | undefined): CodexToolOutcome;
+/** Extract the same authoritative outcome from a raw Codex runtime-end payload. */
+export declare function codexRuntimeToolOutcomeFromPayload(payloadType: string | undefined, payload: Record<string, unknown>): CodexToolOutcome;
+/** Infer bridge output status only when Codex did not record an explicit status. */
+export declare function codexToolOutputOutcome(output: unknown, explicitStatus?: unknown): CodexToolOutcome;