cogpit-memory 0.3.0 → 0.4.1

package/dist/lib/agent-descriptors.d.ts

@@ -21,7 +21,7 @@ export { AGENT_KINDS } from "./types";
  * point: a fourth CLI adds one row here instead of a new arm in 40 conditionals.
  */
 export interface AgentCapabilities {
-    /** Git worktrees, which Cogpit stores under the Claude projects tree. */
+    /** Launch a session in a worktree managed by its CLI. */
     readonly worktrees: boolean;
     /** MCP server configuration can be passed at spawn time. */
     readonly mcp: boolean;
@@ -59,8 +59,18 @@ export interface AgentCapabilities {
      * exist only for models whose live catalog entry advertises them.
      */
     readonly reasoningEffort: boolean;
+    readonly configurableContextWindow: boolean;
     /** A faster/priority service tier can be requested. */
     readonly fastTier: boolean;
+    /**
+     * The CLI can carry a session past a spent session allowance by continuing at
+     * lower priority, spending the weekly allowance to do it. The mode is reached
+     * only from the CLI's own terminal UI — no flag, no setting, and nothing on
+     * the programmatic interface Cogpit drives — so the hand-off is all Cogpit
+     * can offer. Never true for an agent billed per request, which has no
+     * allowance to run out of in the first place.
+     */
+    readonly lowPriorityInTerminal: boolean;
     /**
      * Images may be attached when the selected model's catalog entry says nothing
      * about its input modalities. When false, vision has to be advertised.
@@ -68,6 +78,8 @@ export interface AgentCapabilities {
     readonly imageInput: boolean;
     /** A message can be delivered into an already-running turn. */
     readonly midTurnSteering: boolean;
+    /** Shared informational input can join active work at the provider's next opportunity. */
+    readonly activeNotifications: boolean;
     /** The whole session can be shut down from the composer. */
     readonly stopSession: boolean;
     /** Maximum-effort orchestration mode, pinned to the top effort level. */
@@ -85,6 +97,7 @@ export interface AgentCapabilities {
     readonly modelFallbackNotices: boolean;
     /** Whether an unattended "auto" permission mode can be offered. */
     readonly autoPermissionMode: "never" | "per-model" | "always";
+    readonly toolPermissionRules: boolean;
     /** Whether composer settings take effect immediately or on the next turn. */
     readonly settingsApply: "live" | "next-turn";
     /**
@@ -107,6 +120,8 @@ export interface AgentDirNameCodec {
     readonly lossy: boolean;
     /** True when `dirName` belongs to this agent. */
     owns(dirName: string | null | undefined): boolean;
+    /** True when `dirName` is a name `encode` produces, rather than one this agent merely owns. */
+    recognizes(dirName: string): boolean;
     /** Encode a project path as this agent's dirName. */
     encode(cwd: string): string;
     /** Decode one of this agent's dirNames back to a project path. */
@@ -125,6 +140,22 @@ export interface AgentSessionFileCodec {
     urlId(fileName: string): string;
     /** Exact inverse of `urlId`. */
     fileNameFromUrlId(urlId: string): string;
+    /**
+     * The top-level session a transcript belongs to, so a sub-agent or workflow
+     * transcript answers with the session that spawned it. Takes the file's
+     * canonical path — symlinks resolved, `/`-separated — relative to the
+     * project directory where the agent has one on disk, to the sessions root
+     * otherwise; `AgentStore.transcriptRoot` produces exactly that. Null for a
+     * path that could step outside it or names no session.
+     */
+    transcriptRoot(relativePath: string): TranscriptRoot | null;
+}
+/** The top-level session a transcript belongs to. */
+export interface TranscriptRoot {
+    /** Lowercased. */
+    rootSessionId: string;
+    /** False for a sub-agent's or workflow's transcript filed under that session. */
+    isRootTranscript: boolean;
 }
 export interface AgentResumeCodec {
     /** Copy-pasteable shell command that reopens the session in a terminal. */
@@ -184,6 +215,9 @@ export interface AgentCli {
     readonly homeDirName: string;
     /** Environment variable overriding that directory, if the CLI has one. */
     readonly homeEnvVar: string | null;
+    readonly sdkHomeEnvVar?: string;
+    /** The native session ID this CLI supplies to its shell commands. */
+    readonly sessionIdEnvVar?: string;
     /**
      * Path inside the home whose existence proves the CLI has been used. Empty
      * when the home directory itself is the evidence.
@@ -195,6 +229,7 @@ export interface AgentCli {
      * that configuration is missing; the rest sit at a fixed, env-overridable
      * location and can be found on a first run.
      */
+    readonly requiresConfiguration?: boolean;
     readonly homeIsDiscoverable: boolean;
     readonly process: AgentProcessMatch;
 }
@@ -211,6 +246,8 @@ export interface AgentConfigFile {
     readonly scopes: readonly AgentConfigScope[];
     /** Tree label; defaults to `path`. */
     readonly label?: string;
+    /** Read only when none of the agent's other instruction files exist at that scope. */
+    readonly fallback?: true;
 }
 /**
  * Where a CLI reads its instructions, settings and extensions from. Drives the
@@ -329,6 +366,8 @@ export interface AgentDescriptor {
     readonly binName: string;
     readonly dirName: AgentDirNameCodec;
     readonly sessionFile: AgentSessionFileCodec;
+    /** Folder inside a project where the CLI cuts its worktrees; null when they live elsewhere. */
+    readonly projectWorktreeDir: string | null;
     /**
      * Whether header metadata is complete after reading only the first bytes of a
      * transcript. False when an exact line count or the last user message matters
@@ -385,3 +424,6 @@ export declare function projectDirNameFor(kind: AgentKind, cwd: string, knownDir
 export declare function sessionIdFromFileName(kind: AgentKind, fileName: string): string | null;
 /** True when `value` is a bare session UUID. */
 export declare function isSessionUuid(value: string): boolean;
+/** Canonical access identity, preserving the instance token's case. */
+export declare function canonicalSessionId(value: string): string | null;
+export declare const PERSISTED_AGENT_HOME_FIELD = "claudeDir";

package/dist/lib/agents.d.ts

@@ -42,12 +42,25 @@ export interface AgentFormat {
     /** Status derived from raw records. */
     status(records: readonly RawRecord[]): SessionStatusInfo;
     /**
-     * The first record of a transcript, rewritten for a branch: it now names
-     * `sessionId` and records the session and turn it was cut from. Returns the
-     * id the record carried before, which is what the branch reports as its
-     * origin.
+     * True for a raw line the CLI writes for its own bookkeeping that no reader
+     * of the transcript uses. The server drops these before paging or streaming,
+     * so they never take a page's byte budget or line floor.
      */
-    brandBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null): {
+    isNoiseLine(line: string): boolean;
+    /**
+     * The transcript's first line as a page of it carries it, when a reader of
+     * one page needs facts about the rest of the file. `lastLines` reads the
+     * file's last complete lines.
+     */
+    pageHeaderLine?(firstLine: string, lastLines: () => Promise<readonly string[]>): Promise<string>;
+    /**
+     * The first record of a transcript, rewritten for a branch cut at
+     * `branchedAt`: it now names `sessionId` and records the session and turn
+     * it was cut from, and when, where the copied lines cannot otherwise be
+     * told from the branch's own. Returns the id the record carried before,
+     * which is what the branch reports as its origin.
+     */
+    brandBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null, branchedAt: number): {
         record: Record<string, unknown>;
         originalId: string;
     };
@@ -74,6 +87,8 @@ export declare function formatForText(jsonlText: string): AgentFormat;
 export declare function formatForRecords(records: readonly {
     type?: unknown;
 }[]): AgentFormat;
+/** `isNoiseLine` for a scan that reads lines before it knows which agent wrote them. */
+export declare function isAnyAgentNoiseLine(line: string): boolean;
 /**
  * Boundary indexes for raw JSONL lines rather than parsed records.
  *
@@ -94,15 +109,25 @@ export declare function cutLineForTurnCount(format: AgentFormat, lines: readonly
  */
 export declare function cutLineAfterTurnIndex(format: AgentFormat, lines: readonly string[], turnIndex: number): number | null;
 /**
- * The line to cut at to keep everything through the turn containing the record
- * whose `uuid` is `turnUuid`. Correct even when the caller has only a tail of
- * the transcript loaded, so its turn indexes do not match file order.
+ * Each turn's first line paired with the id the parser gives that turn, in file
+ * order. Null when the two do not pair up, which would mean the ids cannot be
+ * trusted to name these lines.
+ *
+ * This is what lets a caller holding only the loaded tail of a transcript name
+ * a turn: its window index says nothing about file order, but its id does.
+ */
+export declare function turnStartsWithIds(format: AgentFormat, lines: readonly string[]): {
+    line: number;
+    id: string;
+}[] | null;
+/**
+ * The line to cut at to keep everything through the turn whose id is `turnId`.
  *
- * `"keep-all"` means the uuid was found in the last turn (nothing to remove);
- * null means it was not found at all, and the caller should fall back to an
- * index-based cut.
+ * `"keep-all"` means it is the last turn (nothing to remove); null means no
+ * turn has that id — an agent may leave a turn unlabelled — and the caller
+ * should fall back to an index-based cut.
  */
-export declare function cutLineAfterUuid(format: AgentFormat, lines: readonly string[], turnUuid: string): number | "keep-all" | null;
+export declare function cutLineAfterTurnId(format: AgentFormat, lines: readonly string[], turnId: string): number | "keep-all" | null;
 /**
  * The tool calls a recorded call actually ran. Every format records one call
  * per tool use except Codex code mode, which persists a whole script of them as

package/dist/lib/backgroundAgents.d.ts

@@ -0,0 +1,16 @@
+import type { BackgroundAgent, SessionStatusInfo } from "./types";
+/** A launched background agent, placed by the transcript records that started and ended it. */
+export interface AgentLaunch {
+    agent: Omit<BackgroundAgent, "done">;
+    /** Index of the record that launched it */
+    launchedAt: number;
+    /** Index of the record that completed, failed or stopped it; absent while it runs */
+    endedAt?: number;
+}
+/**
+ * The awaiting-agents status for a session's background agents, or null when
+ * none is still running. The batch is every agent launched since the last
+ * moment no agent was running, so agents that already finished in this wait
+ * still count toward its progress.
+ */
+export declare function awaitingAgentsStatus(launches: readonly AgentLaunch[], pendingQueue?: number): SessionStatusInfo | null;

package/dist/lib/claude.d.ts

@@ -9,6 +9,16 @@ import type { ParseSessionOptions, ParsedSession, RawRecord, SessionStatusInfo }
  * registry exists to remove.
  */
 export declare function isClaudeSessionText(): boolean;
+/**
+ * True for the `api-request`, `api-request-blob` and `api-request-shape`
+ * records Claude Code 2.1.300+ logs for every API call. Nothing reads them,
+ * and they can be most of a transcript's bytes.
+ *
+ * Inside a JSON string every quote is escaped, so `"type":"api-request` can
+ * only be a key and its value; with no `{` before it but the line's own, it is
+ * the top-level key, wherever the writer put it.
+ */
+export declare function isClaudeNoiseLine(line: string): boolean;
 export interface ClaudeMetadata {
     sessionId: string;
     version: string;

package/dist/lib/codex.d.ts

@@ -25,6 +25,38 @@ 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;
+/**
+ * A rollout's first line as a page of it carries it: a sub-agent's
+ * `session_meta` gains the ordinal of the rollout's last record, so a page
+ * holding only copied history still knows its history boundary is real.
+ */
+export declare function codexPageHeaderLine(firstLine: string, lastLines: () => Promise<readonly string[]>): Promise<string>;
+/**
+ * The prompt a record carries, or "" for any other record, including the
+ * AGENTS.md, environment and other context Codex injects as user messages.
+ */
+export declare function codexPromptText(record: {
+    type?: unknown;
+    payload?: unknown;
+}): string;
+/**
+ * Reads each prompt in a rollout once, fed its records in order.
+ *
+ * Codex 0.15x+ writes a prompt only as a `response_item` user message. Older
+ * CLIs follow that record with an `event_msg` `user_message` echo of it, which
+ * this skips.
+ */
+export declare function createCodexPromptReader(): (record: {
+    type?: unknown;
+    payload?: unknown;
+}) => string;
 export declare function isCodexSessionText(jsonlText: string): boolean;
 /** True when already-parsed raw records came from this CLI. */
 export declare function isCodexRawRecords(records: readonly {
@@ -42,8 +74,12 @@ export declare function parseCodexSession(jsonlText: string, options?: ParseSess
 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. */
-export declare function brandCodexBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null): {
+/**
+ * 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;
 };

package/dist/lib/dirs.d.ts

@@ -12,6 +12,7 @@ export declare const dirs: {
     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/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/read-session.d.ts

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

package/dist/lib/stores.d.ts

@@ -11,6 +11,7 @@ export interface SessionFile {
 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;

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/transcriptFile.d.ts

@@ -0,0 +1,22 @@
+export declare function isCompressedTranscript(filePath: string): boolean;
+/** The name a transcript has uncompressed. */
+export declare function uncompressedTranscriptName(fileName: string): string;
+/**
+ * Whether a directory entry is a transcript this runtime can read, given its
+ * siblings: mid-compression both forms exist, and the plain one is current.
+ */
+export declare function isListableTranscript(name: string, siblings: ReadonlySet<string>): boolean;
+export declare function readTranscriptTextSync(filePath: string): string;
+export declare function readTranscriptText(filePath: string): Promise<string>;
+/** The subset of a `FileHandle` transcript readers use. */
+export interface TranscriptHandle {
+    read(buffer: Buffer, offset: number, length: number, position: number): Promise<{
+        bytesRead: number;
+    }>;
+    stat(): Promise<{
+        size: number;
+        mtimeMs: number;
+    }>;
+    close(): Promise<void>;
+}
+export declare function openTranscript(filePath: string): Promise<TranscriptHandle>;

package/dist/lib/types.d.ts

@@ -1,5 +1,5 @@
 /** The agent CLIs Cogpit can drive. */
-export type AgentKind = "claude" | "codex" | "copilot";
+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
@@ -19,6 +19,19 @@ export interface SessionStatusInfo {
     pendingAgents?: number;
     /** Short descriptions of the pending background agents, oldest first */
     pendingAgentDescriptions?: string[];
+    /** Agents launched since the oldest one still running, in launch order (status awaiting_agents) */
+    backgroundAgents?: BackgroundAgent[];
+}
+/** A background agent launched by the session. */
+export interface BackgroundAgent {
+    /** What the agent was asked to do; empty when the launch carried no description */
+    description: string;
+    /** When the agent was launched (ISO), if the transcript records it */
+    startedAt?: string;
+    /** The launching tool call, which keys the agent's live progress summaries */
+    toolUseId?: string;
+    /** Finished, failed or stopped */
+    done: boolean;
 }
 /** A raw transcript record, before any agent-specific interpretation. */
 export type RawRecord = {
@@ -126,7 +139,10 @@ export interface UserMessage extends BaseMessage {
     thinkingMetadata?: {
         maxThinkingTokens: number;
     };
-    toolUseResult?: AgentToolUseResult;
+    toolUseResult?: Partial<AgentToolUseResult> & {
+        staged?: boolean;
+        bashEditDiff?: unknown;
+    };
     sourceToolAssistantUUID?: string;
 }
 export interface TokenUsage {
@@ -199,8 +215,17 @@ export interface AgentProgressData {
     };
     prompt: string;
     agentId: string;
+    /**
+     * Written by Cogpit's subagent watcher. The Agent call that launched this
+     * agent, when that differs from the record's `parentToolUseID` — a nested
+     * agent's records are filed under the main-thread call it descends from.
+     */
+    toolUseId?: string;
+    /** The subagent that launched this one (the CLI's `parent_task_id`). */
+    parentAgentId?: string;
+    subagentType?: 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) */
@@ -268,9 +293,14 @@ export interface SystemMessage extends BaseMessage {
     isMeta?: boolean;
     content?: string;
     compactMetadata?: CompactionMeta;
+    /** On a `local_command` record answering `/context`. */
+    contextUsage?: LocalCommandContextUsage;
+    /** On a `local_command` record answering `/usage`. */
+    usageReport?: LocalCommandUsageReport;
 }
 export interface CompactionMeta {
-    trigger: "auto" | "manual";
+    /** "idle" (Claude Code 2.1.290+) compacts while the session waits for the user. */
+    trigger: "auto" | "manual" | "idle";
     preTokens: number;
     postTokens?: number;
 }
@@ -346,6 +376,16 @@ 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;
@@ -354,6 +394,14 @@ export interface ToolCall {
     /** 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
@@ -372,6 +420,8 @@ export interface SubAgentMessage {
     agentId: string;
     /** The Task/Agent tool_use id this agent belongs to (streaming overlay key) */
     parentToolUseId?: string;
+    /** The subagent that launched this one; absent when the main thread did. */
+    parentAgentId?: string;
     agentName: string | null;
     subagentType: string | null;
     type: "user" | "assistant";
@@ -382,6 +432,8 @@ export interface SubAgentMessage {
     timestamp: string;
     tokenUsage: TokenUsage | null;
     model: string | null;
+    /** Reasoning effort the agent ran at, when its spawn recorded one. */
+    effort?: string;
     isBackground: boolean;
     /** Summary fields from toolUseResult (new format, v2.1.63+) */
     prompt?: string;
@@ -468,7 +520,103 @@ 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`. Newer CLIs
+ * record a structured twin of `/context` and `/usage` beside the text.
+ */
+ | {
+    kind: "local_command";
+    content: string;
+    timestamp?: string;
+    contextUsage?: LocalCommandContextUsage;
+    usageReport?: LocalCommandUsageReport;
 };
+/** One `/context` category row. Classify on `kind`, never on the display name. */
+export interface ContextUsageCategory {
+    name: string;
+    tokens: number;
+    /** `deferred` rows sit outside the window and stay out of the usage math. */
+    kind: "used" | "free" | "buffer" | "deferred";
+}
+/** The structured twin of a `/context` reply, as the CLI records it. */
+export interface LocalCommandContextUsage {
+    model: string;
+    total_tokens: number;
+    /** The window usage is measured against. */
+    raw_max_tokens: number;
+    percentage: number;
+    over_limit?: {
+        tokens_over: number;
+        kind: "hard_limit" | "compaction_window";
+    };
+    categories: ContextUsageCategory[];
+    mcp_tools?: {
+        name: string;
+        server_name: string;
+        tokens: number;
+    }[];
+    memory_files?: {
+        path: string;
+        type: string;
+        tokens: number;
+    }[];
+    agents?: {
+        agent_type: string;
+        source: string;
+        tokens: number;
+    }[];
+    skills?: {
+        name: string;
+        source: string;
+        plugin_name?: string;
+        tokens: number;
+    }[];
+}
+/** One plan meter of a `/usage` reply, rendered in the server's order and grading. */
+export interface UsageLimitRow {
+    /** The meter kind, e.g. `session`, `weekly_all`, `weekly_scoped`. */
+    kind: string;
+    group: string;
+    percent: number;
+    resets_at: string | null;
+    scope?: {
+        model?: {
+            display_name: string;
+        } | null;
+        surface?: {
+            display_name: string;
+        } | null;
+    } | null;
+    /** e.g. `normal`, `warning`, `critical`. */
+    severity: string;
+    is_active: boolean;
+}
+/** The structured twin of a `/usage` reply, as the CLI records it. */
+export interface LocalCommandUsageReport {
+    session: {
+        total_cost_usd: number;
+        total_api_duration_ms: number;
+        total_duration_ms: number;
+        total_lines_added: number;
+        total_lines_removed: number;
+    };
+    /** Null when the plan's usage could not be fetched (no plan, API key). */
+    rate_limits: {
+        limits: UsageLimitRow[] | null;
+        /** Amounts are in minor units of `currency`. */
+        extra_usage?: {
+            is_enabled: boolean;
+            monthly_limit: number | null;
+            used_credits: number | null;
+            utilization: number | null;
+            currency?: string | null;
+        } | null;
+    } | null;
+}
 export interface Turn {
     id: string;
     userMessage: UserContent | null;
@@ -553,6 +701,7 @@ export interface ParsedSession {
      * of truth — the session's dirName is (see `shared/session/agents.ts`).
      */
     agentKind?: AgentKind;
+    instanceId?: string;
 }
 export interface ArchivedToolCall {
     type: "Edit" | "Write";
@@ -564,6 +713,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[];
@@ -574,7 +725,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[];
@@ -583,8 +741,6 @@ export interface Branch {
 }
 export interface UndoState {
     sessionId: string;
-    currentTurnIndex: number;
-    totalTurns: number;
     branches: Branch[];
     activeBranchId: string | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cogpit-memory",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "CLI tool for Claude Code, Codex, and GitHub Copilot CLI session introspection",
   "license": "MIT",
   "repository": {