cogpit-memory 0.3.0 → 0.4.0

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.
@@ -85,6 +95,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 +118,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 +138,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 +213,7 @@ export interface AgentCli {
     readonly homeDirName: string;
     /** Environment variable overriding that directory, if the CLI has one. */
     readonly homeEnvVar: string | null;
+    readonly sdkHomeEnvVar?: string;
     /**
      * Path inside the home whose existence proves the CLI has been used. Empty
      * when the home directory itself is the evidence.
@@ -195,6 +225,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 +242,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 +362,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 +420,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,13 @@ 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.
+     * 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): {
+    brandBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null, branchedAt: number): {
         record: Record<string, unknown>;
         originalId: string;
     };
@@ -94,15 +95,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.
  *
- * `"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.
+ * 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 cutLineAfterUuid(format: AgentFormat, lines: readonly string[], turnUuid: string): number | "keep-all" | null;
+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 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 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/codex.d.ts

@@ -25,6 +25,13 @@ 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;
 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 +49,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/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
@@ -126,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 {
@@ -200,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) */
@@ -346,6 +349,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 +367,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
@@ -468,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;
@@ -553,6 +585,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 +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[];
@@ -574,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[];
@@ -583,8 +625,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.0",
   "description": "CLI tool for Claude Code, Codex, and GitHub Copilot CLI session introspection",
   "license": "MIT",
   "repository": {

package/skill/SKILL.md

@@ -153,7 +153,7 @@ 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. When the provider writes a separate sub-agent transcript, use Layer 3 for the full conversation
@@ -353,3 +353,11 @@ cogpit-memory index rebuild
 | 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.