@adhdev/daemon-core 0.9.82-rc.15 → 0.9.82-rc.151

package/src/providers/sdk/v1/schemas/primitives/tui-spinner-v1.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/spinner@1",
+  "title": "tui/spinner — v1",
+  "description": "Declares which patterns in the PTY/screen text indicate the agent is actively generating. The daemon's status state machine fires `generating` when any pattern matches inside the configured scope window. Codex's `Working (8m 56s • esc to interrupt)`, Claude's braille spinner, and Antigravity's `Thinking…` are all expressible with this primitive.",
+  "type": "object",
+  "required": ["$schema", "patterns"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "const": "adhdev:tui/spinner@1"
+    },
+    "patterns": {
+      "type": "array",
+      "minItems": 1,
+      "description": "List of patterns. Any match within the scope window classifies the screen as generating.",
+      "items": {
+        "type": "object",
+        "required": ["regex"],
+        "additionalProperties": false,
+        "properties": {
+          "regex": {
+            "type": "string",
+            "description": "ECMAScript regex source. Daemon compiles with the flags below."
+          },
+          "flags": {
+            "type": "string",
+            "pattern": "^[gimsuy]*$",
+            "default": "i"
+          },
+          "description": {
+            "type": "string",
+            "description": "Author-facing note explaining when this pattern fires."
+          }
+        }
+      }
+    },
+    "scope": {
+      "description": "Where in the text the patterns are searched. Defaults to `live-frame-tail` which mirrors the safest production behaviour (avoids matching scrollback or earlier turns).",
+      "default": "live-frame-tail",
+      "oneOf": [
+        {
+          "const": "live-frame-tail",
+          "title": "Live frame tail",
+          "description": "Last N lines of the visible screen, where N is `scopeWindowLines` (default 8). Recommended for most providers."
+        },
+        {
+          "const": "whole-screen",
+          "title": "Whole screen",
+          "description": "Match anywhere in the current screen text. Use with caution; tends to false-positive on scrollback."
+        },
+        {
+          "const": "recent-buffer",
+          "title": "Recent buffer",
+          "description": "Last ~1000 chars of accumulated buffer. Useful when the spinner is in raw byte stream but not in the rendered screen yet."
+        }
+      ]
+    },
+    "scopeWindowLines": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 64,
+      "default": 8,
+      "description": "Number of trailing lines considered the live frame when scope is `live-frame-tail`."
+    }
+  },
+  "examples": [
+    {
+      "$schema": "adhdev:tui/spinner@1",
+      "patterns": [
+        { "regex": "(?:Thinking|Working) \\([0-9hms\\s]+", "flags": "i", "description": "Codex/Claude elapsed-time spinner" },
+        { "regex": "esc to (?:cancel|interrupt|stop)", "flags": "i" }
+      ]
+    },
+    {
+      "$schema": "adhdev:tui/spinner@1",
+      "scope": "whole-screen",
+      "patterns": [
+        { "regex": "[⠁-⣿]", "description": "Braille spinner glyphs" }
+      ]
+    }
+  ]
+}

