@adhdev/daemon-core 0.9.82-rc.20 → 0.9.82-rc.200

package/src/providers/spec/schema.json

@@ -0,0 +1,237 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "adhdev:cli/spec@1",
+    "title": "ADHDev CLI provider spec",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["$schema", "id", "name", "binary", "send_message", "layout", "states", "default_state"],
+    "properties": {
+        "$schema": { "type": "string", "const": "adhdev:cli/spec@1" },
+        "id": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9-]*$" },
+        "name": { "type": "string", "minLength": 1 },
+        "binary": { "type": "string", "minLength": 1 },
+        "spawn_args": { "type": "array", "items": { "type": "string" }, "default": [] },
+        "env": {
+            "type": "object",
+            "additionalProperties": { "type": "string" },
+            "default": {}
+        },
+        "send_message": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["submit_key"],
+            "properties": {
+                "submit_key": { "type": "string", "minLength": 1 },
+                "delay_ms_before_submit": { "type": "integer", "minimum": 0 },
+                "delay_ms_per_char": { "type": "integer", "minimum": 0 }
+            }
+        },
+        "layout": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["sections"],
+            "properties": {
+                "sections": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "$ref": "#/definitions/section" }
+                }
+            }
+        },
+        "states": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "#/definitions/state" }
+        },
+        "default_state": { "type": "string", "minLength": 1 },
+        "control_bar": {
+            "type": "array",
+            "default": [],
+            "items": { "$ref": "#/definitions/control" }
+        },
+        "notifications": {
+            "type": "array",
+            "default": [],
+            "items": { "$ref": "#/definitions/notification" }
+        },
+        "delegate": {
+            "type": "array",
+            "default": [],
+            "items": { "$ref": "#/definitions/delegateTrigger" }
+        },
+        "native_history": { "$ref": "#/definitions/nativeHistory" },
+        "cli_version_range": { "type": "string", "minLength": 1 },
+        "requiresFinalAssistantBeforeIdle": { "type": "boolean" },
+        "debounce": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "busy_hold_ms": { "type": "integer", "minimum": 0 },
+                "idle_hold_ms": { "type": "integer", "minimum": 0 },
+                "startup_grace_ms": { "type": "integer", "minimum": 0 },
+                "completion_idle_after": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["regex", "hold_ms"],
+                    "properties": {
+                        "section": { "type": "string", "minLength": 1 },
+                        "regex": { "type": "string", "minLength": 1 },
+                        "flags": { "type": "string" },
+                        "hold_ms": { "type": "integer", "minimum": 0 }
+                    }
+                }
+            }
+        }
+    },
+    "definitions": {
+        "size": {
+            "oneOf": [
+                { "type": "integer", "minimum": 0 },
+                { "type": "string", "pattern": "^\\d+(\\.\\d+)?%$" }
+            ]
+        },
+        "section": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$" },
+                "from_top": { "$ref": "#/definitions/size" },
+                "from_bottom": { "$ref": "#/definitions/size" },
+                "until": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["section"],
+                    "properties": { "section": { "type": "string" } }
+                }
+            }
+        },
+        "sectionRegex": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["regex"],
+            "properties": {
+                "section": { "type": "string" },
+                "regex": { "type": "string", "minLength": 1 },
+                "flags": { "type": "string", "default": "i" },
+                "cursor_row_min": { "type": "integer", "minimum": 0 },
+                "cursor_row_max": { "type": "integer", "minimum": 0 },
+                "cursor_col_min": { "type": "integer", "minimum": 0 },
+                "cursor_col_max": { "type": "integer", "minimum": 0 }
+            }
+        },
+        "sectionPattern": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pattern"],
+            "properties": {
+                "section": { "type": "string" },
+                "pattern": { "type": "string", "minLength": 1 },
+                "flags": { "type": "string", "default": "" }
+            }
+        },
+        "state": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label", "when"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$" },
+                "label": { "type": "string", "minLength": 1 },
+                "when": { "$ref": "#/definitions/sectionRegex" },
+                "extract_title": { "$ref": "#/definitions/sectionRegex" },
+                "modal_buttons": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["pattern", "key_for_index"],
+                    "properties": {
+                        "section": { "type": "string" },
+                        "pattern": { "type": "string", "minLength": 1 },
+                        "flags": { "type": "string" },
+                        "key_for_index": { "type": "string", "minLength": 1 },
+                        "min_count": { "type": "integer", "minimum": 1, "default": 2 },
+                        "continuation_lines": { "type": "boolean", "default": false }
+                    }
+                }
+            }
+        },
+        "control": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label", "action"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$" },
+                "label": { "type": "string", "minLength": 1 },
+                "visible_when_state": { "type": "array", "items": { "type": "string" } },
+                "action": { "$ref": "#/definitions/controlAction" }
+            }
+        },
+        "controlAction": {
+            "oneOf": [
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "keys"],
+                    "properties": {
+                        "type": { "const": "send_keys" },
+                        "keys": { "type": "string", "minLength": 1 }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "trigger_keys", "wait_for", "extract_choices", "submit_key"],
+                    "properties": {
+                        "type": { "const": "open_picker" },
+                        "trigger_keys": { "type": "string", "minLength": 1 },
+                        "wait_for": { "$ref": "#/definitions/sectionRegex" },
+                        "extract_choices": { "$ref": "#/definitions/sectionPattern" },
+                        "submit_key": { "type": "string", "minLength": 1 }
+                    }
+                },
+                {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type", "method", "keys_template"],
+                    "properties": {
+                        "type": { "const": "attach_image" },
+                        "method": { "const": "tempfile_then_keys" },
+                        "keys_template": { "type": "string", "minLength": 1 }
+                    }
+                }
+            ]
+        },
+        "notification": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "when_state", "title"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$" },
+                "when_state": { "type": "string", "minLength": 1 },
+                "title": { "type": "string", "minLength": 1 },
+                "body": { "type": "string" }
+            }
+        },
+        "nativeHistory": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["reader"],
+            "properties": {
+                "reader": {
+                    "type": "string",
+                    "enum": ["claude-cli", "codex-cli", "antigravity-cli", "hermes-cli"]
+                }
+            }
+        },
+        "delegateTrigger": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "when_state", "task_template"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1, "pattern": "^[a-z][a-z0-9_]*$" },
+                "when_state": { "type": "string", "minLength": 1 },
+                "after_duration_ms": { "type": "integer", "minimum": 0 },
+                "task_template": { "type": "string", "minLength": 1 }
+            }
+        }
+    }
+}

