@capybara-hq/device 0.1.0-rc.12 → 0.1.0-rc.13

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,10 +3,10 @@ import type { Policy, SandboxMode } from "../state.js";
3
3
  import { type ExecMode, type Executor } from "./types.js";
4
4
  export type { ExecMode } from "./types.js";
5
5
  /**
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
6
+ * How long the latest command's limits decide file writes. The kernel judges the mode at each
7
+ * exec, and file writes carry no limits, so a decision older than this no longer counts: file
8
+ * writes 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 writes
10
10
  * around its commands while bounding how long an organization's change takes to reach a device
11
11
  * that runs no more commands.
12
12
  */
@@ -14,17 +14,17 @@ export declare const FILE_OPS_DECISION_TTL_MS = 60000;
14
14
  /** The refusal of an auto-mode command whose sandbox was turned back on before it started. */
15
15
  export declare const SANDBOX_BACK_ON: string;
16
16
  /**
17
- * The refusal of a file operation on a machine without the OS sandbox when no recent command
18
- * decided the mode: file operations never pass command review, so they cannot exceed a ceiling
17
+ * The refusal of a file write on a machine without the OS sandbox when no recent command
18
+ * decided the mode: file writes never pass command review, so they cannot exceed a ceiling
19
19
  * the deployment has not confirmed.
20
20
  */
21
21
  export declare const NO_FRESH_DECISION: string;
22
22
  /**
23
23
  * The OS-mode executor the program serves: each command runs in the sandbox or, in auto mode,
24
24
  * directly on the machine ({@link effectiveMode}). The policy is read per operation, so a change
25
- * applies at the next command. File operations use the host executor's direct IO (any absolute
25
+ * applies at the next command. File writes use the host executor's direct IO (any absolute
26
26
  * path in auto mode, the roots in the sandbox) only while the latest command's decision is fresh;
27
- * before any command, or once its limits are stale, the sandboxed helper runs (file operations
27
+ * before any command, or once its limits are stale, the sandboxed helper runs (file writes
28
28
  * never pass command review, so the org's ceiling may not be exceeded). When the policy turns the
29
29
  * sandbox back on, every auto-mode command still running (and what it left in the background) is
30
30
  * killed, and one still starting is refused right before its spawn; while auto mode is on, the
@@ -47,7 +47,7 @@ export declare class SwitchingExecutor implements Executor {
47
47
  */
48
48
  private readonly sandboxReady;
49
49
  private watch;
50
- /** The latest command's limits and when they came (file operations follow their decision). */
50
+ /** The latest command's limits and when they came (file writes follow their decision). */
51
51
  private lastLimits;
52
52
  private lastLimitsAt;
