cogpit-memory 0.2.1 → 0.4.0

package/dist/lib/codex.d.ts

@@ -1,4 +1,4 @@
-import type { ParseSessionOptions, ParsedSession } from "./types";
+import type { ParseSessionOptions, ParsedSession, RawRecord, SessionStatusInfo } from "./types";
 export { extractApplyPatchInputs, findFailedNestedPatchCallIds, parseApplyPatch, parseCodexToolPatches, } from "./codex-patches";
 export { parseCustomToolOutput } from "./codex-tool-normalization";
 interface CodexMetadata {
@@ -25,6 +25,45 @@ interface CodexMetadata {
     /** Canonical collaboration path for the agent that owns this rollout. */
     agentPath: string;
 }
+/**
+ * The session a rollout was forked or spawned from, read from its
+ * `session_meta` payload. Forks name it in `forked_from_id`; spawned threads
+ * and reviews in `parent_thread_id`, and some spawned threads only under
+ * `source.subagent.thread_spawn`.
+ */
+export declare function codexParentId(payload: Record<string, unknown>): string | null;
 export declare function isCodexSessionText(jsonlText: string): boolean;
+/** True when already-parsed raw records came from this CLI. */
+export declare function isCodexRawRecords(records: readonly {
+    type?: unknown;
+}[]): boolean;
 export declare function extractCodexMetadataFromLines(lines: string[]): CodexMetadata;
 export declare function parseCodexSession(jsonlText: string, options?: ParseSessionOptions): ParsedSession;
+/**
+ * Incrementally extend a parsed session with newly written lines.
+ *
+ * Rollout records carry cross-turn state (patch folding, collaboration agent
+ * lifecycles, token roll-ups), so the whole transcript is re-parsed rather than
+ * only its tail.
+ */
+export declare function appendCodexSession(existing: ParsedSession, newJsonlText: string): ParsedSession;
+/** Derive status by walking backward through a rollout's records. */
+export declare function deriveCodexSessionStatus(rawMessages: readonly RawRecord[]): SessionStatusInfo;
+/**
+ * A branch keeps the `session_meta` record, renamed and pointed back at its
+ * origin. The copied lines keep their origin's timestamps, so `at` is what
+ * tells them from the branch's own.
+ */
+export declare function brandCodexBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null, branchedAt: number): {
+    record: Record<string, unknown>;
+    originalId: string;
+};
+/**
+ * Indexes at which a turn starts.
+ *
+ * A rollout writes the `turn_context` record that configures a turn *before*
+ * the user message that opens it, so the boundary reported is that context
+ * record: cutting at the user message alone would strand a context line
+ * belonging to a turn that no longer exists.
+ */
+export declare function codexTurnBoundaries(records: readonly Record<string, unknown>[]): number[];

package/dist/lib/copilot.d.ts

@@ -0,0 +1,51 @@
+import type { ParseSessionOptions, ParsedSession, RawRecord, SessionStatusInfo } from "./types";
+interface CopilotMetadata {
+    sessionId: string;
+    version: string;
+    gitBranch: string;
+    cwd: string;
+    model: string;
+    slug: string;
+    name: string;
+    firstUserMessage: string;
+    lastUserMessage: string;
+    timestamp: string;
+    lastTimestamp: string;
+    turnCount: number;
+    isSubagent: false;
+    parentSessionId: null;
+}
+export declare function isCopilotSessionText(jsonlText: string): boolean;
+/** True when already-parsed raw records came from this CLI. */
+export declare function isCopilotRawRecords(records: readonly {
+    type?: unknown;
+}[]): boolean;
+export declare function extractCopilotMetadataFromLines(lines: string[]): CopilotMetadata;
+export declare function parseCopilotSession(jsonlText: string, options?: ParseSessionOptions): ParsedSession;
+/**
+ * Incrementally extend a parsed session with newly written lines.
+ *
+ * Copilot's durable events carry cross-turn state (permission requests, usage
+ * roll-ups, sub-agent lifecycles), so the whole transcript is re-parsed rather
+ * than only its tail.
+ */
+export declare function appendCopilotSession(existing: ParsedSession, newJsonlText: string): ParsedSession;
+/** True when a record `type` belongs to this CLI's durable event stream. */
+export declare function isCopilotEventType(type: unknown): type is string;
+/** Derive status from Copilot CLI's durable session events. */
+export declare function deriveCopilotSessionStatus(rawMessages: readonly RawRecord[]): SessionStatusInfo;
+/**
+ * Copilot branches through its own fork RPC (`capabilities.nativeFork`), so a
+ * copied-and-cut transcript is never made and there is no header shape to
+ * invent for one.
+ */
+export declare function brandCopilotBranch(): never;
+/**
+ * Indexes of the `user.message` events that open a turn.
+ *
+ * Sub-agent events carry an `agentId` and belong to the turn already in
+ * flight. An event with no durable `id` cannot be addressed by the CLI's fork
+ * and rewind RPCs, so it cannot be a boundary either.
+ */
+export declare function copilotTurnBoundaries(records: readonly Record<string, unknown>[]): number[];
+export {};

