cogpit-memory 0.2.1 → 0.3.0

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,17 @@
+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;
 };
 /** 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/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/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,47 @@
+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 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/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;

package/dist/lib/types.d.ts

@@ -1,3 +1,30 @@
+/** The agent CLIs Cogpit can drive. */
+export type AgentKind = "claude" | "codex" | "copilot";
+/**
+ * Every agent kind, in transcript-detection order. Codex and Copilot carry
+ * positive discriminators in their records; Claude is the terminal fallback and
+ * must stay last.
+ */
+export declare const AGENT_KINDS: readonly AgentKind[];
+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[];
+}
+/** A raw transcript record, before any agent-specific interpretation. */
+export type RawRecord = {
+    type: string;
+    [key: string]: unknown;
+};
 export interface TextBlock {
     type: "text";
     text: string;
@@ -324,8 +351,18 @@ export interface ToolCall {
     name: string;
     input: Record<string, unknown>;
     result: string | null;
+    /** Binary images returned by a tool, when the provider persists them. */
+    resultImages?: ImageBlock[];
     isError: boolean;
     timestamp: string;
+    /**
+     * A question whose tool result is only an acceptance receipt. Codex's
+     * `request_user_input_async` returns `{"accepted":true}` at once and the
+     * agent keeps working, so the answer arrives later as an ordinary message
+     * rather than as this call's result — `result !== null` does not mean
+     * answered here.
+     */
+    asyncQuestion?: boolean;
     /** Set by parser when a PostToolUse hook replaced this tool's output */
     outputReplacedByHook?: boolean;
     /** Total duration of PostToolUse hooks attached to this call, summed in ms */
@@ -511,10 +548,11 @@ export interface ParsedSession {
         turnIndex?: number | null;
     };
     /**
-     * The provider that produced this session. Set by the parser when the
-     * format is known. Consumers can use this instead of inspecting rawMessages.
+     * The agent that produced this session, as determined by the parser from the
+     * transcript's own bytes. This is the parser's finding, not the app's source
+     * of truth — the session's dirName is (see `shared/session/agents.ts`).
      */
-    agentKind?: "claude" | "codex";
+    agentKind?: AgentKind;
 }
 export interface ArchivedToolCall {
     type: "Edit" | "Write";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cogpit-memory",
-  "version": "0.2.1",
-  "description": "CLI tool for Claude Code and Codex session introspection",
+  "version": "0.3.0",
+  "description": "CLI tool for Claude Code, Codex, and GitHub Copilot CLI session introspection",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -13,6 +13,7 @@
   "keywords": [
     "claude-code",
     "codex",
+    "github-copilot",
     "session",
     "memory",
     "cli",