@lmctl-ai/lmctl 0.1.341 → 0.2.2

package/dist/providers/opencode.d.ts

@@ -0,0 +1,40 @@
+import type { SessionProvider, SessionSummary, SessionDetail } from "./types.js";
+type OpenCodeCompatibleProviderName = "opencode" | "lmplayer";
+interface OpenCodeProviderOptions {
+    dbPath?: string;
+    providerName?: OpenCodeCompatibleProviderName;
+    startCommand?: string;
+    /** Read-only connection `PRAGMA busy_timeout` in ms. Default 5000; lower
+     *  for tests that need to observe the retry-then-give-up path quickly. */
+    busyTimeoutMs?: number;
+}
+export declare class OpenCodeProvider implements SessionProvider {
+    readonly name: OpenCodeCompatibleProviderName;
+    private readonly startCommand;
+    private readonly dbPaths;
+    private readonly busyTimeoutMs;
+    constructor(opts?: OpenCodeProviderOptions);
+    private existingDbPaths;
+    private openDb;
+    discoverSessions(): Promise<SessionSummary[]>;
+    loadSession(sessionId: string): Promise<SessionDetail | null>;
+    private buildSessionDetail;
+    private extractText;
+    resolveSessionPath(sessionId: string): Promise<string | null>;
+    deleteSession(sessionId: string): Promise<boolean>;
+    private findSessionRow;
+}
+/**
+ * Bundle-identity probe (batch bundle mode): does the opencode session store
+ * hold a session with EXACTLY this id, and which directory does it belong
+ * to? opencode's `session/load` response does not echo the sessionId
+ * (verified on the wire, 2026-09-25), so the bundle driver verifies the
+ * resume target here instead. Read-only, with the same busy_timeout
+ * rationale as OpenCodeProvider.openDb.
+ */
+export declare function opencodeSessionStoreEntry(sessionId: string, opts?: {
+    dbPath?: string;
+}): {
+    directory: string;
+} | null;
+export {};

package/dist/providers/parsers/acp.d.ts

@@ -0,0 +1,47 @@
+export interface AcpResult {
+    result: string;
+    sessionId: string;
+    durationMs: number;
+    stopReason: string;
+    exitCode: number | null;
+    /** Human-readable strings when this turn's provider silently dropped a
+     * declared model=/effort= (task #232) -- e.g. a `session/set_config_option`
+     * rejection the turn proceeded past anyway. Omitted when nothing was
+     * dropped. */
+    warnings?: string[];
+}
+export interface AcpOutputProcessorResult {
+    result: string;
+    sessionId: string;
+    stopReason: string;
+}
+export interface AcpOutputProcessor {
+    setSessionId(sessionId: string): void;
+    beginTurn(): void;
+    completeTurn(promptResponse: Record<string, unknown>): AcpOutputProcessorResult;
+    /**
+     * Abandon the in-flight turn WITHOUT recording a result (bundle
+     * cancellation): stops collecting, discards the partial text, and leaves
+     * `gotResult` untouched so a late-arriving prompt response cannot be
+     * mistaken for a completed turn. The next `beginTurn()` starts clean.
+     */
+    cancelTurn(): void;
+    processMessage(message: Record<string, unknown>): boolean;
+    finalize(): AcpOutputProcessorResult | null;
+}
+export declare function isolateGeminiLatestAgentMessage(text: string): string;
+export declare function acpSessionIdFromResponse(response: Record<string, unknown>, fallback?: string): string;
+export declare function acpStopReasonFromResponse(response: Record<string, unknown>): string;
+export declare function createAcpOutputProcessor(opts?: {
+    tool?: string;
+    onDelta?: (text: string) => void;
+    /**
+     * Result-text isolation for providers that replay prior turns (gemini's
+     * latest-agent-message isolation). Supplied by the provider's ACP
+     * profile (transports/acp-profiles/); when absent, falls back to the
+     * historical `tool === "gemini"` keying so direct callers that pass
+     * only a tool name keep their behavior.
+     */
+    isolateResult?: (text: string) => string;
+}): AcpOutputProcessor;
+export declare function supportsAcp(tool: string): boolean;

