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

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 (65) hide show
  1. package/README.md +79 -0
  2. package/dist/activity.d.ts +31 -0
  3. package/dist/activity.js +62 -0
  4. package/dist/args.d.ts +18 -2
  5. package/dist/args.js +56 -8
  6. package/dist/cli.js +13 -2
  7. package/dist/commands/ceiling.js +22 -0
  8. package/dist/commands/keep-awake.d.ts +19 -0
  9. package/dist/commands/keep-awake.js +77 -0
  10. package/dist/commands/login.js +29 -16
  11. package/dist/commands/service.d.ts +3 -1
  12. package/dist/commands/service.js +35 -2
  13. package/dist/commands/start.d.ts +7 -0
  14. package/dist/commands/start.js +120 -1
  15. package/dist/commands/status.d.ts +8 -1
  16. package/dist/commands/status.js +50 -2
  17. package/dist/control/client.d.ts +12 -0
  18. package/dist/control/client.js +63 -0
  19. package/dist/control/protocol.d.ts +58 -0
  20. package/dist/control/protocol.js +16 -0
  21. package/dist/control/server.d.ts +28 -0
  22. package/dist/control/server.js +254 -0
  23. package/dist/exec/mac-operation-backend.d.ts +5 -0
  24. package/dist/exec/mac-operation-backend.js +26 -6
  25. package/dist/exec/native-helper-client.js +10 -2
  26. package/dist/exec/operation-supervisor.d.ts +30 -1
  27. package/dist/exec/operation-supervisor.js +60 -2
  28. package/dist/exec/operation-worker.js +3 -0
  29. package/dist/exec/transfer-timing.d.ts +16 -0
  30. package/dist/exec/transfer-timing.js +26 -0
  31. package/dist/index.d.ts +2 -0
  32. package/dist/index.js +1 -0
  33. package/dist/keep-awake.d.ts +39 -0
  34. package/dist/keep-awake.js +104 -0
  35. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +22 -4
  36. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +4 -3
  37. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -1
  38. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -1
  39. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +1 -1
  40. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
  41. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
  42. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
  43. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
  44. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
  45. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
  46. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
  47. package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
  48. package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
  49. package/dist/runtime-manifest.json +1 -1
  50. package/dist/server-ops.d.ts +3 -0
  51. package/dist/server-ops.js +33 -0
  52. package/dist/service/launchd.d.ts +2 -0
  53. package/dist/service/launchd.js +10 -4
  54. package/dist/service/manager.d.ts +2 -0
  55. package/dist/service/manager.js +16 -2
  56. package/dist/service/systemd.d.ts +2 -0
  57. package/dist/service/systemd.js +8 -2
  58. package/dist/staged-connect.d.ts +9 -0
  59. package/dist/staged-connect.js +24 -2
  60. package/dist/staged-device.js +6 -0
  61. package/dist/state.d.ts +9 -0
  62. package/dist/state.js +9 -1
  63. package/dist/wake.d.ts +23 -0
  64. package/dist/wake.js +29 -0
  65. package/package.json +2 -2
