aec-agent 1.0.0

package/dist/components/sandbox-hub/docker/sandbox-helper.js

@@ -0,0 +1,442 @@
+// ---------------------------------------------------------------------------
+// Sandbox helper — a small Node program installed into every Docker sandbox at
+// /tmp/.aec/helper.js (root-owned, read-only for the sandbox user) and run with
+// `docker exec` for each operation (A-60).
+//
+// It exists because path checks must happen WHERE THE FILES ARE: the host can
+// canonicalise "../x", but only the container can see symlinks. Every path is
+// resolved component by component (following links, including dangling ones)
+// and must stay inside the roots the host sends — otherwise "path_escape".
+//
+//   node helper.js           file operation: one JSON request on stdin,
+//                            one JSON response line on stdout
+//   node helper.js exec      command: JSON header line on stdin, then stdin is
+//                            held open; closing it kills the command's whole
+//                            process group. stdout starts with "AEC-OK\n" or
+//                            "AEC-ERR {json}\n", followed by the command output.
+//
+// Plain JavaScript (no template literals — this file embeds it in one), no
+// dependencies, Node >= 18. Images used for sandboxes must provide `node`.
+// ---------------------------------------------------------------------------
+/** Where the helper lives inside the container. */
+export const HELPER_PATH = "/tmp/.aec/helper.js";
+export const HELPER_SOURCE = String.raw `"use strict";
+const fs = require("fs");
+const posix = require("path").posix;
+const crypto = require("crypto");
+const cp = require("child_process");
+const os = require("os");
+
+class OpError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+function fail(code, message) { throw new OpError(code, message); }
+
+function within(p, roots) {
+  return roots.some((r) => p === r || p.startsWith(r === "/" ? "/" : r + "/"));
+}
+
+function fsError(err, label) {
+  if (err instanceof OpError) return err;
+  const c = err && err.code;
+  if (c === "ENOENT") return new OpError("not_found", label + " does not exist");
+  if (c === "ENOTDIR") return new OpError("invalid_path", label + ": a parent is not a directory");
+  if (c === "EISDIR") return new OpError("invalid_path", label + " is a directory");
+  if (c === "ELOOP") return new OpError("invalid_path", label + ": too many symlinks");
+  if (c === "ENAMETOOLONG") return new OpError("invalid_path", label + ": name too long");
+  if (c === "EACCES" || c === "EPERM" || c === "EROFS") return new OpError("policy_denied", label + ": permission denied");
+  if (c === "ENOSPC" || c === "EDQUOT" || c === "EFBIG") return new OpError("too_large", label + ": no space left in the sandbox");
+  return new OpError("environment_unavailable", label + ": " + (err && err.message ? err.message : String(err)));
+}
+
+// Follow symlinks one component at a time — also through missing tails and
+// dangling links, so a write cannot land outside via a link that points nowhere yet.
+function realPath(logical, roots) {
+  let resolved = "/";
+  const pending = logical.split("/").filter(Boolean);
+  let hops = 0;
+  while (pending.length) {
+    const part = pending.shift();
+    const next = posix.join(resolved, part);
+    let st = null;
+    try { st = fs.lstatSync(next); } catch (e) {
+      if (e.code !== "ENOENT" && e.code !== "ENOTDIR") throw fsError(e, logical);
+    }
+    if (st && st.isSymbolicLink()) {
+      if (++hops > 40) fail("invalid_path", "Too many symlinks resolving " + logical);
+      const target = fs.readlinkSync(next);
+      const absolute = target.startsWith("/") ? target : posix.join(resolved, target);
+      resolved = "/";
+      pending.unshift.apply(pending, absolute.split("/").filter(Boolean));
+    } else {
+      resolved = next;
+    }
+  }
+  const real = posix.normalize(resolved);
+  if (!within(real, roots)) {
+    fail("path_escape", "\"" + logical + "\" resolves through a symlink to a location outside the workspace");
+  }
+  return real;
+}
+
+function typeOf(st) {
+  if (st.isFile()) return "file";
+  if (st.isDirectory()) return "directory";
+  if (st.isSymbolicLink()) return "symlink";
+  return "other";
+}
+
+function sha256File(p) {
+  const hash = crypto.createHash("sha256");
+  const fd = fs.openSync(p, "r");
+  const buf = Buffer.allocUnsafe(1 << 20);
+  try {
+    let n;
+    while ((n = fs.readSync(fd, buf, 0, buf.length, null)) > 0) hash.update(buf.subarray(0, n));
+  } finally { fs.closeSync(fd); }
+  return hash.digest("hex");
+}
+
+function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^$\{\}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp("^" + escaped + "$");
+}
+
+function byName(a, b) { return a.name.localeCompare(b.name); }
+
+// Make a tree writable by its owner so rm can remove read-only folders an agent created.
+function makeWritable(p) {
+  let st;
+  try { st = fs.lstatSync(p); } catch (_) { return; }
+  if (!st.isDirectory()) return;
+  try { fs.chmodSync(p, st.mode | 0o700); } catch (_) {}
+  let names = [];
+  try { names = fs.readdirSync(p); } catch (_) {}
+  for (const name of names) makeWritable(posix.join(p, name));
+}
+
+const SEARCH_SKIP_DIRS = new Set([".git", "node_modules"]);
+const MAX_LINE_CHARS = 1000;
+
+const ops = {
+  read(q) {
+    const real = realPath(q.path, q.roots);
+    let st;
+    try { st = fs.statSync(real); } catch (e) { throw fsError(e, q.path); }
+    if (!st.isFile()) fail("invalid_path", "\"" + q.path + "\" is a " + typeOf(st) + ", not a file");
+    const ranged = q.startLine != null || q.endLine != null;
+    if (ranged && st.size > q.rangeMaxBytes) {
+      fail("too_large", "\"" + q.path + "\" is " + st.size + " bytes — too large to read by line range (limit " + q.rangeMaxBytes + ")");
+    }
+    const want = ranged ? Infinity : q.maxBytes;
+    const hash = crypto.createHash("sha256");
+    const keep = [];
+    let kept = 0;
+    let size = 0;
+    const fd = fs.openSync(real, "r");
+    const buf = Buffer.allocUnsafe(1 << 20);
+    try {
+      let n;
+      while ((n = fs.readSync(fd, buf, 0, buf.length, null)) > 0) {
+        const chunk = buf.subarray(0, n);
+        hash.update(chunk);
+        size += n;
+        if (kept < want) {
+          const take = chunk.subarray(0, Math.min(n, want - kept));
+          keep.push(Buffer.from(take));
+          kept += take.length;
+        }
+      }
+    } finally { fs.closeSync(fd); }
+    const data = Buffer.concat(keep);
+    let content;
+    let truncated = false;
+    if (ranged) {
+      const lines = data.toString("utf8").split("\n");
+      const start = Math.max(1, q.startLine == null ? 1 : q.startLine);
+      const end = Math.min(lines.length, q.endLine == null ? lines.length : q.endLine);
+      content = lines.slice(start - 1, end).join("\n");
+      truncated = start > 1 || end < lines.length;
+      const bytes = Buffer.from(content, "utf8");
+      if (bytes.length > q.maxBytes) {
+        content = bytes.subarray(0, q.maxBytes).toString("utf8");
+        truncated = true;
+      }
+    } else {
+      content = data.toString("utf8");
+      truncated = size > data.length;
+    }
+    return { path: real, content: content, size: size, truncated: truncated, sha256: hash.digest("hex") };
+  },
+
+  write(q) {
+    const real = realPath(q.path, q.roots);
+    let existing = null;
+    try { existing = fs.lstatSync(real); } catch (e) {
+      if (e.code !== "ENOENT" && e.code !== "ENOTDIR") throw fsError(e, q.path);
+    }
+    if (existing && !existing.isFile()) fail("invalid_path", "\"" + q.path + "\" is a " + typeOf(existing));
+    if (q.expectedSha256 != null) {
+      const current = existing ? sha256File(real) : null;
+      if (current !== q.expectedSha256) fail("conflict", "\"" + q.path + "\" changed since it was read (hash mismatch)");
+    }
+    const parent = posix.dirname(real);
+    let parentStat = null;
+    try { parentStat = fs.statSync(parent); } catch (e) {
+      if (e.code !== "ENOENT") throw fsError(e, parent);
+    }
+    if (!parentStat) {
+      if (q.createDirs === false) fail("not_found", "Directory \"" + parent + "\" does not exist");
+      try { fs.mkdirSync(parent, { recursive: true }); } catch (e) { throw fsError(e, parent); }
+    } else if (!parentStat.isDirectory()) {
+      fail("invalid_path", "\"" + parent + "\" is not a directory");
+    }
+    // Write to a temp file and rename: readers never see a half-written file.
+    const data = Buffer.from(q.content, "utf8");
+    const tmp = posix.join(parent, ".aec-write-" + process.pid + "-" + crypto.randomBytes(4).toString("hex"));
+    try {
+      fs.writeFileSync(tmp, data, { flag: "wx", mode: existing ? existing.mode & 0o7777 : 0o644 });
+      fs.renameSync(tmp, real);
+    } catch (e) {
+      try { fs.unlinkSync(tmp); } catch (_) {}
+      throw fsError(e, q.path);
+    }
+    return {
+      path: real,
+      bytes: data.length,
+      sha256: crypto.createHash("sha256").update(data).digest("hex"),
+      created: !existing,
+    };
+  },
+
+  stat(q) {
+    const real = realPath(q.path, q.roots);
+    let st;
+    try { st = fs.statSync(real); } catch (e) {
+      if (e.code === "ENOENT" || e.code === "ENOTDIR") return null;
+      throw fsError(e, q.path);
+    }
+    return { path: real, type: typeOf(st), size: st.isFile() ? st.size : 0, modifiedAt: Math.round(st.mtimeMs) };
+  },
+
+  list(q) {
+    const real = realPath(q.path, q.roots);
+    let st;
+    try { st = fs.statSync(real); } catch (e) { throw fsError(e, q.path); }
+    if (!st.isDirectory()) fail("invalid_path", "\"" + q.path + "\" is not a directory");
+    const entries = [];
+    let truncated = false;
+    const walk = (dir, top) => {
+      let children;
+      try { children = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) {
+        if (top) throw fsError(e, q.path);
+        return; // unreadable subfolder: skipped, not fatal
+      }
+      children.sort(byName);
+      for (const d of children) {
+        if (!q.includeHidden && d.name.startsWith(".")) continue;
+        if (entries.length >= q.maxEntries) { truncated = true; return; }
+        const p = posix.join(dir, d.name);
+        const type = d.isFile() ? "file" : d.isDirectory() ? "directory" : d.isSymbolicLink() ? "symlink" : "other";
+        let size = 0;
+        if (type === "file") { try { size = fs.lstatSync(p).size; } catch (_) {} }
+        entries.push({ path: p, name: d.name, type: type, size: size });
+        // Symlinks are listed, never followed.
+        if (q.recursive && type === "directory") walk(p, false);
+        if (truncated) return;
+      }
+    };
+    walk(real, true);
+    return { entries: entries, truncated: truncated };
+  },
+
+  search(q) {
+    const base = realPath(q.path, q.roots);
+    let matcher;
+    if (q.literal === false) {
+      let re;
+      try { re = new RegExp(q.pattern, q.caseSensitive === false ? "i" : ""); } catch (e) {
+        fail("invalid_argument", "Invalid regular expression: " + e.message);
+      }
+      matcher = (line) => re.test(line);
+    } else if (q.caseSensitive === false) {
+      const needle = q.pattern.toLowerCase();
+      matcher = (line) => line.toLowerCase().includes(needle);
+    } else {
+      matcher = (line) => line.includes(q.pattern);
+    }
+    const nameFilter = q.glob ? globToRegExp(q.glob) : null;
+    const deadline = Date.now() + q.timeBudgetMs;
+    const matches = [];
+    let truncated = false;
+
+    const scan = (p, size) => {
+      if (nameFilter && !nameFilter.test(posix.basename(p))) return;
+      if (size > q.maxFileBytes) return;
+      let buf;
+      try { buf = fs.readFileSync(p); } catch (_) { return; }
+      if (buf.subarray(0, 8000).includes(0)) return; // binary
+      const lines = buf.toString("utf8").split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        if (!matcher(lines[i])) continue;
+        if (matches.length >= q.maxMatches) { truncated = true; return; }
+        const text = lines[i].length > MAX_LINE_CHARS ? lines[i].slice(0, MAX_LINE_CHARS) : lines[i];
+        matches.push({ path: p, line: i + 1, text: text });
+      }
+    };
+    const walk = (dir) => {
+      if (Date.now() > deadline) { truncated = true; return; }
+      let children;
+      try { children = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+      children.sort(byName);
+      for (const d of children) {
+        if (truncated) return;
+        const p = posix.join(dir, d.name);
+        if (d.isDirectory()) {
+          if (!SEARCH_SKIP_DIRS.has(d.name)) walk(p);
+        } else if (d.isFile()) {
+          let size;
+          try { size = fs.lstatSync(p).size; } catch (_) { continue; }
+          scan(p, size);
+        }
+      }
+    };
+
+    let st;
+    try { st = fs.statSync(base); } catch (e) { throw fsError(e, q.path); }
+    if (st.isDirectory()) walk(base);
+    else if (st.isFile()) scan(base, st.size);
+    return { matches: matches, truncated: truncated };
+  },
+
+  mkdir(q) {
+    for (const p of q.paths) {
+      const real = realPath(p, q.roots);
+      try { fs.mkdirSync(real, { recursive: true }); } catch (e) { throw fsError(e, p); }
+    }
+    return {};
+  },
+
+  remove(q) {
+    const real = realPath(q.path, q.roots);
+    makeWritable(real);
+    try { fs.rmSync(real, { recursive: true, force: true }); } catch (e) { throw fsError(e, q.path); }
+    return {};
+  },
+};
+
+function runOperation() {
+  const chunks = [];
+  process.stdin.on("data", (c) => chunks.push(c));
+  process.stdin.on("end", () => {
+    let response;
+    try {
+      const q = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      const op = Object.prototype.hasOwnProperty.call(ops, q.op) ? ops[q.op] : null;
+      if (!op) fail("invalid_argument", "Unknown operation " + q.op);
+      response = { ok: true, result: op(q) };
+    } catch (e) {
+      const err = fsError(e, "operation");
+      response = { ok: false, code: err.code, message: err.message };
+    }
+    process.stdout.write(JSON.stringify(response) + "\n", () => process.exit(0));
+  });
+}
+
+function runExec() {
+  let header = "";
+  let started = false;
+  let child = null;
+  let killed = false;
+  let finished = false;
+
+  const kill = () => {
+    if (!child || !child.pid || killed) return;
+    killed = true;
+    // Negative pid = the whole process group, so children of the command die too.
+    try { process.kill(-child.pid, "SIGKILL"); } catch (_) {
+      try { child.kill("SIGKILL"); } catch (_) {}
+    }
+  };
+  const finish = (code) => {
+    if (finished) return;
+    finished = true;
+    process.stdout.write("", () => process.exit(code));
+  };
+
+  // The host closes stdin to stop the command (timeout, cancel, output cap).
+  process.stdin.on("end", () => {
+    if (!started) process.exit(2);
+    kill();
+  });
+  process.stdin.on("data", (chunk) => {
+    if (started) return;
+    header += chunk.toString("utf8");
+    const nl = header.indexOf("\n");
+    if (nl === -1) return;
+    started = true;
+    start(JSON.parse(header.slice(0, nl)));
+  });
+
+  function start(q) {
+    let cwd;
+    try {
+      cwd = realPath(q.cwd, q.roots);
+      let st;
+      try { st = fs.statSync(cwd); } catch (e) { throw fsError(e, q.cwd); }
+      if (!st.isDirectory()) fail("invalid_path", "\"" + q.cwd + "\" is not a directory");
+    } catch (e) {
+      const err = fsError(e, q.cwd);
+      process.stdout.write("AEC-ERR " + JSON.stringify({ code: err.code, message: err.message }) + "\n", () => process.exit(0));
+      finished = true;
+      return;
+    }
+
+    // Only the container's PATH/HOME plus what the request passes — never the server's env.
+    const env = {
+      PATH: process.env.PATH || "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+      HOME: process.env.HOME || "/tmp",
+      LANG: "C.UTF-8",
+    };
+    Object.assign(env, q.env || {});
+    const argv = q.shell ? ["/bin/sh", "-c", q.command.join(" ")] : q.command;
+
+    process.stdout.write("AEC-OK\n");
+    child = cp.spawn(argv[0], argv.slice(1), { cwd: cwd, env: env, detached: true, stdio: ["pipe", "pipe", "pipe"] });
+
+    // One byte over the cap is passed through so the host can tell the output was cut.
+    let budget = q.maxOutputBytes + 1;
+    const pipe = (src, dst) => {
+      src.on("data", (d) => {
+        if (budget <= 0) return;
+        const piece = d.length > budget ? d.subarray(0, budget) : d;
+        budget -= piece.length;
+        dst.write(piece);
+        if (budget <= 0) kill();
+      });
+    };
+    pipe(child.stdout, process.stdout);
+    pipe(child.stderr, process.stderr);
+    child.stdin.on("error", () => {});
+    child.stdin.end(q.stdin || "");
+
+    // Backstop: the host normally stops the command first.
+    const timer = setTimeout(kill, q.timeoutMs + 1000);
+    child.on("error", (e) => {
+      clearTimeout(timer);
+      const notFound = e.code === "ENOENT";
+      process.stderr.write(argv[0] + ": " + (notFound ? "command not found" : e.message) + "\n");
+      finish(notFound ? 127 : 126);
+    });
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      if (!child.pid) return; // spawn failed — reported by "error"
+      finish(code != null ? code : 128 + (os.constants.signals[signal] || 9));
+    });
+  }
+}
+
+if (process.argv[2] === "exec") runExec();
+else runOperation();
+`;
+//# sourceMappingURL=sandbox-helper.js.map

