@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.
- package/dist/exec/mac-operation-backend.js +25 -6
- package/dist/exec/native-helper-client.js +10 -2
- package/dist/exec/operation-supervisor.d.ts +24 -1
- package/dist/exec/operation-supervisor.js +50 -2
- package/dist/exec/operation-worker.js +3 -0
- package/dist/exec/transfer-timing.d.ts +16 -0
- package/dist/exec/transfer-timing.js +26 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +22 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +4 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/runtime-manifest.json +1 -1
- package/package.json +2 -2
|
@@ -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
|
-
|
|
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
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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
|
|
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
|
-
|
|
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 = {
|
|
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
|
-
|
|
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
|
*/
|
|
@@ -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
|
*/
|