@adhdev/daemon-core 0.9.82-rc.43 → 0.9.82-rc.431

package/src/providers/sdk/v1/sandbox/script-runner.ts

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ */
+
+import { LOG } from '../../../../logging/logger.js';
+
+/** 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 const DEFAULT_SANDBOX_OPTIONS: SandboxOptions = {
+    cpuTimeLimitMs: 50,
+    memoryLimitMb: 32,
+    allowedGlobals: ['console', 'JSON', 'Math', 'Date', 'String', 'Number', 'Boolean', 'Array', 'Object', 'RegExp'],
+};
+
+/**
+ * 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 class DirectEvalRunner implements SandboxedScriptRunner {
+    private warned = false;
+    private readonly defaultOptions: SandboxOptions;
+
+    constructor(options?: Partial<SandboxOptions>) {
+        this.defaultOptions = { ...DEFAULT_SANDBOX_OPTIONS, ...options };
+    }
+
+    async run(
+        script: string,
+        context: Record<string, unknown>,
+        _options?: Partial<SandboxOptions>,
+    ): Promise<unknown> {
+        if (!this.warned) {
+            LOG.warn('Sandbox', '[DirectEvalRunner] isolated-vm not available — running script without sandboxing. Install isolated-vm for production use.');
+            this.warned = true;
+        }
+
+        // Build a function body that exposes context keys as locals, then
+        // evaluates the script and returns its result.
+        const contextKeys = Object.keys(context);
+        const contextValues = contextKeys.map((k) => context[k]);
+
+        // eslint-disable-next-line no-new-func
+        const fn = new Function(...contextKeys, `"use strict";\nreturn (${script});`);
+        return fn(...contextValues);
+    }
+
+    dispose(): void {
+        // Nothing to release — DirectEvalRunner holds no native resources.
+    }
+}
+
+/**
+ * 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 function createScriptRunner(options?: Partial<SandboxOptions>): SandboxedScriptRunner {
+    try {
+        // Dynamic require so that the import does not break the module when
+        // isolated-vm is absent from node_modules.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const isolatedVm = require('isolated-vm');
+        if (isolatedVm && typeof isolatedVm.Isolate === 'function') {
+            // Phase 5: IsolatedVmRunner — not yet implemented.
+            // TODO(phase5): return new IsolatedVmRunner(options);
+            LOG.warn('Sandbox', '[createScriptRunner] isolated-vm detected but IsolatedVmRunner is not yet implemented — falling back to DirectEvalRunner.');
+        }
+    } catch {
+        // isolated-vm is not installed — this is the expected state for now.
+    }
+    return new DirectEvalRunner(options);
+}

package/src/providers/sdk/v1/schemas/cli/provider.schema.json

@@ -0,0 +1,504 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "adhdev:cli/provider@1",
+  "title": "CLI provider.json — v1",
+  "description": "Schema for CLI provider manifests. Validates the contract documented in docs/provider-contract/cli/v1.md. All 4 production CLI providers (codex, claude, hermes, antigravity) pass this schema without modification.",
+  "type": "object",
+  "required": ["type", "name", "category", "binary", "spawn"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Schema URL. Hint for editor tooling; not consumed by the daemon."
+    },
+    "links": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Documentation URLs. Surfaced in marketplace UI."
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "description": "Install instructions by channel (npm/pip/manual/brew). UI-only."
+    },
+    "source": {
+      "type": "object",
+      "description": "GitHub source descriptor. Daemon uses this to fetch script files on install.",
+      "additionalProperties": false,
+      "properties": {
+        "type": { "const": "github" },
+        "repo": { "type": "string", "pattern": "^[\\w.-]+/[\\w.-]+$" },
+        "ref":  { "type": "string" },
+        "subdir": { "type": "string" }
+      },
+      "required": ["type", "repo", "ref"]
+    },
+    "type": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Stable identifier. Lowercase kebab-case."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Short canonical name."
+    },
+    "displayName": {
+      "type": "string",
+      "description": "Optional UI label. Defaults to name."
+    },
+    "category": {
+      "const": "cli",
+      "description": "Must be \"cli\" for this schema."
+    },
+    "icon": {
+      "type": "string",
+      "maxLength": 4,
+      "description": "Single emoji or short glyph."
+    },
+    "aliases": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Alternative identifiers accepted at launch."
+    },
+    "engines": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "adhdev": {
+          "type": "string",
+          "description": "SemVer range against the ADHDev contract version. Required for marketplace-published providers."
+        }
+      },
+      "description": "Optional today; required by marketplace publish flow once registry is live."
+    },
+    "providerVersion": {
+      "type": "string",
+      "description": "Provider package SemVer."
+    },
+    "contractVersion": {
+      "type": ["number", "string"],
+      "description": "Legacy contract version. Reserved."
+    },
+    "status": {
+      "enum": ["Stable", "Beta", "Experimental", "Deprecated"]
+    },
+    "details": {
+      "type": "string",
+      "description": "Short blurb shown in marketplace."
+    },
+    "disableUpstream": {
+      "type": "boolean",
+      "description": "When true, daemon does not auto-sync this provider from registry. claude-cli uses this for explicit-version pinning."
+    },
+    "binary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Binary basename used for which-style detection."
+    },
+    "versionCommand": {
+      "type": "string",
+      "description": "Command the daemon runs to probe installed version. Example: \"my-cli --version\"."
+    },
+    "spawn": {
+      "type": "object",
+      "required": ["command"],
+      "additionalProperties": false,
+      "properties": {
+        "command": { "type": "string", "minLength": 1 },
+        "args": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": []
+        },
+        "shell": { "type": "boolean", "default": false },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "default": {}
+        }
+      }
+    },
+    "sendDelayMs": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Delay between pasting prompt text and pressing Enter."
+    },
+    "scriptCallBudgetMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 5000,
+      "default": 50,
+      "description": "Per-invocation wall-clock budget (ms) for provider scripts (detectStatus, parseSession, parseApproval). Default 50. Scripts that exceed the budget are flagged in the runner's invocation trace and surfaced via the debug bundle so operators can identify a hanging settle loop. The budget is NOT a hard kill — Node CJS cannot interrupt synchronous code without a worker thread."
+    },
+    "sendKey": {
+      "type": "string",
+      "default": "\r",
+      "description": "Character sent to submit a prompt. Default carriage return."
+    },
+    "submitStrategy": {
+      "enum": ["wait_for_echo", "immediate"],
+      "default": "immediate"
+    },
+    "requirePromptEchoBeforeSubmit": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, daemon waits for the typed prompt to be visible in the PTY screen before sending sendKey."
+    },
+    "allowInputDuringGeneration": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, daemon permits sending a new prompt mid-generation."
+    },
+    "requiresFinalAssistantBeforeIdle": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, daemon defers generating→idle until parseSession includes a final standard assistant message."
+    },
+    "augmentStaleSnapshot": {
+      "type": "boolean",
+      "description": "Reserved for future use."
+    },
+    "transcriptAuthority": {
+      "enum": ["provider", "daemon"],
+      "description": "When 'provider', daemon treats parsed output as canonical and suppresses fallback parsing."
+    },
+    "transcriptContext": {
+      "enum": ["full", "tail"],
+      "description": "When 'full', provider-owned parser receives the entire accumulated transcript context."
+    },
+    "patterns": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional regex hints for the legacy fallback detector. Modern providers express these via primitives.",
+      "properties": {
+        "prompt":     { "$ref": "#/$defs/patternList" },
+        "generating": { "$ref": "#/$defs/patternList" },
+        "approval":   { "$ref": "#/$defs/patternList" },
+        "ready":      { "$ref": "#/$defs/patternList" },
+        "dialog":     { "$ref": "#/$defs/patternList" }
+      }
+    },
+    "approvalKeys": {
+      "type": "object",
+      "patternProperties": {
+        "^[0-9]+$": { "type": "string" }
+      },
+      "additionalProperties": false,
+      "description": "Map of button index → key sequence to send."
+    },
+    "approvalPositiveHints": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Lowercase substrings considered \"positive\" (accept). Auto-approve picks the matching button."
+    },
+    "timeouts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ptyFlush":           { "type": "number", "minimum": 0 },
+        "dialogAccept":       { "type": "number", "minimum": 0 },
+        "approvalCooldown":   { "type": "number", "minimum": 0 },
+        "generatingIdle":     { "type": "number", "minimum": 0 },
+        "idleFinish":         { "type": "number", "minimum": 0 },
+        "idleFinishConfirm":  { "type": "number", "minimum": 0 },
+        "statusActivityHold": { "type": "number", "minimum": 0 },
+        "maxResponse":        { "type": "number", "minimum": 0 },
+        "shutdownGrace":      { "type": "number", "minimum": 0 },
+        "outputSettle":       { "type": "number", "minimum": 0 }
+      }
+    },
+    "resume": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["supported"],
+      "properties": {
+        "supported": { "type": "boolean" },
+        "stopStrategy": { "enum": ["command", "ctrl_c", "signal"] },
+        "stopCommand": { "type": "string" },
+        "shutdownGraceMs": { "type": "number", "minimum": 0 },
+        "sessionIdFormat": { "enum": ["uuid", "free", "string"] },
+        "newSessionArgs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "resumeSessionArgs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "resumeArgs": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "compatibility": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["ideVersion"],
+        "additionalProperties": false,
+        "properties": {
+          "ideVersion": { "type": "string", "description": "SemVer range." },
+          "scriptDir":  { "type": "string", "pattern": "^scripts/[^/]+$" },
+          "spec":       { "type": "string", "pattern": "^specs/[^/]+\\.json$", "description": "Path to declarative spec.json driving SpecCliAdapter for this version range." }
+        }
+      },
+      "description": "Maps installed agent versions to script subdirectories and/or declarative specs."
+    },
+    "defaultScriptDir": {
+      "type": "string",
+      "pattern": "^scripts/[^/]+$",
+      "description": "Fallback when no compatibility[] entry matches."
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "input": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "multipart": { "type": "boolean" },
+            "mediaTypes": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "strategies": { "type": "array" }
+          }
+        },
+        "output": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "richContent": { "type": "boolean" },
+            "mediaTypes": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "controls": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "typedResults": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "meshCoordinator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["supported"],
+      "properties": {
+        "supported": { "type": "boolean" },
+        "mcpConfig": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode":                { "enum": ["manual", "auto_import"] },
+            "format":              { "type": "string" },
+            "path":                { "type": "string" },
+            "configPathCommand":   { "type": "string" },
+            "serverName":          { "type": "string" },
+            "requiresRestart":     { "type": "boolean" },
+            "instructions":        { "type": "string" },
+            "template":            { "type": "string" }
+          }
+        },
+        "systemPromptInjection": {
+          "description": "How the coordinator system prompt reaches the launched CLI. Replaces hard-coded router branches per CLI type; users may override the prompt body or the injection mechanism here.",
+          "oneOf": [
+            { "type": "object", "additionalProperties": false, "required": ["mode", "flag"],
+              "properties": { "mode": { "const": "cli_arg" }, "flag": { "type": "string" } } },
+            { "type": "object", "additionalProperties": false, "required": ["mode", "flag", "template"],
+              "properties": { "mode": { "const": "config_override" }, "flag": { "type": "string" }, "template": { "type": "string" } } },
+            { "type": "object", "additionalProperties": false, "required": ["mode", "path"],
+              "properties": { "mode": { "const": "context_file" }, "path": { "type": "string" }, "wrapper": { "type": "string" } } },
+            { "type": "object", "additionalProperties": false, "required": ["mode", "name"],
+              "properties": { "mode": { "const": "env_var" }, "name": { "type": "string" } } }
+          ]
+        },
+        "delegatedWorkerIsolation": {
+          "description": "Provider-declared launch isolation for coordinator-spawned worker sessions. Keeps worker-only sessions from inheriting coordinator MCP/tools/config.",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "env": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "unset": {
+                  "type": "array",
+                  "items": { "type": "string", "minLength": 1 }
+                }
+              }
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["mode", "flag"],
+                    "properties": {
+                      "mode": { "const": "empty_mcp_config" },
+                      "flag": { "type": "string", "minLength": 1 },
+                      "strictFlag": { "type": "string", "minLength": 1 }
+                    }
+                  },
+                  {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["mode", "flag", "key", "value"],
+                    "properties": {
+                      "mode": { "const": "config_override" },
+                      "flag": { "type": "string", "minLength": 1 },
+                      "key": { "type": "string", "minLength": 1 },
+                      "value": { "type": "string", "minLength": 1 },
+                      "dedupeKey": { "type": "string", "minLength": 1 }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        }
+      }
+    },
+    "nativeHistory": {
+      "type": "object",
+      "description": "Native transcript adapter declaration. v1 canonical field name. Daemon reads/lists provider-native history files via the named scripts (or the built-in adapter identified by $schema).",
+      "additionalProperties": true,
+      "properties": {
+        "$schema":          { "type": "string" },
+        "format":           { "type": "string" },
+        "watchPath":        { "type": "string" },
+        "mode":             { "enum": ["native-source", "materialized-mirror", "disabled", "daemon-mirror"] },
+        "contractVersion":  { "type": "string" },
+        "scripts": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "readSession":  { "type": "string" },
+            "listSessions": { "type": "string" }
+          }
+        }
+      }
+    },
+    "canonicalHistory": {
+      "type": "object",
+      "description": "Deprecated v0 alias for `nativeHistory`. The loader copies this block into `nativeHistory` at load time. New manifests should use `nativeHistory` directly.",
+      "additionalProperties": true,
+      "properties": {
+        "format":           { "type": "string" },
+        "watchPath":        { "type": "string" },
+        "mode":             { "enum": ["native-source", "materialized-mirror", "disabled", "daemon-mirror"] },
+        "contractVersion":  { "type": "string" },
+        "scripts": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "readSession":  { "type": "string" },
+            "listSessions": { "type": "string" }
+          }
+        }
+      }
+    },
+    "settings": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/settingDef" }
+    },
+    "controls": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/controlDef" }
+    },
+    "tui": {
+      "type": "object",
+      "description": "Declarative TUI parsing primitives. When present, daemon's builder synthesises detectStatus / parseApproval / parseSession from these blocks. Each block is identified by its $schema.",
+      "additionalProperties": true
+    },
+    "overrides": {
+      "type": "object",
+      "description": "Optional JS override pointers. Presence promotes the provider tier to `extended`. Each value identifies the handler being overridden and the relative path to the JS file implementing it.",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string", "description": "Relative path to the override JS file." },
+          {
+            "type": "object",
+            "required": ["path"],
+            "additionalProperties": false,
+            "properties": {
+              "$schema": { "type": "string" },
+              "path":    { "type": "string" },
+              "reason":  { "type": "string" }
+            }
+          }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "patternList": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["source"],
+        "additionalProperties": false,
+        "properties": {
+          "source": { "type": "string", "description": "Regex source." },
+          "flags":  { "type": "string", "pattern": "^[gimsuy]*$" }
+        }
+      }
+    },
+    "settingDef": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type":        { "enum": ["boolean", "number", "string", "select"] },
+        "default":     {},
+        "public":      { "type": "boolean" },
+        "label":       { "type": "string" },
+        "description": { "type": "string" },
+        "options":     { "type": "array" },
+        "min":         { "type": "number" },
+        "max":         { "type": "number" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "select" } } },
+          "then": { "required": ["options"] }
+        }
+      ]
+    },
+    "controlDef": {
+      "type": "object",
+      "required": ["id", "type", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "id":              { "type": "string" },
+        "type":            { "enum": ["select", "action", "toggle"] },
+        "label":           { "type": "string" },
+        "icon":            { "type": "string" },
+        "placement":       { "type": "string" },
+        "order":           { "type": "number" },
+        "dynamic":         { "type": "boolean" },
+        "hidden":          { "type": "boolean", "description": "When true, dashboard does not render the control directly. Used for commands triggered by other UI (slash menu, etc.)." },
+        "options":         { "type": "array" },
+        "listScript":      { "type": "string" },
+        "setScript":       { "type": "string" },
+        "invokeScript":    { "type": "string" },
+        "readFrom":        { "type": "string" },
+        "resultDisplay":   { "type": "string" },
+        "defaultValue":    {},
+        "confirmTitle":    { "type": "string" },
+        "confirmMessage":  { "type": "string" },
+        "confirmLabel":    { "type": "string" }
+      }
+    }
+  }
+}