package/dist/lib/dirs.d.ts

@@ -1,8 +1,18 @@
+import { type AgentKind } from "./agent-descriptors";
+/**
+ * Where each agent CLI keeps its state, honouring the environment variable it
+ * publishes for that. `$CODEX_HOME` used to be ignored here while
+ * `$COPILOT_HOME` was honoured, so a redirected Codex install was invisible to
+ * the whole package.
+ */
+export declare function agentHomeDir(kind: AgentKind, env?: NodeJS.ProcessEnv, homeDirectory?: string): string;
 export declare const dirs: {
     PROJECTS_DIR: string;
     TEAMS_DIR: string;
     TASKS_DIR: string;
     CODEX_SESSIONS_DIR: string;
+    COPILOT_SESSIONS_DIR: string;
+    ACP_PROJECTS_DIR: string;
 };
 /** Default database path for the FTS5 search index. */
 export declare const DEFAULT_DB_PATH: string;

package/dist/lib/helpers.d.ts

@@ -1,25 +1,5 @@
-/** Find the JSONL file path for a session by searching all project directories. */
-export declare function findJsonlPath(sessionId: string): Promise<string | null>;
 export declare function matchSubagentToMember(leadSessionId: string, subagentFileName: string, members: Array<{
     name: string;
     agentType: string;
     prompt?: string;
 }>): Promise<string | null>;
-/**
- * Encode a cwd using Claude Code's project-directory naming convention: every
- * character outside `[A-Za-z0-9]` becomes `-`, so both `/Users/x/proj` and
- * `C:\Users\x\proj` collapse into a flat directory name under
- * `~/.claude/projects`. Mirrors `shared/providers/claude.ts`; this package is
- * published standalone and cannot import outside its own `src` root.
- */
-export declare function encodeClaudeDirName(cwd: string): string;
-/**
- * Best-effort inverse of {@link encodeClaudeDirName}. The encoding is lossy —
- * a literal `-` is indistinguishable from a separator — so callers that can
- * read a session's recorded `cwd` should always prefer that.
- */
-export declare function decodeClaudeDirName(dirName: string): string;
-export declare function projectDirToReadableName(dirName: string): {
-    path: string;
-    shortName: string;
-};

package/dist/lib/instances.d.ts

@@ -0,0 +1,12 @@
+import type { ParsedSession } from "./types";
+export declare function instanceSessionId(instanceId: string, nativeId: string): string;
+export declare function splitInstanceSessionId(id: string): {
+    instanceId: string;
+    nativeId: string;
+};
+export declare function instanceDirName(instanceId: string, nativeDirName: string): string;
+export declare function splitInstanceDirName(dirName: string | null | undefined): {
+    instanceId: string;
+    nativeDirName: string;
+};
+export declare function scopeParsedSession(session: ParsedSession, instanceId: string): ParsedSession;

package/dist/lib/interactiveState.d.ts

@@ -8,6 +8,12 @@ export interface PlanApprovalState {
         tool: string;
         prompt: string;
     }>;