package/dist/components/sandbox-hub/docker/sandbox-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-helper.js","sourceRoot":"","sources":["../../../../src/components/sandbox-hub/docker/sandbox-helper.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,gFAAgF;AAChF,2CAA2C;AAC3C,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,EAAE;AACF,wEAAwE;AACxE,8DAA8D;AAC9D,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,iFAAiF;AACjF,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,8EAA8E;AAE9E,mDAAmD;AACnD,MAAM,CAAC,MAAM,WAAW,GAAG,qBAAqB,CAAC;AAEjD,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkatC,CAAC"}

package/dist/components/sandbox-hub/docker/types.d.ts

@@ -0,0 +1,26 @@
+import type { SandboxLimits } from "../types/sandbox.js";
+import type { ResourceLimits } from "../types/provider.js";
+/** Settings for DockerSandboxProvider — host code only, never from agent profiles. */
+export interface DockerSandboxProviderOptions {
+    /** docker CLI binary. Default "docker". */
+    dockerPath?: string;
+    /** Prefix for container and volume names. Default "aec-sandbox" (→ "aec-sandbox-shared", "aec-sandbox-own-<agentId>"). */
+    namePrefix?: string;
+    /** Image when a spec names none. Default AEC_SANDBOX_IMAGE. Every image must provide `node` (>= 18). */
+    defaultImage?: string;
+    /** uid:gid every command and file operation runs as. Default "1000:1000" (`node` in aec-sandbox). */
+    user?: string;
+    /** Container resources when a spec sets none. Default 2 cpus, 2048 MB, 256 processes. */
+    defaultResources?: Partial<ResourceLimits>;
+    /** Size of the tmpfs at /tmp (wiped when the container restarts). Default "256m". */
+    tmpfsSize?: string;
+    /** Per-operation ceilings (read/write/list/search/exec). */
+    limits?: Partial<SandboxLimits>;
+    /** Build AEC_SANDBOX_IMAGE from the bundled Dockerfile when it is missing. Default true. */
+    buildDefaultImage?: boolean;
+    /** `docker pull` other missing images. Default true. */
+    pullImages?: boolean;
+    /** Ceiling for one file operation (read, write, list, search). Default 60 s. */
+    operationTimeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/sandbox-hub/docker/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/components/sandbox-hub/docker/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,sFAAsF;AACtF,MAAM,WAAW,4BAA4B;IAC3C,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0HAA0H;IAC1H,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAC3C,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;IAChC,4FAA4F;IAC5F,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B"}

package/dist/components/sandbox-hub/docker/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/components/sandbox-hub/docker/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/components/sandbox-hub/docker/types.ts"],"names":[],"mappings":""}

package/dist/components/sandbox-hub/host/host-sandbox-provider.d.ts

@@ -0,0 +1,34 @@
+import type { Sandbox, SandboxLimits } from "../types/sandbox.js";
+import type { CreateSandboxContext, SandboxProvider, SandboxSpec } from "../types/provider.js";
+/** Per-operation ceilings of a host sandbox (overridable via options.limits). */
+export declare const HOST_DEFAULT_LIMITS: SandboxLimits;
+export interface HostSandboxProviderOptions {
+    /** Absolute folder on the server machine that holds every host sandbox. Set by the host, never by a profile. */
+    root: string;
+    limits?: Partial<SandboxLimits>;
+}
+/**
+ * Host sandboxes: real folders on the server machine (not isolated).
+ *
+ *   own sandbox      <root>/<agentId>             the whole /workspace
+ *   shared sandbox   <root>/.shared/agents/<id>   one folder per agent
+ *
+ * Files are plain files — they survive restarts and can be opened from the machine.
+ * Commands run as the server's user, so the default approval policy asks the user
+ * before every write and command in a host sandbox.
+ */
+export declare class HostSandboxProvider implements SandboxProvider {
+    readonly name = "sandbox:host";
+    readonly version = "1.0.0";
+    readonly kind: "host";
+    readonly root: string;
+    private limits;
+    constructor(options: HostSandboxProviderOptions);
+    create(spec: SandboxSpec, context: CreateSandboxContext): Promise<Sandbox>;
+    removeData(_spec: SandboxSpec, context: CreateSandboxContext, opts?: {
+        agentId?: string;
+    }): Promise<void>;
+    /** Host folder that logical /workspace maps to for this sandbox. */
+    baseFor(context: CreateSandboxContext): string;
+}
+//# sourceMappingURL=host-sandbox-provider.d.ts.map

package/dist/components/sandbox-hub/host/host-sandbox-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-sandbox-provider.d.ts","sourceRoot":"","sources":["../../../../src/components/sandbox-hub/host/host-sandbox-provider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAG/F,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,EAAE,aAOjC,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,gHAAgH;IAChH,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,OAAO,WAAW;IAC3B,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAgB;IAE9B,YAAY,OAAO,EAAE,0BAA0B,EAM9C;IAEK,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyB/E;IAEK,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,oBAAoB,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlH;IAED,oEAAoE;IACpE,OAAO,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAQ7C;CACF"}

package/dist/components/sandbox-hub/host/host-sandbox-provider.js

@@ -0,0 +1,81 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+import { SandboxError } from "../../../kernel/errors/sandbox-error.js";
+import { AGENTS_DIR, assertSafeAgentId, WORKSPACE_ROOT } from "../logical-path.js";
+import { HostSandbox } from "./host-sandbox.js";
+/** Per-operation ceilings of a host sandbox (overridable via options.limits). */
+export const HOST_DEFAULT_LIMITS = {
+    maxReadBytes: 2_000_000,
+    maxWriteBytes: 5_000_000,
+    maxListEntries: 5_000,
+    maxSearchMatches: 500,
+    maxExecTimeoutMs: 10 * 60_000,
+    maxExecOutputBytes: 2_000_000,
+};
+/**
+ * Host sandboxes: real folders on the server machine (not isolated).
+ *
+ *   own sandbox      <root>/<agentId>             the whole /workspace
+ *   shared sandbox   <root>/.shared/agents/<id>   one folder per agent
+ *
+ * Files are plain files — they survive restarts and can be opened from the machine.
+ * Commands run as the server's user, so the default approval policy asks the user
+ * before every write and command in a host sandbox.
+ */
+export class HostSandboxProvider {
+    name = "sandbox:host";
+    version = "1.0.0";
+    kind = "host";
+    root;
+    limits;
+    constructor(options) {
+        if (!options.root || !path.isAbsolute(options.root)) {
+            throw new Error(`HostSandboxProvider needs an absolute root folder (got "${options.root}")`);
+        }
+        this.root = path.resolve(options.root);
+        this.limits = { ...HOST_DEFAULT_LIMITS, ...options.limits };
+    }
+    async create(spec, context) {
+        if (spec.kind !== "host") {
+            throw new SandboxError(`HostSandboxProvider cannot create "${spec.kind}" sandboxes`, "provider_unavailable", context.id);
+        }
+        const base = this.baseFor(context);
+        try {
+            await fs.mkdir(base, { recursive: true });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new SandboxError(`Cannot create host folder "${base}": ${message}`, "environment_unavailable", context.id);
+        }
+        return new HostSandbox(context.id, {
+            kind: "host",
+            isolated: false,
+            // Commands run on the server machine with its network.
+            network: "full",
+            persistent: true,
+            tenancy: context.tenancy,
+            os: process.platform === "win32" ? "windows" : process.platform === "darwin" ? "darwin" : "linux",
+        }, this.limits, base);
+    }
+    async removeData(_spec, context, opts = {}) {
+        if (opts.agentId && context.tenancy === "shared") {
+            assertSafeAgentId(opts.agentId);
+            const rel = path.posix.relative(WORKSPACE_ROOT, `${AGENTS_DIR}/${opts.agentId}`);
+            await fs.rm(path.join(this.baseFor(context), ...rel.split("/")), { recursive: true, force: true });
+            return;
+        }
+        await fs.rm(this.baseFor(context), { recursive: true, force: true });
+    }
+    /** Host folder that logical /workspace maps to for this sandbox. */
+    baseFor(context) {
+        if (context.tenancy === "own") {
+            if (!context.agentId)
+                throw new SandboxError("An own host sandbox needs an agent id", "invalid_argument", context.id);
+            assertSafeAgentId(context.agentId);
+            return path.join(this.root, context.agentId);
+        }
+        // Agent ids never start with "." (assertSafeAgentId), so this cannot collide with an own folder.
+        return path.join(this.root, ".shared");
+    }
+}
+//# sourceMappingURL=host-sandbox-provider.js.map

package/dist/components/sandbox-hub/host/host-sandbox-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-sandbox-provider.js","sourceRoot":"","sources":["../../../../src/components/sandbox-hub/host/host-sandbox-provider.ts"],"names":[],"mappings":"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"}

package/dist/components/sandbox-hub/host/host-sandbox.d.ts

@@ -0,0 +1,22 @@
+import type { Sandbox, SandboxCapability, SandboxLimits, SandboxTraits, SandboxView } from "../types/sandbox.js";
+export declare class HostSandbox implements Sandbox {
+    readonly id: string;
+    readonly traits: SandboxTraits;
+    readonly limits: SandboxLimits;
+    /** Host folder that logical /workspace maps to. */
+    readonly base: string;
+    readonly capabilities: ReadonlySet<SandboxCapability>;
+    disposed: boolean;
+    constructor(id: string, traits: SandboxTraits, limits: SandboxLimits, 
+    /** Host folder that logical /workspace maps to. */
+    base: string);
+    /** Logical path (already checked against roots) → host path. */
+    toHost(logical: string): string;
+    forAgent(agentId: string): Promise<SandboxView>;
+    health(): Promise<"ready" | "unavailable">;
+    removeAgentData(agentId: string): Promise<void>;
+    dispose(opts?: {
+        removeData?: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=host-sandbox.d.ts.map

package/dist/components/sandbox-hub/host/host-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-sandbox.d.ts","sourceRoot":"","sources":["../../../../src/components/sandbox-hub/host/host-sandbox.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAYV,OAAO,EACP,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,WAAW,EAKZ,MAAM,qBAAqB,CAAC;AA4F7B,qBAAa,WAAY,YAAW,OAAO;IAKvC,QAAQ,CAAC,EAAE,EAAE,MAAM;IACnB,QAAQ,CAAC,MAAM,EAAE,aAAa;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM;IARvB,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAA6B;IAClF,QAAQ,UAAS;IAEjB,YACW,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,aAAa;IAC9B,mDAAmD;IAC1C,IAAI,EAAE,MAAM,EACnB;IAEJ,gEAAgE;IAChE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG9B;IAEK,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CASpD;IAEK,MAAM,IAAI,OAAO,CAAC,OAAO,GAAG,aAAa,CAAC,CAG/C;IAEK,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpD;IAEK,OAAO,CAAC,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG5D;CACF"}