@adhdev/daemon-core 0.9.82-rc.20 → 0.9.82-rc.201

package/src/providers/sdk/v1/validators/manifest.ts

@@ -0,0 +1,110 @@
+/**
+ * Manifest validators — runtime JSON Schema check for v1 provider manifests.
+ *
+ * The schemas live under `schemas/{category}/provider.schema.json` and are
+ * the authoritative contract for what a v1 manifest may contain. Daemon
+ * code that loads a manifest at install or boot time runs it through
+ * `validateCliProviderManifest()` first; failures are reported back to
+ * the caller with structured paths so manifest authors can locate the
+ * offending field without guessing.
+ *
+ * Validation lives in the SDK layer (not in provider-loader) so dashboards,
+ * registry workers, and the provider publish flow can all reuse the
+ * same code path and produce identical error messages.
+ */
+
+import Ajv2020, { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import cliProviderSchema from '../schemas/cli/provider.schema.json';
+
+export interface ManifestValidationIssue {
+    /** JSON Pointer-style path into the manifest. Empty string for the root. */
+    path: string;
+    /** Schema-keyword that failed. */
+    keyword: string;
+    /** Human-readable explanation. */
+    message: string;
+    /** Allowed values when the failure is an `enum` / `const` / `additionalProperties`. */
+    allowed?: unknown;
+}
+
+export interface ManifestValidationResult {
+    ok: boolean;
+    issues: ManifestValidationIssue[];
+}
+
+let _ajv: Ajv2020 | null = null;
+let _cliValidator: ValidateFunction | null = null;
+
+function getAjv(): Ajv2020 {
+    if (_ajv) return _ajv;
+    // strict=false because the schema authors freely use schema-level
+    // `description`/`examples` fields that ajv would otherwise warn about.
+    // allErrors=true so a single validation run reports every problem at
+    // once instead of bailing on the first — that's what makes the
+    // structured-error output usable for manifest authors.
+    _ajv = new Ajv2020({
+        strict: false,
+        allErrors: true,
+        allowUnionTypes: true,
+    });
+    addFormats(_ajv);
+    return _ajv;
+}
+
+function getCliValidator(): ValidateFunction {
+    if (_cliValidator) return _cliValidator;
+    _cliValidator = getAjv().compile(cliProviderSchema as unknown as object);
+    return _cliValidator;
+}
+
+function formatIssue(err: ErrorObject): ManifestValidationIssue {
+    const path = err.instancePath || '';
+    const params = err.params as Record<string, unknown>;
+    let message = err.message || 'validation failed';
+    let allowed: unknown;
+
+    if (err.keyword === 'additionalProperties') {
+        const extra = params.additionalProperty;
+        message = `unexpected property "${extra}"`;
+    } else if (err.keyword === 'required') {
+        message = `missing required property "${params.missingProperty}"`;
+    } else if (err.keyword === 'enum') {
+        allowed = params.allowedValues;
+        message = `must be one of ${JSON.stringify(allowed)}`;
+    } else if (err.keyword === 'const') {
+        allowed = params.allowedValue;
+        message = `must equal ${JSON.stringify(allowed)}`;
+    } else if (err.keyword === 'type') {
+        message = `must be ${params.type}`;
+    }
+
+    return { path, keyword: err.keyword, message, ...(allowed !== undefined ? { allowed } : {}) };
+}
+
+/**
+ * Validate a CLI provider.v1.json manifest. Returns `{ ok: true, issues: [] }`
+ * on success and `{ ok: false, issues: [...] }` on failure with each issue
+ * pointing at the offending field. Never throws — manifest parse errors
+ * should be caught by the caller before this is called.
+ */
+export function validateCliProviderManifest(manifest: unknown): ManifestValidationResult {
+    const validator = getCliValidator();
+    const ok = validator(manifest) as boolean;
+    if (ok) return { ok: true, issues: [] };
+    const issues = (validator.errors || []).map(formatIssue);
+    return { ok: false, issues };
+}
+
+/**
+ * Render a list of validation issues as a single multi-line string,
+ * suitable for log lines or daemon command error fields.
+ */
+export function formatManifestValidationIssues(issues: ManifestValidationIssue[]): string {
+    return issues
+        .map((issue) => {
+            const where = issue.path || '<root>';
+            return `  - ${where}: ${issue.message} (${issue.keyword})`;
+        })
+        .join('\n');
+}

package/src/providers/sdk/v1/validators/taint.ts

@@ -0,0 +1,309 @@
+/**
+ * Static taint analyzer for extended-tier override JS.
+ *
+ * Goal: classify the override JS shipped with an extended-tier provider into
+ * one of three risk tiers, so the dashboard + daemon trust prompt can
+ * surface accurate language to the operator instead of a single generic
+ * "this provider contains JS" warning.
+ *
+ *   - clean    : no flagged APIs at all. The override looks like pure string
+ *                manipulation. Still extended-tier, but the warning copy is
+ *                "this provider contains JS; nothing dangerous was detected".
+ *   - elevated : touches process / dynamic codegen / dynamic require / eval
+ *                / Function constructor / child_process. The warning copy is
+ *                explicit ("this provider can run shell commands / dynamically
+ *                load code").
+ *   - hostile  : combines elevated APIs with network egress, AND uses obvious
+ *                obfuscation (base64-decoded strings fed into Function / eval).
+ *                The publish endpoint should reject these.
+ *
+ * Implementation note: this is a *static* analyzer — string + light AST scan
+ * via Node's built-in parser. It is intentionally fail-loud: anything that
+ * looks suspicious is flagged. False positives are fine; this exists to gate
+ * the trust prompt, not to be a real sandbox. The real sandbox lives in
+ * Phase 5 (isolated-vm).
+ *
+ * Used by:
+ *   - `adhdev provider validate` (CLI tier classification)
+ *   - registry publish endpoint static-check
+ *   - daemon at provider-load time, to size the warning
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+
+// ─── Findings ──────────────────────────────────────────────────────────
+
+export type TaintLevel = 'clean' | 'elevated' | 'hostile';
+
+export interface TaintFinding {
+  /** What was found, e.g. "child_process.exec". */
+  api: string;
+  /** Coarse category. */
+  category: TaintCategory;
+  /** File the finding came from. */
+  file: string;
+  /** Line number (1-indexed) of the first character of the matched token. */
+  line: number;
+  /** The surrounding source excerpt, trimmed. */
+  excerpt: string;
+}
+
+export type TaintCategory =
+  | 'process-control'   // process.exit, process.kill
+  | 'shell-exec'        // child_process.{exec,execSync,spawn,spawnSync,fork}
+  | 'fs-write'          // fs.writeFile / writeFileSync outside override dir
+  | 'fs-read'           // fs.readFile / readFileSync
+  | 'network'           // http(s).request, fetch, net.connect, dgram
+  | 'dynamic-codegen'   // eval, new Function(), Function('...')
+  | 'dynamic-require'   // require(variable), import(variable)
+  | 'obfuscation'       // Buffer.from(...,'base64').toString + (eval|Function)
+  | 'global-mutation';  // mutating Object.prototype, process.env
+
+export interface TaintResult {
+  level: TaintLevel;
+  findings: TaintFinding[];
+  files: string[];
+}
+
+// ─── Patterns ──────────────────────────────────────────────────────────
+
+interface PatternRule {
+  category: TaintCategory;
+  /** Display label. */
+  label: string;
+  /** Regex applied per-line. */
+  pattern: RegExp;
+}
+
+const PATTERNS: PatternRule[] = [
+  {
+    category: 'shell-exec',
+    label: 'child_process.exec',
+    pattern: /\bchild_process\b[\s\S]{0,40}?\b(exec|execSync|spawn|spawnSync|fork|execFile)\b/,
+  },
+  {
+    category: 'shell-exec',
+    label: 'require("child_process")',
+    pattern: /\brequire\s*\(\s*['"]child_process['"]\s*\)/,
+  },
+  {
+    category: 'shell-exec',
+    label: 'import child_process',
+    pattern: /\bfrom\s+['"](?:node:)?child_process['"]/,
+  },
+  {
+    category: 'process-control',
+    label: 'process.exit / kill',
+    pattern: /\bprocess\.(exit|kill|abort)\s*\(/,
+  },
+  {
+    category: 'global-mutation',
+    label: 'process.env mutation',
+    pattern: /\bprocess\.env\.[A-Z_][A-Z0-9_]*\s*=/,
+  },
+  {
+    category: 'global-mutation',
+    label: 'prototype pollution',
+    pattern: /\bObject\.prototype\b.*=/,
+  },
+  {
+    category: 'dynamic-codegen',
+    label: 'eval()',
+    pattern: /(?<![A-Za-z0-9_$])eval\s*\(/,
+  },
+  {
+    category: 'dynamic-codegen',
+    label: 'new Function()',
+    pattern: /\bnew\s+Function\s*\(/,
+  },
+  {
+    category: 'dynamic-require',
+    label: 'require(variable)',
+    pattern: /\brequire\s*\(\s*(?!['"`])/,
+  },
+  {
+    category: 'dynamic-require',
+    label: 'import(variable)',
+    pattern: /(?<![.\w])import\s*\(\s*(?!['"`])/,
+  },
+  {
+    category: 'network',
+    label: 'fetch()',
+    pattern: /(?<![A-Za-z0-9_$])fetch\s*\(/,
+  },
+  {
+    category: 'network',
+    label: 'http(s).request',
+    pattern: /\b(https?)\.(request|get)\s*\(/,
+  },
+  {
+    category: 'network',
+    label: 'net.connect / Socket',
+    pattern: /\b(net\.connect|tls\.connect|new\s+net\.Socket)\b/,
+  },
+  {
+    category: 'network',
+    label: 'dgram',
+    pattern: /\brequire\s*\(\s*['"](?:node:)?dgram['"]/,
+  },
+  {
+    category: 'fs-write',
+    label: 'fs.writeFile / writeFileSync',
+    pattern: /\bfs\.(writeFile|writeFileSync|appendFile|appendFileSync|unlink|unlinkSync|rm|rmSync)\b/,
+  },
+  {
+    category: 'fs-read',
+    label: 'fs.readFile / readFileSync',
+    pattern: /\bfs\.(readFile|readFileSync|readdir|readdirSync|stat|statSync)\b/,
+  },
+];
+
+// Obfuscation heuristic: base64 / hex decode feeding into eval or Function.
+const OBFUSCATION_PATTERN =
+  /Buffer\.from\s*\([^)]*['"](?:base64|hex)['"]\s*\)\s*\.toString\s*\([^)]*\)[\s\S]{0,80}?(eval|Function)\s*\(/;
+
+// ─── File walker — picks up everything reachable from overrides ────────
+
+function listOverrideJsFiles(manifestPath: string): string[] {
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8')) as { overrides?: Record<string, unknown> };
+  if (!manifest.overrides) return [];
+  const base = dirname(manifestPath);
+  const out = new Set<string>();
+  for (const value of Object.values(manifest.overrides)) {
+    let rel: string | null = null;
+    if (typeof value === 'string') rel = value;
+    else if (value && typeof value === 'object' && 'path' in value && typeof (value as { path: unknown }).path === 'string') {
+      rel = (value as { path: string }).path;
+    }
+    if (!rel) continue;
+    const abs = resolve(base, rel);
+    if (existsSync(abs)) out.add(abs);
+  }
+  // Best-effort: also scan sibling scripts/ tree, since overrides commonly
+  // require() helpers from there.
+  for (const candidate of ['scripts']) {
+    const dir = join(base, candidate);
+    if (existsSync(dir)) {
+      try {
+        walk(dir, out);
+      } catch {
+        // Ignore individual unreadable files.
+      }
+    }
+  }
+  return [...out];
+}
+
+function walk(dir: string, into: Set<string>): void {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { readdirSync, statSync } = require('node:fs') as typeof import('node:fs');
+  for (const entry of readdirSync(dir)) {
+    const abs = join(dir, entry);
+    let st;
+    try { st = statSync(abs); } catch { continue; }
+    if (st.isDirectory()) walk(abs, into);
+    else if (st.isFile() && /\.(?:m|c)?js$/.test(entry)) into.add(abs);
+  }
+}
+
+// ─── Scanner ───────────────────────────────────────────────────────────
+
+function scanFile(file: string): TaintFinding[] {
+  const source = readFileSync(file, 'utf-8');
+  const findings: TaintFinding[] = [];
+  // Per-line scan keeps line numbers honest.
+  const lines = source.split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    for (const rule of PATTERNS) {
+      if (rule.pattern.test(line)) {
+        findings.push({
+          api: rule.label,
+          category: rule.category,
+          file,
+          line: i + 1,
+          excerpt: line.trim().slice(0, 200),
+        });
+      }
+    }
+  }
+  // Whole-file scan for obfuscation pattern (may span lines).
+  if (OBFUSCATION_PATTERN.test(source)) {
+    findings.push({
+      api: 'base64/hex → eval|Function',
+      category: 'obfuscation',
+      file,
+      line: 1,
+      excerpt: '<obfuscation pattern across multiple lines>',
+    });
+  }
+  return findings;
+}
+
+// ─── Classification ────────────────────────────────────────────────────
+
+const ELEVATED_CATEGORIES = new Set<TaintCategory>([
+  'shell-exec',
+  'process-control',
+  'dynamic-codegen',
+  'dynamic-require',
+  'fs-write',
+  'global-mutation',
+]);
+
+const HOSTILE_REQUIRES = new Set<TaintCategory>([
+  'obfuscation',
+]);
+
+function classify(findings: TaintFinding[]): TaintLevel {
+  if (findings.length === 0) return 'clean';
+  const cats = new Set(findings.map((f) => f.category));
+  if ([...cats].some((c) => HOSTILE_REQUIRES.has(c))) return 'hostile';
+  // Hostile also: elevated + network combined.
+  const hasElevated = [...cats].some((c) => ELEVATED_CATEGORIES.has(c));
+  const hasNetwork = cats.has('network');
+  if (hasElevated && hasNetwork) return 'hostile';
+  if (hasElevated || hasNetwork) return 'elevated';
+  return 'clean'; // only fs-read on its own is fine.
+}
+
+// ─── Public API ────────────────────────────────────────────────────────
+
+export function analyzeOverrideTaint(manifestPath: string): TaintResult {
+  const files = listOverrideJsFiles(manifestPath);
+  const findings: TaintFinding[] = [];
+  for (const f of files) findings.push(...scanFile(f));
+  return {
+    level: classify(findings),
+    findings,
+    files,
+  };
+}
+
+/** Format a result as a single CLI-friendly block. */
+export function formatTaintResult(result: TaintResult): string {
+  const lines: string[] = [];
+  lines.push(`Tier: extended (override JS present)`);
+  lines.push(`Risk level: ${result.level}`);
+  lines.push(`Files scanned: ${result.files.length}`);
+  if (result.findings.length === 0) {
+    lines.push('No flagged APIs detected.');
+    return lines.join('\n');
+  }
+  // Group by category for a tighter report.
+  const byCat = new Map<TaintCategory, TaintFinding[]>();
+  for (const f of result.findings) {
+    const arr = byCat.get(f.category) ?? [];
+    arr.push(f);
+    byCat.set(f.category, arr);
+  }
+  for (const [cat, items] of byCat) {
+    lines.push(`  ${cat}: ${items.length} occurrence(s)`);
+    for (const f of items.slice(0, 5)) {
+      lines.push(`    ${f.file}:${f.line}  ${f.api}`);
+    }
+    if (items.length > 5) lines.push(`    …and ${items.length - 5} more`);
+  }
+  return lines.join('\n');
+}

package/src/providers/spec/adapter.ts

@@ -0,0 +1,176 @@
+/**
+ * Thin generic terminal adapter.
+ *
+ * Spawns a PTY, feeds bytes into a headless xterm so a visible screen
+ * snapshot is always available, and exposes a small hook surface
+ * (init / tick / on_screen_changed / on_exit). Nothing in this module
+ * knows about agents, modals, or specs — it's just a terminal host.
+ *
+ * The Spec Driver is built on top of this adapter and consumes the
+ * hooks to drive its declarative state machine.
+ *
+ * Inbound from driver:
+ *   send_keys(str)  — raw bytes to PTY
+ *   resize(c, r)    — resize the PTY and the xterm
+ *   kill()          — terminate the child
+ *
+ * Outbound to driver:
+ *   init({ pid })
+ *   on_pty_data(chunk)            — raw bytes for dashboard's terminal pane
+ *   on_screen_changed(snapshot)   — coalesced visible-screen change
+ *   tick()                        — periodic timer (configurable interval)
+ *   on_exit({ exitCode })
+ */
+'use strict';
+
+// @xterm/headless ships as CJS only but stamps __esModule = true on its
+// export object, so tsup's __toESM helper neither synthesizes a `default`
+// property (it sees the __esModule marker and trusts it) nor preserves
+// the named `Terminal` export through a plain ESM-style
+// `import { Terminal } from '@xterm/headless'`. The first symptom we saw
+// from this was the published `adhdev` CLI exploding with
+// "Named export 'Terminal' not found" inside the mcp ipc bootstrap.
+//
+// Pull Terminal off the namespace import (which tsup compiles into a
+// shim that *does* see the package's own Terminal property) instead.
+// Type-only import keeps the .d.ts surface honest.
+import type { Terminal as TerminalType } from '@xterm/headless';
+import * as xtermHeadlessNs from '@xterm/headless';
+const TerminalCtor: { new (...args: unknown[]): TerminalType } =
+    (xtermHeadlessNs as any).Terminal
+    ?? (xtermHeadlessNs as any).default?.Terminal;
+import { NodePtyTransportFactory, type PtyRuntimeTransport, type PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+
+export interface TerminalAdapterOpts {
+    binary: string;
+    args?: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+    /** Coalesce screen snapshots: emit on_screen_changed at most this often. */
+    screenChangeDebounceMs?: number;
+    /** tick() period. 0 disables ticks. */
+    tickIntervalMs?: number;
+    /**
+     * Optional PTY transport factory. When the daemon supplies a
+     * SessionHostPtyTransportFactory (standalone runs the PTY inside the
+     * session-host so the runtime/<sid>/snapshot endpoint can serve it),
+     * forward it here. Without it the PTY spawns locally inside the
+     * daemon process and the dashboard's terminal pane reports
+     * "Runtime terminal unavailable: Unknown session".
+     */
+    transportFactory?: PtyTransportFactory;
+}
+
+export interface TerminalAdapterHandlers {
+    init?(info: { pid: number }): void;
+    on_pty_data?(chunk: string): void;
+    on_screen_changed?(snapshot: string): void;
+    tick?(): void;
+    on_exit?(info: { exitCode: number }): void;
+}
+
+export class TerminalAdapter {
+    private term: TerminalType;
+    private pty: PtyRuntimeTransport | null = null;
+    private factory: PtyTransportFactory;
+    private cols: number;
+    private rows: number;
+    private screenDebounceMs: number;
+    private tickIntervalMs: number;
+    private screenTimer: ReturnType<typeof setTimeout> | null = null;
+    private tickTimer: ReturnType<typeof setInterval> | null = null;
+    private lastScreen = '';
+
+    constructor(
+        private readonly opts: TerminalAdapterOpts,
+        private readonly handlers: TerminalAdapterHandlers,
+    ) {
+        this.cols = opts.cols ?? 100;
+        this.rows = opts.rows ?? 30;
+        this.screenDebounceMs = opts.screenChangeDebounceMs ?? 80;
+        this.tickIntervalMs = opts.tickIntervalMs ?? 0;
+        this.factory = opts.transportFactory ?? new NodePtyTransportFactory();
+        this.term = new TerminalCtor({ cols: this.cols, rows: this.rows, allowProposedApi: true, scrollback: 1000 });
+    }
+
+    start(): void {
+        this.pty = this.factory.spawn(this.opts.binary, this.opts.args ?? [], {
+            cwd: this.opts.cwd,
+            env: { ...process.env, ...(this.opts.env ?? {}) } as Record<string, string>,
+            cols: this.cols,
+            rows: this.rows,
+        });
+        this.handlers.init?.({ pid: this.pty.pid });
+        this.pty.onData((chunk) => this.onChunk(chunk));
+        this.pty.onExit((info) => {
+            this.stopTimers();
+            this.handlers.on_exit?.({ exitCode: typeof info.exitCode === 'number' ? info.exitCode : 0 });
+            this.pty = null;
+        });
+        if (this.tickIntervalMs > 0) {
+            this.tickTimer = setInterval(() => this.handlers.tick?.(), this.tickIntervalMs);
+        }
+    }
+
+    send_keys(s: string): void {
+        this.pty?.write(s);
+    }
+
+    resize(cols: number, rows: number): void {
+        this.cols = cols; this.rows = rows;
+        this.pty?.resize(cols, rows);
+        this.term.resize(cols, rows);
+    }
+
+    snapshot(): string {
+        return this.lastScreen || this.computeScreen();
+    }
+
+    getCursorPosition(): { row: number; col: number } {
+        const buf = this.term.buffer.active;
+        return {
+            row: Math.max(0, (buf as any).cursorY ?? 0),
+            col: Math.max(0, (buf as any).cursorX ?? 0),
+        };
+    }
+
+    kill(): void {
+        this.stopTimers();
+        try { this.pty?.kill(); } catch { /* ignore */ }
+        this.pty = null;
+        this.term.dispose();
+    }
+
+    private onChunk(chunk: string): void {
+        try { this.handlers.on_pty_data?.(chunk); } catch { /* user side */ }
+        this.term.write(chunk);
+        // Coalesce snapshot emission — rapid bursts shouldn't fire 200x.
+        if (this.screenTimer) return;
+        this.screenTimer = setTimeout(() => {
+            this.screenTimer = null;
+            const snap = this.computeScreen();
+            if (snap === this.lastScreen) return;
+            this.lastScreen = snap;
+            try { this.handlers.on_screen_changed?.(snap); } catch { /* user side */ }
+        }, this.screenDebounceMs);
+    }
+
+    private computeScreen(): string {
+        const buf = this.term.buffer.active;
+        const out: string[] = [];
+        for (let y = 0; y < buf.length; y += 1) {
+            const line = buf.getLine(y);
+            if (!line) continue;
+            out.push(line.translateToString(true));
+        }
+        while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+        return out.join('\n');
+    }
+
+    private stopTimers(): void {
+        if (this.screenTimer) { clearTimeout(this.screenTimer); this.screenTimer = null; }
+        if (this.tickTimer)   { clearInterval(this.tickTimer); this.tickTimer = null; }
+    }
+}