cogpit-memory 0.1.9 → 0.2.1

package/dist/lib/agentEnvelope.d.ts

@@ -0,0 +1,24 @@
+export interface ParsedAgentEnvelope {
+    /** Sender named by the first envelope that names one, or null when none does. */
+    sender: string | null;
+    /** True when at least one envelope was unwrapped, even if it named no sender. */
+    matched: boolean;
+    /** Text with every envelope unwrapped. Unchanged when no envelope matched. */
+    body: string;
+}
+/**
+ * Removes envelope framing that wraps a body — an envelope no reader unwrapped,
+ * or the trailing tag the nested case above leaves behind. Only the wrapper
+ * goes: a tag quoted inside the body is content, and stays.
+ */
+export declare function stripEnvelopeFraming(body: string): string;
+export declare function parseAgentEnvelope(text: string): ParsedAgentEnvelope;
+/**
+ * Whether a message reads as asking the reader for something: announced in the
+ * opening, or left on the closing line as a `?` or a request.
+ *
+ * This is the one guessed signal in agent mail, so callers must gate it on the
+ * message also being unanswered — a false positive then disappears as soon as
+ * the reader replies, and can never go stale on screen.
+ */
+export declare function looksLikeQuestion(body: string): boolean;

package/dist/lib/codex-exec.d.ts

@@ -0,0 +1,27 @@
+export interface JsStringLiteral {
+    endIndex: number;
+    value: string;
+}
+export interface CodexExecInvocation {
+    name: string;
+    argumentSource: string;
+    startIndex: number;
+}
+export declare function readJsStringLiteral(source: string, startIndex: number): JsStringLiteral | null;
+/**
+ * Extract actual tool invocations from a Codex code-mode `exec` script.
+ *
+ * This is a lexer, not a JavaScript evaluator: it deliberately ignores strings
+ * and comments, balances nested literals, and only recognizes calls rooted at
+ * the injected `tools` object. That keeps transcript rendering deterministic
+ * and safe even when the persisted script is malformed or user-controlled.
+ */
+export declare function extractCodexExecInvocations(source: string): CodexExecInvocation[];
+/** Return the source expression for a top-level property of an object argument. */
+export declare function extractJsPropertySource(source: string, property: string): string | null;
+/** Find simple string-valued object properties at any nesting depth. */
+export declare function extractJsStringPropertyValues(source: string, property: string): string[];
+/** Find simple numeric object properties at any nesting depth. */
+export declare function extractJsNumberPropertyValues(source: string, property: string): number[];
+/** Count top-level entries in an array literal, or one for a non-empty value. */
+export declare function countJsCollectionEntries(source: string): number;

package/dist/lib/codex-patches.d.ts

@@ -0,0 +1,9 @@
+import type { ToolCall } from "./types";
+/** Extract patch payloads passed to nested `tools.apply_patch(...)` calls in Codex exec scripts. */
+export declare function extractApplyPatchInputs(execSource: string): string[];
+/** Parse a Codex apply_patch string into per-file Edit/Write tool calls. */
+export declare function parseApplyPatch(patchText: string, callId: string, timestamp: string, cwd?: string): ToolCall[];
+/** Normalize direct and exec-wrapped Codex apply_patch calls into file tool calls. */
+export declare function parseCodexToolPatches(toolName: string, rawInput: string, callId: string, timestamp: string, cwd?: string): ToolCall[];
+/** Attribute an exec-wrapper patch failure without tainting earlier successful patch calls. */
+export declare function findFailedNestedPatchCallIds(output: string, wrapperIsError: boolean, calls: readonly ToolCall[]): Set<string>;

package/dist/lib/codex-tool-normalization.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a Codex function name to its canonical collaboration-tool name.
+ * Current collaboration tools carry a namespace separately, but older and
+ * transitional rollouts also encoded it in the function name itself.
+ */
+export declare function normalizeFunctionName(rawName: string): string;
+export declare function inferToolError(output: string | null): boolean;
+/** Normalize Codex update_plan input to TodoWrite format. */
+export declare function normalizePlanToTodos(input: Record<string, unknown>): Record<string, unknown>;
+/** Parse Codex custom_tool_call output JSON or structured content blocks. */
+export declare function parseCustomToolOutput(output: unknown): {
+    text: string;
+    isError: boolean;
+};

package/dist/lib/codex.d.ts

@@ -0,0 +1,30 @@
+import type { ParseSessionOptions, ParsedSession } from "./types";
+export { extractApplyPatchInputs, findFailedNestedPatchCallIds, parseApplyPatch, parseCodexToolPatches, } from "./codex-patches";
+export { parseCustomToolOutput } from "./codex-tool-normalization";
+interface CodexMetadata {
+    sessionId: string;
+    version: string;
+    gitBranch: string;
+    cwd: string;
+    model: string;
+    slug: string;
+    name: string;
+    branchedFrom?: {
+        sessionId: string;
+        turnIndex?: number | null;
+    };
+    firstUserMessage: string;
+    lastUserMessage: string;
+    timestamp: string;
+    lastTimestamp: string;
+    turnCount: number;
+    /** True when this session is a Codex sub-agent (spawned by spawn_agent) */
+    isSubagent: boolean;
+    /** Parent session ID for sub-agent sessions */
+    parentSessionId: string | null;
+    /** Canonical collaboration path for the agent that owns this rollout. */
+    agentPath: string;
+}
+export declare function isCodexSessionText(jsonlText: string): boolean;
+export declare function extractCodexMetadataFromLines(lines: string[]): CodexMetadata;
+export declare function parseCodexSession(jsonlText: string, options?: ParseSessionOptions): ParsedSession;

