@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.491

package/dist/providers/sdk/v1/builders/cli/parse-approval.d.ts

@@ -0,0 +1,65 @@
+/**
+ * buildParseApprovalFromTui
+ *
+ * Turns a `tui/modal@1` block into a runtime
+ * `(input: CliApprovalInput) => CliApprovalModal | null` function.
+ *
+ * Contract rules enforced (sprint-2026-06):
+ *   - Returns null when the question pattern is not visible.
+ *   - Returns null when the button list is empty or shorter than minButtons.
+ *   - Button labels are raw text; never rewritten (e.g. "Yes, and don't ask
+ *     again for X" stays verbatim).
+ *   - Modal scope respects between-last-two-separators / window-around-question
+ *     / whole-screen to avoid false-positives from numbered lists in
+ *     assistant prose.
+ */
+import type { CliParseApprovalFn } from '../../types/cli/index.js';
+import { type VisibleRegionSpec } from './visible-region.js';
+interface ModalQuestionVariant {
+    regex: string;
+    flags?: string;
+    label?: string;
+}
+interface ModalContextHeader {
+    regex: string;
+    flags?: string;
+}
+export interface ModalTuiSpec {
+    $schema: 'adhdev:tui/modal@1';
+    questionPattern: string;
+    questionFlags?: string;
+    questionVariants?: ModalQuestionVariant[];
+    buttonPattern: string;
+    buttonFlags?: string;
+    buttonLabelGroup?: number;
+    /**
+     * Optional fallback for terminals that render all options on a single line
+     * (e.g. Antigravity feedback survey: `[0] skip [1] yes [2] no [3] still using`).
+     * When per-line button extraction collects fewer than `minButtons`, the
+     * builder makes a second pass with this regex (global match, capture group 1
+     * is the label).
+     */
+    inlineButtonPattern?: string;
+    inlineButtonFlags?: string;
+    scope?: 'between-last-two-separators' | 'window-around-question' | 'whole-screen';
+    scopeWindowLines?: number;
+    contextHeader?: ModalContextHeader;
+    continuationLines?: boolean;
+    minButtons?: number;
+}
+declare function findQuestionLineIndex(spec: ModalTuiSpec, lines: string[]): {
+    index: number;
+    matchedSource: 'primary' | string;
+} | null;
+declare function scopeLines(spec: ModalTuiSpec, lines: string[], questionIndex: number): {
+    start: number;
+    end: number;
+};
+declare function extractButtons(spec: ModalTuiSpec, lines: string[], windowStart: number, windowEnd: number): string[];
+export declare function buildParseApprovalFromTui(spec: ModalTuiSpec, visibleRegion?: VisibleRegionSpec): CliParseApprovalFn;
+export declare const __internal: {
+    findQuestionLineIndex: typeof findQuestionLineIndex;
+    scopeLines: typeof scopeLines;
+    extractButtons: typeof extractButtons;
+};
+export {};

package/dist/providers/sdk/v1/builders/cli/parse-session.d.ts

@@ -0,0 +1,91 @@
+/**
+ * buildParseSessionFromTui — synthesize a parseSession function from the
+ * manifest tui block alone.
+ *
+ * Composition:
+ *   1. detectStatus from tui.spinner/modal/settledPrompt/dispatchOrder
+ *      (delegated to buildDetectStatusFromTui)
+ *   2. parseApproval from tui.modal (delegated to buildParseApprovalFromTui)
+ *   3. message extraction from tui.transcriptPty (this file)
+ *
+ * The result has the same shape as the legacy parse_output:
+ *   { status, messages, activeModal, transcriptAuthority?, coverage?, providerSessionId? }
+ *
+ * Identity stamping (providerUnitKey, bubbleId, sequence, bubbleState) is
+ * applied by the caller, mirroring _shared/parse_session.js. We export the
+ * stamper as `normalizeMessageIdentity` for reuse.
+ */
+import { type ModalTuiSpec } from './parse-approval.js';
+export interface PrefixSpec {
+    regex: string;
+    flags?: string;
+}
+export interface ToolPrefixSpec extends PrefixSpec {
+    skip?: boolean;
+}
+export interface ChromePatternSpec {
+    regex: string;
+    flags?: string;
+    label?: string;
+}
+export interface TranscriptPtySpec {
+    $schema?: 'adhdev:tui/transcript-pty@1';
+    assistantPrefix: PrefixSpec;
+    userPrefix?: PrefixSpec;
+    toolPrefix?: ToolPrefixSpec;
+    continuationLine?: {
+        indented?: boolean;
+    };
+    chromePatterns?: ChromePatternSpec[];
+    stripLeadingChrome?: boolean;
+    scope?: 'screen' | 'buffer' | 'tail';
+}
+export interface SessionIdExtractionSpec {
+    $schema?: 'adhdev:tui/session-id-extraction@1';
+    regex: string;
+    flags?: string;
+    scope?: 'screen' | 'tail' | 'buffer';
+    label?: string;
+}
+export interface ParseSessionTuiSpec {
+    spinner?: any;
+    settledPrompt?: any;
+    modal?: ModalTuiSpec;
+    dispatchOrder?: any;
+    transcriptPty: TranscriptPtySpec;
+    sessionIdExtraction?: SessionIdExtractionSpec;
+}
+export interface SynthesizedMessage {
+    role: 'user' | 'assistant';
+    kind?: 'standard' | 'tool';
+    content: string;
+    receivedAt?: number;
+}
+export interface SynthesizedSession {
+    status: string | null;
+    messages: SynthesizedMessage[];
+    activeModal: {
+        message: string;
+        buttons: string[];
+    } | null;
+    modal: {
+        message: string;
+        buttons: string[];
+    } | null;
+    parsedStatus: string | null;
+    transcriptAuthority?: 'provider' | 'daemon';
+    coverage?: 'full' | 'tail' | 'current-turn';
+    providerSessionId?: string;
+}
+export declare function normalizeMessageIdentity<T extends {
+    role?: string;
+    kind?: string;
+    content?: string;
+}>(messages: T[], status: string): Array<T & {
+    providerUnitKey: string;
+    bubbleId: string;
+    sequence: number;
+    _turnKey: string;
+    bubbleState: 'streaming' | 'final';
+}>;
+export declare function buildParseSessionFromTui(spec: ParseSessionTuiSpec): (input: any) => SynthesizedSession;

