cogpit-memory 0.1.9 → 0.1.10

package/dist/lib/types.d.ts

@@ -0,0 +1,401 @@
+export interface TextBlock {
+    type: "text";
+    text: string;
+}
+export interface ThinkingBlock {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+}
+export interface ToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | ContentBlock[];
+    is_error?: boolean;
+}
+export interface Base64MediaSource {
+    type: "base64";
+    media_type: string;
+    data: string;
+}
+export interface ImageBlock {
+    type: "image";
+    source: Base64MediaSource;
+}
+export interface DocumentBlock {
+    type: "document";
+    source: Base64MediaSource;
+}
+export interface AudioBlock {
+    type: "audio";
+    source: Base64MediaSource;
+}
+/** Claude emits this when an API request falls back from one model to another. */
+export interface FallbackBlock {
+    type: "fallback";
+    from: {
+        model: string;
+    };
+    to: {
+        model: string;
+    };
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock | ImageBlock | DocumentBlock | AudioBlock | FallbackBlock;
+export type UserContent = string | ContentBlock[];
+interface BaseMessage {
+    type: string;
+    [key: string]: unknown;
+    parentUuid?: string | null;
+    isSidechain?: boolean;
+    cwd?: string;
+    sessionId?: string;
+    version?: string;
+    gitBranch?: string;
+    uuid?: string;
+    timestamp?: string;
+    userType?: string;
+    slug?: string;
+}
+/** Summary result from an Agent/Task tool call (new format, v2.1.63+) */
+export interface AgentToolUseResult {
+    status: string;
+    prompt: string;
+    agentId: string;
+    content: ContentBlock[];
+    totalDurationMs?: number;
+    totalTokens?: number;
+    totalToolUseCount?: number;
+    usage?: TokenUsage;
+}
+export interface UserMessage extends BaseMessage {
+    type: "user";
+    message: {
+        role: "user";
+        content: UserContent;
+    };
+    isMeta?: boolean;
+    permissionMode?: string;
+    thinkingMetadata?: {
+        maxThinkingTokens: number;
+    };
+    toolUseResult?: AgentToolUseResult;
+    sourceToolAssistantUUID?: string;
+}
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+    /** "fast" when the turn ran in fast mode (billed at a higher tier on Opus 4.6/4.7) */
+    speed?: string;
+}
+export interface AssistantMessage extends BaseMessage {
+    type: "assistant";
+    message: {
+        model: string;
+        id: string;
+        role: "assistant";
+        content: ContentBlock[];
+        stop_reason: string | null;
+        usage: TokenUsage;
+    };
+    requestId?: string;
+}
+/**
+ * @deprecated Claude Code v2.1.63+ no longer emits inline agent_progress messages.
+ * Subagent results now come as `toolUseResult` on the tool_result UserMessage.
+ * This interface is kept for backward compat with old sessions and for
+ * subagentWatcher.ts which synthesizes these for live progress display.
+ * New features should use AgentToolUseResult instead.
+ */
+export interface AgentProgressData {
+    type: "agent_progress";
+    message: {
+        type: "user" | "assistant";
+        message: {
+            role: string;
+            content: unknown;
+        };
+        uuid?: string;
+        timestamp?: string;
+    };
+    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 interface HookProgressData {
+    type: "hook_progress";
+    /** Event name (newer SDK: hook_event_name; older SDK: hookEvent) */
+    hook_event_name?: HookEventName | string;
+    /** Older SDK field for event name (e.g. "PostToolUse") */
+    hookEvent?: HookEventName | string;
+    /** Human-readable hook name like "PostToolUse:Read" (older SDK) */
+    hookName?: string;
+    /** Source of the hook configuration: "settings" | "plugin" | "skill" */
+    source?: string;
+    /** Tool call this hook is associated with (for Pre/PostToolUse) */
+    tool_use_id?: string;
+    /** Tool name (Pre/PostToolUse) */
+    tool_name?: string;
+    /** Hook command line that ran */
+    command?: string;
+    /** stdout/stderr from the hook command */
+    output?: string;
+    stderr?: string;
+    /** Exit code */
+    exit_code?: number;
+    /** Decision returned by hook (allow/deny/block/ask/defer) */
+    decision?: string;
+    /** Duration in milliseconds (PostToolUse, 2.1.119+) */
+    duration_ms?: number;
+    /** Hook-specific output (e.g., updatedToolOutput, sessionTitle) */
+    hookSpecificOutput?: Record<string, unknown>;
+    /** Permits arbitrary additional fields without coupling */
+    [key: string]: unknown;
+}
+export interface ParsedHookEvent {
+    /** Event name like "PreToolUse" */
+    eventName: string;
+    /** Source: settings/plugin/skill */
+    source?: string;
+    /** Tool the hook is gated on (for Pre/PostToolUse) */
+    toolName?: string;
+    toolUseId?: string;
+    /** Command that ran */
+    command?: string;
+    output?: string;
+    stderr?: string;
+    exitCode?: number;
+    decision?: string;
+    /** Duration in ms */
+    durationMs?: number;
+    /** PostToolUse hooks (2.1.121) can replace tool output via updatedToolOutput */
+    updatedToolOutput?: string;
+    /** UserPromptSubmit hooks (2.1.94) can set sessionTitle */
+    sessionTitle?: string;
+    /** WorktreeCreate hooks (2.1.84) return worktreePath */
+    worktreePath?: string;
+    timestamp: string;
+}
+export interface ProgressMessage extends BaseMessage {
+    type: "progress";
+    data: AgentProgressData | HookProgressData;
+    parentToolUseID?: string;
+    toolUseID?: string;
+}
+export interface SystemMessage extends BaseMessage {
+    type: "system";
+    subtype?: string;
+    durationMs?: number;
+    isMeta?: boolean;
+    content?: string;
+    compactMetadata?: {
+        trigger: "auto" | "manual";
+        preTokens: number;
+    };
+}
+export interface FileHistorySnapshotMessage extends BaseMessage {
+    type: "file-history-snapshot";
+    messageId?: string;
+    snapshot?: {
+        messageId: string;
+        trackedFileBackups: Record<string, unknown>;
+        timestamp: string;
+    };
+    isSnapshotUpdate?: boolean;
+}
+export interface SummaryMessage extends BaseMessage {
+    type: "summary";
+    leafUuid?: string;
+    summary?: string;
+}
+/** Claude Code persists prompts submitted during an active turn as queue operations. */
+export interface QueueOperationMessage extends BaseMessage {
+    type: "queue-operation";
+    operation: "enqueue" | "dequeue" | "remove" | string;
+    content?: string | null;
+}
+export type RawMessage = UserMessage | AssistantMessage | ProgressMessage | SystemMessage | FileHistorySnapshotMessage | SummaryMessage | QueueOperationMessage;
+export interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    result: string | null;
+    isError: boolean;
+    timestamp: string;
+    /** 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 */
+    hookDurationMs?: number;
+}
+export interface SubAgentMessage {
+    agentId: string;
+    /** The Task/Agent tool_use id this agent belongs to (streaming overlay key) */
+    parentToolUseId?: string;
+    agentName: string | null;
+    subagentType: string | null;
+    type: "user" | "assistant";
+    content: unknown;
+    toolCalls: ToolCall[];
+    thinking: string[];
+    text: string[];
+    timestamp: string;
+    tokenUsage: TokenUsage | null;
+    model: string | null;
+    isBackground: boolean;
+    /** Summary fields from toolUseResult (new format, v2.1.63+) */
+    prompt?: string;
+    status?: string;
+    durationMs?: number;
+    toolUseCount?: number;
+}
+/** Ordered content block within a turn – preserves chronological order */
+export type TurnContentBlock = {
+    kind: "thinking";
+    blocks: ThinkingBlock[];
+    timestamp?: string;
+} | {
+    kind: "text";
+    text: string[];
+    timestamp?: string;
+} | {
+    kind: "tool_calls";
+    toolCalls: ToolCall[];
+    timestamp?: string;
+} | {
+    kind: "queued_prompt";
+    content: string;
+    timestamp?: string;
+} | {
+    kind: "sub_agent";
+    messages: SubAgentMessage[];
+    timestamp?: string;
+} | {
+    kind: "background_agent";
+    messages: SubAgentMessage[];
+    timestamp?: string;
+} | {
+    kind: "hook_event";
+    events: ParsedHookEvent[];
+    timestamp?: string;
+} | {
+    kind: "plan_mode";
+    plan: string;
+    planFilePath?: string;
+    status: "pending" | "approved" | "rejected";
+    toolCalls: ToolCall[];
+    timestamp?: string;
+}
+/**
+ * Away summary / recap block — emitted as a system message with
+ * subtype "away_summary" (Claude Code v2.1.108+, observed in production
+ * JSONL as of 2026-04). The /recap command produces the same shape.
+ * Content is plain text (may be long-form prose, not always markdown).
+ */
+ | {
+    kind: "recap";
+    content: string;
+    timestamp?: string;
+};
+export interface Turn {
+    id: string;
+    userMessage: UserContent | null;
+    /** Chronologically ordered content blocks for rendering */
+    contentBlocks: TurnContentBlock[];
+    thinking: ThinkingBlock[];
+    assistantText: string[];
+    toolCalls: ToolCall[];
+    subAgentActivity: SubAgentMessage[];
+    timestamp: string;
+    durationMs: number | null;
+    tokenUsage: TokenUsage | null;
+    model: string | null;
+    /** Set when a compaction happened before this turn */
+    compactionSummary?: string;
+}
+export interface SessionStats {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheCreationTokens: number;
+    totalCacheReadTokens: number;
+    totalCostUSD: number;
+    toolCallCounts: Record<string, number>;
+    errorCount: number;
+    totalDurationMs: number;
+    turnCount: number;
+}
+export interface ParseSessionOptions {
+    /** Skip aggregate cost/token work and raw-message retention for index-only consumers. */
+    skipStats?: boolean;
+}
+export interface ParsedSession {
+    sessionId: string;
+    version: string;
+    gitBranch: string;
+    cwd: string;
+    slug: string;
+    /** Session display name set via `--name` CLI flag. */
+    name: string;
+    model: string;
+    turns: Turn[];
+    stats: SessionStats;
+    /**
+     * Raw JSONL message objects. Widened from `RawMessage[]` to support multiple
+     * provider formats (Claude Code and Codex) without a discriminated union at
+     * every call site. Use `agentKind` to distinguish formats when needed.
+     */
+    rawMessages: Array<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+    branchedFrom?: {
+        sessionId: string;
+        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.
+     */
+    agentKind?: "claude" | "codex";
+}
+export interface ArchivedToolCall {
+    type: "Edit" | "Write";
+    filePath: string;
+    oldString?: string;
+    newString?: string;
+    replaceAll?: boolean;
+    content?: string;
+}
+export interface ArchivedTurn {
+    index: number;
+    userMessage: string | null;
+    toolCalls: ArchivedToolCall[];
+    thinkingBlocks: string[];
+    assistantText: string[];
+    timestamp: string;
+    model: string | null;
+}
+export interface Branch {
+    id: string;
+    createdAt: string;
+    branchPointTurnIndex: number;
+    label: string;
+    turns: ArchivedTurn[];
+    jsonlLines: string[];
+    /** Branches that were nested within the archived range, preserved for restore */
+    childBranches?: Branch[];
+}
+export interface UndoState {
+    sessionId: string;
+    currentTurnIndex: number;
+    totalTurns: number;
+    branches: Branch[];
+    activeBranchId: string | null;
+}
+export {};

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "cogpit-memory",
-  "version": "0.1.9",
-  "description": "CLI tool for Claude Code session introspection — search, browse, and drill into past sessions",
+  "version": "0.1.10",
+  "description": "CLI tool for Claude Code and Codex session introspection",
+  "packageManager": "bun@1.3.14",
   "main": "./dist/index.js",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "bin": {
-    "cogpit-memory": "./dist/cli.js"
+    "cogpit-memory": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
   },
   "files": [
     "dist/",
@@ -13,9 +17,10 @@
   ],
   "scripts": {
     "test": "bun test",
+    "test:contracts": "bun run build:npm && node scripts/test-package-contract.mjs",
     "build": "bun build --compile src/cli.ts --outfile cogpit-memory",
-    "build:npm": "node scripts/build-npm.mjs",
-    "prepublishOnly": "node scripts/build-npm.mjs"
+    "build:npm": "node scripts/build-npm.mjs && tsc --pretty false -p tsconfig.build.json",
+    "prepublishOnly": "bun run build:npm"
   },
   "dependencies": {
     "better-sqlite3": "^12.6.2"
@@ -23,6 +28,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "bun-types": "latest",
-    "esbuild": "^0.27.3"
+    "esbuild": "^0.27.3",
+    "typescript": "~5.6.2"
   }
 }

