@adhdev/daemon-core 0.9.82-rc.220 → 0.9.82-rc.221

package/src/providers/spec/types.ts

@@ -1,17 +1,14 @@
 /**
- * Type mirror of adhdev:cli/spec@1 (v1) and adhdev:cli/spec@3 (v3).
- * Keep in sync with schema.gen.ts.
+ * Shared types for the adhdev:cli/spec@4 FSM spec system.
  *
- * v1 uses layout.sections[] and debounce{}.
- * v3 uses sections{} (object) and timing{}, with composable conditions.
- *
- * The loader auto-migrates v1 → v3. Callers receive a CliSpec (v3) after
- * loadSpec; the v1 raw shape is only used during migration.
+ * These are the building blocks reused by fsm-types.ts, evaluator.ts, and
+ * the rest of the spec stack. v3/v1 types have been removed — all providers
+ * are on v4.
  */
 'use strict';
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Shared / unchanged types
+// Shared / layout types
 // ─────────────────────────────────────────────────────────────────────────────
 
 export type Size = number | string;
@@ -22,12 +19,19 @@ export interface SectionPattern {
     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: SectionRegex;
+          wait_for: WaitForCondition;
           extract_choices: SectionPattern;
           submit_key: string;
       }
@@ -58,15 +62,6 @@ export interface DelegateTrigger {
     task_template: string;
 }
 