package/dist/providers/parsers/codex-app-server.d.ts

@@ -0,0 +1,60 @@
+export type CodexPermissionMode = "plan" | "yolo";
+export declare function codexSandboxForPermissionMode(mode: CodexPermissionMode): string;
+export declare function buildCodexThreadStartParams(opts: {
+    cwd: string;
+    permissionMode?: CodexPermissionMode;
+    model?: string;
+}): Record<string, unknown>;
+export declare function buildCodexThreadResumeParams(opts: {
+    threadId: string;
+    permissionMode?: CodexPermissionMode;
+    model?: string;
+}): Record<string, unknown>;
+export interface CodexInitializePayload extends Record<string, unknown> {
+    clientInfo: {
+        name: string;
+        title: string;
+        version: string;
+    };
+    capabilities: {
+        experimentalApi: boolean;
+    };
+}
+export declare function buildInitializePayload(version?: string): CodexInitializePayload;
+export type AgentMessagePhase = "commentary" | "final_answer";
+export interface AgentMessageItemState {
+    phase: AgentMessagePhase | undefined;
+    buffer: string;
+}
+export interface CodexAgentAccumulatorState {
+    agentItems: Map<string, AgentMessageItemState>;
+    resultText: string;
+}
+export interface CodexItemMismatchInfo {
+    itemId: string;
+    threadId?: string;
+    turnId?: string;
+    expectedFromItemText: string;
+    gotFromBuffer: string;
+}
+export declare function createCodexAgentAccumulator(): CodexAgentAccumulatorState;
+export declare function processCodexAgentNotification(notification: Record<string, unknown>, state: CodexAgentAccumulatorState, onDelta?: (text: string) => void, onItemMismatch?: (info: CodexItemMismatchInfo) => void): boolean;
+export declare function flushCodexAgentAccumulator(state: CodexAgentAccumulatorState): void;
+export type CodexErrorDisposition = {
+    willRetry: true;
+} | {
+    willRetry: false;
+    turnError: Error;
+};
+export declare function classifyCodexErrorDisposition(notification: Record<string, unknown>): CodexErrorDisposition;
+export interface CodexTurnState {
+    pendingCodexError: Error | null;
+}
+export declare function createCodexTurnState(): CodexTurnState;
+export declare function recordCodexErrorNotification(notification: Record<string, unknown>, state: CodexTurnState): CodexErrorDisposition;
+export declare function resolveCodexTurnCompletion(notification: Record<string, unknown>, state: CodexTurnState): {
+    shouldReject: true;
+    turnError: Error;
+} | {
+    shouldReject: false;
+};

package/dist/providers/parsers/stream-json.d.ts

