sidekick-shared 0.27.6 → 0.28.1

package/dist/esm/sessionPromptHistory.js

@@ -0,0 +1,254 @@
+/**
+ * Node-only whole-session view of prompt history: every human prompt of a
+ * Claude Code or Codex session, grouped by session, for consumers that
+ * classify a session as a whole (intent, conflict, issues).
+ *
+ * Sessions are read from the start with the same scanners as
+ * `collectPromptHistory()`, so scope rules, prompt text, first-call model and
+ * usage, and ordinals are identical. The replies and interaction signals that
+ * the prompt filter leaves out are opt-in through `include`.
+ *
+ * There is no cursor: each call returns whole sessions. A bound that stops a
+ * call lists the sessions it did not read in `unread`; passing them back as
+ * `sessionIds` continues. Scope fails closed as in `collectPromptHistory()`,
+ * and replies or signals that belong to an out-of-scope prompt are dropped.
+ */
+import * as fs from 'fs';
+import { DEFAULT_BOUNDS, compareStrings, emptyStats, listCandidates, resolveRoots, scanFile, } from './promptHistory';
+import { createSessionRecordExtractor, } from './sessionPromptSignals';
+const DEFAULT_SESSION_BOUNDS = {
+    maxSessions: 1000,
+    maxSessionBytes: 256 * 1024 * 1024,
+    maxTotalBytes: 256 * 1024 * 1024,
+    maxRecordBytes: DEFAULT_BOUNDS.maxRecordBytes,
+    deadlineMs: 60_000,
+};
+const MAX_EXCLUSIONS = 1000;
+/** Collect every human prompt of each matching session, grouped by session. */
+export async function collectSessionPromptHistory(options) {
+    const bounds = { ...DEFAULT_SESSION_BOUNDS, ...definedBounds(options.bounds) };
+    const include = {
+        signals: options.include?.signals === true,
+        replies: options.include?.replies === true,
+    };
+    const startedAt = Date.now();
+    const sessions = [];
+    const unread = [];
+    const boundsHit = new Set();
+    const exclusions = [];
+    const scanStats = emptyStats();
+    const stats = {
+        sessionsMatched: 0,
+        sessionsScanned: 0,
+        sessionsReturned: 0,
+        sessionsWithoutPrompts: 0,
+        sessionsOutOfScope: 0,
+        sessionsNotInteractive: 0,
+        sessionsTruncated: 0,
+        recordsOverSizeLimit: 0,
+        recordsMalformed: 0,
+        promptsMissingTimestamp: 0,
+        promptsOutOfScope: 0,
+    };
+    const finish = () => {
+        stats.sessionsReturned = sessions.length;
+        stats.recordsOverSizeLimit = scanStats.recordsOverSizeLimit;
+        stats.recordsMalformed = scanStats.recordsMalformed;
+        stats.promptsMissingTimestamp = scanStats.promptsMissingTimestamp;
+        stats.promptsOutOfScope = scanStats.promptsOutOfScope;
+        return {
+            sessions: sessions.sort(compareSessions),
+            unread,
+            boundsHit: [...boundsHit],
+            exclusions,
+            stats,
+        };
+    };
+    const realpaths = new Map();
+    const { roots, listingRoots } = resolveRoots(options.workspacePaths, options.includeWorktrees !== false, realpaths);
+    if (roots.length === 0)
+        return finish();
+    const selected = await selectCandidates(options, listingRoots);
+    stats.sessionsMatched = selected.length;
+    const limit = typeof options.limit === 'number' && options.limit > 0 ? Math.floor(options.limit) : Infinity;
+    const shouldStop = () => {
+        if (options.signal?.aborted)
+            return 'aborted';
+        if (Date.now() - startedAt >= bounds.deadlineMs)
+            return 'deadline';
+        return null;
+    };
+    const refOf = ({ candidate }) => ({
+        provider: candidate.provider,
+        sessionId: candidate.sessionId,
+        sessionKey: candidate.key,
+    });
+    let totalBytes = 0;
+    for (let index = 0; index < selected.length && sessions.length < limit; index++) {
+        const item = selected[index];
+        const stopAt = (bound, fromIndex) => {
+            boundsHit.add(bound);
+            unread.push(...selected.slice(fromIndex).map(refOf));
+        };
+        const stop = shouldStop();
+        if (stop) {
+            stopAt(stop, index);
+            break;
+        }
+        if (stats.sessionsScanned >= bounds.maxSessions) {
+            stopAt('maxSessions', index);
+            break;
+        }
+        const remainingTotal = bounds.maxTotalBytes - totalBytes;
+        if (stats.sessionsScanned > 0 && remainingTotal <= 0) {
+            stopAt('maxTotalBytes', index);
+            break;
+        }
+        let excludedRecords = 0;
+        const extractor = createSessionRecordExtractor(item.candidate.provider, include);
+        const context = {
+            roots,
+            // Sessions come back whole: `since` only selects files.
+            sinceMs: null,
+            stats: scanStats,
+            realpaths,
+            bounds: {
+                ...DEFAULT_BOUNDS,
+                maxRecordBytes: bounds.maxRecordBytes,
+                maxEntries: Number.MAX_SAFE_INTEGER,
+            },
+            shouldStop,
+            entriesSoFar: () => 0,
+            exclude: (exclusion) => {
+                excludedRecords++;
+                if (exclusions.length < MAX_EXCLUSIONS)
+                    exclusions.push(exclusion);
+            },
+            observe: (record, info) => extractor.observe(record, info),
+        };
+        const sessionLimited = bounds.maxSessionBytes <= remainingTotal;
+        stats.sessionsScanned++;
+        let outcome;
+        try {
+            outcome = await scanFile(item.candidate, item.stat, undefined, {
+                bytes: sessionLimited ? bounds.maxSessionBytes : Math.max(0, remainingTotal),
+                bound: sessionLimited ? 'maxFileBytes' : 'maxTotalBytes',
+                forceProgress: true,
+            }, context);
+        }
+        catch {
+            // Changed while opening or verifying it: a later call can read it again.
+            unread.push(refOf(item));
+            continue;
+        }
+        totalBytes += outcome.bytesRead;
+        if (outcome.notInteractive) {
+            stats.sessionsNotInteractive++;
+            continue;
+        }
+        const stoppedBy = outcome.stoppedBy;
+        if (stoppedBy === 'deadline' || stoppedBy === 'aborted' || stoppedBy === 'maxTotalBytes') {
+            // A partial read cannot be resumed without a cursor: read it whole next call.
+            stopAt(stoppedBy, index);
+            break;
+        }
+        if (!outcome.session || (outcome.session.backlog && stoppedBy === null)) {
+            // Truncated or rewritten while it was being read.
+            unread.push(refOf(item));
+            continue;
+        }
+        if (outcome.inScope === 0) {
+            if (outcome.outOfScope > 0)
+                stats.sessionsOutOfScope++;
+            else
+                stats.sessionsWithoutPrompts++;
+            continue;
+        }
+        const truncated = stoppedBy === 'maxFileBytes';
+        if (truncated) {
+            boundsHit.add('maxSessionBytes');
+            stats.sessionsTruncated++;
+        }
+        sessions.push(buildSession(item.candidate, outcome.entries, outcome.session.lastOrdinal, extractor.result(), include, { truncated, excludedRecords }));
+    }
+    return finish();
+}
+function definedBounds(bounds) {
+    const result = {};
+    if (!bounds)
+        return result;
+    for (const key of Object.keys(DEFAULT_SESSION_BOUNDS)) {
+        const value = bounds[key];
+        if (typeof value === 'number' && !Number.isNaN(value))
+            result[key] = Math.max(0, value);
+    }
+    return result;
+}
+/** Matching session files, most recently modified first. */
+async function selectCandidates(options, listingRoots) {
+    const sinceMs = options.since ? options.since.getTime() : null;
+    const providers = options.providers ?? ['claude-code', 'codex'];
+    let candidates = await listCandidates(providers, listingRoots, sinceMs);
+    if (options.sessionIds || options.sessionRefs) {
+        const ids = new Set(options.sessionIds ?? []);
+        const keys = new Set();
+        const refs = new Set();
+        for (const ref of options.sessionRefs ?? []) {
+            if (ref.sessionKey)
+                keys.add(ref.sessionKey);
+            else
+                refs.add(`${ref.provider}:${ref.sessionId}`);
+        }
+        candidates = candidates.filter((candidate) => ids.has(candidate.sessionId) ||
+            keys.has(candidate.key) ||
+            refs.has(`${candidate.provider}:${candidate.sessionId}`));
+    }
+    const selected = [];
+    for (const candidate of candidates) {
+        try {
+            selected.push({ candidate, stat: await fs.promises.stat(candidate.filePath) });
+        }
+        catch {
+            // Gone since it was listed.
+        }
+    }
+    return selected.sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs ||
+        compareStrings(left.candidate.key, right.candidate.key));
+}
+function buildSession(candidate, entries, lastOrdinal, extraction, include, read) {
+    const ordered = [...entries].sort((left, right) => left.ordinal - right.ordinal);
+    const returned = new Set(ordered.map((entry) => entry.ordinal));
+    const prompts = ordered.map(({ provider: _provider, sessionId: _sessionId, ...prompt }) => {
+        const reply = include.replies ? extraction.replies.get(prompt.ordinal) : undefined;
+        return reply ? { ...prompt, reply } : prompt;
+    });
+    const droppedPrompts = Math.max(0, lastOrdinal + 1 - ordered.length);
+    const session = {
+        provider: candidate.provider,
+        sessionId: candidate.sessionId,
+        sessionKey: candidate.key,
+        startedAt: extraction.firstTimestamp ?? ordered[0].timestamp,
+        lastActivityAt: extraction.lastTimestamp ?? ordered[ordered.length - 1].timestamp,
+        cwds: distinct(ordered.map((entry) => entry.cwd)),
+        gitBranches: distinct(ordered.map((entry) => entry.gitBranch)),
+        models: distinct(ordered.map((entry) => entry.model)),
+        prompts,
+        complete: !read.truncated && droppedPrompts === 0 && read.excludedRecords === 0,
+        truncated: read.truncated,
+        droppedPrompts,
+        excludedRecords: read.excludedRecords,
+    };
+    if (include.signals) {
+        // Fail closed: nothing that followed an out-of-scope prompt is returned.
+        session.signals = extraction.signals.filter((signal) => signal.afterOrdinal === -1 || returned.has(signal.afterOrdinal));
+    }
+    return session;
+}
+function distinct(values) {
+    return [...new Set(values.filter((value) => typeof value === 'string'))];
+}
+function compareSessions(left, right) {
+    return (Date.parse(right.lastActivityAt) - Date.parse(left.lastActivityAt) ||
+        compareStrings(left.provider, right.provider) ||
+        compareStrings(left.sessionId, right.sessionId));
+}