@@ -0,0 +1,254 @@
1
+ import { chmodSync, lstatSync, statSync, unlinkSync } from "node:fs";
2
+ import { createConnection, createServer } from "node:net";
3
+ import { CONTROL_LINE_MAX_BYTES, CONTROL_OPS, CONTROL_PATH_MAX_BYTES, CONTROL_WRITE_MAX_BYTES, controlSocketPath, } from "./protocol.js";
4
+ /** How long the check for a live socket at the path waits for a connection. */
5
+ const PROBE_TIMEOUT_MS = 1000;
6
+ /** Owner-only peers: a handful of connections is plenty (the desktop app, a `status`). */
7
+ const MAX_CONNECTIONS = 32;
8
+ const mode = (st) => `0${(st.mode & 0o777).toString(8)}`;
9
+ /**
10
+ * Why no control socket can be made for this state directory, from what is visible without
11
+ * binding: a path over {@link CONTROL_PATH_MAX_BYTES}, or a state directory that is missing, not
12
+ * the user's or open to other users (the same owner and mode rule the credential file follows).
13
+ * Undefined when nothing is in the way. `status` uses it to explain a runner that does not answer.
14
+ */
15
+ export function controlUnavailableReason(stateDir) {
16
+ const path = controlSocketPath(stateDir);
17
+ const bytes = Buffer.byteLength(path);
18
+ if (bytes > CONTROL_PATH_MAX_BYTES) {
19
+ return (`the control socket path ${path} is ${bytes} bytes, longer than the ` +
20
+ `${CONTROL_PATH_MAX_BYTES} bytes a unix socket path may have; use a shorter XDG_CONFIG_HOME`);
21
+ }
22
+ let st;
23
+ try {
24
+ st = statSync(stateDir);
25
+ }
26
+ catch (e) {
27
+ return `the state directory ${stateDir} cannot be read (${e.message})`;
28
+ }
29
+ if (!st.isDirectory())
30
+ return `the state directory ${stateDir} is not a directory`;
31
+ const uid = process.getuid?.();
32
+ if (uid !== undefined && st.uid !== uid) {
33
+ return `the state directory ${stateDir} belongs to another user (uid ${st.uid})`;
34
+ }
35
+ if ((st.mode & 0o077) !== 0) {
36
+ return (`the state directory ${stateDir} has mode ${mode(st)}, open to other users; ` +
37
+ `run chmod 700 ${stateDir}`);
38
+ }
39
+ return undefined;
40
+ }
41
+ /** Whether something answers on the socket at `path`: "live", "stale" (nothing listens) or why not. */
42
+ function probe(path) {
43
+ return new Promise((resolve) => {
44
+ const sock = createConnection(path);
45
+ const done = (r) => {
46
+ clearTimeout(timer);
47
+ sock.destroy();
48
+ resolve(r);
49
+ };
50
+ const timer = setTimeout(() => done({ error: "it did not answer in time" }), PROBE_TIMEOUT_MS);
51
+ sock.once("connect", () => done("live"));
52
+ sock.once("error", (e) => done(e.code === "ECONNREFUSED" || e.code === "ENOENT" ? "stale" : { error: e.message }));
53
+ });
54
+ }
55
+ /**
56
+ * Clears the way for a socket at `path`: nothing there, or a stale socket of this user (nothing
57
+ * listens) that is removed. A live socket, a file that is not a socket or one of another user is
58
+ * never touched. Answers why not, or undefined when the path is free.
59
+ */
60
+ async function clearPath(path) {
61
+ let st;
62
+ try {
63
+ st = lstatSync(path);
64
+ }
65
+ catch {
66
+ return undefined;
67
+ }
68
+ if (!st.isSocket())
69
+ return `${path} exists and is not a socket; it was left alone`;
70
+ const uid = process.getuid?.();
71
+ if (uid !== undefined && st.uid !== uid)
72
+ return `${path} belongs to another user`;
73
+ const found = await probe(path);
74
+ if (found === "live")
75
+ return `another capybara-device already answers on ${path}`;
76
+ if (found !== "stale")
77
+ return `${path} cannot be checked (${found.error})`;
78
+ try {
79
+ // only the socket judged stale: a file replaced meanwhile is left alone
80
+ const now = lstatSync(path);
81
+ if (now.ino === st.ino && now.dev === st.dev)
82
+ unlinkSync(path);
83
+ }
84
+ catch {
85
+ // gone already
86
+ }
87
+ return undefined;
88
+ }
89
+ /** Binds `path` with the umask closed to group and others, so the socket is never wider than 0600. */
90
+ function listen(server, path) {
91
+ return new Promise((resolve, reject) => {
92
+ server.once("error", reject);
93
+ // the bind of a unix socket happens inside listen(), synchronously: the umask is restored
94
+ // right after it, never left closed across an await
95
+ const umask = process.umask(0o077);
96
+ try {
97
+ server.listen(path, () => {
98
+ server.off("error", reject);
99
+ resolve();
100
+ });
101
+ }
102
+ finally {
103
+ process.umask(umask);
104
+ }
105
+ });
106
+ }
107
+ /**
108
+ * Starts the control socket at `<stateDir>/control.sock` (mode 0600). Answers `{ unavailable }`
109
+ * with the reason instead when the socket cannot be made safely; the runner keeps serving then.
110
+ */
111
+ export async function startControlServer(opts) {
112
+ const path = controlSocketPath(opts.stateDir);
113
+ const blocked = controlUnavailableReason(opts.stateDir) ?? (await clearPath(path));
114
+ if (blocked !== undefined)
115
+ return { unavailable: blocked };
116
+ const sockets = new Set();
117
+ const subscribers = new Set();
118
+ const send = (sock, line) => {
119
+ if (sock.destroyed || !sock.writable)
120
+ return;
121
+ sock.write(`${JSON.stringify(line)}\n`);
122
+ // a peer that stopped reading (a subscriber above all) never pins memory here
123
+ if (sock.writableLength > CONTROL_WRITE_MAX_BYTES)
124
+ sock.destroy();
125
+ };
126
+ const failure = (id, code, message) => ({
127
+ id,
128
+ ok: false,
129
+ error: { code, message },
130
+ });
131
+ const fail = (sock, id, code, message) => send(sock, failure(id, code, message));
132
+ /** The answer to one request line; a subscribe also adds the connection to the subscribers. */
133
+ const respond = (sock, line) => {
134
+ let req;
135
+ try {
136
+ req = JSON.parse(line);
137
+ }
138
+ catch {
139
+ return failure(0, "bad_request", "The line is not JSON");
140
+ }
141
+ const r = (req !== null && typeof req === "object" ? req : {});
142
+ const id = typeof r.id === "number" && Number.isSafeInteger(r.id) && r.id > 0 ? r.id : 0;
143
+ if (id === 0)
144
+ return failure(0, "bad_request", 'The request needs "id", a positive integer');
145
+ if (typeof r.op !== "string" || !CONTROL_OPS.includes(r.op)) {
146
+ return failure(id, "unknown_op", `Unknown op; one of ${CONTROL_OPS.join(", ")}`);
147
+ }
148
+ const op = r.op;
149
+ try {
150
+ if (op === "status")
151
+ return { id, ok: true, result: opts.status() };
152
+ if (op === "running")
153
+ return { id, ok: true, result: opts.running() };
154
+ if (op === "subscribe") {
155
+ subscribers.add(sock);
156
+ return { id, ok: true, result: opts.status() };
157
+ }
158
+ if (op === "drain")
159
+ opts.drain();
160
+ else
161
+ opts.stop();
162
+ return { id, ok: true, result: null };
163
+ }
164
+ catch (e) {
165
+ return failure(id, "failed", e.message);
166
+ }
167
+ };
168
+ const answer = (sock, line) => send(sock, respond(sock, line));
169
+ const server = createServer((sock) => {
170
+ sockets.add(sock);
171
+ sock.setEncoding("utf8");
172
+ let buf = "";
173
+ let refused = false;
174
+ const overLong = () => {
175
+ refused = true;
176
+ buf = "";
177
+ fail(sock, 0, "bad_request", `A line is longer than ${CONTROL_LINE_MAX_BYTES} bytes`);
178
+ sock.end();
179
+ };
180
+ // one listener per connection: lines are answered in order
181
+ sock.on("data", (chunk) => {
182
+ if (refused)
183
+ return;
184
+ buf += chunk;
185
+ for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
186
+ const line = buf.slice(0, i);
187
+ buf = buf.slice(i + 1);
188
+ if (Buffer.byteLength(line) > CONTROL_LINE_MAX_BYTES)
189
+ return overLong();
190
+ if (line.trim() !== "")
191
+ answer(sock, line);
192
+ }
193
+ if (Buffer.byteLength(buf) > CONTROL_LINE_MAX_BYTES)
194
+ overLong();
195
+ });
196
+ sock.on("error", () => {
197
+ // a peer that went away: nothing to answer
198
+ });
199
+ sock.on("close", () => {
200
+ sockets.delete(sock);
201
+ subscribers.delete(sock);
202
+ });
203
+ });
204
+ server.maxConnections = MAX_CONNECTIONS;
205
+ try {
206
+ await listen(server, path);
207
+ }
208
+ catch (e) {
209
+ const err = e;
210
+ return {
211
+ unavailable: err.code === "EADDRINUSE"
212
+ ? `another capybara-device already answers on ${path}`
213
+ : `cannot listen on ${path} (${err.message})`,
214
+ };
215
+ }
216
+ let bound;
217
+ try {
218
+ chmodSync(path, 0o600);
219
+ bound = lstatSync(path);
220
+ }
221
+ catch (e) {
222
+ await new Promise((r) => server.close(() => r()));
223
+ return { unavailable: `cannot secure ${path} (${e.message})` };
224
+ }
225
+ server.on("error", () => {
226
+ // a failure after listening affects new connections only; the runner keeps serving
227
+ });
228
+ let closed;
229
+ return {
230
+ publish(s) {
231
+ for (const sock of subscribers)
232
+ send(sock, { event: "status", status: s });
233
+ },
234
+ close() {
235
+ closed ??= new Promise((resolve) => {
236
+ for (const sock of sockets)
237
+ sock.destroy();
238
+ server.close(() => {
239
+ try {
240
+ // only the socket this server bound: one another runner bound meanwhile stays
241
+ const now = lstatSync(path);
242
+ if (now.ino === bound.ino && now.dev === bound.dev)
243
+ unlinkSync(path);
244
+ }
245
+ catch {
246
+ // removed already (the listener's close unlinks it)
247
+ }
248
+ resolve();
249
+ });
250
+ });
251
+ return closed;
252
+ },
253
+ };
254
+ }
@@ -14,6 +14,11 @@ export interface MacOperationBackendOptions {
14
14
  */
15
15
  runtimeHash?: string;
16
16
  readOwnerCeiling: () => Promise<DeviceOwnerCeiling>;
17
+ /**
18
+ * Called when an operation's worker is gone (completed, killed, failed to launch): a background
19
+ * task long after its start answered. Feeds the control socket's running operations.
20
+ */
21
+ onOperationEnded?: (operationId: string) => void;
17
22
  }
