cogpit-memory 0.2.1 → 0.3.0

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

@@ -0,0 +1,387 @@
+/**
+ * Static facts about each agent CLI: how it names project directories and
+ * session files, and which product capabilities it supports.
+ *
+ * This module is deliberately parser-free. It imports only `./types`, so a
+ * caller that just needs a dirName codec — `server/sessionPaths.ts`, the
+ * cogpit-memory CLI, a renderer route guard — does not drag the 40 KB Codex and
+ * Copilot transcript parsers along with it. The parsing side of an agent lives
+ * behind `AgentFormat` in `./agents`.
+ *
+ * Everything here is data or pure string math. Anything needing `node:fs` is an
+ * `AgentStore` and lives in `server/agents/`, because `shared/` is bundled into
+ * the renderer and must stay free of node builtins.
+ */
+import { type AgentKind } from "./types";
+export type { AgentKind } from "./types";
+export { AGENT_KINDS } from "./types";
+/**
+ * What a given agent can actually do. Every flag names a *capability*, never an
+ * agent — `capabilities.worktrees`, never `kind === "claude"`. That is the whole
+ * 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. */
+    readonly worktrees: boolean;
+    /** MCP server configuration can be passed at spawn time. */
+    readonly mcp: boolean;
+    /** `/slash` command discovery and expansion. */
+    readonly slashCommands: boolean;
+    /** The Workflow tool writes run state Cogpit can read back. */
+    readonly workflows: boolean;
+    /** Agent teams (multi-session teammates). */
+    readonly agentTeams: boolean;
+    /** Sub-agent transcripts are written as separate readable files. */
+    readonly subagentTranscripts: boolean;
+    /**
+     * Whether a sub-agent can itself own sub-agents that are addressed under its
+     * own session id. When false, every descendant is filed under the root
+     * session, so listing the root's children already yields the whole tree.
+     */
+    readonly nestedSubagents: boolean;
+    /** Sessions can be published as read-only shares. */
+    readonly sharing: boolean;
+    /**
+     * How a long-running goal is tracked: read back from the transcript and set
+     * with a slash command, through the CLI's own goal API, or not at all.
+     */
+    readonly goals: "transcript" | "thread-api" | false;
+    /** Transcript-rewinding undo is available. */
+    readonly undo: boolean;
+    /** Undo history is persisted, so redo and branches work. */
+    readonly redo: boolean;
+    /** The CLI exposes its own rewind RPC (used instead of replaying edits). */
+    readonly nativeRewind: boolean;
+    /** The CLI checkpoints files itself, so undo can restore them natively. */
+    readonly fileCheckpoints: boolean;
+    /**
+     * A reasoning-effort ladder applies by default. When false, effort levels
+     * exist only for models whose live catalog entry advertises them.
+     */
+    readonly reasoningEffort: boolean;
+    /** A faster/priority service tier can be requested. */
+    readonly fastTier: 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.
+     */
+    readonly imageInput: boolean;
+    /** A message can be delivered into an already-running turn. */
+    readonly midTurnSteering: boolean;
+    /** The whole session can be shut down from the composer. */
+    readonly stopSession: boolean;
+    /** Maximum-effort orchestration mode, pinned to the top effort level. */
+    readonly ultracode: boolean;
+    /** Remaining context can be computed from the transcript. */
+    readonly contextWindow: boolean;
+    /**
+     * A session may be driven by a process Cogpit did not start, in which case it
+     * is view-only.
+     */
+    readonly externalProcesses: boolean;
+    /** Several logins are managed by a switcher tool Cogpit can drive. */
+    readonly accountSwitching: boolean;
+    /** The transcript records model substitutions the composer surfaces. */
+    readonly modelFallbackNotices: boolean;
+    /** Whether an unattended "auto" permission mode can be offered. */
+    readonly autoPermissionMode: "never" | "per-model" | "always";
+    /** Whether composer settings take effect immediately or on the next turn. */
+    readonly settingsApply: "live" | "next-turn";
+    /**
+     * Where turn liveness is read for listings and notifications: the transcript
+     * tail, or the runtime's own turn state for a CLI whose transcript lags it.
+     */
+    readonly turnLiveness: "transcript" | "runtime";
+    /** Partial assistant output is published on the stream bus while a turn runs. */
+    readonly tokenStreaming: boolean;
+    /** Branching is a fork RPC on the CLI rather than a copied and cut transcript. */
+    readonly nativeFork: boolean;
+    /** A title can be given to a session when it is created. */
+    readonly namedSessions: boolean;
+}
+export interface AgentDirNameCodec {
+    /**
+     * True when `decode(encode(cwd))` can differ from `cwd`, so a caller holding
+     * the real dirName must pass it along rather than recompute it.
+     */
+    readonly lossy: boolean;
+    /** True when `dirName` belongs to this agent. */
+    owns(dirName: string | null | undefined): 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. */
+    decode(dirName: string): string | null;
+}
+export interface AgentSessionFileCodec {
+    /** Path of a session's transcript, relative to this agent's sessions root. */
+    name(sessionId: string, at?: Date): string;
+    /** Inverse of `name`: recover the session id, or null if unrecognised. */
+    sessionId(fileName: string): string | null;
+    /**
+     * The identifier a URL carries for this transcript. Agents whose on-disk name
+     * is rebuildable from the id shorten to it; the rest keep the relative path,
+     * because a date-nested rollout cannot be recovered from its uuid alone.
+     */
+    urlId(fileName: string): string;
+    /** Exact inverse of `urlId`. */
+    fileNameFromUrlId(urlId: string): string;
+}
+export interface AgentResumeCodec {
+    /** Copy-pasteable shell command that reopens the session in a terminal. */
+    command(sessionId: string, cwd?: string): string;
+    /** argv handed to `binName` when Cogpit spawns the resume itself. */
+    args(sessionId: string): readonly string[];
+}
+export interface AgentHomebrewFormula {
+    readonly name: string;
+    /** Casks ship a prebuilt app and need `brew upgrade --cask`. */
+    readonly cask: boolean;
+}
+export interface AgentSelfUpdate {
+    /** argv appended to `binName` to make the CLI update itself. */
+    readonly args: readonly string[];
+    /**
+     * Whether a resolved binary path belongs to a self-managing install.
+     *
+     * Paths arrive lowercased and forward-slashed, because the caller normalises
+     * every candidate before any predicate runs — these are written against that
+     * form and comparing a raw Windows path here would never match.
+     */
+    matches(normalizedPath: string): boolean;
+}
+/** How a CLI shows up in the machine's process listing. */
+export interface AgentProcessMatch {
+    /**
+     * `"command"`: any command line naming the binary is this CLI, launchers and
+     * helpers included. `"executable"`: only a process whose executable is the
+     * binary, for a name too common to match loosely.
+     */
+    readonly by: "command" | "executable";
+    /** The session a resumed process was started with, read from its command line. */
+    sessionIdFromCommand(command: string): string | null;
+}
+/**
+ * Everything Cogpit needs to find, version and upgrade one CLI, plus where that
+ * CLI keeps its own state. Cogpit drives whatever the user installed, so all of
+ * this is discovery, never assumption — the one exception being a CLI that
+ * Cogpit's own dependencies happen to ship a copy of.
+ */
+export interface AgentCli {
+    /** npm package publishing this CLI. */
+    readonly packageName: string;
+    readonly homebrew: AgentHomebrewFormula | null;
+    readonly wingetId: string | null;
+    /** argv that makes the CLI print its version. */
+    readonly versionArgs: readonly string[];
+    readonly selfUpdate: AgentSelfUpdate | null;
+    /**
+     * Whether an SDK in Cogpit's dependency tree vendors its own copy of this
+     * CLI. That is the only case where there is more than one binary to choose
+     * from, so it is what enables the executable picker.
+     */
+    readonly bundledBySdk: boolean;
+    /** Directory holding the CLI's own state, relative to the user's home. */
+    readonly homeDirName: string;
+    /** Environment variable overriding that directory, if the CLI has one. */
+    readonly homeEnvVar: string | null;
+    /**
+     * Path inside the home whose existence proves the CLI has been used. Empty
+     * when the home directory itself is the evidence.
+     */
+    readonly installMarker: string;
+    /**
+     * Whether Cogpit can locate this home on its own. Claude's is a user-chosen
+     * path stored in Cogpit's own configuration, so it cannot be discovered when
+     * that configuration is missing; the rest sit at a fixed, env-overridable
+     * location and can be found on a first run.
+     */
+    readonly homeIsDiscoverable: boolean;
+    readonly process: AgentProcessMatch;
+}
+export type AgentConfigScope = "global" | "project";
+export interface AgentConfigFile {
+    /**
+     * `"scope"` places the file beside the config root — in the user's home
+     * directory or at the project root — and `"root"` places it inside it.
+     */
+    readonly in: "scope" | "root";
+    /** Path relative to whichever of those two directories `in` names. */
+    readonly path: string;
+    /** Scopes at which this file exists. */
+    readonly scopes: readonly AgentConfigScope[];
+    /** Tree label; defaults to `path`. */
+    readonly label?: string;
+}
+/**
+ * Where a CLI reads its instructions, settings and extensions from. Drives the
+ * config browser, so an agent missing a row here is an agent the user cannot
+ * configure through Cogpit at all.
+ */
+export interface AgentConfigLayout {
+    /** Directory the CLI reads config from, under the home or a project root. */
+    readonly rootDirName: string;
+    readonly instructions: readonly AgentConfigFile[];
+    readonly settings: readonly AgentConfigFile[];
+    /** Directories inside the config root; null when the CLI has no such concept. */
+    readonly skillsDir: string | null;
+    readonly agentsDir: string | null;
+    /** Codex calls these "prompts". */
+    readonly commandsDir: string | null;
+    /** Global-only theme directory, if the CLI has one. */
+    readonly themesDir: string | null;
+    /** Global-only installed-plugin tree, if the CLI has one. */
+    readonly pluginsDir: string | null;
+    /**
+     * Marker directory holding `plugin.json` inside a plugin the CLI loads from a
+     * path, and so the shape Cogpit writes its own local plugin in. Null for a
+     * CLI that has no plugins and reads `skillsDir` alone.
+     */
+    readonly pluginManifestDir: string | null;
+}
+export interface AgentContextWindow {
+    /** Window assumed for a model with no entry in `limits`. */
+    readonly defaultLimit: number;
+    /** Model-id substrings with a different window; first match wins. */
+    readonly limits: readonly {
+        readonly match: string;
+        readonly limit: number;
+    }[];
+    /**
+     * Headroom the CLI reserves before it auto-compacts. Zero for a CLI that
+     * decides its own compaction point, so applying another's reserve would
+     * report a session as nearly full while it still has room.
+     */
+    readonly compactBuffer: number;
+    /** Model-id marker requesting an extended window, if the CLI has one. */
+    readonly extendedContext: {
+        readonly marker: string;
+        readonly limit: number;
+    } | null;
+}
+/**
+ * Cogpit's access picker, as it crosses the wire. Every field is optional
+ * because it arrives from a client that may be older than the server; each
+ * agent maps it onto its own policy vocabulary.
+ */
+export interface PermissionsConfig {
+    mode?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+}
+/**
+ * argv Cogpit appends to `binName` when it launches a turn. Each function
+ * returns an empty array when the setting was not chosen, so call sites spread
+ * them unconditionally.
+ */
+export interface AgentLaunchArgs {
+    /** Translate the access picker into this CLI's own policy flags. */
+    permissions(permissions?: PermissionsConfig): string[];
+    model(model?: string): string[];
+    effort(effort?: string): string[];
+    fastTier(enabled?: boolean): string[];
+}
+/**
+ * The wire values a "fast mode" request carries.
+ *
+ * An agent Cogpit drives two ways can want two different spellings of the same
+ * intent, and they are recorded separately rather than merged, because only the
+ * CLI itself can say which is right.
+ */
+export interface AgentServiceTier {
+    /** `serviceTier` sent over a persistent RPC/app-server connection. */
+    readonly appServerValue: string;
+    /** `service_tier` written into the CLI's own config when it is spawned. */
+    readonly cliConfigValue: string;
+}
+export interface EffortOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface ServiceTierOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+/** One row of a model picker, and one entry of the `/api/models` catalog. */
+export interface ModelOption {
+    value: string;
+    label: string;
+    description?: string;
+    /** Canonical wire model id this option resolves to (`""` is the default). */
+    resolvedModel?: string;
+    isDefault?: boolean;
+    defaultReasoningEffort?: string;
+    supportedReasoningEfforts?: EffortOption[];
+    inputModalities?: string[];
+    supportsPersonality?: boolean;
+    serviceTiers?: ServiceTierOption[];
+    availabilityMessage?: string;
+    supportsEffort?: boolean;
+    supportsAdaptiveThinking?: boolean;
+    supportsAutoMode?: boolean;
+}
+export interface AgentDescriptor {
+    readonly kind: AgentKind;
+    /** Human-facing product name. */
+    readonly displayName: string;
+    /** Executable name, as invoked on PATH. */
+    readonly binName: string;
+    readonly dirName: AgentDirNameCodec;
+    readonly sessionFile: AgentSessionFileCodec;
+    /**
+     * 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
+     * and nothing short of a full read can produce them, which is what makes a
+     * partial head read a false economy for that agent.
+     */
+    readonly metadataFromHead: boolean;
+    readonly resume: AgentResumeCodec;
+    readonly launchArgs: AgentLaunchArgs;
+    /** Null for an agent with no faster tier, or one that asks for it some other way. */
+    readonly serviceTier: AgentServiceTier | null;
+    readonly cli: AgentCli;
+    readonly config: AgentConfigLayout;
+    readonly contextWindow: AgentContextWindow;
+    readonly capabilities: AgentCapabilities;
+}
+/** True when a process listing's command line belongs to this CLI. */
+export declare function matchesAgentProcess(descriptor: AgentDescriptor, command: string): boolean;
+/** The `Win32_Process` name filter that lists this CLI, for `Get-CimInstance`. */
+export declare function windowsProcessNameFilter(descriptor: AgentDescriptor): string;
+export declare const CODEX_DIR_PREFIX = "codex__";
+export declare const COPILOT_DIR_PREFIX = "copilot__";
+export declare function descriptorFor(kind: AgentKind): AgentDescriptor;
+export declare function allDescriptors(): readonly AgentDescriptor[];
+/**
+ * The one agent with a given property, for code that only makes sense while
+ * exactly one has it — the configured home, the slash-command palette. Fails
+ * loudly on zero or several rather than silently picking the first, so a
+ * capability a second agent gains is noticed instead of misrouted.
+ */
+export declare function soleDescriptorWhere(predicate: (descriptor: AgentDescriptor) => boolean, what: string): AgentDescriptor;
+/**
+ * Resolve the agent that owns a project dirName.
+ *
+ * This is Cogpit's **source of truth** for "which agent is this session?". It
+ * beats content sniffing because it is known before a single byte is read, it
+ * is what the URL carries, and it is what every write path (spawn, undo,
+ * branch) already keys on. `ParsedSession.agentKind` is the parser's own
+ * finding and is used to cross-check, never to override.
+ *
+ * Falls back to Claude for a null/unknown dirName, matching the historical
+ * behaviour every caller depends on.
+ */
+export declare function descriptorForDirName(dirName: string | null | undefined): AgentDescriptor;
+/** Convenience wrapper: the agent kind owning a project dirName. */
+export declare function agentKindForDirName(dirName: string | null | undefined): AgentKind;
+/**
+ * Encode a project path for a given agent. An agent whose encoding is lossy
+ * cannot recover its canonical dirName from the path, so a caller that already
+ * holds it passes it as `knownDirName` rather than let it be re-derived.
+ */
+export declare function projectDirNameFor(kind: AgentKind, cwd: string, knownDirName?: string): string;
+/** True when `fileName` looks like a session transcript for `kind`. */
+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;

