@capybara-hq/device 0.1.0-rc.8 → 0.1.0-rc.9

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 (46) hide show
  1. package/README.md +90 -179
  2. package/dist/api.d.ts +5 -0
  3. package/dist/args.d.ts +7 -2
  4. package/dist/args.js +33 -16
  5. package/dist/cli.d.ts +7 -5
  6. package/dist/cli.js +20 -31
  7. package/dist/client.d.ts +0 -2
  8. package/dist/client.js +9 -10
  9. package/dist/command-log.d.ts +3 -5
  10. package/dist/commands/login.js +55 -1
  11. package/dist/commands/mode.d.ts +52 -0
  12. package/dist/commands/mode.js +108 -0
  13. package/dist/commands/policy.d.ts +11 -65
  14. package/dist/commands/policy.js +62 -249
  15. package/dist/commands/start.d.ts +2 -2
  16. package/dist/commands/start.js +14 -6
  17. package/dist/commands/status.js +11 -3
  18. package/dist/exec/docker.d.ts +22 -30
  19. package/dist/exec/docker.js +81 -69
  20. package/dist/exec/fs-helper.d.ts +13 -8
  21. package/dist/exec/fs-helper.js +30 -12
  22. package/dist/exec/host.d.ts +8 -8
  23. package/dist/exec/host.js +9 -9
  24. package/dist/exec/os.d.ts +36 -69
  25. package/dist/exec/os.js +65 -159
  26. package/dist/exec/sandbox-messages.d.ts +14 -0
  27. package/dist/exec/sandbox-messages.js +21 -0
  28. package/dist/exec/shared.d.ts +21 -36
  29. package/dist/exec/shared.js +30 -164
  30. package/dist/exec/switch.d.ts +38 -55
  31. package/dist/exec/switch.js +58 -108
  32. package/dist/exec/types.d.ts +8 -18
  33. package/dist/index.d.ts +1 -1
  34. package/dist/network.d.ts +7 -7
  35. package/dist/network.js +11 -18
  36. package/dist/policy-store.d.ts +7 -8
  37. package/dist/policy-store.js +11 -15
  38. package/dist/policy.d.ts +25 -100
  39. package/dist/policy.js +44 -146
  40. package/dist/server-ops.d.ts +15 -35
  41. package/dist/server-ops.js +36 -117
  42. package/dist/state.d.ts +15 -16
  43. package/dist/state.js +38 -36
  44. package/package.json +2 -2
  45. package/dist/proxy-guard.d.ts +0 -58
  46. package/dist/proxy-guard.js +0 -137
@@ -1,4 +1,5 @@
1
- import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
1
+ import { type SandboxRoots } from "@capybara-hq/plugin-sdk";
2
+ import type { SandboxMode } from "../state.js";
2
3
  import { DeviceOpError } from "./types.js";
3
4
  /** The file that marks a directory as a device directory this program has used. */
4
5
  export declare const ROOT_MARKER = ".capybara-device";
@@ -7,25 +8,11 @@ export declare const PIPE_GRACE_MS = 200;
7
8
  export declare const ENV_NAME_RE: RegExp;
8
9
  /** The roots of a device directory: `<dir>/workspace`, `<dir>/skills`, `<dir>/tmp`. */
9
10
  export declare function osRoots(dir: string): SandboxRoots;
10
- /** The device's package caches: `<dir>/cache`, outside the workspace (spec §5.2.1). */
11
- export declare function cacheRoot(dir: string): string;
12
- /**
13
- * The cache variables of `dev` / `open` (spec §5.2.1), each pointing at a folder of `root`
14
- * (`MAVEN_OPTS` as `-Dmaven.repo.local=<folder>`). With `create` (on the host, before a
15
- * sandboxed command), the root is made a real directory first ({@link ensureCacheRoot}) and the
16
- * folders are made on demand; a folder that cannot be made leaves its variable out, and a root
17
- * that cannot be made, or that was swapped while the folders were made, leaves every variable
18
- * out, so a broken cache never stops the next command. A command's
19
- * own value wins: callers apply the request's environment after these.
20
- */
21
- export declare function cacheEnv(root: string, opts?: {
22
- create?: boolean;
23
- }): Record<string, string>;
24
11
  /**
25
12
  * The data directories of version managers, relative to the home: the OS sandbox sets HOME to the
26
13
  * workspace, so their shims would look there and fail ("unknown command: python3. Perhaps you
27
14
  * have to reshim?"). mise's follow XDG_DATA_HOME / XDG_CONFIG_HOME when the device's environment
28
- * sets them. CARGO_HOME is a package cache ({@link cacheEnv}).
15
+ * sets them.
29
16
  */
