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

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.
@@ -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;
@@ -208,7 +210,16 @@ export async function createLocalOperationBackend(options, dependencies, host) {
208
210
  cwd: args?.cwd ?? options.roots.workspace,
209
211
  },
210
212
  };
211
- const hash = digest({ scope, native, args, authority, background });
213
+ // The admission hash binds the operation id to its exact input. A write's bytes enter it as
214
+ // their sha256, hashed once, instead of being re-serialised inside the request JSON: a
215
+ // collision-resistant hash of the bytes binds them as tightly as the bytes themselves.
216
+ const hash = timed(native?.method ?? "exec", "digest", () => {
217
+ const { dataB64, ...rest } = native ?? {};
218
+ const input = dataB64 === undefined
219
+ ? native
220
+ : { ...rest, dataSha256: createHash("sha256").update(dataB64).digest("hex") };
221
+ return digest({ scope, native: input, args, authority, background });
222
+ });
212
223
  return background
213
224
  ? supervisor.start(request, hash, background.retainUntilMs, signal)
214
225
  : supervisor.execute(request, hash, signal);
@@ -221,15 +232,23 @@ export async function createLocalOperationBackend(options, dependencies, host) {
221
232
  opts.maxBytes < 0 ||
222
233
  opts.maxBytes > 16 * 1024 * 1024)
223
234
  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;
235
+ return timed("readFile", "total", async () => {
236
+ const result = (await run({ method: "readFile", path, maxBytes: opts.maxBytes }, opts.signal));
237
+ return result
238
+ ? timed("readFile", "encode", () => ({
239
+ data: Buffer.from(result.dataB64, "base64"),
240
+ truncated: result.truncated,
241
+ }))
242
+ : null;
243
+ });
228
244
  },
229
245
  writeFile: async (path, data, signal) => {
230
246
  if (data.byteLength > 16 * 1024 * 1024)
231
247
  throw new SandboxScopeDeniedError("Native write exceeds bounded transport");
232
- await run({ method: "writeFile", path, dataB64: Buffer.from(data).toString("base64") }, signal);
248
+ await timed("writeFile", "total", async () => {
249
+ const dataB64 = timed("writeFile", "encode", () => Buffer.from(data).toString("base64"));
250
+ await run({ method: "writeFile", path, dataB64 }, signal);
251
+ });
233
252
  },
234
253
  stat: (path, signal) => run({ method: "stat", path }, signal),
235
254
  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;
@@ -45,6 +56,12 @@ export interface SupervisorOptions {
45
56
  * the entry stays unknown and is never resumed.
46
57
  */
47
58
  reapOrphan?: (identity: TrustedLaunchIdentity) => void;
59
+ /**
60
+ * The most completed native read bytes kept in memory for retries (default 64 MiB). Past it the
61
+ * oldest reads give their bytes up and their retry reports an unknown outcome, as after a
62
+ * restart.
63
+ */
64
+ retainedReadBytes?: number;
48
65
  }
49
66
  /** What a supervisor still owns: work that a drain must see settle before it disconnects. */
