@capybara-hq/device 0.1.0-rc.17 → 0.1.0-rc.19

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 (107) hide show
  1. package/README.md +143 -32
  2. package/dist/activity.d.ts +31 -0
  3. package/dist/activity.js +62 -0
  4. package/dist/api.d.ts +3 -3
  5. package/dist/args.d.ts +25 -4
  6. package/dist/args.js +82 -21
  7. package/dist/cli.js +14 -3
  8. package/dist/client.js +1 -1
  9. package/dist/commands/ceiling.d.ts +3 -2
  10. package/dist/commands/ceiling.js +60 -20
  11. package/dist/commands/keep-awake.d.ts +19 -0
  12. package/dist/commands/keep-awake.js +77 -0
  13. package/dist/commands/login.d.ts +15 -11
  14. package/dist/commands/login.js +75 -49
  15. package/dist/commands/policy.js +16 -10
  16. package/dist/commands/service.d.ts +3 -1
  17. package/dist/commands/service.js +35 -2
  18. package/dist/commands/start.d.ts +18 -3
  19. package/dist/commands/start.js +144 -9
  20. package/dist/commands/status.d.ts +8 -1
  21. package/dist/commands/status.js +59 -7
  22. package/dist/control/client.d.ts +12 -0
  23. package/dist/control/client.js +63 -0
  24. package/dist/control/protocol.d.ts +58 -0
  25. package/dist/control/protocol.js +16 -0
  26. package/dist/control/server.d.ts +28 -0
  27. package/dist/control/server.js +254 -0
  28. package/dist/exec/docker-operations.d.ts +14 -2
  29. package/dist/exec/docker-operations.js +32 -5
  30. package/dist/exec/linux-agent.d.ts +13 -3
  31. package/dist/exec/linux-agent.js +450 -43
  32. package/dist/exec/linux-operation-backend.d.ts +27 -6
  33. package/dist/exec/linux-operation-backend.js +30 -9
  34. package/dist/exec/linux-operation-worker.d.ts +51 -3
  35. package/dist/exec/linux-operation-worker.js +55 -3
  36. package/dist/exec/linux-runtime.d.ts +3 -2
  37. package/dist/exec/linux-runtime.js +4 -2
  38. package/dist/exec/mac-operation-backend.d.ts +12 -2
  39. package/dist/exec/mac-operation-backend.js +19 -10
  40. package/dist/exec/mac-write-policy.d.ts +2 -0
  41. package/dist/exec/mac-write-policy.js +1 -1
  42. package/dist/exec/operation-supervisor.d.ts +6 -0
  43. package/dist/exec/operation-supervisor.js +10 -0
  44. package/dist/exec/operation-types.d.ts +35 -5
  45. package/dist/exec/operation-types.js +73 -23
  46. package/dist/exec/operation-worker.d.ts +80 -1
  47. package/dist/exec/operation-worker.js +197 -14
  48. package/dist/exec/protected-targets.d.ts +16 -0
  49. package/dist/exec/protected-targets.js +53 -0
  50. package/dist/exec/shared.d.ts +7 -3
  51. package/dist/exec/shared.js +7 -5
  52. package/dist/index.d.ts +2 -0
  53. package/dist/index.js +1 -0
  54. package/dist/keep-awake.d.ts +39 -0
  55. package/dist/keep-awake.js +104 -0
  56. package/dist/node_modules/@anthropic-ai/sandbox-runtime/CAPYBARA-MODIFICATIONS.patch +343 -7
  57. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/resolved-address-guard.js +220 -6
  58. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-config.js +17 -0
  59. package/dist/node_modules/@anthropic-ai/sandbox-runtime/dist/sandbox/sandbox-manager.js +11 -0
  60. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.d.ts +77 -46
  61. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +206 -83
  62. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +5 -2
  63. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +5 -2
  64. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.d.ts +98 -0
  65. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/network-classes.js +291 -0
  66. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
  67. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-linux-runtime-source.js +460 -28
  68. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-native-runtime-source.js +143 -3
  69. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.d.ts +36 -4
  70. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-operation.js +21 -4
  71. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-runtime-source.js +2 -2
  72. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.d.ts +87 -8
  73. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox-write-denies.js +249 -10
  74. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/sandbox.d.ts +11 -22
  75. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
  76. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
  77. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
  78. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
  79. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
  80. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
  81. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
  82. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  83. package/dist/owner-report.d.ts +1 -1
  84. package/dist/owner-report.js +5 -4
  85. package/dist/policy-store.d.ts +2 -1
  86. package/dist/policy-store.js +2 -1
  87. package/dist/policy.d.ts +23 -14
  88. package/dist/policy.js +28 -21
  89. package/dist/runtime-manifest.json +1 -1
  90. package/dist/server-ops.d.ts +33 -5
  91. package/dist/server-ops.js +138 -85
  92. package/dist/service/launchd.d.ts +2 -0
  93. package/dist/service/launchd.js +10 -4
  94. package/dist/service/manager.d.ts +2 -0
  95. package/dist/service/manager.js +16 -2
  96. package/dist/service/systemd.d.ts +2 -0
  97. package/dist/service/systemd.js +8 -2
  98. package/dist/staged-connect.d.ts +10 -1
  99. package/dist/staged-connect.js +25 -3
  100. package/dist/staged-device.d.ts +1 -1
  101. package/dist/staged-device.js +13 -5
  102. package/dist/staged-session.d.ts +1 -1
  103. package/dist/state.d.ts +50 -21
  104. package/dist/state.js +111 -46
  105. package/dist/wake.d.ts +23 -0
  106. package/dist/wake.js +29 -0
  107. package/package.json +2 -2
