@adhdev/daemon-core 0.9.82-rc.34 → 0.9.82-rc.340

package/dist/providers/spec/fsm-loader.d.ts

@@ -0,0 +1,14 @@
+import { type CliSpecV4 } from './fsm-types.js';
+export interface FsmLoadOk {
+    ok: true;
+    spec: CliSpecV4;
+    sourcePath: string;
+}
+export interface FsmLoadErr {
+    ok: false;
+    errors: string[];
+    sourcePath: string;
+}
+export declare function loadFsmSpec(sourcePath: string): FsmLoadOk | FsmLoadErr;
+/** Pure validator — usable from a "validate before save" API in the panel. */
+export declare function validateFsmSpec(raw: unknown): string[];

package/dist/providers/spec/fsm-types.d.ts

@@ -0,0 +1,144 @@
+import type { RegexCondition, ChangedCondition, Control, NotificationRule, DelegateTrigger, NativeHistoryConfig, SectionDef, ExtractTitle, ExtractButtons } from './types.js';
+/** True once `ms` have elapsed since the current state was entered. */
+export interface ElapsedCondition {
+    elapsed_ms: number;
+}
+/** True once the region `cursor_above` lines above the cursor has been
+ *  unchanged for `ms`. A stability gate — the inverse of a busy signal. */
+export interface StableCondition {
+    stable_ms: number;
+    /** Lines above the cursor that must be stable. Default: whole screen. */
+    cursor_above?: number;
+}
+export interface FsmAllCondition {
+    all: FsmCondition[];
+}
+export interface FsmAnyCondition {
+    any: FsmCondition[];
+}
+/** Negation — true when the inner condition is false. Lets a transition say
+ *  "go busy unless the completion marker is present", etc. */
+export interface FsmNotCondition {
+    not: FsmCondition;
+}
+export type FsmCondition = RegexCondition | ChangedCondition | ElapsedCondition | StableCondition | FsmAllCondition | FsmAnyCondition | FsmNotCondition;
+export interface FsmState {
+    id: string;
+    label: string;
+    /** Exactly one state must be `initial: true` — the state at spawn. */
+    initial?: boolean;
+    /** Modal states (approval/picker) expose modal buttons in the UI and are
+     *  treated as "interesting" — the dashboard surfaces them distinctly. */
+    modal?: boolean;
+    /** Status this state maps to for the dashboard/cli-adapter status field.
+     *  One of: idle | generating | approval. Defaults: modal→approval,
+     *  initial→idle, id==='busy'→generating, else idle. Explicit wins. */
+    status?: 'idle' | 'generating' | 'approval';
+    /** Optional extraction run whenever this state is the committed state —
+     *  used by modal states to surface a title + buttons. */
+    extract?: {
+        title?: ExtractTitle;
+        buttons?: ExtractButtons;
+    };
+}
+export interface FsmTransition {
+    /** Source state id, or list of source ids, or "*" for any state. */
+    from: string | string[];
+    /** Destination state id. */
+    to: string;
+    /** Guard condition. Omitted → always eligible (only gated by `from` +
+     *  min_hold_ms). Evaluated against the current screen + clock. */
+    when?: FsmCondition;
+    /** Minimum time the machine must have been in `from` before this edge can
+     *  fire. Replaces busy_hold_ms / idle_hold_ms (per-edge, not global). */
+    min_hold_ms?: number;
+    /** Higher priority transitions are evaluated first. Default 0. Ties broken
+     *  by declaration order. */
+    priority?: number;
+    /** Human label for the debugger. */
+    label?: string;
+}
+/**
+ * Declarative "trust this folder before spawn" config. Some agent CLIs gate the
+ * first run in a new folder behind an interactive trust prompt and persist the
+ * answer as a string array in a JSON settings file. Declaring this lets the
+ * engine add the workspace path to that array before spawn so the prompt never
+ * appears — the robust alternative to detecting and auto-clicking the modal.
+ * CLIs without such a gate omit this field and the engine does nothing.
+ */
+export interface PreLaunchTrust {
+    /** Path to the CLI's JSON settings file. A leading `~` expands to $HOME. */
+    settings_path: string;
+    /** Key of the string-array of trusted folder paths within that file. */
+    key: string;
+}
+export interface CliSpecV4 {
+    $schema: 'adhdev:cli/spec@4';
+    id: string;
+    name: string;
+    binary: string;
+    spawn_args?: string[];
+    env?: Record<string, string>;
+    cli_version_range?: string;
+    /**
+     * Optional raw byte sequences written to the PTY once, shortly after spawn,
+     * to prime a TUI that gates its input handling on a terminal event the
+     * daemon would otherwise never emit. The canonical case is a focus-event
+     * TUI (Ink `useStdin`/`useFocus`, e.g. antigravity's `agy`) that enables
+     * focus reporting (`CSI ?1004h`) and treats its input box as unfocused —
+     * silently dropping the first programmatic write — until it receives a
+     * focus-in event (`ESC [ I`). Declaring `[""]` here wakes the input
+     * stream on spawn so the first delegated message lands without a manual
+     * keystroke. CLIs that do not focus-gate input simply omit this field; the
+     * engine writes nothing extra for them, so it stays CLI-agnostic.
+     */
+    send_on_spawn?: string[];
+    /** Delay (ms) after spawn before writing `send_on_spawn`. Default 250. */
+    send_on_spawn_delay_ms?: number;
+    /**
+     * Opt-in stall recovery for focus-gated TUIs. The same CLIs that need
+     * `send_on_spawn` (focus-event TUIs like antigravity's `agy`) also stop
+     * rendering / flushing output the moment they believe they have lost focus
+     * MID-TURN — the screen freezes and only repaints once the user presses a
+     * key, which the daemon never does on its own. When this field is set and
+     * the machine is in a `generating`-status state whose screen has not changed
+     * for `refocus_when_stalled_ms`, the engine re-injects the `send_on_spawn`
+     * prime (the focus-in event) once to wake the render loop, then waits for the
+     * screen to change or for the stall window to lapse again before re-priming
+     * (a cooldown that prevents a tight re-prime loop). Requires `send_on_spawn`
+     * to carry the wake sequence; with no `send_on_spawn` there is nothing to
+     * re-inject and the engine does nothing. Omitted by every non-focus-gated
+     * CLI spec, so the engine stays CLI-agnostic.
+     */
+    refocus_when_stalled_ms?: number;
+    /**
+     * Optional pre-spawn folder-trust step. When present, the engine adds the
+     * launch workspace path to the declared trusted-folders array before
+     * spawning, so a CLI that gates first run on a "trust this folder?" prompt
+     * (e.g. antigravity's `agy`) starts trusted and never blocks. Omitted for
+     * CLIs without such a gate. See pre-launch-trust.ts.
+     */
+    pre_launch_trust?: PreLaunchTrust;
+    send_message: {
+        submit_key: string;
+        delay_ms_before_submit?: number;
+        delay_ms_per_char?: number;
+    };
+    sections: Record<string, SectionDef>;
+    states: FsmState[];
+    transitions: FsmTransition[];
+    control_bar?: Control[];
+    notifications?: NotificationRule[];
+    delegate?: DelegateTrigger[];
+    native_history?: NativeHistoryConfig;
+    requiresFinalAssistantBeforeIdle?: boolean;
+}
+export declare function isV4Spec(raw: unknown): raw is CliSpecV4;
+export declare function initialState(spec: CliSpecV4): FsmState;
+export declare function stateById(spec: CliSpecV4, id: string): FsmState | undefined;
+/** Outgoing transitions from `stateId`, highest priority first, declaration
+ *  order as tiebreak. Includes wildcard ("*") and list-membership sources. */
+export declare function outgoingTransitions(spec: CliSpecV4, stateId: string): FsmTransition[];
+/** Map a state to the dashboard status string, applying the documented
+ *  defaults when `status` is not explicit. */
+export declare function statusForState(state: FsmState): 'idle' | 'generating' | 'approval';

