@adhdev/daemon-core 0.9.82-rc.46 → 0.9.82-rc.460

package/dist/providers/sdk/v1/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Provider SDK — v1 surface.
+ *
+ * Internal consumers (daemon-core) import directly from here.
+ * External consumers (provider authors) import from the npm package
+ * `@adhdev/provider-types` (Apache 2.0), which is extracted from this
+ * source at build time.
+ */
+export * from './types/cli/index.js';
+export * from './types/common/index.js';
+export { buildDetectStatusFromTui, type DetectStatusTuiSpec, } from './builders/cli/detect-status.js';
+export { buildParseApprovalFromTui, type ModalTuiSpec, } from './builders/cli/parse-approval.js';
+export { applyVisibleRegion, type VisibleRegionSpec, } from './builders/cli/visible-region.js';
+export { buildParseApprovalFromSquash, compactText, type ApprovalSquashSpec, } from './builders/cli/parse-approval-squash.js';
+export { buildParseSessionFromTui, normalizeMessageIdentity, type ParseSessionTuiSpec, type TranscriptPtySpec, type SessionIdExtractionSpec, type SynthesizedMessage, type SynthesizedSession, } from './builders/cli/parse-session.js';
+export { buildDetectStatusFromAcp, type AcpSessionSpec, type AcpStatusInput, type AcpDetectedStatus, } from './builders/acp/detect-status.js';
+export { loadFixtureExpected, replayFixture, formatReplayReport, type FixtureExpected, type FixtureAnchor, type MessageShape, type AnchorReplayResult, type FixtureReplayResult, type CliProviderHandlers, type ReplayOptions, } from './fixture-tooling/index.js';
+export { analyzeOverrideTaint, formatTaintResult, type TaintLevel, type TaintCategory, type TaintFinding, type TaintResult, validateCliProviderManifest, formatManifestValidationIssues, type ManifestValidationIssue, type ManifestValidationResult, } from './validators/index.js';
+export declare const V1_PRIMITIVE_CATALOG: Readonly<{
+    readonly acp: readonly ["adhdev:acp/session-protocol@1"];
+    readonly tui: readonly ["adhdev:tui/prompt-marker@1", "adhdev:tui/spinner@1", "adhdev:tui/settled-prompt@1", "adhdev:tui/assistant-block@1", "adhdev:tui/tool-block@1", "adhdev:tui/thinking-block@1", "adhdev:tui/user-echo@1", "adhdev:tui/modal@1", "adhdev:tui/modal-as-message@1", "adhdev:tui/footer-chrome@1", "adhdev:tui/welcome-screen@1", "adhdev:tui/visible-region@1", "adhdev:tui/cue-ordering@1", "adhdev:tui/dispatch-order@1", "adhdev:tui/index-finder@1", "adhdev:tui/status-downgrade@1", "adhdev:tui/approval-stitching@1", "adhdev:tui/approval-squash@1", "adhdev:tui/media-input@1", "adhdev:tui/session-id-extraction@1", "adhdev:tui/error-detection@1"];
+    readonly nativeHistory: readonly ["adhdev:native-history/codex-rollout@1", "adhdev:native-history/claude-jsonl@1", "adhdev:native-history/anthropic-cli-transcript@1", "adhdev:native-history/hermes-session@1"];
+    readonly cliCapability: readonly ["adhdev:cli/capability-list@1", "adhdev:cli/control-state@1", "adhdev:cli/capability-action@1", "adhdev:cli/control-toggle@1", "adhdev:cli/picker-open@1", "adhdev:cli/picker-set@1"];
+    readonly common: readonly ["adhdev:common/setting-boolean@1", "adhdev:common/setting-number@1", "adhdev:common/setting-string@1", "adhdev:common/setting-select@1", "adhdev:common/capability-input@1", "adhdev:common/capability-output@1", "adhdev:common/capability-controls@1", "adhdev:common/auth-env-var@1", "adhdev:common/auth-cli-command@1", "adhdev:common/spawn@1", "adhdev:common/timeouts@1", "adhdev:common/resume@1", "adhdev:common/mesh-coordinator@1"];
+    readonly override: readonly ["adhdev:override/cli-parse-session@1", "adhdev:override/cli-detect-status@1", "adhdev:override/cli-parse-approval@1", "adhdev:override/cli-parse-output@1", "adhdev:override/cli-read-native-history@1", "adhdev:override/cli-list-native-history@1", "adhdev:override/cli-capability-handler@1"];
+}>;
+/** Aggregate flat list — for provider catalog endpoints. */
+export declare const V1_ALL_PRIMITIVES: ReadonlyArray<string>;
+/** Catalog version label exposed at `registry.adhf.dev/primitives`. */
+export declare const V1_CONTRACT_VERSION: "1.0.0";

