cogpit-memory 0.4.0 → 0.4.1

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

@@ -78,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. */
@@ -214,6 +216,8 @@ export interface AgentCli {
     /** 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.

package/dist/lib/agents.d.ts

@@ -41,6 +41,18 @@ export interface AgentFormat {
     metadataFromLines(lines: readonly string[]): AgentSessionMetadata;
     /** Status derived from raw records. */
     status(records: readonly RawRecord[]): SessionStatusInfo;
+    /**
+     * 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.
+     */
+    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
@@ -75,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.
  *

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

@@ -32,6 +32,31 @@ interface CodexMetadata {
  * `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 {

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

@@ -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 = {
@@ -202,6 +215,15 @@ 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" | "PreModelSwitch" | "PostModelSwitch" | "PermissionDenied" | "TaskCreated" | "WorktreeCreate" | "CwdChanged" | "FileChanged" | "Elicitation" | "ElicitationResult" | "Notification";
 export interface HookProgressData {
@@ -271,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;
 }
@@ -393,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";
@@ -403,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;
@@ -494,13 +525,98 @@ export type TurnContentBlock = {
  * 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`.
+ * 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;

package/package.json

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