package/dist/providers/spec/native-history-executor.d.ts

@@ -0,0 +1,41 @@
+import type { NativeHistoryConfig } from './types.js';
+export interface NativeHistoryInput {
+    agentType?: string;
+    sessionId?: string;
+    providerSessionId?: string;
+    historySessionId?: string;
+    workspace?: string;
+    /** Daemon-side wall clock at the moment the session was registered.
+     *  Native-history file lookups use this as the lower bound: any file
+     *  whose mtime is before the current session started can't be from
+     *  this session, so it's excluded from newest-recent matching. The
+     *  caller (chat-history pipeline) populates this from the session
+     *  registry; specs/executor never need to know how it's sourced. */
+    sessionStartedAtMs?: number;
+    /** Env overrides the daemon set on the spawned CLI. The mesh
+     *  coordinator points hermes at a per-coordinator HERMES_HOME so
+     *  the hermes process writes its state.db into a tmp directory
+     *  instead of ~/.hermes. expandPath consults this map before
+     *  process.env so the native-history reader follows the spawned
+     *  child's view of HERMES_HOME / similar overrides; without it
+     *  the reader would always look at ~/.hermes and miss every
+     *  coordinator-session transcript. */
+    envOverrides?: Record<string, string>;
+    args?: Record<string, unknown>;
+}
+export interface NativeHistoryMessage {
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    receivedAt: number;
+    kind?: string;
+    workspace?: string;
+}
+export interface NativeHistoryResult {
+    messages: NativeHistoryMessage[];
+    providerSessionId?: string;
+    sourcePath: string;
+    sourceMtimeMs: number;
+    nativeHistoryCoverage?: 'full' | 'partial' | 'best-effort';
+    workspace?: string;
+}
+export declare function executeNativeHistory(cfg: NativeHistoryConfig, input: NativeHistoryInput): NativeHistoryResult | null;