50
67
  export interface SupervisorOwnership {
@@ -89,8 +106,14 @@ export declare class MacOperationSupervisor {
89
106
  private controlFile;
90
107
  private recoverControl;
91
108
  private persistControl;
109
+ /**
110
+ * Keeps the completed read bytes held for retries within {@link SupervisorOptions.retainedReadBytes}:
111
+ * the oldest reads (admission order) give their bytes up first.
112
+ */
113
+ private boundRetainedReads;
92
114
  private serial;
93
115
  private persist;
116
+ private persistNow;
94
117
  private expireRetained;
95
118
  private validate;
96
119
  private admit;
@@ -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 &&
@@ -613,7 +661,7 @@ export class MacOperationSupervisor {
613
661
  async execute(request, hash, signal) {
614
662
  const { entry, fresh } = await this.admit(request, hash, this.now() + 60000, signal);
615
663
  if (!fresh) {
616
- if (entry.state === "completed")
664
+ if (entry.state === "completed" && !isOmittedRead(entry.result))
617
665
  return entry.result ?? null;
618
666
  throw new SandboxOperationOutcomeUnknownError("Consumed operation outcome is unknown");
619
667
  }
@@ -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
+ }
@@ -756,13 +756,31 @@ function request(o) {
756
756
  validated.limits = { mode: "sandbox" };
757
757
  // Reuse v2's pure value guards; inserted mode is never returned or used as authority.
758
758
  parseLegacyDeviceFrame(JSON.stringify({ type: "req", id, op: native, args: validated, deadlineMs }), "kernel");
759
- if (native === "writeFile" &&
760
- (typeof a.dataB64 !== "string" ||
761
- !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(a.dataB64)))
759
+ if (native === "writeFile" && (typeof a.dataB64 !== "string" || !isBase64(a.dataB64)))
762
760
  throw new DeviceProtocolError("Invalid base64 payload");
763
761
  }
764
762
  return freeze({ type: "req", id, op: op, args: a, deadlineMs });
765
763
  }
764
+ /**
765
+ * Padded standard base64: whole quartets of `A-Z a-z 0-9 + /`, the last one possibly ending in
766
+ * `=` or `==`. One linear pass: a regex with a repeated group exhausts the engine's backtracking
767
+ * stack on payloads of a few megabytes.
768
+ */
769
+ function isBase64(value) {
770
+ if (value.length % 4 !== 0)
771
+ return false;
772
+ const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
773
+ for (let i = 0; i < value.length - padding; i++) {
774
+ const c = value.charCodeAt(i);
775
+ if (!((c >= 65 && c <= 90) ||
776
+ (c >= 97 && c <= 122) ||
777
+ (c >= 48 && c <= 57) ||
778
+ c === 43 ||
779
+ c === 47))
780
+ return false;
781
+ }
782
+ return true;
783
+ }
766
784
  /** Strictly parses one protocol 3 frame; throws {@link DeviceProtocolError}. */
767
785
  export function parseDeviceFrame(raw, from, maxFrameBytes) {
768
786
  if (maxFrameBytes !== undefined &&
@@ -900,7 +918,7 @@ export function parseOperationResult(op, result, request) {
900
918
  if (integer(o.offset) !== offset ||
901
919
  typeof o.dataB64 !== "string" ||
902
920
  o.dataB64.length > 87384 ||
903
- !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(o.dataB64))
921
+ !isBase64(o.dataB64))
904
922
  throw new DeviceProtocolError("Invalid output range or base64");
905
923
  const decoded = atob(o.dataB64);
906
924
  if (btoa(decoded) !== o.dataB64 ||
@@ -41,9 +41,10 @@ export interface HookScope {
41
41
  * `WebFetch` tool, `review` is the command-review classifier's call (`review` purpose, no run
42
42
  * step; absent = no classifier), `suggestion` is the prompt suggestion side request after a
43
43
  * completed web run (`runId` the run, `step` 0, `attempt` 1; a denial skips it and is recorded only
44
- * in the audit log).
44
+ * in the audit log), `vision` is the call that reads an image for a model without vision, made by
45
+ * the `Read` tool (also for a pasted image, read by its `file_id`; the `vision` purpose's model).
45
46
  */
46
- export type ModelCallPurpose = "step" | "compaction" | "title" | "web_fetch" | "review" | "image" | "suggestion";
47
+ export type ModelCallPurpose = "step" | "compaction" | "title" | "web_fetch" | "review" | "image" | "vision" | "suggestion";
47
48
  /**
48
49
  * What a reported or requested model call was for: the {@link ModelCallPurpose} values, or
49
50
  * `embedding` for an embedding call an extension made through `ctx.models` (`usage.report`, and
@@ -91,7 +92,7 @@ export type HookModelRequest = Omit<ModelRequest, "messages"> & {
91
92
  * denial skips the title and is recorded only in the audit log), once for each `WebFetch`
92
93
  * extraction call (`purpose: "web_fetch"`) and once for each prompt suggestion call
93
94
  * (`purpose: "suggestion"`, `step` 0, `attempt` 1; a denial skips the suggestion and is recorded
94
- * only in the audit log).
95
+ * only in the audit log) and once for each vision call (`purpose: "vision"`).
95
96
  * `request` is the request as sent, except that images and documents are placeholders
96
97
  * ({@link HookMediaPlaceholder}): no media bytes, no attachment ids.
97
98
  */
@@ -1,4 +1,4 @@
1
- export declare const SDK_VERSION = "0.1.0-rc.36";
1
+ export declare const SDK_VERSION = "0.1.0-rc.37";
2
2
  export * from "./agent-template.js";
3
3
  export * from "./bootstrap.js";
4
4
  export * from "./cards.js";
@@ -1,4 +1,4 @@
1
- export const SDK_VERSION = "0.1.0-rc.36";
1
+ export const SDK_VERSION = "0.1.0-rc.37";
2
2
  export * from "./agent-template.js";
3
3
  export * from "./bootstrap.js";
4
4
  export * from "./cards.js";
@@ -69,7 +69,7 @@ export interface ModelInfo {
69
69
  * Whether `document` blocks are accepted (default false). Images are governed by `vision`. When
70
70
  * the model does not support them the kernel replaces media blocks with English text
71
71
  * placeholders
72
- * (e.g. `[Attached image "<name>" — this model cannot view images.]`; `text/*` documents are
72
+ * (e.g. `[Attached image "<name>" — this model cannot view images. Read with file_id <id> sends it to the organization's vision model, if one is set.]`; `text/*` documents are
73
73
  * inlined as truncated text instead),
74
74
  * and never sends the bytes to it.
75
75
  */
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@capybara-hq/plugin-sdk",
3
- "version": "0.1.0-rc.36",
3
+ "version": "0.1.0-rc.37",
4
4
  "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {