@adhdev/daemon-core 0.9.82-rc.35 → 0.9.82-rc.351

package/src/providers/sdk/v1/fixture-tooling/replay.ts

@@ -0,0 +1,352 @@
+/**
+ * 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 { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import {
+  TerminalTranscriptAccumulator,
+  buildCliScreenSnapshot,
+  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 {
+  CliApprovalModal,
+  CliChatMessage,
+  CliStatus,
+} from '../types/cli/index.js';
+import type {
+  FixtureExpected,
+  FixtureAnchor,
+  AnchorReplayResult,
+  FixtureReplayResult,
+  MessageShape,
+} from './format.js';
+
+// ─── Provider handler shape (matches the contract) ─────────────────────
+
+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;
+}
+
+// ─── Helpers — build the inputs the handlers expect ────────────────────
+
+function makeStatusInput(buffer: string, rawBuffer: string): InternalCliStatusInput {
+  const tail = buffer.slice(-1000);
+  const screenText = buffer;
+  return {
+    tail,
+    screenText,
+    rawBuffer,
+    isWaitingForResponse: false,
+    screen: buildCliScreenSnapshot(screenText),
+    tailScreen: buildCliScreenSnapshot(tail),
+  };
+}
+
+function makeApprovalInput(buffer: string, rawBuffer: string): InternalCliApprovalInput {
+  const tail = buffer.slice(-1000);
+  const screenText = buffer;
+  return {
+    buffer,
+    screenText,
+    rawBuffer,
+    tail,
+    screen: buildCliScreenSnapshot(screenText),
+    bufferScreen: buildCliScreenSnapshot(buffer),
+    tailScreen: buildCliScreenSnapshot(tail),
+  };
+}
+
+function makeScriptInput(
+  buffer: string,
+  rawBuffer: string,
+  spawnAt: number,
+): InternalCliScriptInput {
+  const recentBuffer = buffer.slice(-1000);
+  const screenText = buffer;
+  return {
+    buffer,
+    rawBuffer,
+    recentBuffer,
+    screenText,
+    screen: buildCliScreenSnapshot(screenText),
+    bufferScreen: buildCliScreenSnapshot(buffer),
+    recentScreen: buildCliScreenSnapshot(recentBuffer),
+    messages: [],
+    partialResponse: '',
+    isWaitingForResponse: false,
+    spawnAt,
+  };
+}
+
+// ─── Anchor stop condition ─────────────────────────────────────────────
+
+function nextStopIndex(anchor: FixtureAnchor, startIdx: number, raw: string): number {
+  if (typeof anchor.untilByte === 'number') {
+    return Math.min(anchor.untilByte, raw.length);
+  }
+  if (anchor.untilSentinel) {
+    const idx = raw.indexOf(anchor.untilSentinel, startIdx);
+    return idx < 0 ? raw.length : idx + anchor.untilSentinel.length;
+  }
+  // Default: replay everything.
+  return raw.length;
+}
+
+// ─── Shape matching for messages ───────────────────────────────────────
+
+function isShapeArray(input: unknown): input is MessageShape[] {
+  if (!Array.isArray(input) || input.length === 0) return false;
+  return input.every((m) => {
+    if (!m || typeof m !== 'object') return false;
+    const keys = Object.keys(m as object);
+    // Detect by absence of CliChatMessage-only required fields like `content` typed string.
+    return (
+      keys.some((k) => k === 'contentIncludes' || k === 'contentMatches') ||
+      (keys.includes('role') && !keys.includes('content'))
+    );
+  });
+}
+
+function messageMatchesShape(actual: CliChatMessage, shape: MessageShape): string | null {
+  if (actual.role !== shape.role) {
+    return `role mismatch: expected "${shape.role}", got "${actual.role}"`;
+  }
+  if (shape.kind && actual.kind && actual.kind !== shape.kind) {
+    return `kind mismatch: expected "${shape.kind}", got "${actual.kind}"`;
+  }
+  const content = typeof actual.content === 'string'
+    ? actual.content
+    : JSON.stringify(actual.content);
+  if (shape.contentIncludes && !content.includes(shape.contentIncludes)) {
+    return `content missing substring "${shape.contentIncludes.slice(0, 40)}"`;
+  }
+  if (shape.contentMatches) {
+    const re = new RegExp(shape.contentMatches.source, shape.contentMatches.flags ?? '');
+    if (!re.test(content)) {
+      return `content does not match /${shape.contentMatches.source}/${shape.contentMatches.flags ?? ''}`;
+    }
+  }
+  return null;
+}
+
+// ─── Diffing ───────────────────────────────────────────────────────────
+
+function diffStatus(
+  label: string,
+  expected: unknown,
+  actual: unknown,
+  diffs: string[],
+): void {
+  if (expected === undefined) return;
+  if (expected !== actual) {
+    diffs.push(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+function diffModal(
+  label: string,
+  expected: CliApprovalModal | null | undefined,
+  actual: CliApprovalModal | null,
+  diffs: string[],
+): void {
+  if (expected === undefined) return;
+  if (expected === null) {
+    if (actual !== null) {
+      diffs.push(`${label}: expected null modal, got ${JSON.stringify(actual)}`);
+    }
+    return;
+  }
+  if (actual === null) {
+    diffs.push(`${label}: expected modal, got null`);
+    return;
+  }
+  if (expected.message !== actual.message) {
+    diffs.push(`${label}.message: expected "${expected.message}", got "${actual.message}"`);
+  }
+  if (expected.buttons.length !== actual.buttons.length) {
+    diffs.push(`${label}.buttons.length: expected ${expected.buttons.length}, got ${actual.buttons.length}`);
+  } else {
+    for (let i = 0; i < expected.buttons.length; i += 1) {
+      if (expected.buttons[i] !== actual.buttons[i]) {
+        diffs.push(`${label}.buttons[${i}]: expected "${expected.buttons[i]}", got "${actual.buttons[i]}"`);
+      }
+    }
+  }
+}
+
+function diffMessages(
+  label: string,
+  expected: CliChatMessage[] | MessageShape[] | undefined,
+  actual: CliChatMessage[],
+  diffs: string[],
+): void {
+  if (expected === undefined) return;
+  if (expected.length !== actual.length) {
+    diffs.push(`${label}.length: expected ${expected.length}, got ${actual.length}`);
+    return;
+  }
+  if (isShapeArray(expected)) {
+    for (let i = 0; i < expected.length; i += 1) {
+      const reason = messageMatchesShape(actual[i], expected[i] as MessageShape);
+      if (reason) diffs.push(`${label}[${i}]: ${reason}`);
+    }
+  } else {
+    for (let i = 0; i < expected.length; i += 1) {
+      const e = expected[i] as CliChatMessage;
+      const a = actual[i];
+      if (e.role !== a.role) diffs.push(`${label}[${i}].role: ${e.role} vs ${a.role}`);
+      const ec = typeof e.content === 'string' ? e.content : JSON.stringify(e.content);
+      const ac = typeof a.content === 'string' ? a.content : JSON.stringify(a.content);
+      if (ec !== ac) diffs.push(`${label}[${i}].content: differs`);
+    }
+  }
+}
+
+// ─── Replay one anchor ─────────────────────────────────────────────────
+
+function replayAnchor(
+  raw: string,
+  startIdx: number,
+  acc: TerminalTranscriptAccumulator,
+  anchor: FixtureAnchor,
+  handlers: CliProviderHandlers,
+  spawnAt: number,
+): { result: AnchorReplayResult; nextIdx: number } {
+  const stop = nextStopIndex(anchor, startIdx, raw);
+  const chunk = raw.slice(startIdx, stop);
+  const buffer = acc.append(chunk);
+  const rawBufferSnapshot = raw.slice(0, stop);
+
+  const detect = handlers.detectStatus(makeStatusInput(buffer, rawBufferSnapshot));
+  const modal = handlers.parseApproval(makeApprovalInput(buffer, rawBufferSnapshot));
+  const state = handlers.createState ? handlers.createState() : undefined;
+  const session = handlers.parseSession(state, makeScriptInput(buffer, rawBufferSnapshot, spawnAt));
+
+  const diffs: string[] = [];
+  diffStatus('detectStatus', anchor.expect.detectStatus, detect as CliStatus | null, diffs);
+  diffModal('parseApproval', anchor.expect.parseApproval, modal, diffs);
+  if (anchor.expect.parseSession) {
+    diffStatus('parseSession.status', anchor.expect.parseSession.status, session.status as CliStatus, diffs);
+    diffModal('parseSession.modal', anchor.expect.parseSession.modal, session.modal as CliApprovalModal | null, diffs);
+    if (anchor.expect.parseSession.providerSessionId !== undefined) {
+      diffStatus(
+        'parseSession.providerSessionId',
+        anchor.expect.parseSession.providerSessionId,
+        session.providerSessionId,
+        diffs,
+      );
+    }
+    diffMessages(
+      'parseSession.messages',
+      anchor.expect.parseSession.messages,
+      session.messages as CliChatMessage[],
+      diffs,
+    );
+  }
+
+  return {
+    result: {
+      anchor,
+      passes: diffs.length === 0,
+      diffs,
+      actual: {
+        detectStatus: detect as CliStatus | null,
+        parseApproval: modal,
+        parseSession: {
+          status: session.status as CliStatus,
+          modal: session.modal as CliApprovalModal | null,
+          providerSessionId: session.providerSessionId,
+          messages: session.messages as CliChatMessage[],
+        },
+      },
+    },
+    nextIdx: stop,
+  };
+}
+
+// ─── Public API ────────────────────────────────────────────────────────
+
+export function loadFixtureExpected(expectedPath: string): FixtureExpected {
+  const raw = readFileSync(expectedPath, 'utf-8');
+  const parsed = JSON.parse(raw) as FixtureExpected;
+  if (parsed.version !== 1) {
+    throw new Error(`Fixture format version ${parsed.version} not supported (this runner is v1).`);
+  }
+  if (!parsed.providerType) throw new Error('Fixture missing providerType');
+  if (!parsed.ptyFile) throw new Error('Fixture missing ptyFile');
+  if (!Array.isArray(parsed.anchors) || parsed.anchors.length === 0) {
+    throw new Error('Fixture must declare at least one anchor');
+  }
+  return parsed;
+}
+
+export function replayFixture(
+  expectedPath: string,
+  handlers: CliProviderHandlers,
+  options: ReplayOptions = {},
+): FixtureReplayResult {
+  const expected = loadFixtureExpected(expectedPath);
+  const ptyFullPath = resolve(dirname(expectedPath), expected.ptyFile);
+  const rawBytes = readFileSync(ptyFullPath, 'utf-8');
+  const acc = new TerminalTranscriptAccumulator();
+  const spawnAt = options.spawnAt ?? Date.now();
+  let idx = 0;
+  const perAnchor: AnchorReplayResult[] = [];
+  for (const anchor of expected.anchors) {
+    const { result, nextIdx } = replayAnchor(rawBytes, idx, acc, anchor, handlers, spawnAt);
+    perAnchor.push(result);
+    idx = nextIdx;
+  }
+  return {
+    fixturePath: expectedPath,
+    expected,
+    perAnchor,
+    overallPasses: perAnchor.every((a) => a.passes),
+  };
+}
+
+/**
+ * Format a result as a human-readable report. Returns the multi-line string;
+ * caller decides whether to print or assert.
+ */
+export function formatReplayReport(result: FixtureReplayResult): string {
+  const lines: string[] = [];
+  lines.push(`Fixture: ${result.fixturePath}`);
+  lines.push(`Provider: ${result.expected.providerType}`);
+  lines.push(`Anchors: ${result.perAnchor.length}`);
+  for (const a of result.perAnchor) {
+    if (a.passes) {
+      lines.push(`  ✓ ${a.anchor.name}`);
+    } else {
+      lines.push(`  ✗ ${a.anchor.name}`);
+      for (const d of a.diffs) lines.push(`      ${d}`);
+    }
+  }
+  lines.push(result.overallPasses ? 'OVERALL: PASS' : 'OVERALL: FAIL');
+  return lines.join('\n');
+}

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

