cogpit-memory 0.2.1 → 0.4.0

package/dist/lib/types.d.ts

@@ -1,3 +1,30 @@
+/** The agent CLIs Cogpit can drive. */
+export type AgentKind = "claude" | "codex" | "copilot" | "acp";
+/**
+ * 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;
@@ -99,7 +126,10 @@ export interface UserMessage extends BaseMessage {
     thinkingMetadata?: {
         maxThinkingTokens: number;
     };
-    toolUseResult?: AgentToolUseResult;
+    toolUseResult?: Partial<AgentToolUseResult> & {
+        staged?: boolean;
+        bashEditDiff?: unknown;
+    };
     sourceToolAssistantUUID?: string;
 }
 export interface TokenUsage {
@@ -173,7 +203,7 @@ export interface AgentProgressData {
     prompt: string;
     agentId: string;
 }
-export type HookEventName = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "StopFailure" | "SubagentStop" | "PreCompact" | "PostCompact" | "PermissionDenied" | "TaskCreated" | "WorktreeCreate" | "CwdChanged" | "FileChanged" | "Elicitation" | "ElicitationResult" | "Notification";
+export type HookEventName = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "UserPromptSubmit" | "SessionStart" | "SessionEnd" | "Stop" | "StopFailure" | "SubagentStop" | "PreCompact" | "PostCompact" | "PreModelSwitch" | "PostModelSwitch" | "PermissionDenied" | "TaskCreated" | "WorktreeCreate" | "CwdChanged" | "FileChanged" | "Elicitation" | "ElicitationResult" | "Notification";
 export interface HookProgressData {
     type: "hook_progress";
     /** Event name (newer SDK: hook_event_name; older SDK: hookEvent) */
@@ -319,13 +349,41 @@ export interface AgentSettingMessage extends BaseMessage {
     agentSetting?: string;
 }
 export type RawMessage = UserMessage | AssistantMessage | ProgressMessage | SystemMessage | FileHistorySnapshotMessage | SummaryMessage | QueueOperationMessage | AttachmentMessage;
