@capybara-hq/device 0.1.0-rc.1 → 0.1.0-rc.11

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 (73) hide show
  1. package/README.md +205 -44
  2. package/dist/api.d.ts +6 -1
  3. package/dist/args.d.ts +14 -3
  4. package/dist/args.js +74 -10
  5. package/dist/cli.d.ts +27 -4
  6. package/dist/cli.js +81 -11
  7. package/dist/client.d.ts +19 -6
  8. package/dist/client.js +93 -19
  9. package/dist/command-log.d.ts +8 -0
  10. package/dist/commands/drain.d.ts +14 -1
  11. package/dist/commands/drain.js +31 -2
  12. package/dist/commands/login.d.ts +3 -0
  13. package/dist/commands/login.js +96 -11
  14. package/dist/commands/logout.d.ts +2 -0
  15. package/dist/commands/logout.js +1 -1
  16. package/dist/commands/mode.d.ts +69 -0
  17. package/dist/commands/mode.js +129 -0
  18. package/dist/commands/policy.d.ts +13 -4
  19. package/dist/commands/policy.js +162 -33
  20. package/dist/commands/service.d.ts +26 -4
  21. package/dist/commands/service.js +242 -19
  22. package/dist/commands/signal.d.ts +6 -2
  23. package/dist/commands/signal.js +7 -4
  24. package/dist/commands/start.d.ts +18 -3
  25. package/dist/commands/start.js +46 -7
  26. package/dist/commands/status.js +12 -4
  27. package/dist/commands/stop.d.ts +20 -2
  28. package/dist/commands/stop.js +26 -3
  29. package/dist/exec/docker.d.ts +41 -13
  30. package/dist/exec/docker.js +123 -57
  31. package/dist/exec/fs-helper.d.ts +13 -8
  32. package/dist/exec/fs-helper.js +31 -13
  33. package/dist/exec/groups.d.ts +42 -0
  34. package/dist/exec/groups.js +100 -0
  35. package/dist/exec/host.d.ts +53 -0
  36. package/dist/exec/host.js +183 -0
  37. package/dist/exec/os.d.ts +85 -15
  38. package/dist/exec/os.js +208 -36
  39. package/dist/exec/reap.d.ts +41 -0
  40. package/dist/exec/reap.js +89 -0
  41. package/dist/exec/sandbox-messages.d.ts +14 -0
  42. package/dist/exec/sandbox-messages.js +21 -0
  43. package/dist/exec/shared.d.ts +42 -13
  44. package/dist/exec/shared.js +94 -16
  45. package/dist/exec/switch.d.ts +98 -0
  46. package/dist/exec/switch.js +175 -0
  47. package/dist/exec/types.d.ts +28 -4
  48. package/dist/index.d.ts +1 -1
  49. package/dist/network.d.ts +45 -0
  50. package/dist/network.js +154 -0
  51. package/dist/pid.d.ts +44 -3
  52. package/dist/pid.js +110 -7
  53. package/dist/policy-ops.d.ts +47 -0
  54. package/dist/policy-ops.js +90 -0
  55. package/dist/policy-store.d.ts +43 -0
  56. package/dist/policy-store.js +94 -0
  57. package/dist/policy.d.ts +36 -16
  58. package/dist/policy.js +77 -19
  59. package/dist/public-suffix.d.ts +6 -0
  60. package/dist/public-suffix.js +79 -0
  61. package/dist/server-ops.d.ts +48 -7
  62. package/dist/server-ops.js +287 -29
  63. package/dist/service/installed.d.ts +5 -0
  64. package/dist/service/installed.js +14 -0
  65. package/dist/service/launchd.d.ts +14 -1
  66. package/dist/service/launchd.js +25 -1
  67. package/dist/service/manager.d.ts +41 -0
  68. package/dist/service/manager.js +91 -0
  69. package/dist/service/systemd.d.ts +2 -0
  70. package/dist/service/systemd.js +8 -0
  71. package/dist/state.d.ts +50 -6
  72. package/dist/state.js +195 -16
  73. package/package.json +3 -3
