@capybara-hq/device 0.1.0-rc.2 → 0.1.0-rc.4

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.
@@ -3,7 +3,7 @@ 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
5
  import { DEFAULT_SANDBOX_ROOTS, } from "@capybara-hq/plugin-sdk";
6
- import { effectiveEgress } from "../policy.js";
6
+ import { ANY_HOST, deviceTier, effectiveEgress, provisionalTier, tierFacts, } from "../policy.js";
7
7
  import { EXEC_MARKER } from "./procs.js";
8
8
  import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
9
9
  import { DeviceOpError } from "./types.js";
@@ -26,6 +26,31 @@ const SPEC_LABEL = "capybara.device.spec";
26
26
  /** A file operation in the container that takes longer than this is killed. */
27
27
  const FILE_OP_TIMEOUT_S = 30;
28
28
  const ROOTS = DEFAULT_SANDBOX_ROOTS;
29
+ /**
30
+ * The container's `--shm-size` for a tier (spec §5.2): `strict` keeps Docker's default (64 MiB);
31
+ * `dev` and `open` get a quarter of the memory ceiling up to 1 GiB (at least the default), or
32
+ * 1 GiB without a ceiling, so browsers have room.
33
+ */
34
+ export function shmSize(tier, memoryMb) {
35
+ if (tier === "strict")
36
+ return undefined;
37
+ if (memoryMb === null)
38
+ return "1g";
39
+ return `${Math.max(64, Math.min(1024, Math.floor(memoryMb / 4)))}m`;
40
+ }
41
+ /**
42
+ * Whether a command gets the default bridge (spec §5.2 table). Docker mode has no domain filter,
43
+ * and the bridge reaches the host and the intranet, so only an explicit choice opens it: the
44
+ * device's own allowed domains within the ceiling (as `strict` computes them; the dev hosts do
45
+ * not count), or tier `open` with a ceiling that allows any host (an allowlist ceiling at `open`
46
+ * counts only its explicit local domains, like the lower tiers).
47
+ */
48
+ export function bridgeNetwork(policy, limits) {
49
+ if (deviceTier(policy, limits) === "open" && effectiveEgress(policy, limits).includes(ANY_HOST)) {
50
+ return true;
51
+ }
52
+ return effectiveEgress({ ...policy, tier: "strict" }, limits).length > 0;
53
+ }
29
54
  /** Container name of a device. */