package/dist/lib/dirs.d.ts

@@ -0,0 +1,8 @@
+export declare const dirs: {
+    PROJECTS_DIR: string;
+    TEAMS_DIR: string;
+    TASKS_DIR: string;
+    CODEX_SESSIONS_DIR: string;
+};
+/** Default database path for the FTS5 search index. */
+export declare const DEFAULT_DB_PATH: string;

package/dist/lib/helpers.d.ts

@@ -0,0 +1,25 @@
+/** 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

@@ -0,0 +1,40 @@
+/**
+ * Interactive prompt detection — plan approval and user question states.
+ */
+import type { ParsedSession, Turn } from "./types";
+export interface PlanApprovalState {
+    type: "plan";
+    allowedPrompts?: Array<{
+        tool: string;
+        prompt: string;
+    }>;
+}
+export interface UserQuestionState {
+    type: "question";
+    toolUseId: string;
+    questions: Array<{
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }>;
+}
+export type PendingInteraction = PlanApprovalState | UserQuestionState | null;
+/**
+ * Check if the previous turn's last tool call is the same interactive tool that
+ * *errored* -- indicates a stuck re-call loop we should suppress.
+ *
+ * An unanswered (result === null) prompt in the previous turn is NOT a loop:
+ * it just means the user replied with a message instead of answering, and the
+ * agent is now asking again. Treating that as stuck suppressed the current
+ * prompt entirely, leaving the turn blocked with no way to answer it.
+ */
+export declare function isStuckInteractiveLoop(turns: Turn[], toolName: string): boolean;
+/**
+ * Detect if the session is waiting for user interaction (plan approval or
+ * AskUserQuestion). Returns the interaction state or null.
+ */
+export declare function detectPendingInteraction(session: ParsedSession): PendingInteraction;

package/dist/lib/messageTypeGuards.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared message type guards for RawMessage discrimination.
+ *
+ * Previously duplicated between turnBuilder.ts and parser.ts to avoid circular
+ * dependencies. Extracted here as a dependency-free leaf module (imports only
+ * from ./types) so both files can share a single source of truth.
+ */
+import type { RawMessage, UserMessage, AssistantMessage, ProgressMessage, SystemMessage, SummaryMessage, QueueOperationMessage, AttachmentMessage } from "./types";
+export declare function isUserMessage(msg: RawMessage): msg is UserMessage;
+export declare function isAssistantMessage(msg: RawMessage): msg is AssistantMessage;
+export declare function isProgressMessage(msg: RawMessage): msg is ProgressMessage;
+export declare function isSystemMessage(msg: RawMessage): msg is SystemMessage;
+export declare function isSummaryMessage(msg: RawMessage): msg is SummaryMessage;
+export declare function isQueueOperationMessage(msg: RawMessage): msg is QueueOperationMessage;
+export declare function isAttachmentMessage(msg: RawMessage): msg is AttachmentMessage;
+/**
+ * The synthetic user message Claude Code writes after compacting, carrying the
+ * summary text. Flagged `isVisibleInTranscriptOnly` too — it is transcript
+ * furniture, never something the user typed.
+ */
+export declare function isCompactSummaryMessage(msg: RawMessage): msg is UserMessage & {
+    isCompactSummary: true;
+};
+export declare function isCompactBoundary(msg: RawMessage): msg is SystemMessage & {
+    subtype: "compact_boundary";
+};

package/dist/lib/metadata.d.ts

