@capybara-hq/device 0.1.0-rc.14 → 0.1.0-rc.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/README.md +101 -157
  2. package/dist/api.d.ts +2 -2
  3. package/dist/args.d.ts +2 -8
  4. package/dist/args.js +2 -25
  5. package/dist/cli.d.ts +2 -11
  6. package/dist/cli.js +6 -61
  7. package/dist/client.d.ts +8 -45
  8. package/dist/client.js +25 -424
  9. package/dist/command-log.d.ts +14 -4
  10. package/dist/command-log.js +37 -1
  11. package/dist/commands/ceiling.d.ts +0 -2
  12. package/dist/commands/ceiling.js +3 -4
  13. package/dist/commands/login.d.ts +25 -1
  14. package/dist/commands/login.js +75 -61
  15. package/dist/commands/policy.d.ts +6 -8
  16. package/dist/commands/policy.js +30 -49
  17. package/dist/commands/start.d.ts +2 -17
  18. package/dist/commands/start.js +13 -53
  19. package/dist/exec/docker-operations.d.ts +2 -2
  20. package/dist/exec/docker-operations.js +4 -2
  21. package/dist/exec/docker.d.ts +37 -122
  22. package/dist/exec/docker.js +72 -717
  23. package/dist/exec/instance-binding.d.ts +4 -4
  24. package/dist/exec/linux-agent.js +30 -0
  25. package/dist/exec/linux-operation-backend.d.ts +5 -0
  26. package/dist/exec/linux-operation-backend.js +3 -1
  27. package/dist/exec/linux-operation-worker.d.ts +9 -0
  28. package/dist/exec/linux-operation-worker.js +11 -2
  29. package/dist/exec/mac-read-policy.d.ts +58 -0
  30. package/dist/exec/mac-read-policy.js +104 -0
  31. package/dist/exec/mac-self-check.d.ts +6 -3
  32. package/dist/exec/mac-self-check.js +28 -5
  33. package/dist/exec/operation-worker.d.ts +21 -2
  34. package/dist/exec/operation-worker.js +164 -43
  35. package/dist/exec/sandbox-check.d.ts +10 -0
  36. package/dist/exec/sandbox-check.js +18 -0
  37. package/dist/exec/sandbox-messages.d.ts +3 -11
  38. package/dist/exec/sandbox-messages.js +3 -18
  39. package/dist/exec/shared.d.ts +24 -47
  40. package/dist/exec/shared.js +53 -165
  41. package/dist/exec/types.d.ts +2 -66
  42. package/dist/exec/types.js +1 -1
  43. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +71 -12
  44. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js +18 -4
  45. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +6 -0
  46. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +4 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/concepts.md +9 -4
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/channel.md +1 -1
  49. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md +2 -0
  50. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/sandbox.md +1 -1
  51. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/plugin-format.md +1 -1
  52. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.d.ts +11 -0
  53. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.js +1 -1
  54. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/channel.d.ts +37 -0
  55. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ctx.d.ts +47 -3
  56. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.d.ts +14 -0
  57. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.js +41 -0
  58. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +140 -20
  59. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +419 -14
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/file-preview.d.ts +22 -5
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +77 -13
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/http-access.d.ts +10 -0
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +2 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +2 -3
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +89 -5
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.js +103 -0
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.d.ts +3 -2
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +2 -2
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +4 -0
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.d.ts +1 -1
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.js +11 -0
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +25 -6
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  74. package/dist/owner-report.d.ts +2 -2
  75. package/dist/owner-report.js +2 -2
  76. package/dist/policy-store.d.ts +6 -10
  77. package/dist/policy-store.js +9 -23
  78. package/dist/policy.d.ts +3 -32
  79. package/dist/policy.js +4 -74
  80. package/dist/runtime-manifest.json +1 -1
  81. package/dist/server-ops.d.ts +18 -46
  82. package/dist/server-ops.js +134 -269
  83. package/dist/staged-connect.js +44 -7
  84. package/dist/staged-device.d.ts +4 -4
  85. package/dist/staged-device.js +3 -0
  86. package/dist/staged-session.d.ts +5 -5
  87. package/dist/staged-session.js +4 -4
  88. package/dist/state.js +3 -2
  89. package/package.json +2 -2
  90. package/dist/commands/mode.d.ts +0 -69
  91. package/dist/commands/mode.js +0 -133
  92. package/dist/exec/fs-helper.d.ts +0 -21
  93. package/dist/exec/fs-helper.js +0 -171
  94. package/dist/exec/host.d.ts +0 -61
  95. package/dist/exec/host.js +0 -203
  96. package/dist/exec/listing.d.ts +0 -35
  97. package/dist/exec/listing.js +0 -157
  98. package/dist/exec/os.d.ts +0 -162
  99. package/dist/exec/os.js +0 -616
  100. package/dist/exec/procs.d.ts +0 -11
  101. package/dist/exec/procs.js +0 -67
  102. package/dist/exec/reap.d.ts +0 -41
  103. package/dist/exec/reap.js +0 -89
  104. package/dist/exec/switch.d.ts +0 -107
  105. package/dist/exec/switch.js +0 -204
  106. package/dist/network.d.ts +0 -45
  107. package/dist/network.js +0 -154
  108. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.d.ts +0 -117
  109. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.js +0 -409
@@ -2,13 +2,8 @@ import { spawn } from "node:child_process";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
3
  import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
4
4
  import { join, resolve } from "node:path";
