@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.491

package/dist/providers/contracts.d.ts

@@ -10,6 +10,14 @@ import type { ProviderSummaryMetadata } from '../shared-types.js';
 import type { ChatMessageKind } from './chat-message-normalization.js';
 export type ReadChatTurnStatus = 'open' | 'waiting_approval' | 'complete' | 'error';
 export interface ReadChatResult {
+    /**
+     * Declared chat contract version. Absent or `'1.0'` → legacy v1 payload
+     * (current shape). `'2.0'` → v2 payload conforming to transcript-v2.ts
+     * (ReadChatResultV2). Validators in read-chat-contract.ts route on this
+     * field. A1 only adds the field; A2 will make v2 the daemon-internal
+     * canonical form and reject unrecognised versions at provider load time.
+     */
+    contractVersion?: import('./transcript-v2.js').ChatContractVersion;
     messages: ChatMessage[];
     status: AgentStatus;
     activeModal?: ModalInfo | null;
@@ -294,10 +302,89 @@ export interface ProviderMeshCoordinatorConfig {
         requiresRestart?: boolean;
         /** User-facing setup explanation for manual modes. */
         instructions?: string;
-        /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{workspace}}, {{serverName}}. */
+        /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{adhdevMcpArgs}}, {{workspace}}, {{serverName}}. */
         template?: string;
     };
+    /**
+     * How the coordinator system prompt reaches the launched CLI. Replaces the
+     * old hard-coded `if (cliType === 'claude-cli') push --append-system-prompt`
+     * branches in router.ts: a new CLI now ships its injection rule in its
+     * provider.v1.json, no daemon code change needed. Users can override the
+     * rendered prompt or the injection mechanism per-provider; if omitted, no
+     * system prompt is injected (safe default — won't crash spawn with a flag
+     * the CLI doesn't recognize).
+     */
+    systemPromptInjection?: MeshCoordinatorSystemPromptInjection;
+    /**
+     * How coordinator-launched worker sessions are isolated from coordinator-only
+     * MCP/tools/config. Provider-specific CLI quirks belong here, not in daemon
+     * launch code.
+     */
+    delegatedWorkerIsolation?: MeshCoordinatorDelegatedWorkerIsolation;
 }
