lazyclaw 4.3.0 → 5.0.0

package/providers/gemini_cli.mjs

@@ -0,0 +1,179 @@
+// Gemini subscription/CLI provider (no API key).
+//
+// Spawns the local `gemini` CLI binary (the Google Gemini CLI shipped
+// from npm: @google/gemini-cli) in non-interactive mode:
+//
+//   gemini --skip-trust -p "<prompt>" -o json [-m model]
+//
+// Auth is whatever `gemini` is already signed into on the host —
+// Google account / Vertex / AI Studio session — so no GEMINI_API_KEY
+// is required and no key lands in the lazyclaw config. This is the
+// CLI counterpart to providers/gemini.mjs (which talks to the
+// Generative Language API and needs an API key).
+//
+// Output shape (one JSON object on stdout):
+//   { session_id, response: "<text>", stats: { models: {...} } }
+//
+// We capture stdout in full, parse the JSON once, and yield the
+// `response` string in a single chunk. The orchestrator and chat
+// REPL both treat AsyncIterable<string> as their only contract, so
+// non-streaming is transparent to callers.
+//
+// Why `--skip-trust` is hard-coded: lazyclaw orchestrator / workflow
+// subprocesses commonly run from /tmp or scratch dirs which gemini's
+// trusted-folder policy rejects. We are spawning gemini ourselves with
+// our own prompt, so the policy adds friction without security value.
+
+import { spawnSandboxed } from '../sandbox.mjs';
+
+class AbortError extends Error {
+  constructor(message = 'aborted') {
+    super(message);
+    this.name = 'AbortError';
+    this.code = 'ABORT';
+  }
+}
+
+class CliMissingError extends Error {
+  constructor() {
+    super('gemini CLI not found in PATH — install @google/gemini-cli or use the gemini API provider');
+    this.name = 'GeminiCliMissingError';
+    this.code = 'CLI_MISSING';
+  }
+}
+
+class CliExitError extends Error {
+  constructor(code, signal, stderr) {
+    super(`gemini CLI exited ${code ?? signal}: ${String(stderr).slice(0, 400)}`);
+    this.name = 'GeminiCliExitError';
+    this.code = 'CLI_EXIT';
+    this.exitCode = code;
+    this.signal = signal;
+    this.stderr = stderr;
+  }
+}
+
+// `gemini -m` accepts the marketing model id directly (e.g. gemini-2.5-pro),
+// so unlike claude_cli no alias map is needed. We still normalize a few
+// shorthand inputs that users have typed in chat config.
+const _ALIASES = {
+  pro: 'gemini-2.5-pro',
+  flash: 'gemini-2.5-flash',
+  'gemini-pro': 'gemini-2.5-pro',
+  'gemini-flash': 'gemini-2.5-flash',
+};
+
+// Drop cross-vendor model ids (claude-*, gpt-*, o1/o3/o4-*) silently so the
+// CLI falls back to its own default. The orchestrator workflow happily
+// dispatches the same cfg.model to every worker, and `providers test`
+// forwards cfg.model verbatim — both would otherwise crash here with
+// "ModelNotFoundError" the moment cfg.model is anything Anthropic/OpenAI.
+function resolveModel(model) {
+  if (!model) return '';
+  const lower = String(model).toLowerCase();
+  if (_ALIASES[lower]) return _ALIASES[lower];
+  if (lower.startsWith('gemini') || lower.startsWith('gemma')) return String(model);
+  return '';
+}
+
+function buildPrompt(messages, system) {
+  const parts = [];
+  if (system) parts.push(`[System instructions: ${system}]`);
+  for (const m of messages) {
+    if (!m || !m.content) continue;
+    if (m.role === 'system' && !system) parts.push(`[System instructions: ${m.content}]`);
+    else if (m.role === 'user') parts.push(`User: ${m.content}`);
+    else if (m.role === 'assistant') parts.push(`Assistant: ${m.content}`);
+  }
+  return parts.length ? parts.join('\n') + '\n\nAssistant:' : '';
+}
+
+// Pull usage totals out of the gemini stats block. The shape is
+// `stats.models["<model-id>"].api` + `.tokens`. We sum across all
+// model entries since a single response can route through multiple
+// (e.g. flash for reasoning + pro for the final answer).
+function extractUsage(stats) {
+  if (!stats || typeof stats !== 'object') return null;
+  const models = stats.models || {};
+  let input = 0, output = 0;
+  for (const m of Object.values(models)) {
+    const t = m?.tokens || {};
+    input  += (t.prompt ?? t.input ?? 0);
+    output += (t.candidates ?? t.output ?? 0);
+  }
+  if (!input && !output) return null;
+  return { inputTokens: input, outputTokens: output, totalCostUsd: 0 };
+}
+
+export const geminiCliProvider = {
+  name: 'gemini-cli',
+  async *sendMessage(messages, opts = {}) {
+    const bin = opts.bin || 'gemini';
+    const prompt = buildPrompt(messages, opts.system || messages.find(m => m.role === 'system')?.content);
+    if (!prompt) return;
+
+    const args = ['--skip-trust', '-p', prompt, '-o', 'json'];
+    const model = resolveModel(opts.model);
+    if (model) args.push('-m', model);
+
+    if (opts.signal?.aborted) throw new AbortError('aborted before spawn');
+
+    let proc;
+    try {
+      proc = spawnSandboxed(opts.sandbox || null, bin, args, {
+        cwd: opts.cwd || process.cwd(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, GEMINI_CLI_TRUST_WORKSPACE: 'true' },
+      });
+    } catch (err) {
+      if (err && err.code === 'ENOENT') throw new CliMissingError();
+      throw err;
+    }
+
+    const onAbort = () => { try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ } };
+    if (opts.signal) opts.signal.addEventListener('abort', onAbort);
+
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.setEncoding('utf8');
+    proc.stderr.setEncoding('utf8');
+    proc.stdout.on('data', (c) => { stdout += c; });
+    proc.stderr.on('data', (c) => { stderr += c; });
+
+    const exitInfo = await new Promise((resolve) => {
+      proc.on('close', (code, signal) => resolve({ code, signal }));
+    });
+
+    try {
+      if (opts.signal?.aborted) throw new AbortError('aborted mid-run');
+      if (exitInfo.code !== 0) {
+        throw new CliExitError(exitInfo.code, exitInfo.signal, stderr || stdout);
+      }
+      // Gemini emits one JSON document; some installations prefix it
+      // with a "Ripgrep is not available. Falling back to GrepTool."
+      // line on stderr (harmless) and never touch stdout. Defensive
+      // parse: find the first `{` to skip any pre-banner noise.
+      const first = stdout.indexOf('{');
+      const payload = first >= 0 ? stdout.slice(first) : stdout;
+      let parsed;
+      try {
+        parsed = JSON.parse(payload);
+      } catch (err) {
+        throw new Error(`gemini CLI returned non-JSON stdout: ${err.message} :: ${payload.slice(0, 200)}`);
+      }
+      const text = typeof parsed.response === 'string' ? parsed.response : '';
+      if (text) yield text;
+      const usage = extractUsage(parsed.stats);
+      if (usage && typeof opts.onUsage === 'function') {
+        try { opts.onUsage(usage); } catch (_) { /* never break stream on usage callback */ }
+      }
+    } finally {
+      if (opts.signal) opts.signal.removeEventListener('abort', onAbort);
+      if (!proc.killed && exitInfo === null) {
+        try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
+      }
+    }
+  },
+};
+
+export { CliMissingError, CliExitError, AbortError, resolveModel, buildPrompt, extractUsage };