package/README.md CHANGED
@@ -17,6 +17,12 @@ capybara-device status [--json]
17
17
  capybara-device logout
18
18
  ```
19
19
 
20
+ `login --json` is for programs that drive the CLI (the desktop app): it opens no browser and writes one
21
+ JSON object per line to stdout, the human lines going to stderr: `{"event":"verification","url":…,
22
+ "userCode":…,"expiresIn":…}`, then `{"event":"done","deviceId":…,"orgId":…,"dir":…}` or
23
+ `{"event":"error","code":…,"message":…}` (for example `device_sign_in.expired`, `device_sign_in.denied`).
24
+ It never prints the credential.
25
+
20
26
  `login` shows a code like `BCDF-GHJK`; with `--no-browser` it prints the address (`<url>/devices/link`) and
21
27
  the code to enter on any signed-in browser, where you pick the org and the device (a new one or
22
28
  an existing connected one of yours) after reading what the program can do. Logging in again from
@@ -56,7 +62,7 @@ and the platform rebuilds the device on its next use.
56
62
  Commands: `login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]`, `logout`,
57
63
  `status [--json]`, `start`, `stop`,
58
64
  `drain [--wait] [--timeout <seconds>]`,
59
- `ceiling show | ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]`,
65
+ `ceiling show | ceiling set [--outside-sandbox on|off] [--network open|allowlist] [--project-reach workspace|os-user] [--yes]`,
60
66
  `policy [show | set <key> <value> | add|remove <key> <value>]` and
61
67
  `service install|uninstall|start|stop|restart|status`.
62
68
  `ceiling set` is the only way to change the owner ceiling (`policy set mode` points there); a
@@ -76,31 +82,41 @@ and `tmp/`.
76
82
 
77
83
  ## Permissions
78
84
 
79
- Every operation the deployment sends carries a scope: the conversation's permission profile
80
- (`request-approval` and `approve-for-me` are restricted, `full-access` is Full access), the roots
81
- it may read and write, and its network. The device checks each one against the **owner ceiling**
82
- in `policy.json`, which only you change, on this machine:
83
-
84
- - **Full access** `allow|deny`: whether a conversation set to Full access may run here. Full access
85
- runs as you (in Docker mode, as the container's user): your files, credentials and network; the
86
- deployment reviews every command, but that review is the boundary, not a sandbox.
87
- - **Project reach** `workspace|os-user`: whether restricted work and project browsing may read
85
+ Every operation the deployment sends carries a scope: the roots it may read and write, its network
86
+ and the conversation's permission profile (for the record only: every profile runs in the sandbox,
87
+ Full access included; a profile only decides who approves going beyond it). The device checks each
88
+ scope against the **owner ceiling** in `policy.json`, which only you widen, on this machine:
89
+
90
+ - **Outside the sandbox** `on|off`: whether one approved call may run outside the sandbox
91
+ (`sandbox: "escalated"`). Such a call runs as you (in Docker mode, as the container's user): your
92
+ files, credentials and network, with the program's environment minus every `CAPYBARA_*` variable.
93
+ The person, the review model or a Full access auto-grant approves each one, and each is recorded.
94
+ - **Network** `open|allowlist`: the sandbox network. `open` is the public internet (private, local
95
+ and metadata addresses closed, below); `allowlist` is only the hosts in `allowedDomains` that the
96
+ organization also allows, and the list is then this machine's ceiling for per-call host grants.
97
+ - **Project reach** `workspace|os-user`: whether sandboxed work and project browsing may read
88
98
  projects outside the device's `workspace/`.
89
99
 
90
- A new login starts restricted (`deny`, `workspace`). `login` prints the ceiling and how to widen
91
- it; a widening prints the risk text and needs `--yes` or a `y` at the prompt. The organization and
92
- the platform can switch Full access off on their side; the narrowest setting wins.
100
+ A new login starts with outside-the-sandbox off, the open network and `workspace` reach. `login`
101
+ prints the ceiling and how to widen it; a widening prints the risk text and needs `--yes` or a `y`
102
+ at the prompt. The organization and the platform have their own settings; the narrowest wins. An
103
+ older `policy.json` (protocol 3, `fullAccess`) is converted once on start, never wider: allowed
104
+ becomes outside-the-sandbox on with the open network, denied keeps the allowlist (and `start` prints
105
+ `capybara-device ceiling set --network open`). A logged-in machine without `policy.json` (set up
106
+ before rc.58) ran with no reachable host and keeps that: `start` writes outside-the-sandbox off and
107
+ the allowlist with no host, and prints the same command; a missing file never reads as open.
93
108
 
94
109
  ```bash
95
- capybara-device ceiling show # the owner ceiling, network baseline, revision
96
- capybara-device ceiling set --full-access deny --project-reach workspace # narrow
97
- capybara-device ceiling set --full-access allow --project-reach os-user --yes # widen
110
+ capybara-device ceiling show # the owner ceiling, network, revision
111
+ capybara-device ceiling show --json # {"outsideSandbox":…,"network":…,"allowedDomains":[…],"projectReach":…,"revision":…} (revision: string | null)
112
+ capybara-device ceiling set --outside-sandbox off --network allowlist --project-reach workspace # narrow
113
+ capybara-device ceiling set --outside-sandbox on --network open --yes # widen
98
114
  capybara-device policy add allowedDomains files.slack.com
99
115
  capybara-device policy remove allowedDomains files.slack.com