package/dist/providers/sdk/v1/sandbox/README-design.d.ts

@@ -0,0 +1,193 @@
+/**
+ * @file README-design.ts
+ * @description Phase 5 Sandbox Design Document
+ *
+ * This file is a design document written as TypeScript JSDoc/comments.
+ * It is NOT executable — it exists to communicate the sandboxing architecture
+ * to future implementors, reviewers, and delegated agents.
+ *
+ * =============================================================================
+ * CONTEXT: EXTENDED-LEGACY PROVIDER SCRIPT EXECUTION (PRE-PHASE-5)
+ * =============================================================================
+ *
+ * "Extended-legacy" providers (e.g. hermes-cli, and any provider using the
+ * `compatibility` script format) supply JavaScript override scripts that the
+ * daemon loads and calls directly via Node.js `require()`:
+ *
+ *   provider-loader.ts → require(scriptsPath)           // load
+ *   cli-script-runner.ts → this.invoke(fn, input)       // call at runtime
+ *
+ * The loaded module exports plain JS functions (detectStatus, parseApproval,
+ * parseSession, etc.). These functions run **in the daemon process with full
+ * Node.js access** — no memory cap, no CPU limit, full `require`, `fs`, `net`.
+ *
+ * The `extended-legacy` label refers to providers that still use the JS-function
+ * override layer rather than the pure-declarative `tui` manifest block. The
+ * claude-cli provider (scripts/v1/detect_status.js) is the canonical example of
+ * this pattern: it delegates to `sdk.declarativeDetectStatus` for the raw verdict
+ * but adds a stateful generating-hold on top that cannot be expressed declaratively.
+ *
+ * =============================================================================
+ * PHASE 5 GOAL: isolated-vm SANDBOXING
+ * =============================================================================
+ *
+ * Phase 5 wraps each script call in an isolated-vm context so that:
+ *
+ *   1. CPU time is capped per call (default 50 ms hard limit).
+ *   2. Memory is capped per Isolate (default 32 MB heap limit).
+ *   3. The script cannot reach back into the daemon process — no `require`,
+ *      no `import`, no Node.js built-ins (fs, net, child_process, etc.).
+ *   4. Execution errors and timeouts are caught and surfaced cleanly instead
+ *      of propagating exceptions that could crash the daemon parse loop.
+ *
+ * =============================================================================
+ * SANDBOX EXECUTION MODEL
+ * =============================================================================
+ *
+ * Each call to SandboxedScriptRunner.run() creates a **fresh evaluation context**
+ * inside the Isolate. Persistent state across calls (e.g. the `state` object in
+ * detectStatus) is cloned in/out of the sandbox via structured serialization.
+ *
+ * Flow per call:
+ *
+ *   1. Serialize `context` (input + state) into a plain JSON-safe value.
+ *   2. Create a new isolated-vm Context from the shared Isolate.
+ *   3. Inject allowed globals (see below) into the context.
+ *   4. Compile + run the script string with `cpuTimeLimitMs` enforced.
+ *   5. Deserialize and return the result.
+ *   6. Discard the Context (short-lived).
+ *
+ * The Isolate itself is reused across calls so that the V8 JIT and snapshot
+ * warm-up cost is paid once per runner instance, not per call.
+ *
+ * Memory limit (32 MB) applies to the Isolate heap. If a script allocates
+ * beyond the limit, isolated-vm throws RangeError: Array buffer allocation
+ * failed (or similar). The runner catches this and returns an error signal.
+ *
+ * CPU time limit (50 ms) is a wall-clock limit on the script execution tick
+ * measured by isolated-vm's internal timer. Async operations inside the script
+ * are not permitted (the context is synchronous-only).
+ *
+ * =============================================================================
+ * ALLOWED API SURFACE (what scripts CAN use)
+ * =============================================================================
+ *
+ * The following globals are explicitly injected into the sandbox context:
+ *
+ *   - `input`        — the calling frame's input object (CliStatusInput, etc.)
+ *   - `sdk`          — a controlled facade object; see sdk shape below
+ *   - `console.log`  — redirected to daemon LOG.debug; console.error/warn also
+ *                      allowed but routed to LOG.warn
+ *   - `JSON`         — standard JSON object (parse + stringify)
+ *   - `Math`         — standard Math object
+ *   - `Date`         — Date constructor (read-only; no timers)
+ *   - `String`, `Number`, `Boolean`, `Array`, `Object`, `RegExp`
+ *                    — standard constructors
+ *   - `undefined`, `null`, `NaN`, `Infinity`, `parseInt`, `parseFloat`,
+ *     `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`
+ *
+ * sdk shape injected into the sandbox:
+ *
+ *   sdk.declarativeDetectStatus(input) → string
+ *     Calls the daemon-built declarative verdict function. The implementation
+ *     serializes the call, executes the declarative function in daemon-land,
+ *     and returns the result string into the sandbox.
+ *
+ *   sdk.tailHasPrimitive(input, primitive) → boolean
+ *     Returns true if the screen tail contains the named TUI primitive token.
+ *
+ *   sdk.state (object | null)
+ *     The per-session state object returned by createState(). Mutable inside
+ *     the script; mutations are copied back after the call completes.
+ *
+ * =============================================================================
+ * FORBIDDEN API SURFACE (what scripts CANNOT use)
+ * =============================================================================
+ *
+ * The sandbox provides NO access to:
+ *
+ *   - `require` / `import` / `module` / `exports` / `__dirname` / `__filename`
+ *   - `process` (no env, no exit, no stdio)
+ *   - `fs`, `path`, `os`, `net`, `http`, `https`, `child_process`, `worker_threads`
+ *   - `setTimeout`, `setInterval`, `setImmediate`, `clearTimeout`, `clearInterval`
+ *     (async scheduling is blocked; scripts must be synchronous)
+ *   - `Promise`, `async/await` (not injected; async resolution is disallowed)
+ *   - `WebAssembly` (not injected)
+ *   - `Buffer`, `TextEncoder`, `TextDecoder` (not injected by default; can be
+ *     added to allowedGlobals if a specific script family requires them)
+ *   - Any daemon-internal module, class, or singleton
+ *
+ * =============================================================================
+ * MIGRATION PATH FOR HERMES-CLI (when Phase 5 lands)
+ * =============================================================================
+ *
+ * hermes-cli (adhdev-providers/cli/hermes-cli) uses the `compatibility` script
+ * format with `defaultScriptDir: "scripts/1.0"`. Its scripts are loaded via
+ * require() in provider-loader.ts → loadScriptsFromDir() and called via
+ * CliScriptRunner.invoke().
+ *
+ * Phase 5 migration steps:
+ *
+ *   1. The ProviderLoader detects at load time whether a provider's scriptDir
+ *      uses the extended-legacy JS override layer (i.e. scripts.js exports
+ *      function(s) rather than a pure-declarative object).
+ *
+ *   2. For extended-legacy providers, instead of storing the raw Function
+ *      references in `normalizedProvider.scripts`, the loader stores the
+ *      **script source strings** alongside a flag `sandboxed: true`.
+ *
+ *   3. CliScriptRunner is extended with an optional SandboxedScriptRunner
+ *      member. When present, invoke() routes script calls through the sandbox
+ *      instead of calling the function directly.
+ *
+ *   4. hermes-cli's scripts/1.0/scripts.js is updated (or a scripts/2.0/ dir
+ *      created) with source strings compatible with the allowed API surface.
+ *      In particular:
+ *        - `require` calls must be removed.
+ *        - Any direct Node.js module access must be replaced with sdk equivalents.
+ *
+ *   5. The daemon's dev server (port 19280) exposes a /sandbox/test endpoint
+ *      that accepts a script source string + input and returns the sandboxed
+ *      result — useful for provider authors to iterate without restarting.
+ *
+ *   6. Fallback: providers that have not been migrated to the sandbox API still
+ *      run via DirectEvalRunner (see script-runner.ts) — unsafe but compatible,
+ *      with a visible deprecation warning in the daemon log.
+ *
+ * =============================================================================
+ * SandboxedScriptRunner INTERFACE (to be satisfied by the Phase 5 implementation)
+ * =============================================================================
+ *
+ * The interface defined in script-runner.ts must be satisfied by two
+ * implementations:
+ *
+ *   DirectEvalRunner   — no-op stub; runs script via eval() in a try/catch.
+ *                        Used when isolated-vm is not installed or when
+ *                        sandboxing is explicitly disabled for development.
+ *                        Logs a warning on first use.
+ *                        Safe to use in tests (no native dependency).
+ *
+ *   IsolatedVmRunner   — full implementation using the `isolated-vm` npm package.
+ *                        Created by createScriptRunner() when isolated-vm is
+ *                        importable. Not committed to the OSS package — loaded
+ *                        dynamically at runtime.
+ *
+ * Factory function createScriptRunner(options?) returns:
+ *   - IsolatedVmRunner if `require('isolated-vm')` succeeds
+ *   - DirectEvalRunner otherwise, with a LOG.warn() deprecation notice
+ *
+ * =============================================================================
+ * FILE LAYOUT (Phase 5 deliverables under this directory)
+ * =============================================================================
+ *
+ *   sandbox/
+ *     README-design.ts          ← this file (design document)
+ *     script-runner.ts          ← SandboxedScriptRunner interface + DirectEvalRunner stub
+ *     isolated-vm-runner.ts     ← IsolatedVmRunner (Phase 5 full impl, not yet committed)
+ *
+ *   Related files that will be touched in Phase 5:
+ *     cli-adapters/cli-script-runner.ts     ← add optional SandboxedScriptRunner member
+ *     providers/provider-loader.ts          ← detect extended-legacy, store source strings
+ *     providers/cli-provider-instance.ts    ← TODO comment (already added in Phase 4 scaffold)
+ */
+export {};