@@ -0,0 +1,57 @@
+export interface StreamJsonResult {
+    result: string;
+    sessionId: string;
+    durationMs: number;
+    numTurns: number;
+    exitCode: number | null;
+    /** Set only by the result-grace-timeout fallback in transports/stream-json.ts
+     * (BUG-claude-cli-stalls-after-end-turn.md): the model finished responding
+     * but the CLI never emitted its own closing `result` event. Same convention
+     * as TurnResult.warnings -- informational, does not change the outcome. */
+    warnings?: string[];
+}
+export interface StreamJsonProcessor {
+    processLine(line: string): void;
+    sawResult(): boolean;
+    finalize(): {
+        result: string;
+        sessionId: string;
+        durationMs: number;
+        numTurns: number;
+        /**
+         * True when the aggregated turn produced NO usable text and at least
+         * one `result` event reported `is_error: true` — see
+         * AggregatedResultEvents.isError below for why this must not be
+         * conflated with "the model genuinely returned nothing."
+         */
+        isError: boolean;
+        errorMessage?: string;
+    } | null;
+}
+export interface AggregatedResultEvents {
+    resultTexts: string[];
+    durationMs: number;
+    numTurns: number;
+    sessionId: string;
+    /**
+     * A `result` event can report `is_error: true` with NO `result` field at
+     * all (confirmed live, 2026-09-16, against a real `claude` CLI resuming
+     * an evicted/unresolvable session id: subtype "error_during_execution",
+     * no "result" key, the actual message only in an `errors: string[]`
+     * array). Without this flag that shape reads as a genuine empty
+     * response — "status: ok, content: (empty)" — indistinguishable from a
+     * model that legitimately said nothing, when the two need completely
+     * different remedies (a member refresh vs. investigating the prompt).
+     * `errorMessage` is the joined `errors` array, or a subtype-based
+     * fallback when `errors` is absent.
+     */
+    isError: boolean;
+    errorMessage?: string;
+}
+export declare function joinResultTurns(texts: string[]): string;
+export declare function createStreamJsonProcessor(opts?: {
+    onEvent?: (event: Record<string, unknown>) => void;
+    onText?: (text: string) => void;
+}): StreamJsonProcessor;
+export declare function aggregateResultEvents(events: Array<Record<string, unknown>>): AggregatedResultEvents;
+export declare function supportsStreamJson(tool: string): boolean;