package/dist/providers/spec/pre-launch-trust.d.ts

@@ -0,0 +1,16 @@
+import type { PreLaunchTrust } from './fsm-types.js';
+/**
+ * Idempotently add `workingDir` (realpath) to the trusted-folders array named
+ * by `trust.key` inside the JSON settings file at `trust.settings_path`.
+ *
+ * - Creates the file (and parent dir) if missing.
+ * - Preserves all other settings; only the trust array is touched.
+ * - No-ops if the path is already present.
+ * - Best-effort: any failure is logged and swallowed. A failed pre-trust must
+ *   not block the launch — the worst case is the old behavior (the FSM still
+ *   detects the trust modal as an approval state), not a crash.
+ *
+ * Returns the path that was added (realpath), or null if nothing changed /
+ * an error occurred — purely so callers/tests can assert the effect.
+ */
+export declare function applyPreLaunchTrust(trust: PreLaunchTrust, workingDir: string): string | null;

package/dist/providers/spec/route.d.ts

@@ -0,0 +1,4 @@
+import type { CliProviderModule } from '../../cli-adapters/provider-cli-adapter.js';
+import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import type { CliAdapter } from '../../cli-adapter-types.js';
+export declare function createCliAdapter(provider: CliProviderModule, workingDir: string, cliArgs: string[], extraEnv: Record<string, string>, transportFactory?: PtyTransportFactory): CliAdapter;

package/dist/providers/spec/types.d.ts