package/dist/providers/sdk/v1/sandbox/require-whitelist.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Provider script require() whitelist.
+ *
+ * Provider scripts (detect_status.js, parse_session.js, the override layer
+ * the v1 contract exposes, plus their _shared helpers) execute in the
+ * daemon process with full Node access — see sandbox/README-design.ts for
+ * the long story. Full isolation via isolated-vm has a real perf cost and
+ * a real marshalling-complexity cost, so we instead constrain the most
+ * dangerous attack surface: what a provider script can `require()`.
+ *
+ * The hook wraps Node's CJS `Module._load` and, when the calling file is
+ * inside a directory that this loader has registered as a provider script
+ * root, blocks every module that isn't on the allowlist below. Relative
+ * paths are allowed but only when they resolve back inside the same
+ * provider root — providers can require their sibling helpers but they
+ * can't reach `../../../../etc/passwd` through a clever segment.
+ *
+ * The hook installs exactly once per process; subsequent `register()` /
+ * `unregister()` calls just adjust the set of roots that are gated.
+ *
+ * Performance: the hook adds one `path.normalize` + one Set lookup to
+ * every require call coming from a registered root. At the measured
+ * baseline (~6 script invocations / second / session, each making
+ * ≤1 require during initial module evaluation, zero during steady-state
+ * calls), this is unmeasurable.
+ */
+/**
+ * Wrap `globalThis.process` methods so calls from provider script stacks
+ * throw, while every other caller (daemon-core itself, npm deps, the test
+ * harness) goes through untouched.
+ *
+ * Trade-off: this is a stack-introspection check on every call to the
+ * affected methods. The methods in question (exit/kill/abort/binding/dlopen)
+ * are not hot paths — they're either never called or called once at
+ * shutdown. The cost is negligible.
+ *
+ * Alternative considered: wrap only the module-scope `process` binding via
+ * Module._extensions. Node's ESM/CJS semantics make this unreliable across
+ * dynamic-require paths. Stack introspection is uglier but correct.
+ *
+ * Caveat: a provider script that grabs `globalThis.process.exit` once and
+ * passes the reference to a non-provider callback can still escape — the
+ * stack at the actual call site no longer goes through provider code. We
+ * accept this gap; the threat model assumes scripts are not actively
+ * trying to launder calls through arbitrary daemon callbacks, just that
+ * a naive `process.exit(0)` should not silently terminate the daemon.
+ */
+export declare function installProviderProcessShim(): void;
+/** For tests — restore the original process.* methods. */
+export declare function _uninstallProviderProcessShimForTest(): void;
+/**
+ * Register a directory whose `.js` files should be subject to the
+ * whitelist when they call require(). Idempotent — repeated registration
+ * of the same root is a no-op. Pass the same string back to
+ * `unregisterProviderScriptRoot` to remove it.
+ */
+export declare function registerProviderScriptRoot(absRoot: string): void;
+/** Inverse of registerProviderScriptRoot. */
+export declare function unregisterProviderScriptRoot(absRoot: string): void;
+/** For tests — drop every registration and reset internal state. */
+export declare function _resetProviderScriptRoots(): void;
+/** For tests — peek at the gated root list. */
+export declare function _getRegisteredRoots(): readonly string[];
+/**
+ * Public re-exports — registry consumers want to know what's on the
+ * allowlist without parsing this file.
+ */
+export declare const PROVIDER_REQUIRE_POLICY: Readonly<{
+    safeStdlib: string[];
+    shimmedStdlib: string[];
+    fsAllowedMembers: ("existsSync" | "statSync" | "lstatSync" | "realpathSync" | "readFileSync" | "readdirSync" | "readlinkSync" | "accessSync" | "constants" | "exists" | "stat" | "lstat" | "realpath" | "readFile" | "readdir" | "readlink" | "access" | "promises")[];
+    childProcessAllowedMembers: string[];
+    processDeniedMembers: string[];
+}>;