30
17
  export declare const TOOL_HOME_DIRS: readonly (readonly [string, string])[];
31
18
  /**
@@ -37,20 +24,6 @@ export declare const TOOL_HOME_DIRS: readonly (readonly [string, string])[];
37
24
  * home.
38
25
  */
39
26
  export declare function toolHomeEnv(home: string, env?: Record<string, string | undefined>): Record<string, string>;
40
- /**
41
- * The short socket directory of a device on macOS (spec §5.2.3): `<base>/cap-<first 8 hex of the
42
- * device's key>`, short enough for Chromium's singleton socket (unix socket paths stop at 104
43
- * bytes). `base` is `/private/tmp` outside tests.
44
- */
45
- export declare function socketDirPath(dirKey: string, base?: string): string;
46
- /**
47
- * Creates the socket directory (mode 0700), or checks an existing one is a real directory of this
48
- * user and makes it 0700 again. The check and the mode change go through one descriptor opened
49
- * without following links, so a link swapped in meanwhile (the shared /tmp is sticky, not
50
- * private) is refused, never followed. Returns undefined when the path is taken by something else
51
- * (another user's directory, a file or a link): commands then use the tmp root.
52
- */
53
- export declare function prepareSocketDir(path: string, uid?: number | undefined): string | undefined;
54
27
  /**
55
28
  * The longest prefix of `b` that does not end inside a UTF-8 sequence (a cut buffer's tail is
56
29
  * dropped instead of decoding to U+FFFD).
@@ -89,17 +62,29 @@ export declare class RootGuard {
89
62
  ensure(): "ok" | "gone";
90
63
  }
91
64
  /**
92
- * Host-side file access under the three roots (real paths, symlinks resolved, refused when they
93
- * leave a root). Used for the skills root, which commands can only read, so nothing can race it.
65
+ * Host-side file access. In sandbox mode `path`s are confined to the three roots (real paths,
66
+ * symlinks resolved, refused when they leave a root); in auto mode any clean absolute path is
67
+ * accepted (shape checks only: absolute, no `..` segments, no control characters). Used for the
68
+ * skills root (commands can only read it, so nothing can race it) and by the host executor.
94
69
  */