package/dist/esm/sessionPromptSignals.js

@@ -0,0 +1,364 @@
+/**
+ * What the human-prompt filter leaves out of a session, for consumers that
+ * classify a whole session: the agent's reply to each prompt and timestamped
+ * interaction signals (interrupts, rejected or failed tools, compactions, API
+ * errors, rollbacks). Pure: log records in, results out; no file system access.
+ *
+ * Records reach an extractor after the prompt scanner has seen them, with the
+ * ordinal of the latest human prompt, so replies and signals share the prompt
+ * ordinals of `collectPromptHistory()`.
+ */
+import { parseMcpToolName } from './parsers/mcpToolName';
+import { classifyTool } from './toolCategory';
+/** Error text kept on a signal; tool output can be arbitrarily long. */
+export const SIGNAL_TEXT_CHARS = 1024;
+const CLAUDE_REJECTED_PREFIX = "The user doesn't want to proceed with this tool use";
+const CLAUDE_REJECTION_REASON = /the user said:\s*([\s\S]*)$/;
+const CLAUDE_INTERRUPT_PREFIX = '[Request interrupted by user';
+const CLAUDE_TOOL_USE_INTERRUPT = '[Request interrupted by user for tool use]';
+export function createSessionRecordExtractor(provider, include) {
+    return provider === 'claude-code'
+        ? new ClaudeRecordExtractor(include)
+        : new CodexRecordExtractor(include);
+}
+/** Timestamps, signal bookkeeping, and reply slots shared by both providers. */
+class RecordExtractor {
+    include;
+    firstMs = Infinity;
+    lastMs = -Infinity;
+    firstTimestamp;
+    lastTimestamp;
+    signals = [];
+    replies = new Map();
+    constructor(include) {
+        this.include = include;
+    }
+    observe(record, info) {
+        const timestamp = validTimestamp(record.timestamp);
+        if (timestamp) {
+            const ms = Date.parse(timestamp);
+            if (ms < this.firstMs) {
+                this.firstMs = ms;
+                this.firstTimestamp = timestamp;
+            }
+            if (ms > this.lastMs) {
+                this.lastMs = ms;
+                this.lastTimestamp = timestamp;
+            }
+        }
+        this.accept(record, timestamp, info.ordinal, info.lineOffset);
+    }
+    result() {
+        return {
+            ...(this.firstTimestamp ? { firstTimestamp: this.firstTimestamp } : {}),
+            ...(this.lastTimestamp ? { lastTimestamp: this.lastTimestamp } : {}),
+            signals: [...this.signals],
+            replies: new Map(this.replies),
+        };
+    }
+    signal(kind, timestamp, ordinal, detail = {}) {
+        if (!this.include.signals || !timestamp)
+            return;
+        const signal = { kind, timestamp, afterOrdinal: ordinal };
+        if (detail.tool)
+            signal.tool = detail.tool;
+        if (detail.tool || detail.mcp) {
+            const mcpServer = detail.mcpServer || (detail.tool ? parseMcpToolName(detail.tool)?.serverName : undefined);
+            signal.toolCategory =
+                detail.mcp || !detail.tool ? 'mcp' : classifyTool(detail.tool, { mcpServer });
+            if (mcpServer)
+                signal.mcpServer = mcpServer;
+        }
+        if (detail.fullText) {
+            signal.text = detail.fullText;
+        }
+        else if (detail.text?.trim()) {
+            const text = detail.text.trim();
+            if (text.length > SIGNAL_TEXT_CHARS) {
+                signal.text = detachedPrefix(text, SIGNAL_TEXT_CHARS);
+                signal.textTruncated = true;
+            }
+            else {
+                signal.text = text;
+            }
+        }
+        this.signals.push(signal);
+    }
+}
+class ClaudeRecordExtractor extends RecordExtractor {
+    toolNames = new Map();
+    /** The reply being assembled: split records of one message share an id. */
+    reply = null;
+    /**
+     * A rejection without a reason is always followed by a
+     * `[Request interrupted by user for tool use]` record; it is one action.
+     */
+    rejectionAwaitingInterrupt = false;
+    lastOrdinal = -1;
+    accept(record, timestamp, ordinal, lineOffset) {
+        if (record.isSidechain === true)
+            return;
+        if (ordinal !== this.lastOrdinal) {
+            this.lastOrdinal = ordinal;
+            this.rejectionAwaitingInterrupt = false;
+        }
+        if (record.type === 'system') {
+            if (record.subtype === 'compact_boundary')
+                this.signal('compaction', timestamp, ordinal);
+            return;
+        }
+        const message = record.message;
+        if (typeof message !== 'object' || message === null)
+            return;
+        const blocks = contentBlocks(message.content);
+        if (record.type === 'assistant') {
+            this.rejectionAwaitingInterrupt = false;
+            for (const block of blocks) {
+                if (block.type === 'tool_use' && typeof block.id === 'string') {
+                    const name = stringValue(block.name);
+                    if (name)
+                        this.toolNames.set(block.id, name);
+                }
+            }
+            if (record.isApiErrorMessage === true) {
+                this.signal('apiError', timestamp, ordinal, { text: blockText(blocks) });
+                return;
+            }
+            if (message.model === '<synthetic>')
+                return;
+            this.recordReply(blocks, stringValue(message.id) ?? `line:${lineOffset}`, timestamp, ordinal);
+            return;
+        }
+        if (record.type !== 'user')
+            return;
+        for (const block of blocks) {
+            if (block.type === 'text' && typeof block.text === 'string') {
+                const text = block.text.trim();
+                if (!text.startsWith(CLAUDE_INTERRUPT_PREFIX))
+                    continue;
+                const paired = text.startsWith(CLAUDE_TOOL_USE_INTERRUPT) && this.rejectionAwaitingInterrupt;
+                this.rejectionAwaitingInterrupt = false;
+                if (!paired)
+                    this.signal('interrupt', timestamp, ordinal);
+            }
+            else if (block.type === 'tool_result' && block.is_error === true) {
+                const text = toolResultText(block.content);
+                const tool = typeof block.tool_use_id === 'string' ? this.toolNames.get(block.tool_use_id) : undefined;
+                if (text.startsWith(CLAUDE_REJECTED_PREFIX)) {
+                    const reason = text.match(CLAUDE_REJECTION_REASON)?.[1].trim();
+                    this.signal('toolRejected', timestamp, ordinal, { tool, fullText: reason || undefined });
+                    this.rejectionAwaitingInterrupt = !reason;
+                }
+                else {
+                    this.signal('toolError', timestamp, ordinal, { tool, text });
+                }
+            }
+        }
+    }
+    recordReply(blocks, id, timestamp, ordinal) {
+        if (!this.include.replies || ordinal < 0 || !timestamp)
+            return;
+        const text = blockText(blocks);
+        if (!text.trim())
+            return;
+        const current = this.reply;
+        if (current && current.ordinal === ordinal && current.id === id) {
+            current.parts.push(text);
+        }
+        else {
+            this.reply = { ordinal, id, parts: [text], timestamp };
+        }
+        const reply = this.reply;
+        this.replies.set(ordinal, { text: reply.parts.join('\n'), timestamp: reply.timestamp });
+    }
+}
+class CodexRecordExtractor extends RecordExtractor {
+    /** Ordinals whose reply came from `task_complete`, which later fallbacks do not replace. */
+    finalReplies = new Set();
+    accept(record, timestamp, ordinal) {
+        // Every compaction writes one top-level `compacted` record; the matching
+        // event or item exists only in some Codex versions, so it is not counted.
+        if (record.type === 'compacted') {
+            this.signal('compaction', timestamp, ordinal);
+            return;
+        }
+        const payload = record.payload;
+        if (typeof payload !== 'object' || payload === null)
+            return;
+        if (record.type === 'response_item') {
+            if (payload.type === 'message' && payload.role === 'assistant') {
+                this.fallbackReply(blockText(contentBlocks(payload.content)), timestamp, ordinal);
+            }
+            return;
+        }
+        if (record.type !== 'event_msg')
+            return;
+        switch (payload.type) {
+            case 'turn_aborted':
+                this.signal('interrupt', timestamp, ordinal);
+                break;
+            case 'thread_rolled_back':
+                this.signal('rollback', timestamp, ordinal);
+                break;
+            case 'task_complete': {
+                const last = stringValue(payload.last_agent_message);
+                if (last?.trim() && this.include.replies && ordinal >= 0 && timestamp) {
+                    this.replies.set(ordinal, { text: last, timestamp });
+                    this.finalReplies.add(ordinal);
+                }
+                if (payload.error !== undefined && payload.error !== null) {
+                    this.signal('apiError', timestamp, ordinal, { text: errorText(payload.error) });
+                }
+                break;
+            }
+            case 'error':
+                this.signal('apiError', timestamp, ordinal, { text: errorText(payload) });
+                break;
+            case 'agent_message':
+                this.fallbackReply(stringValue(payload.message) ?? '', timestamp, ordinal);
+                break;
+            case 'exec_command_end':
+                if (payload.status === 'failed' || nonZero(payload.exit_code)) {
+                    this.signal('toolError', timestamp, ordinal, {
+                        tool: 'exec_command',
+                        text: commandText(payload),
+                    });
+                }
+                break;
+            case 'patch_apply_end':
+                if (payload.success === false) {
+                    this.signal('toolError', timestamp, ordinal, {
+                        tool: 'apply_patch',
+                        text: stringValue(payload.stderr) || stringValue(payload.stdout),
+                    });
+                }
+                break;
+            case 'mcp_tool_call_end': {
+                const invocation = payload.invocation;
+                const failure = mcpFailure(payload.result);
+                if (failure !== null) {
+                    this.signal('toolError', timestamp, ordinal, {
+                        tool: invocation ? stringValue(invocation.tool) : undefined,
+                        mcp: true,
+                        mcpServer: invocation ? stringValue(invocation.server) : undefined,
+                        text: failure,
+                    });
+                }
+                break;
+            }
+            case 'item_completed':
+                this.acceptItem(payload.item, timestamp, ordinal);
+                break;
+        }
+    }
+    acceptItem(item, timestamp, ordinal) {
+        if (typeof item !== 'object' || item === null)
+            return;
+        const row = item;
+        const failed = row.status === 'failed';
+        switch (row.type) {
+            case 'AgentMessage':
+                this.fallbackReply(blockText(contentBlocks(row.content)), timestamp, ordinal);
+                break;
+            case 'CommandExecution':
+                if (failed) {
+                    this.signal('toolError', timestamp, ordinal, {
+                        tool: 'exec_command',
+                        text: commandText(row),
+                    });
+                }
+                break;
+            case 'FileChange':
+                if (failed) {
+                    this.signal('toolError', timestamp, ordinal, {
+                        tool: 'apply_patch',
+                        text: stringValue(row.stderr) || stringValue(row.stdout),
+                    });
+                }
+                break;
+            case 'McpToolCall':
+                if (failed) {
+                    this.signal('toolError', timestamp, ordinal, {
+                        tool: stringValue(row.tool),
+                        mcp: true,
+                        mcpServer: stringValue(row.server),
+                        text: row.error !== undefined && row.error !== null
+                            ? errorText(row.error)
+                            : (mcpFailure(row.result) ?? undefined),
+                    });
+                }
+                break;
+        }
+    }
+    /** The latest agent text of the turn, until `task_complete` settles it. */
+    fallbackReply(text, timestamp, ordinal) {
+        if (!this.include.replies || ordinal < 0 || !timestamp || !text.trim())
+            return;
+        if (this.finalReplies.has(ordinal))
+            return;
+        this.replies.set(ordinal, { text, timestamp });
+    }
+}
+/**
+ * The first `chars` UTF-16 units of `text` as a new string. A plain slice can
+ * keep the whole source string alive (V8 sliced strings), which for a tool's
+ * output may be megabytes per signal. A surrogate pair is never split.
+ */
+function detachedPrefix(text, chars) {
+    const end = /[\uD800-\uDBFF]/.test(text.charAt(chars - 1)) ? chars - 1 : chars;
+    return Buffer.from(text.slice(0, end), 'utf8').toString('utf8');
+}
+function validTimestamp(value) {
+    return typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : undefined;
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function contentBlocks(content) {
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    if (!Array.isArray(content))
+        return [];
+    return content.filter((block) => typeof block === 'object' && block !== null);
+}
+/** Text of text-like blocks: Claude `text`, Codex `output_text`, Codex item `Text`. */
+function blockText(blocks) {
+    return blocks
+        .filter((block) => (block.type === 'text' || block.type === 'output_text' || block.type === 'Text') &&
+        typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n');
+}
+function toolResultText(content) {
+    return blockText(contentBlocks(content)).trim();
+}
+function nonZero(value) {
+    return typeof value === 'number' && value !== 0;
+}
+/** A failed command as `$ <command>` plus its output. */
+function commandText(row) {
+    const command = Array.isArray(row.command)
+        ? row.command.filter((part) => typeof part === 'string').at(-1)
+        : stringValue(row.command);
+    const output = stringValue(row.aggregated_output) ?? stringValue(row.stderr) ?? stringValue(row.stdout) ?? '';
+    return command ? `$ ${command}\n${output}` : output;
+}
+function errorText(error) {
+    if (typeof error === 'string')
+        return error;
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    return stringValue(error.message);
+}
+/** The failure text of an MCP call result, or null when it succeeded. */
+function mcpFailure(result) {
+    if (typeof result !== 'object' || result === null)
+        return null;
+    const row = result;
+    if ('Err' in row)
+        return typeof row.Err === 'string' ? row.Err : (errorText(row.Err) ?? '');
+    const ok = (row.Ok ?? row);
+    if (typeof ok !== 'object' || ok === null || ok.isError !== true)
+        return null;
+    return blockText(contentBlocks(ok.content));
+}