@@ -0,0 +1,180 @@
+export type Size = number | string;
+export interface SectionPattern {
+    section?: string;
+    pattern: string;
+    flags?: string;
+}
+/** Inline wait_for shape used by open_picker control actions. */
+export interface WaitForCondition {
+    section?: string;
+    regex?: string;
+    flags?: string;
+}
+export type ControlAction = {
+    type: 'send_keys';
+    keys: string;
+} | {
+    type: 'open_picker';
+    trigger_keys: string;
+    wait_for: WaitForCondition;
+    extract_choices: SectionPattern;
+    submit_key: string;
+} | {
+    type: 'attach_image';
+    method: 'tempfile_then_keys';
+    keys_template: string;
+};
+export interface Control {
+    id: string;
+    label: string;
+    visible_when_state?: string[];
+    action: ControlAction;
+}
+export interface NotificationRule {
+    id: string;
+    when_state: string;
+    title: string;
+    body?: string;
+}
+export interface DelegateTrigger {
+    id: string;
+    when_state: string;
+    after_duration_ms?: number;
+    task_template: string;
+}
+export interface NativeHistoryConfig {
+    reader?: 'claude-cli' | 'codex-cli' | 'antigravity-cli' | 'hermes-cli';
+    source?: NativeHistorySource;
+    override_path?: string;
+}
+export type NativeHistorySource = NativeHistoryJsonlSource | NativeHistorySqliteSource;
+export interface NativeHistoryJsonlSource {
+    kind: 'jsonl';
+    path: string;
+    file_pattern?: string;
+    recent_window_ms?: number;
+    session_id_from?: 'filename_uuid' | 'first_record';
+    session_id_path?: string;
+    message_filter?: {
+        where: string;
+    };
+    message_map: NativeHistoryMessageMap;
+}
+export interface NativeHistorySqliteSource {
+    kind: 'sqlite';
+    path: string;
+    session_query: string;
+    message_query: string;
+    message_map: NativeHistoryMessageMap;
+}
+export interface NativeHistoryMessageMap {
+    role: string;
+    content: string;
+    content_strip?: string[];
+    content_unwrap?: string[];
+    timestamp_ms?: string;
+    kind?: string;
+    /**
+     * Declarative tool-bubble extraction. Without it the executor only emits
+     * the text-bearing parts of each record, so a turn that is purely a tool
+     * call or tool result (no prose) is dropped — the restored transcript
+     * loses every tool interaction. When present, the executor walks each
+     * record's content blocks and emits an extra `kind:'tool'` message for
+     * any block whose `$.type` matches a tool shape.
+     *
+     * Defaults target the Anthropic-style content-block shape that claude-cli
+     * and codex-cli persist (blocks of `{ type: 'tool_use' | 'tool_result',
+     * name, input, content }`); a provider with a different on-disk shape
+     * overrides the field paths. Set `tools: {}` to opt in with the defaults.
+     */
+    tools?: NativeHistoryToolMap;
+}
+/**
+ * How to surface tool-call / tool-result blocks as `kind:'tool'` bubbles.
+ * Every field is optional — the defaults read the Anthropic block shape.
+ * Paths are jsonpath-lite evaluated against a single content block (the
+ * element of `$.message.content[]`), not the whole record.
+ */
+export interface NativeHistoryToolMap {
+    /** Path to a block's discriminator. Default `$.type`. */
+    block_type?: string;
+    /** Block-type values that mean "a tool was invoked". Default
+     *  `['tool_use', 'function_call', 'custom_tool_call']`. */
+    call_types?: string[];
+    /** Block-type values that mean "a tool returned". Default
+     *  `['tool_result', 'function_call_output', 'custom_tool_call_output']`. */
+    result_types?: string[];
+    /** Path to the tool name on a call block. Default `$.name`. */
+    call_name?: string;
+    /** Path to the tool arguments on a call block. Default `$.input`. */
+    call_args?: string;
+    /** Path to the result payload on a result block. Default `$.content`. */
+    result_content?: string;
+}
+export interface AnchorContext {
+    prev?: string;
+    next?: string;
+    prev_flags?: string;
+    next_flags?: string;
+}
+export interface SectionDef {
+    from_top?: Size;
+    from_bottom?: Size;
+    until?: string;
+    /**
+     * Anchor regex(es). A single string anchors on the first/last matching line
+     * (per `anchor_last`). An array is an OR-set: every candidate line is one
+     * that matches ANY entry; with `anchor_last` the LAST such line across all
+     * patterns wins, otherwise the FIRST. This lets one section capture two
+     * different shapes — e.g. a box-divider modal AND a divider-less modal whose
+     * only stable landmark is the question line above its numbered choices.
+     */
+    anchor?: string | string[];
+    anchor_flags?: string;
+    anchor_last?: boolean;
+    /**
+     * Context guard(s) for the anchor. A single object applies to every anchor
+     * pattern. An array is matched positionally against an `anchor` array (entry
+     * i guards anchor i); a positional `undefined`/null entry means "no guard"
+     * for that anchor. A scalar `anchor` ignores array form beyond index 0.
+     */
+    anchor_context?: AnchorContext | (AnchorContext | null)[];
+    lines?: number;
+    until_regex?: string;
+    until_regex_flags?: string;
+}
+export interface RegexCondition {
+    section?: string;
+    matches: string;
+    flags?: string;
+    cursor_row_min?: number;
+    cursor_row_max?: number;
+    cursor_col_min?: number;
+    cursor_col_max?: number;
+}
+export interface ChangedCondition {
+    cursor_above: number;
+    changed: boolean;
+    stable_ms?: number;
+}
+export interface AllCondition {
+    all: Condition[];
+}
+export interface AnyCondition {
+    any: Condition[];
+}
+export type Condition = RegexCondition | ChangedCondition | AllCondition | AnyCondition;
+export interface ExtractTitle {
+    section?: string;
+    regex?: string;
+    flags?: string;
+    first_line?: true;
+}
+export interface ExtractButtons {
+    section?: string;
+    pattern: string;
+    flags?: string;
+    key_for_index: string;
+    min_count?: number;
+    continuation_lines?: boolean;
+}