+export interface MeshCoordinatorDelegatedWorkerIsolation {
+    /** Environment variables to unset for delegated worker sessions. */
+    env?: {
+        unset?: string[];
+    };
+    /** Spawn-argument rules applied before launching a delegated worker. */
+    args?: MeshCoordinatorDelegatedWorkerArgRule[];
+}
+export type MeshCoordinatorDelegatedWorkerArgRule = {
+    mode: 'empty_mcp_config';
+    /** CLI flag that points at an MCP config file, e.g. '--mcp-config'. */
+    flag: string;
+    /** Optional CLI flag that forces only the provided MCP config to be used. */
+    strictFlag?: string;
+} | {
+    mode: 'config_override';
+    /** CLI config flag, e.g. '-c' or '--config'. */
+    flag: string;
+    /** Config key to set for worker isolation. */
+    key: string;
+    /** Config value to set. */
+    value: string;
+    /** Optional broader key prefix used for duplicate detection. */
+    dedupeKey?: string;
+};
+/**
+ * Declarative description of how a CLI accepts a session-scoped system prompt.
+ *
+ * Modes:
+ *   - cli_arg          → push `flag` + prompt onto spawn args                (Claude)
+ *   - config_override  → push `flag` + a templated key=value config override (Codex)
+ *   - context_file     → write prompt into a workspace markdown the CLI
+ *                        auto-loads as project context                       (Gemini, Antigravity)
+ *   - env_var          → expose prompt to the spawned process as $name       (Hermes)
+ *
+ * The prompt text is templated with `{prompt}` (raw) or `{prompt_json}`
+ * (JSON-encoded for embedding inside config-override strings).
+ */
+export type MeshCoordinatorSystemPromptInjection = {
+    mode: 'cli_arg';
+    /** Spawn-args flag, e.g. '--append-system-prompt'. The prompt becomes the next argv. */
+    flag: string;
+} | {
+    mode: 'config_override';
+    /** Spawn-args flag, e.g. '-c'. Followed by `template` with placeholders rendered. */
+    flag: string;
+    /** Template using {prompt} or {prompt_json}, e.g. 'developer_instructions={prompt_json}'. */
+    template: string;
+} | {
+    mode: 'context_file';
+    /** Workspace-relative file path the CLI auto-loads, e.g. 'AGENTS.md' or 'GEMINI.md'. */
+    path: string;
+    /**
+     * Optional wrapper around the prompt. Use `{prompt}` placeholder. Existing
+     * wrapper-delimited blocks are replaced rather than duplicated, so re-launching
+     * a coordinator doesn't pile up copies. If omitted, the prompt is appended raw.
+     */
+    wrapper?: string;
+} | {
+    mode: 'env_var';
+    /** Env-var name, e.g. 'HERMES_EPHEMERAL_SYSTEM_PROMPT'. */
+    name: string;
+};
 export interface ProviderCompatibilityEntry {
     ideVersion: string;
     scriptDir: string;
@@ -378,6 +465,14 @@ export interface ProviderModule {
     extensionIdPattern_flags?: string;
     compatibility?: ProviderCompatibilityEntry[];
     defaultScriptDir?: string;
+    /**
+     * v1 declarative tui block (spinner/settledPrompt/modal/dispatchOrder/etc).
+     * When present, the daemon's CliScriptRunner builds canonical
+     * (input → verdict) functions from this and injects them into provider
+     * scripts as `sdk.declarativeDetectStatus` and `sdk.declarativeParseApproval`.
+     * v0 / verified-tier providers can omit this entirely.
+     */
+    tui?: Record<string, unknown>;
     /**
      * Scripts that can run at the IDE main-page level (not just inside the extension webview session frame).
      * Default: ['listModes', 'setMode', 'listModels', 'setModel'].
@@ -394,6 +489,63 @@ export interface ProviderModule {
         /** Auto-implement spawn config — controls how this provider is invoked for autonomous script generation */
         autoImpl?: ProviderAutoImplSpawnConfig;
     };
+    /**
+     * MAGI-KIND-PANEL (model axis): template for expanding an `initialModel` selection
+     * into launch args for a CLI provider. `{{model}}` is substituted with the model
+     * string; e.g. `['--model', '{{model}}']` for claude-cli → `--model opus`. Applied
+     * at session launch when `initialModel` is passed AND this provider is a plain CLI
+     * (ACP providers instead route the model through setConfigOption). A CLI provider
+     * with no template silently ignores `initialModel` at launch (best-effort; a model
+     * request never fails a launch). Absent → no launch-time model selection for CLI.
+     */
+    modelLaunchArgs?: string[];
+    /**
+     * BRAIN-ROUTING (model axis): suggested model values for this provider, surfaced
+     * as dropdown options in the new-session dialog (e.g. claude ['opus','sonnet',
+     * 'haiku']; codex ['gpt-5.5','gpt-5-codex']). Advisory only — the UI allows free
+     * text too, so the list going stale never blocks a model the provider accepts.
+     */
+    modelOptions?: string[];
+    /**
+     * BRAIN-ROUTING (thinking axis): template for expanding an `initialThinkingLevel`
+     * selection into launch args for a CLI provider, parallel to modelLaunchArgs.
+     * `{{level}}` is substituted with the provider-appropriate reasoning-effort value
+     * (already mapped from the standard low|medium|high level, see thinkingLevelMap).
+     * Examples: claude-cli `['--effort', '{{level}}']` → `--effort high`; codex-cli
+     * `['-c', 'model_reasoning_effort={{level}}']`. Applied at session launch when
+     * `initialThinkingLevel` is passed AND this provider is a plain CLI. A CLI provider
+     * with no template silently ignores the thinking level (best-effort; never fails a
+     * launch). ACP providers instead route thinking through setConfigOption('thought_level').
+     */
+    thinkingLaunchArgs?: string[];
+    /**
+     * BRAIN-ROUTING (thinking axis): optional per-provider mapping from the standard
+     * thinking levels (`low`|`medium`|`high`) to this provider's own reasoning-effort
+     * vocabulary, used to fill `{{level}}` in thinkingLaunchArgs. e.g. claude-cli might
+     * map `{ high: 'max' }`; codex-cli `{ high: 'xhigh' }`. A level absent from the map
+     * passes through unchanged (so `medium` → `medium` by default).
+     */
+    thinkingLevelMap?: Partial<Record<'low' | 'medium' | 'high', string>>;
+    /**
+     * BRAIN-ROUTING (thinking axis): the reasoning-effort values this provider actually
+     * accepts, surfaced as the thinking-level dropdown options in the new-session
+     * dialog (e.g. claude ['low','medium','high','max']; codex ['minimal','low',
+     * 'medium','high','xhigh']). Absent → the UI falls back to the standard
+     * low/medium/high. These are the provider's OWN vocabulary and are passed through
+     * verbatim as initialThinkingLevel (not remapped by thinkingLevelMap, which only
+     * translates the mesh's standard low/medium/high presets).
+     */
+    thinkingLevelOptions?: string[];
+    /**
+     * BRAIN-ROUTING (thinking axis, runtime-control providers): the `controls[].id`
+     * of a runtime reasoning-effort control to drive for the thinking level when the
+     * provider has no `thinkingLaunchArgs` (e.g. hermes-cli's `reasoning` select,
+     * which types `/reasoning <level>` into the PTY via its setScript). At launch,
+     * initialThinkingLevel (after thinkingLevelMap) is applied by invoking that
+     * control's setScript with `{ value: <level> }`. Ignored if the id doesn't match a
+     * control. Providers that use thinkingLaunchArgs don't need this.
+     */
+    thinkingControlId?: string;
     /** Delay before submitting typed CLI input (provider-specific TUI tuning) */
     sendDelayMs?: number;
     /** Submit key used after typing into CLI PTY (default: carriage return) */
@@ -429,8 +581,16 @@ export interface ProviderModule {
     /** History behavior config — controls message filtering and collapse during replay */
     historyBehavior?: ProviderHistoryBehavior;
     /**
-     * Canonical history sync config — for providers that maintain native history files.
-     * When set, daemon syncs from native format into ADHDev JSONL store on each tick.
+     * Native history config — for providers that maintain native history files.
+     * When set, daemon reads/lists provider-native transcripts directly. This is
+     * the canonical v1 field name; the legacy `canonicalHistory` field name is
+     * still accepted by the loader and aliased onto this field at load time.
+     */
+    nativeHistory?: NativeHistoryConfig;
+    /**
+     * @deprecated Legacy v0 alias for {@link ProviderModule.nativeHistory}.
+     * Loader populates this from `nativeHistory` so existing internal readers
+     * keep working during the transition. Remove after one release.
      */
     canonicalHistory?: ProviderCanonicalHistoryConfig;
     /**
@@ -561,20 +721,25 @@ export interface ProviderHistoryBehavior {
  * daemon-core. They let each provider own native transcript file discovery and
  * parsing while daemon-core only validates/pages the normalized result.
  */
-export interface ProviderCanonicalHistoryScriptsConfig {
+export interface NativeHistoryScriptsConfig {
     /** Reads one native session. Default: 'readNativeHistory'. */
     readSession?: string;
     /** Lists native sessions with summary metadata. Default: 'listNativeHistory'. */
     listSessions?: string;
 }
 /**
- * Canonical history sync config — for providers that maintain their own native history files.
+ * @deprecated Use {@link NativeHistoryScriptsConfig}. Retained as an alias for
+ * one release so external consumers that referenced the old name keep compiling.
+ */
+export type ProviderCanonicalHistoryScriptsConfig = NativeHistoryScriptsConfig;
+/**
+ * Native history config — for providers that maintain their own native history files.
  *
  * Preferred mode is provider-owned scripts via `scripts`. `format` is now an
  * opaque provider label retained for diagnostics/backward compatibility; daemon
  * live paths must not branch on provider-specific format values.
  */
-export interface ProviderCanonicalHistoryConfig {
+export interface NativeHistoryConfig {
     /** Opaque provider-owned history format label. */
     format?: string;
     /** Optional native history glob/template for diagnostics only. */
@@ -590,7 +755,23 @@ export interface ProviderCanonicalHistoryConfig {
      * Omitted mode defaults to 'native-source'.
      */
     mode?: 'native-source' | 'materialized-mirror' | 'disabled';
+    /**
+     * Chat transcript contract version this provider's read_chat output
+     * conforms to. See transcript-v2.ts for the v2 invariants. Absent or `'1.0'`
+     * → legacy v1 payload (current behaviour). `'2.0'` → strict v2 payload
+     * (stable providerUnitKey/bubbleId/sequence, strict enums, honest coverage).
+     *
+     * A1 only surfaces this field; validators in read-chat-contract.ts route
+     * on it. A2 makes v2 the daemon-internal canonical form and rejects
+     * unrecognised values at provider load time.
+     */
+    contractVersion?: import('./transcript-v2.js').ChatContractVersion;
 }
+/**
+ * @deprecated Use {@link NativeHistoryConfig}. Retained as an alias for one
+ * release so external consumers that referenced the old name keep compiling.
+ */
+export type ProviderCanonicalHistoryConfig = NativeHistoryConfig;
 /**
  * Auto-implement spawn config — controls how the provider is spawned for autonomous AI-driven
  * provider script implementation (dev-auto-implement.ts).
@@ -863,4 +1044,13 @@ export interface ProviderControlDef {
     order?: number;
     /** Hide this control when condition not met */
     hidden?: boolean;
+    /**
+     * FSM state ids in which this control should be visible (mirrors the spec's
+     * `control_bar[].visible_when_state`). When omitted the control is always
+     * visible. The daemon enforces this on click (FsmDriver.handleClickControl),
+     * so the web bar must mirror the same gating to avoid showing a button that
+     * the daemon would silently drop. Uses raw FSM state ids (e.g. 'idle',
+     * 'busy'), not the derived dashboard status.
+     */
+    visibleWhenState?: string[];
 }

package/dist/providers/external-sources.d.ts

@@ -0,0 +1,71 @@
+export interface ExternalSource {
+    /** Unique short identifier, e.g. "@vendor-x". User-supplied or derived from the URL. */
+    name: string;
+    /** Full git URL (https://, git@, …). */
+    url: string;
+    /** Branch / tag / commit-ish to track. Defaults to `main`. */
+    ref: string;
+    /** ISO timestamp when first registered. */
+    addedAt: string;
+}
+export interface ExternalSourcesFile {
+    /** Schema version — bump if shape changes. */
+    schema: 1;
+    sources: ExternalSource[];
+}
+/**
+ * Per-type active source selection. Only types reachable from more than
+ * one source need an entry — single-source types have no ambiguity.
+ *
+ * Shape: { active: { "<type>": "<source-name>" } }
+ */
+export interface ProvidersActiveFile {
+    schema: 1;
+    active: Record<string, string>;
+}
+export declare function externalRoot(): string;
+export declare function sourcesFilePath(): string;
+export declare function activeFilePath(): string;
+export declare function loadExternalSources(): ExternalSourcesFile;
+export declare function saveExternalSources(file: ExternalSourcesFile): void;
+export declare function loadProvidersActive(): ProvidersActiveFile;
+export declare function saveProvidersActive(file: ProvidersActiveFile): void;
+/**
+ * Derive a short identifier from a git URL when the user didn't supply one.
+ *   https://github.com/vendor/extra-providers.git → "@vendor-extra-providers"
+ *   git@github.com:vendor/extra-providers       → "@vendor-extra-providers"
+ *
+ * Idempotent; safe to call before validation since it produces a string
+ * regardless of input shape.
+ */
+export declare function deriveSourceName(url: string): string;
+/**
+ * Return the per-source category/type tree currently on disk under
+ * ~/.adhdev/external/<source>/. Used by the conflict detector and by
+ * list_provider_sources.
+ */
+export interface SourceInventoryEntry {
+    sourceName: string;
+    /** Map: category → list of provider types. */
+    providers: Record<string, string[]>;
+}
+export declare function inventoryExternalSources(): SourceInventoryEntry[];
+/**
+ * For a given category+type, list every source that currently exposes it.
+ * Returns source names in disk-walk order; callers can use the first one
+ * when no explicit active selection exists.
+ */
+export declare function sourcesProviding(category: string, type: string): string[];
+/**
+ * Resolve which source should be active for a given category+type.
+ *   - If exactly one source provides it → that source.
+ *   - If multiple sources provide it → the one named in providers-active.json
+ *     (when present) or null (ambiguous; loader should warn and pick
+ *     the first deterministically so daemon doesn't refuse to boot).
+ *   - If none → null.
+ */
+export declare function resolveActiveSource(category: string, type: string, activeFile?: ProvidersActiveFile): {
+    source: string | null;
+    ambiguous: boolean;
+    candidates: string[];
+};

package/dist/providers/manual-attendance.d.ts

@@ -0,0 +1,79 @@
+/**
+ * ManualAttendanceTracker — provider-agnostic "is a human driving this session
+ * right now" signal, used to suppress auto-approve while the user is taking
+ * manual control of a session from the dashboard.
+ *
+ * Why this exists
+ * ---------------
+ * When `autoApprove` is on, an approval modal is auto-dismissed within a few
+ * hundred ms of appearing. For a background mesh worker that is exactly the
+ * desired delegated behavior. But for a session the user is actively watching
+ * and operating (a base-node / foreground session), the auto-fire closes the
+ * modal before the human can pick a button — and likewise fights their use of
+ * the controlbar. The fix is to give the human a short quiet window: while they
+ * are attending the session by hand, auto-approve holds; once they go idle it
+ * resumes.
+ *
+ * The tracker holds only a timestamp. The *signal* — which commands count as
+ * "a human attending" — is decided by the caller (the command handler), and is
+ * the same set for every provider: foreground tab selection (select_session /
+ * open_panel), controlbar use (invoke_provider_script / set_mode / change_model
+ * / set_thought_level), manual approval (resolve_action) and manual terminal
+ * input (pty_input). Notably NOT send_chat, which is also how a coordinator
+ * delegates a task to a worker — counting it would wrongly suppress the
+ * worker's delegated auto-approve.
+ *
+ * Because a background worker never receives any of those attending commands,
+ * it is never "attended", so its delegated auto-approve is unaffected. The
+ * mechanism is therefore provider-common AND preserves worker auto-approve
+ * without any per-provider branching.
+ */
+/**
+ * How long after the last manual interaction auto-approve stays suppressed.
+ *
+ * Trade-off: long enough that after foregrounding a session's tab the user has
+ * a realistic chance to act on an incoming approval (the auto-approve settle
+ * window is only ~600ms, so a human cannot out-race it), yet short enough that
+ * a session left unattended — e.g. a worker tab the user briefly peeked at —
+ * resumes auto-approving within about a minute. Re-armed on every attending
+ * command, so a user who keeps interacting keeps the window fresh.
+ */
+export declare const AUTO_APPROVE_MANUAL_ATTENDANCE_SUPPRESS_MS = 60000;
+export declare class ManualAttendanceTracker {
+    private readonly suppressMs;
+    private lastInteractionAt;
+    constructor(suppressMs?: number);
+    /** Record that a human just drove this session by hand. */
+    note(now?: number): void;
+    /** True while a manual interaction is recent enough to suppress auto-approve. */
+    isAttended(now?: number): boolean;
+    /**
+     * Milliseconds remaining in the current suppression window, or 0 when not
+     * attended. Used to re-arm a re-check timer so auto-approve fires the moment
+     * the window lapses even if the PTY/agent has since gone silent.
+     */
+    remainingMs(now?: number): number;
+}
+/**
+ * The session-scoped commands that count as "a human is attending this session
+ * by hand". Shared so the command handler and any forward path agree on one
+ * definition. Deliberately excludes send_chat (coordinator task delegation) and
+ * pure read commands (read_chat / list_chats — passive polling, not driving).
+ */
+export declare const MANUAL_ATTENDANCE_COMMANDS: ReadonlySet<string>;
+/**
+ * The subset of {@link MANUAL_ATTENDANCE_COMMANDS} that are PASSIVE view-only
+ * actions — foregrounding a session's tab / opening its panel. They convey "I am
+ * looking at this session", not "I am driving it", and carry no user input.
+ *
+ * For a foreground (base-node) session these still attend: a user who
+ * foregrounds their own session should get the quiet window so an incoming
+ * approval stays visible for them to act on. But for a DELEGATED worker session
+ * a passive peek must NOT attend — a coordinator merely opening a worker's panel
+ * to watch progress would otherwise suppress that worker's delegated
+ * auto-approve for the whole window (secondary cause, #137). The per-instance
+ * hook decides: it drops a passive stamp only when the session is a delegated
+ * worker, so explicit input (controlbar / resolve_action / pty_input) still
+ * attends a worker and a foreground session is unaffected.
+ */
+export declare const MANUAL_ATTENDANCE_PASSIVE_VIEW_COMMANDS: ReadonlySet<string>;

package/dist/providers/native-history/antigravity-claim-registry.d.ts

@@ -0,0 +1,39 @@
+/** A claim older than this with no refresh is reclaimable (owner presumed dead). */
+export declare const CLAIM_STALE_MS: number;
+/**
+ * Derive the per-session owner token, keyed ONLY on the stable instanceId
+ * (== the session registry sessionId == the read path's targetSessionId). Both
+ * the dispatcher (read side) and the provider instance (claim/release side) pass
+ * this same id, so their tokens always agree and the claim isolation holds.
+ *
+ * Returns '' when no instanceId is available — the caller then skips claiming
+ * (the exclusion checks still run against existing claims). This is the SSOT
+ * rule: there is exactly ONE token form. The removed legacy fallback derived a
+ * `spawn:<workspace>:<sessionStartedAtMs>` token from the spawn timestamp when
+ * the instanceId was missing; because one session's spawn time is sampled
+ * independently at three sites (instance startedAt, adapter spawnedAtMs, registry
+ * spawnedAtMs) those never matched, so the SAME session's instance-side and
+ * read-side tokens silently diverged and the claim mutual-exclusion collapsed
+ * (the antigravity conversation crosswire). An empty token (skip-claim) is
+ * strictly safer than a token that disagrees with the same session's other
+ * token. workspace/sessionStartedAtMs are kept in the signature for call-site
+ * compatibility but no longer affect the token.
+ */
+export declare function antigravityOwnerToken(workspace: string, sessionStartedAtMs: number, instanceId?: string): string;
+/**
+ * Claim `uuid` for `owner`. Succeeds (and refreshes) when the conversation is
+ * unclaimed, already owned by this owner, or held by a stale (abandoned) owner.
+ * Fails when a DIFFERENT live owner holds it. Returns whether `owner` holds the
+ * claim after the call.
+ */
+export declare function claimAntigravityConversation(uuid: string, owner: string, now?: number): boolean;
+/** True when `uuid` is held by a live owner OTHER than `owner`. */
+export declare function isAntigravityConversationClaimedByOther(uuid: string, owner: string, now?: number): boolean;
+/** The live owner of `uuid`, or undefined when unclaimed or stale. */
+export declare function antigravityConversationOwner(uuid: string, now?: number): string | undefined;
+/** Release a single conversation, only if held by `owner` (or `owner` empty). */
+export declare function releaseAntigravityConversation(uuid: string, owner?: string): void;
+/** Release every conversation held by `owner` (called on session shutdown). */
+export declare function releaseAntigravityOwner(owner: string): void;
+/** Test-only: wipe all claims so each test starts from a clean registry. */
+export declare function __resetAntigravityClaimRegistry(): void;

package/dist/providers/native-history/antigravity-cli-transcript.d.ts

@@ -0,0 +1,137 @@
+/**
+ * antigravity-cli-transcript — Daemon-side built-in native history adapter for antigravity-cli.
+ *
+ * Antigravity CLI stores conversations in multiple complementary locations:
+ *
+ *   1. ~/.gemini/antigravity-cli/history.jsonl
+ *      Lightweight index of user prompts, one row per turn:
+ *        { conversationId: string, display: string, workspace: string, timestamp: number }
+ *
+ *   2. ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript*.jsonl
+ *      Per-session full transcript, one row per agent step:
+ *        { source: 'USER_EXPLICIT'|'MODEL', type: string, content: string, status: 'DONE'|..., created_at: number }
+ *
+ *   3. ~/.gemini/antigravity-cli/conversations/<uuid>.pb
+ *      Legacy protobuf binary — schema not publicly documented. Adapter extracts
+ *      printable UTF-8 text runs as best-effort content (no proto library needed).
+ *
+ *   4. ~/.gemini/antigravity-cli/conversations/<uuid>.db  ← current format
+ *      Per-session SQLite database. Recent antigravity migrated conversation
+ *      storage from .pb (+ brain/*.jsonl) to a per-session SQLite db. The
+ *      schema is a trajectory of `steps`, NOT a simple messages(role,content)
+ *      table:
+ *        steps(idx INTEGER PK, step_type INTEGER, status INTEGER,
+ *              step_payload BLOB [protobuf], ...)
+ *      Each `step_payload` is a protobuf message. Empirically (introspected
+ *      from real stores):
+ *        - step_type 14 → a USER turn. The prompt text is the largest
+ *          contiguous UTF-8 run inside the payload (field 19 subtree).
+ *        - step_type 15 → a MODEL/assistant turn. The assistant's final
+ *          natural-language answer lives at payload field 20 → field 1
+ *          (identical to field 8). Field 20 → field 3 is the internal
+ *          reasoning summary and is intentionally NOT surfaced.
+ *        - other step types are tool calls / ephemeral system context.
+ *      We read the blobs with a tiny dependency-free protobuf field walker
+ *      (no proto schema / codegen needed) and map the two message step types.
+ *      Because the daemon does NOT read this db, native history previously
+ *      returned 0 rows for these sessions and read_chat fell back to the
+ *      pty parser (which only echoes the user's own input) — assistant
+ *      answers appeared lost even though they were on disk.
+ *
+ *      Schema-drift resilience: the exact field path (20 → 1/8 for the answer,
+ *      19 → 2/3 for the prompt) is empirically verified against real stores, but
+ *      antigravity may move it in a future build. So when the known path yields
+ *      no text, instead of silently dropping the turn we fall back to a UTF-8
+ *      printable-run scan of the payload (recoverMessageText) that recovers the
+ *      answer/prompt even if the field number drifted — while explicitly
+ *      EXCLUDING the reasoning subtree (20 → 3) so internal reasoning is never
+ *      surfaced as the answer. Only when even that finds nothing beyond
+ *      reasoning/metadata is the step dropped, and a content-free DEBUG
+ *      breadcrumb is logged so a real drift is greppable rather than invisible.
+ *
+ * This adapter provides:
+ *   - Full coverage from a per-session .db (current format) — preferred.
+ *   - Full coverage when a brain transcript exists (legacy authoritative source).
+ *   - Partial coverage (user prompts only) from history.jsonl as fallback.
+ *   - Best-effort raw-string extraction from .pb files when no other source exists.
+ *
+ * watchPath (from provider.v1.json):
+ *   ~/.gemini/antigravity-cli/history.jsonl
+ *   ~/.gemini/antigravity-cli/brain/{uuid}/.system_generated/logs/transcript*.jsonl
+ *   ~/.gemini/antigravity-cli/conversations/{uuid}.pb
+ *   ~/.gemini/antigravity-cli/conversations/{uuid}.db
+ *
+ * OSS code (AGPL-3.0). Must not import from packages/ (proprietary).
+ */
+export type NativeHistoryRole = 'user' | 'assistant' | 'system';
+export type NativeHistoryKind = 'standard' | 'tool' | 'session_start';
+export interface NativeHistoryMessage {
+    ts: string;
+    receivedAt: number;
+    role: NativeHistoryRole;
+    content: string;
+    kind: NativeHistoryKind;
+    senderName?: string;
+    agent: 'antigravity-cli';
+    historySessionId: string;
+    workspace?: string;
+    /** Stable per-message identity (v2 contract). */
+    providerUnitKey?: string;
+}
+export interface NativeHistorySession {
+    messages: NativeHistoryMessage[];
+    providerSessionId: string;
+    source: 'provider-native';
+    sourcePath: string;
+    sourceMtimeMs: number;
+    /**
+     * 'full' — brain transcript was available and parsed.
+     * 'partial' — only history.jsonl user-prompts are available.
+     * 'best-effort' — .pb file bytes were used for raw text extraction.
+     */
+    nativeHistoryCoverage: 'full' | 'partial' | 'best-effort';
+    workspace?: string;
+    partialReason?: string;
+}
+export interface NativeHistorySessionMeta {
+    historySessionId: string;
+    sessionId: string;
+    sourcePath: string;
+    sourceMtimeMs: number;
+    messageCount: number;
+    firstMessageAt: number;
+    lastMessageAt: number;
+    sessionTitle?: string;
+    preview?: string;
+    workspace?: string;
+    agent: 'antigravity-cli';
+    source: 'provider-native';
+    nativeHistoryCoverage: 'full' | 'partial' | 'best-effort';
+    partialReason?: string;
+}
+/**
+ * Read a single Antigravity CLI session by its source file path.
+ *
+ * `sessionPath` is the absolute path to one of:
+ *   - A brain transcript JSONL: ~/.gemini/antigravity-cli/brain/<uuid>/.system_generated/logs/transcript*.jsonl
+ *   - The shared history.jsonl: ~/.gemini/antigravity-cli/history.jsonl
+ *   - A conversation SQLite db: ~/.gemini/antigravity-cli/conversations/<uuid>.db
+ *   - A conversation protobuf: ~/.gemini/antigravity-cli/conversations/<uuid>.pb
+ *
+ * The session UUID is inferred from the directory name (brain), filename (pb), or
+ * must be provided explicitly via `sessionId` for history.jsonl paths.
+ *
+ * Returns `null` when the file is missing, empty, or yields no parseable messages.
+ */
+export declare function readSession(sessionPath: string, sessionId?: string, workspace?: string): NativeHistorySession | null;
+/**
+ * List all Antigravity CLI sessions found across all watchPath locations.
+ *
+ * Priority:
+ *   1. Brain transcript sessions (full coverage) — preferred source.
+ *   2. History JSONL entries without a brain transcript (partial coverage).
+ *   3. .pb conversation files without any other source (best-effort).
+ *
+ * Returns summary metadata sorted by most recently updated first.
+ */
+export declare function listSessions(_watchPath: string): Promise<NativeHistorySessionMeta[]>;

package/dist/providers/native-history/claude-cli-transcript.d.ts

@@ -0,0 +1,70 @@
+/**
+ * claude-cli-transcript — Daemon-side built-in native history adapter for claude-cli.
+ *
+ * Reads Claude Code JSONL transcript files directly without shelling out to a JS override.
+ * The transcript format is one JSON object per line, where each line has:
+ *   - type: 'user' | 'assistant'
+ *   - message: { content: string | ContentBlock[] }
+ *   - timestamp: number (ms epoch) | string (ISO)
+ *   - sessionId?: string
+ *   - cwd?: string
+ *
+ * OSS code (AGPL-3.0). Must not import from packages/ (proprietary).
+ */
+export type NativeHistoryRole = 'user' | 'assistant' | 'system';
+export type NativeHistoryKind = 'standard' | 'tool' | 'session_start';
+export interface NativeHistoryMessage {
+    ts: string;
+    receivedAt: number;
+    role: NativeHistoryRole;
+    content: string;
+    kind: NativeHistoryKind;
+    senderName?: string;
+    agent: 'claude-cli';
+    historySessionId: string;
+    workspace?: string;
+    /** Stable per-message identity (v2 contract). */
+    providerUnitKey?: string;
+}
+export interface NativeHistorySession {
+    messages: NativeHistoryMessage[];
+    providerSessionId: string;
+    source: 'provider-native';
+    sourcePath: string;
+    sourceMtimeMs: number;
+    nativeHistoryCoverage: 'full';
+    workspace?: string;
+}
+export interface NativeHistorySessionMeta {
+    historySessionId: string;
+    sessionId: string;
+    sourcePath: string;
+    sourceMtimeMs: number;
+    messageCount: number;
+    firstMessageAt: number;
+    lastMessageAt: number;
+    sessionTitle?: string;
+    preview?: string;
+    workspace?: string;
+    agent: 'claude-cli';
+    source: 'provider-native';
+    nativeHistoryCoverage: 'full';
+}
+/**
+ * Read a single Claude Code session by its transcript file path.
+ *
+ * `sessionPath` is the absolute path to a `<uuid>.jsonl` file.
+ * Returns `null` when the file is missing, empty, or yields no parseable messages.
+ */
+export declare function readSession(sessionPath: string): NativeHistorySession | null;
+/**
+ * List all Claude Code sessions under the given glob-style watchPath base dir.
+ *
+ * `watchPath` is the pattern from provider.v1.json (`~/.claude/projects/**\/*.jsonl`).
+ * This implementation expands the home directory and scans `~/.claude/projects/`
+ * recursively, collecting all `.jsonl` files.
+ *
+ * Returns summary metadata for each session (no full message reads on this hot path;
+ * each file is opened only for lightweight scanning).
+ */
+export declare function listSessions(watchPath: string): Promise<NativeHistorySessionMeta[]>;