@capybara-hq/device 0.1.0-rc.14 → 0.1.0-rc.16

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 (109) hide show
  1. package/README.md +101 -157
  2. package/dist/api.d.ts +2 -2
  3. package/dist/args.d.ts +2 -8
  4. package/dist/args.js +2 -25
  5. package/dist/cli.d.ts +2 -11
  6. package/dist/cli.js +6 -61
  7. package/dist/client.d.ts +8 -45
  8. package/dist/client.js +25 -424
  9. package/dist/command-log.d.ts +14 -4
  10. package/dist/command-log.js +37 -1
  11. package/dist/commands/ceiling.d.ts +0 -2
  12. package/dist/commands/ceiling.js +3 -4
  13. package/dist/commands/login.d.ts +25 -1
  14. package/dist/commands/login.js +75 -61
  15. package/dist/commands/policy.d.ts +6 -8
  16. package/dist/commands/policy.js +30 -49
  17. package/dist/commands/start.d.ts +2 -17
  18. package/dist/commands/start.js +13 -53
  19. package/dist/exec/docker-operations.d.ts +2 -2
  20. package/dist/exec/docker-operations.js +4 -2
  21. package/dist/exec/docker.d.ts +37 -122
  22. package/dist/exec/docker.js +72 -717
  23. package/dist/exec/instance-binding.d.ts +4 -4
  24. package/dist/exec/linux-agent.js +30 -0
  25. package/dist/exec/linux-operation-backend.d.ts +5 -0
  26. package/dist/exec/linux-operation-backend.js +3 -1
  27. package/dist/exec/linux-operation-worker.d.ts +9 -0
  28. package/dist/exec/linux-operation-worker.js +11 -2
  29. package/dist/exec/mac-read-policy.d.ts +58 -0
  30. package/dist/exec/mac-read-policy.js +104 -0
  31. package/dist/exec/mac-self-check.d.ts +6 -3
  32. package/dist/exec/mac-self-check.js +28 -5
  33. package/dist/exec/operation-worker.d.ts +21 -2
  34. package/dist/exec/operation-worker.js +164 -43
  35. package/dist/exec/sandbox-check.d.ts +10 -0
  36. package/dist/exec/sandbox-check.js +18 -0
  37. package/dist/exec/sandbox-messages.d.ts +3 -11
  38. package/dist/exec/sandbox-messages.js +3 -18
  39. package/dist/exec/shared.d.ts +24 -47
  40. package/dist/exec/shared.js +53 -165
  41. package/dist/exec/types.d.ts +2 -66
  42. package/dist/exec/types.js +1 -1
  43. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +71 -12
  44. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/macos-sandbox-utils.js +18 -4
  45. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +6 -0
  46. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +4 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/concepts.md +9 -4
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/channel.md +1 -1
  49. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/file-preview.md +2 -0
  50. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/extension-points/sandbox.md +1 -1
  51. package/dist/node_modules/@capybara-hq/plugin-sdk/agent-docs/plugin-format.md +1 -1
  52. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.d.ts +11 -0
  53. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/cards.js +1 -1
  54. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/channel.d.ts +37 -0
  55. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ctx.d.ts +47 -3
  56. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.d.ts +14 -0
  57. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-denied-paths.js +41 -0
  58. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +140 -20
  59. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +419 -14
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/file-preview.d.ts +22 -5
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +77 -13
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/http-access.d.ts +10 -0
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +2 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +2 -3
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +89 -5
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.js +103 -0
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.d.ts +3 -2
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +2 -2
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +4 -0
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.d.ts +1 -1
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-parts.js +11 -0
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +25 -6
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  74. package/dist/owner-report.d.ts +2 -2
  75. package/dist/owner-report.js +2 -2
  76. package/dist/policy-store.d.ts +6 -10
  77. package/dist/policy-store.js +9 -23
  78. package/dist/policy.d.ts +3 -32
  79. package/dist/policy.js +4 -74
  80. package/dist/runtime-manifest.json +1 -1
  81. package/dist/server-ops.d.ts +18 -46
  82. package/dist/server-ops.js +134 -269
  83. package/dist/staged-connect.js +44 -7
  84. package/dist/staged-device.d.ts +4 -4
  85. package/dist/staged-device.js +3 -0
  86. package/dist/staged-session.d.ts +5 -5
  87. package/dist/staged-session.js +4 -4
  88. package/dist/state.js +3 -2
  89. package/package.json +2 -2
  90. package/dist/commands/mode.d.ts +0 -69
  91. package/dist/commands/mode.js +0 -133
  92. package/dist/exec/fs-helper.d.ts +0 -21
  93. package/dist/exec/fs-helper.js +0 -171
  94. package/dist/exec/host.d.ts +0 -61
  95. package/dist/exec/host.js +0 -203
  96. package/dist/exec/listing.d.ts +0 -35
  97. package/dist/exec/listing.js +0 -157
  98. package/dist/exec/os.d.ts +0 -162
  99. package/dist/exec/os.js +0 -616
  100. package/dist/exec/procs.d.ts +0 -11
  101. package/dist/exec/procs.js +0 -67
  102. package/dist/exec/reap.d.ts +0 -41
  103. package/dist/exec/reap.js +0 -89
  104. package/dist/exec/switch.d.ts +0 -107
  105. package/dist/exec/switch.js +0 -204
  106. package/dist/network.d.ts +0 -45
  107. package/dist/network.js +0 -154
  108. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.d.ts +0 -117
  109. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol-v3.js +0 -409