package/src/providers/sdk/v1/schemas/primitives/tui-transcript-pty-v1.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/transcript-pty@1",
+  "title": "TUI transcript extraction (PTY screen)",
+  "description": "Declarative rules for extracting user/assistant/tool messages from a PTY screen buffer. Composed with detect-status + parse-approval to yield a full parseSession output without provider-specific JavaScript.\n\nThe extraction model: each line in the screen is classified as one of {assistant, user, tool, chrome, continuation}. Adjacent lines of the same role (or marked as continuations) get grouped into a single message. Chrome lines are skipped.\n\nWith just this primitive declared, a verified/declarative-only provider can produce a working transcript from PTY output alone, no parse_output.js required.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["assistantPrefix"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/transcript-pty@1" },
+    "assistantPrefix": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["regex"],
+      "description": "Regex that matches the leading character/string of an assistant message line. Capture group 1 is the rest of the line (the message content for this line). Examples: Claude `^[⏺]\\s+(.*)$`, Codex `^>\\s+(.*)$`.",
+      "properties": {
+        "regex": { "type": "string" },
+        "flags": { "type": "string", "default": "" }
+      }
+    },
+    "userPrefix": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["regex"],
+      "description": "Optional: regex that matches the user's submitted prompt line on screen (post-echo). When omitted, user messages are tracked via input echo correlation only.",
+      "properties": {
+        "regex": { "type": "string" },
+        "flags": { "type": "string", "default": "" }
+      }
+    },
+    "toolPrefix": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["regex"],
+      "description": "Optional: regex that matches lines emitted by tool calls. By default these are surfaced as `kind: 'tool'` messages. Examples: Claude `^[⎿]\\s+(.*)$`, Codex `^[•]\\s+(.*)$`.",
+      "properties": {
+        "regex": { "type": "string" },
+        "flags": { "type": "string", "default": "" },
+        "skip": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, tool lines are silently dropped from the transcript instead of being emitted as `kind: 'tool'` messages."
+        }
+      }
+    },
+    "continuationLine": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How to recognize continuation lines (no prefix) that belong to the previous message. Default rule: any non-empty line that is not chrome and has no role prefix continues the previous message.",
+      "properties": {
+        "indented": {
+          "type": "boolean",
+          "default": false,
+          "description": "When true, only lines starting with whitespace are continuation lines. When false (default), any unprefixed non-chrome non-empty line is a continuation."
+        }
+      }
+    },
+    "chromePatterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["regex"],
+        "properties": {
+          "regex": { "type": "string" },
+          "flags": { "type": "string", "default": "" },
+          "label": { "type": "string" }
+        }
+      },
+      "description": "Lines matching any of these regexes are treated as chrome and excluded from messages. Use this for shell prompts, footer hints, copyright banners, etc."
+    },
+    "stripLeadingChrome": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true, leading welcome/banner lines (before the first user or assistant prefix is seen) are dropped."
+    },
+    "scope": {
+      "enum": ["screen", "buffer", "tail"],
+      "default": "buffer",
+      "description": "Which input field to parse: rendered screen text, full buffer (default), or tail string. Most providers use buffer because the screen alone loses scrollback."
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-visible-region-v1.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/visible-region@1",
+  "title": "TUI visible region",
+  "description": "Defines which portion of the rendered terminal screen counts as 'visible' for detectStatus / parseApproval / parseSession dispatch. Used to scope matchers away from off-screen scrollback or header chrome. Without a visible-region declaration, daemon falls back to the entire accumulator buffer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scope"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/visible-region@1" },
+    "scope": {
+      "enum": ["screen", "tail", "buffer", "between-anchors"],
+      "description": "screen=current rendered viewport, tail=last N chars, buffer=full accumulated buffer, between-anchors=between most recent top/bottom anchor lines."
+    },
+    "tailChars": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 4000,
+      "description": "Used when scope=tail."
+    },
+    "anchors": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Used when scope=between-anchors.",
+      "properties": {
+        "top": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pattern"],
+          "properties": {
+            "pattern": { "type": "string" },
+            "flags": { "type": "string" }
+          }
+        },
+        "bottom": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["pattern"],
+          "properties": {
+            "pattern": { "type": "string" },
+            "flags": { "type": "string" }
+          }
+        }
+      }
+    },
+    "selectAnchor": {
+      "enum": ["first", "last"],
+      "default": "first",
+      "description": "When multiple matches exist for the anchor pair, pick the first or last. Antigravity uses `last` to anchor on the most recent prompt separator and exclude scrollback above it; codex's similar pattern also benefits from `last`."
+    },
+    "stripCues": {
+      "type": "array",
+      "description": "Optional list of primitive $ids whose matches should be masked out of the visible region before downstream dispatch. Common: footer-chrome, welcome-screen.",
+      "items": { "type": "string" }
+    }
+  }
+}

package/src/providers/sdk/v1/schemas/primitives/tui-welcome-screen-v1.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:tui/welcome-screen@1",
+  "title": "TUI welcome screen",
+  "description": "Declares cues that identify the cold-start welcome / splash region of a CLI agent. Daemon uses this to suppress assistant-block / message extraction during the boot phase, so the splash banner is not turned into a fake assistant message.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["cues"],
+  "properties": {
+    "$schema": { "const": "adhdev:tui/welcome-screen@1" },
+    "cues": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["pattern"],
+        "properties": {
+          "pattern": { "type": "string" },
+          "flags": { "type": "string" }
+        }
+      }
+    },
+    "dismissAfter": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "How the welcome state ends. Default: first prompt-marker sighting.",
+      "properties": {
+        "onPromptMarker": { "type": "boolean", "default": true },
+        "onUserEcho": { "type": "boolean", "default": true },
+        "onAssistantBlock": { "type": "boolean", "default": false }
+      }
+    }
+  }
+}