5
- import { DEFAULT_SANDBOX_ROOTS, DEVICE_SCAN_SKIPPED_BASE_DIRS, DEVICE_SCAN_SKIPPED_DIRS, MAX_DEVICE_SCAN_DEPTH, MAX_DEVICE_SCAN_DIRS, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
6
- import { effectiveMode } from "../policy.js";
7
- import { policyMode } from "../state.js";
8
- import { finishScan } from "./listing.js";
9
- import { EXEC_MARKER } from "./procs.js";
10
- import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, ROOT_MARKER, RootGuard, } from "./shared.js";
11
- import { FILE_OPS_DECISION_TTL_MS } from "./switch.js";
5
+ import { DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
6
+ import { osRoots } from "./shared.js";
12
7
  import { DeviceOpError } from "./types.js";
13
8
  /** The version of the published sandbox images this program runs commands in. */
14
9
  export const SANDBOX_IMAGE_TAG = "0.1.0-rc.5";
@@ -26,8 +21,17 @@ export function containerUser(platform = process.platform, uid = process.getuid?
26
21
  return `${uid}:${gid}`;
27
22
  }
28
23
  const SPEC_LABEL = "capybara.device.spec";
29
- /** A file operation in the container that takes longer than this is killed. */
30
- const FILE_OP_TIMEOUT_S = 30;
24
+ /**
25
+ * The container format. It is part of the run flags, so a container an older format made (a
26
+ * protocol 2 program's, which may hold its commands' leftovers and may run without a network) is
27
+ * recreated at its first use, once nothing holds it, never reused.
28
+ */
29
+ export const CONTAINER_FORMAT = 2;
30
+ export const CONTAINER_FORMAT_LABEL = "capybara.device.format";
31
+ /** The spec label of a container made with `runFlags`: a container made otherwise is recreated. */
32
+ export function containerSpec(runFlags) {
33
+ return createHash("sha256").update(JSON.stringify(runFlags)).digest("hex").slice(0, 16);
34
+ }
31
35
  const ROOTS = DEFAULT_SANDBOX_ROOTS;
32
36
  /** Container name of a device. */
33
37
  export function containerName(deviceId) {
@@ -36,7 +40,7 @@ export function containerName(deviceId) {
36
40
  /** Runs `docker <args>` to completion (not a command of the device). */
37
41
  function docker(args, o = {}) {
38
42
  return new Promise((resolvePromise, reject) => {
39
- const child = spawn("docker", args, { stdio: [o.input ? "pipe" : "ignore", "pipe", "pipe"] });
43
+ const child = spawn("docker", args, { stdio: ["ignore", "pipe", "pipe"] });
40
44
  const out = [];
41
45
  const err = [];
42
46
  let size = 0;
@@ -47,25 +51,15 @@ function docker(args, o = {}) {
47
51
  size += b.length;
48
52
  });
49
53
  child.stderr?.on("data", (b) => err.push(b));
50
- if (child.stdin) {
51
- child.stdin.on("error", () => { });
52
- child.stdin.end(Buffer.from(o.input));
53
- }
54
54
  const timer = o.timeoutMs !== undefined ? setTimeout(() => child.kill("SIGKILL"), o.timeoutMs) : undefined;
55
- const onAbort = () => {
56
- child.kill("SIGKILL");
57
- };
58
- o.signal?.addEventListener("abort", onAbort, { once: true });
59
55
  child.once("error", (e) => {
60
56
  if (timer)
61
57
  clearTimeout(timer);
62
- o.signal?.removeEventListener("abort", onAbort);
63
58
  reject(e);
64
59
  });
65
60
  child.once("close", (code) => {
66
61
  if (timer)
67
62
  clearTimeout(timer);
68
- o.signal?.removeEventListener("abort", onAbort);
69
63
  resolvePromise({ code, stdout: Buffer.concat(out), stderr: Buffer.concat(err) });
70
64
  });
71
65
  });
@@ -83,184 +77,26 @@ export async function dockerAvailability() {
83
77
  return { ok: false, reason: "the docker command was not found" };
84
78
  }
85
79
  }
86
- /** Kills the processes whose `CAPYBARA_EXEC` is `$1` exactly, or starts with `$2` (when `$1` is empty). */
87
- const KILL_SCRIPT = `m=$1; pre=$2; for round in 1 2; do for e in /proc/[0-9]*/environ; do
88
- p=\${e%/environ}; p=\${p#/proc/}; [ "$p" = "$$" ] && continue
89
- if [ -n "$m" ]; then tr '\\0' '\\n' < "$e" 2>/dev/null | grep -qxF "${EXEC_MARKER}=$m" && kill -9 "$p" 2>/dev/null
90
- else tr '\\0' '\\n' < "$e" 2>/dev/null | grep -q "^${EXEC_MARKER}=$pre" && kill -9 "$p" 2>/dev/null; fi
91
- done; done; exit 0`;
92
- /**
93
- * The command wrapper. The host sends a random nonce on stdin; the wrapper keeps it in a shell
94
- * variable, runs the command (stdin `/dev/null`), then writes one final line on stderr with the
95
- * nonce and the exit status. `docker exec` itself ends only when every process holding its
96
- * output (a background child) has closed it, so the host reads the status from this line instead.
97
- * The command cannot suppress the line (the wrapper writes it after waiting) and never sees the
98
- * nonce; a forged line without it is ordinary output.
99
- */
100
- const EXEC_WRAPPER = 'read -r n; /bin/bash -c "$1" </dev/null; s=$?; printf \'\\nCAPYBARA-DONE:%s:%d:END\\n\' "$n" "$s" >&2; exit $s';
101
80
  /** The pids limit of a container (as the cloud sandbox). */
102
81
  const PIDS_LIMIT = 1024;
103
- // Exit codes of the file scripts.
104
- const E_MODE = 9;
105
- const E_MISSING = 10;
106
- const E_OUTSIDE = 11;
107
- const E_NOT_FILE = 12;
108
- const E_FAIL = 13;
109
- const E_DANGLING = 14;
110
82
  /**
111
- * The shared prologue of the file scripts: `$1` is the mode, `$2` the path, `$3` the extra
112
- * argument. In sandbox mode `allowed` checks a real path against the mounted roots; in auto mode
113
- * any absolute path in the container is allowed (the host checks its shape already).
83
+ * The docker-mode device's one long-lived container of the published sandbox image: the device
84
+ * directory's workspace, skills (read only) and tmp are mounted at /workspace, /skills and /tmp.
85
+ * It hosts the permission operations (`docker-operations.ts`): each one holds the container
86
+ * through {@link operationContainer}, so it is never recreated under a running operation. A change
87
+ * of the container's flags recreates it at the next operation that finds it idle. Nothing here
88
+ * runs commands or kills processes: the operation backend owns its work and stops it exactly.
114
89
  */
115
- const FILE_PROLOGUE = `mode=$1; p=$2; arg=$3
116
- allowed() {
117
- if [ "$mode" = "auto" ]; then
118
- case "$1" in /*) ;; *) return 1;; esac
119
- case "/$1/" in *"/../"*) return 1;; esac
120
- return 0
121
- fi
122
- case "$1" in /workspace|/workspace/*|/tmp|/tmp/*) return 0;; esac
123
- return 1
124
- }
125
- if [ "$mode" != "auto" ] && [ "$mode" != "sandbox" ]; then exit ${E_MODE}; fi
126
- `;
127
- const READ_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$p" 2>/dev/null) || exit ${E_MISSING}
128
- allowed "$r" || exit ${E_OUTSIDE}
129
- [ -d "$r" ] && exit ${E_MISSING}
130
- [ -f "$r" ] || exit ${E_NOT_FILE}
131
- head -c "$arg" -- "$r"`;
132
- const STAT_SCRIPT = `${FILE_PROLOGUE}r=$(realpath -e -- "$p" 2>/dev/null) || exit ${E_MISSING}
133
- allowed "$r" || exit ${E_OUTSIDE}
134
- if [ -d "$r" ]; then printf '%s d' "$(stat -c %s -- "$r")"; else printf '%s f' "$(stat -c %s -- "$r")"; fi`;
135
- const WRITE_SCRIPT = `${FILE_PROLOGUE}d=$(dirname -- "$p"); a=$d
136
- while [ ! -e "$a" ] && [ "$a" != / ]; do a=$(dirname -- "$a"); done
137
- ra=$(realpath -e -- "$a" 2>/dev/null) || exit ${E_FAIL}
138
- allowed "$ra" || exit ${E_OUTSIDE}
139
- mkdir -p -- "$d" || exit ${E_FAIL}
140
- rp=$(realpath -e -- "$d" 2>/dev/null) || exit ${E_FAIL}
141
- allowed "$rp" || exit ${E_OUTSIDE}
142
- f="$rp/$(basename -- "$p")"
143
- if [ -L "$f" ]; then r=$(realpath -e -- "$f" 2>/dev/null) || exit ${E_DANGLING}; allowed "$r" || exit ${E_OUTSIDE}; f=$r; fi
144
- if [ -e "$f" ] && [ ! -f "$f" ]; then exit ${E_NOT_FILE}; fi
145
- cat > "$f" || exit ${E_FAIL}`;
146
- /**
147
- * `list` / `scan` in the container (python3, which the sandbox image carries): argv `<op> <path>
148
- * <limit>`, the path lexically under /workspace already. The same rules as `listing.ts`'s
149
- * `listDirectory` / `scanDirectory` with /workspace as the area: realpath containment, a link
150
- * leaving the workspace is not a directory, null / [] for a missing path, the same breadth-first
151
- * walk and budget. Names sort by UTF-16 code unit (`utf-16-be` bytes). stdout: `{"r": ...}` or
152
- * `{"e": "policy" | "error", "m": ...}`; scan answers raw paths (the caller applies `finishScan`).
153
- */
154
- const LIST_SCRIPT = `
155
- import errno, json, os, sys
156
- op, p, limit = sys.argv[1], sys.argv[2], int(sys.argv[3])
157
- W = "/workspace"
158
- def out(o):
159
- sys.stdout.write(json.dumps(o)); sys.exit(0)
160
- def key(s):
161
- return s.encode("utf-16-be", "surrogatepass")
162
- def under(r):
163
- return r == W or r.startswith(W + "/")
164
- def fail(e):
165
- c = errno.errorcode.get(getattr(e, "errno", None) or 0)
166
- out({"e": "error", "m": p + " cannot be read" + (" (" + c + ")" if c else "")})
167
- away = {"e": "policy", "m": p + " is outside the container's workspace (/workspace); this device reads only that"}
168
- q = os.path.normpath(p)
169
- if not os.path.isabs(q) or not under(q):
170
- out(away)
171
- try:
172
- r = os.path.realpath(q, strict=True)
173
- except (FileNotFoundError, NotADirectoryError):
174
- out({"r": None if op == "list" else []})
175
- except OSError as e:
176
- fail(e)
177
- if not under(r):
178
- out(away)
179
- if not os.path.isdir(r):
180
- out({"e": "error", "m": p + " is not a directory"})
181
- try:
182
- with os.scandir(r) as it:
183
- ents = sorted(it, key=lambda e: key(e.name))
184
- except OSError as e:
185
- fail(e)
186
- def is_dir(d, e):
187
- try:
188
- if e.is_dir(follow_symlinks=False):
189
- return True
190
- if not e.is_symlink():
191
- return False
192
- t = os.path.realpath(os.path.join(d, e.name), strict=True)
193
- return under(t) and os.path.isdir(t)
194
- except OSError:
195
- return False
196
- if op == "list":
197
- out({"r": {"entries": [{"name": e.name, "isDir": is_dir(r, e)} for e in ents[:limit]], "truncated": len(ents) > limit}})
198
- skip_any = ${JSON.stringify(DEVICE_SCAN_SKIPPED_DIRS)}
199
- skip_base = ${JSON.stringify(DEVICE_SCAN_SKIPPED_BASE_DIRS)}
200
- found = []
201
- def below(d, rep, es, depth):
202
- if any(e.name == ".git" or (e.name == "AGENTS.md" and not e.is_dir(follow_symlinks=False)) for e in es):
203
- found.append(rep)
204
- if depth >= ${MAX_DEVICE_SCAN_DEPTH}:
205
- return []
206
- return [(os.path.join(d, e.name), os.path.join(rep, e.name)) for e in es
207
- if e.is_dir(follow_symlinks=False) and not e.name.startswith(".")
208
- and e.name not in skip_any and not (depth == 0 and e.name in skip_base)]
209
- visits = 1
210
- level = below(r, q, ents, 0)
211
- depth = 1
212
- while level and visits < ${MAX_DEVICE_SCAN_DIRS}:
213
- level.sort(key=lambda n: key(n[1]))
214
- nxt = []
215
- for d, rep in level:
216
- if visits >= ${MAX_DEVICE_SCAN_DIRS}:
217
- break
218
- visits += 1
219
- try:
220
- with os.scandir(d) as it:
221
- es = list(it)
222
- except OSError:
223
- continue
224
- nxt.extend(below(d, rep, es, depth))
225
- level = nxt
226
- depth += 1
227
- out({"r": found})
228
- `;
229
- /**
230
- * Runs every command with `docker exec` in one long-lived container of the published sandbox
231
- * image: the device directory's workspace, skills (read only) and tmp are mounted at
232
- * /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
233
- * (as the `sandbox` user, so a link a command plants resolves in the container and never on the
234
- * host); the skills directory, which commands cannot write, is accessed from the host with the
235
- * same real-path checks as the OS executor. Auto mode: the container on its default bridge, and
236
- * file operations reach any absolute path in the container. Sandbox mode: no network attached and
237
- * file operations stay in the mounted roots. Docker mode has no per-domain filter. A change of the
238
- * container's flags recreates it at the next command that finds it idle.
239
- */
240
- export class DockerExecutor {
90
+ export class DockerContainer {
241
91
  opts;
242
- mode = "docker";
243
92
  roots = ROOTS;
244
93
  name;
245
94
  dir;
246
95
  hostRoots;
247
- guard;
248
- hostFiles;
249
- /** Marks every process of this device's commands: `<dirKey>.<tag>`. */
250
- dirKey;
251
- running = new Set();
252
96
  chain = Promise.resolve();
253
97
  ready = false;
254
- /** The container has the default bridge (commands may reach the network). */
255
- netOpen = false;
98
+ /** Operations holding the container now. */
256
99
  inflight = 0;
257
- queue = [];
258
- pumping = false;
259
- dirty = false;
260
- /** The limits of the latest command: the kernel's mode ceiling for file operations. */
261
- lastLimits;
262
- /** When {@link lastLimits} came (file operations follow it only inside the window). */
263
- lastLimitsAt = 0;
264
100
  /** The spec hash of the container in use (set when it is created or reused). */
265
101
  spec;
266
102
  constructor(opts) {
@@ -268,16 +104,7 @@ export class DockerExecutor {
268
104
  const dir = resolve(opts.dir);
269
105
  this.dir = existsSync(dir) ? realpathSync(dir) : dir;
270
106
  this.hostRoots = osRoots(this.dir);
271
- this.guard = new RootGuard(this.dir, this.hostRoots);
272
- this.hostFiles = new HostFiles(this.hostRoots, "sandbox");
273
107
  this.name = containerName(opts.deviceId);
274
- this.dirKey = createHash("sha256").update(this.dir).digest("hex").slice(0, 16);
275
- }
276
- async ensureRoot() {
277
- return this.guard.ensure();
278
- }
279
- markerOf(tag) {
280
- return `${this.dirKey}.${tag}`;
281
108
  }
282
109
  serial(f) {
283
110
  const next = this.chain.then(f, f);
@@ -297,21 +124,8 @@ export class DockerExecutor {
297
124
  { source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
298
125
  ];
299
126
  }
300
- /**
301
- * The mode file operations use now. File operations carry no limits and never pass command
302
- * review, so they use the sandboxed result before any exec and once the latest decision is stale
303
- * (the safe default for an organization whose ceiling is sandbox), else
304
- * `effectiveMode(policy, limits)`.
305
- */
306
- modeNow(policy = this.opts.policy()) {
307
- if (policyMode(policy) === "sandbox" || this.lastLimits === undefined)
308
- return "sandbox";
309
- if (Date.now() - this.lastLimitsAt > FILE_OPS_DECISION_TTL_MS)
310
- return "sandbox";
311
- return effectiveMode(policy, this.lastLimits);
312
- }
313
127
  /** Every `docker run` flag of the container except its name and spec label. */
314
- runArgs() {
128
+ runFlags() {
315
129
  const policy = this.opts.policy();
316
130
  return [
317
131
  "--init",
@@ -328,6 +142,8 @@ export class DockerExecutor {
328
142
  ROOTS.workspace,
329
143
  "--label",
330
144
  `capybara.device.id=${this.opts.deviceId}`,
145
+ "--label",
146
+ `${CONTAINER_FORMAT_LABEL}=${CONTAINER_FORMAT}`,
331
147
  ...this.wanted().flatMap((m) => [
332
148
  "--mount",
333
149
  `type=bind,source=${m.source},target=${m.dest}${m.rw ? "" : ",readonly"}`,
@@ -344,10 +160,7 @@ export class DockerExecutor {
344
160
  }
345
161
  /** A hash of the run flags: a container made with other flags is recreated. */
346
162
  specHash() {
347
- return this.hashOf(this.runArgs());
348
- }
349
- hashOf(runArgs) {
350
- return createHash("sha256").update(JSON.stringify(runArgs)).digest("hex").slice(0, 16);
163
+ return containerSpec(this.runFlags());
351
164
  }
352
165
  matches(c) {
353
166
  return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
@@ -359,13 +172,8 @@ export class DockerExecutor {
359
172
  }
360
173
  return r;
361
174
  }
362
- /**
363
- * Creates the container, or reuses the existing one when it matches; call inside `serial`.
364
- * A file operation (`anySpec`) reuses any container that sees the directory: it needs no
365
- * particular flags, and before the first command the policy is not known yet. The next command
366
- * that finds it idle recreates it if its flags differ.
367
- */
368
- async ensureContainer(opts = {}) {
175
+ /** Creates the container, or reuses the existing one when it matches; call inside `serial`. */
176
+ async ensureContainer() {
369
177
  if (this.ready)
370
178
  return;
371
179
  if (!existsSync(this.dir)) {
@@ -378,23 +186,24 @@ export class DockerExecutor {
378
186
  mkdirSync(r, { recursive: true });
379
187
  }
380
188
  let c = await this.inspect();
189
+ // other flags, an older format, a lost bridge or stale mounts: recreated, never repaired
381
190
  if (c !== null &&
382
- ((opts.anySpec !== true && !this.matches(c)) || !(await this.seesHostRoots(c)))) {
191
+ (!this.matches(c) ||
192
+ !("bridge" in (c.NetworkSettings.Networks ?? {})) ||
193
+ !(await this.seesHostRoots(c)))) {
383
194
  await this.mustDocker(["rm", "-f", this.name], "removing the old container");
384
195
  c = null;
385
196
  }
386
197
  if (c === null) {
387
- const runArgs = this.runArgs();
388
- const spec = this.hashOf(runArgs);
198
+ const runArgs = this.runFlags();
199
+ const spec = containerSpec(runArgs);
389
200
  await this.mustDocker(["run", "-d", "--name", this.name, "--label", `${SPEC_LABEL}=${spec}`, ...runArgs], "creating the container");
201
+ // created on the default bridge
390
202
  this.spec = spec;
391
- // Created on the default bridge (a container created with `none` cannot join it later).
392
- this.netOpen = true;
393
203
  }
394
204
  else {
395
205
  if (!c.State.Running)
396
206
  await this.mustDocker(["start", this.name], "starting the container");
397
- this.netOpen = "bridge" in (await this.inspectNetworks());
398
207
  this.spec = c.Config.Labels?.[SPEC_LABEL];
399
208
  }
400
209
  this.ready = true;
@@ -420,124 +229,40 @@ export class DockerExecutor {
420
229
  rmSync(join(m.source, probe), { force: true });
421
230
  }
422
231
  }
423
- async inspectNetworks() {
424
- const c = await this.inspect();
425
- return c?.NetworkSettings.Networks ?? {};
426
- }
427
- async setNet(open) {
428
- await this.mustDocker(["network", open ? "connect" : "disconnect", "bridge", this.name], open ? "enabling the network" : "disabling the network");
429
- this.netOpen = open;
430
- }
431
232
  /**
432
- * Waits until the container exists with the wanted network state and counts the caller as
433
- * running. Callers are served in arrival order: once one needs the other network state, later
434
- * callers for the current state queue behind it, so it is not starved.
233
+ * The container for one permission operation: running on its default bridge (Full access is
234
+ * the container user's own network; restricted operations are mediated by the launcher). The
235
+ * caller holds the
236
+ * container (it is not recreated) until it calls `release`, once; an abort while waiting for it
237
+ * rejects and holds nothing.
435
238
  */
436
- acquire(open, signal) {
239
+ async operationContainer(signal) {
437
240
  signal.throwIfAborted();
438
- return new Promise((resolveWait, rejectWait) => {
439
- const w = {
440
- open,
441
- dead: false,
442
- counted: false,
443
- resolve: resolveWait,
444
- reject: rejectWait,
445
- };
446
- const onAbort = () => {
447
- w.dead = true;
448
- this.dequeue(w);
449
- rejectWait(signal.reason);
450
- };
451
- signal.addEventListener("abort", onAbort, { once: true });
452
- const done = w.resolve;
453
- w.resolve = () => {
454
- signal.removeEventListener("abort", onAbort);
455
- done();
456
- };
457
- this.queue.push(w);
458
- this.pump();
241
+ const acquired = this.serial(async () => {
242
+ // the policy changed the container's flags (cpu, memory): recreate it once nothing holds it
243
+ if (this.ready && this.inflight === 0 && this.spec !== this.specHash())
244
+ this.ready = false;
245
+ await this.ensureContainer();
246
+ this.inflight++;
459
247
  });
460
- }
461
- pump() {
462
- if (this.pumping) {
463
- this.dirty = true;
464
- return;
248
+ try {
249
+ await new Promise((resolveWait, rejectWait) => {
250
+ const onAbort = () => rejectWait(signal.reason);
251
+ signal.addEventListener("abort", onAbort, { once: true });
252
+ acquired.then(() => {
253
+ signal.removeEventListener("abort", onAbort);
254
+ resolveWait();
255
+ }, (e) => {
256
+ signal.removeEventListener("abort", onAbort);
257
+ rejectWait(e);
258
+ });
259
+ });
260
+ }
261
+ catch (e) {
262
+ // aborted while waiting: a hold acquired later is given back at once
263
+ acquired.then(() => this.inflight--, () => { });
264
+ throw e;
465
265
  }
466
- this.pumping = true;
467
- void this.drain().finally(() => {
468
- this.pumping = false;
469
- if (this.dirty)
470
- this.pump();
471
- });
472
- }
473
- dequeue(w) {
474
- const i = this.queue.indexOf(w);
475
- if (i >= 0)
476
- this.queue.splice(i, 1);
477
- }
478
- async drain() {
479
- do {
480
- this.dirty = false;
481
- while (this.queue.length > 0) {
482
- const w = this.queue[0];
483
- if (w.dead) {
484
- this.dequeue(w);
485
- continue;
486
- }
487
- let served;
488
- try {
489
- served = await this.serial(async () => {
490
- // The policy or the mode changed the container's flags (shm, cpu, memory): recreate
491
- // it once nothing runs in it.
492
- if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
493
- this.ready = false;
494
- }
495
- await this.ensureContainer();
496
- if (w.dead)
497
- return true;
498
- if (this.netOpen !== w.open) {
499
- // Commands run with the other network state: wait for them.
500
- if (this.inflight > 0)
501
- return false;
502
- await this.setNet(w.open);
503
- }
504
- this.inflight++;
505
- w.counted = true;
506
- return true;
507
- });
508
- }
509
- catch (e) {
510
- // An abort while being served already removed it; never remove another waiter.
511
- this.dequeue(w);
512
- if (!w.dead)
513
- w.reject(e);
514
- continue;
515
- }
516
- if (!served)
517
- break;
518
- this.dequeue(w);
519
- if (w.dead) {
520
- // Aborted while being served: give back the slot if it was counted.
521
- if (w.counted)
522
- this.inflight--;
523
- continue;
524
- }
525
- w.resolve();
526
- }
527
- } while (this.dirty);
528
- }
529
- release() {
530
- this.inflight--;
531
- this.pump();
532
- }
533
- /**
534
- * The container for one permission operation (protocol 3): running on its default bridge (Full
535
- * access is the container user's own network; restricted operations are mediated by the
536
- * launcher). The caller holds the container (it is not recreated) until it calls `release`,
537
- * once; an abort while waiting for it rejects.
538
- */
539
- async operationContainer(signal) {
540
- await this.acquire(true, signal);
541
266
  let released = false;
542
267
  return {
543
268
  name: this.name,
@@ -546,389 +271,19 @@ export class DockerExecutor {
546
271
  if (released)
547
272
  return;
548
273
  released = true;
549
- this.release();
274
+ this.inflight--;
550
275
  },
551
276
  };
552
277
  }
553
- /** A docker-level failure that means the container vanished: the next call recreates it. */
554
- noteFailure(stderr) {
555
- if (/No such container|is not running|is restarting/i.test(stderr))
556
- this.ready = false;
557
- }
558
- async exec(args, signal) {
559
- signal.throwIfAborted();
560
- const mode = effectiveMode(this.opts.policy(), args.limits);
561
- const cwd = this.containerPath(args.cwd ?? ROOTS.workspace, mode);
562
- const env = {
563
- HOME: ROOTS.workspace,
564
- TERM: "dumb",
565
- ...args.env,
566
- TMPDIR: ROOTS.tmp,
567
- [EXEC_MARKER]: this.markerOf(args.tag),
568
- };
569
- for (const k of Object.keys(env)) {
570
- if (!ENV_NAME_RE.test(k))
571
- throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
572
- }
573
- this.lastLimits = args.limits;
574
- this.lastLimitsAt = Date.now();
575
- // Auto: the container on its default bridge. Sandbox: no network at all (spec P-D7).
576
- const open = effectiveMode(this.opts.policy(), args.limits) === "auto";
577
- await this.acquire(open, signal);
578
- try {
579
- signal.throwIfAborted();
580
- return await this.run(args, cwd, env, signal);
581
- }
582
- finally {
583
- this.release();
584
- }
585
- }
586
- run(args, cwd, env, signal) {
587
- const nonce = randomBytes(16).toString("hex");
588
- return new Promise((resolvePromise, reject) => {
589
- const child = spawn("docker", [
590
- "exec",
591
- "-i",
592
- "--workdir",
593
- cwd,
594
- ...Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
595
- this.name,
596
- "/bin/bash",
597
- "-c",
598
- EXEC_WRAPPER,
599
- "capybara-exec",
600
- args.command,
601
- ], { stdio: ["pipe", "pipe", "pipe"] });
602
- child.stdin?.on("error", () => { });
603
- child.stdin?.end(`${nonce}\n`);
604
- const sentinel = Buffer.from(`\nCAPYBARA-DONE:${nonce}:`);
605
- const entry = { tag: args.tag, killed: false, child };
606
- this.running.add(entry);
607
- const cap = new OutputCap(args.maxOutputBytes);
608
- const dockerErr = [];
609
- let timedOut = false;
610
- let exit;
611
- let settled = false;
612
- let grace;
613
- const kill = () => {
614
- if (exit === undefined)
615
- entry.killed = true;
616
- void this.killMarker(this.markerOf(args.tag)).then(() => {
617
- // The docker client normally ends with the command; never leave it behind.
618
- setTimeout(() => child.kill("SIGKILL"), 1000).unref();
619
- });
620
- };
621
- const timer = setTimeout(() => {
622
- if (exit === undefined)
623
- timedOut = true;
624
- kill();
625
- }, args.timeoutMs);
626
- const onAbort = () => kill();
627
- signal.addEventListener("abort", onAbort, { once: true });
628
- const cleanup = () => {
629
- clearTimeout(timer);
630
- if (grace)
631
- clearTimeout(grace);
632
- // A background child may keep the client attached: it is not needed any more.
633
- child.kill("SIGKILL");
634
- signal.removeEventListener("abort", onAbort);
635
- this.running.delete(entry);
636
- };
637
- const finish = () => {
638
- if (settled || exit === undefined)
639
- return;
640
- settled = true;
641
- cleanup();
642
- child.stdout?.destroy();
643
- child.stderr?.destroy();
644
- if (status === undefined && pending.length > 0)
645
- cap.push("stderr", pending);
646
- const stderr = cap.text("stderr");
647
- if (exit.code === 126 || exit.code === 125 || exit.code === 1) {
648
- this.noteFailure(Buffer.concat(dockerErr).toString("utf8"));
649
- }
650
- resolvePromise({
651
- exitCode: entry.killed || timedOut ? null : (exit.code ?? 128),
652
- stdout: cap.text("stdout"),
653
- stderr,
654
- truncated: cap.truncated,
655
- timedOut,
656
- });
657
- };
658
- child.stdout?.on("data", (b) => cap.push("stdout", b));
659
- // stderr carries the wrapper's final status line; hold back a tail that might begin it.
660
- let pending = Buffer.alloc(0);
661
- let status;
662
- const onStderr = (b) => {
663
- if (dockerErr.length < 64)
664
- dockerErr.push(b);
665
- if (status !== undefined) {
666
- status = Buffer.concat([status, b]);
667
- }
668
- else {
669
- const data = Buffer.concat([pending, b]);
670
- const at = data.indexOf(sentinel);
671
- if (at >= 0) {
672
- cap.push("stderr", data.subarray(0, at));
673
- pending = Buffer.alloc(0);
674
- status = data.subarray(at + sentinel.length);
675
- }
676
- else {
677
- const keep = Math.min(data.length, sentinel.length - 1);
678
- cap.push("stderr", data.subarray(0, data.length - keep));
679
- pending = data.subarray(data.length - keep);
680
- }
681
- }
682
- if (status !== undefined && exit === undefined) {
683
- const m = /^(\d+):END\n/.exec(status.toString("latin1"));
684
- if (m) {
685
- exit = { code: Number(m[1]), sig: null };
686
- grace = setTimeout(finish, PIPE_GRACE_MS);
687
- }
688
- }
689
- };
690
- child.stderr?.on("data", onStderr);
691
- child.once("error", (e) => {
692
- if (settled)
693
- return;
694
- settled = true;
695
- cleanup();
696
- reject(e);
697
- });
698
- child.once("exit", (code, sig) => {
699
- if (exit !== undefined)
700
- return;
701
- exit = { code, sig };
702
- grace = setTimeout(finish, PIPE_GRACE_MS);
703
- });
704
- child.once("close", () => finish());
705
- });
706
- }
707
- /**
708
- * `path` made absolute and normalized. Auto mode accepts any clean absolute path (the container
709
- * is the boundary); sandbox mode refuses anything outside the mounted roots.
710
- */
711
- containerPath(path, mode) {
712
- if (mode === "auto") {
713
- const errors = validateSandboxPathShape(path);
714
- if (errors.length > 0)
715
- throw policyError(`${path}: ${errors.join("; ")}`);
716
- return resolve(path);
717
- }
718
- if (!path.startsWith("/"))
719
- throw policyError(`${path} is not an absolute path`);
720
- const p = resolve(path);
721
- const roots = Object.values(ROOTS);
722
- if (!roots.some((r) => isUnder(p, r))) {
723
- throw policyError(`${path} is outside the device's roots (${roots.join(", ")})`);
724
- }
725
- return p;
726
- }
727
- /** The host path of a /skills path (the skills directory is mounted read only). */
728
- skillsHostPath(p) {
729
- return join(this.hostRoots.skills, p.slice(ROOTS.skills.length));
730
- }
731
- inSkills(p) {
732
- return isUnder(p, ROOTS.skills);
733
- }
734
- /** Runs one file script in the container; `null` for a missing file. */
735
- async fileOp(script, mode, path, arg2, input) {
736
- // A file operation does not need the network; it runs on whichever state the container has.
737
- await this.serial(() => this.ensureContainer({ anySpec: true }));
738
- const r = await docker([
739
- "exec",
740
- ...(input !== undefined ? ["-i"] : []),
741
- this.name,
742
- "timeout",
743
- "-s",
744
- "KILL",
745
- String(FILE_OP_TIMEOUT_S),
746
- "/bin/sh",
747
- "-c",
748
- script,
749
- "capybara-file",
750
- mode,
751
- path,
752
- arg2,
753
- ], {
754
- ...(input !== undefined && { input }),
755
- timeoutMs: (FILE_OP_TIMEOUT_S + 5) * 1000,
756
- });
757
- return this.fileResult(r, path);
758
- }
759
- fileResult(r, path) {
760
- switch (r.code) {
761
- case 0:
762
- return r;
763
- case E_MODE:
764
- throw new DeviceOpError("policy", `missing or unknown mode for ${path}`);
765
- case E_MISSING:
766
- return null;
767
- case E_OUTSIDE:
768
- throw policyError(`${path} resolves outside the device's roots`);
769
- case E_NOT_FILE:
770
- throw policyError(`${path} is not a regular file`);
771
- case E_DANGLING:
772
- throw policyError(`${path} is a dangling symbolic link`);
773
- default:
774
- this.noteFailure(r.stderr.toString("utf8"));
775
- throw new DeviceOpError("error", `file operation on ${path} failed: ${r.stderr.toString("utf8").trim().slice(0, 300)}`);
776
- }
777
- }
778
- async readFile(path, maxBytes) {
779
- const mode = this.modeNow();
780
- const p = this.containerPath(path, mode);
781
- if (this.inSkills(p))
782
- return this.hostFiles.read(this.skillsHostPath(p), maxBytes);
783
- const r = await this.fileOp(READ_SCRIPT, mode, p, String(maxBytes + 1));
784
- if (r === null)
785
- return null;
786
- return {
787
- data: r.stdout.subarray(0, maxBytes),
788
- truncated: r.stdout.length > maxBytes,
789
- };
790
- }
791
- async writeFile(path, data) {
792
- const mode = this.modeNow();
793
- const p = this.containerPath(path, mode);
794
- if (this.inSkills(p))
795
- return this.hostFiles.write(this.skillsHostPath(p), data);
796
- await this.fileOp(WRITE_SCRIPT, mode, p, "", data);
797
- }
798
- async stat(path) {
799
- const mode = this.modeNow();
800
- const p = this.containerPath(path, mode);
801
- if (this.inSkills(p))
802
- return this.hostFiles.stat(this.skillsHostPath(p));
803
- const r = await this.fileOp(STAT_SCRIPT, mode, p, "");
804
- if (r === null)
805
- return null;
806
- const [size, kind] = r.stdout.toString("utf8").split(" ");
807
- return { size: Number(size), isDir: kind === "d" };
808
- }
809
- /**
810
- * `path` made absolute and normalized, refused unless it lies lexically under the container's
811
- * workspace: a container device offers its workspace only, in either mode (spec §4.2).
812
- */
813
- workspacePath(path) {
814
- if (!path.startsWith("/"))
815
- throw policyError(`${path} is not an absolute path`);
816
- const p = resolve(path);
817
- if (!isUnder(p, ROOTS.workspace)) {
818
- throw policyError(`${path} is outside the container's workspace (${ROOTS.workspace}); this device reads only that`);
819
- }
820
- return p;
821
- }
822
- /**
823
- * Whether the device directory is marked and holds all three roots. `list` and `scan` only
824
- * read: a removed root under a marked directory lost its files and is never recreated empty
825
- * (`ensureContainer` would create it), and an unmarked or vanished directory gets no roots either.
826
- */
827
- rootsIntact() {
828
- return (existsSync(join(this.dir, ROOT_MARKER)) &&
829
- Object.values(this.hostRoots).every((r) => existsSync(r)));
830
- }
831
- /**
832
- * Runs {@link LIST_SCRIPT} in the container (as the `sandbox` user, like the file operations):
833
- * links resolve in the container, so whatever a command there does to the workspace, the answer
834
- * shows only what the container itself can see, never the host behind the bind mount. A stopped
835
- * container is started first, as for the file operations.
836
- */
837
- async listOp(op, path, limit, signal) {
838
- signal?.throwIfAborted();
839
- await this.serial(() => this.ensureContainer({ anySpec: true }));
840
- signal?.throwIfAborted();
841
- const r = await docker([
842
- "exec",
843
- this.name,
844
- "timeout",
845
- "-s",
846
- "KILL",
847
- String(FILE_OP_TIMEOUT_S),
848
- "python3",
849
- "-I",
850
- "-c",
851
- LIST_SCRIPT,
852
- op,
853
- path,
854
- String(limit),
855
- ], { timeoutMs: (FILE_OP_TIMEOUT_S + 5) * 1000, ...(signal !== undefined && { signal }) });
856
- signal?.throwIfAborted();
857
- let res;
858
- try {
859
- res = JSON.parse(r.stdout.toString("utf8"));
860
- }
861
- catch {
862
- this.noteFailure(r.stderr.toString("utf8"));
863
- throw new DeviceOpError("error", `${op} ${path} failed in the container: ${r.stderr.toString("utf8").trim().slice(0, 300)}`);
864
- }
865
- if (res.e !== undefined) {
866
- throw new DeviceOpError(res.e === "policy" ? "policy" : "error", res.m ?? "failed");
867
- }
868
- return res.r ?? null;
869
- }
870
- /** Lists a container workspace directory, read in the container, in either mode. */
871
- async list(_mode, path, limit, signal) {
872
- const p = this.workspacePath(path);
873
- // nothing under the workspace exists (as the OS reader answers)
874
- if (!this.rootsIntact())
875
- return null;
876
- const r = await this.listOp("list", p, limit, signal);
877
- if (r !== null && !Array.isArray(r.entries)) {
878
- throw new DeviceOpError("error", `list ${path} answered an invalid result`);
879
- }
880
- return r;
881
- }
882
- /** Scans a container workspace directory, read in the container ({@link list}'s rules). */
883
- async scan(_mode, base, signal) {
884
- const p = this.workspacePath(base);
885
- if (!this.rootsIntact())
886
- return [];
887
- const r = await this.listOp("scan", p, 0, signal);
888
- if (!Array.isArray(r) || !r.every((x) => typeof x === "string")) {
889
- throw new DeviceOpError("error", `scan ${base} answered an invalid result`);
890
- }
891
- return finishScan(r);
892
- }
893
- /** Kills the container processes of one marker (exact) or marker prefix. */
894
- async killScript(marker, prefix) {
895
- try {
896
- await docker(["exec", this.name, "/bin/sh", "-c", KILL_SCRIPT, "capybara-kill", marker, prefix], { timeoutMs: 15_000 });
897
- }
898
- catch {
899
- // No docker, or no container: nothing of ours runs.
900
- }
901
- }
902
- killMarker(marker) {
903
- return this.killScript(marker, "");
904
- }
905
- async killTagged(tags) {
906
- const want = new Set(tags);
907
- for (const r of this.running)
908
- if (want.has(r.tag))
909
- r.killed = true;
910
- await Promise.all(tags.map((t) => this.killMarker(this.markerOf(t))));
911
- }
912
- async killAll() {
913
- for (const r of this.running)
914
- r.killed = true;
915
- await this.killLeftovers();
916
- }
917
- /** Kills every process carrying this device's marker (also a previous run's). */
918
- async killLeftovers() {
919
- await this.killScript("", `${this.dirKey}.`);
920
- }
921
- /** Kills every running command; the container stays for the next start. */
922
- async dispose() {
923
- await this.killAll();
924
- }
925
278
  }
926
- /** The Docker executor: checks the daemon and kills what a previous run left running. */
927
- export async function createDockerExecutor(opts) {
279
+ /**
280
+ * The docker-mode device's container host: checks the daemon. It kills nothing at startup (no
281
+ * marker reaper): work an earlier run left is the operation backend's, recovered and stopped
282
+ * exactly through its journal.
283
+ */
284
+ export async function createDockerContainer(opts) {
928
285
  const available = await dockerAvailability();
929
286
  if (!available.ok)
930
287
  throw new Error(available.reason);
931
- const executor = new DockerExecutor(opts);
932
- await executor.killLeftovers();
933
- return executor;
288
+ return new DockerContainer(opts);
934
289
  }