package/dist/providers/passive-readers/agy.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Passive (read-only, bounded, certified) reader for Antigravity CLI (`agy`)
+ * sessions.
+ *
+ * `agy` lives under `~/.gemini/antigravity-cli` but is NOT Gemini CLI — the
+ * shared parent directory is a naming coincidence, and nothing in this reader is
+ * shared with a Gemini/ACP path.
+ *
+ * ## The two candidate sources, and why only one is used
+ *
+ * 1. `conversations/<session>.db` — SQLite. Tables: `trajectory_meta`, `steps`,
+ *    `gen_metadata`, `executor_metadata`, `parent_references`,
+ *    `trajectory_metadata_blob`, `battle_mode_infos`. **Every payload column is
+ *    an opaque protobuf blob** (`google3/third_party/jetski/cortex_pb`), not
+ *    JSON. One `gen_metadata` row == one model generation.
+ * 2. `brain/<session>/.system_generated/logs/transcript_full.jsonl` (and the
+ *    older compact `transcript.jsonl`) — readable JSONL.
+ *
+ * A census of every local transcript (141 files, 13 801 records) shows the JSONL
+ * carries ONLY: `step_index`, `source`, `type`, `status`, `created_at`,
+ * `content`, `tool_calls`, `thinking`, `exit_code`, `error`, `error_code`.
+ * There is **no token field, no model field and no per-response id anywhere in
+ * it**, so it cannot supply a `response_id` and cannot be the response source.
+ * It is therefore not read here at all; see the owner report for why joining it
+ * back to a generation is a separate, larger piece of work.
+ *
+ * ## What IS certified from the database
+ *
+ * Read with a schema-less protobuf wire walker (field numbers only — no
+ * generated stubs, nothing evaluated), cross-checked across 4 sessions and 2
+ * model families:
+ *
+ * - `gen_metadata.data` field 1 is the generation's chat-model metadata message.
+ * - Inside it, field 20 is a repeated `{1:key, 2:value}` string map. It contains
+ *   `request_id` (`<trajectory_id>-<n>`), which is unique per generation and is
+ *   used as `response_id`. It also contains `trajectory_id`, `last_step_index`,
+ *   `model_enum`, `last_execution_id` and `used_claude`/`used_non_gemini_model`
+ *   flags. Cross-checked: the top-level field-4 UUID is NOT per-generation (it
+ *   repeats across rows) and is deliberately not used as an id.
+ * - Field 19 is the response model name string (`gemini-3.8-flash`,
+ *   `gemini-pro-default` locally).
+ * - `last_step_index` indexes the `steps` table, whose `step_payload` field 5
+ *   sub-field 1 is a `google.protobuf.Timestamp`. That join gives a real
+ *   per-generation timestamp and is verified monotonic against generation order.
+ *
+ * ## What is NOT certified: tokens
+ *
+ * ## Tokens — RESOLVED via the installed client's own embedded schema
+ *
+ * Field 4 of the chat-model metadata was long treated as an unnamed counter
+ * block because no `.proto` was available and the standard `UsageMetadata`
+ * interpretation was directly ruled out (its assumed field 3 was smaller than
+ * its assumed field 2 — impossible for total-vs-candidates under that guess).
+ * That block is NOT a guess anymore: the installed `agy` binary is a Go build
+ * of `google.golang.org/protobuf`, which embeds each compiled `.proto` file's
+ * real `FileDescriptorProto` bytes for reflection. Locating the descriptor's
+ * self-declared name field (`third_party/jetski/cortex_pb/cortex.proto`,
+ * tag `0x0a` immediately preceding it — distinguishing it from the many
+ * `0x1a` dependency-reference copies of the same string elsewhere in the
+ * binary) and parsing the schema-less-walked byte range with the real
+ * `google.protobuf` library recovers the ACTUAL message: field 4 is
+ * `exa.codeium_common_pb.ModelUsageStats`, not a generic `UsageMetadata`.
+ * Its real fields (confirmed against 6,662 real local rows, independently
+ * re-derived and cross-checked by a second reviewer against the raw binary):
+ *   2 input_tokens, 3 output_tokens, 4 cache_write_tokens (never observed
+ *   non-null locally — genuinely rare/unused, not unread), 5 cache_read_tokens
+ *   (absent on some rows — no cache yet), 9 thinking_output_tokens,
+ *   10 response_output_tokens, 1 model (enum; the string alias is already
+ *   separately captured from field 19 above), 7/11/12 assorted opaque id
+ *   strings (message_id/response_id/provider_assigned_message_id — these,
+ *   not a "bot id"/"session id", are what the pre-schema walk was seeing).
+ * `response_output_tokens + thinking_output_tokens === output_tokens` EXACTLY
+ * on all 6,662/6,662 rows carrying both — proof (not inference) that
+ * `output_tokens` is the total and `thinking_output_tokens` is its reasoning
+ * subset. `cache_write_tokens`'s relationship (if any) to `input_uncached` is
+ * deliberately left unasserted — see `agyUsage`'s own doc comment below; a
+ * shared field name across providers is not evidence of shared semantics.
+ * `input_tokens` is used directly as `input_uncached`, never subtracted from:
+ * real rows show `input_tokens < cache_read_tokens` (e.g. 3280 vs 12145),
+ * which is only possible if the two are independent additive counts, not an
+ * inclusive total/subset pair — ruling out subtraction the same way the
+ * original block-level guess was ruled out (an impossible relation under the
+ * wrong model). Missing/invalid buckets stay NULL per-field (never a guessed
+ * 0) — `cache_write_tokens` in particular is null on every locally observed
+ * row precisely because it has genuinely never been populated here, not
+ * because it is unread.
+ *
+ * `files_read` / `files_written` / `external_io` are NULL (unknown), not `[]`:
+ * tool calls live in `steps.step_payload`, a different opaque message, and in
+ * the un-joinable transcript. NULL correctly forces `read_bytes`/`write_bytes`
+ * to NULL rather than presenting "no tools observed" as "no I/O occurred".
+ */
+import type { ReadLimits, Snapshot, Source, SourceState } from "../passive-session-reader.js";
+import { type TokenValues } from "./shared.js";
+export declare const AGY_PROVIDER = "agy";
+export declare const AGY_EXTRACTION_REVISION_TAG = "agy-tokens-v1";
+/**
+ * `steps.step_payload` → ISO timestamp, via field 5 (step metadata) sub-field 1
+ * (`google.protobuf.Timestamp` {1:seconds, 2:nanos}). Returns null when the
+ * shape is absent — never a fabricated or file-mtime-derived time.
+ */
+export declare function agyStepTimestamp(stepPayload: Buffer): string | null;
+/** One generation extracted from a `gen_metadata` row. */
+export interface AgyGeneration {
+    /** Native `request_id` — `<trajectory_id>-<n>`, unique per generation. */
+    requestId: string;
+    model: string | null;
+    /** `steps.idx` this generation ended on; the timestamp join key. */
+    lastStepIndex: number | null;
+    tokens: TokenValues;
+    thinkingOutputTokens: number | null;
+}
+/**
+ * Extract the certified facts from one `gen_metadata.data` blob. Returns null
+ * when the row carries no `request_id` — without a native id the generation
+ * cannot be addressed, and inventing one is forbidden.
+ */
+export declare function parseAgyGeneration(data: Buffer): AgyGeneration | null;
+export interface AgyPassiveReaderOptions {
+    /** Defaults to `$HOME/.gemini/antigravity-cli/conversations`. */
+    agyConversationsDir?: string;
+}
+export declare class AgyPassiveReader {
+    private readonly conversationsDir;
+    private readonly sqliteBusyTimeoutMs;
+    constructor(options?: AgyPassiveReaderOptions & {
+        sqliteBusyTimeoutMs?: number;
+    });
+    /**
+     * Enumerate up to `cap` `<conversationsDir>/<session>.db` files ordered by real
+     * path. A flat listing, so there is no traversal budget to exhaust; `truncated`
+     * is always false and is returned only to match the other readers' shape.
+     *
+     * `.db-wal` / `.db-shm` companions are excluded by the exact `.db` suffix test:
+     * they are not sources, and treating one as a session would mint a bogus id.
+     */
+    discover(limits: ReadLimits, cap: number, afterPath?: string | null): Promise<{
+        sources: Source[];
+        truncated: boolean;
+    }>;
+    /**
+     * Open the conversation database read-only, after proving the path is a real,
+     * non-symlink file inside the configured conversations directory AND that its
+     * basename is the claimed session id.
+     *
+     * Returns null (→ `unavailable`) rather than throwing when the file is not a
+     * usable SQLite database. A live session's `-wal`/`-shm` companions are read
+     * through by SQLite itself; a read-only open that cannot reach them fails
+     * closed here instead of returning a half-visible snapshot.
+     */
+    private open;
+    inspect(source: Source, limits: ReadLimits): Promise<SourceState>;
+    read(source: Source, revision: string, limits: ReadLimits): Promise<Snapshot>;
+}
+export declare function createAgyPassiveReader(options?: AgyPassiveReaderOptions): AgyPassiveReader;