-/**
- * Native history config — three modes, picked by which fields are present:
- *
- *   1. `reader`: built-in reader id (claude-cli / codex-cli / antigravity-cli / hermes-cli).
- *
- *   2. `source`: declarative source descriptor.
- *
- *   3. `override_path`: relative path to a provider-supplied reader module.
- */
 export interface NativeHistoryConfig {
     reader?: 'claude-cli' | 'codex-cli' | 'antigravity-cli' | 'hermes-cli';
     source?: NativeHistorySource;
@@ -106,21 +101,20 @@ export interface NativeHistoryMessageMap {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-// v1 types (legacy — used internally during migration)
+// Section definition
 // ─────────────────────────────────────────────────────────────────────────────
 
-export interface Section {
-    id: string;
+export interface SectionDef {
     from_top?: Size;
     from_bottom?: Size;
-    until?: { section: string };
-    anchor_regex?: string;
+    until?: string;             // section id OR regex (starts with ^)
+    anchor?: string;
     anchor_flags?: string;
     anchor_last?: boolean;
     anchor_context?: {
         prev?: string;
-        prev_flags?: string;
         next?: string;
+        prev_flags?: string;
         next_flags?: string;
     };
     lines?: number;
@@ -128,63 +122,13 @@ export interface Section {
     until_regex_flags?: string;
 }
 
-/** v1 condition — flat SectionRegex object. Also used in control_bar.wait_for. */
-export interface SectionRegex {
-    section?: string;
-    regex?: string;
-    flags?: string;
-    cursor_row_min?: number;
-    cursor_row_max?: number;
-    cursor_col_min?: number;
-    cursor_col_max?: number;
-    /** v1 delta detection (cursor_above_lines + changed). */
-    cursor_above_lines?: number;
-    /** Required when cursor_above_lines is set. */
-    changed?: true;
-}
-
-export interface ModalButtonsRule {
-    section?: string;
-    pattern?: string;
-    flags?: string;
-    patterns?: Array<{ pattern: string; flags?: string }>;
-    key_for_index: string;
-    min_count?: number;
-    continuation_lines?: boolean;
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
-// v3 types (current)
+// Conditions (shared with fsm-types.ts FsmCondition leaves)
 // ─────────────────────────────────────────────────────────────────────────────
 
-/**
- * v3 section definition — keyed by id in `sections{}` object.
- * `until` is EITHER a section-id string (no `^` prefix) OR a regex string (starts with `^`).
- */
-export interface SectionDef {
-    // positional
-    from_top?: Size;
-    from_bottom?: Size;
-    until?: string;             // section id OR regex (starts with ^)
-    // anchor-based
-    anchor?: string;            // regex (replaces anchor_regex)
-    anchor_flags?: string;
-    anchor_last?: boolean;
-    anchor_context?: {
-        prev?: string;
-        next?: string;
-        prev_flags?: string;
-        next_flags?: string;
-    };
-    lines?: number;
-    until_regex?: string;       // kept for anchor-based extension
-    until_regex_flags?: string;
-}
-
-/** v3 regex condition against a section (or full screen). */
 export interface RegexCondition {
     section?: string;
-    matches: string;            // regex string
+    matches: string;
     flags?: string;
     cursor_row_min?: number;
     cursor_row_max?: number;
@@ -192,28 +136,26 @@ export interface RegexCondition {
     cursor_col_max?: number;
 }
 
-/** v3 delta condition: N lines above cursor changed vs prevLines.
- *  changed:false + stable_ms: region must be stable for at least N ms. */
 export interface ChangedCondition {
     cursor_above: number;
     changed: boolean;
-    /** Only for changed:false — region must have been stable for this many ms. */
     stable_ms?: number;
 }
 
-/** v3 AND composite. */
 export interface AllCondition {
     all: Condition[];
 }
 
-/** v3 OR composite. */
 export interface AnyCondition {
     any: Condition[];
 }
 
 export type Condition = RegexCondition | ChangedCondition | AllCondition | AnyCondition;
 
-/** v3 extract_title config. */
+// ─────────────────────────────────────────────────────────────────────────────
+// Extraction helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
 export interface ExtractTitle {
     section?: string;
     regex?: string;
@@ -221,7 +163,6 @@ export interface ExtractTitle {
     first_line?: true;
 }
 
-/** v3 extract_buttons config. */
 export interface ExtractButtons {
     section?: string;
     pattern: string;
@@ -230,136 +171,3 @@ export interface ExtractButtons {
     min_count?: number;
     continuation_lines?: boolean;
 }
-
-/** v3 state. */
-export interface SpecStateV3 {
-    id: string;
-    label: string;
-    when: AllCondition | AnyCondition;
-    extract?: {
-        title?: ExtractTitle;
-        buttons?: ExtractButtons;
-    };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// CliSpec — v3 (the canonical runtime type after loading)
-// ─────────────────────────────────────────────────────────────────────────────
-
-export interface CliSpec {
-    $schema: 'adhdev:cli/spec@3';
-    id: string;
-    name: string;
-    binary: string;
-    spawn_args?: string[];
-    env?: Record<string, string>;
-    cli_version_range?: string;
-    send_message: {
-        submit_key: string;
-        delay_ms_before_submit?: number;
-        delay_ms_per_char?: number;
-    };
-    sections: Record<string, SectionDef>;
-    states: SpecStateV3[];
-    default_state: string;
-    control_bar?: Control[];
-    notifications?: NotificationRule[];
-    delegate?: DelegateTrigger[];
-    native_history?: NativeHistoryConfig;
-    requiresFinalAssistantBeforeIdle?: boolean;
-    /**
-     * Per-spec timing knobs. Replaces v1 `debounce`.
-     * Also accessible via the legacy `debounce` alias in the driver for
-     * backward compat with older callers.
-     */
-    timing?: {
-        busy_hold_ms?: number;
-        idle_hold_ms?: number;
-        startup_grace_ms?: number;
-        /** Suppress idle downshift while the screen is actively changing.
-         *  When set, any PTY frame that changes the screen resets a timer;
-         *  idle transitions (busy_hold expiry and completion_idle_after) are
-         *  blocked until the screen has been stable for this many ms. */
-        screen_active_hold_ms?: number;
-        completion_marker?: {
-            section?: string;
-            matches: string;
-            flags?: string;
-            hold_ms: number;
-            force_after_ms?: number;
-        };
-    };
-    /**
-     * Legacy alias: v1 callers (tests, tooling) may read `debounce`.
-     * The loader populates both `timing` and `debounce` pointing at the
-     * same object so callers that use either field see consistent values.
-     * @deprecated Use `timing` instead.
-     */
-    debounce?: {
-        busy_hold_ms?: number;
-        idle_hold_ms?: number;
-        startup_grace_ms?: number;
-        screen_active_hold_ms?: number;
-        /**
-         * Legacy field name for completion_marker. Populated by the loader
-         * from `timing.completion_marker` for backward compat.
-         */
-        completion_idle_after?: {
-            section?: string;
-            regex: string;
-            flags?: string;
-            hold_ms: number;
-            force_after_ms?: number;
-        };
-    };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// v1 CliSpec raw shape (for migration only — not exported as the primary type)
-// ─────────────────────────────────────────────────────────────────────────────
-
-/** Raw v1 spec shape as loaded from JSON. Used only in migrateV1toV3. */
-export interface RawCliSpecV1 {
-    $schema: 'adhdev:cli/spec@1';
-    id: string;
-    name: string;
-    binary: string;
-    spawn_args?: string[];
-    env?: Record<string, string>;
-    cli_version_range?: string;
-    send_message: {
-        submit_key: string;
-        delay_ms_before_submit?: number;
-        delay_ms_per_char?: number;
-    };
-    layout: { sections: Section[] };
-    states: Array<{
-        id: string;
-        label: string;
-        when: SectionRegex;
-        extract_title?: SectionRegex;
-        modal_buttons?: ModalButtonsRule;
-    }>;
-    default_state: string;
-    control_bar?: Control[];
-    notifications?: NotificationRule[];
-    delegate?: DelegateTrigger[];
-    native_history?: NativeHistoryConfig;
-    requiresFinalAssistantBeforeIdle?: boolean;
-    debounce?: {
-        busy_hold_ms?: number;
-        idle_hold_ms?: number;
-        startup_grace_ms?: number;
-        completion_idle_after?: {
-            section?: string;
-            regex: string;
-            flags?: string;
-            hold_ms: number;
-            force_after_ms?: number;
-        };
-    };
-}
-
-// Keep SpecState as alias for backward compat with cli-adapter.ts and other code
-// that imports SpecState from types.ts. In v3 we use SpecStateV3.
-export type SpecState = SpecStateV3;

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

@@ -1,287 +0,0 @@
-import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
-import { type SpecEvaluation, type TraceEntry } from './evaluator.js';
-import type { CliSpec } from './types.js';
-export type DashboardEvent = {
-    kind: 'pty_data';
-    chunk: string;
-} | {
-    kind: 'state_changed';
-    state: {
-        id: string;
-        label: string;
-        title: string | null;
-    };
-    modal: {
-        title: string | null;
-        buttons: {
-            index: number;
-            label: string;
-        }[];
-    } | null;
-    controls: {
-        id: string;
-        label: string;
-        action_type: string;
-    }[];
-} | {
-    kind: 'notification';
-    id: string;
-    title: string;
-    body: string;
-} | {
-    kind: 'delegate';
-    id: string;
-    task: string;
-} | {
-    kind: 'spec_trace';
-    entries: TraceEntry[];
-} | {
-    kind: 'exit';
-    exit_code: number;
-} | {
-    kind: 'spec_error';
-    errors: string[];
-};
-export type DashboardCommand = {
-    kind: 'send_message';
-    text: string;
-} | {
-    kind: 'pty_write';
-    data: string;
-} | {
-    kind: 'click_control';
-    control_id: string;
-    payload?: unknown;
-} | {
-    kind: 'click_modal_button';
-    index: number;
-} | {
-    kind: 'attach_image';
-    blob: string;
-    mime: string;
-} | {
-    kind: 'resize';
-    cols: number;
-    rows: number;
-} | {
-    kind: 'cancel';
-} | {
-    kind: 'shutdown';
-};
-/** One state-history entry — the union of fields produced by the v3 SpecDriver
- *  (debounce-based) and the v4 FsmDriver (transition-based). The cli-adapter
- *  and debug panel read this shape from either driver. */
-export interface DriverHistoryEntry {
-    stateId: string;
-    label: string;
-    at: number;
-    durationMs: number;
-    reason: string;
-    matchedStateId?: string;
-    matchedRules?: string[];
-    debounceKind?: string;
-    idleHoldMs?: number;
-    busyHoldMs?: number;
-    /** v4: the transition that fired, e.g. "idle→busy". */
-    via?: string;
-}
-/** The surface the cli-adapter drives. Implemented by both SpecDriver (v3,
- *  debounce) and FsmDriver (v4, FSM). Lets the adapter hold either without
- *  branching on the concrete type. */
-export interface ISpecDriver {
-    subscribe(listener: (ev: DashboardEvent) => void): () => void;
-    start(): void;
-    dispatch(cmd: DashboardCommand): void;
-    snapshot(): string;
-    getCursorPosition(): {
-        row: number;
-        col: number;
-    };
-    getScreen(): string;
-    getSpecPath(): string;
-    shutdown(): void;
-    getStateHistory(): ReadonlyArray<DriverHistoryEntry>;
-    getSections(): Array<{
-        id: string;
-        text: string;
-    }> | null;
-    getLastBusyAt(): number;
-    hasIdleHoldPending(): boolean;
-    getCompletionIdleDebounceState(): {
-        active: boolean;
-        ageMs: number;
-        holdMs: number;
-        forceAfterMs: number;
-    } | null;
-    /** v4 only — present on FsmDriver. Returns the live transition table. */
-    getFsmDebug?(): unknown;
-}
-export interface SpecDriverOpts {
-    specPath: string;
-    workingDir: string;
-    extraEnv?: Record<string, string>;
-    cols?: number;
-    rows?: number;
-    /** Set false to skip the spec.json fs.watch. */
-    hotReload?: boolean;
-    /** Set true to forward trace entries on every state_changed. */
-    emitTrace?: boolean;
-    /** Inject the daemon's PTY transport (typically SessionHostPtyTransportFactory). */
-    transportFactory?: PtyTransportFactory;
-    /**
-     * Extra CLI args appended to spec.spawn_args. Used by the daemon to
-     * pass per-launch arguments like `--session-id <uuid>` so the agent
-     * uses the daemon's providerSessionId instead of generating its own.
-     */
-    extraCliArgs?: string[];
-}
-/**
- * Pick the effective delay (ms) to wait between writing the prompt body and
- * writing the submit_key. Exported for tests; production callers go through
- * actuallySendMessage. Floors to SUBMIT_DELAY_FLOOR_MS so specs that omit
- * delay_ms_before_submit (e.g. claude, antigravity) still get baseline
- * protection against the paste→submit race. Adds line-count bonus so
- * multi-line prompts get more settling time on TUIs that re-render per
- * embedded `\n`.
- */
-export declare function resolveSubmitDelayMs(specBeforeSubmit: number | undefined, text: string): number;
-export declare function matchesCompletionIdleRule(spec: CliSpec, ev: SpecEvaluation, screen: string): string | null;
-export declare function matchesCompletionIdleTargetState(spec: CliSpec, ev: SpecEvaluation, screen: string, cursor?: {
-    row: number;
-    col: number;
-}): boolean;
-export declare class SpecDriver implements ISpecDriver {
-    private readonly opts;
-    private spec;
-    private adapter;
-    private listeners;
-    private currentStateId;
-    /** Have we ever seen the spec's idle state *after* the startup grace
-     *  window? Until we do, the agent's startup banner may still be
-     *  painting and any send_message we forward to the PTY will be wiped
-     *  when the banner clears the screen. Queue + drain on first valid
-     *  idle. */
-    private idleSeenOnce;
-    private startedAtMs;
-    private pendingSends;
-    private currentEval;
-    private pickerInProgress;
-    private delegateTimers;
-    /** Timestamp of the last time the evaluator returned busy. Used to debounce
-     *  the busy → idle transition (see reevaluate). */
-    private lastBusyAt;
-    /** The exact busy state object we last saw — held alongside lastBusyAt so
-     *  the hold can re-emit the same { id: 'busy', label, title } payload the
-     *  dashboard already learned about. currentEval can't fill this role
-     *  because the evaluator already moved past busy by the time the hold
-     *  kicks in. */
-    private lastBusyState;
-    /** Timestamp of the last time we entered a modal state (approval/picker or
-     *  any non-busy non-idle state). Used to suppress brief busy blips that
-     *  appear while the modal is still on screen — Claude Code streams body
-     *  text that transiently shows a spinner even while an approval modal is
-     *  visible, causing rapid approval→busy→approval flicker on the dashboard. */
-    private lastModalAt;
-    /** The modal state snapshot held across busy blips. */
-    private lastModalState;
-    /** Timestamp of when we last *exited* a modal state (approval/picker → idle
-     *  or directly via completion_idle_after).  Used to suppress completion_idle_after
-     *  firings that were queued before the modal appeared and expire immediately
-     *  after the modal is dismissed — without this the agent appears idle even
-     *  though it is still generating. */
-    private lastModalExitAt;
-    private completionIdleFirstSeenAt;
-    private completionIdleKey;
-    /** Previous screen lines — passed to evaluate() for `changed` condition detection. */
-    private prevScreenLines;
-    /** Timestamp when idle was last committed (either direct or via idle_hold_ms).
-     *  Used to suppress immediate idle → busy re-entry from transient `changed`
-     *  condition blips (e.g. completion-marker counter "Completed for Xs" updating
-     *  every second, which triggers cursor_above:changed and bounces back to busy
-     *  right after an idle commit). */
-    private lastIdleCommittedAt;
-    /** Timestamp of the last PTY frame that changed the screen content.
-     *  Used by screen_active_hold_ms to suppress idle downshifts while
-     *  the terminal is still actively updating. */
-    private lastScreenChangedAt;
-    /** Per-cursor_above region last-changed timestamps for stable_ms tracking.
-     *  Key: cursor_above value. Value: last time that region changed. */
-    private regionLastChangedAt;
-    /** Timer that re-runs evaluate() once the hold window expires. Needed
-     *  because the PTY stops emitting once the agent finishes; without an
-     *  explicit wake-up there's nothing to trigger the busy → idle
-     *  downshift. */
-    private busyExpiryTimer;
-    /** Set true while reevaluate() is invoked from busyExpiryTimer callback. */
-    private busyExpiryFired;
-    /** Pending idle-commit timer. Armed when the evaluator first returns idle;
-     *  fires after idle_hold_ms if no non-idle reading has cancelled it. */
-    private idleHoldTimer;
-    /** State snapshot captured when the idle hold was armed — emitted on commit. */
-    private pendingIdleState;
-    private specWatcher;
-    /** Ring buffer of committed state transitions (max 50). */
-    private stateHistory;
-    private prevStateAt;
-    constructor(opts: SpecDriverOpts);
-    /** Subscribe to outbound events. Returns an unsubscribe fn. */
-    subscribe(listener: (ev: DashboardEvent) => void): () => void;
-    start(): void;
-    dispatch(cmd: DashboardCommand): void;
-    snapshot(): string;
-    getCursorPosition(): {
-        row: number;
-        col: number;
-    };
-    shutdown(): void;
-    private cancelIdleHold;
-    private pushHistory;
-    getStateHistory(): ReadonlyArray<{
-        stateId: string;
-        label: string;
-        at: number;
-        durationMs: number;
-        reason: string;
-        matchedStateId?: string;
-        matchedRules?: string[];
-        debounceKind?: string;
-        idleHoldMs?: number;
-        busyHoldMs?: number;
-    }>;
-    getLastBusyAt(): number;
-    hasIdleHoldPending(): boolean;
-    getSpecPath(): string;
-    getCompletionIdleDebounceState(): {
-        active: boolean;
-        ageMs: number;
-        holdMs: number;
-        forceAfterMs: number;
-    } | null;
-    getScreen(): string;
-    getSections(): Array<{
-        id: string;
-        text: string;
-    }> | null;
-    private loadSpecOrThrow;
-    private buildAdapterOpts;
-    private armSpecWatcher;
-    private emitInitialState;
-    /** Re-arm the timer that wakes the driver up after BUSY_HOLD_MS so it
-     *  can decide whether to downshift to idle. Always uses the most recent
-     *  hold value so a spec hot-reload that shortens the hold takes effect
-     *  on the next busy entry. Safe to call repeatedly; only the last call
-     *  fires. */
-    private scheduleBusyExpiry;
-    private reevaluate;
-    private armOrCancelDelegateTimers;
-    private fireDelegate;
-    private handleSendMessage;
-    private actuallySendMessage;
-    private handleClickControl;
-    private handleClickModalButton;
-    private handleAttachImage;
-    private tryAdvancePicker;
-    private handleExit;
-    private emit;
-}
-export declare function guessExt(mime: string): string;

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

@@ -1,15 +0,0 @@
-import type { CliSpec } from './types.js';
-export interface SpecLoadResult {
-    ok: true;
-    spec: CliSpec;
-    sourcePath: string;
-}
-export interface SpecLoadError {
-    ok: false;
-    errors: string[];
-    sourcePath: string;
-}
-export declare function loadSpec(sourcePath: string): SpecLoadResult | SpecLoadError;
-export declare function migrateV1toV3(raw: any): any;
-/** Convenience: look up a provider's spec.json next to its provider dir. */
-export declare function resolveSpecPath(providerDir: string): string;