@@ -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 §4.1): `/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. That is auto mode; the program picks this executor per
13
+ * command (see `exec/switch.ts`) when no sandbox is in force.
14
+ *
15
+ * What stays the same as the OS sandbox: the working directory defaults to the device's workspace,
16
+ * every command leads its own process group and carries {@link EXEC_MARKER}, so timeouts, aborts,
17
+ * `killTagged` and `killAll` reach it and what it leaves running. File operations reach any
18
+ * absolute path on the machine (the kernel's `Read` / `Write` / `Edit` / `Glob` / `Grep` do, and
19
+ * the deployment reviews writes outside the workspace, spec §5.1).
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 §4.1): `/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. That is auto mode; the program picks this executor per
12
+ * command (see `exec/switch.ts`) when no sandbox is in force.
13
+ *
14
+ * What stays the same as the OS sandbox: the working directory defaults to the device's workspace,
15
+ * every command leads its own process group and carries {@link EXEC_MARKER}, so timeouts, aborts,
16
+ * `killTagged` and `killAll` reach it and what it leaves running. File operations reach any
17
+ * absolute path on the machine (the kernel's `Read` / `Write` / `Edit` / `Glob` / `Grep` do, and
18
+ * the deployment reviews writes outside the workspace, spec §5.1).
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, "auto");
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,6 +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, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
3
3
  import type { Policy } from "../state.js";
4
+ import { type ReaperDeps } from "./reap.js";
4
5
  import { type Executor } from "./types.js";
5
6
  export { osRoots, ROOT_MARKER, utf8Prefix } from "./shared.js";
6
7
  /** Whether the OS sandbox can run here, and why not. */
@@ -10,44 +11,102 @@ export declare function sandboxAvailability(): {
10
11
  ok: false;
11
12
  reason: string;
12
13
  };
14
+ /** How to fix an unavailable OS sandbox (shared by the command refusal and the mode switch). */
15
+ export { SANDBOX_INSTALL_HINT, sandboxUnavailableMessage, sandboxUnavailableSwitchRefusal, } from "./sandbox-messages.js";
13
16
  export interface OsExecutorOptions {
14
- /** The environment directory (from login). */
17
+ /** The device directory (from login). */
15
18
  dir: string;
16
- policy: Policy;
19
+ /** The local policy now (read at each command, so a change applies without a restart). */
20
+ policy: () => Policy;
17
21
  /** The home whose secret paths are denied (default: the user's home). */
18
22
  home?: string;
19
23
  /** More paths commands may not read (this program's state directory). */
20
24
  denyRead?: string[];
25
+ /** The reaper's process operations (default: the real ones); injectable for tests. */
26
+ reaper?: Partial<ReaperDeps>;
21
27
  }
22
28
  /**
23
- * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap):
24
- * writes only under the workspace and tmp roots, the secret paths unreadable, network only to
25
- * the intersection of the local policy and the environment's egress. File operations in the
26
- * workspace and tmp roots run in a sandboxed helper too. Construct it with
27
- * {@link createOsExecutor}; the constructor alone serves only `ensureRoot` and the skills root.
29
+ * Runs every command inside `@anthropic-ai/sandbox-runtime` (macOS Seatbelt, Linux bubblewrap),
30
+ * today's strict profile (spec §4.4): writes only under the workspace and tmp roots, the secret
31
+ * paths unreadable, no local binding or unix sockets, network only to the intersection of the
32
+ * device's allowlist and the kernel's. File operations in the workspace, tmp and skills roots run
33
+ * in a sandboxed helper too. Construct it with {@link createOsExecutor}; the constructor alone
34
+ * serves only `ensureRoot`.
28
35
  */