package/dist/providers/status-monitor.d.ts

@@ -3,16 +3,16 @@
  *
  * Common across all Provider categories (IDE/Extension/CLI/ACP).
  * - Approval waiting (waiting_approval) notification
- * - Notification when generating persists for extended duration
+ * - No-progress watchdog: alert when an active turn makes no progress for a while
  * - All config toggleable via Provider Settings
  */
 export interface MonitorConfig {
     /** Enable awaiting-approval notification */
     approvalAlert: boolean;
-    /** Prolonged generating notification enabled */
-    longGeneratingAlert: boolean;
-    /** Prolonged threshold (seconds) */
-    longGeneratingThresholdSec: number;
+    /** No-progress watchdog notification enabled */
+    noProgressAlert: boolean;
+    /** No-progress threshold (seconds) */
+    noProgressThresholdSec: number;
     /** Repeat notification cooldown (seconds) */
     alertCooldownSec: number;
 }
@@ -28,7 +28,7 @@ export declare class StatusMonitor {
     private config;
     private lastAlertTime;
     private generatingStartTimes;
-    private longGeneratingAlerted;
+    private noProgressAlerted;
     private lastProgressFingerprint;
     private lastProgressChangeAt;
     constructor(config?: Partial<MonitorConfig>);
@@ -40,7 +40,7 @@ export declare class StatusMonitor {
      * Check status transition → return notification event array.
      * Called from each onTick() or detectStatusTransition().
      */
-    check(agentKey: string, status: string, now: number, progressFingerprint?: string): MonitorEvent[];
+    check(agentKey: string, status: string, now: number, progressFingerprint?: string, approvalPending?: boolean): MonitorEvent[];
     /** Cooldown check — prevent sending the same notification too frequently */
     private shouldAlert;
     /** Reset (on agent terminate/restart) */

package/dist/providers/transcript-v2.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Chat Transcript Contract v2
+ *
+ * First-class message identity, monotonic sequence, strict enums. Designed to
+ * replace the v1 contract (contracts.ts ReadChatResult + types.ts ChatMessage)
+ * during the A2 big-bang. This module defines the contract; it does not yet
+ * change runtime behaviour. v1 keeps working until A2 flips the switch.
+ *
+ * Invariants v2 enforces (and v1 does not):
+ *   1. Every ChatMessageV2 has providerUnitKey, bubbleId, sequence — none optional.
+ *   2. sequence is a monotonic integer per (sessionId, source) tuple. Producers
+ *      never reuse it; consumers MAY assume strict ordering.
+ *   3. providerUnitKey is stable across re-reads: the same logical message
+ *      always yields the same key even if its index shifts or content is
+ *      edited mid-stream. Producers derive it from provider-owned identifiers
+ *      (turn id, native message id), not from content hashes or array index.
+ *   4. timestamp is producer-asserted wall-clock; orderingTimestamp is monotonic
+ *      and used for snapshot diffs. 1ms fallback increments are forbidden — if
+ *      a producer cannot supply a stable monotonic value, the daemon assigns
+ *      sequence at ingest and orderingTimestamp = ingestedAt.
+ *   5. visibility / source / role / kind are strict unions. No `(string & {})`
+ *      escape hatches.
+ *   6. Coverage is exactly one of full/tail/current-turn. Mixing it with
+ *      partialReason or unavailableReason is a contract violation.
+ *   7. workspace / sessionId are explicit on every ReadChatResultV2; the daemon
+ *      no longer infers them from message bodies.
+ */
+import type { MessagePart, ToolCallInfo } from './contracts.js';
+export declare const CHAT_CONTRACT_VERSION_V1: "1.0";
+export declare const CHAT_CONTRACT_VERSION_V2: "2.0";
+export type ChatContractVersion = typeof CHAT_CONTRACT_VERSION_V1 | typeof CHAT_CONTRACT_VERSION_V2;
+export declare const SUPPORTED_CHAT_CONTRACT_VERSIONS: readonly ChatContractVersion[];
+export declare const CHAT_ROLES_V2: readonly ["user", "assistant", "system"];
+export type ChatRoleV2 = typeof CHAT_ROLES_V2[number];
+export declare const CHAT_MESSAGE_KINDS_V2: readonly ["standard", "thought", "tool", "terminal", "system"];
+export type ChatMessageKindV2 = typeof CHAT_MESSAGE_KINDS_V2[number];
+export declare const CHAT_VISIBILITIES_V2: readonly ["user", "debug", "internal", "hidden"];
+export type ChatVisibilityV2 = typeof CHAT_VISIBILITIES_V2[number];
+export declare const CHAT_AUDIENCES_V2: readonly ["chat", "debug", "trace", "internal"];
+export type ChatAudienceV2 = typeof CHAT_AUDIENCES_V2[number];
+export declare const CHAT_SOURCES_V2: readonly ["assistant_text", "tool_call", "terminal_command", "runtime_activity", "runtime_status", "provider_chrome", "control"];
+export type ChatSourceV2 = typeof CHAT_SOURCES_V2[number];
+export declare const CHAT_BUBBLE_STATES_V2: readonly ["draft", "streaming", "final", "removed"];
+export type ChatBubbleStateV2 = typeof CHAT_BUBBLE_STATES_V2[number];
+/**
+ * Stable identity of a single chat message. All fields are required in v2.
+ *
+ * - providerUnitKey: provider-owned canonical id. Must be derivable from
+ *   provider primitives (native message id, turn id, bubble id), NOT from
+ *   array index or content hash. Stable across re-reads of the same logical
+ *   message even if neighbours change.
+ * - bubbleId: dashboard-owned bubble identity. May equal providerUnitKey when
+ *   the provider already exposes a bubble-grained id; otherwise daemon
+ *   derives it deterministically from providerUnitKey (e.g. `bubble:${key}`).
+ * - sequence: monotonic integer per (sessionId, source). Strictly increasing
+ *   over the lifetime of the session. Used for snapshot diffs and dedup.
+ * - turnKey: stable identifier for the conversation turn this message belongs
+ *   to. Required so consumers can group messages without re-deriving turns.
+ */
+export interface MessageIdentityV2 {
+    providerUnitKey: string;
+    bubbleId: string;
+    sequence: number;
+    turnKey: string;
+}
+/**
+ * Producer-asserted wall-clock time (ms since epoch). Forward jumps are
+ * permitted; consumers MUST NOT rely on this for ordering.
+ */
+export type ChatTimestampMs = number;
+/**
+ * Monotonic ordering value (ms since epoch, but assigned by the daemon at
+ * ingest to guarantee monotonicity even if the producer's wall clock skews).
+ * Used by snapshot diffs in place of timestamp.
+ */
+export type ChatOrderingTimestampMs = number;
+export interface ChatMessageV2 extends MessageIdentityV2 {
+    role: ChatRoleV2;
+    kind: ChatMessageKindV2;
+    content: string | MessagePart[];
+    bubbleState: ChatBubbleStateV2;
+    timestamp: ChatTimestampMs;
+    orderingTimestamp: ChatOrderingTimestampMs;
+    visibility: ChatVisibilityV2;
+    audience: ChatAudienceV2;
+    source: ChatSourceV2;
+    /** Sender display name (for shared sessions). Empty string when unused. */
+    senderName: string;
+    /** Tool calls associated with this message. Empty array when none. */
+    toolCalls: ToolCallInfo[];
+    /** Producer-defined metadata. Daemon never inspects this except for passthrough. */
+    meta: Readonly<Record<string, unknown>>;
+}
+export interface WorkspaceContextV2 {
+    /** Absolute realpath of the workspace the session is reading from. */
+    workspacePath: string;
+    /** Workspace the session was intended to operate on (may differ during cross-workspace ops). */
+    intendedWorkspacePath: string;
+}
+export interface SessionContextV2 {
+    /** Provider-owned session id (e.g. claude.jsonl uuid, codex session_meta.id). */
+    providerSessionId: string;
+    /** Optional daemon-side history alias used to disambiguate within a workspace. */
+    historySessionId?: string;
+}
+/**
+ * v1 allowed `coverage='full'` to coexist with `partialReason`/`unavailableReason`,
+ * which is a contract lie. v2 makes the three states mutually exclusive.
+ */
+export type CoverageHintV2 = {
+    kind: 'full';
+} | {
+    kind: 'tail';
+    tailMessageCount: number;
+} | {
+    kind: 'current-turn';
+    turnKey: string;
+} | {
+    kind: 'partial';
+    partialReason: string;
+} | {
+    kind: 'unavailable';
+    unavailableReason: string;
+};
+export type CanonicalHistoryModeV2 = 'native-source' | 'disabled' | 'materialized-mirror';
+export interface CanonicalHistoryDeclarationV2 {
+    contractVersion: ChatContractVersion;
+    format: string;
+    mode: CanonicalHistoryModeV2;
+    watchPath?: string;
+    scripts: {
+        readSession: string;
+        listSessions: string;
+    };
+}
+export type ReadChatStatusV2 = 'idle' | 'generating' | 'waiting_approval' | 'error' | 'panel_hidden' | 'streaming';
+export type ReadChatTurnStatusV2 = 'open' | 'waiting_approval' | 'complete' | 'error';
+export interface ReadChatResultV2 {
+    contractVersion: typeof CHAT_CONTRACT_VERSION_V2;
+    workspace: WorkspaceContextV2;
+    session: SessionContextV2;
+    coverage: CoverageHintV2;
+    status: ReadChatStatusV2;
+    messages: ChatMessageV2[];
+    currentTurnId: string;
+    turnStatus: ReadChatTurnStatusV2;
+    transcriptAuthority: 'provider' | 'daemon';
+}
+export declare class ChatContractViolationError extends Error {
+    readonly violationPath: string;
+    readonly contractVersion: ChatContractVersion;
+    constructor(contractVersion: ChatContractVersion, violationPath: string, detail: string);
+}
+/**
+ * Validate a v2 read_chat payload. Throws ChatContractViolationError on the
+ * first violation. v2 invariants beyond per-field checks:
+ *   - messages[*].sequence strictly increasing
+ *   - messages[*].orderingTimestamp monotonic non-decreasing
+ *   - coverage union is well-formed
+ */
+export declare function assertReadChatResultV2Payload(raw: unknown): ReadChatResultV2;
+export declare function isSupportedChatContractVersion(value: unknown): value is ChatContractVersion;
+/**
+ * Read a provider's declared chat contract version from its parsed
+ * provider.json `canonicalHistory.contractVersion` field.
+ *
+ * - Absent or unrecognized → treated as v1 (legacy behaviour preserved during
+ *   the A1 transition). A2 will tighten this to reject unsupported versions
+ *   at provider load time.
+ * - Present and supported → returned as-is.
+ *
+ * The returned version drives which validator (assertReadChatResultV2Payload
+ * vs the legacy validateReadChatResultPayload) processes the provider's
+ * read_chat output.
+ */
+export declare function readDeclaredChatContractVersion(canonicalHistory: unknown): ChatContractVersion;