package/providers/registry.mjs

@@ -61,6 +61,61 @@ export { anthropicProvider, openaiProvider, ollamaProvider, geminiProvider, clau
 export { makeOpenAICompatProvider, fetchOpenAICompatModels };
 export { makeOrchestratorProvider };
 
+// ─── Phase A: trainer resolver (spec §2.3, §2.4, canonical C3/C9) ───
+//
+// resolveTrainer(cfg, opts) returns { provider, model } for synthesis /
+// reflection calls — split from the chat provider so users can route
+// learning to a cheap model or to a CLI-subscription worker.
+//
+// Rules:
+//   - cfg.trainer omitted → mirror chat (v4 compat).
+//   - cfg.trainer.provider === 'auto' → claude-cli when Pro/Max
+//     session detected, else mirror chat (canonical decision C9).
+//   - opts.useFallback → parse cfg.trainer.fallback ('provider:model')
+//     and use it; missing pieces inherit from chat.
+//   - All identifiers MUST be kebab-case in user-facing config (C3).
+
+export function parseProviderModel(spec) {
+  const s = String(spec || '');
+  const i = s.indexOf(':');
+  if (i < 0) return { provider: s || null, model: null };
+  return { provider: s.slice(0, i) || null, model: s.slice(i + 1) || null };
+}
+
+function _defaultDetectClaudeCli() {
+  // Phase A stub: real Pro/Max session detection arrives in Phase B
+  // (it requires reading the claude-cli OAuth token cache). Until
+  // then, treat presence of CLAUDE_CODE_OAUTH_TOKEN as a positive
+  // signal so users can opt-in explicitly.
+  return Boolean(process.env.CLAUDE_CODE_OAUTH_TOKEN);
+}
+
+export function resolveTrainer(cfg, opts = {}) {
+  const chatProvider = cfg && cfg.provider;
+  const chatModel = cfg && cfg.model;
+  const t = cfg && cfg.trainer;
+
+  if (!t || !t.provider) {
+    return { provider: chatProvider, model: chatModel };
+  }
+
+  if (opts.useFallback && t.fallback) {
+    const { provider, model } = parseProviderModel(t.fallback);
+    return {
+      provider: provider || chatProvider,
+      model: model || chatModel,
+    };
+  }
+
+  if (t.provider === 'auto') {
+    const detect = opts.detectClaudeCli || _defaultDetectClaudeCli;
+    if (detect()) return { provider: 'claude-cli', model: t.model || chatModel };
+    return { provider: chatProvider, model: t.model || chatModel };
+  }
+
+  return { provider: t.provider, model: t.model || chatModel };
+}
+
 // Built-in OpenAI-compatible vendors. Same wire format → one factory call
 // each. The picker treats these like first-class providers so users don't
 // have to walk through "+ Add a custom endpoint" for the popular ones.
@@ -431,10 +486,15 @@ export function resolveBuiltinEnvKey(provider) {
  * Split a unified "provider/model" string (OpenClaw style:
  * "anthropic/claude-opus-4-7"). Also accepts a bare model id and returns
  * provider=null so callers can fall back to a separately-stored provider.
+ *
+ * Renamed from `parseProviderModel` in v5.0 to free that name for the
+ * trainer fallback parser (which uses ':' as the separator — see spec
+ * §2.4). Callers that still need the slash form should import this.
+ *
  * @param {string} s
  * @returns {{ provider: string|null, model: string }}
  */
-export function parseProviderModel(s) {
+export function parseSlashProviderModel(s) {
   if (!s || typeof s !== 'string') return { provider: null, model: '' };
   const slash = s.indexOf('/');
   if (slash > 0) {

package/sandbox/base.mjs

@@ -0,0 +1,82 @@
+// sandbox/base.mjs — Sandbox + SandboxSession contracts.
+//
+// Spec ref: §0.1 C8 (6-enum), §6 (backend contract).
+// Every backend module (docker/local/ssh/singularity/modal/daytona)
+// exports a class extending Sandbox and returns SandboxSession from
+// open(). The session is the only object that holds resources
+// (sockets, child PIDs, remote workspace ids) — caller MUST call
+// close() in a finally block.
+
+export const SANDBOX_KINDS = Object.freeze([
+  'local', 'docker', 'ssh', 'singularity', 'modal', 'daytona',
+]);
+
+export class SandboxError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SandboxError';
+    this.code = code || 'SANDBOX_ERR';
+  }
+  toString() {
+    return `${this.name}[${this.code}]: ${this.message}`;
+  }
+}
+
+export class Sandbox {
+  /**
+   * @param {{kind: string} & Record<string, unknown>} spec
+   * @param {{_skipAbstract?: boolean}} [opts]
+   */
+  constructor(spec, opts = {}) {
+    if (new.target === Sandbox && !opts._skipAbstract) {
+      throw new SandboxError(
+        'Sandbox is abstract — instantiate a backend subclass',
+        'SANDBOX_ABSTRACT',
+      );
+    }
+    if (!spec || !SANDBOX_KINDS.includes(spec.kind)) {
+      throw new SandboxError(
+        `unknown sandbox kind "${spec && spec.kind}" — expected one of ${SANDBOX_KINDS.join(', ')}`,
+        'SANDBOX_BAD_KIND',
+      );
+    }
+    this.spec = spec;
+  }
+
+  /**
+   * Open a session. Subclasses MUST override.
+   * @returns {Promise<SandboxSession>}
+   */
+  async open() {
+    throw new SandboxError(`${this.constructor.name}.open() not implemented`, 'SANDBOX_NOT_IMPL');
+  }
+
+  /** Short human label for `lazyclaw sandbox list`. */
+  describe() { return `${this.spec.kind}`; }
+}
+
+export class SandboxSession {
+  /**
+   * Run an argv inside the sandbox.
+   * @param {string[]} argv
+   * @param {{cwd?: string, env?: Record<string,string>, stdio?: 'pipe'|'inherit', input?: string}} [opts]
+   * @returns {Promise<{code: number, stdout: string, stderr: string}>}
+   */
+  async exec(_argv, _opts) {
+    throw new SandboxError(`${this.constructor.name}.exec() not implemented`, 'SANDBOX_NOT_IMPL');
+  }
+
+  /**
+   * Spawn a long-running child within the sandbox. Returns a
+   * node:child_process-shaped object with stdin/stdout/stderr.
+   * Default: synthesise from exec() via streaming if backend allows.
+   */
+  async spawn(_argv, _opts) {
+    throw new SandboxError(`${this.constructor.name}.spawn() not implemented`, 'SANDBOX_NOT_IMPL');
+  }
+
+  /** Release resources. Idempotent. */
+  async close() {
+    throw new SandboxError(`${this.constructor.name}.close() not implemented`, 'SANDBOX_NOT_IMPL');
+  }
+}

package/sandbox/confiners/bubblewrap.mjs

@@ -0,0 +1,21 @@
+// sandbox/confiners/bubblewrap.mjs — Linux bwrap wrapper.
+
+import { execFileSync } from 'node:child_process';
+
+export function available() {
+  if (process.platform !== 'linux') return false;
+  try { execFileSync('bwrap', ['--version'], { stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+
+export function buildArgv(argv, opts = {}) {
+  const readOnly = opts.readOnly || ['/usr', '/lib', '/lib64', '/bin', '/etc'];
+  const readWrite = opts.readWrite || [process.cwd()];
+  const allowNet = opts.allowNet === true;
+  const out = ['bwrap', '--die-with-parent', '--proc', '/proc', '--dev', '/dev'];
+  for (const p of readOnly) out.push('--ro-bind', p, p);
+  for (const p of readWrite) out.push('--bind', p, p);
+  if (!allowNet) out.push('--unshare-net');
+  out.push('--unshare-pid', '--unshare-ipc', '--unshare-uts');
+  return [...out, ...argv];
+}

package/sandbox/confiners/firejail.mjs

@@ -0,0 +1,16 @@
+// sandbox/confiners/firejail.mjs — firejail wrapper.
+
+import { execFileSync } from 'node:child_process';
+
+export function available() {
+  if (process.platform !== 'linux') return false;
+  try { execFileSync('firejail', ['--version'], { stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+
+export function buildArgv(argv, opts = {}) {
+  const allowNet = opts.allowNet === true;
+  const out = ['firejail', '--quiet', '--private', '--caps.drop=all'];
+  out.push(allowNet ? '--net=eth0' : '--net=none');
+  return [...out, ...argv];
+}

package/sandbox/confiners/landlock.mjs

@@ -0,0 +1,14 @@
+// sandbox/confiners/landlock.mjs — Linux Landlock helper.
+//
+// Landlock is enforced from *inside* the process via the
+// landlock_create_ruleset() syscall. With no native bindings available
+// in plain Node, we currently emit the argv unchanged and let
+// downstream tooling (e.g. a future `lazyclaw-landlock-shim` binary)
+// install the ruleset. Returns argv unchanged on non-Linux.
+
+export function available() { return process.platform === 'linux'; }
+
+export function buildArgv(argv, _opts = {}) {
+  // Pass-through. Spec §0.1 C8 leaves room for a preloader binary.
+  return [...argv];
+}

package/sandbox/confiners/seatbelt.mjs

@@ -0,0 +1,28 @@
+// sandbox/confiners/seatbelt.mjs — macOS sandbox-exec wrapper.
+// Spec §0.1 C8: local.confiner sub-option.
+
+import { execFileSync } from 'node:child_process';
+
+export function available() {
+  if (process.platform !== 'darwin') return false;
+  try { execFileSync('sandbox-exec', ['-h'], { stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+
+export function buildArgv(argv, opts = {}) {
+  const readOnly = opts.readOnly || [];
+  const readWrite = opts.readWrite || [process.cwd()];
+  const allowNet = opts.allowNet === true;
+  const profile = [
+    '(version 1)',
+    '(deny default)',
+    '(allow process-fork)',
+    '(allow process-exec)',
+    '(allow signal)',
+    '(allow sysctl-read)',
+    allowNet ? '(allow network*)' : '(deny network*)',
+    ...readOnly.map(p => `(allow file-read* (subpath "${p}"))`),
+    ...readWrite.map(p => `(allow file-read* file-write* (subpath "${p}"))`),
+  ].join('\n');
+  return ['sandbox-exec', '-p', profile, ...argv];
+}

package/sandbox/daytona.mjs

@@ -0,0 +1,37 @@
+// sandbox/daytona.mjs — Daytona workspace wrapper.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { Sandbox, SandboxSession, SandboxError } from './base.mjs';
+
+export function buildDaytonaArgv(spec, argv) {
+  if (!spec || !spec.workspace) {
+    throw new SandboxError('daytona sandbox requires workspace', 'SANDBOX_BAD_SPEC');
+  }
+  const out = ['daytona', 'ssh', spec.workspace];
+  if (spec.persistent === false) out.push('--auto-stop=true');
+  out.push('--', ...argv);
+  return out;
+}
+
+class DaytonaSession extends SandboxSession {
+  constructor(spec) { super(); this.spec = spec; }
+  async exec(argv, opts = {}) {
+    const a = buildDaytonaArgv(this.spec, argv);
+    const r = spawnSync(a[0], a.slice(1), {
+      input: opts.input, env: { ...process.env, ...(opts.env || {}) },
+      stdio: opts.stdio || 'pipe', encoding: 'utf8',
+    });
+    return { code: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '' };
+  }
+  async spawn(argv, opts = {}) {
+    const a = buildDaytonaArgv(this.spec, argv);
+    return spawn(a[0], a.slice(1), opts);
+  }
+  async close() {}
+}
+
+export class DaytonaSandbox extends Sandbox {
+  constructor(spec) { super(spec); }
+  async open() { return new DaytonaSession(this.spec); }
+  describe() { return `daytona · ${this.spec.workspace}`; }
+}

package/sandbox/docker.mjs

@@ -0,0 +1,91 @@
+// sandbox/docker.mjs — Docker backend.
+//
+// Ported from the original single-file sandbox.mjs (v4.3). Behaviour
+// is byte-identical for parseSandboxSpec / buildDockerArgs /
+// spawnSandboxed; the new piece is the DockerSandbox class that
+// implements the §6 Sandbox interface.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { Sandbox, SandboxSession, SandboxError } from './base.mjs';
+
+function arrayify(v) {
+  if (v === undefined || v === null) return [];
+  return Array.isArray(v) ? v : [String(v)];
+}
+
+export function parseSandboxSpec(spec, flags = {}) {
+  if (!spec || /^(off|none|-)$/i.test(String(spec))) return null;
+  const m = String(spec).match(/^([a-z]+):(.+)$/i);
+  if (!m) throw new SandboxError(`bad sandbox spec "${spec}" — expected "docker:<image>"`, 'SANDBOX_BAD_SPEC');
+  const [, kind, rest] = m;
+  if (kind.toLowerCase() !== 'docker') {
+    throw new SandboxError(`unsupported sandbox kind "${kind}" — only "docker" parses via this shim`, 'SANDBOX_UNSUPPORTED');
+  }
+  return {
+    kind: 'docker',
+    image: rest.trim(),
+    network: flags['sandbox-network'] || 'none',
+    mounts: arrayify(flags['sandbox-mount']),
+    envPassthrough: arrayify(flags['sandbox-env']),
+  };
+}
+
+export function buildDockerArgs(spec, [bin, ...binArgs], opts = {}) {
+  if (!spec || spec.kind !== 'docker') {
+    throw new SandboxError('buildDockerArgs requires a docker spec', 'SANDBOX_BAD_SPEC');
+  }
+  const cwd = opts.cwd || process.cwd();
+  const args = [
+    'run', '--rm', '-i',
+    '--network', spec.network || 'none',
+    '-v', `${cwd}:${cwd}`,
+    '-w', cwd,
+  ];
+  for (const mount of spec.mounts || []) {
+    if (!mount.includes(':')) {
+      throw new SandboxError(`bad mount "${mount}" — expected host:container[:mode]`, 'SANDBOX_BAD_MOUNT');
+    }
+    args.push('-v', mount);
+  }
+  for (const envName of spec.envPassthrough || []) {
+    args.push('-e', envName);
+  }
+  args.push(spec.image, bin, ...binArgs);
+  return args;
+}
+
+export function spawnSandboxed(spec, bin, args, spawnOpts = {}) {
+  if (!spec) return spawn(bin, args, spawnOpts);
+  if (spec.kind !== 'docker') {
+    throw new SandboxError(`spawnSandboxed shim handles docker only; got "${spec.kind}"`, 'SANDBOX_UNSUPPORTED');
+  }
+  const dockerArgs = buildDockerArgs(spec, [bin, ...args], { cwd: spawnOpts.cwd });
+  return spawn('docker', dockerArgs, spawnOpts);
+}
+
+class DockerSession extends SandboxSession {
+  constructor(spec) { super(); this.spec = spec; this._closed = false; }
+
+  async exec(argv, opts = {}) {
+    const dockerArgv = buildDockerArgs(this.spec, argv, { cwd: opts.cwd });
+    const r = spawnSync('docker', dockerArgv, {
+      input: opts.input,
+      env: { ...process.env, ...(opts.env || {}) },
+      stdio: opts.stdio || 'pipe',
+      encoding: 'utf8',
+    });
+    return { code: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '' };
+  }
+
+  async spawn(argv, opts = {}) {
+    return spawnSandboxed(this.spec, argv[0], argv.slice(1), opts);
+  }
+
+  async close() { this._closed = true; }
+}
+
+export class DockerSandbox extends Sandbox {
+  constructor(spec) { super(spec); }
+  async open() { return new DockerSession(this.spec); }
+  describe() { return `docker · ${this.spec.image} · net=${this.spec.network}`; }
+}

package/sandbox/index.mjs

@@ -0,0 +1,67 @@
+// sandbox/index.mjs — config-driven backend resolver.
+//
+// Spec §0.1 C8 (6-enum), §1.7 (cfg.sandbox additive).
+//
+// Config schema (additive, all optional):
+//
+//   sandbox: {
+//     default: 'local' | 'docker' | 'ssh' | 'singularity' | 'modal' | 'daytona',
+//     local:        { confiner: 'none'|'seatbelt'|'bubblewrap'|'firejail'|'landlock',
+//                     readOnly?: string[], readWrite?: string[], allowNet?: boolean },
+//     docker:       { image, network?, mounts?: string[], envPassthrough?: string[] },
+//     ssh:          { host, user?, port?, identityFile? },
+//     singularity:  { image, bind?: string[], net?: boolean, useApptainer?: boolean },
+//     modal:        { app, region?, token?, idleWake?: boolean, host? },
+//     daytona:      { workspace, persistent?: boolean },
+//     bindings:     { '<workerName>': '<kind>' | { kind, ...overrides } },
+//   }
+
+import { SANDBOX_KINDS, SandboxError } from './base.mjs';
+import { LocalSandbox } from './local.mjs';
+import { DockerSandbox, parseSandboxSpec } from './docker.mjs';
+import { SshSandbox } from './ssh.mjs';
+import { SingularitySandbox } from './singularity.mjs';
+import { ModalSandbox } from './modal.mjs';
+import { DaytonaSandbox } from './daytona.mjs';
+
+const CTORS = {
+  local: LocalSandbox,
+  docker: DockerSandbox,
+  ssh: SshSandbox,
+  singularity: SingularitySandbox,
+  modal: ModalSandbox,
+  daytona: DaytonaSandbox,
+};
+
+export function listBackends() { return [...SANDBOX_KINDS]; }
+
+export { parseSandboxSpec };
+
+export function resolveSandbox(cfg, workerName) {
+  const sb = (cfg && cfg.sandbox) || {};
+  let kind = sb.default || 'local';
+  let overrides = {};
+
+  const binding = workerName && sb.bindings && sb.bindings[workerName];
+  if (binding) {
+    if (typeof binding === 'string') kind = binding;
+    else { kind = binding.kind || kind; overrides = binding; }
+  }
+
+  if (!CTORS[kind]) {
+    throw new SandboxError(
+      `unknown sandbox kind "${kind}" — expected one of ${SANDBOX_KINDS.join(', ')}`,
+      'SANDBOX_BAD_KIND',
+    );
+  }
+
+  const sectionDefaults = sb[kind] || {};
+  const spec = {
+    kind,
+    ...(kind === 'local' ? { confiner: 'none' } : {}),
+    ...sectionDefaults,
+    ...overrides,
+    kind,
+  };
+  return new CTORS[kind](spec);
+}

package/sandbox/local.mjs

@@ -0,0 +1,59 @@
+// sandbox/local.mjs — Local backend with pluggable confiner.
+// Spec §0.1 C8: confiner ∈ {none, seatbelt, bubblewrap, firejail, landlock}.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { Sandbox, SandboxSession, SandboxError } from './base.mjs';
+import * as seatbelt from './confiners/seatbelt.mjs';
+import * as bubblewrap from './confiners/bubblewrap.mjs';
+import * as firejail from './confiners/firejail.mjs';
+import * as landlock from './confiners/landlock.mjs';
+
+const CONFINERS = { seatbelt, bubblewrap, firejail, landlock };
+
+class LocalSession extends SandboxSession {
+  constructor(spec, confinerMod) {
+    super();
+    this.spec = spec;
+    this.confiner = confinerMod;
+  }
+
+  _wrap(argv) {
+    if (!this.confiner) return [...argv];
+    return this.confiner.buildArgv(argv, this.spec);
+  }
+
+  async exec(argv, opts = {}) {
+    const wrapped = this._wrap(argv);
+    const r = spawnSync(wrapped[0], wrapped.slice(1), {
+      input: opts.input,
+      cwd: opts.cwd,
+      env: { ...process.env, ...(opts.env || {}) },
+      stdio: opts.stdio || 'pipe',
+      encoding: 'utf8',
+    });
+    return { code: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '' };
+  }
+
+  async spawn(argv, opts = {}) {
+    const wrapped = this._wrap(argv);
+    return spawn(wrapped[0], wrapped.slice(1), opts);
+  }
+
+  async close() { /* no resources */ }
+}
+
+export class LocalSandbox extends Sandbox {
+  constructor(spec) {
+    super(spec);
+    const key = spec.confiner || 'none';
+    if (key !== 'none' && !(key in CONFINERS)) {
+      throw new SandboxError(`unknown confiner "${key}"`, 'SANDBOX_BAD_CONFINER');
+    }
+    this.confiner = key === 'none' ? null : CONFINERS[key];
+  }
+
+  async open() { return new LocalSession(this.spec, this.confiner); }
+  describe() {
+    return `local · confiner=${this.spec.confiner || 'none'}`;
+  }
+}