+    provider?: "copilot";
+    requestId?: string;
+    summary?: string;
+    planContent?: string;
+    actions?: string[];
+    recommendedAction?: string;
 }
 export interface UserQuestionState {
     type: "question";
@@ -36,5 +42,8 @@ export declare function isStuckInteractiveLoop(turns: Turn[], toolName: string):
 /**
  * Detect if the session is waiting for user interaction (plan approval or
  * AskUserQuestion). Returns the interaction state or null.
+ *
+ * A blocking prompt wins over an async question asked earlier in the same turn:
+ * it is the one holding the agent up.
  */
 export declare function detectPendingInteraction(session: ParsedSession): PendingInteraction;

package/dist/lib/metadata.d.ts

@@ -1,20 +1,27 @@
 import { type SessionStatusInfo } from "./sessionStatus";
+/**
+ * Header metadata for one transcript, whichever agent wrote it.
+ *
+ * Which agent that is comes from the shared format registry, in its own
+ * detection order — the same code the app and the parser use, rather than a
+ * hand-rolled sniff that recognised a narrower set of Codex records.
+ */
 export declare function getSessionMeta(filePath: string): Promise<{
+    lineCount: number;
+    branchedFrom: {
+        sessionId: string;
+        turnIndex?: number | null;
+    } | undefined;
+    firstUserMessage: string;
+    lastUserMessage: string;
+    timestamp: string;
+    turnCount: number;
     sessionId: string;
     version: string;
     gitBranch: string;
     model: string;
     slug: string;
     cwd: string;
-    firstUserMessage: string;
-    lastUserMessage: string;
-    timestamp: string;
-    turnCount: number;
-    lineCount: number;
-    branchedFrom: {
-        sessionId: string;
-        turnIndex?: number | null;
-    } | undefined;
 }>;
 /**
  * Read backward through a session JSONL to derive agent status.
@@ -24,8 +31,3 @@ export declare function getSessionMeta(filePath: string): Promise<{
  * deriveSessionStatus() function as the client side.
  */
 export declare function getSessionStatus(filePath: string): Promise<SessionStatusInfo>;
-/**
- * Search all user messages in a session file for a query string.
- * Returns the first matching message snippet, or null if no match.
- */
-export declare function searchSessionMessages(filePath: string, query: string): Promise<string | null>;

package/dist/lib/parser.d.ts

@@ -1,14 +1,16 @@
-import type { ParsedSession, ImageBlock, ParseSessionOptions, UserContent } from "./types";
+import type { ImageBlock, ParseSessionOptions, ParsedSession, UserContent } from "./types";
 export type { PendingInteraction } from "./interactiveState";
 export type { ParseSessionOptions } from "./types";
 export { detectPendingInteraction } from "./interactiveState";
 export declare function parseSession(jsonlText: string, options?: ParseSessionOptions): ParsedSession;
 /**
  * Incrementally append new JSONL lines to an existing parsed session.
- * Avoids re-parsing all turns from scratch — only re-processes the last
- * (potentially incomplete) turn and any new messages.
+ *
+ * Dispatch is on raw-record shape, never on `existing.agentKind`: that field is
+ * optional on `ParsedSession` and this is the append hot path. When the records
+ * carry no discriminator — an empty window, or one paged in above the loaded
+ * range — the newly arrived text decides instead.
  */
 export declare function parseSessionAppend(existing: ParsedSession, newJsonlText: string): ParsedSession;
 export declare function getUserMessageText(content: UserContent | null): string;
 export declare function getUserMessageImages(content: UserContent | null): ImageBlock[];
-export declare function getToolColor(toolName: string): string;

package/dist/lib/read-session.d.ts

@@ -0,0 +1 @@
+export declare function parseTranscript(content: string, filePath: string): import("./types").ParsedSession;

package/dist/lib/search-index.d.ts

@@ -6,7 +6,6 @@ export interface IndexStats {
     indexedSessions: number;
     indexedSubagents: number;
     totalRows: number;
-    watcherRunning: boolean;
     lastFullBuild: string | null;
     lastUpdate: string | null;
 }
@@ -20,12 +19,8 @@ export interface SearchHit {
 export declare class SearchIndex {
     private db;
     private dbPath;
-    projectsDir: string | null;
-    private _watcherRunning;
     private _lastFullBuild;
     private _lastUpdate;
-    private watcher;
-    private debounceTimers;
     constructor(dbPath: string);
     private initSchema;
     getStats(): IndexStats;
@@ -45,6 +40,7 @@ export declare class SearchIndex {
         isSubagent?: boolean;
         parentSessionId?: string | null;
     }): void;
+    pruneMissingFiles(): number;
     /**
      * Query the FTS5 index and return structured search results.
      *
@@ -59,6 +55,7 @@ export declare class SearchIndex {
     search(query: string, opts?: {
         limit?: number;
         sessionId?: string;
+        excludeSessionId?: string;
         maxAgeMs?: number;
         caseSensitive?: boolean;
     }): SearchHit[];
@@ -68,32 +65,20 @@ export declare class SearchIndex {
      */
     countMatches(query: string, opts?: {
         sessionId?: string;
+        excludeSessionId?: string;
         maxAgeMs?: number;
     }): {
         totalHits: number;
         sessionsSearched: number;
     };
     /**
-     * Clear all indexed data and re-index every JSONL file under `projectsDir`.
-     * Structure: projectsDir/{projectName}/{sessionId}.jsonl
-     * Subagents:  projectsDir/{projectName}/{sessionId}/subagents/agent-{id}.jsonl
+     * Clear all indexed data and re-index every transcript, from every agent.
      *
      * Optimized: discovers all files first, then processes them in a single
      * SQLite transaction with pre-prepared statements. This avoids the overhead
      * of 3000+ individual transactions (each forcing a disk sync).
-     *
-     * Stores `projectsDir` as a class field so `rebuild()` can reuse it.
      */
-    buildFull(projectsDir: string): void;
-    /**
-     * Incrementally re-index only files whose mtime has changed since last index.
-     * New files (not in indexed_files) are always indexed.
-     *
-     * WARNING: This walks ALL files under projectsDir and stats each one.
-     * On large session stores (3000+ files) this can take minutes.
-     * Prefer `updateRecent()` for CLI search paths.
-     */
-    updateStale(projectsDir: string): void;
+    buildFull(): void;
     /**
      * Lightweight incremental update for CLI search paths.
      *
@@ -102,53 +87,8 @@ export declare class SearchIndex {
      * Caps re-indexing to `maxFiles` to prevent blocking on large backlogs
      * (run `index rebuild` for a full catch-up).
      */
-    updateRecent(projectsDir: string, maxFiles?: number): void;
-    /**
-     * Re-run buildFull using the previously stored projectsDir.
-     * No-op if projectsDir was never set.
-     */
-    rebuild(): void;
-    /**
-     * Walk the projects directory tree and invoke `callback` for every JSONL file.
-     *
-     * Directory structure:
-     *   projectsDir/
-     *     {projectName}/
-     *       {sessionId}.jsonl              <- session file
-     *       {sessionId}/subagents/
-     *         agent-{agentId}.jsonl        <- subagent file (recursive)
-     *
-     * Skips the "memory" directory.
-     */
+    updateRecent(maxFiles?: number): void;
+    /** Every transcript from every agent, tagged with the session it belongs to. */
     private discoverFiles;
-    /**
-     * Recursively discover subagent JSONL files under the subagents directory
-     * that corresponds to `parentPath`.
-     *
-     * For a parent at `/path/to/session-1.jsonl`, looks for subagents at
-     * `/path/to/session-1/subagents/agent-*.jsonl`.
-     *
-     * Recurses up to `maxDepth` levels (default 4).
-     */
-    private discoverSubagents;
-    /**
-     * Start watching `projectsDir` for JSONL file changes.
-     * Runs `updateStale()` immediately for an initial sync, then sets up
-     * `fs.watch` with `{ recursive: true }` (macOS-compatible) to detect
-     * subsequent file changes and trigger debounced re-indexing.
-     */
-    startWatching(projectsDir: string): void;
-    /**
-     * Stop the file watcher and clear any pending debounce timers.
-     * Safe to call even when not watching (no-op).
-     */
-    stopWatching(): void;
-    /**
-     * Private helper: debounce re-indexing of a single file.
-     * Waits 2 seconds after the last change event for a given file path
-     * before actually calling `indexFile()`. This coalesces rapid writes
-     * (e.g. streaming JSONL appends) into a single index operation.
-     */
-    private debouncedReindex;
     close(): void;
 }

package/dist/lib/sessionStats.d.ts

@@ -5,6 +5,7 @@
  * computed here: pricing needs the live LiteLLM rate table, which callers
  * apply via shared/usageCost/pricing.ts.
  */
-import type { Turn, SessionStats } from "./types";
+import type { Turn, SessionStats, TokenUsage } from "./types";
 export declare function createEmptySessionStats(turnCount: number): SessionStats;
 export declare function computeStats(turns: Turn[]): SessionStats;
+export declare function mergeTokenUsage(existing: TokenUsage | null, incoming: TokenUsage): TokenUsage;

package/dist/lib/sessionStatus.d.ts

@@ -1,42 +1,21 @@
 /**
- * Derives the current session status from raw JSONL messages.
- * Walks backward from the last message to determine if the agent
- * is idle, thinking, calling tools, etc.
+ * Session status: what the agent is doing right now, and how to label it.
  *
- * This is a pure function — status is always derived from data,
- * never stored as app state.
+ * Status is always derived from raw transcript records, never stored as app
+ * state. Each format derives its own — this file only routes to the format the
+ * records were written in, and holds the presentation labels.
  */
-export type SessionStatus = "idle" | "thinking" | "tool_use" | "processing" | "completed" | "compacting" | "deferred" | "awaiting_agents";
-export interface SessionStatusInfo {
-    status: SessionStatus;
-    /** Name of the tool currently being used (if status is tool_use) */
-    toolName?: string;
-    /** Number of pending queue items (user messages waiting to be processed) */
-    pendingQueue?: number;
-    /** Why the session terminated (from Claude Code's terminal_reason). Only set for non-normal endings. */
-    terminalReason?: string;
-    /** Number of background agents/workflows still running (status awaiting_agents) */
-    pendingAgents?: number;
-    /** Short descriptions of the pending background agents, oldest first */
-    pendingAgentDescriptions?: string[];
-}
-type RawMsg = {
-    type: string;
-    [key: string]: unknown;
-};
+import type { RawRecord, SessionStatus, SessionStatusInfo } from "./types";
+export type { SessionStatus, SessionStatusInfo } from "./types";
 /**
- * Derive session status from raw JSONL message objects.
+ * Derive session status from raw JSONL record objects.
  *
- * **Provider dispatch:** The function auto-detects the session format by
- * inspecting `rawMessages[0].type`. Codex sessions start with one of
- * `session_meta | turn_context | event_msg | response_item` and are routed
- * to `deriveCodexSessionStatus`. All other sessions are treated as Claude Code
- * format. If a third provider is added, add a detection branch here and in
- * `src/lib/providers/registry.ts`.
+ * The format is resolved from the records themselves, in `AGENT_KINDS` order,
+ * so a transcript that carries no positive discriminator lands on the terminal
+ * format — the same fallback the parser uses.
  */
-export declare function deriveSessionStatus(rawMessages: RawMsg[]): SessionStatusInfo;
+export declare function deriveSessionStatus(rawMessages: RawRecord[]): SessionStatusInfo;
 /** Human-readable label for terminal_reason values from Claude Code. */
 export declare function getTerminalReasonLabel(reason: string): string;
 /** Human-readable label for a session status. Returns null for "idle". */
 export declare function getStatusLabel(status: SessionStatus | undefined, toolName?: string, terminalReason?: string, pendingAgents?: number): string | null;
-export {};

package/dist/lib/stores.d.ts

@@ -0,0 +1,48 @@
+import { type AgentDescriptor, type AgentKind } from "./agent-descriptors";
+/** One transcript on disk, plus what an index needs to file it under. */
+export interface SessionFile {
+    path: string;
+    mtimeMs: number;
+    sessionId: string;
+    isSubagent: boolean;
+    parentSessionId: string | null;
+}
+/** Where a transcript belongs, without reading it. */
+export type SessionFileIdentity = Omit<SessionFile, "path" | "mtimeMs">;
+export interface AgentSessionStore {
+    readonly kind: AgentKind;
+    readonly instanceId: string;
+    readonly descriptor: AgentDescriptor;
+    /** Absolute root this agent's transcripts live under. */
+    root(): string;
+    /** True when an absolute path is inside this agent's root. */
+    ownsPath(filePath: string): boolean;
+    /**
+     * Which session a transcript belongs to. Never `basename(file, ".jsonl")`:
+     * that is Copilot's literal `events`, and it loses a sub-agent's parent.
+     */
+    identify(filePath: string, root?: string): SessionFileIdentity;
+    /** Transcripts modified at or after `cutoffMs`. */
+    list(cutoffMs: number, root?: string): SessionFile[];
+    /** Locate a session by id, or null when this agent does not have it. */
+    find(sessionId: string): string | null;
+}
+export declare function storeFor(kind: AgentKind): AgentSessionStore;
+/** The store a path under no known root is read with: the agent that owns every unprefixed project. */
+export declare function defaultStore(): AgentSessionStore;
+/** Every store, in registry order. */
+export declare function allStores(): readonly AgentSessionStore[];
+/** The store whose root contains `filePath`, or null when none does. */
+export declare function storeForPath(filePath: string): AgentSessionStore | null;
+/**
+ * Transcripts from every agent, newest first. One walk per root, so no caller
+ * can accidentally cover a different set of agents from its neighbours.
+ */
+export declare function listAllSessionFiles(cutoffMs: number): SessionFile[];
+/**
+ * Absolute path of a session's transcript, searched across every agent.
+ *
+ * The id arrives from a CLI argument and is joined straight onto a root, so it
+ * is rejected outright unless it is a single path segment.
+ */
+export declare function findSessionFile(sessionId: string): Promise<string | null>;

package/dist/lib/toolResults.d.ts

@@ -0,0 +1,12 @@
+import type { ToolCall, ToolFileDiff } from "./types";
+export declare function toolResultMetadata(name: string, value: unknown): Pick<ToolCall, "awaitingReview" | "fileDiffs" | "additionalFileDiffs">;
+export declare function formatToolFileDiff(file: ToolFileDiff): string;
+export declare function toolDiffEdits(files: readonly ToolFileDiff[]): Array<{
+    filePath: string;
+    oldString: string;
+    newString: string;
+    diffLineCounts: {
+        add: number;
+        del: number;
+    };
+}>;

package/dist/lib/turnBuilder.d.ts

@@ -33,6 +33,28 @@ export declare function pairAgentMessageReplies(turns: readonly Turn[]): Turn[];
  *
  * Mirrors the turn-creation rule of `buildTurns` below — a parser test asserts
  * the two agree, so keep them in lockstep.
+ *
+ * This is a cheap forward scan on the append hot path, which is the only reason
+ * it restates the rule instead of calling `buildTurnsWithStarts`. It is
+ * deliberately NOT used to cut a transcript: undo and branching go through
+ * `AgentFormat.turnBoundaries`, which is derived from the real turn walk,
+ * because a boundary that disagrees with the parser truncates history. Widen
+ * this only alongside `buildTurns`, never on its own.
  */
 export declare function findTurnStartIndices(messages: RawMessage[]): number[];
+export interface BuiltTurns {
+    turns: Turn[];
+    /** Index, into `messages`, of the record that opened each turn. */
+    turnStartIndices: number[];
+}
+/**
+ * Build turns and report where each one started.
+ *
+ * Turn boundaries used to be derived by a separate predicate that restated this
+ * function's turn rule; the two drifted, and because boundaries decide where a
+ * transcript gets physically cut, the disagreement silently truncated history.
+ * Both now come from this one walk.
+ */
+export declare function buildTurnsWithStarts(messages: RawMessage[]): BuiltTurns;
+/** Turns only — the common case. */
 export declare function buildTurns(messages: RawMessage[]): Turn[];

package/dist/lib/turnContent.d.ts

@@ -0,0 +1,2 @@
+import type { Turn } from "./types";
+export declare function appendAssistantText(turn: Turn, text: string, timestamp: string): void;