package/dist/lib/agents.d.ts

@@ -0,0 +1,112 @@
+import { type CodexExecCall } from "./codex-exec";
+import { type AgentKind } from "./types";
+import type { ParseSessionOptions, ParsedSession, RawRecord, SessionStatusInfo } from "./types";
+import type { AgentDescriptor } from "./agent-descriptors";
+export type { AgentCapabilities, AgentDescriptor, AgentDirNameCodec, AgentKind, AgentSessionFileCodec, } from "./agent-descriptors";
+export { AGENT_KINDS, CODEX_DIR_PREFIX, COPILOT_DIR_PREFIX, agentKindForDirName, allDescriptors, descriptorFor, descriptorForDirName, isSessionUuid, projectDirNameFor, sessionIdFromFileName, } from "./agent-descriptors";
+/**
+ * Header metadata every format can report from the first lines of a transcript.
+ *
+ * Individual formats return supersets of this (turn counts, first/last user
+ * message, sub-agent parentage); the registry narrows them to the fields all
+ * three agree on.
+ */
+export interface AgentSessionMetadata {
+    sessionId: string;
+    version: string;
+    gitBranch: string;
+    cwd: string;
+    slug: string;
+    name: string;
+    model: string;
+    branchedFrom?: {
+        sessionId: string;
+        turnIndex?: number | null;
+    };
+}
+export interface AgentFormat {
+    readonly kind: AgentKind;
+    readonly descriptor: AgentDescriptor;
+    /** True when this JSONL text was produced by this CLI. */
+    detectsText(jsonlText: string): boolean;
+    /** True when these already-parsed raw records came from this CLI. */
+    detectsRecords(records: readonly {
+        type?: unknown;
+    }[]): boolean;
+    /** Full parse into the shared session model. */
+    parse(jsonlText: string, options?: ParseSessionOptions): ParsedSession;
+    /** Incremental append of newly written lines. */
+    append(existing: ParsedSession, newJsonlText: string): ParsedSession;
+    /** Cheap header metadata read from already-split transcript lines. */
+    metadataFromLines(lines: readonly string[]): AgentSessionMetadata;
+    /** 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.
+     */
+    brandBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null): {
+        record: Record<string, unknown>;
+        originalId: string;
+    };
+    /**
+     * Indexes of the records at which a turn starts, in file order.
+     *
+     * The **one** implementation of turn-boundary detection. Undo cuts a
+     * transcript by computing `keepLines` on the client and having the server
+     * verify and apply it; if the two sides scanned for boundaries separately
+     * and ever disagreed by one line, the result would be a silently corrupted
+     * transcript rather than an error. They cannot disagree while they both call
+     * this.
+     */
+    turnBoundaries(records: readonly Record<string, unknown>[]): number[];
+}
+/**
+ * The kind that claims any transcript nothing else did. Detection order makes
+ * it the last entry of `AGENT_KINDS`; callers that need to know whether
+ * detection actually matched compare against this.
+ */
+export declare const TERMINAL_AGENT_KIND: AgentKind;
+export declare function formatFor(kind: AgentKind): AgentFormat;
+export declare function formatForText(jsonlText: string): AgentFormat;
+export declare function formatForRecords(records: readonly {
+    type?: unknown;
+}[]): AgentFormat;
+/**
+ * Boundary indexes for raw JSONL lines rather than parsed records.
+ *
+ * A malformed line stands in as an empty record so indexes keep matching the
+ * caller's line array — every consumer here slices that array by the returned
+ * index, so dropping a line would shift the cut.
+ */
+export declare function turnBoundaryLines(format: AgentFormat, lines: readonly string[]): number[];
+/**
+ * The line to cut at to keep exactly `keepTurnCount` turns — i.e. where the
+ * turn after the last kept one begins. `lines.length` when the transcript has
+ * no more turns than that, meaning nothing is removed.
+ */
+export declare function cutLineForTurnCount(format: AgentFormat, lines: readonly string[], keepTurnCount: number): number;
+/**
+ * The line to cut at to keep everything through turn `turnIndex`, or null when
+ * that turn is the last one and there is nothing to remove.
+ */
+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.
+ *
+ * `"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.
+ */
+export declare function cutLineAfterUuid(format: AgentFormat, lines: readonly string[], turnUuid: 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
+ * a single `exec` call, so readers that care about what ran — rather than how
+ * it is presented — expand a call here instead of learning that grammar.
+ */
+export declare function expandToolScript<T extends CodexExecCall>(call: T): CodexExecCall[];

package/dist/lib/claude.d.ts

@@ -0,0 +1,49 @@
+import type { ParseSessionOptions, ParsedSession, RawRecord, SessionStatusInfo } from "./types";
+/**
+ * Unconditionally true: this is the terminal arm of transcript detection.
+ *
+ * Detection ORDER is the contract. `AGENT_KINDS` ends with this format, so a
+ * transcript only reaches it after every positively-discriminated format has
+ * declined it. Spelling the fallback out as "not the others" instead would make
+ * each new CLI edit this function and re-introduce the mutual references the
+ * registry exists to remove.
+ */
+export declare function isClaudeSessionText(): boolean;
+export interface ClaudeMetadata {
+    sessionId: string;
+    version: string;
+    gitBranch: string;
+    cwd: string;
+    slug: string;
+    name: string;
+    model: string;
+    branchedFrom?: {
+        sessionId: string;
+        turnIndex?: number | null;
+    };
+}
+/** Cheap header metadata read from already-split transcript lines. */
+export declare function extractClaudeMetadataFromLines(lines: readonly string[]): ClaudeMetadata;
+export declare function parseClaudeSession(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 appendClaudeSession(existing: ParsedSession, newJsonlText: string): ParsedSession;
+/** Derive status by walking backward through Claude Code's JSONL records. */
+export declare function deriveClaudeSessionStatus(rawMessages: readonly RawRecord[]): SessionStatusInfo;
+/** A branch keeps the header record, renamed and pointed back at its origin. */
+export declare function brandClaudeBranch(firstRecord: Record<string, unknown>, sessionId: string, turnIndex: number | null): {
+    record: Record<string, unknown>;
+    originalId: string;
+};
+/**
+ * Indexes of the records that start a turn.
+ *
+ * A user record that carries *any* `tool_result` block is a continuation of the
+ * turn in flight, not a new one — the CLI writes tool results back as user
+ * records. This predicate is the one the client and the server both cut on, so
+ * an off-by-one here writes a corrupted transcript rather than failing loudly.
+ */
+export declare function claudeTurnBoundaries(records: readonly Record<string, unknown>[]): number[];

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

@@ -7,6 +7,10 @@ export interface CodexExecInvocation {
     argumentSource: string;
     startIndex: number;
 }
+export interface CodexExecCall {
+    name: string;
+    input: Record<string, unknown>;
+}
 export declare function readJsStringLiteral(source: string, startIndex: number): JsStringLiteral | null;
 /**
  * Extract actual tool invocations from a Codex code-mode `exec` script.
@@ -25,3 +29,11 @@ export declare function extractJsStringPropertyValues(source: string, property:
 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;
+/** Codex code mode wraps a whole orchestration script in one `exec` tool call. */
+export declare function isCodexExecCall<T extends CodexExecCall>(call: T): call is T & {
+    input: {
+        raw: string;
+    };
+};
+/** Decode literal call inputs for presentation; expressions remain available as source. */
+export declare function getCodexExecCalls(input: Record<string, unknown>): CodexExecCall[];

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

@@ -1,14 +1,35 @@
+import type { ImageBlock } from "./types";
 /**
  * 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;
+/**
+ * Read the exit code Codex's shell wrapper prints into its own output. Nothing
+ * else in the text decides failure: a command that prints source files, HTML or
+ * logs carries words like "error" that say nothing about how it ended.
+ */
+export declare function hasFailedExit(output: string | null): boolean;
+/**
+ * Names Codex gives the tool that asks the user a question, both the blocking
+ * form and the `_async` one that returns a receipt and keeps working.
+ */
+export declare function isCodexQuestionTool(name: string): boolean;
+/**
+ * Normalize Codex request_user_input input to AskUserQuestion format.
+ *
+ * Codex writes a question as `{ title, options: string[] | null }`, where the
+ * options are bare labels rather than the `{ label, description }` objects the
+ * question card renders.
+ */
+export declare function normalizeQuestions(input: Record<string, unknown>): Record<string, unknown>;
 /** 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): {
+export interface CodexToolOutput {
     text: string;
     isError: boolean;
-};
+    images?: ImageBlock[];
+}
+/** Read function, custom-tool, and MCP output without losing structured images. */
+export declare function parseCustomToolOutput(output: unknown): CodexToolOutput;

package/dist/lib/codex.d.ts

@@ -1,4 +1,4 @@
-import type { ParseSessionOptions, ParsedSession } from "./types";
+import type { ParseSessionOptions, ParsedSession, RawRecord, SessionStatusInfo } from "./types";
 export { extractApplyPatchInputs, findFailedNestedPatchCallIds, parseApplyPatch, parseCodexToolPatches, } from "./codex-patches";
 export { parseCustomToolOutput } from "./codex-tool-normalization";
 interface CodexMetadata {
@@ -26,5 +26,33 @@ interface CodexMetadata {
     agentPath: string;
 }
 export declare function isCodexSessionText(jsonlText: string): boolean;
+/** True when already-parsed raw records came from this CLI. */
+export declare function isCodexRawRecords(records: readonly {
+    type?: unknown;
+}[]): boolean;
 export declare function extractCodexMetadataFromLines(lines: string[]): CodexMetadata;
 export declare function parseCodexSession(jsonlText: string, options?: ParseSessionOptions): ParsedSession;
+/**
+ * Incrementally extend a parsed session with newly written lines.
+ *
+ * Rollout records carry cross-turn state (patch folding, collaboration agent
+ * lifecycles, token roll-ups), so the whole transcript is re-parsed rather than
+ * only its tail.
+ */
+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): {
+    record: Record<string, unknown>;
+    originalId: string;
+};
+/**
+ * Indexes at which a turn starts.
+ *
+ * A rollout writes the `turn_context` record that configures a turn *before*
+ * the user message that opens it, so the boundary reported is that context
+ * record: cutting at the user message alone would strand a context line
+ * belonging to a turn that no longer exists.
+ */
+export declare function codexTurnBoundaries(records: readonly Record<string, unknown>[]): number[];