sidekick-shared 0.27.4 → 0.27.5

package/dist/sessionPromptHistory.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { type PromptHistoryEntry, type PromptHistoryExclusion, type PromptHistoryProvider } from './promptHistory';
+import { type PromptHistoryReply, type PromptHistorySignal } from './sessionPromptSignals';
+export interface SessionPromptHistoryInclude {
+    /** Interrupts, rejected and failed tool calls, compactions, API errors, rollbacks. */
+    signals?: boolean;
+    /** The agent's last text for each prompt's turn. */
+    replies?: boolean;
+}
+export interface SessionPromptHistoryBounds {
+    /** Session files read in one call. Default 1000. */
+    maxSessions?: number;
+    /** Bytes read from one session; a longer session is returned `truncated`. Default 256 MiB. */
+    maxSessionBytes?: number;
+    /** Bytes read across all sessions in one call. Default 256 MiB. */
+    maxTotalBytes?: number;
+    /** Largest single log record that is parsed. Default 16 MiB. */
+    maxRecordBytes?: number;
+    /** Wall-clock budget for the call. Default 60 000 ms. */
+    deadlineMs?: number;
+}
+export interface CollectSessionPromptHistoryOptions {
+    /** Absolute workspace roots; realpath-normalized internally. */
+    workspacePaths: string[];
+    /** Add git worktree siblings of each root. Default true. */
+    includeWorktrees?: boolean;
+    /** Default both. */
+    providers?: PromptHistoryProvider[];
+    /** Only these sessions (exact ids). */
+    sessionIds?: string[];
+    /** Only sessions whose file changed at or after this. Each comes back whole. */
+    since?: Date;
+    /** Return at most this many sessions, most recently modified first. */
+    limit?: number;
+    /** Opt-in content beyond the prompts. */
+    include?: SessionPromptHistoryInclude;
+    bounds?: SessionPromptHistoryBounds;
+    signal?: AbortSignal;
+}
+export interface PromptHistorySessionPrompt extends Omit<PromptHistoryEntry, 'provider' | 'sessionId'> {
+    /** With `include.replies`: the agent's last text for this prompt's turn. */
+    reply?: PromptHistoryReply;
+}
+export interface PromptHistorySession {
+    provider: PromptHistoryProvider;
+    sessionId: string;
+    /** Earliest timestamp in the session log. */
+    startedAt: string;
+    /** Latest timestamp in the session log. */
+    lastActivityAt: string;
+    /** Distinct prompt working directories, in order of first use. */
+    cwds: string[];
+    /** Distinct prompt git branches, in order of first use. */
+    gitBranches: string[];
+    /** Distinct models that answered a prompt, in order of first use. */
+    models: string[];
+    /** Every human prompt in scope, by ordinal. */
+    prompts: PromptHistorySessionPrompt[];
+    /** With `include.signals`: interaction signals in log order. */
+    signals?: PromptHistorySignal[];
+    /** Read to the end with no dropped prompts and no excluded records. */
+    complete: boolean;
+    /** `maxSessionBytes` stopped the read; later prompts are missing. */
+    truncated: boolean;
+    /** Prompts left out because their cwd was out of scope or they had no timestamp. */
+    droppedPrompts: number;
+    /** Records left out as oversized or malformed (see `exclusions`). */
+    excludedRecords: number;
+}
+export interface PromptHistorySessionRef {
+    provider: PromptHistoryProvider;
+    sessionId: string;
+}
+export type SessionPromptHistoryBound = 'maxSessions' | 'maxSessionBytes' | 'maxTotalBytes' | 'deadline' | 'aborted';
+export interface SessionPromptHistoryStats {
+    /** Session files that matched the provider, id, and `since` filters. */
+    sessionsMatched: number;
+    sessionsScanned: number;
+    sessionsReturned: number;
+    /** Scanned sessions with no human prompt at all. */
+    sessionsWithoutPrompts: number;
+    /** Scanned sessions with human prompts but none inside the allowed roots. */
+    sessionsOutOfScope: number;
+    /** Codex sessions skipped as non-interactive (subagent, fork, unknown source). */
+    sessionsNotInteractive: number;
+    sessionsTruncated: number;
+    recordsOverSizeLimit: number;
+    recordsMalformed: number;
+    promptsMissingTimestamp: number;
+    promptsOutOfScope: number;
+}
+export interface SessionPromptHistoryResult {
+    /** Most recent activity first. */
+    sessions: PromptHistorySession[];
+    /**
+     * Sessions this call did not read, because a bound stopped it or the file
+     * changed while it was read; pass them as `sessionIds` to continue.
+     */
+    unread: PromptHistorySessionRef[];
+    boundsHit: SessionPromptHistoryBound[];
+    /** Permanent exclusions found in this call (at most 1000; stats count all). */
+    exclusions: PromptHistoryExclusion[];
+    stats: SessionPromptHistoryStats;
+}
+/** Collect every human prompt of each matching session, grouped by session. */
+export declare function collectSessionPromptHistory(options: CollectSessionPromptHistoryOptions): Promise<SessionPromptHistoryResult>;