package/dist/providers/sdk/v1/builders/cli/visible-region.d.ts

@@ -0,0 +1,42 @@
+/**
+ * applyVisibleRegion
+ *
+ * Scopes the raw terminal text to the "visible region" declared by a
+ * `tui/visible-region@1` spec before handing it to detect-status and
+ * parse-approval matchers.
+ *
+ * Scope semantics:
+ *   screen   → full text unchanged  (daemon already passes rendered screen)
+ *   buffer   → full text unchanged
+ *   tail     → last `tailChars` characters (default 4000)
+ *   between-anchors → text between most recent (or first) top/bottom anchor
+ *                     regex matches; falls back to full text if anchors not found
+ *
+ * selectAnchor:
+ *   "last"  → use the LAST occurrence of the top anchor — useful for providers
+ *             like Antigravity that redraw a separator + prompt on every turn;
+ *             this excludes all scrollback above the current session frame.
+ *   "first" → use the FIRST occurrence (default per schema).
+ */
+interface AnchorPatternSpec {
+    pattern: string;
+    flags?: string;
+}
+interface AnchorsSpec {
+    top?: AnchorPatternSpec;
+    bottom?: AnchorPatternSpec;
+}
+export interface VisibleRegionSpec {
+    $schema?: 'adhdev:tui/visible-region@1';
+    scope: 'screen' | 'tail' | 'buffer' | 'between-anchors';
+    tailChars?: number;
+    anchors?: AnchorsSpec;
+    selectAnchor?: 'first' | 'last';
+    stripCues?: string[];
+}
+/**
+ * Apply the visible-region spec to `text` and return the scoped substring.
+ * Never throws on missing anchors — falls back to the full text instead.
+ */
+export declare function applyVisibleRegion(spec: VisibleRegionSpec, text: string): string;
+export {};