package/src/providers/sdk/v1/types/cli/index.ts

@@ -0,0 +1,365 @@
+/**
+ * CLI provider types — v1.
+ *
+ * Mirrors the contract documented in
+ * adhdev-providers/docs/provider-contract/cli/v1.md.
+ *
+ * Extracted at build time into the Apache 2.0 npm package
+ * `@adhdev/provider-types`.
+ */
+
+import type {
+  SettingsDef,
+  CapabilitiesDef,
+  SpawnDef,
+  TimeoutsDef,
+  ResumeDef,
+  MeshCoordinatorDef,
+  CompatibilityEntryDef,
+  ControlDef,
+  ProviderLifecycleStatus,
+} from '../common/index.js';
+
+// ─── Screen snapshot types — used by all handlers ───────────────────────
+
+export interface CliScreenLine {
+  text: string;
+  /** Number of visible columns the line occupies. */
+  width: number;
+}
+
+export interface CliScreenSnapshot {
+  text: string;
+  lineCount: number;
+  lines: CliScreenLine[];
+  nonEmptyLines: CliScreenLine[];
+  firstNonEmptyLineIndex: number;
+  lastNonEmptyLineIndex: number;
+  firstNonEmptyLine: CliScreenLine | null;
+  lastNonEmptyLine: CliScreenLine | null;
+  promptLineIndex: number;
+  promptLine: CliScreenLine | null;
+  linesAbovePrompt: CliScreenLine[];
+  linesBelowPrompt: CliScreenLine[];
+}
+
+// ─── Chat message — output shape from parseSession.messages ────────────
+
+export type CliChatRole = 'user' | 'assistant' | 'system' | 'tool';
+export type CliChatKind = 'standard' | 'tool' | 'thinking' | 'system';
+export type CliBubbleState = 'visible' | 'collapsed' | 'hidden';
+
+export interface CliChatMessage {
+  role: CliChatRole;
+  /** Plain string is the common case; rich content (arrays / objects) is permitted but parsing differs by category. */
+  content: string | unknown;
+  timestamp?: number;
+  receivedAt?: number;
+  kind?: CliChatKind | string;
+  /** Stable id from the agent's native history when available. */
+  id?: string;
+  /** Display index, can drift. Prefer `providerUnitKey` for stable identity. */
+  index?: number;
+  /**
+   * Stable per-message identity used by ChatSourceMachine to compare native
+   * vs PTY transcripts. When the provider supports native history, this
+   * should be derivable from the on-disk session-id + turn-number.
+   */
+  providerUnitKey?: string;
+  bubbleId?: string;
+  bubbleState?: CliBubbleState;
+  senderName?: string;
+  meta?: Record<string, unknown>;
+  /** Provider-specific extensions are permitted; daemon ignores unknown keys. */
+  [extra: string]: unknown;
+}
+
+// ─── Approval modal ────────────────────────────────────────────────────
+
+export interface CliApprovalModal {
+  message: string;
+  /** Raw button labels as the user sees them. Do not rewrite. */
+  buttons: string[];
+}
+
+// ─── Inputs ────────────────────────────────────────────────────────────
+
+/**
+ * Provided to `parseSession` and `parseOutput`. The richest input shape.
+ */
+export interface CliScriptInput {
+  /** Accumulated PTY output, ANSI cleaned. */
+  buffer: string;
+  /** Raw PTY bytes including ANSI sequences. */
+  rawBuffer: string;
+  /** Last ~1000 chars of buffer. */
+  recentBuffer: string;
+  /** The terminal screen as rendered by ghostty/xterm. */
+  screenText: string;
+  workspace?: string;
+  /** Same as workspace; legacy alias. */
+  workingDir?: string;
+  /** Last known provider session id. May be empty. */
+  providerSessionId?: string;
+  /** Alias used for some native-history flows. */
+  historySessionId?: string;
+  screen: CliScreenSnapshot;
+  bufferScreen: CliScreenSnapshot;
+  recentScreen: CliScreenSnapshot;
+  /** Accumulated from previous parse calls. */
+  messages: CliChatMessage[];
+  /** Current in-flight assistant text. */
+  partialResponse: string;
+  isWaitingForResponse?: boolean;
+  /** The user's prompt for the active turn. */
+  promptText?: string;
+  /** Provider settings from ~/.adhdev/config.json. */
+  settings?: Record<string, unknown>;
+  /** Command-specific args (e.g. handler invocation parameters). */
+  args?: Record<string, unknown>;
+  /** ms timestamp of process spawn. Useful for native rollover guards. */
+  spawnAt?: number;
+}
+
+/**
+ * Provided to `detectStatus`. Trimmed for hot-path performance.
+ */
+export interface CliStatusInput {
+  tail: string;
+  screenText?: string;
+  rawBuffer?: string;
+  isWaitingForResponse?: boolean;
+  screen: CliScreenSnapshot;
+  tailScreen: CliScreenSnapshot;
+}
+
+/**
+ * Provided to `parseApproval`.
+ */
+export interface CliApprovalInput {
+  buffer: string;
+  screenText?: string;
+  rawBuffer?: string;
+  tail: string;
+  screen: CliScreenSnapshot;
+  bufferScreen: CliScreenSnapshot;
+  tailScreen: CliScreenSnapshot;
+}
+
+// ─── Outputs ───────────────────────────────────────────────────────────
+
+export type CliStatus = 'idle' | 'generating' | 'waiting_approval' | 'starting' | 'error';
+export type CliTranscriptAuthority = 'provider' | 'daemon';
+export type CliTranscriptCoverage = 'full' | 'tail' | 'current-turn';
+
+export interface CliParsedSession {
+  status: CliStatus;
+  messages: CliChatMessage[];
+  modal: CliApprovalModal | null;
+  parsedStatus?: string | null;
+  errorMessage?: string;
+  errorReason?: string;
+  providerSessionId?: string;
+  transcriptAuthority?: CliTranscriptAuthority;
+  coverage?: CliTranscriptCoverage;
+}
+
+export interface CliReadChatPayload {
+  id: 'cli_session' | string;
+  status: CliStatus;
+  title: string;
+  messages: CliChatMessage[];
+  activeModal: CliApprovalModal | null;
+  providerSessionId?: string;
+  transcriptAuthority?: CliTranscriptAuthority;
+  coverage?: CliTranscriptCoverage;
+  controlValues?: Record<string, unknown>;
+}
+
+// ─── Handler function signatures ───────────────────────────────────────
+
+export type CliCreateStateFn<S = Record<string, unknown>> = () => S;
+
+export type CliParseSessionFn<S = unknown> = (
+  state: S | undefined,
+  input: CliScriptInput,
+) => CliParsedSession;
+
+export type CliDetectStatusFn = (
+  input: CliStatusInput,
+) => CliStatus | null;
+
+export type CliParseApprovalFn = (
+  input: CliApprovalInput,
+) => CliApprovalModal | null;
+
+export type CliParseOutputFn<S = unknown> = (
+  state: S | undefined,
+  input: CliScriptInput,
+) => CliReadChatPayload;
+
+// ─── Capability handlers ───────────────────────────────────────────────
+
+export interface CliCapabilityHandlerResult {
+  ok?: boolean;
+  writeRaw?: string;
+  sendMessage?: string;
+  result?: unknown;
+}
+
+export type CliCapabilityHandlerFn<S = unknown> = (
+  state: S | undefined,
+  input: CliScriptInput,
+) => CliCapabilityHandlerResult;
+
+// ─── Native history ────────────────────────────────────────────────────
+
+export interface CliNativeHistoryReadInput {
+  historySessionId?: string;
+  workspace?: string;
+  /** ms timestamp of provider spawn. Use to reject pre-spawn rollovers. */
+  spawnAt?: number;
+}
+
+export interface CliNativeHistoryMessage {
+  role: CliChatRole;
+  content: unknown;
+  kind?: CliChatKind | string;
+  providerUnitKey?: string;
+  receivedAt?: number;
+  workspace?: string;
+  historySessionId?: string;
+}
+
+export interface CliNativeHistoryReadResult {
+  source: 'provider-native';
+  providerSessionId: string;
+  messages: CliNativeHistoryMessage[];
+  sourcePath: string;
+  sourceMtimeMs: number;
+  nativeHistoryCoverage: CliTranscriptCoverage;
+  workspace?: string;
+  unavailableReason?: string;
+}
+
+export type CliReadNativeHistoryFn = (
+  input: CliNativeHistoryReadInput,
+) => CliNativeHistoryReadResult | null;
+
+export interface CliListNativeHistoryEntry {
+  providerSessionId: string;
+  title?: string;
+  workspace?: string;
+  receivedAt?: number;
+  messageCount?: number;
+}
+
+export type CliListNativeHistoryFn = () => {
+  sessions: CliListNativeHistoryEntry[];
+};
+
+// ─── Native history config ─────────────────────────────────────────────
+
+export interface CliNativeHistoryDef {
+  /** Built-in adapter $schema (e.g. "adhdev:native-history/claude-jsonl@1"). */
+  $schema?: string;
+  format: string;
+  watchPath: string;
+  mode: 'native-source' | 'daemon-mirror';
+  contractVersion?: string;
+  scripts?: {
+    readSession?: string;
+    listSessions?: string;
+  };
+}
+
+/**
+ * @deprecated Use {@link CliNativeHistoryDef}. Retained as an alias for one
+ * release so SDK consumers that referenced the v0 name keep compiling.
+ */
+export type CliCanonicalHistoryDef = CliNativeHistoryDef;
+
+// ─── Patterns (legacy fallback detector hints) ─────────────────────────
+
+export interface CliPatternEntry {
+  source: string;
+  flags?: string;
+}
+
+export interface CliPatternsDef {
+  prompt?: CliPatternEntry[];
+  generating?: CliPatternEntry[];
+  approval?: CliPatternEntry[];
+  ready?: CliPatternEntry[];
+  dialog?: CliPatternEntry[];
+}
+
+// ─── Manifest ──────────────────────────────────────────────────────────
+
+export interface CliProviderManifest {
+  /** Identity */
+  type: string;
+  name: string;
+  displayName?: string;
+  category: 'cli';
+  icon?: string;
+  aliases?: ReadonlyArray<string>;
+
+  /** Versioning */
+  engines?: { adhdev?: string };
+  providerVersion?: string;
+  contractVersion?: number | string;
+  status?: ProviderLifecycleStatus;
+  details?: string;
+  disableUpstream?: boolean;
+
+  /** Process spawn */
+  binary: string;
+  versionCommand?: string;
+  spawn: SpawnDef;
+
+  /** Input/output behavior */
+  sendDelayMs?: number;
+  sendKey?: string;
+  submitStrategy?: 'wait_for_echo' | 'immediate';
+  requirePromptEchoBeforeSubmit?: boolean;
+  allowInputDuringGeneration?: boolean;
+  requiresFinalAssistantBeforeIdle?: boolean;
+  augmentStaleSnapshot?: boolean;
+  transcriptAuthority?: CliTranscriptAuthority;
+  transcriptContext?: 'full' | 'tail';
+
+  /** Patterns (legacy fallback) */
+  patterns?: CliPatternsDef;
+
+  /** Approval */
+  approvalKeys?: Readonly<Record<string, string>>;
+  approvalPositiveHints?: ReadonlyArray<string>;
+
+  /** Timeouts */
+  timeouts?: TimeoutsDef;
+
+  /** Resume */
+  resume?: ResumeDef;
+
+  /** Compatibility */
+  compatibility: ReadonlyArray<CompatibilityEntryDef>;
+  defaultScriptDir?: string;
+
+  /** Capabilities advertised to the dashboard */
+  capabilities?: CapabilitiesDef;
+
+  /** Mesh coordinator setup */
+  meshCoordinator?: MeshCoordinatorDef;
+
+  /** Native history (v1 canonical field name) */
+  nativeHistory?: CliNativeHistoryDef;
+  /** @deprecated v0 alias for `nativeHistory`. */
+  canonicalHistory?: CliCanonicalHistoryDef;
+
+  /** Settings (UI toggles persisted to ~/.adhdev/config.json) */
+  settings?: SettingsDef;
+
+  /** Controls (dashboard chips/buttons) */
+  controls?: ReadonlyArray<ControlDef>;
+}