package/dist/sessionPromptHistory.js

@@ -0,0 +1,278 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectSessionPromptHistory = collectSessionPromptHistory;
+const fs = __importStar(require("fs"));
+const promptHistory_1 = require("./promptHistory");
+const sessionPromptSignals_1 = require("./sessionPromptSignals");
+const DEFAULT_SESSION_BOUNDS = {
+    maxSessions: 1000,
+    maxSessionBytes: 256 * 1024 * 1024,
+    maxTotalBytes: 256 * 1024 * 1024,
+    maxRecordBytes: promptHistory_1.DEFAULT_BOUNDS.maxRecordBytes,
+    deadlineMs: 60_000,
+};
+const MAX_EXCLUSIONS = 1000;
+/** Collect every human prompt of each matching session, grouped by session. */
+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 = (0, promptHistory_1.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 } = (0, promptHistory_1.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,
+    });
+    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 = (0, sessionPromptSignals_1.createSessionRecordExtractor)(item.candidate.provider, include);
+        const context = {
+            roots,
+            // Sessions come back whole: `since` only selects files.
+            sinceMs: null,
+            stats: scanStats,
+            realpaths,
+            bounds: {
+                ...promptHistory_1.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 (0, promptHistory_1.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 (0, promptHistory_1.listCandidates)(providers, listingRoots, sinceMs);
+    if (options.sessionIds) {
+        const wanted = new Set(options.sessionIds);
+        candidates = candidates.filter((candidate) => wanted.has(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 ||
+        (0, promptHistory_1.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,
+        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) ||
+        (0, promptHistory_1.compareStrings)(left.provider, right.provider) ||
+        (0, promptHistory_1.compareStrings)(left.sessionId, right.sessionId));
+}

package/dist/sessionPromptSignals.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 type { PromptHistoryProvider } from './promptHistory';
+export type PromptHistorySignalKind = 'interrupt' | 'toolRejected' | 'toolError' | 'compaction' | 'apiError' | 'rollback';
+export interface PromptHistorySignal {
+    kind: PromptHistorySignalKind;
+    /** ISO timestamp from the log line; never synthesized. */
+    timestamp: string;
+    /** Ordinal of the human prompt this followed, or -1 before the first prompt. */
+    afterOrdinal: number;
+    /** The tool involved, for `toolRejected` and `toolError`, when the log names it. */
+    tool?: string;
+    /**
+     * `toolRejected`: the reason the person typed, untruncated. `toolError` and
+     * `apiError`: the error text, cut to 1024 characters (`textTruncated`).
+     */
+    text?: string;
+    textTruncated?: true;
+}
+export interface PromptHistoryReply {
+    /** The agent's last text for the prompt's turn, untruncated. */
+    text: string;
+    /** ISO timestamp of the log line that carried the reply. */
+    timestamp: string;
+}
+export interface SessionRecordInclude {
+    signals: boolean;
+    replies: boolean;
+}
+export interface SessionRecordExtraction {
+    /** Earliest timestamp on any record. */
+    firstTimestamp?: string;
+    /** Latest timestamp on any record. */
+    lastTimestamp?: string;
+    signals: PromptHistorySignal[];
+    /** Keyed by prompt ordinal. */
+    replies: Map<number, PromptHistoryReply>;
+}
+export interface SessionRecordExtractor {
+    observe(record: Record<string, unknown>, info: {
+        ordinal: number;
+        lineOffset: number;
+    }): void;
+    result(): SessionRecordExtraction;
+}
+/** Error text kept on a signal; tool output can be arbitrarily long. */
+export declare const SIGNAL_TEXT_CHARS = 1024;
+export declare function createSessionRecordExtractor(provider: PromptHistoryProvider, include: SessionRecordInclude): SessionRecordExtractor;