package/dist/providers/sdk/v1/fixture-tooling/format.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Provider fixture format — v1.
+ *
+ * A fixture is two files committed alongside a provider:
+ *
+ *   fixtures/<scenario>.pty             — raw PTY byte capture (binary or text)
+ *   fixtures/<scenario>.expected.json   — expected handler outputs at one
+ *                                          or more anchor frames
+ *
+ * Scenarios cover one concrete agent behaviour: cold start, prompt sent,
+ * generating with tool call, approval modal, idle after assistant complete,
+ * etc.
+ *
+ * The replay runner feeds the .pty bytes through the daemon's terminal
+ * emulator (TerminalTranscriptAccumulator) building up snapshots at each
+ * declared anchor, invokes the provider handlers, and compares results
+ * to the .expected.json shape.
+ *
+ * This file is the source of truth for the format. Schema mirror at
+ * sdk/v1/schemas/fixture-expected.schema.json.
+ */
+import type { CliApprovalModal, CliChatMessage, CliStatus } from '../types/cli/index.js';
+/**
+ * The top-level shape of <scenario>.expected.json.
+ *
+ * `anchors` is an ordered list; each anchor declares a point in the
+ * PTY stream (by byte offset or by sentinel string) and the expected
+ * handler outputs at that point.
+ */
+export interface FixtureExpected {
+    /** Schema version. Currently always 1. */
+    version: 1;
+    /** Free-form human description of the scenario. */
+    description?: string;
+    /** Provider type this fixture is for. */
+    providerType: string;
+    /** Path (relative to the .expected.json file) of the corresponding .pty file. */
+    ptyFile: string;
+    /** Optional cols/rows the recording was captured under. Defaults to 80x24. */
+    terminal?: {
+        cols: number;
+        rows: number;
+    };
+    /** Anchor points. Order matters; bytes are replayed up to each anchor. */
+    anchors: FixtureAnchor[];
+}
+export interface FixtureAnchor {
+    /** Human-readable identifier. Used in test reporter output. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /**
+     * Where to stop replaying bytes. Exactly one of:
+     *   - `untilByte` — stop after the Nth raw byte
+     *   - `untilSentinel` — stop the first time `sentinel` appears in the
+     *     accumulated rendered screen text
+     */
+    untilByte?: number;
+    untilSentinel?: string;
+    /**
+     * Expected handler outputs. All keys optional; the replay runner only
+     * checks the keys you provide.
+     */
+    expect: {
+        detectStatus?: CliStatus | null;
+        parseApproval?: CliApprovalModal | null;
+        parseSession?: {
+            status?: CliStatus;
+            modal?: CliApprovalModal | null;
+            providerSessionId?: string;
+            /**
+             * Either an exact array (deep-equal) or a shape declaration that lets
+             * you match only the role/kind/content shape without pinning specific
+             * fields. Pin specific message-by-message when you care about content.
+             */
+            messages?: CliChatMessage[] | MessageShape[];
+        };
+    };
+    /**
+     * Optional notes about why this anchor exists. Encouraged for
+     * regression-style fixtures so future maintainers know what bug the
+     * fixture catches.
+     */
+    notes?: string;
+}
+/**
+ * A shape declaration that matches a message by role/kind plus optional
+ * content substring or regex. Use this instead of an exact CliChatMessage
+ * when you do not want to pin exact text.
+ */
+export interface MessageShape {
+    role: CliChatMessage['role'];
+    kind?: CliChatMessage['kind'];
+    /** Substring the content must contain. Plain string only. */
+    contentIncludes?: string;
+    /** Regex the content must match. */
+    contentMatches?: {
+        source: string;
+        flags?: string;
+    };
+}
+/**
+ * Result of replaying one anchor — what the handlers actually emitted.
+ * Used by the test runner to produce diff output.
+ */
+export interface AnchorReplayResult {
+    anchor: FixtureAnchor;
+    passes: boolean;
+    diffs: string[];
+    actual: {
+        detectStatus?: CliStatus | null;
+        parseApproval?: CliApprovalModal | null;
+        parseSession?: {
+            status: CliStatus;
+            modal: CliApprovalModal | null;
+            providerSessionId?: string;
+            messages: CliChatMessage[];
+        };
+    };
+}
+export interface FixtureReplayResult {
+    fixturePath: string;
+    expected: FixtureExpected;
+    perAnchor: AnchorReplayResult[];
+    overallPasses: boolean;
+}

package/dist/providers/sdk/v1/fixture-tooling/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Fixture tooling — public surface.
+ *
+ * Imported by `adhdev provider test` and by daemon-core's CI regression
+ * suite. Format types and the replay runner are stable v1.
+ */
+export type { FixtureExpected, FixtureAnchor, MessageShape, AnchorReplayResult, FixtureReplayResult, } from './format.js';
+export { loadFixtureExpected, replayFixture, formatReplayReport, type CliProviderHandlers, type ReplayOptions, } from './replay.js';

package/dist/providers/sdk/v1/fixture-tooling/replay.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fixture replay runner.
+ *
+ * Given a `.pty` byte capture and `.expected.json` declaration, replay the
+ * bytes through the daemon's TerminalTranscriptAccumulator, invoke the
+ * provider handlers at each anchor, and diff against expectations.
+ *
+ * Used by:
+ *   - `adhdev provider test` (daemon-cloud CLI)
+ *   - daemon-core CI suite for production-provider regression tests
+ *   - external authors as `adhdev provider test ./`
+ */
+import { type CliScriptInput as InternalCliScriptInput, type CliStatusInput as InternalCliStatusInput, type CliApprovalInput as InternalCliApprovalInput, type ParsedSession as InternalParsedSession } from '../../../../cli-adapters/provider-cli-shared.js';
+import type { FixtureExpected, FixtureReplayResult } from './format.js';
+export interface CliProviderHandlers {
+    createState?: () => Record<string, unknown>;
+    parseSession: (state: unknown, input: InternalCliScriptInput) => InternalParsedSession;
+    detectStatus: (input: InternalCliStatusInput) => string | null;
+    parseApproval: (input: InternalCliApprovalInput) => {
+        message: string;
+        buttons: string[];
+    } | null;
+    parseOutput?: (state: unknown, input: InternalCliScriptInput) => unknown;
+}
+export interface ReplayOptions {
+    /** Override accumulator dimensions. Defaults to the fixture's terminal block or 80x24. */
+    cols?: number;
+    rows?: number;
+    /** Provided manually (e.g. by tests). Defaults to wall-clock at replay start. */
+    spawnAt?: number;
+}
+export declare function loadFixtureExpected(expectedPath: string): FixtureExpected;
+export declare function replayFixture(expectedPath: string, handlers: CliProviderHandlers, options?: ReplayOptions): FixtureReplayResult;
+/**
+ * Format a result as a human-readable report. Returns the multi-line string;
+ * caller decides whether to print or assert.
+ */
+export declare function formatReplayReport(result: FixtureReplayResult): string;

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 {};