package/skill/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: cogpit-memory
-description: CLI tool for Claude Code 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 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.
 ---
 
 # Cogpit Memory -- Session Context CLI
 
-CLI tool that gives any AI assistant memory of past Claude Code sessions. Retrieve conversation history, tool usage, thinking, and sub-agent activity via a layered command structure. **Also supports full-text search across all sessions** and session discovery/listing.
+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.
 
 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.
 
@@ -105,7 +105,7 @@ Response shape:
 ```
 
 Key fields:
-- `userMessage` -- the human's full prompt text (`null` for synthetic turns, images shown as `[image attached]`)
+- `userMessage` -- the human's full prompt text (`null` for synthetic turns; images, documents, and audio are shown as attachment placeholders)
 - `assistantMessage` -- the AI's full text response (`null` if only tools ran)
 - `toolSummary` -- tool name to count (e.g., `{"Read": 5, "Edit": 2}`)
 - `subAgents` -- summary of sub-agents that ran in this turn. Fields `status`, `durationMs`, `toolUseCount` may be `null` for older sessions
@@ -151,7 +151,7 @@ Response shape:
 ```
 
 Key details:
-- `contentBlocks` kinds: `thinking`, `text`, `tool_calls`, `sub_agent`, `background_agent`
+- `contentBlocks` kinds: `thinking`, `text`, `tool_calls`, `sub_agent`, `background_agent`, `queued_prompt`, `hook_event`, `plan_mode`, `recap`
 - 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