package/dist/providers/sdk/v1/sandbox/script-runner.d.ts

@@ -0,0 +1,98 @@
+/**
+ * script-runner.ts — SandboxedScriptRunner interface + DirectEvalRunner stub
+ *
+ * Phase 5 scaffold: defines the interface that the isolated-vm implementation
+ * will satisfy, and provides a DirectEvalRunner that keeps providers working
+ * without the native isolated-vm package.
+ *
+ * See README-design.ts for the full design rationale.
+ */
+/** Options controlling the resource limits applied to a sandboxed script call. */
+export interface SandboxOptions {
+    /** Maximum CPU time (wall-clock) in milliseconds before the script is killed. Default: 50. */
+    cpuTimeLimitMs: number;
+    /** Maximum V8 heap size in megabytes for the Isolate. Default: 32. */
+    memoryLimitMb: number;
+    /**
+     * Whitelist of global names the script may access.
+     * The full allowed surface is documented in README-design.ts.
+     * Default: ['console', 'JSON', 'Math', 'Date', 'String', 'Number', 'Boolean',
+     *           'Array', 'Object', 'RegExp']
+     */
+    allowedGlobals: string[];
+}
+/** Default resource limits applied when no options are supplied. */
+export declare const DEFAULT_SANDBOX_OPTIONS: SandboxOptions;
+/**
+ * Contract for sandboxed script execution.
+ *
+ * Implementations:
+ *   - DirectEvalRunner  — no-op stub; uses eval() with a try/catch (unsafe, no limits).
+ *   - IsolatedVmRunner  — Phase 5 full implementation using the `isolated-vm` package.
+ *
+ * Usage:
+ *   const runner = createScriptRunner({ cpuTimeLimitMs: 50, memoryLimitMb: 32 });
+ *   const result = await runner.run(scriptSource, { input, sdk });
+ *   runner.dispose();
+ */
+export interface SandboxedScriptRunner {
+    /**
+     * Execute `script` synchronously inside a sandboxed context.
+     *
+     * @param script   JavaScript source string. The script body should
+     *                 evaluate to the desired return value (the last expression
+     *                 is returned, module.exports is NOT consulted).
+     *                 Example: `"input.tail.includes('✓') ? 'idle' : 'generating'"`
+     *
+     * @param context  Plain key/value pairs injected as globals inside the
+     *                 sandbox. All values must be JSON-serializable.
+     *                 Typically: `{ input: <CliStatusInput>, sdk: <sdk facade> }`
+     *
+     * @param options  Optional per-call overrides for resource limits.
+     *                 Merged with the options supplied to createScriptRunner().
+     *
+     * @returns        The value produced by the script (JSON-deserialized from
+     *                 the sandbox). May be `unknown` — callers must validate.
+     *
+     * @throws         Re-throws if the script contains a syntax error.
+     *                 Returns `undefined` (via rejection) on timeout or OOM.
+     */
+    run(script: string, context: Record<string, unknown>, options?: Partial<SandboxOptions>): Promise<unknown>;
+    /**
+     * Release all resources held by this runner (Isolate, Contexts, etc.).
+     * After dispose(), calling run() has undefined behavior.
+     */
+    dispose(): void;
+}
+/**
+ * No-op stub used when isolated-vm is not available (graceful degradation).
+ *
+ * Falls back to direct `eval()` inside a try/catch — there are no CPU or
+ * memory limits. A warning is logged on the first run() call to make the
+ * fallback visible in daemon logs.
+ *
+ * This implementation is suitable for:
+ *   - Development environments where isolated-vm is not installed.
+ *   - Unit tests (no native dependency required).
+ *   - Graceful fallback for existing extended-legacy providers while Phase 5
+ *     is being rolled out.
+ *
+ * NOT suitable for production use with untrusted script sources.
+ */
+export declare class DirectEvalRunner implements SandboxedScriptRunner {
+    private warned;
+    private readonly defaultOptions;
+    constructor(options?: Partial<SandboxOptions>);
+    run(script: string, context: Record<string, unknown>, _options?: Partial<SandboxOptions>): Promise<unknown>;
+    dispose(): void;
+}
+/**
+ * Factory: returns IsolatedVmRunner if isolated-vm is installed, else DirectEvalRunner.
+ *
+ * Logs a warning when falling back to DirectEvalRunner so the operator is aware
+ * that sandboxing is inactive.
+ *
+ * @param options  Resource limit defaults applied to every run() call unless
+ *                 overridden at the call site. Merged with DEFAULT_SANDBOX_OPTIONS.
+ */
+export declare function createScriptRunner(options?: Partial<SandboxOptions>): SandboxedScriptRunner;

package/dist/providers/sdk/v1/types/cli/index.d.ts

@@ -0,0 +1,277 @@
+/**
+ * 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';
+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[];
+}
+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;
+}
+export interface CliApprovalModal {
+    message: string;
+    /** Raw button labels as the user sees them. Do not rewrite. */
+    buttons: string[];
+}
+/**
+ * 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;
+}
+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>;
+}
+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;
+export interface CliCapabilityHandlerResult {
+    ok?: boolean;
+    writeRaw?: string;
+    sendMessage?: string;
+    result?: unknown;
+}
+export type CliCapabilityHandlerFn<S = unknown> = (state: S | undefined, input: CliScriptInput) => CliCapabilityHandlerResult;
+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[];
+};
+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;
+export interface CliPatternEntry {
+    source: string;
+    flags?: string;
+}
+export interface CliPatternsDef {
+    prompt?: CliPatternEntry[];
+    generating?: CliPatternEntry[];
+    approval?: CliPatternEntry[];
+    ready?: CliPatternEntry[];
+    dialog?: CliPatternEntry[];
+}
+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>;
+}