sidekick-shared 0.26.6 → 0.27.1

package/dist/promptHistory.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Node-only collection of human-typed prompts from Claude Code and Codex
+ * session logs, scoped to a set of workspace roots.
+ *
+ * Parse-only: no redaction and no network I/O. Scope fails closed — a prompt
+ * is returned only when the working directory recorded on its log line (or,
+ * for Codex, its session/turn context) realpath-resolves to an allowed root
+ * or somewhere inside one. Every bound stops cleanly and is reported in
+ * `boundsHit`; nothing is silently truncated and no bound throws.
+ *
+ * A prompt can be written before its answer. The cursor then keeps the byte
+ * offset of that prompt's line (not its text), the next call replays from it,
+ * and the prompt is returned again under the same identity once its first
+ * answering call brings model or usage (`metadataStatus` says how settled).
+ */
+import { type HumanPromptProvider } from './humanPrompt';
+export type PromptHistoryProvider = HumanPromptProvider;
+export type PromptHistoryBound = 'maxSessions' | 'maxFileBytes' | 'maxTotalBytes' | 'deadline' | 'aborted';
+export interface PromptHistoryBounds {
+    /** Session files read in one call (unchanged files do not count). Default 1000. */
+    maxSessions?: number;
+    /**
+     * Bytes a single file may need read in this pass. Default 16 MiB. A file over
+     * it is skipped, and calling again with the same bounds skips it again.
+     */
+    maxFileBytes?: number;
+    /** Bytes read across all files in this call. Default 256 MiB. */
+    maxTotalBytes?: number;
+    /** Wall-clock budget for the call. Default 30 000 ms. */
+    deadlineMs?: number;
+}
+/** Codex parse state carried across resumes (Claude lines are self-describing). */
+export interface PromptHistoryResumeState {
+    cwd?: string;
+    gitBranch?: string;
+    model?: string;
+    /** Session is not interactive (non-human source, fork, or missing metadata). */
+    excluded?: boolean;
+    /** `session_meta` has been seen. */
+    meta?: boolean;
+}
+/**
+ * The last emitted prompt of a file whose answering call is not final yet.
+ * Holds a replay position and a metadata digest, never prompt or answer text.
+ */
+export interface PromptHistoryPendingPrompt {
+    ordinal: number;
+    /** Byte offset where the prompt's log line starts; the next pass replays from here. */
+    offset: number;
+    /** Digest of the model, usage, and status last returned for this prompt. */
+    emitted: string;
+    /** Codex parse state as it was just before the prompt line. */
+    state?: PromptHistoryResumeState;
+}
+export interface PromptHistoryCursorSession {
+    provider: PromptHistoryProvider;
+    sessionId: string;
+    size: number;
+    mtimeMs: number;
+    /** Ordinal of the last human prompt seen in this file, or -1 when none. */
+    lastOrdinal: number;
+    /** Byte offset just past the last complete line processed. */
+    offset: number;
+    state?: PromptHistoryResumeState;
+    pending?: PromptHistoryPendingPrompt;
+}
+/**
+ * JSON-serializable resume point. Keys are opaque and never contain paths, but
+ * values can (Codex `state.cwd`), so treat the cursor as sensitive local state.
+ * Version 1 cursors from 0.27.0 are accepted as input; output is always version 2.
+ */
+export interface PromptHistoryCursor {
+    version: 2;
+    sessions: Record<string, PromptHistoryCursorSession>;
+}
+/**
+ * How settled an entry's `model` / `usage` are:
+ * - `pending`: no answering call seen yet.
+ * - `provisional`: the first answering call is still being written (Claude
+ *   `stop_reason: null`); values may change.
+ * - `final`: the first answering call is complete, or the prompt was closed
+ *   without one. Missing usage is then unknown, not zero.
+ */
+export type PromptHistoryMetadataStatus = 'pending' | 'provisional' | 'final';
+export interface PromptHistoryUsage {
+    /** Uncached input tokens. */
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export interface PromptHistoryEntry {
+    provider: PromptHistoryProvider;
+    sessionId: string;
+    /** Stable index of this prompt among the session's human prompts (0-based). */
+    ordinal: number;
+    /** ISO timestamp from the log line; never synthesized. */
+    timestamp: string;
+    /** Full prompt text, untruncated. */
+    text: string;
+    /** Realpath of the working directory; always inside an allowed root. */
+    cwd: string;
+    gitBranch?: string;
+    /** Model of the first assistant response to this prompt, when known. */
+    model?: string;
+    /** Usage of that first answering model call, when known. */
+    usage?: PromptHistoryUsage;
+    /**
+     * Whether `model` / `usage` can still change. A prompt that is not `final`
+     * is returned again, with the same provider, sessionId, ordinal, timestamp,
+     * and text, by a later call once its metadata or status changes.
+     */
+    metadataStatus: PromptHistoryMetadataStatus;
+}
+export interface PromptHistoryStats {
+    sessionsScanned: number;
+    sessionsSkippedUnchanged: number;
+    /** Scanned sessions with human prompts but none inside the allowed roots. */
+    sessionsOutOfScope: number;
+    filesOverSizeLimit: number;
+    /** Codex sessions skipped as non-interactive (subagent, fork, unknown source). */
+    sessionsNotInteractive: number;
+    /** Human prompts dropped because the log line had no usable timestamp. */
+    promptsMissingTimestamp: number;
+    /** Human prompts dropped because their cwd was missing or outside the roots. */
+    promptsOutOfScope: number;
+}
+export interface CollectPromptHistoryOptions {
+    /** Absolute workspace roots; realpath-normalized internally. */
+    workspacePaths: string[];
+    /** Add git worktree siblings of each root. Default true. */
+    includeWorktrees?: boolean;
+    /** Default both. */
+    providers?: PromptHistoryProvider[];
+    /** Drop prompts older than this (and skip files not modified since). */
+    since?: Date;
+    cursor?: PromptHistoryCursor;
+    bounds?: PromptHistoryBounds;
+    signal?: AbortSignal;
+}
+export interface PromptHistoryResult {
+    /** Ordered by provider, session, then ordinal. */
+    entries: PromptHistoryEntry[];
+    cursor: PromptHistoryCursor;
+    stats: PromptHistoryStats;
+    boundsHit: PromptHistoryBound[];
+}
+/** Collect human-typed prompts from Claude Code and Codex logs under the given roots. */
+export declare function collectPromptHistory(options: CollectPromptHistoryOptions): Promise<PromptHistoryResult>;