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

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

@@ -0,0 +1,282 @@
+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;
+    message_filter?: {
+        where: string;
+    };
+    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;
+    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;
+    kind?: string;
+}
+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;
+        };
+    };
+}

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;

package/dist/providers/types/interactive-prompt.d.ts

@@ -0,0 +1,48 @@
+export interface InteractivePrompt {
+    promptId: string;
+    origin: 'cli' | 'mcp' | 'agent';
+    providerType: string;
+    createdAt: number;
+    questions: InteractiveQuestion[];
+}
+export interface InteractiveQuestion {
+    questionId: string;
+    question: string;
+    header?: string;
+    multiSelect: boolean;
+    options: InteractiveOption[];
+    allowFreeform?: boolean;
+}
+export interface InteractiveOption {
+    label: string;
+    description?: string;
+    preview?: string;
+}
+export interface InteractivePromptResponse {
+    promptId: string;
+    answers: Record<string, InteractiveAnswer>;
+}
+export interface InteractiveAnswer {
+    selectedLabels: string[];
+    freeformText?: string;
+}
+export declare function normalizeInteractivePrompt(raw: unknown): InteractivePrompt | null;
+export declare function normalizeInteractivePromptResponse(raw: unknown): InteractivePromptResponse;
+export declare function buildClaudeInteractiveToolResult(response: InteractivePromptResponse): string;
+export interface ClaudeInteractiveTuiPage {
+    screenText: string;
+    header?: string;
+}
+export declare function detectClaudeAskUserQuestionPromptFromTuiPages(pages: ClaudeInteractiveTuiPage[], options: {
+    promptId: string;
+    providerType?: string;
+    createdAt?: number;
+}): InteractivePrompt | null;
+export declare function buildClaudeInteractiveTuiAnswerSteps(prompt: InteractivePrompt, response: InteractivePromptResponse): string[];
+export declare function interactivePromptFromClaudeAskUserQuestion(input: unknown, options: {
+    promptId: string;
+    providerType: string;
+    createdAt?: number;
+    origin?: InteractivePrompt['origin'];
+}): InteractivePrompt | null;
+export declare function detectClaudeAskUserQuestionPromptFromJson(value: unknown, providerType?: string): InteractivePrompt | null;