29
36
  export declare class OsExecutor implements Executor {
30
37
  private readonly opts;
31
38
  readonly mode: "os";
32
39
  readonly roots: SandboxRoots;
33
40
  private readonly dir;
34
- /** Marks every process of this environment's commands: `<dirKey>.<tag>`. */
41
+ /** Marks every process of this device's commands: `<dirKey>.<tag>.<exec id>`. */
35
42
  private readonly dirKey;
36
43
  private readonly groups;
37
44
  private pruneTimer;
45
+ /** Kills what a foreground exec left running once it ends. */
46
+ private readonly reaper;
38
47
  private readonly guard;
39
48
  private readonly files;
40
- constructor(opts: OsExecutorOptions);
41
- /** The configuration the sandbox is initialized with (no domains: those are per command). */
49
+ /**
50
+ * The network limits of the latest command. The ask callback has no command id; a device belongs
51
+ * to one organization, so these stand for its allowlist when it explains a refusal.
52
+ */
53
+ private lastLimits;
54
+ /** The configuration the sandbox runs with now, as JSON (see {@link applyConfig}). */
55
+ private installed;
56
+ /**
57
+ * Background tasks launched on macOS that still run, by the command id of their launch, with
58
+ * the task's process group id (its sid). A task keeps its launch's network permissions (the
59
+ * per-command list) until its group is gone: it uses the launch's proxy credentials long after
60
+ * the launch returned. Checked on the prune tick.
61
+ */
62
+ private readonly backgroundNet;
63
+ /** Whether the OS sandbox can run here; false means sandbox-mode operations are refused. */
64
+ readonly available: boolean;
65
+ /** Why the OS sandbox is unavailable (when {@link available} is false). */
66
+ readonly unavailableReason: string | undefined;
67
+ constructor(opts: OsExecutorOptions, state?: {
68
+ unavailable?: string;
69
+ });
70
+ /** Throws the actionable refusal when the OS sandbox is unavailable. */
71
+ private requireSandbox;
72
+ /** The sandbox configuration (no domains: those are per command). */
42
73
  config(): SandboxRuntimeConfig;
74
+ /**
75
+ * Installs {@link config} when it changed, so a policy change applies at the next command
76
+ * without a restart. The runtime reads its global configuration at each wrap.
77
+ */
78
+ private applyConfig;
79
+ /** Records the configuration the sandbox was initialized with. */
80
+ markInstalled(config: SandboxRuntimeConfig): void;
43
81
  ensureRoot(): Promise<"ok" | "gone">;
44
- /** The marker value of a tag's processes. */
82
+ /**
83
+ * The sandbox's ask callback, reached only for a host no list allows: it refuses, with a reason
84
+ * clients that print the proxy's status phrase show (spec §9.1). Sandbox mode has no
85
+ * "any host" state (auto mode runs without the OS sandbox and has the machine's network), so
86
+ * this never allows.
87
+ */
88
+ readonly askCallback: SandboxAskCallback;
89
+ /** The classified network refusals of one command (read before it unregisters). */
90
+ private blockedFor;
91
+ /**
92
+ * The marker value of a tag's processes. An exec's processes carry `<this>.<exec id>` (see
93
+ * {@link execMarker}); {@link killTagged} matches both.
94
+ */
45
95
  markerOf(tag: string): string;
96
+ /** The marker value of one exec's processes: its tag's plus an id of its own (no dots in a tag). */
97
+ private execMarker;
46
98
  /**
47
99
  * Wraps `script` (run by bash inside the sandbox, after the request's `env` and TMPDIR are
48
100
  * exported) and spawns it as the leader of a new process group.
49
101
  */
50
102
  private spawnSandboxed;
103
+ /** Drops a command's network permissions (its per-command list). */
104
+ private releaseNet;
105
+ /** Keeps a launched background task's network permissions while its group `sid` lives. */
106
+ private keepBackgroundNet;
107
+ /** Releases the network permissions of background tasks whose group is gone (all: `all`). */
108
+ private pruneBackgroundNet;
109
+ private startPruning;
51
110
  /** Tracks a spawned command's process group; returns the entry. */
52
111
  private track;
53
112
  /** Forgets finished groups with no members left (or whose id was taken by another process). */
@@ -67,14 +126,25 @@ export declare class OsExecutor implements Executor {
67
126
  } | null>;
68
127
  killTagged(tags: string[]): Promise<void>;
69
128
  killAll(): Promise<void>;
70
- /** Kills every process carrying this environment's marker (also a previous run's). */
129
+ /** Kills every process carrying this device's marker (also a previous run's). */
71
130
  killLeftovers(): Promise<void>;
72
131
  /** Kills every running command and shuts the sandbox's proxies down. */
73
132
  dispose(): Promise<void>;
74
133
  }
134
+ /**
135
+ * The process group id a background task launch printed as its last line (the task's sid), on
136
+ * macOS only: there the sandbox shares the host's process ids, so the device can watch the group.
137
+ * Elsewhere (Linux: bwrap's own pid namespace) undefined, and the launch's permissions end with it.
138
+ */
139
+ export declare function launchedGroup(stdout: string, platform?: NodeJS.Platform): number | undefined;
75
140
  /**
76
141
  * The OS sandbox executor: checks the platform and dependencies, starts the sandbox's proxies
77
- * once for this process, and kills what a previous run of this environment left running.
142
+ * once for this process, and kills what a previous run of this device left running.
78
143
  * Network is denied unless a command's own list allows it.
144
+ *
145
+ * When the OS sandbox is unavailable (an unsupported platform or missing dependencies) this still
146
+ * returns an executor, marked unavailable, so `start` keeps serving: auto mode works, and every
147
+ * sandbox-mode command or file operation is refused with the actionable reason
148
+ * ({@link sandboxUnavailableMessage}) instead of running unsandboxed or stopping the device.
79
149
  */
80
150
  export declare function createOsExecutor(opts: OsExecutorOptions): Promise<OsExecutor>;