100
116
  capybara-device policy show
101
117
  ```
102
118
 
103
- **Restricted work** runs each operation in its own sandbox: macOS uses
119
+ **Sandboxed work** (every operation but an escalated call) runs each operation in its own sandbox: macOS uses
104
120
  `@anthropic-ai/sandbox-runtime` (Seatbelt); Linux and Docker mode use the SDK's restricted Linux
105
121
  runtime (Landlock plus a seccomp broker). Writes stay in the scope's roots; reads stay in them too,
106
122
  plus the system and developer tool directories (on macOS `/System`, `/usr`, `/bin`, `/sbin`,
@@ -108,9 +124,25 @@ plus the system and developer tool directories (on macOS `/System`, `/usr`, `/bi
108
124
  installed JDKs) and the data of the version managers your home uses, read only; other files of the
109
125
  machine, such as the rest of your home, are not readable. Secret paths (`~/.ssh`, cloud CLI
110
126
  credentials, `~/.netrc`, `~/.gnupg`, browser profiles, this program's state directory) stay
111
- unreadable even inside those, and the network reaches only hosts in the local `allowedDomains` that
112
- the organization's allowlist also admits (plus a run's or a task's grants, within that allowlist),
113
- through a proxy that refuses loopback, private addresses and internal names. Restricted work also
127
+ unreadable even inside those. Commands get a minimal environment (`PATH`, `LANG`,
128
+ `HOME` set to the working root, a private temp directory, the tool homes, the proxy variables),
129
+ never this program's. The network is the owner ceiling's: `open` reaches the public
130
+ internet, `allowlist` only hosts in the local `allowedDomains` that the organization's allowlist
131
+ also admits (plus a run's or a task's grants, within that allowlist). Either way traffic goes
132
+ through the operation's own proxy, which decides each connection on the resolved address and dials
133
+ the address it checked: loopback (another program's localhost port), private and LAN, CGNAT, IPv6
134
+ ULA, link-local, cloud metadata and NAT64 addresses and this machine's own addresses stay closed,
135
+ for names and IP literals alike. A client that ignores the proxy variables (plain `ssh`) does not
136
+ connect. No sandboxed client connects to a loopback listener, its own included; on Linux a
137
+ restricted command may listen on loopback for clients outside the sandbox, and on macOS it cannot
138
+ listen at all (a dev server needs an approved call outside the sandbox). Behind a fake-IP resolver (a router or proxy in OpenClash-style fake-IP mode answers
139
+ every name with an address in `198.18.0.0/15`), the proxy re-resolves such a name through
140
+ DNS-over-HTTPS (RFC 8484) to Cloudflare (`1.1.1.1`, `1.0.0.1`) and then Google (`8.8.8.8`,
141
+ `8.8.4.4`), reached by IP over verified TLS within 5 seconds, and judges the real answer; when that
142
+ lookup fails the connection is refused with a reason naming the fake-IP resolver, never dialed to
143
+ the fake address. The open network decides on the address, not on where it routes: a router's
144
+ public WAN address reached by hairpin NAT, a VPN routing public addresses to an intranet, or an
145
+ operator NAT64 prefix are not closed; such a machine should keep the allowlist. Restricted work also
114
146
  follows one write policy (below). On macOS each restricted command also gets its own empty temporary
115
147
  directory (`TMPDIR`, `TMP`, `TEMP`), removed when the command ends; `mktemp` without a template
116
148
  writes to the user's shared temporary directory instead, which stays closed, so give it one (`mktemp
@@ -129,10 +161,10 @@ exactly when the operation ends, is cancelled or its task is stopped; it never k
129
161
 
130
162
  ### Changes from the deployment
131
163
 
132
- The deployment changes the local policy only by narrowing it: it may add or remove
133
- `allowedDomains` (an approval adds an exact host; the device page may add a `*.` wildcard) and
134
- narrow the owner ceiling. It can never widen it. Every host is validated like a local one, and the
135
- change is written under `policy.json.lock`.
164
+ The deployment changes the local policy only by narrowing it: it may remove `allowedDomains`,
165
+ switch the network to `allowlist` and turn outside-the-sandbox off. It can never widen it: a
166
+ `policy` request that adds hosts or carries a `mode` is refused and writes nothing (an approval's
167
+ host grant lasts for its run instead). Every change is written under `policy.json.lock`.
136
168
 
137
169
  ### The command log
138
170
 
@@ -144,13 +176,13 @@ refused or failed ones included. It never holds a command's text, its environmen
144
176
  ```text
145
177
  {"op":"exec","tag":"t1","actor":{"accountId":"acc_123","conversationId":"conv_1"},"exitCode":0,"isolation":"restricted",...}
146
178
  {"op":"policy","detail":"policy add files.slack.com by Ada Lovelace (acc_123) via web, approval apr_456",...}
147
- {"op":"policy","detail":"ceiling set fullAccess allow, projectReach os-user by ada via cli",...}
179
+ {"op":"policy","detail":"ceiling set outsideSandbox on, network open by ada via cli",...}
148
180
  ```
149
181
 
150
182
  Limits to know: the platform's `Grep` tool assumes GNU grep, so on macOS (BSD grep) in OS mode some
151
183
  Grep options behave differently or fail. In OS mode the `cpu` and `memoryMb` ceilings are not
152
- enforced yet, and `allowCredentials` is ignored (Full access already has your credentials,
153
- restricted work gets none).
184
+ enforced yet, and `allowCredentials` is ignored (an escalated call already has your credentials,
185
+ sandboxed work gets none).
154
186
 
155
187
  ### Upgrading from a protocol 2 program
156
188
 
@@ -159,6 +191,73 @@ they left running survive the upgrade. Restart the machine, or kill such leftove
159
191
  upgrade yourself; this version never searches for them. In Docker mode the old container is
160
192
  recreated at the first operation, which ends whatever it still ran.
161
193
 
194
+ ## Control socket
195
+
196
+ While `start` serves, it answers on `<stateDir>/control.sock` (next to `credential.json`): a unix
197
+ socket of mode 0600, made only when the state directory belongs to you and has no group or other
198
+ permissions (mode 0700). A socket left by a program that crashed (nothing listens on it) is
199
+ replaced; one another running program answers on is never touched. When the path is longer than
200
+ 103 bytes (a long `XDG_CONFIG_HOME`) or the directory is open to other users, the program keeps
201
+ serving without the socket and says why once.
202
+
203
+ The protocol is JSON lines. A request is `{"id":<positive integer>,"op":"<op>"}`; each answer
204
+ carries the request's id: `{"id":1,"ok":true,"result":...}` or
205
+ `{"id":1,"ok":false,"error":{"code":"...","message":"..."}}` (`bad_request`, with id 0 for a line
206
+ without a usable id, `unknown_op`). A malformed line keeps the connection open; a line over 64 KiB,
207
+ or more than 1 MiB of answers a peer leaves unread, closes it.
208
+
209
+ | Op | Result |
210
+ |---|---|
211
+ | `status` | The live status: `pid`, `version`, `url`, `orgId`, `deviceId`, `mode` (`os` or `docker`), `connection` (`starting`, `online`, `offline` or `draining`), `offlineReason` (while offline), `since` (when `connection` last changed), `keepAwake` (`mode`, `held`, and `unavailable` with the reason when the holder cannot run), `lastWakeAt` (once the computer woke from sleep) |
212
+ | `running` | The operations executing now (an exec while it runs, a background task until it completes or is killed): `tag`, `conversationId`, `accountId`, `isolation` (`restricted` or `full`), `startedAt`; never a command's text, environment or output |
213
+ | `subscribe` | The live status now; afterwards the connection receives `{"event":"status","status":{...}}` after each change |
214
+ | `drain` | `null`; drains as `capybara-device drain` does |
215
+ | `stop` | `null`; stops as `capybara-device stop` does |
216
+
217
+ `status --json` asks the socket (for at most 500 ms) and adds:
218
+
219
+ - `control`: `ok` (the running program answered), `absent` (no program runs) or `unavailable`
220
+ (a program runs but has no socket, with the reason in `controlReason`);
221
+ - `live`: the live status above, or `null`.
222
+
223
+ The credential is never part of any answer.
224
+
225
+ ## Keep-awake
226
+
227
+ While the device serves, it can keep this computer from going to idle sleep, so a command a
228
+ conversation started is not cut off and the deployment can reach the device. `policy.json` holds
229
+ the mode in `keepAwake`:
230
+
231
+ - `off`: never;
232
+ - `while-busy` (the default): only while operations run (an exec, or a background task until it
233
+ ends);
234
+ - `connected`: the whole time the device is connected to the deployment.
235
+
236
+ ```bash
237
+ capybara-device keep-awake # show the mode (--json for one JSON object)
238
+ capybara-device keep-awake off # lower it: applies at once
239
+ capybara-device keep-awake connected --yes # raise it: asks on a terminal, needs --yes without one
240
+ ```
241
+
242
+ A running program applies a change within a few seconds, without a restart; the change is logged
243
+ in `commands.log`. The hold is a helper process: `/usr/bin/caffeinate -i -w <pid>` on macOS and
244
+ `systemd-inhibit --what=idle:sleep --mode=block --who=capybara-device --why="Capybara device is
245
+ serving" sleep infinity` on Linux. If it cannot start or ends early, the status says so
246
+ (`keepAwake.unavailable`); it is never reported as held then. The program also notices a wake from
247
+ sleep (a wall-clock jump of over 30 s): it writes `{ "op": "wake" }` to `commands.log` and sets
248
+ `lastWakeAt` in the live status.
249
+
250
+ A holder that cannot start or ends early is not started again while the same mode still wants it;
251
+ it is tried again after nothing is wanted for one check, or when the mode changes. On Linux a runner
252
+ killed with SIGKILL leaves `sleep infinity` holding the inhibitor until that process is killed (on
253
+ macOS `caffeinate -w` ends with the runner).
254
+
255
+ What this cannot prevent: closing the lid of a Mac on battery without an external display
256
+ (clamshell) still sleeps; so do choosing Sleep, a critically low battery and thermal emergencies;
257
+ on Linux, the lid switch as logind handles it (taking `handle-lid-switch` needs privileges the user
258
+ service lacks). While the computer sleeps the device's WebSocket stops, and the kernel sees a
259
+ sleeping machine as offline, as for a lost network.
260
+
162
261
  ## Docker mode
163
262
 
164
263
  `login --mode docker` runs every operation in one container per device
@@ -171,7 +270,7 @@ container has a read-only root file system, a pids limit of 1024, `--cap-drop AL
171
270
  `no-new-privileges`, and the policy's `cpu` and `memoryMb` as `--cpus`, `--memory` and an equal
172
271
  `--memory-swap`.
173
272
 
174
- The container is always on Docker's default bridge: Full access has the container's whole network.
273
+ The container is always on Docker's default bridge: an escalated call has the container's whole network.
175
274
  Restricted work inside it is confined by the Linux launcher (Landlock, the seccomp broker and the
176
275
  proxy with the allowlist above), on the container's paths. The hello reports no home directory, and
177
276
  browsing covers the container's `/workspace` only. The container is reused while its mounts, flags
@@ -201,6 +300,11 @@ has the agent loaded, or systemd the unit active, and its pid is the pid file's)
201
300
  how to restart the installed service; started by the service manager (launchd sets
202
301
  `XPC_SERVICE_NAME`, systemd `INVOCATION_ID`) it prints no such hint.
203
302
 
303
+ `capybara-device service status --json` prints one object instead: `installed`, `loaded`, `running`,
304
+ `binExists` (false when the service file's `bin` path is gone, e.g. the app that installed it moved)
305
+ and, when known, `pid`, `runningVersion`, `installedVersion`, `nodePath`, `binPath`. The exit code is
306
+ the same as the human report's.
307
+
204
308
  `capybara-device service status` says one of four things: not installed; installed but not loaded
205
309
  (`service start`); loaded but the program is not running, i.e. it exited (the reason is at the end of
206
310
  `service.log`; fix it, then `service restart`); or running, with the service manager's pid and the
@@ -218,21 +322,28 @@ times. On Linux, installing again restarts the unit so the new file applies.
218
322
 
219
323
  ## Operation backend
220
324
 
221
- The program speaks device protocol 3 only. It binds each instance generation the deployment creates
325
+ The program speaks device protocol 4 only; the kernel and this program upgrade together (a
326
+ protocol 4 program facing an older deployment says the deployment must be upgraded). It binds each instance generation the deployment creates
222
327
  to a verified, sealed runtime and reports restricted support only once a self-check on that runtime
223
328
  passed (macOS: a write in its root goes through, while a write outside it, reads of a denied secret
224
329
  and of an ordinary file it was never granted, and a local connection are refused) or the runtime's
225
- probe passed (Linux, Docker); there is no Full fallback for restricted work.
330
+ probe passed (Linux, Docker); nothing falls back to running outside the sandbox.
226
331
 
227
332
  Each restricted operation has its own immutable sandbox-runtime process and proxy lifetime.
228
333
  Native methods use the SDK's hash-checked Python helper and pinned directory descriptors, with a
229
- private descriptor-identity handshake before dispatch. Full uses the existing OS user directly.
334
+ private descriptor-identity handshake before dispatch. An escalated call uses the existing OS
335
+ user directly.
230
336
  Execution grants arrive separately over authenticated transport; scope hosts cannot manufacture
231
337
  an owner allowance. Strict fresh owner-policy reads fail closed on missing or malformed policy.
232
338
 
233
339
  Restricted operations follow one write policy on every platform (`sandbox-write-denies.ts` in
234
340
  the SDK): no shell, git-global, direnv, npm, editor, agent or hook-manager configuration; inside
235
- any `.git` only git's ordinary internals; no bare-repository lookalike; no `.git` moved away.
341
+ any `.git` only git's ordinary internals; no bare-repository lookalike; no `.git` moved away; no
342
+ OS persistence location (launch agents, systemd user units, autostart, the crontab spool). At
343
+ operation start each protected home location is resolved link by link (a dotfile manager's
344
+ `~/.zshrc` chain), and every link on the way and the final target are denied, with no move of
345
+ their ancestors. Names starting with `.capybara-staging-` (any case) are reserved for the Linux
346
+ broker's staged directory moves and denied to every sandboxed write.
236
347
  As defence in depth, owners are advised to run
237
348
 
238
349
  git config --global safe.bareRepository explicit
@@ -0,0 +1,31 @@
1
+ /**
2
+ * An operation executing on this machine now, as the control socket's `running` op lists it: who
3
+ * asked and how it runs. Never the command, its arguments, its environment or its output.
4
+ */
5
+ export interface RunningOperation {
6
+ tag: string;
7
+ conversationId: string | null;
8
+ accountId: string | null;
9
+ isolation: "restricted" | "full";
10
+ startedAt: string;
11
+ }
12
+ /**
13
+ * The operations executing in this process: an exec while it runs, a background task from its
14
+ * start until its worker is gone (completed or killed, reported by the backend). In-process by
15
+ * design: only this runner's control socket reads it, and it dies with the process whose
16
+ * operations it lists.
17
+ */
18
+ export declare class RunningOperations {
19
+ private readonly ops;
20
+ private readonly listeners;
21
+ /** Calls `fn` after every change of the list; returns how to stop. */
22
+ subscribe(fn: () => void): () => void;
23
+ private changed;
24
+ /** `operationId` lets {@link endOperation} end exactly this one. */
25
+ begin(op: RunningOperation, operationId?: string): void;
26
+ /** Ends the oldest running operation with this tag (tags may repeat); unknown tags are ignored. */
27
+ end(tag: string): void;
28
+ /** Ends the operation begun with this id; ids already ended are ignored. */
29
+ endOperation(operationId: string): void;
30
+ list(): RunningOperation[];
31
+ }
@@ -0,0 +1,62 @@
1
+ /**
2
+ * The operations executing in this process: an exec while it runs, a background task from its
3
+ * start until its worker is gone (completed or killed, reported by the backend). In-process by
4
+ * design: only this runner's control socket reads it, and it dies with the process whose
5
+ * operations it lists.
6
+ */
7
+ export class RunningOperations {
8
+ ops = [];
9
+ listeners = new Set();
10
+ /** Calls `fn` after every change of the list; returns how to stop. */
11
+ subscribe(fn) {
12
+ this.listeners.add(fn);
13
+ return () => this.listeners.delete(fn);
14
+ }
15
+ changed() {
16
+ for (const fn of this.listeners) {
17
+ try {
18
+ fn();
19
+ }
20
+ catch {
21
+ // an observer never affects the operations
22
+ }
23
+ }
24
+ }
25
+ /** `operationId` lets {@link endOperation} end exactly this one. */
26
+ begin(op, operationId) {
27
+ // a retried start of the same operation replaces its entry instead of adding one
28
+ if (operationId !== undefined)
29
+ this.endOperation(operationId);
30
+ // copy only the known fields: whatever else the caller holds never reaches the socket
31
+ this.ops.push({
32
+ ...(operationId !== undefined && { operationId }),
33
+ op: {
34
+ tag: op.tag,
35
+ conversationId: op.conversationId,
36
+ accountId: op.accountId,
37
+ isolation: op.isolation,
38
+ startedAt: op.startedAt,
39
+ },
40
+ });
41
+ this.changed();
42
+ }
43
+ /** Ends the oldest running operation with this tag (tags may repeat); unknown tags are ignored. */
44
+ end(tag) {
45
+ const i = this.ops.findIndex((o) => o.op.tag === tag);
46
+ if (i >= 0) {
47
+ this.ops.splice(i, 1);
48
+ this.changed();
49
+ }
50
+ }
51
+ /** Ends the operation begun with this id; ids already ended are ignored. */
52
+ endOperation(operationId) {
53
+ const i = this.ops.findIndex((o) => o.operationId === operationId);
54
+ if (i >= 0) {
55
+ this.ops.splice(i, 1);
56
+ this.changed();
57
+ }
58
+ }
59
+ list() {
60
+ return this.ops.map((o) => ({ ...o.op }));
61
+ }
62
+ }
package/dist/api.d.ts CHANGED
@@ -15,10 +15,10 @@ export interface TokenResponse {
15
15
  /** The program uses 16 MiB when it is absent. */
16
16
  maxFrameBytes?: number;
17
17
  /**
18
- * Whether the platform and the organization allow Full access (`allowed`) or not (`off`):
19
- * `login` prints the matching line. Absent counts as allowed.
18
+ * Whether the platform and the organization allow running outside the sandbox (`allowed`) or not
19
+ * (`off`): `login` prints the matching line. Absent counts as allowed.
20
20
  */
21
- fullAccess?: "allowed" | "off";
21
+ outsideSandbox?: "allowed" | "off";
22
22
  }
23
23
  /** An error response of the kernel: `{ error: { code, message } }`. */
24
24
  export declare class ApiError extends Error {
package/dist/args.d.ts CHANGED
@@ -1,4 +1,5 @@
1
- import type { RestrictedProjectReach } from "./state.js";
1
+ import type { DeviceNetworkMode } from "@capybara-hq/plugin-sdk";
2
+ import { type KeepAwakeMode, type RestrictedProjectReach } from "./state.js";
2
3
  export type DeviceMode = "os" | "docker";
3
4
  /** A parsed command line. */
4
5
  export type Command = {
@@ -7,6 +8,8 @@ export type Command = {
7
8
  browser: boolean;
8
9
  dir?: string;
9
10
  mode: DeviceMode;
11
+ /** `--json`: one JSON event per line on stdout (implies `--no-browser`). */
12
+ json?: true;
10
13
  } | {
11
14
  command: "logout";
12
15
  } | {
@@ -33,20 +36,38 @@ export type Command = {
33
36
  } | {
34
37
  command: "ceiling";
35
38
  action: "show";
39
+ json?: true;
36
40
  } | {
37
41
  command: "ceiling";
38
42
  action: "set";
39
- fullAccess: boolean;
40
- projectReach: RestrictedProjectReach;
43
+ /** `--outside-sandbox on|off`; absent keeps the current value. */
44
+ outsideSandbox?: boolean;
45
+ /** `--network open|allowlist`; absent keeps the current value. */
46
+ network?: DeviceNetworkMode;
47
+ /** `--project-reach workspace|os-user`; absent keeps the current value. */
48
+ projectReach?: RestrictedProjectReach;
41
49
  /** `--yes`: confirms a widening without asking. */
42
50
  yes?: true;
51
+ } | {
52
+ command: "keep-awake";
53
+ action: "show";
54
+ json?: true;
55
+ } | {
56
+ command: "keep-awake";
57
+ action: "set";
58
+ mode: KeepAwakeMode;
59
+ /** `--yes`: confirms keeping the computer awake more often without asking. */
60
+ yes?: true;
61
+ json?: true;
43
62
  } | {
44
63
  command: "service";
45
64
  action: "install" | "uninstall" | "start" | "stop" | "restart" | "status";
65
+ /** `service status --json`. */
66
+ json?: true;
46
67
  } | {
47
68
  command: "help";
48
69
  };
49
- export declare const USAGE = "Usage:\n capybara-device login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]\n Connect this machine: approve the code in the browser\n capybara-device logout Forget the credential on this machine\n capybara-device status [--json] Show whether this machine is logged in\n capybara-device start Connect and serve the device\n capybara-device stop Stop the running program\n capybara-device drain [--wait] [--timeout <seconds>]\n Finish running commands, accept no new ones, then stop;\n --wait returns once it has stopped (default limit 600 s)\n capybara-device ceiling show Show this machine's owner ceiling (Full access, project reach)\n capybara-device ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]\n Set the owner ceiling; widening needs --yes or a y at the prompt\n capybara-device policy [show] Show the local policy\n capybara-device policy set <key> <value>\n Replace one field (cpu, memoryMb, allowCredentials)\n capybara-device policy add|remove allowedDomains <host>\n Allow or stop allowing a domain for restricted work\n capybara-device policy add|remove allowCredentials <name>\n Allow or stop allowing a credential for restricted work\n capybara-device service install|uninstall\n Run at login as a user service, or remove it\n capybara-device service start|stop|restart\n Start, stop or restart the login service\n capybara-device service status Report whether the login service is loaded, what is running,\n and whether it is older than the installed program";
70
+ export declare const USAGE = "Usage:\n capybara-device login --url <url> [--no-browser] [--dir <path>] [--mode os|docker] [--json]\n Connect this machine: approve the code in the browser;\n --json prints one JSON event per line (no browser)\n capybara-device logout Forget the credential on this machine\n capybara-device status [--json] Show whether this machine is logged in\n capybara-device start Connect and serve the device\n capybara-device stop Stop the running program\n capybara-device drain [--wait] [--timeout <seconds>]\n Finish running commands, accept no new ones, then stop;\n --wait returns once it has stopped (default limit 600 s)\n capybara-device ceiling show [--json]\n Show this machine's owner ceiling (outside the sandbox, network,\n project reach)\n capybara-device ceiling set [--outside-sandbox on|off] [--network open|allowlist]\n [--project-reach workspace|os-user] [--yes]\n Change the owner ceiling (at least one field; the others stay);\n widening needs --yes or a y at the prompt\n capybara-device keep-awake [show | off | while-busy | connected] [--yes] [--json]\n Show or set when this computer is kept awake; raising it\n needs --yes or a y at the prompt\n capybara-device policy [show] Show the local policy\n capybara-device policy set <key> <value>\n Replace one field (cpu, memoryMb, allowCredentials)\n capybara-device policy add|remove allowedDomains <host>\n Allow or stop allowing a domain on the sandbox allowlist\n capybara-device policy add|remove allowCredentials <name>\n Allow or stop allowing a credential for restricted work\n capybara-device service install|uninstall\n Run at login as a user service, or remove it\n capybara-device service start|stop|restart\n Start, stop or restart the login service\n capybara-device service status [--json]\n Report whether the login service is loaded, what is running,\n and whether it is older than the installed program";
50
71
  /** Thrown for a bad command line; the message is shown with the usage. */
51
72
  export declare class UsageError extends Error {
52
73
  }
package/dist/args.js CHANGED
@@ -1,7 +1,9 @@
1
1
  import { parseArgs } from "node:util";
2
+ import { isKeepAwakeMode } from "./state.js";
2
3
  export const USAGE = `Usage:
3
- capybara-device login --url <url> [--no-browser] [--dir <path>] [--mode os|docker]
4
- Connect this machine: approve the code in the browser
4
+ capybara-device login --url <url> [--no-browser] [--dir <path>] [--mode os|docker] [--json]
5
+ Connect this machine: approve the code in the browser;
6
+ --json prints one JSON event per line (no browser)
5
7
  capybara-device logout Forget the credential on this machine
6
8
  capybara-device status [--json] Show whether this machine is logged in
7
9
  capybara-device start Connect and serve the device
@@ -9,21 +11,29 @@ export const USAGE = `Usage:
9
11
  capybara-device drain [--wait] [--timeout <seconds>]
10
12
  Finish running commands, accept no new ones, then stop;
11
13
  --wait returns once it has stopped (default limit 600 s)
12
- capybara-device ceiling show Show this machine's owner ceiling (Full access, project reach)
13
- capybara-device ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]
14
- Set the owner ceiling; widening needs --yes or a y at the prompt
14
+ capybara-device ceiling show [--json]
15
+ Show this machine's owner ceiling (outside the sandbox, network,
16
+ project reach)
17
+ capybara-device ceiling set [--outside-sandbox on|off] [--network open|allowlist]
18
+ [--project-reach workspace|os-user] [--yes]
19
+ Change the owner ceiling (at least one field; the others stay);
20
+ widening needs --yes or a y at the prompt
21
+ capybara-device keep-awake [show | off | while-busy | connected] [--yes] [--json]
22
+ Show or set when this computer is kept awake; raising it
23
+ needs --yes or a y at the prompt
15
24
  capybara-device policy [show] Show the local policy
16
25
  capybara-device policy set <key> <value>
17
26
  Replace one field (cpu, memoryMb, allowCredentials)
18
27
  capybara-device policy add|remove allowedDomains <host>
19
- Allow or stop allowing a domain for restricted work
28
+ Allow or stop allowing a domain on the sandbox allowlist
20
29
  capybara-device policy add|remove allowCredentials <name>
21
30
  Allow or stop allowing a credential for restricted work
22
31
  capybara-device service install|uninstall
23
32
  Run at login as a user service, or remove it
24
33
  capybara-device service start|stop|restart
25
34
  Start, stop or restart the login service
26
- capybara-device service status Report whether the login service is loaded, what is running,
35
+ capybara-device service status [--json]
36
+ Report whether the login service is loaded, what is running,
27
37
  and whether it is older than the installed program`;
28
38
  /** Thrown for a bad command line; the message is shown with the usage. */
29
39
  export class UsageError extends Error {
@@ -55,6 +65,7 @@ export function parseCommandLine(argv) {
55
65
  "no-browser": { type: "boolean" },
56
66
  dir: { type: "string" },
57
67
  mode: { type: "string" },
68
+ json: { type: "boolean" },
58
69
  });
59
70
  if (positionals.length > 0)
60
71
  throw new UsageError("login takes no positional arguments");
@@ -66,9 +77,10 @@ export function parseCommandLine(argv) {
66
77
  return {
67
78
  command: "login",
68
79
  url: String(values.url),
69
- browser: values["no-browser"] !== true,
80
+ browser: values["no-browser"] !== true && values.json !== true,
70
81
  ...(values.dir !== undefined && { dir: String(values.dir) }),
71
82
  mode,
83
+ ...(values.json === true && { json: true }),
72
84
  };
73
85
  }
74
86
  case "status": {
@@ -119,39 +131,84 @@ export function parseCommandLine(argv) {
119
131
  }
120
132
  case "ceiling": {
121
133
  const { values, positionals } = parse(rest, {
122
- "full-access": { type: "string" },
134
+ "outside-sandbox": { type: "string" },
135
+ network: { type: "string" },
123
136
  "project-reach": { type: "string" },
137
+ "full-access": { type: "string" },
124
138
  yes: { type: "boolean", short: "y" },
139
+ json: { type: "boolean" },
125
140
  });
126
141
  const [action, ...extra] = positionals;
127
- const usage = "usage: ceiling show | ceiling set --full-access allow|deny --project-reach workspace|os-user [--yes]";
142
+ const usage = "usage: ceiling show | ceiling set [--outside-sandbox on|off] [--network open|allowlist] " +
143
+ "[--project-reach workspace|os-user] [--yes]";
144
+ if (values["full-access"] !== undefined)
145
+ throw new UsageError(`--full-access is gone: Full access always runs in the sandbox now; use --outside-sandbox on|off. ${usage}`);
128
146
  if (extra.length > 0)
129
147
  throw new UsageError(usage);
148
+ const outside = values["outside-sandbox"];
149
+ const network = values.network;
150
+ const reach = values["project-reach"];
130
151
  if (action === "show" || action === undefined) {
131
- if (values["full-access"] !== undefined || values["project-reach"] !== undefined)
152
+ if (outside !== undefined || network !== undefined || reach !== undefined)
132
153
  throw new UsageError(usage);
133
- return { command: "ceiling", action: "show" };
154
+ return {
155
+ command: "ceiling",
156
+ action: "show",
157
+ ...(values.json === true && { json: true }),
158
+ };
134
159
  }
135
160
  if (action !== "set")
136
161
  throw new UsageError(usage);
137
- const full = values["full-access"];
138
- const reach = values["project-reach"];
139
- // both fields: one explicit atomic target
140
- if (full !== "allow" && full !== "deny")
162
+ if (values.json === true)
163
+ throw new UsageError(usage);
164
+ if (outside === undefined && network === undefined && reach === undefined)
165
+ throw new UsageError(usage);
166
+ if (outside !== undefined && outside !== "on" && outside !== "off")
141
167
  throw new UsageError(usage);
142
- if (reach !== "workspace" && reach !== "os-user")
168
+ if (network !== undefined && network !== "open" && network !== "allowlist")
169
+ throw new UsageError(usage);
170
+ if (reach !== undefined && reach !== "workspace" && reach !== "os-user")
143
171
  throw new UsageError(usage);
144
172
  return {
145
173
  command: "ceiling",
146
174
  action: "set",
147
- fullAccess: full === "allow",
148
- projectReach: reach,
175
+ ...(outside !== undefined && { outsideSandbox: outside === "on" }),
176
+ ...(network !== undefined && { network }),
177
+ ...(reach !== undefined && { projectReach: reach }),
178
+ ...(values.yes === true && { yes: true }),
179
+ };
180
+ }
181
+ case "keep-awake": {
182
+ const { values, positionals } = parse(rest, {
183
+ yes: { type: "boolean", short: "y" },
184
+ json: { type: "boolean" },
185
+ });
186
+ const usage = "usage: keep-awake [show | off | while-busy | connected] [--yes] [--json]";
187
+ const [action, ...extra] = positionals;
188
+ if (extra.length > 0)
189
+ throw new UsageError(usage);
190
+ const json = values.json === true && { json: true };
191
+ if (action === undefined || action === "show") {
192
+ if (values.yes === true)
193
+ throw new UsageError(usage);
194
+ return { command: "keep-awake", action: "show", ...json };
195
+ }
196
+ if (!isKeepAwakeMode(action))
197
+ throw new UsageError(usage);
198
+ return {
199
+ command: "keep-awake",
200
+ action: "set",
201
+ mode: action,
149
202
  ...(values.yes === true && { yes: true }),
203
+ ...json,
150
204
  };
151
205
  }
152
206
  case "service": {
153
- const { positionals } = parse(rest, {});
207
+ const { values, positionals } = parse(rest, { json: { type: "boolean" } });
154
208
  const [action, ...extra] = positionals;
209
+ if (values.json === true && action !== "status") {
210
+ throw new UsageError("--json is only for service status");
211
+ }
155
212
  if ((action === "install" ||
156
213
  action === "uninstall" ||
157
214
  action === "start" ||
@@ -159,7 +216,11 @@ export function parseCommandLine(argv) {
159
216
  action === "restart" ||
160
217
  action === "status") &&
161
218
  extra.length === 0) {
162
- return { command: "service", action };
219
+ return {
220
+ command: "service",
221
+ action,
222
+ ...(values.json === true && { json: true }),
223
+ };
163
224
  }
164
225
  throw new UsageError("usage: service install|uninstall|start|stop|restart|status");
165
226
  }