package/dist/providers/passive-readers/copilot.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Passive (read-only, bounded, certified) reader for GitHub Copilot CLI sessions.
+ *
+ * ## What the native store actually is (real records, not assumed)
+ *
+ * Copilot writes one append-only event log per session:
+ *   `$HOME/.copilot/session-state/<uuid>/events.jsonl`  (+ a `workspace.yaml`).
+ * Each line is a JSON object `{ type, id, timestamp, data }`. The event TYPES seen
+ * locally: `session.start`, `session.model_change`, `session.info`,
+ * `system.message`, `user.message`, `assistant.turn_start`, `assistant.message`,
+ * `assistant.turn_end`, `tool.execution_start`, `tool.execution_complete`,
+ * `session.shutdown`.
+ *
+ * ## Token semantics — the copilot warning, verified on disk
+ *
+ * lmbi's directive: "Copilot has cumulative per-model shutdown totals and some
+ * per-message usage; NEVER distribute a session total over responses without
+ * evidence." Measured against real sessions:
+ *
+ *  - `assistant.message.outputTokens` IS a genuine PER-RESPONSE count.
+ *  - There is NO per-message input / cache / reasoning field anywhere on the wire.
+ *    Those counters exist only in `session.shutdown.modelMetrics` snapshots.
+ *
+ * CORRECTED (real evidence, not the original assumption): `session.shutdown`
+ * is NOT a proven session-wide cumulative. A session can carry MANY shutdown
+ * events (measured: up to 24 in one real session), and a shutdown's
+ * `requests.count`/`outputTokens` can be far smaller than the session's real
+ * total turn count/output sum (measured: a 201-turn session's last shutdown
+ * reported `requests.count=7`, `outputTokens=1984` against a real per-message
+ * sum of 82,375 — a ~97.6% undercount). So each shutdown snapshot's semantics
+ * are `"reported_scope_unknown"`, never asserted cumulative.
+ *
+ * Therefore each response record here carries `tokens.output` (real, per-message)
+ * and leaves `input_uncached` / `input_cached` / `input_cache_write` NULL — the
+ * shutdown snapshot's input is NEVER divided across responses. Every shutdown
+ * snapshot is surfaced SEPARATELY and RAW as `CopilotSessionUsage` (see
+ * `readCopilot`/`readWithUsage`) — never spread over the per-response rows,
+ * never emitted as a fabricated pseudo-response, and never renamed/normalized
+ * into this reader's own canonical token vocabulary (that's lmbi's own
+ * downstream decision to make, not this reader's).
+ *
+ * ## Identity, revision, attribution
+ *
+ *  - `response_id` = `assistant.message.data.messageId` (a real uuid); never
+ *    invented. Repeated events for one messageId sum their `outputTokens`.
+ *  - The revision is the sha256 of the exact `events.jsonl` bytes (extraction-
+ *    semantics-tagged, see EXTRACTION_SEMANTICS) with
+ *    a dev/ino/size/mtime recheck: a live append caught mid-write is `partial`,
+ *    never a clean revision, and a file not ending on a record boundary is refused.
+ *  - Prompt admission: `user.message.data.content` bytes attach to the FIRST
+ *    assistant response of the same `interactionId`; later responses in that
+ *    interaction are a real 0 (the prompt was already admitted). A response whose
+ *    interaction has no visible user admission (truncated history / system-driven
+ *    turn) gets an unknown coverage marker — "no input" cannot be certified.
+ *
+ * ## File / external-I/O (bx2), conservative by contract
+ *
+ * `create` ({path,file_text}) and `apply_patch` (<patch string>) are KNOWN writes
+ * with measurable added bytes. `view` ({path}) is a KNOWN read whose bytes are
+ * NULL — the result content is line-decorated with no clean chunk to count, so the
+ * honest size is unavailable (not guessed). `report_intent` is internal control
+ * (neither direction). Everything else opaque (`bash`/`read_bash`/`write_bash`/
+ * `stop_bash`/`list_bash`/`rg`/`glob`/`sql`/`fetch_*`/…) is unknown in BOTH
+ * directions, forcing that direction's aggregate NULL.
+ */
+import type { ReadLimits, Snapshot, Source, SourceState } from "../passive-session-reader.js";
+export declare const COPILOT_PROVIDER = "copilot";
+/**
+ * One event line of a copilot `events.jsonl`. Only the fields this reader reads.
+ */
+interface CopilotEvent {
+    type?: unknown;
+    id?: unknown;
+    timestamp?: unknown;
+    data?: unknown;
+}
+/**
+ * One native model's RAW `session.shutdown` counters. Field NAMES are copied
+ * directly from the native wire (`usage.inputTokens` -> `input_tokens`,
+ * `tokenDetails.input.tokenCount` -> `input_other_tokens`, etc.) — this reader
+ * does NOT compute, clamp, infer, or rename a "canonical uncached" figure here.
+ * Per lmbi's explicit instruction: raw naming preserves the native facts while
+ * this snapshot's own window/scope semantics remain unproven; normalizing
+ * (e.g. `input_uncached = input_tokens - cache_read_tokens`) is a downstream
+ * decision for the consumer, not this reader's to bake in.
+ */
+export interface CopilotModelUsage {
+    model: string;
+    requests_count: number | null;
+    /** `usage.inputTokens`, copied as-is. */
+    input_tokens: number | null;
+    /** `tokenDetails.input.tokenCount`, copied as-is — a real native "fresh"
+     * figure, narrower than `input_tokens`. NOT a canonical uncached total. */
+    input_other_tokens: number | null;
+    cache_read_tokens: number | null;
+    cache_write_tokens: number | null;
+    output_tokens: number | null;
+    reasoning_tokens: number | null;
+}
+/**
+ * One native `session.shutdown` EVENT, with every model in its `modelMetrics`
+ * grouped underneath (mirrors the native shape: one event, many models) —
+ * surfaced beside, never inside, the per-response rows.
+ *
+ * CORRECTED (real evidence, not assumption): a session can carry MULTIPLE
+ * `session.shutdown` events (measured: up to 24 in one real session on this box),
+ * and a shutdown's `requests.count`/`usage.outputTokens` can be far smaller than
+ * the session's real total turn count/output sum (measured: a 201-turn session's
+ * last shutdown reported `requests.count=7`, `outputTokens=1984` against a real
+ * per-message sum of 82,375 — a ~97.6% undercount). So this is NOT a proven
+ * session-wide cumulative; `semantics: "reported_scope_unknown"` reflects that
+ * honestly. Every shutdown event is retained (never "last wins", exact
+ * duplicate `native_id` replays coalesce to one), each with its own native
+ * event id/timestamp, so later analysis isn't precluded by discarding earlier
+ * snapshots.
+ */
+export interface CopilotSessionUsage {
+    /** The `session.shutdown` event's own top-level `id` (a real uuid). An event
+     * with no real id is never given a fabricated one — it is excluded from this
+     * array entirely (an explicit capture gap, not silently-fine metadata). */
+    native_id: string;
+    /** The `session.shutdown` event's own top-level `timestamp`, canonicalized. */
+    recorded_at: string | null;
+    kind: "copilot_session_shutdown";
+    semantics: "reported_scope_unknown";
+    models: CopilotModelUsage[];
+}
+export interface CopilotReadResult {
+    snapshot: Snapshot;
+    /** null when the session has no shutdown event with a real id yet (live/torn,
+     * or every shutdown event on this session lacked an id) — normal. */
+    sessionUsage: CopilotSessionUsage[] | null;
+}
+/**
+ * Extract the per-response snapshot AND the retained session-usage snapshots
+ * (scope-unknown, never asserted cumulative) from a parsed copilot event log.
+ * Pure and deterministic. A malformed event never throws; the
+ * whole snapshot is only refused (`partial`) when a response row count exceeds the
+ * budget — otherwise unrecognized shapes degrade to conservative NULL markers.
+ */
+export declare function readCopilot(events: CopilotEvent[], source: Source, revision: string, limits: ReadLimits): CopilotReadResult;
+export interface CopilotPassiveReaderOptions {
+    /** Defaults to `$HOME/.copilot/session-state`. */
+    copilotSessionStateDir?: string;
+}
+export declare class CopilotPassiveReader {
+    private readonly sessionStateDir;
+    constructor(options?: CopilotPassiveReaderOptions);
+    /**
+     * Enumerate up to `cap` sources ordered by real path. `afterKey` (a
+     * `source_id\0sessionid` sourceKey) continues a previous page. Discovery is a
+     * single-level scan of the session-state directory (no deep recursion), so
+     * there is no traversal budget to exhaust — `truncated` is always false.
+     */
+    discover(limits: ReadLimits, cap: number, afterKey?: string | null): Promise<{
+        sources: Source[];
+        truncated: boolean;
+    }>;
+    /**
+     * A source is ours only when its real path is `<dir>/events.jsonl` contained by
+     * the session-state directory AND `<dir>` basename is the claimed session id.
+     */
+    private matches;
+    inspect(source: Source, limits: ReadLimits): Promise<SourceState>;
+    /** Contract-shaped read: per-response Snapshot only. Use `readWithUsage` to also
+     * obtain the retained session-usage snapshots that must not be distributed
+     * over responses (see the module header — their scope is unproven, never
+     * asserted cumulative). */
+    read(source: Source, revision: string, limits: ReadLimits): Promise<Snapshot>;
+    readWithUsage(source: Source, revision: string, limits: ReadLimits): Promise<CopilotReadResult>;
+}
+export declare function createCopilotPassiveReader(options?: CopilotPassiveReaderOptions): CopilotPassiveReader;
+export {};