@@ -0,0 +1,152 @@
+/**
+ * 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';
+
+// Builders — turn declarative manifest blocks into runtime functions.
+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';
+
+// ACP builders — declarative stdio session-status detection.
+export {
+  buildDetectStatusFromAcp,
+  type AcpSessionSpec,
+  type AcpStatusInput,
+  type AcpDetectedStatus,
+} from './builders/acp/detect-status.js';
+
+// Fixture tooling — record/replay for provider regression suites.
+export {
+  loadFixtureExpected,
+  replayFixture,
+  formatReplayReport,
+  type FixtureExpected,
+  type FixtureAnchor,
+  type MessageShape,
+  type AnchorReplayResult,
+  type FixtureReplayResult,
+  type CliProviderHandlers,
+  type ReplayOptions,
+} from './fixture-tooling/index.js';
+
+// Static validators — used by `adhdev provider validate` + registry publish.
+export {
+  analyzeOverrideTaint,
+  formatTaintResult,
+  type TaintLevel,
+  type TaintCategory,
+  type TaintFinding,
+  type TaintResult,
+  validateCliProviderManifest,
+  formatManifestValidationIssues,
+  type ManifestValidationIssue,
+  type ManifestValidationResult,
+} from './validators/index.js';
+
+// Primitive identifiers — the canonical list.
+// Implementations live under ./primitives/ and are wired in by builders.
+export const V1_PRIMITIVE_CATALOG = Object.freeze({
+  acp: [
+    'adhdev:acp/session-protocol@1',
+  ],
+  tui: [
+    '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',
+  ],
+  nativeHistory: [
+    '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',
+  ],
+  cliCapability: [
+    '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',
+  ],
+  common: [
+    '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',
+  ],
+  override: [
+    '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',
+  ],
+} as const);
+
+/** Aggregate flat list — for provider catalog endpoints. */
+export const V1_ALL_PRIMITIVES: ReadonlyArray<string> = Object.freeze(
+  Object.values(V1_PRIMITIVE_CATALOG).flat(),
+);
+
+/** Catalog version label exposed at `registry.adhf.dev/primitives`. */
+export const V1_CONTRACT_VERSION = '1.0.0' as const;

package/src/providers/sdk/v1/sandbox/README-design.ts

@@ -0,0 +1,195 @@
+/**
+ * @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)
+ */
+
+// This file contains no executable code.
+export {};