18
23
  export type MacOperationBackend = Required<Pick<SandboxProvider, "permissionSupport" | "operation" | "browse" | "prepare" | "revokeOperation" | "background">> & {
19
24
  forExecution(authority: LocalExecAuthority): Pick<MacOperationBackend, "operation" | "background">;
@@ -1,8 +1,10 @@
1
+ import { createHash } from "node:crypto";
1
2
  import { resolve } from "node:path";
2
3
  import { parseSandboxBrowseScope, parseSandboxOperationScope, parseSandboxPreparationScope, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
3
4
  import { implicitWritePaths } from "../policy.js";
4
5
  import { MacOperationSupervisor, } from "./operation-supervisor.js";
5
6
  import { checkRoots, digest, freezeAuthority, intersectOperation, within, } from "./operation-types.js";
7
+ import { timed } from "./transfer-timing.js";
6
8
  const PENDING = "Restricted macOS per-instance validation and coordinated policy/background activation are pending";
7
9
  export async function createMacOperationBackend(options, dependencies = {}) {
8
10
  const platform = dependencies.platform ?? process.platform;
@@ -75,6 +77,7 @@ export async function createLocalOperationBackend(options, dependencies, host) {
75
77
  ...(dependencies.now ? { now: dependencies.now } : {}),
76
78
  ...(host.startWorker ? { start: host.startWorker } : {}),
77
79
  ...(host.reapOrphan ? { reapOrphan: host.reapOrphan } : {}),
80
+ ...(options.onOperationEnded ? { onLiveEnded: options.onOperationEnded } : {}),
78
81
  onLiveChanged: (live) => {
79
82
  if (live && !stopWatch) {
80
83
  if (dependencies.watch)
@@ -208,7 +211,16 @@ export async function createLocalOperationBackend(options, dependencies, host) {
208
211
  cwd: args?.cwd ?? options.roots.workspace,
209
212
  },
210
213
  };
211
- const hash = digest({ scope, native, args, authority, background });
214
+ // The admission hash binds the operation id to its exact input. A write's bytes enter it as
215
+ // their sha256, hashed once, instead of being re-serialised inside the request JSON: a
216
+ // collision-resistant hash of the bytes binds them as tightly as the bytes themselves.
217
+ const hash = timed(native?.method ?? "exec", "digest", () => {
218
+ const { dataB64, ...rest } = native ?? {};
219
+ const input = dataB64 === undefined
220
+ ? native
221
+ : { ...rest, dataSha256: createHash("sha256").update(dataB64).digest("hex") };
222
+ return digest({ scope, native: input, args, authority, background });
223
+ });
212
224
  return background
213
225
  ? supervisor.start(request, hash, background.retainUntilMs, signal)
214
226
  : supervisor.execute(request, hash, signal);
@@ -221,15 +233,23 @@ export async function createLocalOperationBackend(options, dependencies, host) {
221
233
  opts.maxBytes < 0 ||
222
234
  opts.maxBytes > 16 * 1024 * 1024)
223
235
  throw new SandboxScopeDeniedError("Invalid native read bound");
224
- const result = (await run({ method: "readFile", path, maxBytes: opts.maxBytes }, opts.signal));
225
- return result
226
- ? { data: Buffer.from(result.dataB64, "base64"), truncated: result.truncated }
227
- : null;
236
+ return timed("readFile", "total", async () => {
237
+ const result = (await run({ method: "readFile", path, maxBytes: opts.maxBytes }, opts.signal));
238
+ return result
239
+ ? timed("readFile", "encode", () => ({
240
+ data: Buffer.from(result.dataB64, "base64"),
241
+ truncated: result.truncated,
242
+ }))
243
+ : null;
244
+ });
228
245
  },
229
246
  writeFile: async (path, data, signal) => {
230
247
  if (data.byteLength > 16 * 1024 * 1024)
231
248
  throw new SandboxScopeDeniedError("Native write exceeds bounded transport");
232
- await run({ method: "writeFile", path, dataB64: Buffer.from(data).toString("base64") }, signal);
249
+ await timed("writeFile", "total", async () => {
250
+ const dataB64 = timed("writeFile", "encode", () => Buffer.from(data).toString("base64"));
251
+ await run({ method: "writeFile", path, dataB64 }, signal);
252
+ });
233
253
  },
234
254
  stat: (path, signal) => run({ method: "stat", path }, signal),
235
255
  list: (path, opts) => run({ method: "list", path, limit: opts.limit }, opts.signal),
@@ -1,6 +1,7 @@
1
1
  import { spawn } from "node:child_process";
2
2
  import { fstatSync } from "node:fs";
3
3
  import { SANDBOX_RUNTIME_SOURCE, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, } from "@capybara-hq/plugin-sdk";
4
+ import { recordTransferTiming, timed } from "./transfer-timing.js";
4
5
  // The pinned SDK source remains unchanged. This fixed transport only establishes its exact
5
6
  // directory roots; the ancestor descriptor never becomes a NativeFiles data grant.
6
7
  /** The native helper by name: the bundle also carries the Linux launcher, so order is not relied on. */
@@ -82,6 +83,8 @@ export async function runNativeHelper(request, roots, launch, signal) {
82
83
  throw new Error("Pinned root must be a directory");
83
84
  return [s.dev, s.ino];
84
85
  });
86
+ const spawnedAt = performance.now();
87
+ let dispatchedAt = 0;
85
88
  const child = (launch.spawn ?? spawn)(launch.pythonPath, ["-I", "-c", PRELUDE, NATIVE_FILES_SOURCE, JSON.stringify(expected)], { detached: true, stdio: ["pipe", "pipe", "pipe", "pipe", ...roots.map((r) => r.fd)] });
86
89
  let bytes = 0;
87
90
  let stderrBytes = 0;
@@ -144,6 +147,7 @@ export async function runNativeHelper(request, roots, launch, signal) {
144
147
  }
145
148
  if (handshake === "ready\n" && !ready) {
146
149
  ready = true;
150
+ recordTransferTiming(request.method, "spawn", performance.now() - spawnedAt);
147
151
  void (async () => {
148
152
  try {
149
153
  await launched;
@@ -160,7 +164,9 @@ export async function runNativeHelper(request, roots, launch, signal) {
160
164
  ...(r.components ? { components: r.components } : {}),
161
165
  });
162
166
  });
163
- child.stdin?.end(JSON.stringify({ ...request, roots: mapped }));
167
+ const body = timed(request.method, "serialise", () => JSON.stringify({ ...request, roots: mapped }));
168
+ dispatchedAt = performance.now();
169
+ child.stdin?.end(body);
164
170
  }
165
171
  catch (e) {
166
172
  failure = e;
@@ -181,6 +187,8 @@ export async function runNativeHelper(request, roots, launch, signal) {
181
187
  signal.removeEventListener("abort", abort);
182
188
  kill();
183
189
  }
190
+ if (dispatchedAt)
191
+ recordTransferTiming(request.method, "helperIo", performance.now() - dispatchedAt);
184
192
  signal.throwIfAborted();
185
193
  if (failure)
186
194
  throw failure;
@@ -188,7 +196,7 @@ export async function runNativeHelper(request, roots, launch, signal) {
188
196
  throw new SandboxPermissionUnsupportedError("Native helper descriptor handshake failed; pathname reopening is forbidden");
189
197
  let response;
190
198
  try {
191
- response = JSON.parse(Buffer.concat(chunks).toString("utf8"));
199
+ response = timed(request.method, "parse", () => JSON.parse(Buffer.concat(chunks).toString("utf8")));
192
200
  }
193
201
  catch {
194
202
  throw new Error("Native helper returned invalid bounded JSON");
@@ -11,7 +11,7 @@ interface Entry {
11
11
  state: "consumed" | "running" | "completed" | "unknown";
12
12
  revoked: boolean;
13
13
  identity?: TrustedLaunchIdentity;
14
- result?: ExecResult | NativeHelperResult;
14
+ result?: ExecResult | NativeHelperResult | OmittedReadResult;
15
15
  stop?: SandboxStopResult;
16
16
  request?: {
17
17
  scope: MacWorkerRequest["scope"];
@@ -29,6 +29,17 @@ interface Entry {
29
29
  cleaned?: boolean;
30
30
  };
31
31
  }
32
+ /**
33
+ * What the journal keeps of a completed native read: its outcome, never its bytes. The bytes stay
34
+ * in this process's memory for in-process retries; rewriting megabytes of file content on every
35
+ * fsynced journal commit is what made transfers slow and could exhaust the journal. A read has no
36
+ * lasting effect, so after a restart its retry reports an unknown outcome instead.
37
+ */
38
+ interface OmittedReadResult {
39
+ omitted: "native-read";
40
+ bytes: number;
41
+ truncated: boolean;
42
+ }
32
43
  export interface SupervisorOptions {
33
44
  stateDir: string;
34
45
  deviceId: string;
@@ -36,6 +47,11 @@ export interface SupervisorOptions {
36
47
  now?: () => number;
37
48
  start?: (request: MacWorkerRequest, signal: AbortSignal) => Promise<MacWorkerHandle>;
38
49
  onLiveChanged?: (live: boolean) => void;
50
+ /**
51
+ * Called once each live worker (an exec, or a background task long after its start answered)
52
+ * is gone: completed, killed or failed to launch. Never throws into the supervisor.
53
+ */
54
+ onLiveEnded?: (operationId: string) => void;
39
55
  pythonPath?: string;
40
56
  outputBarrier?: (name: string) => Promise<void>;
41
57
  beforePersist?: () => void;
@@ -45,6 +61,12 @@ export interface SupervisorOptions {
45
61
  * the entry stays unknown and is never resumed.
46
62
  */
47
63
  reapOrphan?: (identity: TrustedLaunchIdentity) => void;
64
+ /**
65
+ * The most completed native read bytes kept in memory for retries (default 64 MiB). Past it the
66
+ * oldest reads give their bytes up and their retry reports an unknown outcome, as after a
67
+ * restart.
68
+ */
69
+ retainedReadBytes?: number;
48
70
  }
49
71
  /** What a supervisor still owns: work that a drain must see settle before it disconnects. */
50
72
  export interface SupervisorOwnership {
@@ -89,8 +111,14 @@ export declare class MacOperationSupervisor {
89
111
  private controlFile;
90
112
  private recoverControl;
91
113
  private persistControl;
114
+ /**
115
+ * Keeps the completed read bytes held for retries within {@link SupervisorOptions.retainedReadBytes}:
116
+ * the oldest reads (admission order) give their bytes up first.
117
+ */
118
+ private boundRetainedReads;
92
119
  private serial;
93
120
  private persist;
121
+ private persistNow;
94
122
  private expireRetained;
95
123
  private validate;
96
124
  private admit;
@@ -117,6 +145,7 @@ export declare class MacOperationSupervisor {
117
145
  * The owner watcher runs while anything is owned: a live worker, a faulted collector's owner or
118
146
  * an exact cancellation still settling (an idle socket or a disconnect does not end it).
119
147
  */
148
+ private liveEnded;
120
149
  private notifyOwned;
121
150
  ownership(): SupervisorOwnership;
122
151
  /** Starts a graceful drain: no new admission from now on, for the rest of this process. */
@@ -6,6 +6,23 @@ import { parseSandboxExecutionRef, parseSandboxOperationRef, SandboxOperationOut
6
6
  import { digest } from "./operation-types.js";
7
7
  import { startMacOperationWorker, } from "./operation-worker.js";
8
8
  import { finalizeRecoveredOutput, ManagedOutputSpool, validateOutputRange, } from "./output-spool.js";
9
+ import { timed } from "./transfer-timing.js";
10
+ const isOmittedRead = (result) => typeof result === "object" && result !== null && "omitted" in result;
11
+ /** A completed native read's bytes as base64, while the entry still holds them. */
12
+ const readBytes = (result) => typeof result === "object" && result !== null && "dataB64" in result ? result.dataB64 : undefined;
13
+ const omitRead = (result) => ({
14
+ omitted: "native-read",
15
+ bytes: Buffer.byteLength(result.dataB64, "base64"),
16
+ truncated: result.truncated,
17
+ });
18
+ /** The entry as the journal stores it (see {@link OmittedReadResult}). */
19
+ function journalForm(entry) {
20
+ const result = entry.result;
21
+ if (readBytes(result) === undefined)
22
+ return entry;
23
+ return { ...entry, result: omitRead(result) };
24
+ }
25
+ const RETAINED_READ_BYTES = 64 * 1024 * 1024;
9
26
  class JournalCommitUncertainError extends Error {
10
27
  }
11
28
  /** A drain gave up before everything it owns settled; the supervisor stays draining. */
@@ -290,12 +307,38 @@ export class MacOperationSupervisor {
290
307
  catch { }
291
308
  }
292
309
  }
310
+ /**
311
+ * Keeps the completed read bytes held for retries within {@link SupervisorOptions.retainedReadBytes}:
312
+ * the oldest reads (admission order) give their bytes up first.
313
+ */
314
+ boundRetainedReads() {
315
+ const budget = this.options.retainedReadBytes ?? RETAINED_READ_BYTES;
316
+ const held = [];
317
+ let total = 0;
318
+ for (const entry of this.entries.values()) {
319
+ const data = readBytes(entry.result);
320
+ if (data === undefined)
321
+ continue;
322
+ held.push(entry);
323
+ total += Buffer.byteLength(data, "base64");
324
+ }
325
+ for (const entry of held) {
326
+ if (total <= budget)
327
+ break;
328
+ const result = entry.result;
329
+ total -= Buffer.byteLength(result.dataB64, "base64");
330
+ entry.result = omitRead(result);
331
+ }
332
+ }
293
333
  serial(fn) {
294
334
  const next = this.queue.then(fn);
295
335
  this.queue = next.catch(() => { });
296
336
  return next;
297
337
  }
298
338
  persist() {
339
+ timed("supervisor", "journal", () => this.persistNow());
340
+ }
341
+ persistNow() {
299
342
  if (this.closed)
300
343
  throw new SandboxPermissionUnsupportedError("This instance generation was superseded; its journal belongs to the current binding");
301
344
  if (this.journalBlocked)
@@ -309,7 +352,11 @@ export class MacOperationSupervisor {
309
352
  deviceId: this.options.deviceId,
310
353
  generation: this.options.instanceGeneration,
311
354
  };
312
- const journal = { version: 1, transaction, entries: [...this.entries.values()] };
355
+ const journal = {
356
+ version: 1,
357
+ transaction,
358
+ entries: [...this.entries.values()].map(journalForm),
359
+ };
313
360
  const text = JSON.stringify(journal);
314
361
  if (Buffer.byteLength(text) > 64 * 1024 * 1024)
315
362
  throw Error("Operation journal capacity exhausted");
@@ -539,6 +586,7 @@ export class MacOperationSupervisor {
539
586
  };
540
587
  entry.state = "completed";
541
588
  entry.result = value;
589
+ this.boundRetainedReads();
542
590
  if (entry.stop?.outcome === "cancel-pending" &&
543
591
  !this.cancellations.has(entry.ref.operationId) &&
544
592
  value &&
@@ -580,6 +628,7 @@ export class MacOperationSupervisor {
580
628
  await spool?.close();
581
629
  signal.removeEventListener("abort", abort);
582
630
  this.live.delete(entry.ref.operationId);
631
+ this.liveEnded(entry.ref.operationId);
583
632
  this.notifyOwned();
584
633
  })
585
634
  .catch((error) => {
@@ -604,6 +653,7 @@ export class MacOperationSupervisor {
604
653
  });
605
654
  reject(error);
606
655
  this.live.delete(entry.ref.operationId);
656
+ this.liveEnded(entry.ref.operationId);
607
657
  this.notifyOwned();
608
658
  throw error;
609
659
  }
@@ -613,7 +663,7 @@ export class MacOperationSupervisor {
613
663
  async execute(request, hash, signal) {
614
664
  const { entry, fresh } = await this.admit(request, hash, this.now() + 60000, signal);
615
665
  if (!fresh) {
616
- if (entry.state === "completed")
666
+ if (entry.state === "completed" && !isOmittedRead(entry.result))
617
667
  return entry.result ?? null;
618
668
  throw new SandboxOperationOutcomeUnknownError("Consumed operation outcome is unknown");
619
669
  }
@@ -872,6 +922,14 @@ export class MacOperationSupervisor {
872
922
  * The owner watcher runs while anything is owned: a live worker, a faulted collector's owner or
873
923
  * an exact cancellation still settling (an idle socket or a disconnect does not end it).
874
924
  */
925
+ liveEnded(operationId) {
926
+ try {
927
+ this.options.onLiveEnded?.(operationId);
928
+ }
929
+ catch {
930
+ // an observer never affects the supervisor
931
+ }
932
+ }
875
933
  notifyOwned() {
876
934
  this.options.onLiveChanged?.(this.live.size > 0 || this.faultOwners.size > 0 || this.cancellations.size > 0);
877
935
  }
@@ -12,6 +12,7 @@ import { runNativeHelper, } from "./native-helper-client.js";
12
12
  import { withCanonicalForms } from "./operation-types.js";
13
13
  import { acquireSealedRuntime, stagePrivateSource, stageRuntimeSource, } from "./runtime-source.js";
14
14
  import { ENV_NAME_RE, OutputCap, restrictedToolHomes, shellQuote } from "./shared.js";
15
+ import { recordTransferTiming } from "./transfer-timing.js";
15
16
  /** Coalesce an active owned cancellation; a failed attempt never becomes a cached outcome. */
16
17
  export function createCancellationAttempt(attempt) {
17
18
  let pending;
@@ -370,6 +371,7 @@ export async function startMacOperationWorker(request, signal) {
370
371
  abort();
371
372
  let sealed;
372
373
  let privateTmp;
374
+ const preparedAt = performance.now();
373
375
  const completion = (async () => {
374
376
  try {
375
377
  // Restricted workers import only the sealed private copy of the verified runtime closure
@@ -578,6 +580,7 @@ export async function startMacOperationWorker(request, signal) {
578
580
  const transport = await import("./native-helper-client.js");
579
581
  const invocation = transport.nativeHelperInvocation(roots, launch);
580
582
  prepared = await wrap([invocation.command, ...invocation.args].map(shellQuote).join(" "));
583
+ recordTransferTiming(request.native.method, "prepare", performance.now() - preparedAt);
581
584
  return await runNativeHelper({
582
585
  ...request.native,
583
586
  path: (() => {
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Debug-level stage timings of native file transfers (readFile / writeFile). Off by default:
3
+ * `CAPYBARA_DEVICE_DEBUG_TIMINGS=1` prints one line per stage to stderr, and tests observe the
4
+ * stages through {@link observeTransferTimings}. Timings carry no paths and no data.
5
+ */
6
+ export type TransferStage = "encode" | "digest" | "journal" | "prepare" | "spawn" | "serialise" | "helperIo" | "parse" | "total";
7
+ export interface TransferTiming {
8
+ method: string;
9
+ stage: TransferStage;
10
+ ms: number;
11
+ }
12
+ /** Observes every recorded stage until the returned function is called. */
13
+ export declare function observeTransferTimings(listener: (timing: TransferTiming) => void): () => void;
14
+ export declare function recordTransferTiming(method: string, stage: TransferStage, ms: number): void;
15
+ /** Runs `work` and records how long it took as `stage`. */
16
+ export declare function timed<T>(method: string, stage: TransferStage, work: () => T): T;
@@ -0,0 +1,26 @@
1
+ const listeners = new Set();
2
+ /** Observes every recorded stage until the returned function is called. */
3
+ export function observeTransferTimings(listener) {
4
+ listeners.add(listener);
5
+ return () => listeners.delete(listener);
6
+ }
7
+ export function recordTransferTiming(method, stage, ms) {
8
+ if (process.env.CAPYBARA_DEVICE_DEBUG_TIMINGS === "1")
9
+ process.stderr.write(`[capybara-device] ${method} ${stage} ${ms.toFixed(1)} ms\n`);
10
+ for (const listener of listeners)
11
+ try {
12
+ listener({ method, stage, ms });
13
+ }
14
+ catch {
15
+ // instrumentation never changes an operation's outcome
16
+ }
17
+ }
18
+ /** Runs `work` and records how long it took as `stage`. */
19
+ export function timed(method, stage, work) {
20
+ const started = performance.now();
21
+ const result = work();
22
+ if (result instanceof Promise)
23
+ return result.finally(() => recordTransferTiming(method, stage, performance.now() - started));
24
+ recordTransferTiming(method, stage, performance.now() - started);
25
+ return result;
26
+ }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ export type { RunningOperation } from "./activity.js";
1
2
  export { type Command, parseCommandLine } from "./args.js";
2
3
  export { runCli } from "./cli.js";
4
+ export { type ControlEvent, type ControlRequest, type ControlResponse, controlSocketPath, type LiveStatus, } from "./control/protocol.js";
3
5
  export { type Credential, type Policy, type SandboxMode, stateDir } from "./state.js";
package/dist/index.js CHANGED
@@ -1,3 +1,4 @@
1
1
  export { parseCommandLine } from "./args.js";
2
2
  export { runCli } from "./cli.js";
3
+ export { controlSocketPath, } from "./control/protocol.js";
3
4
  export { stateDir } from "./state.js";