95
70
  export declare class HostFiles {
96
71
  private readonly roots;
97
- constructor(roots: SandboxRoots);
98
- /** `path` made absolute and normalized; refused unless it is lexically under a root. */
72
+ private readonly mode;
73
+ constructor(roots: SandboxRoots, mode: SandboxMode);
74
+ /**
75
+ * `path` made absolute and normalized; in sandbox mode refused unless it is lexically under a
76
+ * root, in auto mode accepted when its shape is clean.
77
+ */
99
78
  lexical(path: string): string;
100
- /** The real path of an existing `path`, refused unless under a root after resolving links; null when missing. */
79
+ /**
80
+ * The real path of an existing `path` (null when missing); in sandbox mode refused unless under
81
+ * a root after resolving links.
82
+ */
101
83
  existing(path: string): Promise<string | null>;
102
- /** The real path of an existing `path` under a root (symlinks resolved); refused otherwise. */
84
+ /**
85
+ * The real path of an existing `path` (symlinks resolved); in sandbox mode refused unless under
86
+ * a root.
87
+ */
103
88
  inside(path: string, what: string): Promise<string>;
104
89
  private checkReal;
105
90
  private rootList;
@@ -1,6 +1,7 @@
1
- import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, realpathSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
1
+ import { constants, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
2
2
  import { lstat, mkdir, open, realpath } from "node:fs/promises";
3
3
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
4
+ import { validateSandboxPathShape } from "@capybara-hq/plugin-sdk";
4
5
  import { DeviceOpError } from "./types.js";
5
6
  /** The file that marks a directory as a device directory this program has used. */
6
7
  export const ROOT_MARKER = ".capybara-device";
@@ -11,122 +12,11 @@ export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
11
12
  export function osRoots(dir) {
12
13
  return { workspace: join(dir, "workspace"), skills: join(dir, "skills"), tmp: join(dir, "tmp") };
13
14
  }
14
- /** The device's package caches: `<dir>/cache`, outside the workspace (spec §5.2.1). */
15
- export function cacheRoot(dir) {
16
- return join(dir, "cache");
17
- }
18
- /**
19
- * Each cache variable of `dev` / `open` and its folder under the cache root. No pnpm store entry:
20
- * pnpm 10 takes it only from `npm_config_store_dir`, and npm prints a warning about that unknown
21
- * key on every command; pnpm keeps its store at its default under HOME (the workspace).
22
- */
23
- const CACHE_DIRS = [
24
- ["XDG_CACHE_HOME", "xdg"],
25
- ["npm_config_cache", "npm"],
26
- ["PIP_CACHE_DIR", "pip"],
27
- ["UV_CACHE_DIR", "uv"],
28
- ["CARGO_HOME", "cargo"],
29
- ["GOMODCACHE", "go-mod"],
30
- ["GOCACHE", "go-build"],
31
- ["GRADLE_USER_HOME", "gradle"],
32
- ["MAVEN_OPTS", "maven"],
33
- ["PLAYWRIGHT_BROWSERS_PATH", "ms-playwright"],
34
- ["COREPACK_HOME", "corepack"],
35
- ];
36
- /** The device and inode of a real directory (never through a link); undefined otherwise. */
37
- function realDirId(path) {
38
- try {
39
- const st = lstatSync(path);
40
- return st.isDirectory() ? `${st.dev}:${st.ino}` : undefined;
41
- }
42
- catch {
43
- return undefined;
44
- }
45
- }
46
- /**
47
- * Makes the cache root a real directory and returns its identity. Sandboxed commands may write
48
- * the root (it is under `<dir>/cache`), so they can replace it with a link to a host folder: a
49
- * link, a file or anything else in its place is unlinked (never followed) and the root made
50
- * again, mode 0700. Its real path must then be its parent's real path plus its name (nothing in
51
- * between resolves elsewhere). Undefined when it cannot be made a real directory.
52
- */
53
- function ensureCacheRoot(root) {
54
- try {
55
- const st = lstatSync(root);
56
- // unlink, not rm: rm skips a link whose target is missing, and never recurse into a target.
57
- if (!st.isDirectory())
58
- unlinkSync(root);
59
- }
60
- catch (e) {
61
- if (e.code !== "ENOENT")
62
- return undefined;
63
- }
64
- try {
65
- mkdirSync(root, { mode: 0o700 });
66
- }
67
- catch (e) {
68
- if (e.code !== "EEXIST")
69
- return undefined;
70
- }
71
- try {
72
- if (realpathSync(root) !== join(realpathSync(dirname(root)), basename(root)))
73
- return undefined;
74
- }
75
- catch {
76
- return undefined;
77
- }
78
- return realDirId(root);
79
- }
80
- /**
81
- * Makes one cache folder under a verified root: an existing real directory is used, a missing
82
- * one is made (not recursively, so nothing is made through a link). A file or a link a command
83
- * put in its place is left alone (never removed, never followed): its variable is left out.
84
- */
85
- function ensureCacheFolder(path) {
86
- if (realDirId(path) !== undefined)
87
- return true;
88
- try {
89
- mkdirSync(path, { mode: 0o700 });
90
- }
91
- catch {
92
- return false;
93
- }
94
- return realDirId(path) !== undefined;
95
- }
96
- /**
97
- * The cache variables of `dev` / `open` (spec §5.2.1), each pointing at a folder of `root`
98
- * (`MAVEN_OPTS` as `-Dmaven.repo.local=<folder>`). With `create` (on the host, before a
99
- * sandboxed command), the root is made a real directory first ({@link ensureCacheRoot}) and the
100
- * folders are made on demand; a folder that cannot be made leaves its variable out, and a root
101
- * that cannot be made, or that was swapped while the folders were made, leaves every variable
102
- * out, so a broken cache never stops the next command. A command's
103
- * own value wins: callers apply the request's environment after these.
104
- */
105
- export function cacheEnv(root, opts = {}) {
106
- const create = opts.create === true;
107
- const rootId = create ? ensureCacheRoot(root) : undefined;
108
- if (create && rootId === undefined)
109
- return {};
110
- const out = {};
111
- for (const [name, sub] of CACHE_DIRS) {
112
- const path = join(root, sub);
113
- if (create && !ensureCacheFolder(path))
114
- continue;
115
- out[name] = name === "MAVEN_OPTS" ? `-Dmaven.repo.local=${path}` : path;
116
- }
117
- // A concurrent command may have swapped the root meanwhile: then trust none of the folders.
118
- // Accepted narrow race: a swap between ensureCacheRoot and a folder's mkdir makes that one
119
- // fixed-name folder (mode 0700, empty) in the link's target. Nothing is removed or followed
120
- // further, and this recheck of the root's device and inode drops every variable.
121
- if (create && realDirId(root) !== rootId)
122
- return {};
123
- return out;
124
- }
125
15
  /**
126
16
  * The data directories of version managers, relative to the home: the OS sandbox sets HOME to the
127
17
  * workspace, so their shims would look there and fail ("unknown command: python3. Perhaps you
128
18
  * have to reshim?"). mise's follow XDG_DATA_HOME / XDG_CONFIG_HOME when the device's environment
129
- * sets them. CARGO_HOME is a package cache ({@link cacheEnv}).
19
+ * sets them.
130
20
  */
131
21
  export const TOOL_HOME_DIRS = [
132
22
  ["ASDF_DATA_DIR", ".asdf"],
@@ -178,51 +68,6 @@ export function toolHomeEnv(home, env = process.env) {
178
68
  }
179
69
  return out;
180
70
  }
181
- /**
182
- * The short socket directory of a device on macOS (spec §5.2.3): `<base>/cap-<first 8 hex of the
183
- * device's key>`, short enough for Chromium's singleton socket (unix socket paths stop at 104
184
- * bytes). `base` is `/private/tmp` outside tests.
185
- */
186
- export function socketDirPath(dirKey, base = "/private/tmp") {
187
- return join(base, `cap-${dirKey.slice(0, 8)}`);
188
- }
189
- /**
190
- * Creates the socket directory (mode 0700), or checks an existing one is a real directory of this
191
- * user and makes it 0700 again. The check and the mode change go through one descriptor opened
192
- * without following links, so a link swapped in meanwhile (the shared /tmp is sticky, not
193
- * private) is refused, never followed. Returns undefined when the path is taken by something else
194
- * (another user's directory, a file or a link): commands then use the tmp root.
195
- */
196
- export function prepareSocketDir(path, uid = process.getuid?.()) {
197
- try {
198
- mkdirSync(path, { mode: 0o700 });
199
- }
200
- catch (e) {
201
- if (e.code !== "EEXIST")
202
- return undefined;
203
- }
204
- let fd;
205
- try {
206
- fd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
207
- }
208
- catch {
209
- return undefined;
210
- }
211
- try {
212
- const st = fstatSync(fd);
213
- if (!st.isDirectory() || (uid !== undefined && st.uid !== uid))
214
- return undefined;
215
- if ((st.mode & 0o777) !== 0o700)
216
- fchmodSync(fd, 0o700);
217
- return path;
218
- }
219
- catch {
220
- return undefined;
221
- }
222
- finally {
223
- closeSync(fd);
224
- }
225
- }
226
71
  /**
227
72
  * The longest prefix of `b` that does not end inside a UTF-8 sequence (a cut buffer's tail is
228
73
  * dropped instead of decoding to U+FFFD).
@@ -325,16 +170,29 @@ export class RootGuard {
325
170
  }
326
171
  }
327
172
  /**
328
- * Host-side file access under the three roots (real paths, symlinks resolved, refused when they
329
- * leave a root). Used for the skills root, which commands can only read, so nothing can race it.
173
+ * Host-side file access. In sandbox mode `path`s are confined to the three roots (real paths,
174
+ * symlinks resolved, refused when they leave a root); in auto mode any clean absolute path is
175
+ * accepted (shape checks only: absolute, no `..` segments, no control characters). Used for the
176
+ * skills root (commands can only read it, so nothing can race it) and by the host executor.
330
177
  */
331
178
  export class HostFiles {
332
179
  roots;
333
- constructor(roots) {
180
+ mode;
181
+ constructor(roots, mode) {
334
182
  this.roots = roots;
183
+ this.mode = mode;
335
184
  }
336
- /** `path` made absolute and normalized; refused unless it is lexically under a root. */
185
+ /**
186
+ * `path` made absolute and normalized; in sandbox mode refused unless it is lexically under a
187
+ * root, in auto mode accepted when its shape is clean.
188
+ */
337
189
  lexical(path) {
190
+ if (this.mode === "auto") {
191
+ const errors = validateSandboxPathShape(path);
192
+ if (errors.length > 0)
193
+ throw policyError(`${path}: ${errors.join("; ")}`);
194
+ return resolve(path);
195
+ }
338
196
  if (!isAbsolute(path))
339
197
  throw policyError(`${path} is not an absolute path`);
340
198
  const p = resolve(path);
@@ -343,7 +201,10 @@ export class HostFiles {
343
201
  }
344
202
  return p;
345
203
  }
346
- /** The real path of an existing `path`, refused unless under a root after resolving links; null when missing. */
204
+ /**
205
+ * The real path of an existing `path` (null when missing); in sandbox mode refused unless under
206
+ * a root after resolving links.
207
+ */
347
208
  async existing(path) {
348
209
  const p = this.lexical(path);
349
210
  let real;
@@ -357,7 +218,10 @@ export class HostFiles {
357
218
  }
358
219
  return this.checkReal(path, real);
359
220
  }
360
- /** The real path of an existing `path` under a root (symlinks resolved); refused otherwise. */
221
+ /**
222
+ * The real path of an existing `path` (symlinks resolved); in sandbox mode refused unless under
223
+ * a root.
224
+ */
361
225
  async inside(path, what) {
362
226
  const p = this.lexical(path);
363
227
  let real;
@@ -372,6 +236,8 @@ export class HostFiles {
372
236
  return this.checkReal(path, real);
373
237
  }
374
238
  async checkReal(path, real) {
239
+ if (this.mode === "auto")
240
+ return real;
375
241
  const roots = await Promise.all(this.rootList().map((r) => realpath(r).catch(() => r)));
376
242
  if (!roots.some((r) => isUnder(real, r))) {
377
243
  throw policyError(`${path} resolves to ${real}, outside the device's roots`);
@@ -1,51 +1,27 @@
1
- import { type DeviceExecArgs, type ExecResult, type SandboxLimits, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
2
- import { type TierLimits } from "../policy.js";
3
- import type { ProxyGuardResult } from "../proxy-guard.js";
1
+ import type { DeviceExecArgs, ExecResult, SandboxLimits, SandboxRoots } from "@capybara-hq/plugin-sdk";
4
2
  import type { Policy } from "../state.js";
5
- import { type ExecIsolation, type Executor } from "./types.js";
6
- export type { ExecIsolation } from "./types.js";
3
+ import { type ExecMode, type Executor } from "./types.js";
4
+ export type { ExecMode } from "./types.js";
7
5
  /**
8
- * Whether the local policy itself asks for no sandbox: `isolation: "none"` with the owner's own
9
- * tier set to `open` on this machine. A tier the deployment supplies (the org's default) never
10
- * counts, so the kernel can never be the last step that makes commands run unsandboxed.
11
- */
12
- export declare function policyUnsandboxed(policy: Pick<Policy, "tier" | "isolation">): boolean;
13
- /**
14
- * Decides how one command runs (spec §5.4). Without a sandbox only when the local policy says
15
- * `isolation: "none"` with its own tier `open` ({@link policyUnsandboxed}), the device runs in OS
16
- * mode, the kernel allows it for this command (`limits.allowUnsandboxed`: the platform and the
17
- * org allow it and an unattended run has its grant; absent counts as not allowed), and the
18
- * command's tier (that choice cut to the org's ceiling) is `open`. When the policy says `none`
19
- * but any of those does not hold, the command is refused, never run in the sandbox silently: the
20
- * owner asked for no sandbox. The device enforces the kernel's decision itself, because the
21
- * kernel knows the local policy only from the last hello or policy op (spec §4.3); its refusal is
22
- * {@link UNSANDBOXED_NOT_ALLOWED_MESSAGE}, which the kernel maps to its own error. Docker mode
23
- * ignores `isolation` (its container is the isolation).
24
- */
25
- export declare function execIsolation(policy: Pick<Policy, "tier" | "isolation">, limits: ExecLimits, mode: Executor["mode"]): ExecIsolation;
26
- /** What {@link execIsolation} reads of an exec's limits. */
27
- export type ExecLimits = TierLimits & Pick<SandboxLimits, "allowUnsandboxed">;
28
- /** The refusal of a command the policy asks to run without a sandbox below tier `open`. */
29
- export declare function unsandboxedRefusal(policy: Pick<Policy, "tier">, tier: SandboxTier): string;
30
- /**
31
- * How long the latest command's limits decide file operations. The kernel judges the org's
32
- * settings at each exec, and file operations carry no limits, so an unsandboxed decision older
33
- * than this no longer counts: file operations fall back to the sandboxed helper, which reads and
34
- * writes the same roots (only slower), until the next command decides again. A minute covers a
35
- * turn's file operations around its commands while bounding how long an org's change (or a lower
36
- * ceiling) takes to reach a device that runs no more commands.
6
+ * How long the latest command's limits decide file operations. The kernel judges the mode at each
7
+ * exec, and file operations carry no limits, so a decision older than this no longer counts: file
8
+ * operations fall back to the sandboxed helper (the safe default for an organization whose ceiling
9
+ * is sandbox), until the next command decides again. A minute covers a turn's file operations
10
+ * around its commands while bounding how long an organization's change takes to reach a device
11
+ * that runs no more commands.
37
12
  */
38
13
  export declare const FILE_OPS_DECISION_TTL_MS = 60000;
39
- /** The refusal of an unsandboxed command whose sandbox was turned back on before it started. */
14
+ /** The refusal of an auto-mode command whose sandbox was turned back on before it started. */
40
15
  export declare const SANDBOX_BACK_ON: string;
41
16
  /**
42
- * The OS-mode executor the program serves: each command runs in the OS sandbox or, when
43
- * {@link execIsolation} says so, without one; the policy is read per operation, so a change
44
- * applies at once. File operations use the host executor's direct IO (still confined to the
45
- * roots) when the same decision, on the policy now and the latest command's limits, says no
46
- * sandbox; otherwise (and before any command) the sandboxed helper. When the policy turns the
47
- * sandbox back on, every command still running without one (and what it left in the background)
48
- * is killed, and one still starting is refused right before its spawn; while unsandboxed, the
17
+ * The OS-mode executor the program serves: each command runs in the sandbox or, in auto mode,
18
+ * directly on the machine ({@link effectiveMode}). The policy is read per operation, so a change
19
+ * applies at the next command. File operations use the host executor's direct IO (any absolute
20
+ * path in auto mode, the roots in the sandbox) only while the latest command's decision is fresh;
21
+ * before any command, or once its limits are stale, the sandboxed helper runs (file operations
22
+ * never pass command review, so the org's ceiling may not be exceeded). When the policy turns the
23
+ * sandbox back on, every auto-mode command still running (and what it left in the background) is
24
+ * killed, and one still starting is refused right before its spawn; while auto mode is on, the
49
25
  * policy is also checked every second so that happens without waiting for the next operation.
50
26
  * Kills reach both executors' commands.
51
27
  */
@@ -57,38 +33,47 @@ export declare class SwitchingExecutor implements Executor {
57
33
  private readonly onSwitch?;
58
34
  readonly mode: "os";
59
35
  readonly roots: SandboxRoots;
60
- /** The policy asked for no sandbox when last checked. */
61
- private unsandboxed;
36
+ /** The policy said auto mode when last checked. */
37
+ private auto;
38
+ /**
39
+ * Whether the OS sandbox can run here. When it cannot, sandbox-mode operations go to the
40
+ * sandboxed executor and are refused there with the reason; auto mode keeps working.
41
+ */
42
+ private readonly sandboxReady;
62
43
  private watch;
63
44
  /** The latest command's limits and when they came (file operations follow their decision). */
64
45
  private lastLimits;
65
46
  private lastLimitsAt;
66
47
  constructor(sandboxed: Executor,
67
48
  /** Runs commands without a sandbox (the `HostExecutor`). */
68
- host: Executor, policy: () => Policy, onSwitch?: ((isolation: "sandbox" | "none") => void) | undefined);
49
+ host: Executor, policy: () => Policy, onSwitch?: ((mode: "auto" | "sandbox") => void) | undefined);
69
50
  /**
70
- * Rereads the policy; on a change fires `onSwitch` and, when the sandbox came back on, kills
71
- * the unsandboxed commands. Returns whether the policy asks for no sandbox now.
51
+ * Rereads the policy; on a change fires `onSwitch` and, when the sandbox came back on, kills the
52
+ * auto-mode commands. Returns whether the policy says auto mode now.
72
53
  */
73
54
  sync(policy?: Policy): Promise<boolean>;
74
55
  /**
75
56
  * Records an exec's limits, refused ones included, so file operations follow the latest
76
57
  * decision (see {@link FILE_OPS_DECISION_TTL_MS}).
77
58
  */
78
- noteLimits(limits: ExecLimits): void;
59
+ noteLimits(limits: Pick<SandboxLimits, "mode">): void;
79
60
  /**
80
- * The executor for file operations now: the commands' decision on the policy now and the latest
81
- * exec's limits; the sandboxed helper before any exec or once those limits are stale.
61
+ * The executor for file operations now. File operations carry no limits and never pass command
62
+ * review, so they only follow an exec's decision when it is fresh: the sandboxed helper before
63
+ * any exec and once those limits are stale (the safe default for an organization whose ceiling
64
+ * is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox, auto
65
+ * mode still works: without a fresh sandbox decision the host runs them (a sandbox decision is
66
+ * refused by the sandboxed executor with the reason).
82
67
  */
83
68
  private files;
84
69
  exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
85
70
  /**
86
71
  * Runs one command as `how` decided (the caller logs the same decision). The policy it was
87
- * decided on is synced first, so a sandbox turned back on stops the unsandboxed commands. An
88
- * unsandboxed command is decided again on the policy then, right before its spawn: one whose
72
+ * decided on is synced first, so a sandbox turned back on stops the auto-mode commands. An
73
+ * auto-mode command is decided again on the policy then, right before its spawn: one whose
89
74
  * sandbox came back on while it was starting is refused ({@link SANDBOX_BACK_ON}).
90
75
  */
91
- execDecided(args: DeviceExecArgs, signal: AbortSignal, how: ExecIsolation, policy?: Policy): Promise<ExecResult>;
76
+ execDecided(args: DeviceExecArgs, signal: AbortSignal, how: ExecMode, policy?: Policy): Promise<ExecResult>;
92
77
  readFile(path: string, maxBytes: number): Promise<{
93
78
  data: Uint8Array;
94
79
  truncated: boolean;
@@ -101,8 +86,6 @@ export declare class SwitchingExecutor implements Executor {
101
86
  killTagged(tags: string[]): Promise<void>;
102
87
  killAll(): Promise<void>;
103
88
  ensureRoot(): Promise<"ok" | "gone">;
104
- /** The sandboxed executor's latest localhost proxy guard result (see `Executor`). */
105
- proxyGuard(): ProxyGuardResult;
106
89
  /** Stops watching the policy. */
107
90
  dispose(): void;
108
91
  }