53
53
  constructor(sandboxed: Executor,
@@ -59,12 +59,12 @@ export declare class SwitchingExecutor implements Executor {
59
59
  */
60
60
  sync(policy?: Policy): Promise<boolean>;
61
61
  /**
62
- * Records an exec's limits, refused ones included, so file operations follow the latest
62
+ * Records an exec's limits, refused ones included, so file writes follow the latest
63
63
  * decision (see {@link FILE_OPS_DECISION_TTL_MS}).
64
64
  */
65
65
  noteLimits(limits: Pick<SandboxLimits, "mode">): void;
66
66
  /**
67
- * The executor for file operations now. File operations carry no limits and never pass command
67
+ * The executor for file writes now. File writes carry no limits and never pass command
68
68
  * review, so they only follow an exec's decision when it is fresh: the sandboxed helper before
69
69
  * any exec and once those limits are stale (the safe default for an organization whose ceiling
70
70
  * is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox there is
@@ -72,7 +72,7 @@ export declare class SwitchingExecutor implements Executor {
72
72
  * run on the host; a fresh auto decision runs them on the host, a sandbox one is refused by the
73
73
  * sandboxed executor with the reason.
74
74
  */
75
- private files;
75
+ private writeFiles;
76
76
  exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
77
77
  /**
78
78
  * Runs one command as `how` decided (the caller logs the same decision). The policy it was
@@ -81,12 +81,12 @@ export declare class SwitchingExecutor implements Executor {
81
81
  * sandbox came back on while it was starting is refused ({@link SANDBOX_BACK_ON}).
82
82
  */
83
83
  execDecided(args: DeviceExecArgs, signal: AbortSignal, how: ExecMode, policy?: Policy): Promise<ExecResult>;
84
- readFile(path: string, maxBytes: number): Promise<{
84
+ readFile(path: string, maxBytes: number, mode?: SandboxMode): Promise<{
85
85
  data: Uint8Array;
86
86
  truncated: boolean;
87
87
  } | null>;
88
88
  writeFile(path: string, data: Uint8Array): Promise<void>;
89
- stat(path: string): Promise<{
89
+ stat(path: string, mode?: SandboxMode): Promise<{
90
90
  size: number;
91
91
  isDir: boolean;
92
92
  } | null>;
@@ -1,10 +1,10 @@
1
1
  import { effectiveMode } from "../policy.js";
2
2
  import { DeviceOpError } from "./types.js";
3
3
  /**
4
- * How long the latest command's limits decide file operations. The kernel judges the mode at each
5
- * exec, and file operations carry no limits, so a decision older than this no longer counts: file
6
- * operations fall back to the sandboxed helper (the safe default for an organization whose ceiling
7
- * is sandbox), until the next command decides again. A minute covers a turn's file operations
4
+ * How long the latest command's limits decide file writes. The kernel judges the mode at each
5
+ * exec, and file writes carry no limits, so a decision older than this no longer counts: file
6
+ * writes fall back to the sandboxed helper (the safe default for an organization whose ceiling
7
+ * is sandbox), until the next command decides again. A minute covers a turn's file writes
8
8
  * around its commands while bounding how long an organization's change takes to reach a device
9
9
  * that runs no more commands.
10
10
  */
@@ -15,19 +15,19 @@ const WATCH_INTERVAL_MS = 1000;
15
15
  export const SANDBOX_BACK_ON = "The sandbox was turned back on on this machine while the command was starting, so it did " +
16
16
  "not run. Run it again: it runs in the sandbox now.";
17
17
  /**
18
- * The refusal of a file operation on a machine without the OS sandbox when no recent command
19
- * decided the mode: file operations never pass command review, so they cannot exceed a ceiling
18
+ * The refusal of a file write on a machine without the OS sandbox when no recent command
19
+ * decided the mode: file writes never pass command review, so they cannot exceed a ceiling
20
20
  * the deployment has not confirmed.
21
21
  */
22
22
  export const NO_FRESH_DECISION = "The OS sandbox is unavailable on this machine and no recent command decided this device's " +
23
- "mode, so file operations are refused until the next command runs (the deployment decides the " +
23
+ "mode, so file writes are refused until the next command runs (the deployment decides the " +
24
24
  "mode at each command).";
25
25
  /**
26
26
  * The OS-mode executor the program serves: each command runs in the sandbox or, in auto mode,
27
27
  * directly on the machine ({@link effectiveMode}). The policy is read per operation, so a change
28
- * applies at the next command. File operations use the host executor's direct IO (any absolute
28
+ * applies at the next command. File writes use the host executor's direct IO (any absolute
29
29
  * path in auto mode, the roots in the sandbox) only while the latest command's decision is fresh;
30
- * before any command, or once its limits are stale, the sandboxed helper runs (file operations
30
+ * before any command, or once its limits are stale, the sandboxed helper runs (file writes
31
31
  * never pass command review, so the org's ceiling may not be exceeded). When the policy turns the
32
32
  * sandbox back on, every auto-mode command still running (and what it left in the background) is
33
33
  * killed, and one still starting is refused right before its spawn; while auto mode is on, the
@@ -49,7 +49,7 @@ export class SwitchingExecutor {
49
49
  */
50
50
  sandboxReady;
51
51
  watch;
52
- /** The latest command's limits and when they came (file operations follow their decision). */
52
+ /** The latest command's limits and when they came (file writes follow their decision). */
53
53
  lastLimits;
54
54
  lastLimitsAt = 0;
55
55
  constructor(sandboxed,
@@ -96,7 +96,7 @@ export class SwitchingExecutor {
96
96
  return auto;
97
97
  }
98
98
  /**
99
- * Records an exec's limits, refused ones included, so file operations follow the latest
99
+ * Records an exec's limits, refused ones included, so file writes follow the latest
100
100
  * decision (see {@link FILE_OPS_DECISION_TTL_MS}).
101
101
  */
102
102
  noteLimits(limits) {
@@ -104,7 +104,7 @@ export class SwitchingExecutor {
104
104
  this.lastLimitsAt = Date.now();
105
105
  }
106
106
  /**
107
- * The executor for file operations now. File operations carry no limits and never pass command
107
+ * The executor for file writes now. File writes carry no limits and never pass command
108
108
  * review, so they only follow an exec's decision when it is fresh: the sandboxed helper before
109
109
  * any exec and once those limits are stale (the safe default for an organization whose ceiling
110
110
  * is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox there is
@@ -112,7 +112,7 @@ export class SwitchingExecutor {
112
112
  * run on the host; a fresh auto decision runs them on the host, a sandbox one is refused by the
113
113
  * sandboxed executor with the reason.
114
114
  */
115
- async files() {
115
+ async writeFiles() {
116
116
  const policy = this.policy();
117
117
  await this.sync(policy);
118
118
  if (policy.mode === "sandbox")
@@ -148,14 +148,16 @@ export class SwitchingExecutor {
148
148
  };
149
149
  return this.host.exec(args, signal, { beforeSpawn });
150
150
  }
151
- async readFile(path, maxBytes) {
152
- return (await this.files()).readFile(path, maxBytes);
151
+ async readFile(path, maxBytes, mode = "sandbox") {
152
+ const r = await this.readerFor(mode);
153
+ return r.ex.readFile(path, maxBytes);
153
154
  }
154
155
  async writeFile(path, data) {
155
- return (await this.files()).writeFile(path, data);
156
+ return (await this.writeFiles()).writeFile(path, data);
156
157
  }
157
- async stat(path) {
158
- return (await this.files()).stat(path);
158
+ async stat(path, mode = "sandbox") {
159
+ const r = await this.readerFor(mode);
160
+ return r.ex.stat(path);
159
161
  }
160
162
  /**
161
163
  * The executor that reads as a device in `mode` (the request's own effective mode), without the
@@ -167,6 +169,8 @@ export class SwitchingExecutor {
167
169
  const policy = this.policy();
168
170
  await this.sync(policy);
169
171
  const auto = mode === "auto" && policy.mode === "auto";
172
+ if (!auto && !this.sandboxReady)
173
+ throw new DeviceOpError("policy", "The OS sandbox is unavailable; this file request requires sandbox mode.");
170
174
  return auto ? { ex: this.host, mode: "auto" } : { ex: this.sandboxed, mode: "sandbox" };
171
175
  }
172
176
  async list(mode, path, limit, signal) {
@@ -22,14 +22,14 @@ export interface Executor {
22
22
  * the executor that runs commands without a sandbox; others may ignore them.
23
23
  */
24
24
  exec(args: DeviceExecArgs, signal: AbortSignal, hooks?: ExecHooks): Promise<ExecResult>;
25
- /** The file's bytes (at most `maxBytes`); null when it does not exist. */
26
- readFile(path: string, maxBytes: number): Promise<{
25
+ /** The file's bytes (at most `maxBytes`); null when it does not exist. The switching executor uses this request's mode, defaulting to sandbox. */
26
+ readFile(path: string, maxBytes: number, mode?: SandboxMode): Promise<{
27
27
  data: Uint8Array;
28
28
  truncated: boolean;
29
29
  } | null>;
30
30
  writeFile(path: string, data: Uint8Array): Promise<void>;
31
31
  /** null when the path does not exist. */
32
- stat(path: string): Promise<{
32
+ stat(path: string, mode?: SandboxMode): Promise<{
33
33
  size: number;
34
34
  isDir: boolean;
35
35
  } | null>;
@@ -54,7 +54,7 @@ export interface Executor {
54
54
  ensureRoot(): Promise<"ok" | "gone">;
55
55
  /**
56
56
  * OS mode, an executor that can run without a sandbox: records an exec's limits, also of one
57
- * the policy sent to the sandbox, so file operations follow the latest decision.
57
+ * the policy sent to the sandbox, so file writes follow the latest decision.
58
58
  */
59
59
  noteLimits?(limits: DeviceExecArgs["limits"]): void;
60
60
  /**
@@ -240,7 +240,7 @@ function requestCeiling(args) {
240
240
  /**
241
241
  * A `list` or `scan` request (a trust boundary: the device decides what a web session sees of its
242
242
  * machine). Each is read in the mode it would run in now, `effectiveMode` of the owner's policy and
243
- * the ceiling the request carries, never one an earlier command saw nor the file operations'
243
+ * the ceiling the request carries, never one an earlier command saw nor the file writes'
244
244
  * window. Answered without the device directory: it reads the owner's machine, not that
245
245
  * directory. Throws like the executor (a path its mode cannot reach is a `policy` refusal).
246
246
  */
@@ -267,6 +267,13 @@ async function serveRead(executor, req, signal, store) {
267
267
  const result = await executor.scan(mode, base, signal);
268
268
  return { result, detail: `scan ${clean(base, 300)} in ${mode} mode` };
269
269
  }
270
+ /** Each file read uses this request's ceiling, intersected with the machine's current choice. */
271
+ function readMode(args, store) {
272
+ const mode = args?.limits?.mode;
273
+ if (mode !== "auto" && mode !== "sandbox")
274
+ throw new DeviceOpError("error", "invalid request: file reads require limits.mode auto or sandbox");
275
+ return store === undefined ? "sandbox" : effectiveMode(store.current(), { mode });
276
+ }
270
277
  /** The audit line of an exec whose grants applied (sandbox mode only: auto mode ignores grants). */
271
278
  function grantsDetail(executor, args, policy) {
272
279
  if (executor.mode !== "os" || args.grants === undefined || policy === undefined) {
@@ -344,7 +351,7 @@ export async function serveOp(executor, req, signal, ctx = {}) {
344
351
  const run = {
345
352
  mode: effectiveMode(policy ?? DEFAULT_POLICY, args.limits),
346
353
  };
347
- // These limits are the latest decision file operations follow.
354
+ // These limits are the latest decision file writes follow.
348
355
  executor.noteLimits?.(args.limits);
349
356
  const detail = grantsDetail(executor, args, policy);
350
357
  try {
@@ -360,7 +367,8 @@ export async function serveOp(executor, req, signal, ctx = {}) {
360
367
  }
361
368
  case "readFile": {
362
369
  const a = req.args;
363
- const r = await executor.readFile(a.path, a.maxBytes);
370
+ const mode = readMode(req.args, ctx.policy);
371
+ const r = await executor.readFile(a.path, a.maxBytes, mode);
364
372
  return {
365
373
  res: ok(r === null
366
374
  ? null
@@ -372,8 +380,10 @@ export async function serveOp(executor, req, signal, ctx = {}) {
372
380
  await executor.writeFile(a.path, Buffer.from(a.dataB64, "base64"));
373
381
  return { res: ok(null) };
374
382
  }
375
- case "stat":
376
- return { res: ok(await executor.stat(req.args.path)) };
383
+ case "stat": {
384
+ const a = req.args;
385
+ return { res: ok(await executor.stat(a.path, readMode(req.args, ctx.policy))) };
386
+ }
377
387
  case "killTagged":
378
388
  await executor.killTagged(req.args.tags);
379
389
  return { res: ok(null) };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/device",
3
- "version": "0.1.0-rc.12",
3
+ "version": "0.1.0-rc.13",
4
4
  "description": "capybara-device: connects a laptop or server to a Capybara deployment as a device",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -34,7 +34,7 @@
34
34
  "dependencies": {
35
35
  "@anthropic-ai/sandbox-runtime": "0.0.81",
36
36
  "ws": "^8.18.0",
37
- "@capybara-hq/plugin-sdk": "^0.1.0-rc.24"
37
+ "@capybara-hq/plugin-sdk": "^0.1.0-rc.25"
38
38
  },
39
39
  "devDependencies": {
40
40
  "@types/ws": "^8.5.13"