@@ -1,12 +1,7 @@
1
- import { constants, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
2
- import { lstat, mkdir, open, realpath } from "node:fs/promises";
3
- import { basename, dirname, isAbsolute, join, resolve } from "node:path";
4
- import { validateSandboxPathShape } from "@capybara-hq/plugin-sdk";
5
- import { DeviceOpError } from "./types.js";
1
+ import { existsSync, mkdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
2
+ import { isAbsolute, join, normalize } from "node:path";
6
3
  /** The file that marks a directory as a device directory this program has used. */
7
- export const ROOT_MARKER = ".capybara-device";
8
- /** How long a finished command's output pipes may stay open (held by a background child). */
9
- export const PIPE_GRACE_MS = 200;
4
+ const ROOT_MARKER = ".capybara-device";
10
5
  export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
11
6
  /** The roots of a device directory: `<dir>/workspace`, `<dir>/skills`, `<dir>/tmp`. */
12
7
  export function osRoots(dir) {
@@ -29,6 +24,14 @@ export const TOOL_HOME_DIRS = [
29
24
  ["SDKMAN_DIR", ".sdkman"],
30
25
  ["RUSTUP_HOME", ".rustup"],
31
26
  ];
27
+ /**
28
+ * Single files in the home that hold a version manager's global pins, granted read only next to
29
+ * {@link TOOL_HOME_DIRS}: asdf's global `.tool-versions` (mise reads it too). The other managers
30
+ * keep their global version inside their data directory (pyenv and rbenv `version`, nvm
31
+ * `alias/default`, rustup `settings.toml`, mise `config.toml`); a per-project file such as
32
+ * `.nvmrc` is not global. Never a dotfile that could hold a secret.
33
+ */
34
+ export const TOOL_HOME_FILES = [".tool-versions"];
32
35
  function isDir(path) {
33
36
  try {
34
37
  return statSync(path).isDirectory();
@@ -68,6 +71,48 @@ export function toolHomeEnv(home, env = process.env) {
68
71
  }
69
72
  return out;
70
73
  }
74
+ /**
75
+ * What a restricted exec on the host gets for its version managers: the {@link toolHomeEnv}
76
+ * variables of the device process (its real `home` and its own environment `env`), the canonical
77
+ * directories they name as read-only roots, and the global pin files ({@link TOOL_HOME_FILES})
78
+ * that exist as regular files, canonical, as read-only files. A directory is left out when it does
79
+ * not exist, is `/`, lies at or under an owner-denied path, or contains one (Landlock cannot hide
80
+ * a denied path inside a granted root); a file is left out when it, or the target of a link it
81
+ * is, lies at or under one. Nothing here is ever made writable. A command in the device's
82
+ * container uses none of this: its home is the image's.
83
+ */
84
+ export function restrictedToolHomes(home, env, deniedReadRoots) {
85
+ const vars = toolHomeEnv(home, env);
86
+ const inside = (path, root) => root === "/" || path === root || path.startsWith(`${root}/`);
87
+ const denied = (paths, contains) => paths.some((p) => deniedReadRoots.some((d) => inside(p, d) || (contains && inside(d, p))));
88
+ const canonical = (path, kind) => {
89
+ try {
90
+ const real = realpathSync(path);
91
+ const info = statSync(real);
92
+ return (kind === "dir" ? info.isDirectory() : info.isFile()) ? real : undefined;
93
+ }
94
+ catch {
95
+ return undefined;
96
+ }
97
+ };
98
+ const readRoots = new Set();
99
+ for (const dir of Object.values(vars)) {
100
+ const path = normalize(dir).replace(/(.)\/+$/, "$1");
101
+ const real = canonical(path, "dir");
102
+ if (real === undefined || real === "/" || denied([path, real], true))
103
+ continue;
104
+ readRoots.add(real);
105
+ }
106
+ const readFiles = new Set();
107
+ for (const rel of TOOL_HOME_FILES) {
108
+ const path = join(home, rel);
109
+ const real = canonical(path, "file");
110
+ if (real === undefined || denied([path, real], false))
111
+ continue;
112
+ readFiles.add(real);
113
+ }
114
+ return { env: vars, readRoots: [...readRoots], readFiles: [...readFiles] };
115
+ }
71
116
  /**
72
117
  * The longest prefix of `b` that does not end inside a UTF-8 sequence (a cut buffer's tail is
73
118
  * dropped instead of decoding to U+FFFD).
@@ -88,16 +133,6 @@ export function utf8Prefix(b) {
88
133
  export function shellQuote(s) {
89
134
  return `'${s.replaceAll("'", "'\\''")}'`;
90
135
  }
91
- export function isUnder(p, root) {
92
- return p === root || p.startsWith(`${root}/`);
93
- }
94
- export function policyError(message) {
95
- return new DeviceOpError("policy", message);
96
- }
97
- export function isMissing(e) {
98
- const code = e.code;
99
- return code === "ENOENT" || code === "ENOTDIR";
100
- }
101
136
  /** Captures stdout and stderr up to a combined byte budget; the rest is drained and dropped. */
102
137
  export class OutputCap {
103
138
  max;
@@ -169,150 +204,3 @@ export class RootGuard {
169
204
  return "ok";
170
205
  }
171
206
  }
172
- /**
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.
177
- */
178
- export class HostFiles {
179
- roots;
180
- mode;
181
- constructor(roots, mode) {
182
- this.roots = roots;
183
- this.mode = mode;
184
- }
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
- */
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
- }
196
- if (!isAbsolute(path))
197
- throw policyError(`${path} is not an absolute path`);
198
- const p = resolve(path);
199
- if (!this.rootList().some((r) => isUnder(p, r))) {
200
- throw policyError(`${path} is outside the device's roots (${this.rootList().join(", ")})`);
201
- }
202
- return p;
203
- }
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
- */
208
- async existing(path) {
209
- const p = this.lexical(path);
210
- let real;
211
- try {
212
- real = await realpath(p);
213
- }
214
- catch (e) {
215
- if (isMissing(e))
216
- return null;
217
- throw e;
218
- }
219
- return this.checkReal(path, real);
220
- }
221
- /**
222
- * The real path of an existing `path` (symlinks resolved); in sandbox mode refused unless under
223
- * a root.
224
- */
225
- async inside(path, what) {
226
- const p = this.lexical(path);
227
- let real;
228
- try {
229
- real = await realpath(p);
230
- }
231
- catch (e) {
232
- if (isMissing(e))
233
- throw new DeviceOpError("error", `${what} ${path} does not exist`);
234
- throw e;
235
- }
236
- return this.checkReal(path, real);
237
- }
238
- async checkReal(path, real) {
239
- if (this.mode === "auto")
240
- return real;
241
- const roots = await Promise.all(this.rootList().map((r) => realpath(r).catch(() => r)));
242
- if (!roots.some((r) => isUnder(real, r))) {
243
- throw policyError(`${path} resolves to ${real}, outside the device's roots`);
244
- }
245
- return real;
246
- }
247
- rootList() {
248
- return [this.roots.workspace, this.roots.skills, this.roots.tmp];
249
- }
250
- async read(path, maxBytes) {
251
- const real = await this.existing(path);
252
- if (real === null)
253
- return null;
254
- const fh = await open(real, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
255
- try {
256
- const st = await fh.stat();
257
- if (st.isDirectory())
258
- return null;
259
- if (!st.isFile())
260
- throw policyError(`${path} is not a regular file`);
261
- const want = Math.min(st.size, maxBytes);
262
- const buf = Buffer.alloc(want);
263
- let off = 0;
264
- while (off < want) {
265
- const { bytesRead } = await fh.read(buf, off, want - off, off);
266
- if (bytesRead === 0)
267
- break;
268
- off += bytesRead;
269
- }
270
- return { data: buf.subarray(0, off), truncated: st.size > maxBytes };
271
- }
272
- finally {
273
- await fh.close();
274
- }
275
- }
276
- async stat(path) {
277
- const real = await this.existing(path);
278
- if (real === null)
279
- return null;
280
- const st = await lstat(real);
281
- return { size: st.size, isDir: st.isDirectory() };
282
- }
283
- async write(path, data) {
284
- const target = this.lexical(path);
285
- const parent = dirname(target);
286
- // Check the nearest existing ancestor before creating anything beneath it.
287
- let ancestor = parent;
288
- while (!existsSync(ancestor))
289
- ancestor = dirname(ancestor);
290
- await this.inside(ancestor, "path");
291
- await mkdir(parent, { recursive: true });
292
- const realParent = await this.inside(parent, "path");
293
- let file = join(realParent, basename(target));
294
- const st = await lstat(file).catch((e) => {
295
- if (isMissing(e))
296
- return null;
297
- throw e;
298
- });
299
- if (st?.isSymbolicLink()) {
300
- const real = await realpath(file).catch((e) => {
301
- if (isMissing(e))
302
- throw policyError(`${path} is a dangling symbolic link`);
303
- throw e;
304
- });
305
- file = await this.inside(real, "path");
306
- }
307
- const fh = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_NONBLOCK | constants.O_NOFOLLOW, 0o644);
308
- try {
309
- if (!(await fh.stat()).isFile())
310
- throw policyError(`${path} is not a regular file`);
311
- await fh.truncate(0);
312
- await fh.writeFile(data);
313
- }
314
- finally {
315
- await fh.close();
316
- }
317
- }
318
- }
@@ -1,69 +1,5 @@
1
- import type { DeviceErrorKind, DeviceExecArgs, DeviceListResult, DeviceScanResult, ExecResult, SandboxRoots } from "@capybara-hq/plugin-sdk";
2
- import type { Policy, SandboxMode } from "../state.js";
3
- /** How one command runs: in auto mode (no OS sandbox) or in the sandbox. */
4
- export interface ExecMode {
5
- mode: SandboxMode;
6
- }
7
- /** Hooks of one command. */
8
- export interface ExecHooks {
9
- /**
10
- * Called synchronously right before the command is spawned, after everything the executor
11
- * awaits; throwing refuses the command (nothing is spawned) with that error.
12
- */
13
- beforeSpawn?: () => void;
14
- }
15
- /** What runs the operations on this machine: the OS sandbox / host (os) or a container (docker). */
16
- export interface Executor {
17
- readonly mode: "os" | "docker";
18
- readonly roots: SandboxRoots;
19
- /**
20
- * Runs one command; `signal` aborting kills its whole process tree. An executor must not start
21
- * work on an already-aborted signal (the kernel cancelled the request). `hooks` are honoured by
22
- * the executor that runs commands without a sandbox; others may ignore them.
23
- */
24
- exec(args: DeviceExecArgs, signal: AbortSignal, hooks?: ExecHooks): Promise<ExecResult>;
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
- data: Uint8Array;
28
- truncated: boolean;
29
- } | null>;
30
- writeFile(path: string, data: Uint8Array): Promise<void>;
31
- /** null when the path does not exist. */
32
- stat(path: string, mode?: SandboxMode): Promise<{
33
- size: number;
34
- isDir: boolean;
35
- } | null>;
36
- /**
37
- * Lists one directory as a device in `mode` reads (`SandboxProvider.list`'s semantics): `mode`
38
- * is the request's own, `effectiveMode(policy, limits)` on the ceiling that came with it, never
39
- * the latest command's decision. Auto mode reads with the owner's rights; sandbox mode through
40
- * the sandboxed helper, the workspace only; a container device its workspace only, in either
41
- * mode. A path the mode cannot reach throws a `policy` refusal. Works without the device
42
- * directory (it is not called through `ensureRoot`). Optional: without it (and {@link scan})
43
- * the device answers `list` and `scan` as unsupported.
44
- */
45
- list?(mode: SandboxMode, path: string, limit: number, signal: AbortSignal): Promise<DeviceListResult>;
46
- /** Looks for projects under `base` as a device in `mode` reads ({@link list}'s rules). */
47
- scan?(mode: SandboxMode, base: string, signal: AbortSignal): Promise<DeviceScanResult>;
48
- killTagged(tags: string[]): Promise<void>;
49
- killAll(): Promise<void>;
50
- /**
51
- * Creates the device directory (and its marker file) on first use. "gone" when it existed
52
- * before and has vanished; it is never recreated silently.
53
- */
54
- ensureRoot(): Promise<"ok" | "gone">;
55
- /**
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 writes follow the latest decision.
58
- */
59
- noteLimits?(limits: DeviceExecArgs["limits"]): void;
60
- /**
61
- * OS mode, an executor that can run without a sandbox: runs one command as `how` (decided by
62
- * the caller on `policy`, and logged by it) says, instead of deciding again in {@link exec}.
63
- */
64
- execDecided?(args: DeviceExecArgs, signal: AbortSignal, how: ExecMode, policy: Policy): Promise<ExecResult>;
65
- }
66
- /** An executor failure with a protocol error kind (default `error`). */
1
+ import type { DeviceErrorKind } from "@capybara-hq/plugin-sdk";
2
+ /** A device failure with a protocol error kind (default `error`). */
67
3
  export declare class DeviceOpError extends Error {
68
4
  readonly kind: DeviceErrorKind;
69
5
  constructor(kind: DeviceErrorKind, message: string);
@@ -1,4 +1,4 @@
1
- /** An executor failure with a protocol error kind (default `error`). */
1
+ /** A device failure with a protocol error kind (default `error`). */
2
2
  export class DeviceOpError extends Error {
3
3
  kind;
4
4
  constructor(kind, message) {
@@ -1,22 +1,57 @@
1
1
  diff --git a/dist/sandbox/macos-sandbox-utils.js b/dist/sandbox/macos-sandbox-utils.js
2
- index 0e598b612d84d24b09ec2ab0d7ccc9b009c9457b..42f25ad99eb58d1024aa58f9b4a96d996b4afdad 100644
2
+ index 0e598b612d84d24b09ec2ab0d7ccc9b009c9457b..10c4bd0b6518f6b968a105b0ed70838bbd009da9 100644
3
3
  --- a/dist/sandbox/macos-sandbox-utils.js
4
4
  +++ b/dist/sandbox/macos-sandbox-utils.js
5
- @@ -745,6 +745,13 @@ function generateWriteRules(config, logTag, allowGitConfig, writeRoots) {
5
+ @@ -220,6 +220,18 @@ function inBothSpellings(kind, entry) {
6
+ : { glob: false, path: canonical },
7
+ ];
8
+ }
9
+ +/**
10
+ + * capybara patch: the exact read allows, as given. Each must be an absolute, normalized path; it
11
+ + * becomes a `(literal …)` filter, so a directory's entries can be listed but nothing below it
12
+ + * is read, and a symbolic link can be followed or read but not its target.
13
+ + */
14
+ +function exactReadAllows(paths) {
15
+ + for (const p of paths ?? []) {
16
+ + if (typeof p !== 'string' || !path.isAbsolute(p) || path.normalize(p) !== p || (p !== '/' && p.endsWith('/')) || p.includes('\0'))
17
+ + throw new Error(`An exact read allow must be an absolute, normalized path: ${p}`);
18
+ + }
19
+ + return [...new Set(paths ?? [])];
20
+ +}
21
+ function resolveReadConfig(config, writeRoots,
22
+ /**
23
+ * Read denies the library resolved itself — the masked credential files,
24
+ @@ -244,6 +256,8 @@ libraryDenies) {
25
+ // the nested-deny re-emit matches by `path + '/'` prefix, which a
26
+ // preserved trailing slash would defeat ('<dir>//').
27
+ allows: callerEntries('allow', config.allowWithinDeny, config.literalAllowWithinDeny).flatMap(entry => inBothSpellings('allow', entry)),
28
+ + // capybara patch: exact read allows, each one vnode, never the subtree below it
29
+ + exactAllows: exactReadAllows(config.exactAllowWithinDeny),
30
+ writeRoots: [...writeRoots],
31
+ };
32
+ }
33
+ @@ -644,6 +658,9 @@ function generateReadRules(resolved, logTag) {
34
+ rules.push(...renderRule('deny', ['file-read*'], denyFilters, logTag));
35
+ // Re-allow specific paths within denied regions (allowWithinDeny takes precedence)
36
+ const allowFilters = new Set(resolved.allows.map(a => pathFilter(a)));
37
+ + // capybara patch: exact allows join the allow block, so the late denies still win over them
38
+ + for (const p of resolved.exactAllows ?? [])
39
+ + allowFilters.add(`(literal ${escapePath(p)})`);
40
+ rules.push(...renderRule('allow', ['file-read*'], allowFilters, logTag));
41
+ // Denies the allow block would otherwise win over (last-match-wins) land
42
+ // here, after it. Must stay ahead of the file-read-metadata allow below.
43
+ @@ -745,6 +762,10 @@ function generateWriteRules(config, logTag, allowGitConfig, writeRoots) {
6
44
  }
7
45
  }
8
46
  rules.push(...renderRule('deny', ['file-write-unlink', 'file-write-create'], moveFilters, logTag));
9
47
  + // capybara patch: ordered raw regex rules, last, so each decides over everything before it
10
- + // (raw #"…" strings: SBPL string escapes would change the regex; a quote cannot occur)
11
48
  + for (const rule of config.regexRules ?? []) {
12
- + if (rule.regex.includes('"'))
13
- + throw new Error('A raw regex write rule cannot contain a double quote');
14
- + rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex #"${rule.regex}")`]), logTag));
49
+ + rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex ${escapePath(rule.regex)})`]), logTag));
15
50
  + }
16
51
  return rules;
17
52
  }
18
53
  /**
19
- @@ -851,6 +858,8 @@ function generateSandboxProfile({ readConfig, libraryDenyEntries, writeConfig, h
54
+ @@ -851,6 +872,8 @@ function generateSandboxProfile({ readConfig, libraryDenyEntries, writeConfig, h
20
55
  ' (sysctl-name "hw.logicalcpu")',
21
56
  ' (sysctl-name "hw.logicalcpu_max")',
22
57
  ' (sysctl-name "hw.machine")',
@@ -26,13 +61,19 @@ index 0e598b612d84d24b09ec2ab0d7ccc9b009c9457b..42f25ad99eb58d1024aa58f9b4a96d99
26
61
  ' (sysctl-name "hw.ncpu")',
27
62
  ' (sysctl-name "hw.nperflevels")',
28
63
  diff --git a/dist/sandbox/sandbox-config.js b/dist/sandbox/sandbox-config.js
29
- index 76b00b1dc82a2d42a451a9f58068cbbd5e68da75..784dac7f685068a85c3f95f9fe472dac0e1ba65b 100644
64
+ index 76b00b1dc82a2d42a451a9f58068cbbd5e68da75..25ea77fe4259ddeb8578262fffd2021c7c06aa0d 100644
30
65
  --- a/dist/sandbox/sandbox-config.js
31
66
  +++ b/dist/sandbox/sandbox-config.js
32
- @@ -832,6 +832,16 @@ export const FilesystemConfigSchema = z.object({
67
+ @@ -832,6 +832,22 @@ export const FilesystemConfigSchema = z.object({
33
68
  .boolean()
34
69
  .optional()
35
70
  .describe('Allow writes to .git/config files (default: false). Enables git remote URL updates while keeping .git/hooks protected.'),
71
+ + // capybara patch: exact read allows (macOS): absolute paths emitted as (literal …), never
72
+ + // (subpath …), for directories whose entries a command may list or links it may follow
73
+ + allowReadExact: z
74
+ + .array(z.string())
75
+ + .optional()
76
+ + .describe('macOS only: absolute paths re-allowed for reading as exactly that path, not its subtree'),
36
77
  + // capybara patch: ordered raw SBPL regex write rules (macOS), emitted after every other
37
78
  + // write rule so they decide last (Seatbelt is last-match-wins for the same operations)
38
79
  + writeRegexRules: z
@@ -47,10 +88,19 @@ index 76b00b1dc82a2d42a451a9f58068cbbd5e68da75..784dac7f685068a85c3f95f9fe472dac
47
88
  /**
48
89
  * Configuration schema for ignoring specific sandbox violations
49
90
  diff --git a/dist/sandbox/sandbox-manager.js b/dist/sandbox/sandbox-manager.js
50
- index d475e55977bf54a2fe00a0c6aba38313761d55aa..a9a1d4b42f983adabdbc3659b1910b3f36bb61c2 100644
91
+ index d475e55977bf54a2fe00a0c6aba38313761d55aa..d60dab574bca5a1071e55dae7c597c6a2c86a4a6 100644
51
92
  --- a/dist/sandbox/sandbox-manager.js
52
93
  +++ b/dist/sandbox/sandbox-manager.js
53
- @@ -1516,6 +1516,8 @@ function getFsWriteConfig() {
94
+ @@ -1493,6 +1493,8 @@ function getFsReadConfig() {
95
+ allowWithinDeny: allowPaths,
96
+ unlistableDenyDirs: [...unlistableDenyDirs],
97
+ ...literalReadLists(config.filesystem.denyRead, config.filesystem.allowRead),
98
+ + // capybara patch: exact read allows (macOS)
99
+ + exactAllowWithinDeny: config.filesystem.allowReadExact ?? [],
100
+ };
101
+ }
102
+ function getFsWriteConfig() {
103
+ @@ -1516,6 +1518,8 @@ function getFsWriteConfig() {
54
104
  allowOnly,
55
105
  denyWithinAllow: denyPaths,
56
106
  ...literalWriteLists(config.filesystem.allowWrite, config.filesystem.denyWrite),
@@ -59,7 +109,7 @@ index d475e55977bf54a2fe00a0c6aba38313761d55aa..a9a1d4b42f983adabdbc3659b1910b3f
59
109
  };
60
110
  }
61
111
  /**
62
- @@ -1866,6 +1868,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
112
+ @@ -1866,6 +1870,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
63
113
  config?.filesystem.denyWrite ??
64
114
  []),
65
115
  ...literalWriteLists(customConfig?.filesystem?.allowWrite ?? config?.filesystem.allowWrite, customConfig?.filesystem?.denyWrite ?? config?.filesystem.denyWrite),
@@ -68,3 +118,12 @@ index d475e55977bf54a2fe00a0c6aba38313761d55aa..a9a1d4b42f983adabdbc3659b1910b3f
68
118
  };
69
119
  // For a caller that never reads checkDependencies(), the CLI among them.
70
120
  if (!ownInstallLogged) {
121
+ @@ -1917,6 +1923,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
122
+ ...(ownAllowWithinDeny.length > 0 && { ownAllowWithinDeny }),
123
+ unlistableDenyDirs: [...unlistableDenyDirs],
124
+ ...literalReadLists(customConfig?.filesystem?.denyRead ?? config?.filesystem.denyRead, customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead),
125
+ + // capybara patch: exact read allows (macOS)
126
+ + exactAllowWithinDeny: customConfig?.filesystem?.allowReadExact ?? config?.filesystem.allowReadExact ?? [],
127
+ };
128
+ }
129
+ // Nothing below walks, and what it waits for is not this thread.
@@ -220,6 +220,18 @@ function inBothSpellings(kind, entry) {
220
220
  : { glob: false, path: canonical },
221
221
  ];
222
222
  }
223
+ /**
224
+ * capybara patch: the exact read allows, as given. Each must be an absolute, normalized path; it
225
+ * becomes a `(literal …)` filter, so a directory's entries can be listed but nothing below it
226
+ * is read, and a symbolic link can be followed or read but not its target.
227
+ */
228
+ function exactReadAllows(paths) {
229
+ for (const p of paths ?? []) {
230
+ if (typeof p !== 'string' || !path.isAbsolute(p) || path.normalize(p) !== p || (p !== '/' && p.endsWith('/')) || p.includes('\0'))
231
+ throw new Error(`An exact read allow must be an absolute, normalized path: ${p}`);
232
+ }
233
+ return [...new Set(paths ?? [])];
234
+ }
223
235
  function resolveReadConfig(config, writeRoots,
224
236
  /**
225
237
  * Read denies the library resolved itself — the masked credential files,
@@ -244,6 +256,8 @@ libraryDenies) {
244
256
  // the nested-deny re-emit matches by `path + '/'` prefix, which a
245
257
  // preserved trailing slash would defeat ('<dir>//').
246
258
  allows: callerEntries('allow', config.allowWithinDeny, config.literalAllowWithinDeny).flatMap(entry => inBothSpellings('allow', entry)),
259
+ // capybara patch: exact read allows, each one vnode, never the subtree below it
260
+ exactAllows: exactReadAllows(config.exactAllowWithinDeny),
247
261
  writeRoots: [...writeRoots],
248
262
  };
249
263
  }
@@ -644,6 +658,9 @@ function generateReadRules(resolved, logTag) {
644
658
  rules.push(...renderRule('deny', ['file-read*'], denyFilters, logTag));
645
659
  // Re-allow specific paths within denied regions (allowWithinDeny takes precedence)
646
660
  const allowFilters = new Set(resolved.allows.map(a => pathFilter(a)));
661
+ // capybara patch: exact allows join the allow block, so the late denies still win over them
662
+ for (const p of resolved.exactAllows ?? [])
663
+ allowFilters.add(`(literal ${escapePath(p)})`);
647
664
  rules.push(...renderRule('allow', ['file-read*'], allowFilters, logTag));
648
665
  // Denies the allow block would otherwise win over (last-match-wins) land
649
666
  // here, after it. Must stay ahead of the file-read-metadata allow below.
@@ -746,11 +763,8 @@ function generateWriteRules(config, logTag, allowGitConfig, writeRoots) {
746
763
  }
747
764
  rules.push(...renderRule('deny', ['file-write-unlink', 'file-write-create'], moveFilters, logTag));
748
765
  // capybara patch: ordered raw regex rules, last, so each decides over everything before it
749
- // (raw #"…" strings: SBPL string escapes would change the regex; a quote cannot occur)
750
766
  for (const rule of config.regexRules ?? []) {
751
- if (rule.regex.includes('"'))
752
- throw new Error('A raw regex write rule cannot contain a double quote');
753
- rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex #"${rule.regex}")`]), logTag));
767
+ rules.push(...renderRule(rule.action, rule.operations, new Set([`(regex ${escapePath(rule.regex)})`]), logTag));
754
768
  }
755
769
  return rules;
756
770
  }
@@ -832,6 +832,12 @@ export const FilesystemConfigSchema = z.object({
832
832
  .boolean()
833
833
  .optional()
834
834
  .describe('Allow writes to .git/config files (default: false). Enables git remote URL updates while keeping .git/hooks protected.'),
835
+ // capybara patch: exact read allows (macOS): absolute paths emitted as (literal …), never
836
+ // (subpath …), for directories whose entries a command may list or links it may follow
837
+ allowReadExact: z
838
+ .array(z.string())
839
+ .optional()
840
+ .describe('macOS only: absolute paths re-allowed for reading as exactly that path, not its subtree'),
835
841
  // capybara patch: ordered raw SBPL regex write rules (macOS), emitted after every other
836
842
  // write rule so they decide last (Seatbelt is last-match-wins for the same operations)
837
843
  writeRegexRules: z
@@ -1493,6 +1493,8 @@ function getFsReadConfig() {
1493
1493
  allowWithinDeny: allowPaths,
1494
1494
  unlistableDenyDirs: [...unlistableDenyDirs],
1495
1495
  ...literalReadLists(config.filesystem.denyRead, config.filesystem.allowRead),
1496
+ // capybara patch: exact read allows (macOS)
1497
+ exactAllowWithinDeny: config.filesystem.allowReadExact ?? [],
1496
1498
  };
1497
1499
  }
1498
1500
  function getFsWriteConfig() {
@@ -1921,6 +1923,8 @@ async function wrapWithSandboxOnce(walkEnded, restarts, command, binShell, custo
1921
1923
  ...(ownAllowWithinDeny.length > 0 && { ownAllowWithinDeny }),
1922
1924
  unlistableDenyDirs: [...unlistableDenyDirs],
1923
1925
  ...literalReadLists(customConfig?.filesystem?.denyRead ?? config?.filesystem.denyRead, customConfig?.filesystem?.allowRead ?? config?.filesystem.allowRead),
1926
+ // capybara patch: exact read allows (macOS)
1927
+ exactAllowWithinDeny: customConfig?.filesystem?.allowReadExact ?? config?.filesystem.allowReadExact ?? [],
1924
1928
  };
1925
1929
  }
1926
1930
  // Nothing below walks, and what it waits for is not this thread.
@@ -52,10 +52,15 @@ When a person cannot do something themselves (install a plugin that is not on in
52
52
  approve extension permissions), they file a **request**. Org admins or the super admin decide it
53
53
  on the web. Agents can file requests but never decide them.
54
54
 
55
- ## Sandbox
56
-
57
- Agents run commands and keep files in a **sandbox**, one per conversation. Skills are mounted
58
- read-only under `/skills/<name>/`. Sandbox limits and network egress are set per org by admins.
55
+ ## Devices
56
+
57
+ Agents run commands and keep files on a **device**: one instance plus a file system that is kept
58
+ until the device is deleted. A device is a cloud sandbox (from the deployment's sandbox provider)
59
+ or a machine connected with `capybara-device`, and the conversations that use it share its files.
60
+ A device runs in one of two modes: auto (the environment's own capability) or sandbox (an OS
61
+ sandbox with an allowlist network). Skill files are read-only in the device's skills directory;
62
+ each conversation is told the device's directories, mode and network. Sandbox limits and the
63
+ cloud network are set per org by admins.
59
64
 
60
65
  ## What agents may not do
61
66
 
@@ -10,6 +10,6 @@
10
10
 
11
11
  Contract: Channel (`channel.ts`)
12
12
 
13
- Normalize inbound events (messageId, threadId, tenantId, the bot mention stripped) and acknowledge only after the kernel's `onEvent` resolves. Long connections are held only by the gateway role. Replies use the card spec (`validateChannelCard`).
13
+ Normalize inbound events (messageId, threadId, tenantId, the bot mention stripped) and acknowledge only after the kernel's `onEvent` resolves. Long connections are held only by the gateway role. Replies use the card spec (`validateChannelCard`). Files: implement the optional `sendFile` and declare `features.files` (the platform's bot limits); the kernel sends each conversation artifact as one message and falls back to a link line without it.
14
14
 
15
15
  See `extensions` for the rules every extension follows.
@@ -12,4 +12,6 @@ Contract: FilePreviewProvider (`file-preview.ts`)
12
12
 
13
13
  Declare which file types you can preview and render them through schema views or an approved embed. Enabled per org.
14
14
 
15
+ `render` args are a union on `source`: `"conversation"` (org, account, conversation) or `"share"` (org and share id; `file.id` is the share id; no account or conversation). A previewer that needs the conversation declines `source: "share"` by throwing; the kernel reports the failure and the share page falls to the next previewer. A share token is valid only for the `file.preview` slot, never for `/api`.
16
+
15
17
  See `extensions` for the rules every extension follows.
@@ -10,6 +10,6 @@
10
10
 
11
11
  Contract: SandboxProvider (`sandbox.ts`)
12
12
 
13
- The kernel accepts only `sandbox@2`. A device is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours. Never publish a docker socket proxy on a host address.
13
+ The kernel accepts only `sandbox@2`. A device is one instance plus a file system that outlives it. Implement the file system (`createFileSystem`, `destroyFileSystem`, `destroyFileSystemByName`), the instance on it (`create`, which throws `FileSystemGoneError` when the file system is gone instead of making an empty one; `resume`, `suspend`; `destroy` and `destroyByName`, which drop the instance and keep the files), and the instance's `exec`, `readFile`, `writeFile`, `stat`, `killAll` and `killTagged` (`concurrentExec` is required: several conversations share one instance). Aborting a command must kill it. Locking, suspension timing and destruction are the kernel's job, not yours.
14
14
 
15
15
  See `extensions` for the rules every extension follows.
@@ -59,7 +59,7 @@ Rules that the schema cannot show:
59
59
  by `parseThemeFile` (schema `https://capybarahq.com/schemas/theme.v1.schema.json`).
60
60
  - `setupGuides` (at most 8): `{ id, place, template? }`. Each guide is a Markdown document at
61
61
  `guides/<id>.md` (English, required) and `guides/<id>.zh.md` (Chinese, optional), shown where a
62
- person sets up what the plugin brings. `place` is `channel-connection` (新建渠道 and the channel
62
+ person sets up what the plugin brings. `place` is `channel-connection` (New channel and the channel
63
63
  detail; the extension must provide `channel@1`; one per plugin) or `connector-template`
64
64
  (`template` names one of the plugin's `connectors/<id>.json`; one per template). See "Setup
65
65
  guides" below.
@@ -91,6 +91,17 @@ export declare function questionRenderableInline(form: InputForm, opts?: {
91
91
  export declare function validateChannelCard(card: unknown): string[];
92
92
  /** A UI locale. */
93
93
  export type Locale = "zh" | "en";
94
+ /**
95
+ * Puts model-controllable values (approval title, call summary, question title, answer summary)
96
+ * into code, so that in the fallback text they do not turn into links, emphasis or HTML:
97
+ * single-line values use inline code, multi-line values a fenced code block (starting with a
98
+ * newline); the delimiters are always longer than the longest backtick run in the value (CommonMark
99
+ * 6.1 / 4.5).
100
+ * Code is chosen over backslash-escaping punctuation because code is the only form CommonMark / GFM
101
+ * guarantee to display content verbatim (a backslash does not stop GFM bare-URL
102
+ * autolinks, and channel converters treat backslashes inconsistently).
103
+ */
104
+ export declare function asCode(s: string): string;
94
105
  /** The hint line of a pending question card with `textReply`, as {@link renderCardAsText} writes it. */
95
106
  export declare function questionTextReplyHint(mode: "plain" | "mention", locale: Locale): string;
96
107
  /**
@@ -125,7 +125,7 @@ export function validateChannelCard(card) {
125
125
  * guarantee to display content verbatim (a backslash does not stop GFM bare-URL
126
126
  * autolinks, and channel converters treat backslashes inconsistently).
127
127
  */
128
- function asCode(s) {
128
+ export function asCode(s) {
129
129
  const v = s.replace(/\r\n?/g, "\n");
130
130
  const longest = Math.max(0, ...[...v.matchAll(/`+/g)].map((m) => m[0].length));
131
131
  if (v.includes("\n")) {