oh-my-knowledge 0.51.2 → 0.52.1

package/dist/observability/source-record-archive.js

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import { writeJsonFileAtomic } from '../shared/atomic-json.js';
+import { normalizeTraceTimestamp } from './trace-ir.js';
+import { forEachNonEmptyUtf8Line } from './trace-source.js';
+const ARCHIVE_SCHEMA_VERSION = 1;
+const MAX_ARCHIVE_SOURCE_BYTES = 16 * 1024 * 1024;
+const MAX_ARCHIVE_FILE_BYTES = 64 * 1024 * 1024;
+const MAX_RECORD_CHARS = 512 * 1024;
+/**
+ * Persist bounded source records beside a report. Absolute source paths are
+ * consumed only during trusted ingest; Studio later reads relative sidecars.
+ */
+export function writeObservationSourceRecordArchives(report, outDir, reportPath) {
+    const sessions = report.experience?.sessions ?? [];
+    if (sessions.length === 0)
+        return [];
+    const reportStem = basename(reportPath).replace(/\.report\.json$/u, '');
+    const archiveDir = join(outDir, 'source-records', reportStem);
+    const builders = sessions.map((session) => ({
+        session,
+        groupedRanges: groupRecordRanges(session.timelineScope.sessionRecordRanges),
+        records: [],
+        omittedRecordCount: 0,
+        byteCount: 0,
+        truncated: false,
+    }));
+    const targetsBySource = new Map();
+    for (const builder of builders) {
+        for (const [sourceTrace, ranges] of builder.groupedRanges) {
+            const targets = targetsBySource.get(sourceTrace) ?? [];
+            targets.push({
+                builder,
+                ranges,
+                expectedCount: ranges.reduce((sum, range) => sum + range.end - range.start + 1, 0),
+                matchedCount: 0,
+                rangeIndex: 0,
+            });
+            targetsBySource.set(sourceTrace, targets);
+        }
+    }
+    for (const [sourceTrace, targets] of targetsBySource) {
+        collectSourceRecords(sourceTrace, targets);
+    }
+    return builders.map((builder) => persistSessionArchive(builder, archiveDir, outDir, report.meta.generatedAt));
+}
+export function loadObservationSourceRecordArchive(ref, observationsDir) {
+    if (!ref || ref.status === 'unavailable' || !ref.relativePath) {
+        return unavailableView(ref?.reason ?? 'no_record_ranges');
+    }
+    const path = safeArchivePath(observationsDir, ref.relativePath);
+    if (!path || !existsSync(path))
+        return unavailableView('archive_invalid');
+    try {
+        if (statSync(path).size > MAX_ARCHIVE_FILE_BYTES)
+            return unavailableView('archive_invalid');
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!isObservationSourceRecordArchive(parsed, ref.experienceSessionId)) {
+            return unavailableView('archive_invalid');
+        }
+        return {
+            status: ref.status,
+            recordCount: parsed.records.length,
+            records: parsed.records,
+            omittedRecordCount: parsed.omittedRecordCount,
+            byteCount: parsed.byteCount,
+            truncated: parsed.truncated,
+            ...(ref.reason ? { reason: ref.reason } : {}),
+        };
+    }
+    catch {
+        return unavailableView('archive_invalid');
+    }
+}
+/**
+ * Build the page-safe archive metadata without reading the potentially large
+ * sidecar. The source-record endpoint resolves the same ref on demand.
+ */
+export function summarizeObservationSourceRecordArchive(ref) {
+    if (!ref)
+        return unavailableView('no_record_ranges');
+    return {
+        status: ref.status,
+        recordCount: ref.recordCount,
+        records: [],
+        omittedRecordCount: ref.omittedRecordCount,
+        byteCount: ref.byteCount,
+        truncated: ref.truncated,
+        ...(ref.reason ? { reason: ref.reason } : {}),
+    };
+}
+function collectSourceRecords(sourceTrace, targets) {
+    if (extname(sourceTrace).toLowerCase() !== '.jsonl') {
+        markSourceUnavailable(targets, 'unsupported_source');
+        return;
+    }
+    if (!existsSync(sourceTrace)) {
+        markSourceUnavailable(targets, 'source_missing');
+        return;
+    }
+    const maxEnd = targets.reduce((targetMax, target) => target.ranges.reduce((rangeMax, range) => Math.max(rangeMax, range.end), targetMax), -1);
+    let sourceIndex = 0;
+    try {
+        forEachNonEmptyUtf8Line(sourceTrace, (line) => {
+            const currentIndex = sourceIndex;
+            sourceIndex += 1;
+            const recordsByTraceId = new Map();
+            for (const target of targets) {
+                while (target.ranges[target.rangeIndex]
+                    && target.ranges[target.rangeIndex].end < currentIndex) {
+                    target.rangeIndex += 1;
+                }
+                const range = target.ranges[target.rangeIndex];
+                if (!range || currentIndex < range.start || currentIndex > range.end)
+                    continue;
+                target.matchedCount += 1;
+                if (target.builder.byteCount >= MAX_ARCHIVE_SOURCE_BYTES) {
+                    target.builder.omittedRecordCount += 1;
+                    target.builder.truncated = true;
+                    target.builder.failure = 'archive_limit';
+                    continue;
+                }
+                let record = recordsByTraceId.get(range.traceId);
+                if (!record) {
+                    record = observationSourceRecordFromLine(line, currentIndex, range.traceId, sourceTrace);
+                    recordsByTraceId.set(range.traceId, record);
+                }
+                if (target.builder.byteCount + record.byteCount > MAX_ARCHIVE_SOURCE_BYTES) {
+                    target.builder.omittedRecordCount += 1;
+                    target.builder.truncated = true;
+                    target.builder.failure = 'archive_limit';
+                    continue;
+                }
+                target.builder.records.push(record);
+                target.builder.byteCount += record.byteCount;
+                target.builder.truncated ||= record.truncated;
+            }
+            return currentIndex < maxEnd;
+        });
+    }
+    catch {
+        for (const target of targets)
+            target.builder.failure ??= 'read_failed';
+    }
+    for (const target of targets) {
+        target.builder.omittedRecordCount += Math.max(0, target.expectedCount - target.matchedCount);
+    }
+}
+function markSourceUnavailable(targets, reason) {
+    for (const target of targets) {
+        target.builder.omittedRecordCount += target.expectedCount;
+        target.builder.failure ??= reason;
+    }
+}
+function persistSessionArchive(builder, archiveDir, outDir, generatedAt) {
+    const { session, records, omittedRecordCount, byteCount, failure } = builder;
+    if (builder.groupedRanges.size === 0)
+        return unavailableRef(session.id, 'no_record_ranges');
+    if (records.length === 0)
+        return unavailableRef(session.id, failure ?? 'read_failed', omittedRecordCount);
+    const archive = {
+        archiveKind: 'observe-source-records',
+        schemaVersion: ARCHIVE_SCHEMA_VERSION,
+        experienceSessionId: session.id,
+        generatedAt,
+        records,
+        omittedRecordCount,
+        byteCount,
+        truncated: builder.truncated || omittedRecordCount > 0,
+    };
+    const fileName = `${createHash('sha256').update(session.id).digest('hex').slice(0, 24)}.json`;
+    const archivePath = join(archiveDir, fileName);
+    writeJsonFileAtomic(archivePath, archive);
+    const relativePath = relative(outDir, archivePath).split('\\').join('/');
+    const partial = archive.truncated || failure !== undefined;
+    return {
+        experienceSessionId: session.id,
+        status: partial ? 'partial' : 'available',
+        relativePath,
+        recordCount: records.length,
+        omittedRecordCount,
+        byteCount,
+        truncated: archive.truncated,
+        ...(failure ? { reason: failure } : {}),
+    };
+}
+export function observationSourceRecordFromLine(line, sourceIndex, traceId, sourceTrace) {
+    let record = {};
+    let serialized = line;
+    let redacted = false;
+    try {
+        const parsed = JSON.parse(line);
+        if (isRecord(parsed)) {
+            record = parsed;
+            serialized = JSON.stringify(parsed, (key, value) => {
+                if (key !== 'encrypted_content')
+                    return value;
+                redacted = true;
+                return '[opaque encrypted content omitted]';
+            });
+        }
+    }
+    catch {
+        // Malformed source lines are still useful provenance.
+    }
+    const payload = isRecord(record.payload) ? record.payload : {};
+    const recordType = textValue(record.type) ?? 'unknown';
+    const payloadType = textValue(payload.type);
+    const raw = serialized.length > MAX_RECORD_CHARS ? serialized.slice(0, MAX_RECORD_CHARS) : serialized;
+    return {
+        sourceIndex,
+        traceId,
+        sourceTrace,
+        sourceType: `${recordType}:${payloadType ?? ''}`,
+        sourceEventId: textValue(payload.id),
+        timestamp: normalizeTraceTimestamp(record.timestamp),
+        raw,
+        byteCount: Buffer.byteLength(raw),
+        truncated: raw.length < serialized.length,
+        redacted,
+    };
+}
+function groupRecordRanges(ranges) {
+    const grouped = new Map();
+    for (const range of ranges) {
+        const current = grouped.get(range.sourceTrace) ?? [];
+        current.push({ start: range.startRecordIndex, end: range.endRecordIndex, traceId: range.traceId });
+        grouped.set(range.sourceTrace, current);
+    }
+    for (const [sourceTrace, sourceRanges] of grouped) {
+        const sorted = sourceRanges.sort((a, b) => a.start - b.start || a.end - b.end);
+        const merged = [];
+        for (const range of sorted) {
+            const previous = merged.at(-1);
+            if (previous && previous.traceId === range.traceId && range.start <= previous.end + 1) {
+                previous.end = Math.max(previous.end, range.end);
+            }
+            else {
+                merged.push({ ...range });
+            }
+        }
+        grouped.set(sourceTrace, merged);
+    }
+    return grouped;
+}
+function safeArchivePath(observationsDir, relativePath) {
+    if (!relativePath || isAbsolute(relativePath))
+        return undefined;
+    const candidate = resolve(observationsDir, relativePath);
+    const lexicalRelative = relative(resolve(observationsDir), candidate);
+    if (lexicalRelative.startsWith('..') || isAbsolute(lexicalRelative))
+        return undefined;
+    try {
+        const root = realpathSync(observationsDir);
+        const resolved = realpathSync(candidate);
+        const resolvedRelative = relative(root, resolved);
+        if (resolvedRelative.startsWith('..') || isAbsolute(resolvedRelative))
+            return undefined;
+        return resolved;
+    }
+    catch {
+        return undefined;
+    }
+}
+function unavailableRef(experienceSessionId, reason, omittedRecordCount = 0) {
+    return {
+        experienceSessionId,
+        status: 'unavailable',
+        recordCount: 0,
+        omittedRecordCount,
+        byteCount: 0,
+        truncated: omittedRecordCount > 0,
+        reason,
+    };
+}
+function unavailableView(reason) {
+    return {
+        status: 'unavailable',
+        recordCount: 0,
+        records: [],
+        omittedRecordCount: 0,
+        byteCount: 0,
+        truncated: false,
+        reason,
+    };
+}
+function isObservationSourceRecordArchive(value, experienceSessionId) {
+    if (!isRecord(value)
+        || value.archiveKind !== 'observe-source-records'
+        || value.schemaVersion !== ARCHIVE_SCHEMA_VERSION
+        || value.experienceSessionId !== experienceSessionId
+        || typeof value.generatedAt !== 'string'
+        || !Array.isArray(value.records)
+        || !value.records.every(isObservationSourceRecord)
+        || !isCount(value.omittedRecordCount)
+        || !isCount(value.byteCount)
+        || typeof value.truncated !== 'boolean')
+        return false;
+    return value.records.reduce((sum, record) => sum + record.byteCount, 0) === value.byteCount;
+}
+function isObservationSourceRecord(value) {
+    return isRecord(value)
+        && isCount(value.sourceIndex)
+        && typeof value.traceId === 'string'
+        && typeof value.sourceTrace === 'string'
+        && typeof value.sourceType === 'string'
+        && (value.sourceEventId === undefined || typeof value.sourceEventId === 'string')
+        && (value.timestamp === undefined || typeof value.timestamp === 'string')
+        && typeof value.raw === 'string'
+        && isCount(value.byteCount)
+        && Buffer.byteLength(value.raw) === value.byteCount
+        && typeof value.truncated === 'boolean'
+        && typeof value.redacted === 'boolean';
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isCount(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function textValue(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}

package/dist/observability/task-window.d.ts

@@ -0,0 +1,8 @@
+import type { ExperienceTimelineEvent, TaskTrajectorySession, TaskWindowScope } from '../types/index.js';
+export declare const TASK_SEMANTIC_EVENT_LIMIT = 240;
+export interface ResolvedTaskWindow {
+    events: ExperienceTimelineEvent[];
+    semanticEvents: ExperienceTimelineEvent[];
+    scope: TaskWindowScope;
+}
+export declare function resolveTaskWindow(session: TaskTrajectorySession, targetTurnId: string, semanticLimit?: number): ResolvedTaskWindow;

package/dist/observability/task-window.js

@@ -0,0 +1,36 @@
+export const TASK_SEMANTIC_EVENT_LIMIT = 240;
+export function resolveTaskWindow(session, targetTurnId, semanticLimit = TASK_SEMANTIC_EVENT_LIMIT) {
+    const events = session.fullSessionTimeline;
+    const attributedIds = new Set(session.attributedEventIds);
+    const attributed = events.filter((event) => attributedIds.has(event.id));
+    const selected = session.turns.find((turn) => turn.turnId === targetTurnId);
+    const eventById = new Map(events.map((event) => [event.id, event]));
+    const taskEvents = selected
+        ? selected.eventIds.flatMap((id) => {
+            const event = eventById.get(id);
+            return event ? [event] : [];
+        })
+        : [];
+    const semanticEvents = semanticPreview(taskEvents, semanticLimit);
+    const matchedAttributedEventCount = taskEvents.filter((event) => attributedIds.has(event.id)).length;
+    return {
+        events: taskEvents,
+        semanticEvents,
+        scope: {
+            basis: selected?.boundaryBasis ?? 'unresolved',
+            turnId: selected?.turnId,
+            normalizedEventCount: taskEvents.length,
+            semanticEventCount: semanticEvents.length,
+            attributedEventCount: attributed.length,
+            matchedAttributedEventCount,
+            truncated: semanticEvents.length < taskEvents.length,
+        },
+    };
+}
+function semanticPreview(events, limit) {
+    if (events.length <= limit)
+        return events;
+    const headCount = Math.ceil(limit * 0.6);
+    const tailCount = limit - headCount;
+    return [...events.slice(0, headCount), ...events.slice(-tailCount)];
+}

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

@@ -7,6 +7,11 @@ export type TraceMessageRole = 'user' | 'assistant' | 'system';
 export type TraceMessageOrigin = 'human' | 'runtime' | 'skill-context' | 'synthetic';
 export type TraceToolStatus = ToolCallStatus;
 export type TraceToolStatusSource = ToolCallStatusSource;
+export type TraceModelActivityKind = 'reasoning';
+export type TraceModelActivityVisibility = 'plaintext' | 'opaque';
+export type TraceModelActivityContentSource = 'summary' | 'content' | 'text';
+export type TraceRuntimeContextKind = 'session_context' | 'execution_context' | 'settings' | 'goal';
+export type TraceAgentActivityKind = 'communication' | 'status';
 /** Source-neutral tool identity, including provider namespaces when present. */
 export type TraceToolRef = NormalizedToolIdentity;
 interface TraceEventBase {
@@ -23,6 +28,8 @@ export interface TraceMessageEvent extends TraceEventBase {
     role: TraceMessageRole;
     origin: TraceMessageOrigin;
     text: string;
+    /** Human-facing text after a source adapter removes transport/UI envelopes. */
+    displayText?: string;
     model?: string;
     attributionSkill?: string;
 }
@@ -51,17 +58,75 @@ export interface TraceUsageEvent extends TraceEventBase {
     cacheCreationTokens: number;
     reasoningTokens?: number;
 }
+export interface TraceModelActivityEvent extends TraceEventBase {
+    eventKind: 'model_activity';
+    activityKind: TraceModelActivityKind;
+    contentVisibility: TraceModelActivityVisibility;
+    text?: string;
+    contentSource?: TraceModelActivityContentSource;
+    model?: string;
+}
 export interface TraceLifecycleEvent extends TraceEventBase {
     eventKind: 'lifecycle';
     phase: 'session_started' | 'session_ended' | 'turn_started' | 'turn_completed' | 'turn_aborted' | 'turn_interrupted';
     reason?: string;
     durationMs?: number;
 }
+/** Source-neutral execution context visible to the agent for a turn or run. */
+export interface TraceRuntimeContextEvent extends TraceEventBase {
+    eventKind: 'runtime_context';
+    runtimeKind: TraceRuntimeContextKind;
+    runtimeName?: string;
+    runtimeVersion?: string;
+    cwd?: string;
+    workspaceRoots?: string[];
+    currentDate?: string;
+    timezone?: string;
+    model?: string;
+    modelProvider?: string;
+    serviceTier?: string;
+    reasoningEffort?: string;
+    reasoningSummary?: string;
+    personality?: string;
+    approvalPolicy?: string;
+    approvalReviewer?: string;
+    permissionProfile?: string;
+    sandboxMode?: string;
+    collaborationMode?: string;
+    realtimeActive?: boolean;
+    multiAgentMode?: string;
+    multiAgentVersion?: string;
+    memoryMode?: string;
+    historyMode?: string;
+    contextWindowId?: string;
+    availableTools?: string[];
+    instructions?: string;
+    goal?: string;
+    goalStatus?: string;
+    summary?: string;
+}
+/** A source-reported context-window compaction boundary. */
+export interface TraceContextCompactionEvent extends TraceEventBase {
+    eventKind: 'context_compaction';
+    summary?: string;
+    replacementItemCount?: number;
+}
+/** Observable communication or status emitted by a cooperating agent. */
+export interface TraceAgentActivityEvent extends TraceEventBase {
+    eventKind: 'agent_activity';
+    activityKind: TraceAgentActivityKind;
+    agentId?: string;
+    agentPath?: string;
+    activity?: string;
+    author?: string;
+    recipient?: string;
+    text?: string;
+}
 export interface TraceUnknownEvent extends TraceEventBase {
     eventKind: 'unknown';
     raw?: unknown;
 }
-export type TraceEvent = TraceMessageEvent | TraceToolCallEvent | TraceToolResultEvent | TraceUsageEvent | TraceLifecycleEvent | TraceUnknownEvent;
+export type TraceEvent = TraceMessageEvent | TraceToolCallEvent | TraceToolResultEvent | TraceUsageEvent | TraceModelActivityEvent | TraceLifecycleEvent | TraceRuntimeContextEvent | TraceContextCompactionEvent | TraceAgentActivityEvent | TraceUnknownEvent;
 export interface TraceSession {
     /** Concrete source run/thread identifier. */
     runId: string;

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

@@ -96,4 +96,5 @@ export declare function loadTraceSessions(path: string): TraceSession[];
 export declare function loadTraceCorpus(path: string): TraceCorpus;
 /** @deprecated Use `loadTraceSessions`. */
 export declare const loadCcSessions: typeof loadTraceSessions;
+export declare function forEachNonEmptyUtf8Line(filePath: string, visit: (trimmedLine: string) => boolean | void): void;
 export declare function legacyCcSessionToTraceSession(session: CcSession): TraceSession;

package/dist/observability/trace-source.js

@@ -333,7 +333,7 @@ function parseJsonlSessionFile(filePath) {
         },
     };
 }
-function forEachNonEmptyUtf8Line(filePath, visit) {
+export function forEachNonEmptyUtf8Line(filePath, visit) {
     let fd;
     try {
         fd = openSync(filePath, 'r');
@@ -344,30 +344,37 @@ function forEachNonEmptyUtf8Line(filePath, visit) {
     const decoder = new StringDecoder('utf8');
     const buffer = Buffer.allocUnsafe(TRACE_READ_CHUNK_BYTES);
     let pending = '';
+    let stopped = false;
     const consumeCompleteLines = () => {
         let newline = pending.indexOf('\n');
-        while (newline >= 0) {
+        while (newline >= 0 && !stopped) {
             if (newline > MAX_JSONL_RECORD_CHARS) {
                 throw new Error(`trace JSONL 单条记录超过 ${MAX_JSONL_RECORD_CHARS} 字符上限：${filePath}`);
             }
             const trimmed = pending.slice(0, newline).trim();
             pending = pending.slice(newline + 1);
-            if (trimmed)
-                visit(trimmed);
+            if (trimmed && visit(trimmed) === false) {
+                stopped = true;
+                return;
+            }
             newline = pending.indexOf('\n');
         }
+        if (stopped)
+            return;
         if (pending.length > MAX_JSONL_RECORD_CHARS) {
             throw new Error(`trace JSONL 单条记录超过 ${MAX_JSONL_RECORD_CHARS} 字符上限：${filePath}`);
         }
     };
     try {
-        while (true) {
+        while (!stopped) {
             const bytesRead = readSync(fd, buffer, 0, buffer.length, null);
             if (bytesRead === 0)
                 break;
             pending += decoder.write(buffer.subarray(0, bytesRead));
             consumeCompleteLines();
         }
+        if (stopped)
+            return;
         pending += decoder.end();
         consumeCompleteLines();
         const trimmed = pending.trim();

package/dist/observability/turn-index.d.ts

@@ -0,0 +1,3 @@
+import type { ExperienceTimelineEvent, ExperienceTurnSummary } from '../types/index.js';
+/** Reconstruct every observable task without consulting Skill attribution. */
+export declare function reconstructExperienceTurns(timeline: ExperienceTimelineEvent[]): ExperienceTurnSummary[];