30
55
  export function containerName(deviceId) {
31
56
  return `capybara-device-${deviceId}`;
@@ -125,8 +150,10 @@ cat > "$f" || exit ${E_FAIL}`;
125
150
  * /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
126
151
  * (as the `sandbox` user, so a link a command plants resolves in the container and never on the
127
152
  * host); the skills directory, which commands cannot write, is accessed from the host with the
128
- * same real-path checks as the OS executor. Network: none unless the effective egress is
129
- * non-empty, then the default bridge (Docker mode has no domain allowlist).
153
+ * same real-path checks as the OS executor. Network: none unless {@link bridgeNetwork} says
154
+ * otherwise, then the default bridge (Docker mode has no domain allowlist). Tiers `dev` and
155
+ * `open` get a larger `/dev/shm` ({@link shmSize}); a change of the container's flags recreates it
156
+ * at the next command that finds it idle.
130
157
  */
131
158
  export class DockerExecutor {
132
159
  opts;
@@ -148,6 +175,10 @@ export class DockerExecutor {
148
175
  queue = [];
149
176
  pumping = false;
150
177
  dirty = false;
178
+ /** The limits of the latest command: they decide the tier the container is made for. */
179
+ lastLimits;
180
+ /** The spec hash of the container in use (set when it is created or reused). */
181
+ spec;
151
182
  constructor(opts) {
152
183
  this.opts = opts;
153
184
  const dir = resolve(opts.dir);
@@ -182,9 +213,20 @@ export class DockerExecutor {
182
213
  { source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
183
214
  ];
184
215
  }
216
+ /** The tier commands run at now (the owner's choice, else `dev`, before any command). */
217
+ tier(policy = this.opts.policy()) {
218
+ return this.lastLimits === undefined
219
+ ? provisionalTier(policy)
220
+ : deviceTier(policy, this.lastLimits);
221
+ }
222
+ /** What the tier gives in this mode (for the policy summary). */
223
+ tierFacts(policy = this.opts.policy()) {
224
+ return tierFacts(policy, this.lastLimits, { proxyDetected: false, mode: "docker" });
225
+ }
185
226
  /** Every `docker run` flag of the container except its name and spec label. */
186
227
  runArgs() {
187
- const { policy } = this.opts;
228
+ const policy = this.opts.policy();
229
+ const shm = shmSize(this.tier(policy), policy.memoryMb);
188
230
  return [
189
231
  "--init",
190
232
  "--read-only",
@@ -208,6 +250,7 @@ export class DockerExecutor {
208
250
  ...(policy.memoryMb !== null
209
251
  ? ["--memory", `${policy.memoryMb}m`, "--memory-swap", `${policy.memoryMb}m`]
210
252
  : []),
253
+ ...(shm !== undefined ? ["--shm-size", shm] : []),
211
254
  "--entrypoint",
212
255
  "sleep",
213
256
  SANDBOX_IMAGE,
@@ -216,7 +259,10 @@ export class DockerExecutor {
216
259
  }
217
260
  /** A hash of the run flags: a container made with other flags is recreated. */
218
261
  specHash() {
219
- return createHash("sha256").update(JSON.stringify(this.runArgs())).digest("hex").slice(0, 16);
262
+ return this.hashOf(this.runArgs());
263
+ }
264
+ hashOf(runArgs) {
265
+ return createHash("sha256").update(JSON.stringify(runArgs)).digest("hex").slice(0, 16);
220
266
  }
221
267
  matches(c) {
222
268
  return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
@@ -228,8 +274,13 @@ export class DockerExecutor {
228
274
  }
229
275
  return r;
230
276
  }
231
- /** Creates the container, or reuses the existing one when it matches; call inside `serial`. */
232
- async ensureContainer() {
277
+ /**
278
+ * Creates the container, or reuses the existing one when it matches; call inside `serial`.
279
+ * A file operation (`anySpec`) reuses any container that sees the directory: it needs no
280
+ * particular flags, and before the first command the tier is not known yet. The next command
281
+ * that finds it idle recreates it if its flags differ.
282
+ */
283
+ async ensureContainer(opts = {}) {
233
284
  if (this.ready)
234
285
  return;
235
286
  if (!existsSync(this.dir)) {
@@ -242,20 +293,16 @@ export class DockerExecutor {
242
293
  mkdirSync(r, { recursive: true });
243
294
  }
244
295
  let c = await this.inspect();
245
- if (c !== null && (!this.matches(c) || !(await this.seesHostRoots(c)))) {
296
+ if (c !== null &&
297
+ ((opts.anySpec !== true && !this.matches(c)) || !(await this.seesHostRoots(c)))) {
246
298
  await this.mustDocker(["rm", "-f", this.name], "removing the old container");
247
299
  c = null;
248
300
  }
249
301
  if (c === null) {
250
- await this.mustDocker([
251
- "run",
252
- "-d",
253
- "--name",
254
- this.name,
255
- "--label",
256
- `${SPEC_LABEL}=${this.specHash()}`,
257
- ...this.runArgs(),
258
- ], "creating the container");
302
+ const runArgs = this.runArgs();
303
+ const spec = this.hashOf(runArgs);
304
+ await this.mustDocker(["run", "-d", "--name", this.name, "--label", `${SPEC_LABEL}=${spec}`, ...runArgs], "creating the container");
305
+ this.spec = spec;
259
306
  // Created on the default bridge (a container created with `none` cannot join it later).
260
307
  this.netOpen = true;
261
308
  }
@@ -263,6 +310,7 @@ export class DockerExecutor {
263
310
  if (!c.State.Running)
264
311
  await this.mustDocker(["start", this.name], "starting the container");
265
312
  this.netOpen = "bridge" in (await this.inspectNetworks());
313
+ this.spec = c.Config.Labels?.[SPEC_LABEL];
266
314
  }
267
315
  this.ready = true;
268
316
  }
@@ -354,6 +402,11 @@ export class DockerExecutor {
354
402
  let served;
355
403
  try {
356
404
  served = await this.serial(async () => {
405
+ // The policy or the tier changed the container's flags (shm, cpu, memory): recreate
406
+ // it once nothing runs in it.
407
+ if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
408
+ this.ready = false;
409
+ }
357
410
  await this.ensureContainer();
358
411
  if (w.dead)
359
412
  return true;
@@ -411,7 +464,8 @@ export class DockerExecutor {
411
464
  if (!ENV_NAME_RE.test(k))
412
465
  throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
413
466
  }
414
- const open = effectiveEgress(this.opts.policy, args.limits).length > 0;
467
+ this.lastLimits = args.limits;
468
+ const open = bridgeNetwork(this.opts.policy(), args.limits);
415
469
  await this.acquire(open, signal);
416
470
  try {
417
471
  signal.throwIfAborted();
@@ -563,7 +617,7 @@ export class DockerExecutor {
563
617
  /** Runs one file script in the container; `null` for a missing file. */
564
618
  async fileOp(script, path, arg2, input) {
565
619
  // A file operation does not need the network; it runs on whichever state the container has.
566
- await this.serial(() => this.ensureContainer());
620
+ await this.serial(() => this.ensureContainer({ anySpec: true }));
567
621
  const r = await docker([
568
622
  "exec",
569
623
  ...(input !== undefined ? ["-i"] : []),
@@ -0,0 +1,42 @@
1
+ import type { ChildProcess } from "node:child_process";
2
+ /**
3
+ * The key that marks every process of one device directory's commands (`<dirKey>.<tag>` in the
4
+ * marker variable). Executors of the same directory compute the same key, so either one finds
5
+ * and kills what the other started.
6
+ */
7
+ export declare function dirKeyOf(realDir: string): string;
8
+ /** Sends `signal` (SIGKILL by default) to a process group; false when the group no longer exists. */
9
+ export declare function killGroupId(pgid: number, signal?: NodeJS.Signals | 0): boolean;
10
+ export declare function pidAlive(pid: number): boolean;
11
+ /**
12
+ * One command's process group. It is tracked after the command's main process exits, as long as
13
+ * the group has members (background children), so killTagged / killAll still reach them.
14
+ */
15
+ export interface Group {
16
+ tag: string;
17
+ pgid: number;
18
+ /** The leader (the outer shell) has exited and been reaped. */
19
+ exited: boolean;
20
+ /** Called by a kill while the command runs: the result then has `exitCode: null`. */
21
+ onKill?: (() => void) | undefined;
22
+ }
23
+ /** The process groups of one executor's commands (each command leads its own group). */
24
+ export declare class GroupTracker {
25
+ private readonly groups;
26
+ private pruneTimer;
27
+ /** Tracks a spawned command's process group; undefined when it has no pid (spawn failed). */
28
+ track(tag: string, child: ChildProcess): Group | undefined;
29
+ /** Stops tracking a group (its command failed to start). */
30
+ forget(g: Group): void;
31
+ /** Forgets finished groups with no members left (or whose id was taken by another process). */
32
+ prune(): void;
33
+ kill(g: Group): void;
34
+ /** Kills the groups of the given tags. */
35
+ killTags(tags: Iterable<string>): void;
36
+ killAll(): void;
37
+ /** Stops the prune timer (the groups stay known). */
38
+ dispose(): void;
39
+ /** The number of groups tracked (for tests). */
40
+ get size(): number;
41
+ private stopTimerWhenEmpty;
42
+ }
@@ -0,0 +1,100 @@
1
+ import { createHash } from "node:crypto";
2
+ /** How often process groups of finished commands are checked for remaining members. */
3
+ const PRUNE_INTERVAL_MS = 5_000;
4
+ /**
5
+ * The key that marks every process of one device directory's commands (`<dirKey>.<tag>` in the
6
+ * marker variable). Executors of the same directory compute the same key, so either one finds
7
+ * and kills what the other started.
8
+ */
9
+ export function dirKeyOf(realDir) {
10
+ return createHash("sha256").update(realDir).digest("hex").slice(0, 16);
11
+ }
12
+ /** Sends `signal` (SIGKILL by default) to a process group; false when the group no longer exists. */
13
+ export function killGroupId(pgid, signal = "SIGKILL") {
14
+ try {
15
+ process.kill(-pgid, signal);
16
+ return true;
17
+ }
18
+ catch {
19
+ return false;
20
+ }
21
+ }
22
+ export function pidAlive(pid) {
23
+ try {
24
+ process.kill(pid, 0);
25
+ return true;
26
+ }
27
+ catch {
28
+ return false;
29
+ }
30
+ }
31
+ /** The process groups of one executor's commands (each command leads its own group). */
32
+ export class GroupTracker {
33
+ groups = new Set();
34
+ pruneTimer;
35
+ /** Tracks a spawned command's process group; undefined when it has no pid (spawn failed). */
36
+ track(tag, child) {
37
+ if (child.pid === undefined)
38
+ return undefined;
39
+ const g = { tag, pgid: child.pid, exited: false };
40
+ this.groups.add(g);
41
+ if (this.pruneTimer === undefined) {
42
+ this.pruneTimer = setInterval(() => this.prune(), PRUNE_INTERVAL_MS);
43
+ this.pruneTimer.unref();
44
+ }
45
+ return g;
46
+ }
47
+ /** Stops tracking a group (its command failed to start). */
48
+ forget(g) {
49
+ this.groups.delete(g);
50
+ }
51
+ /** Forgets finished groups with no members left (or whose id was taken by another process). */
52
+ prune() {
53
+ for (const g of this.groups) {
54
+ if (!g.exited)
55
+ continue;
56
+ // A reaped leader's pid can be reused only once its group is gone: a live process with
57
+ // that pid means the id now belongs to someone else.
58
+ if (pidAlive(g.pgid) || !killGroupId(g.pgid, 0))
59
+ this.groups.delete(g);
60
+ }
61
+ this.stopTimerWhenEmpty();
62
+ }
63
+ kill(g) {
64
+ if (g.exited) {
65
+ this.prune();
66
+ if (!this.groups.has(g))
67
+ return;
68
+ }
69
+ g.onKill?.();
70
+ if (!killGroupId(g.pgid) && g.exited)
71
+ this.groups.delete(g);
72
+ }
73
+ /** Kills the groups of the given tags. */
74
+ killTags(tags) {
75
+ const want = new Set(tags);
76
+ for (const g of [...this.groups])
77
+ if (want.has(g.tag))
78
+ this.kill(g);
79
+ }
80
+ killAll() {
81
+ for (const g of [...this.groups])
82
+ this.kill(g);
83
+ }
84
+ /** Stops the prune timer (the groups stay known). */
85
+ dispose() {
86
+ if (this.pruneTimer !== undefined)
87
+ clearInterval(this.pruneTimer);
88
+ this.pruneTimer = undefined;
89
+ }
90
+ /** The number of groups tracked (for tests). */
91
+ get size() {
92
+ return this.groups.size;
93
+ }
94
+ stopTimerWhenEmpty() {
95
+ if (this.groups.size === 0 && this.pruneTimer !== undefined) {
96
+ clearInterval(this.pruneTimer);
97
+ this.pruneTimer = undefined;
98
+ }
99
+ }
100
+ }
@@ -0,0 +1,53 @@
1
+ import type { DeviceExecArgs, ExecResult, SandboxRoots } from "@capybara-hq/plugin-sdk";
2
+ import type { ExecHooks, Executor } from "./types.js";
3
+ export interface HostExecutorOptions {
4
+ /** The device directory (from login). */
5
+ dir: string;
6
+ /** The environment commands start from (default: this program's own, `process.env`). */
7
+ env?: NodeJS.ProcessEnv;
8
+ }
9
+ /**
10
+ * Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
11
+ * user, with this program's own environment plus the request's, so commands see the real `HOME`,
12
+ * `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
13
+ * (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
14
+ * (see `exec/switch.ts`).
15
+ *
16
+ * What stays the same as the OS sandbox: the working directory is checked inside the device's
17
+ * roots, file operations are confined to the roots (direct host IO), and every command leads its
18
+ * own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
19
+ * `killAll` reach it and what it leaves running.
20
+ */
21
+ export declare class HostExecutor implements Executor {
22
+ private readonly opts;
23
+ readonly mode: "os";
24
+ readonly roots: SandboxRoots;
25
+ private readonly dir;
26
+ /** Marks every process of this device's commands: `<dirKey>.<tag>` (as the OS executor). */
27
+ private readonly dirKey;
28
+ private readonly groups;
29
+ private readonly guard;
30
+ private readonly files;
31
+ constructor(opts: HostExecutorOptions);
32
+ ensureRoot(): Promise<"ok" | "gone">;
33
+ /** The marker value of a tag's processes. */
34
+ markerOf(tag: string): string;
35
+ /** The command's environment: this program's, the request's, then the marker. */
36
+ private envFor;
37
+ exec(args: DeviceExecArgs, signal: AbortSignal, hooks?: ExecHooks): Promise<ExecResult>;
38
+ readFile(path: string, maxBytes: number): Promise<{
39
+ data: Uint8Array;
40
+ truncated: boolean;
41
+ } | null>;
42
+ writeFile(path: string, data: Uint8Array): Promise<void>;
43
+ stat(path: string): Promise<{
44
+ size: number;
45
+ isDir: boolean;
46
+ } | null>;
47
+ killTagged(tags: string[]): Promise<void>;
48
+ killAll(): Promise<void>;
49
+ /** Kills every process carrying this device's marker (also a previous run's). */
50
+ killLeftovers(): Promise<void>;
51
+ /** Kills every running command and stops tracking. */
52
+ dispose(): Promise<void>;
53
+ }
@@ -0,0 +1,183 @@
1
+ import { spawn } from "node:child_process";
2
+ import { existsSync, realpathSync } from "node:fs";
3
+ import { constants as osConstants } from "node:os";
4
+ import { resolve } from "node:path";
5
+ import { dirKeyOf, GroupTracker } from "./groups.js";
6
+ import { EXEC_MARKER, killMarked } from "./procs.js";
7
+ import { ENV_NAME_RE, HostFiles, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
8
+ /**
9
+ * Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
10
+ * user, with this program's own environment plus the request's, so commands see the real `HOME`,
11
+ * `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
12
+ * (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
13
+ * (see `exec/switch.ts`).
14
+ *
15
+ * What stays the same as the OS sandbox: the working directory is checked inside the device's
16
+ * roots, file operations are confined to the roots (direct host IO), and every command leads its
17
+ * own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
18
+ * `killAll` reach it and what it leaves running.
19
+ */
20
+ export class HostExecutor {
21
+ opts;
22
+ mode = "os";
23
+ roots;
24
+ dir;
25
+ /** Marks every process of this device's commands: `<dirKey>.<tag>` (as the OS executor). */
26
+ dirKey;
27
+ groups = new GroupTracker();
28
+ guard;
29
+ files;
30
+ constructor(opts) {
31
+ this.opts = opts;
32
+ const dir = resolve(opts.dir);
33
+ this.dir = existsSync(dir) ? realpathSync(dir) : dir;
34
+ this.roots = osRoots(this.dir);
35
+ this.guard = new RootGuard(this.dir, this.roots);
36
+ this.files = new HostFiles(this.roots);
37
+ this.dirKey = dirKeyOf(this.dir);
38
+ }
39
+ async ensureRoot() {
40
+ return this.guard.ensure();
41
+ }
42
+ /** The marker value of a tag's processes. */
43
+ markerOf(tag) {
44
+ return `${this.dirKey}.${tag}`;
45
+ }
46
+ /** The command's environment: this program's, the request's, then the marker. */
47
+ envFor(args) {
48
+ const env = {};
49
+ for (const [k, v] of Object.entries(this.opts.env ?? process.env)) {
50
+ if (v !== undefined)
51
+ env[k] = v;
52
+ }
53
+ for (const [k, v] of Object.entries(args.env ?? {})) {
54
+ if (!ENV_NAME_RE.test(k))
55
+ throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
56
+ env[k] = v;
57
+ }
58
+ env[EXEC_MARKER] = this.markerOf(args.tag);
59
+ return env;
60
+ }
61
+ async exec(args, signal, hooks) {
62
+ signal.throwIfAborted();
63
+ const cwd = await this.files.inside(args.cwd ?? this.roots.workspace, "cwd");
64
+ const env = this.envFor(args);
65
+ // The kernel may have cancelled while the cwd was checked.
66
+ signal.throwIfAborted();
67
+ // The sandbox may have been turned back on meanwhile: judged again with no await before the
68
+ // spawn, so a kill of every unsandboxed command never misses this one.
69
+ hooks?.beforeSpawn?.();
70
+ // detached: the command leads its own process group, so a kill reaches its children too.
71
+ const child = spawn("/bin/bash", ["-c", args.command], {
72
+ cwd,
73
+ env,
74
+ detached: true,
75
+ stdio: ["ignore", "pipe", "pipe"],
76
+ });
77
+ return new Promise((resolvePromise, reject) => {
78
+ const cap = new OutputCap(args.maxOutputBytes);
79
+ let timedOut = false;
80
+ let killed = false;
81
+ let exit;
82
+ let settled = false;
83
+ let grace;
84
+ const group = this.groups.track(args.tag, child);
85
+ if (group) {
86
+ group.onKill = () => {
87
+ // A kill after a clean exit (a background child) leaves the result alone.
88
+ if (exit === undefined)
89
+ killed = true;
90
+ };
91
+ }
92
+ const kill = () => {
93
+ if (group)
94
+ this.groups.kill(group);
95
+ };
96
+ const timer = setTimeout(() => {
97
+ if (exit === undefined)
98
+ timedOut = true;
99
+ kill();
100
+ }, args.timeoutMs);
101
+ const onAbort = () => kill();
102
+ signal.addEventListener("abort", onAbort, { once: true });
103
+ const cleanup = () => {
104
+ clearTimeout(timer);
105
+ if (grace)
106
+ clearTimeout(grace);
107
+ signal.removeEventListener("abort", onAbort);
108
+ if (group) {
109
+ group.exited = true;
110
+ group.onKill = undefined;
111
+ }
112
+ };
113
+ const finish = () => {
114
+ if (settled || exit === undefined)
115
+ return;
116
+ settled = true;
117
+ cleanup();
118
+ child.stdout?.destroy();
119
+ child.stderr?.destroy();
120
+ let exitCode = exit.code;
121
+ if (killed || timedOut)
122
+ exitCode = null;
123
+ else if (exitCode === null && exit.sig !== null) {
124
+ exitCode = 128 + (osConstants.signals[exit.sig] ?? 0);
125
+ }
126
+ resolvePromise({
127
+ exitCode,
128
+ stdout: cap.text("stdout"),
129
+ stderr: cap.text("stderr"),
130
+ truncated: cap.truncated,
131
+ timedOut,
132
+ });
133
+ };
134
+ child.stdout?.on("data", (b) => cap.push("stdout", b));
135
+ child.stderr?.on("data", (b) => cap.push("stderr", b));
136
+ child.once("error", (e) => {
137
+ if (settled)
138
+ return;
139
+ settled = true;
140
+ if (group)
141
+ this.groups.forget(group);
142
+ cleanup();
143
+ reject(e);
144
+ });
145
+ child.once("exit", (code, sig) => {
146
+ exit = { code, sig };
147
+ if (group)
148
+ group.exited = true;
149
+ // A background child may hold the pipes open; do not wait for it past a short grace.
150
+ grace = setTimeout(finish, PIPE_GRACE_MS);
151
+ });
152
+ child.once("close", () => finish());
153
+ });
154
+ }
155
+ async readFile(path, maxBytes) {
156
+ return this.files.read(path, maxBytes);
157
+ }
158
+ async writeFile(path, data) {
159
+ await this.files.write(path, data);
160
+ }
161
+ async stat(path) {
162
+ return this.files.stat(path);
163
+ }
164
+ async killTagged(tags) {
165
+ this.groups.killTags(tags);
166
+ const values = new Set(tags.map((t) => this.markerOf(t)));
167
+ await killMarked((v) => values.has(v));
168
+ }
169
+ async killAll() {
170
+ this.groups.killAll();
171
+ await this.killLeftovers();
172
+ }
173
+ /** Kills every process carrying this device's marker (also a previous run's). */
174
+ async killLeftovers() {
175
+ const prefix = `${this.dirKey}.`;
176
+ await killMarked((v) => v.startsWith(prefix));
177
+ }
178
+ /** Kills every running command and stops tracking. */
179
+ async dispose() {
180
+ await this.killAll();
181
+ this.groups.dispose();
182
+ }
183
+ }
package/dist/exec/os.d.ts CHANGED
@@ -1,5 +1,7 @@
1
- import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
2
- import type { DeviceExecArgs, ExecResult, SandboxRoots } from "@capybara-hq/plugin-sdk";
1
+ import { type SandboxAskCallback, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
2
+ import type { DeviceExecArgs, ExecResult, SandboxRoots, SandboxTier } from "@capybara-hq/plugin-sdk";
3
+ import { type TierFacts } from "../policy.js";
4
+ import { type ProxyGuardResult } from "../proxy-guard.js";
3
5
  import type { Policy } from "../state.js";
4
6
  import { type Executor } from "./types.js";
5
7
  export { osRoots, ROOT_MARKER, utf8Prefix } from "./shared.js";
@@ -13,11 +15,16 @@ export declare function sandboxAvailability(): {
13
15
  export interface OsExecutorOptions {
14
16
  /** The device directory (from login). */
15
17
  dir: string;
16
- policy: Policy;
18
+ /** The local policy now (read at each command, so a change applies without a restart). */
19
+ policy: () => Policy;
17
20
  /** The home whose secret paths are denied (default: the user's home). */
18
21
  home?: string;
19
22
  /** More paths commands may not read (this program's state directory). */
20
23
  denyRead?: string[];
24
+ /** The localhost proxy guard (default: {@link detectLocalProxy}); injectable for tests. */
25
+ detectProxy?: () => Promise<ProxyGuardResult>;
26
+ /** Where the macOS short socket directory is made (default `/private/tmp`). */
27
+ socketBase?: string;
21
28
  }
22
29
  /**
23
30
  * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap):
@@ -37,10 +44,71 @@ export declare class OsExecutor implements Executor {
37
44
  private pruneTimer;
38
45
  private readonly guard;
39
46
  private readonly files;
47
+ /**
48
+ * The limits of the latest command. The ask callback has no command id; a device belongs to one
49
+ * org, so these stand for the org's egress when it explains a refusal.
50
+ */
51
+ private lastLimits;
52
+ /** macOS: the short socket directory (TMPDIR in `dev` / `open`); undefined elsewhere. */
53
+ private socketDir;
54
+ /** The device's package caches (`<dir>/cache`). */
55
+ private readonly cacheDir;
56
+ /** The latest proxy guard result, and the policy object it was taken for. */
57
+ private proxy;
58
+ private guardedPolicy;
59
+ private guardedAt;
60
+ /** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
61
+ private installed;
62
+ /**
63
+ * Commands spawned while nothing narrowed them (policy `open`, their limits `open`) and still
64
+ * running. The ask callback allows any public name only while one runs.
65
+ */
66
+ private readonly openCommands;
40
67
  constructor(opts: OsExecutorOptions);
41
- /** The configuration the sandbox is initialized with (no domains: those are per command). */
42
- config(): SandboxRuntimeConfig;
68
+ /**
69
+ * The tier of work that has no limits of its own (the file helper): the device's choice cut to
70
+ * the latest exec's ceiling, `strict` before any exec (no ceiling known yet).
71
+ */
72
+ tier(policy?: Policy): SandboxTier;
73
+ /** What the tier gives on this machine now (for the policy summary). */
74
+ tierFacts(policy?: Policy): TierFacts;
75
+ /** The latest proxy guard result. */
76
+ proxyGuard(): ProxyGuardResult;
77
+ /** The sandbox configuration for the policy at `tier` (no domains: those are per command). */
78
+ config(policy?: Policy, tier?: SandboxTier): SandboxRuntimeConfig;
79
+ /**
80
+ * Installs {@link config} when the policy or the tier changed it, so the change applies at the
81
+ * next command without a restart. The runtime reads its global configuration at each wrap.
82
+ */
83
+ private applyConfig;
84
+ /** Records the configuration the sandbox was initialized with. */
85
+ markInstalled(config: SandboxRuntimeConfig): void;
86
+ /**
87
+ * macOS: makes the short socket directory (0700) at creation, and again before a `dev` / `open`
88
+ * command when it is gone (macOS prunes /tmp). A path taken by something else leaves the
89
+ * device without one: commands then use the tmp root.
90
+ */
91
+ prepareSocketDir(): void;
92
+ /**
93
+ * Runs the localhost proxy guard at creation, when the policy was reloaded since the last run
94
+ * (the store returns a new object for each new version of policy.json), and when the last result
95
+ * is older than {@link PROXY_GUARD_TTL_MS} (a proxy started after this program). A guard that
96
+ * fails counts as a proxy found (fail safe; `localhost: allow` still overrides).
97
+ */
98
+ refreshProxyGuard(policy: Policy): Promise<void>;
43
99
  ensureRoot(): Promise<"ok" | "gone">;
100
+ /**
101
+ * The sandbox's ask callback, reached only for a host no list allows. sandbox-runtime refuses `*`
102
+ * in a per-command list, so a command that may reach any host (device policy `open`, its limits
103
+ * `open`) is allowed here: a public name is allowed while such a command runs and the policy
104
+ * and latest limits still say so (narrowing takes effect at once). The callback has no command
105
+ * id, so a concurrent command of the same device may ride along meanwhile; the file helper never
106
+ * opens it. Otherwise it refuses, with a reason clients that print the proxy's status phrase
107
+ * show (spec §9.1).
108
+ */
109
+ readonly askCallback: SandboxAskCallback;
110
+ /** The classified network refusals of one command (read before it unregisters). */
111
+ private blockedFor;
44
112
  /** The marker value of a tag's processes. */
45
113
  markerOf(tag: string): string;
46
114
  /**