package/dist/providers/passive-readers/dsh.d.ts

@@ -0,0 +1,34 @@
+import type { ReadLimits, Snapshot, Source, SourceState } from "../passive-session-reader.js";
+export declare const DSH_PROVIDER = "dsh";
+interface DshRecord {
+    type?: unknown;
+    seq?: unknown;
+    time?: unknown;
+    data?: unknown;
+}
+export interface DshPassiveReaderOptions {
+    /** Defaults to `$DSH_HOME/sessions`, then `~/.dsh/sessions`. */
+    dshHome?: string;
+    maxDiscoveryTraversalVisits?: number;
+}
+export declare function readDsh(records: DshRecord[], source: Source, revision: string, limits: ReadLimits): Snapshot;
+export declare class DshPassiveReader {
+    private readonly sessionsDir;
+    private readonly maxDiscoveryTraversalVisits;
+    constructor(options?: DshPassiveReaderOptions);
+    /**
+     * Enumerate up to `cap` sources ordered by real path. `afterPath` continues a
+     * previous page. The caller owns cursor encoding and the cross-provider merge.
+     */
+    discover(limits: ReadLimits, cap: number, afterPath?: string | null): Promise<{
+        sources: Source[];
+        truncated: boolean;
+    }>;
+    /** Ours only when a real, non-symlink `session.jsonl.zstd` whose parent dir name
+     *  is the claimed session id. */
+    private matches;
+    inspect(source: Source, limits: ReadLimits): Promise<SourceState>;
+    read(source: Source, revision: string, limits: ReadLimits): Promise<Snapshot>;
+}
+export declare function createDshPassiveReader(options?: DshPassiveReaderOptions): DshPassiveReader;
+export {};

