@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.
- package/dist/exec/switch.d.ts +14 -14
- package/dist/exec/switch.js +22 -18
- package/dist/exec/types.d.ts +4 -4
- package/dist/server-ops.js +15 -5
- package/package.json +2 -2
package/dist/exec/switch.d.ts
CHANGED
|
@@ -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
|
|
7
|
-
* exec, and file
|
|
8
|
-
*
|
|
9
|
-
* is sandbox), until the next command decides again. A minute covers a turn's file
|
|
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
|
|
18
|
-
* decided the mode: file
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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>;
|
package/dist/exec/switch.js
CHANGED
|
@@ -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
|
|
5
|
-
* exec, and file
|
|
6
|
-
*
|
|
7
|
-
* is sandbox), until the next command decides again. A minute covers a turn's file
|
|
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
|
|
19
|
-
* decided the mode: file
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
156
|
+
return (await this.writeFiles()).writeFile(path, data);
|
|
156
157
|
}
|
|
157
|
-
async stat(path) {
|
|
158
|
-
|
|
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) {
|
package/dist/exec/types.d.ts
CHANGED
|
@@ -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
|
|
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
|
/**
|
package/dist/server-ops.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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.
|
|
37
|
+
"@capybara-hq/plugin-sdk": "^0.1.0-rc.25"
|
|
38
38
|
},
|
|
39
39
|
"devDependencies": {
|
|
40
40
|
"@types/ws": "^8.5.13"
|