@@ -0,0 +1,31 @@
+import { type SessionStatusInfo } from "./sessionStatus";
+export declare function getSessionMeta(filePath: string): Promise<{
+    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.
+ * Scans in 4KB chunks from the tail, parsing one line at a time until it
+ * finds a meaningful message (assistant or non-meta user). This reads only
+ * as far as needed — typically one chunk — and uses the same
+ * 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

@@ -0,0 +1,14 @@
+import type { ParsedSession, ImageBlock, ParseSessionOptions, 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.
+ */
+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/response.d.ts

@@ -0,0 +1,2 @@
+/** Parse a duration string like "5d", "12h", "30m" to milliseconds. */
+export declare function parseMaxAge(raw: string): number;

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

@@ -0,0 +1,154 @@
+export interface IndexStats {
+    dbPath: string;
+    dbSizeBytes: number;
+    dbSizeMB: number;
+    indexedFiles: number;
+    indexedSessions: number;
+    indexedSubagents: number;
+    totalRows: number;
+    watcherRunning: boolean;
+    lastFullBuild: string | null;
+    lastUpdate: string | null;
+}
+export interface SearchHit {
+    sessionId: string;
+    filePath: string;
+    location: string;
+    snippet: string;
+    matchCount: number;
+}
+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;
+    /** Index tool call inputs and results under the given location prefix. */
+    private insertToolCalls;
+    /**
+     * Insert all searchable content from a parsed session into the FTS5 index.
+     * Shared by both `indexFile` (single-file) and `buildFull` (batch).
+     */
+    private insertSessionContent;
+    /**
+     * Parse a JSONL file and insert all searchable content into the FTS5 index.
+     * Idempotent: deletes old data for the file before re-indexing.
+     * All inserts run in a single transaction for performance.
+     */
+    indexFile(filePath: string, sessionId?: string, mtimeMs?: number, opts?: {
+        isSubagent?: boolean;
+        parentSessionId?: string | null;
+    }): void;
+    /**
+     * Query the FTS5 index and return structured search results.
+     *
+     * - FTS5 unicode61 tokenizer is case-insensitive by default.
+     * - When `caseSensitive` is true, a post-filter checks the original query
+     *   against the snippet text (exact case match).
+     * - When `maxAgeMs` is provided, only files whose mtime in `indexed_files`
+     *   falls within the window are included (join on source_file).
+     * - `sessionId` restricts results to a single session.
+     * - `limit` defaults to 200 and is clamped to a max of 200.
+     */
+    search(query: string, opts?: {
+        limit?: number;
+        sessionId?: string;
+        maxAgeMs?: number;
+        caseSensitive?: boolean;
+    }): SearchHit[];
+    /**
+     * Count total matching rows and distinct sessions for a query (without LIMIT).
+     * Used by the route to report accurate totalHits and sessionsSearched.
+     */
+    countMatches(query: string, opts?: {
+        sessionId?: 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
+     *
+     * 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;
+    /**
+     * Lightweight incremental update for CLI search paths.
+     *
+     * Still walks and stats all files via `discoverFiles`, but skips DB lookups
+     * for files with mtime <= the high-water mark that are already indexed.
+     * 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.
+     */
+    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

@@ -0,0 +1,10 @@
+/**
+ * Session statistics computation — token usage aggregation and tool call tallying.
+ *
+ * Token totals are the raw figures the transcript reports. Costs are not
+ * computed here: pricing needs the live LiteLLM rate table, which callers
+ * apply via shared/usageCost/pricing.ts.
+ */
+import type { Turn, SessionStats } from "./types";
+export declare function createEmptySessionStats(turnCount: number): SessionStats;
+export declare function computeStats(turns: Turn[]): SessionStats;

package/dist/lib/sessionStatus.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ *
+ * This is a pure function — status is always derived from data,
+ * never stored as app state.
+ */
+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;
+};
+/**
+ * Derive session status from raw JSONL message 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`.
+ */
+export declare function deriveSessionStatus(rawMessages: RawMsg[]): 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/token-costs.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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;

package/dist/lib/turnBuilder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turn builder — state machine that converts raw JSONL messages into Turn objects.
+ */
+import type { RawMessage, Turn } from "./types";
+/**
+ * Attach each peer message to the `SendMessage` that answered it.
+ *
+ * Walks blocks in chronological order holding the still-unanswered messages per
+ * sender, so a reply claims the oldest outstanding message from that sender and
+ * pairing only ever runs forward in time. A `SendMessage` sent *before* any
+ * inbound message from that sender is an instruction, not a reply.
+ *
+ * The join is on the sender name, which is the only key available: the block
+ * carries no task id, because `origin.senderTaskId` names the sending agent's
+ * task rather than the message. `SendMessage.input.to` uses the same names that
+ * arrive in `origin.from`, so the join holds.
+ *
+ * A pure recompute: every existing pairing is cleared before the walk, so the
+ * answer depends only on the list handed in. Callers that assemble a transcript
+ * from several `buildTurns` calls — the page stitcher and the incremental
+ * append — re-run it over the joined list and get what a single parse of that
+ * list would have produced. Turns holding no peer message come back by
+ * reference, so a re-run costs nothing for the rest of the transcript.
+ */
+export declare function pairAgentMessageReplies(turns: readonly Turn[]): Turn[];
+/**
+ * Raw-message index where each turn `buildTurns` would produce begins, so
+ * `starts[i]` is the index that produces `turns[i]`.
+ *
+ * Incremental appends need both a rebuild cut point and the number of turns
+ * that precede it. Deriving them separately is how an append drifts out of
+ * sync with a full re-parse, so both come from this one pass.
+ *
+ * Mirrors the turn-creation rule of `buildTurns` below — a parser test asserts
+ * the two agree, so keep them in lockstep.
+ */
+export declare function findTurnStartIndices(messages: RawMessage[]): number[];
+export declare function buildTurns(messages: RawMessage[]): Turn[];