package/dist/providers/passive-readers/kimi.d.ts

@@ -0,0 +1,44 @@
+import type { ReadLimits, Snapshot, Source, SourceState } from "../passive-session-reader.js";
+export declare const KIMI_PROVIDER = "kimi";
+export interface KimiPassiveReaderOptions {
+    /** Defaults to `$KIMI_CODE_HOME`, then `~/.kimi-code`. */
+    kimiHome?: string;
+    maxDiscoveryTraversalVisits?: number;
+}
+interface WireLine {
+    type?: unknown;
+    agentId?: unknown;
+    event?: unknown;
+    time?: unknown;
+    model?: unknown;
+    modelAlias?: unknown;
+    turnStep?: unknown;
+    input?: unknown;
+    origin?: unknown;
+    promptId?: unknown;
+    protocol_version?: unknown;
+    usage?: unknown;
+}
+export declare function readKimi(lines: WireLine[], source: Source, revision: string, limits: ReadLimits): Snapshot;
+export declare class KimiPassiveReader {
+    private readonly home;
+    private readonly sessionsDir;
+    private readonly indexPath;
+    private readonly maxDiscoveryTraversalVisits;
+    constructor(options?: KimiPassiveReaderOptions);
+    /**
+     * Enumerate up to `cap` agent-wire sources ordered by real path. `afterPath`
+     * continues a previous page. Unions the directory walk with the append-only
+     * index so a missing/damaged index still recovers sessions.
+     */
+    discover(limits: ReadLimits, cap: number, afterPath?: string | null): Promise<{
+        sources: Source[];
+        truncated: boolean;
+    }>;
+    private unionIndex;
+    private matches;
+    inspect(source: Source, limits: ReadLimits): Promise<SourceState>;
+    read(source: Source, revision: string, limits: ReadLimits): Promise<Snapshot>;
+}
+export declare function createKimiPassiveReader(options?: KimiPassiveReaderOptions): KimiPassiveReader;
+export {};