package/src/providers/spec/types.ts

@@ -0,0 +1,301 @@
+/**
+ * Type mirror of adhdev:cli/spec@1. Keep in sync with schema.json.
+ * Adding a field here without also adding it to schema.json (or vice
+ * versa) is a bug — the loader rejects specs that don't match the
+ * schema, so a missing field would fail at load time.
+ */
+'use strict';
+
+export type Size = number | string;
+
+export interface Section {
+    id: string;
+    from_top?: Size;
+    from_bottom?: Size;
+    until?: { section: string };
+    /** Scan the screen for the first (or last, if anchor_last=true) line
+     *  matching this regex and use that line as the section start.
+     *  Combine with `lines`, `until_regex`, or leave alone (defaults to
+     *  end-of-screen) to control how far it extends. */
+    anchor_regex?: string;
+    anchor_flags?: string;
+    /** If true, use the LAST matching line instead of the first. Useful
+     *  when the anchor pattern appears multiple times (e.g. separator
+     *  lines) and you want the one closest to the bottom. */
+    anchor_last?: boolean;
+    /** Optional neighbouring-line guards that must also match for the
+     *  anchor to be accepted. Reduces false positives when the anchor
+     *  pattern could appear elsewhere on screen (e.g. `>` in body text).
+     *  `prev` checks the line immediately above; `next` the line below. */
+    anchor_context?: {
+        prev?: string;
+        prev_flags?: string;
+        next?: string;
+        next_flags?: string;
+    };
+    /** When used with anchor_regex: take at most this many lines from the
+     *  anchor point. */
+    lines?: number;
+    /** When used with anchor_regex: extend until the first line matching
+     *  this regex (exclusive). Takes precedence over `lines`. */
+    until_regex?: string;
+    until_regex_flags?: string;
+}
+
+export interface SectionRegex {
+    section?: string;
+    regex: string;
+    flags?: string;
+    /**
+     * Optional cursor-position guards. When present, the state is only
+     * considered matched if the terminal cursor row/column satisfies the
+     * bounds (0-based, inclusive). Missing or undefined means "no constraint".
+     *
+     * Use case: distinguish modal zone from body zone for TUIs that use
+     * cursor position rather than distinct text to locate the active prompt
+     * (e.g. Antigravity cursor lands in modal_zone rows 8-31 when approval
+     * is visible, never in body rows 0-7). Without this guard, body text
+     * containing "Do you want to proceed?" could false-positive a modal match.
+     */
+    cursor_row_min?: number;
+    cursor_row_max?: number;
+    cursor_col_min?: number;
+    cursor_col_max?: number;
+}
+
+export interface SectionPattern {
+    section?: string;
+    pattern: string;
+    flags?: string;
+}
+
+export interface ModalButtonsRule {
+    section?: string;
+    pattern: string;
+    flags?: string;
+    key_for_index: string;
+    min_count?: number;
+    continuation_lines?: boolean;
+}
+
+export interface SpecState {
+    id: string;
+    label: string;
+    when: SectionRegex;
+    extract_title?: SectionRegex;
+    modal_buttons?: ModalButtonsRule;
+}
+
+export type ControlAction =
+    | { type: 'send_keys'; keys: string }
+    | {
+          type: 'open_picker';
+          trigger_keys: string;
+          wait_for: SectionRegex;
+          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;
+}
+
+/**
+ * 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).
+ *      Backwards-compatible path used by the four shipped providers.
+ *
+ *   2. `source`: declarative source descriptor. The daemon's spec native-history
+ *      executor reads the on-disk store (jsonl file / sqlite db) directly using
+ *      paths + jsonpath maps from this block. New providers should prefer this
+ *      mode — no daemon changes required.
+ *
+ *   3. `override_path`: relative path to a provider-supplied reader module
+ *      (e.g. "./native_history/index.js"). Escape hatch for formats too
+ *      exotic for the declarative executor. The module must default-export
+ *      a function with the signature
+ *        (input: NativeHistoryInput) => NativeHistoryResult | null
+ *      and runs under provider-script-root sandboxing (same gate as
+ *      scripts.js).
+ *
+ * The three modes are mutually exclusive — set exactly one. Loader rejects
+ * specs that set zero or more than one.
+ */
+export interface NativeHistoryConfig {
+    reader?: 'claude-cli' | 'codex-cli' | 'antigravity-cli' | 'hermes-cli';
+    source?: NativeHistorySource;
+    override_path?: string;
+}
+
+export type NativeHistorySource =
+    | NativeHistoryJsonlSource
+    | NativeHistorySqliteSource;
+
+/**
+ * JSONL source — each line in the resolved file is one record.
+ *
+ * `path` accepts ~/, environment variables (${HOME}), and a small set of
+ * runtime variables:
+ *   {cwd}              — the session's working directory, raw
+ *   {cwd_dashed}       — cwd with `/` replaced by `-` (claude's per-project key)
+ *   {session_id}       — providerSessionId, when known
+ *   {yyyy} {mm} {dd}   — UTC date components
+ *
+ * When `path` resolves to a directory, the daemon picks the newest file
+ * matching `file_pattern` whose mtime is inside `recent_window_ms` (default
+ * 5min) — prevents the wrong session's transcript from leaking through.
+ */
+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; // jsonpath into the first record when session_id_from='first_record'
+    message_filter?: { where: string }; // tiny expression: field op value joined by && / ||
+    message_map: NativeHistoryMessageMap;
+}
+
+/**
+ * SQLite source — provider runs two queries on a read-only handle: one to
+ * pick the session row (`session_query` — first row's first column is the
+ * sessionId), then one to fetch messages (`message_query` — `?` is bound
+ * to the sessionId). Output rows are projected through `message_map`.
+ */
+export interface NativeHistorySqliteSource {
+    kind: 'sqlite';
+    path: string;
+    session_query: string;
+    message_query: string;
+    message_map: NativeHistoryMessageMap;
+}
+
+/**
+ * Maps a source record (jsonl line object / sqlite row) to a daemon
+ * native-history message. Values are jsonpath-lite strings: `$.foo.bar`
+ * or `$.items[0].text`. Literal strings (no leading `$`) pass through.
+ *
+ * `content_strip` lets a spec drop wrapper tags that the agent injects
+ * into its own transcript (claude's `<local-command-caveat>`, agy's
+ * `<USER_REQUEST>` / `<ADDITIONAL_METADATA>` / `<USER_SETTINGS_CHANGE>`).
+ * Each entry is a tag name; the executor removes `<tag>…</tag>` segments
+ * non-greedily before the value is handed to the dashboard. After all
+ * strips, leading/trailing whitespace is trimmed. If the result is empty
+ * the message is dropped.
+ */
+export interface NativeHistoryMessageMap {
+    role: string;            // → 'user' | 'assistant' | 'system' after normalize
+    content: string;
+    /**
+     * Tags whose entire `<tag>…</tag>` segment is removed from content.
+     * Use for noise wrappers the agent ships alongside the real message
+     * (claude's `<local-command-caveat>`, agy's `<ADDITIONAL_METADATA>`).
+     */
+    content_strip?: string[];
+    /**
+     * Tags whose open/close markers are removed but inner content is kept.
+     * Use when the *real* user/assistant message is wrapped in a tag
+     * the agent uses for routing (agy wraps user input in `<USER_REQUEST>`).
+     */
+    content_unwrap?: string[];
+    timestamp_ms?: string;   // optional; falls back to receivedAt = now
+    kind?: string;           // optional; defaults to 'standard'
+}
+
+export interface CliSpec {
+    $schema: 'adhdev:cli/spec@1';
+    id: string;
+    name: string;
+    binary: string;
+    spawn_args?: string[];
+    env?: Record<string, string>;
+    /**
+     * Optional version constraint this spec is authored for, e.g. ">=2.1.0".
+     * Pure metadata used by tooling/UI — the actual version-to-spec match
+     * happens in provider-loader via the manifest's compatibility array.
+     * Spec authors include this so a misrouted spec is easy to spot.
+     */
+    cli_version_range?: string;
+    send_message: {
+        submit_key: string;
+        delay_ms_before_submit?: number;
+        delay_ms_per_char?: number;
+    };
+    layout: { sections: Section[] };
+    states: SpecState[];
+    default_state: string;
+    control_bar?: Control[];
+    notifications?: NotificationRule[];
+    delegate?: DelegateTrigger[];
+    native_history?: NativeHistoryConfig;
+    /**
+     * When true, the daemon's completed-finalization gate will not emit
+     * `generating_completed` until native history confirms the last message
+     * role is `assistant`. Prevents PTY quiet-period from triggering idle
+     * before the CLI has finished writing its response to disk.
+     */
+    requiresFinalAssistantBeforeIdle?: boolean;
+    /**
+     * Per-spec debounce knobs. Defaults are conservative (busy_hold_ms
+     * 6000) and live in SpecDriver. Spec authors override here when a
+     * particular CLI flickers slower/faster than the default.
+     */
+    debounce?: {
+        /** Min time to stay in busy after the evaluator last reported it.
+         *  Absorbs per-frame flicker in TUIs that stream output through
+         *  the same region as the spinner. */
+        busy_hold_ms?: number;
+        /** Min time the idle state must remain matched before it is
+         *  committed. Filters transient idle flickers that appear during
+         *  approval dismissals, layout reflows, or brief spinner gaps.
+         *  Any non-idle reading within the window cancels the transition.
+         *  When omitted the idle transition is immediate (legacy behaviour). */
+        idle_hold_ms?: number;
+        /** Min time after start() before a send_message is allowed to
+         *  reach the PTY. Banner paints + auth flows + skill listings
+         *  can keep the agent unable to accept input for several seconds
+         *  even though the idle regex matches a transient empty prompt.
+         *  Send_messages issued before this window are queued and drained
+         *  once the window passes and an idle state has actually been
+         *  observed. */
+        startup_grace_ms?: number;
+        /** Treat a provider-specific completion marker as idle after it has
+         *  remained visible for hold_ms. This handles TUIs that leave their
+         *  last spinner glyph next to a completed timer, causing the normal
+         *  busy regex to keep matching after the turn is done. */
+        completion_idle_after?: {
+            section?: string;
+            regex: string;
+            flags?: string;
+            hold_ms: number;
+            /** If the target-state check still fails this many ms after hold_ms
+             *  expired, force an idle transition anyway. Guards against TUIs that
+             *  show transient UI (pickers, option lists) after the completion
+             *  marker appears, keeping the target-state regex from matching. */
+            force_after_ms?: number;
+        };
+    };
+}