oh-my-knowledge 0.51.2 → 0.52.0

package/dist/observability/knowledge-debugger.js

@@ -0,0 +1,364 @@
+import { createHash } from 'node:crypto';
+import { resolveTaskWindow } from './task-window.js';
+const AGENTS_CONTEXT_RE = /^# AGENTS\.md instructions for ([^\n]+)\n/gim;
+const SKILL_PATH_RE = /((?:~|\.{0,2}|\/)?[^\s"'`]*\/skills\/(?:\.system\/)?([^/\s"'`]+)\/SKILL\.md)\b/i;
+const MUTATING_TOOL_RE = /(?:^|[._-])(write|edit|delete|remove|move|rename|apply[_-]?patch)(?:$|[._-])/i;
+const READ_ONLY_TOOL_RE = /(?:^|[._-])(read|search|query|fetch|get|list|find|glob|grep|view|open)(?:$|[._-])/i;
+const READ_ONLY_SHELL_RE = /^\s*(?:cat|head|tail|sed\s+-n|rg|grep|find|ls|pwd|wc|stat|which|git\s+(?:status|diff|show|log|branch|rev-parse)|gh\s+(?:issue|pr|run|release|repo)\s+(?:view|list|status|checks?))\b/i;
+export function buildKnowledgeDebuggerViewModel(session, targetTurnId, ingestion, sourceRecords = {
+    status: 'unavailable',
+    recordCount: 0,
+    records: [],
+    omittedRecordCount: 0,
+    byteCount: 0,
+    truncated: false,
+    reason: 'no_record_ranges',
+}) {
+    const taskWindow = resolveTaskWindow(session, targetTurnId);
+    const normalizedEvents = taskWindow.events;
+    const timeline = taskWindow.semanticEvents.filter((event) => event.runtimeKind !== 'usage');
+    const knowledgeEvidence = projectKnowledgeEvidence(timeline);
+    const steps = buildTaskReplaySteps(session, timeline, knowledgeEvidence);
+    const notices = buildIntegrityNotices(taskWindow.scope, timeline, steps, ingestion);
+    const userEvents = timeline.filter((event) => event.kind === 'user_message');
+    const assistantEvents = timeline.filter((event) => event.kind === 'assistant_message');
+    const observedModels = timeline.reduce((models, event) => {
+        const eventModel = event.model?.trim();
+        if (eventModel && !models.includes(eventModel))
+            models.push(eventModel);
+        return models;
+    }, []);
+    return {
+        session,
+        taskScope: taskWindow.scope,
+        summary: {
+            userGoal: eventText(userEvents[0]),
+            finalResponse: eventText(assistantEvents.at(-1)),
+            observedStartTimestamp: timeline.find((event) => (event.timestamp && event.runtimeKind !== 'session_context'))?.timestamp
+                ?? timeline.find((event) => event.timestamp)?.timestamp,
+            observedEndTimestamp: [...timeline].reverse().find((event) => event.timestamp)?.timestamp,
+            toolCallCount: steps.filter((step) => step.stepKind === 'tool_exchange').length,
+            toolFailureCount: steps.filter((step) => step.stepKind === 'tool_exchange' && step.toolStatus === 'failure').length,
+            hasUserCorrection: steps.some((step) => step.stepKind === 'user_correction'),
+            observedModels,
+        },
+        steps,
+        normalizedEvents,
+        sourceRecords,
+        knowledgeEvidence,
+        integrity: {
+            status: notices.length > 0 ? 'partial' : 'complete',
+            notices,
+        },
+    };
+}
+export function buildTaskReplaySteps(session, timeline, knowledgeEvidence) {
+    const sorted = [...timeline].sort((a, b) => a.order - b.order);
+    const resultsByCall = new Map();
+    const matchedResultIds = new Set();
+    const knowledgeIdsByEvent = knowledgeEvidence.reduce((map, evidence) => {
+        for (const ref of evidence.evidenceRefs) {
+            map.set(ref.id, [...(map.get(ref.id) ?? []), evidence.id]);
+        }
+        return map;
+    }, new Map());
+    const correctionIds = correctionEventIds(session, sorted);
+    for (const event of sorted) {
+        if (event.kind !== 'tool_result')
+            continue;
+        const key = toolCorrelationKey(event);
+        resultsByCall.set(key, [...(resultsByCall.get(key) ?? []), event]);
+    }
+    const steps = [];
+    let sawUserRequest = false;
+    for (const event of sorted) {
+        if (event.kind === 'tool_result' && matchedResultIds.has(event.id))
+            continue;
+        if (event.kind === 'tool_use') {
+            const result = resultsByCall.get(toolCorrelationKey(event))?.find((item) => !matchedResultIds.has(item.id));
+            if (result)
+                matchedResultIds.add(result.id);
+            const events = result ? [event, result] : [event];
+            steps.push({
+                id: `step:${event.id}`,
+                order: event.order,
+                stepKind: 'tool_exchange',
+                timestamp: event.timestamp,
+                title: event.toolName ?? event.label ?? 'Tool call',
+                events,
+                toolStatus: result?.toolStatus ?? (result?.isError ? 'failure' : event.toolStatus ?? 'unknown'),
+                knowledgeEvidenceIds: knowledgeIdsForEvents(events, knowledgeIdsByEvent),
+            });
+            continue;
+        }
+        const stepKind = stepKindForEvent(event, sawUserRequest, correctionIds);
+        if (event.kind === 'user_message' && !sawUserRequest)
+            sawUserRequest = true;
+        steps.push({
+            id: `step:${event.id}`,
+            order: event.order,
+            stepKind,
+            timestamp: event.timestamp,
+            title: event.toolName ?? event.label ?? event.kind,
+            events: [event],
+            ...(event.kind === 'tool_result'
+                ? { toolStatus: event.toolStatus ?? (event.isError ? 'failure' : 'unknown') }
+                : {}),
+            knowledgeEvidenceIds: knowledgeIdsForEvents([event], knowledgeIdsByEvent),
+        });
+    }
+    return steps;
+}
+export function projectKnowledgeEvidence(timeline) {
+    const candidates = [];
+    const toolCalls = new Map();
+    for (const event of timeline) {
+        if (event.kind === 'tool_use') {
+            toolCalls.set(toolCorrelationKey(event), event);
+            continue;
+        }
+        if (event.kind === 'runtime_context') {
+            const text = event.fullText ?? event.snippet ?? '';
+            const agentsMatches = [...text.matchAll(AGENTS_CONTEXT_RE)];
+            for (const [index, agentsMatch] of agentsMatches.entries()) {
+                if (!agentsMatch[1])
+                    continue;
+                const sectionStart = agentsMatch.index ?? 0;
+                const sectionEnd = agentsMatches[index + 1]?.index ?? text.length;
+                const section = text.slice(sectionStart, sectionEnd).trim();
+                candidates.push({
+                    knowledgeKind: 'project_instruction',
+                    accessKind: 'injected',
+                    label: 'AGENTS.md',
+                    sourceLocator: `runtime-context:${agentsMatch[1].trim()}`,
+                    contentHash: contentHash(section),
+                    firstSeen: event.timestamp,
+                    lastSeen: event.timestamp,
+                    evidenceRef: evidenceRef(event),
+                });
+            }
+            continue;
+        }
+        if (event.kind === 'skill_context') {
+            const text = event.fullText ?? event.snippet ?? '';
+            candidates.push({
+                knowledgeKind: 'skill',
+                accessKind: 'injected',
+                label: event.label || 'Skill context',
+                contentHash: text ? contentHash(text) : undefined,
+                firstSeen: event.timestamp,
+                lastSeen: event.timestamp,
+                evidenceRef: evidenceRef(event),
+            });
+            continue;
+        }
+        if (event.kind !== 'tool_result')
+            continue;
+        const call = toolCalls.get(toolCorrelationKey(event));
+        if (!call)
+            continue;
+        const output = event.fullText ?? event.snippet ?? '';
+        if (!output.trim())
+            continue;
+        const callText = call.fullText ?? call.snippet ?? '';
+        const skillPath = SKILL_PATH_RE.exec(callText);
+        if (skillPath?.[1] && skillPath[2]) {
+            candidates.push({
+                knowledgeKind: 'skill',
+                accessKind: 'read',
+                label: skillPath[2],
+                sourceLocator: skillPath[1],
+                contentHash: contentHash(output),
+                firstSeen: event.timestamp ?? call.timestamp,
+                lastSeen: event.timestamp ?? call.timestamp,
+                evidenceRef: evidenceRef(event),
+            });
+            continue;
+        }
+        const toolName = call.toolName ?? call.label ?? 'tool';
+        if (!isKnowledgeReturningCall(toolName, callText))
+            continue;
+        candidates.push({
+            knowledgeKind: 'runtime_evidence',
+            accessKind: 'returned',
+            label: toolName,
+            sourceLocator: sourceLocator(callText),
+            contentHash: contentHash(output),
+            firstSeen: event.timestamp ?? call.timestamp,
+            lastSeen: event.timestamp ?? call.timestamp,
+            evidenceRef: evidenceRef(event),
+        });
+    }
+    return aggregateCandidates(candidates);
+}
+function isKnowledgeReturningCall(toolName, callText) {
+    if (MUTATING_TOOL_RE.test(toolName))
+        return false;
+    if (READ_ONLY_TOOL_RE.test(toolName))
+        return true;
+    const command = sourceLocator(callText);
+    return command ? READ_ONLY_SHELL_RE.test(command) : false;
+}
+function buildIntegrityNotices(taskScope, timeline, steps, ingestion) {
+    const notices = [];
+    if (taskScope.basis === 'unresolved') {
+        notices.push({ code: 'task_boundary_unavailable', count: 1 });
+    }
+    const omittedSemanticEvents = taskScope.normalizedEventCount - taskScope.semanticEventCount;
+    if (omittedSemanticEvents > 0) {
+        notices.push({ code: 'timeline_truncated', count: omittedSemanticEvents });
+    }
+    if (ingestion?.malformedRecordCount)
+        notices.push({ code: 'malformed_records', count: ingestion.malformedRecordCount });
+    if (ingestion?.ignoredValueCount)
+        notices.push({ code: 'ignored_values', count: ingestion.ignoredValueCount });
+    if (ingestion?.unknownEventCount)
+        notices.push({ code: 'unknown_events', count: ingestion.unknownEventCount });
+    const unmatchedCalls = steps.filter((step) => step.stepKind === 'tool_exchange' && step.events.length === 1).length;
+    if (unmatchedCalls > 0)
+        notices.push({ code: 'unmatched_tool_calls', count: unmatchedCalls });
+    const unmatchedResults = steps.filter((step) => step.stepKind === 'unmatched_tool_result').length;
+    if (unmatchedResults > 0)
+        notices.push({ code: 'unmatched_tool_results', count: unmatchedResults });
+    const missingTimestamps = timeline.filter((event) => !event.timestamp).length;
+    if (missingTimestamps > 0)
+        notices.push({ code: 'missing_timestamps', count: missingTimestamps });
+    return notices;
+}
+function correctionEventIds(session, timeline) {
+    const ids = new Set();
+    for (const episode of session.sessionStory?.episodes ?? []) {
+        for (const signal of episode.feedbackSignals) {
+            if (signal.type === 'correction' || signal.type === 'frustration' || signal.type === 'interruption') {
+                ids.add(signal.evidenceRef.id);
+            }
+        }
+    }
+    const userCorrectionCount = session.indicators?.userCorrectionCount ?? 0;
+    if (ids.size > 0 || userCorrectionCount === 0)
+        return ids;
+    const lastAssistantOrder = Math.max(-1, ...timeline.filter((event) => event.kind === 'assistant_message').map((event) => event.order));
+    const correctionCandidates = timeline
+        .filter((event) => event.kind === 'user_message' && event.order > lastAssistantOrder)
+        .slice(-userCorrectionCount);
+    for (const event of correctionCandidates)
+        ids.add(event.id);
+    return ids;
+}
+function stepKindForEvent(event, sawUserRequest, correctionIds) {
+    if (event.kind === 'user_message') {
+        if (correctionIds.has(event.id))
+            return 'user_correction';
+        return sawUserRequest ? 'user_message' : 'user_request';
+    }
+    if (event.kind === 'assistant_message')
+        return 'assistant_message';
+    if (event.kind === 'model_activity')
+        return 'model_activity';
+    if (event.kind === 'lifecycle')
+        return 'lifecycle';
+    if (event.kind === 'runtime_context')
+        return 'runtime_context';
+    if (event.kind === 'skill_context')
+        return 'skill_context';
+    if (event.kind === 'tool_result')
+        return 'unmatched_tool_result';
+    if (event.kind === 'observation')
+        return 'observation';
+    return 'system_event';
+}
+function knowledgeIdsForEvents(events, knowledgeIdsByEvent) {
+    return [...new Set(events.flatMap((event) => knowledgeIdsByEvent.get(event.id) ?? []))];
+}
+function aggregateCandidates(candidates) {
+    const aggregated = new Map();
+    for (const candidate of candidates) {
+        const identity = [
+            candidate.knowledgeKind,
+            candidate.accessKind,
+            candidate.sourceLocator ?? candidate.label,
+            candidate.contentHash ?? '',
+        ].join('\u0000');
+        const id = `knowledge:${createHash('sha256').update(identity).digest('hex').slice(0, 20)}`;
+        const current = aggregated.get(id);
+        if (current) {
+            current.accessCount += 1;
+            current.evidenceRefs.push(candidate.evidenceRef);
+            if (candidate.firstSeen && (!current.firstSeen || candidate.firstSeen < current.firstSeen)) {
+                current.firstSeen = candidate.firstSeen;
+            }
+            if (candidate.lastSeen && (!current.lastSeen || candidate.lastSeen > current.lastSeen)) {
+                current.lastSeen = candidate.lastSeen;
+            }
+            continue;
+        }
+        aggregated.set(id, {
+            id,
+            knowledgeKind: candidate.knowledgeKind,
+            accessKind: candidate.accessKind,
+            label: candidate.label,
+            sourceLocator: candidate.sourceLocator,
+            contentHash: candidate.contentHash,
+            firstSeen: candidate.firstSeen,
+            lastSeen: candidate.lastSeen,
+            accessCount: 1,
+            evidenceRefs: [candidate.evidenceRef],
+        });
+    }
+    return [...aggregated.values()].sort((a, b) => {
+        const aTime = a.firstSeen ?? '';
+        const bTime = b.firstSeen ?? '';
+        return aTime.localeCompare(bTime) || a.label.localeCompare(b.label);
+    });
+}
+function toolCorrelationKey(event) {
+    return event.callInstanceId ?? event.toolUseId ?? event.id;
+}
+function sourceLocator(inputText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(inputText);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return undefined;
+    const input = parsed;
+    for (const key of ['file_path', 'path', 'url', 'query', 'command', 'cmd']) {
+        const value = input[key];
+        if (typeof value === 'string' && value.trim())
+            return value.trim().slice(0, 500);
+    }
+    return undefined;
+}
+function eventText(event) {
+    const text = event?.fullText ?? event?.snippet;
+    return text?.trim() || undefined;
+}
+function contentHash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function evidenceRef(event) {
+    return {
+        id: event.id,
+        kind: event.kind,
+        traceId: event.traceId,
+        sourceTrace: event.sourceTrace,
+        sessionId: event.sessionId,
+        traceRole: event.traceRole,
+        traceLabel: event.traceLabel,
+        messageIndex: event.messageIndex,
+        logicalMessageIndex: event.logicalMessageIndex,
+        sourceLineIndex: event.sourceLineIndex,
+        messageUuid: event.messageUuid,
+        sourceType: event.sourceType,
+        callInstanceId: event.callInstanceId,
+        toolUseId: event.toolUseId,
+        timestamp: event.timestamp,
+        role: event.role,
+        runtimeKind: event.runtimeKind,
+        label: event.label,
+        snippet: event.snippet,
+    };
+}

package/dist/observability/polling-subscription-hub.d.ts

@@ -0,0 +1,27 @@
+export interface PollingSnapshot<T> {
+    revision: string;
+    terminal: boolean;
+    value: T;
+}
+export type PollingSnapshotLoader<T> = (previous: PollingSnapshot<T> | undefined) => Promise<PollingSnapshot<T>>;
+export interface PollingSnapshotObserver<T> {
+    next(snapshot: PollingSnapshot<T>): void;
+    complete?(): void;
+    error?(cause: unknown): void;
+}
+export interface PollingSubscriptionOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Shares one sequential poll loop between all subscribers of the same key.
+ * The hub owns scheduling and cleanup; source adapters only produce snapshots.
+ */
+export declare class PollingSubscriptionHub<T> {
+    private readonly intervalMs;
+    private readonly entries;
+    constructor(intervalMs?: number);
+    subscribe(key: string, loader: PollingSnapshotLoader<T>, observer: PollingSnapshotObserver<T>, options?: PollingSubscriptionOptions): Promise<() => void>;
+    close(): void;
+    private poll;
+    private dispose;
+}

package/dist/observability/polling-subscription-hub.js

@@ -0,0 +1,149 @@
+/**
+ * Shares one sequential poll loop between all subscribers of the same key.
+ * The hub owns scheduling and cleanup; source adapters only produce snapshots.
+ */
+export class PollingSubscriptionHub {
+    intervalMs;
+    entries = new Map();
+    constructor(intervalMs = 750) {
+        this.intervalMs = intervalMs;
+    }
+    async subscribe(key, loader, observer, options = {}) {
+        let entry = this.entries.get(key);
+        if (!entry) {
+            let resolveReady;
+            let rejectReady;
+            const ready = new Promise((resolve, reject) => {
+                resolveReady = resolve;
+                rejectReady = reject;
+            });
+            entry = {
+                active: true,
+                observers: new Set(),
+                loader,
+                ready,
+                resolveReady,
+                rejectReady,
+            };
+            this.entries.set(key, entry);
+            void this.poll(key, entry, true);
+        }
+        entry.observers.add(observer);
+        if (entry.latest)
+            notifyNext(observer, entry.latest);
+        let subscribed = true;
+        let rejectAborted;
+        const aborted = options.signal
+            ? new Promise((_resolve, reject) => {
+                rejectAborted = reject;
+            })
+            : undefined;
+        const unsubscribe = () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            options.signal?.removeEventListener('abort', abort);
+            entry?.observers.delete(observer);
+            if (entry && entry.observers.size === 0)
+                this.dispose(key, entry);
+        };
+        const abort = () => {
+            unsubscribe();
+            rejectAborted?.(subscriptionAbortError());
+        };
+        if (options.signal) {
+            options.signal.addEventListener('abort', abort, { once: true });
+            if (options.signal.aborted)
+                abort();
+        }
+        try {
+            await (aborted ? Promise.race([entry.ready, aborted]) : entry.ready);
+        }
+        catch (cause) {
+            unsubscribe();
+            throw cause;
+        }
+        return unsubscribe;
+    }
+    close() {
+        for (const [key, entry] of this.entries)
+            this.dispose(key, entry);
+    }
+    async poll(key, entry, initial) {
+        try {
+            const snapshot = await entry.loader(entry.latest);
+            if (!entry.active)
+                return;
+            const changed = snapshot.revision !== entry.latest?.revision;
+            entry.latest = snapshot;
+            if (changed) {
+                for (const observer of entry.observers)
+                    notifyNext(observer, snapshot);
+            }
+            if (initial)
+                entry.resolveReady();
+            if (snapshot.terminal) {
+                for (const observer of entry.observers)
+                    notifyComplete(observer);
+                this.dispose(key, entry);
+                return;
+            }
+            entry.timer = setTimeout(() => {
+                entry.timer = undefined;
+                void this.poll(key, entry, false);
+            }, this.intervalMs);
+            entry.timer.unref?.();
+        }
+        catch (cause) {
+            if (!entry.active)
+                return;
+            if (initial)
+                entry.rejectReady(cause);
+            else
+                for (const observer of entry.observers)
+                    notifyError(observer, cause);
+            this.dispose(key, entry);
+        }
+    }
+    dispose(key, entry) {
+        if (!entry.active)
+            return;
+        entry.active = false;
+        entry.rejectReady(subscriptionAbortError());
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = undefined;
+        entry.observers.clear();
+        if (this.entries.get(key) === entry)
+            this.entries.delete(key);
+    }
+}
+function subscriptionAbortError() {
+    const error = new Error('Polling subscription closed before the initial snapshot was ready');
+    error.name = 'AbortError';
+    return error;
+}
+function notifyNext(observer, snapshot) {
+    try {
+        observer.next(snapshot);
+    }
+    catch {
+        // One consumer must not stop updates for other subscribers.
+    }
+}
+function notifyComplete(observer) {
+    try {
+        observer.complete?.();
+    }
+    catch {
+        // One consumer must not stop completion for other subscribers.
+    }
+}
+function notifyError(observer, cause) {
+    try {
+        observer.error?.(cause);
+    }
+    catch {
+        // One consumer must not stop error delivery for other subscribers.
+    }
+}

package/dist/observability/source-record-archive.d.ts

@@ -0,0 +1,13 @@
+import type { ObservationInboxReport, ObservationSourceRecord, ObservationSourceRecordArchiveRef, ObservationSourceRecordArchiveView } from '../types/index.js';
+/**
+ * Persist bounded source records beside a report. Absolute source paths are
+ * consumed only during trusted ingest; Studio later reads relative sidecars.
+ */
+export declare function writeObservationSourceRecordArchives(report: ObservationInboxReport, outDir: string, reportPath: string): ObservationSourceRecordArchiveRef[];
+export declare function loadObservationSourceRecordArchive(ref: ObservationSourceRecordArchiveRef | undefined, observationsDir: string): ObservationSourceRecordArchiveView;
+/**
+ * Build the page-safe archive metadata without reading the potentially large
+ * sidecar. The source-record endpoint resolves the same ref on demand.
+ */
+export declare function summarizeObservationSourceRecordArchive(ref: ObservationSourceRecordArchiveRef | undefined): ObservationSourceRecordArchiveView;
+export declare function observationSourceRecordFromLine(line: string, sourceIndex: number, traceId: string, sourceTrace: string): ObservationSourceRecord;