+export interface ToolFileDiff {
+    filePath: string;
+    hunks: Array<{
+        oldStart: number;
+        oldLines: number;
+        newStart: number;
+        newLines: number;
+        lines: string[];
+    }>;
+}
 export interface ToolCall {
     id: string;
     name: string;
     input: Record<string, unknown>;
     result: string | null;
+    /** Binary images returned by a tool, when the provider persists them. */
+    resultImages?: ImageBlock[];
     isError: boolean;
+    awaitingReview?: boolean;
+    fileDiffs?: ToolFileDiff[];
+    additionalFileDiffs?: number;
+    /** Counts from one structured file diff, before combining it with later edits. */
+    diffLineCounts?: {
+        add: number;
+        del: number;
+    };
     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 */
@@ -431,6 +489,17 @@ export type TurnContentBlock = {
     kind: "task_notification";
     content: string;
     timestamp?: string;
+}
+/**
+ * Output of a slash command that ran locally and answered the user directly
+ * (`/usage`, `/context`, `/recap`), recorded as a `local_command` system
+ * record. `content` is the raw record text, `<local-command-stdout>` tags
+ * included, left for the renderers like `task_notification`.
+ */
+ | {
+    kind: "local_command";
+    content: string;
+    timestamp?: string;
 };
 export interface Turn {
     id: string;
@@ -511,10 +580,12 @@ 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;
+    instanceId?: string;
 }
 export interface ArchivedToolCall {
     type: "Edit" | "Write";
@@ -526,6 +597,8 @@ export interface ArchivedToolCall {
 }
 export interface ArchivedTurn {
     index: number;
+    /** The archived turn's `Turn.id`. Absent on archives written before ids were kept. */
+    id?: string;
     userMessage: string | null;
     toolCalls: ArchivedToolCall[];
     thinkingBlocks: string[];
@@ -536,7 +609,14 @@ export interface ArchivedTurn {
 export interface Branch {
     id: string;
     createdAt: string;
+    /**
+     * Position of the fork turn among the turns loaded when this was written.
+     * Only a long session's tail is loaded, so it is re-resolved from
+     * `branchPointTurnId` on every read and trusted as stored only without one.
+     */
     branchPointTurnIndex: number;
+    /** `Turn.id` of the last turn kept before the fork; null when none was kept. */
+    branchPointTurnId?: string | null;
     label: string;
     turns: ArchivedTurn[];
     jsonlLines: string[];
@@ -545,8 +625,6 @@ export interface Branch {
 }
 export interface UndoState {
     sessionId: string;
-    currentTurnIndex: number;
-    totalTurns: number;
     branches: Branch[];
     activeBranchId: string | null;
 }

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.4.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",

package/skill/SKILL.md

@@ -1,29 +1,31 @@
 ---
 name: cogpit-memory
-description: CLI tool for Claude Code and Codex session introspection -- retrieves conversation history, tool calls, thinking, sub-agent/team activity, full-text search, and session discovery. All output is JSON to stdout.
+description: CLI tool for Claude Code, Codex, and GitHub Copilot CLI session introspection -- retrieves conversation history, tool calls, thinking, full-text search, session discovery, and supported sub-agent/team activity. All output is JSON to stdout.
 ---
 
 # Cogpit Memory -- Session Context CLI
 
-CLI tool that gives any AI assistant memory of past Claude Code and Codex sessions. Retrieve conversation history, tool usage, thinking, and sub-agent activity via a layered command structure. Session discovery and layered context support both providers; cross-session full-text indexing currently covers Claude Code history, while `search --session` supports either provider.
+CLI tool that gives any AI assistant memory of past Claude Code, Codex, and GitHub Copilot CLI sessions. Retrieve conversation history, tool usage, thinking, and supported sub-agent activity via a layered command structure. Session discovery, root context and cross-session full-text indexing all cover every provider. Copilot nested activity is included inline in the root session, but `context --agent` is unavailable because Copilot CLI does not write separate sub-agent transcript files.
 
 Always start with session discovery or the overview (Layer 1), and drill into specific turns or sub-agents only as needed. Use search when you need to **find** content rather than browse known sessions.
 
-**Prerequisite:** Bun must be installed (uses bun:sqlite for FTS5 search).
-
-## Step 1 -- Verify the tool works
+## Step 1 -- Use the installed CLI
 
 ```bash
-bunx cogpit-memory --help
+command -v cogpit-memory
+cogpit-memory --help
 ```
 
-If this prints usage info, proceed to Step 2. If `bunx` is not available, install the package globally:
+If missing, install it once, wait for installation to finish, then use the installed command:
 
 ```bash
-npm install -g cogpit-memory
+bun install --global cogpit-memory
+cogpit-memory --help
 ```
 
-Then use `cogpit-memory` directly instead of `bunx cogpit-memory`.
+The npm package requires Node.js 20 or newer. If Bun's global bin directory is not on PATH, resolve it with `bun pm bin --global` and invoke `cogpit-memory` there. Do not run parallel `bunx cogpit-memory` installs: transient native-dependency installation can race. Parallel calls to the installed CLI do not reinstall anything.
+
+JSON goes to stdout. Keep stderr separate when piping to `jq` or Python; never merge it with `2>&1` before a JSON parser. A JSON `{ "error": ... }` response exits nonzero and is a failed lookup, not an empty successful result. Use complete session IDs from discovery or search, not abbreviated IDs.
 
 ## Step 2 -- Find sessions
 
@@ -31,13 +33,13 @@ Then use `cogpit-memory` directly instead of `bunx cogpit-memory`.
 
 ```bash
 # List recent sessions (default: last 7 days, up to 20 results)
-bunx cogpit-memory sessions
+cogpit-memory sessions
 
 # Filter by working directory
-bunx cogpit-memory sessions --cwd /path/to/project
+cogpit-memory sessions --cwd /path/to/project
 
 # Customize limit and time window
-bunx cogpit-memory sessions --limit 50 --max-age 30d
+cogpit-memory sessions --limit 50 --max-age 30d
 ```
 
 Options:
@@ -53,7 +55,7 @@ Response: array of session summaries with `sessionId`, `cwd`, `model`, `firstMes
 ### Get current session for a directory
 
 ```bash
-bunx cogpit-memory sessions --current --cwd /path/to/project
+cogpit-memory sessions --current --cwd /path/to/project
 ```
 
 Returns the most recently active session for the given working directory. The `--cwd` flag is required when using `--current` (defaults to the current working directory if omitted).
@@ -63,7 +65,7 @@ Returns the most recently active session for the given working directory. The `-
 This gives you every user prompt and AI reply, plus a tool usage summary per turn. **You must call this before Layer 2 or Layer 3** -- it provides the `turnIndex` and `agentId` values you need for drill-downs.
 
 ```bash
-bunx cogpit-memory context <SESSION_ID>
+cogpit-memory context <SESSION_ID>
 ```
 
 Response shape:
@@ -117,7 +119,7 @@ Key fields:
 Use this to drill into a specific turn. Get thinking, full tool call inputs/outputs, and sub-agent summaries in chronological order.
 
 ```bash
-bunx cogpit-memory context <SESSION_ID> --turn <TURN_INDEX>
+cogpit-memory context <SESSION_ID> --turn <TURN_INDEX>
 ```
 
 Response shape:
@@ -151,10 +153,10 @@ Response shape:
 ```
 
 Key details:
-- `contentBlocks` kinds: `thinking`, `text`, `tool_calls`, `sub_agent`, `background_agent`, `queued_prompt`, `hook_event`, `plan_mode`, `recap`, `agent_message`
+- `contentBlocks` kinds: `thinking`, `text`, `tool_calls`, `sub_agent`, `background_agent`, `queued_prompt`, `hook_event`, `plan_mode`, `recap`, `agent_message`, `task_notification`, `local_command`
 - Tool call `result` is truncated at 10,000 chars -- check `resultTruncated: true`
 - Tool call `result` may be `null` if the tool hasn't returned yet
-- Sub-agent blocks show prompt + result text. For full sub-agent conversation, use Layer 3
+- Sub-agent blocks show prompt + result text. When the provider writes a separate sub-agent transcript, use Layer 3 for the full conversation
 
 **Make separate requests per turn** -- do not try to batch multiple turns in one call.
 
@@ -163,7 +165,7 @@ Key details:
 Drill into a specific sub-agent's full conversation. Returns the same shape as Layer 1 (an overview of the sub-agent's own turns).
 
 ```bash
-bunx cogpit-memory context <SESSION_ID> --agent <AGENT_ID>
+cogpit-memory context <SESSION_ID> --agent <AGENT_ID>
 ```
 
 Get the `AGENT_ID` from Layer 1's `subAgents[].agentId` field.
@@ -188,7 +190,7 @@ Response shape:
 The `overview` field has the exact same shape as Layer 1. You can then drill into specific sub-agent turns:
 
 ```bash
-bunx cogpit-memory context <SESSION_ID> --agent <AGENT_ID> --turn <TURN_INDEX>
+cogpit-memory context <SESSION_ID> --agent <AGENT_ID> --turn <TURN_INDEX>
 ```
 
 This returns the same shape as Layer 2.
@@ -214,32 +216,42 @@ The typical workflow for drilling into sub-agent activity:
 
 1. Call Layer 1 to get the session overview
 2. Look at `turns[].subAgents[]` to find agent IDs
-3. Call Layer 3 with the `--agent` flag to get that sub-agent's overview
+3. If the provider writes a separate sub-agent transcript, call Layer 3 with the `--agent` flag to get that sub-agent's overview
 4. Call Layer 3 + `--turn` to drill into a specific sub-agent turn
 5. If the sub-agent itself had sub-agents, repeat from step 2 using the sub-agent's overview
 
 ## Session Search -- Find keywords across sessions
 
-Search for keywords across all sessions or within a specific session. Searches **everything**: user messages, assistant responses, thinking blocks, tool call inputs/results, sub-agent messages, sub-agent tool calls, and compaction summaries.
+Cross-session search indexes every provider's history. With `--session`, Claude Code, Codex, and Copilot CLI sessions are all supported, including user and assistant messages, thinking, tool I/O, inline sub-agent content, and compaction summaries when the provider records them.
 
 **When to use search vs Layer 1:**
 - You know the session -> Use Layer 1 overview, then drill with Layer 2/3
 - You need to **find** which session discussed something -> Use search first, then drill into hits
 
+When recalling earlier work, exclude this session if its ID is known, so your search commands and copied results do not crowd out history:
+
+```bash
+cogpit-memory search "authentication" --max-age 90d --exclude-session "$COGPIT_SESSION_ID"
+```
+
+Only pass that flag when the environment variable is set, or supply a known full session ID. Do not guess that the most recently modified session is yours when agents share a project. Omit the flag when searching this session itself. The exclusion also covers its indexed subagents.
+
+Search automatically removes index entries for transcript files that no longer exist. It cannot recover deleted transcripts. If a file disappears between search and `context`, report that the source is unavailable and continue with other hits.
+
 ### Basic usage
 
 ```bash
-# Search across all recent sessions (last 5 days)
-bunx cogpit-memory search "authentication"
+# Search recent indexed sessions from all supported CLIs (last 5 days)
+cogpit-memory search "authentication"
 
 # Search within a specific session
-bunx cogpit-memory search "authentication" --session <SESSION_ID>
+cogpit-memory search "authentication" --session <SESSION_ID>
 
 # Search with custom time window and more results
-bunx cogpit-memory search "authentication" --max-age 30d --limit 50
+cogpit-memory search "authentication" --max-age 30d --limit 50
 
 # Case-sensitive search
-bunx cogpit-memory search "AuthProvider" --case-sensitive
+cogpit-memory search "AuthProvider" --case-sensitive
 ```
 
 ### Options
@@ -247,6 +259,7 @@ bunx cogpit-memory search "AuthProvider" --case-sensitive
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--session` | all sessions | Scope to single session |
+| `--exclude-session` | none | Omit one session and its subagents |
 | `--max-age` | `5d` | Time window: `5d`, `12h`, `30d` |
 | `--limit` | `20` | Max total hits returned |
 | `--session-limit` | all | Cap unique sessions in results |
@@ -298,48 +311,53 @@ Locations map directly to Layer 2/3 drill-down commands -- use them to fetch ful
 - `turn/{i}/toolCall/{id}/input` -- tool call input -> drill with `--turn {i}`
 - `turn/{i}/toolCall/{id}/result` -- tool call result -> drill with `--turn {i}`
 - `turn/{i}/compactionSummary` -- compaction summary -> drill with `--turn {i}`
-- `agent/{agentId}/...` -- sub-agent content -> drill with `--agent {agentId}` then `--agent {agentId} --turn {i}`
+- `agent/{agentId}/...` -- sub-agent content; drill with `--agent {agentId}` only when the provider writes a separate transcript
 
 ### Typical workflow
 
-1. Search for keyword: `bunx cogpit-memory search "auth"`
+1. Search for keyword: `cogpit-memory search "auth"`
 2. Pick a hit from results (e.g., `sessionId: "abc-123"`, `location: "turn/3/assistantMessage"`)
-3. Get full turn context: `bunx cogpit-memory context abc-123 --turn 3`
-4. If hit is in a sub-agent, get agent overview first: `bunx cogpit-memory context abc-123 --agent a7f3bc2`
+3. Get full turn context: `cogpit-memory context abc-123 --turn 3`
+4. If a hit is in a sub-agent with a separate transcript, get its overview: `cogpit-memory context abc-123 --agent a7f3bc2`
 
-### Performance notes
+### Search behavior
 
-- Cross-session search uses a raw-text pre-filter -- files that can't match are skipped before expensive parsing
-- Default 5-day window keeps search fast; increase `--max-age` only if needed
-- Single-session search (`--session` flag) is much faster than cross-session
-- Typical cross-session search: ~150 sessions in ~1-2 seconds
+Cross-session search uses an incrementally updated SQLite FTS5 index, with a raw-file fallback if the index is unavailable. The default window is 5 days. Increase `--max-age` for older work. FTS matches whole tokens, so `auth` does not match `authentication`. `--limit` is capped at 200; narrow a broad query or use `--session` to investigate further.
 
 ## Index management
 
-The search index is an FTS5 trigram database at `~/.claude/cogpit-memory/search-index.db`. Most commands work without the index (falling back to raw file scanning), but indexed search is significantly faster.
+The search index is an FTS5 database at `~/.claude/cogpit-memory/search-index.db`. Most commands work without the index (falling back to raw file scanning), but indexed search is significantly faster.
 
 ```bash
 # Show index stats (session count, staleness, DB size)
-bunx cogpit-memory index stats
+cogpit-memory index stats
 
 # Rebuild the full index from scratch
-bunx cogpit-memory index rebuild
+cogpit-memory index rebuild
 ```
 
 ## Quick reference
 
 | Goal | Command |
 |------|---------|
-| List recent sessions | `bunx cogpit-memory sessions` |
-| Sessions for a directory | `bunx cogpit-memory sessions --cwd <path>` |
-| Current session for a directory | `bunx cogpit-memory sessions --current --cwd <path>` |
-| Session overview (always first) | `bunx cogpit-memory context <sessionId>` |
-| Turn detail | `bunx cogpit-memory context <sessionId> --turn <N>` |
-| Sub-agent overview | `bunx cogpit-memory context <sessionId> --agent <agentId>` |
-| Sub-agent turn detail | `bunx cogpit-memory context <sessionId> --agent <agentId> --turn <N>` |
-| **Search across sessions** | `bunx cogpit-memory search "<query>"` |
-| **Search single session** | `bunx cogpit-memory search "<query>" --session <sessionId>` |
-| Index stats | `bunx cogpit-memory index stats` |
-| Index rebuild | `bunx cogpit-memory index rebuild` |
+| List recent sessions | `cogpit-memory sessions` |
+| Sessions for a directory | `cogpit-memory sessions --cwd <path>` |
+| Current session for a directory | `cogpit-memory sessions --current --cwd <path>` |
+| Session overview (always first) | `cogpit-memory context <sessionId>` |
+| Turn detail | `cogpit-memory context <sessionId> --turn <N>` |
+| Sub-agent overview | `cogpit-memory context <sessionId> --agent <agentId>` |
+| Sub-agent turn detail | `cogpit-memory context <sessionId> --agent <agentId> --turn <N>` |
+| **Search indexed sessions** | `cogpit-memory search "<query>"` |
+| **Search any single provider session** | `cogpit-memory search "<query>" --session <sessionId>` |
+| Index stats | `cogpit-memory index stats` |
+| Index rebuild | `cogpit-memory index rebuild` |
 
 **Default to Layer 1 only. Drill into Layer 2/3 only when you have a specific reason.**
+
+## Provider account identities
+
+Sessions from configured Cogpit provider accounts use account-qualified IDs. Pass
+the full ID to context and search commands. Cogpit supplies
+`COGPIT_ORCHESTRATION_ROOT` to discover these profiles; set it to the app data root
+when running the memory CLI independently. Inside a provider worker, introspection
+uses that account’s own transcript store. ACP transcripts are supported.

package/dist/lib/token-costs.d.ts

@@ -1,27 +0,0 @@
-/**
- * Token display estimation and cost formatting.
- *
- * Pricing lives in shared/usageCost/pricing.ts, driven by LiteLLM's live rate
- * table — nothing here carries hardcoded rates. What remains is display-only
- * accounting of the thinking/visible output split.
- *
- * Claude Code 2.1.19x+ reports thinking tokens directly on the assistant
- * record, so that half of the split is now exact. Older transcripts recorded
- * only the message_start placeholder usage, so they still fall back to a
- * content estimate at ≈4 chars/token — as does the visible-output half, which
- * the CLI does not break out.
- */
-import type { Turn } from "./types";
-/** Approximate characters per token for content-based estimation. */
-export declare const CHARS_PER_TOKEN = 4;
-/**
- * Thinking tokens for a turn: the count the model reported when it is
- * available, falling back to a character estimate for older transcripts.
- *
- * A reported 0 is a fact — a turn that did no thinking — so presence is tested
- * rather than truthiness.
- */
-export declare function estimateThinkingTokens(turn: Turn): number;
-/** Estimate non-thinking output tokens (text + tool use JSON). */
-export declare function estimateVisibleOutputTokens(turn: Turn): number;
-export declare function formatCost(usd: number): string;