@moxxy/plugin-computer-control 0.41.2 → 0.42.0

package/dist/contract/tools.js

@@ -0,0 +1,195 @@
+import { OF_THE_FOCUS, pointsAtFocus, wordsIn } from '@moxxy/jev';
+import { z } from 'zod';
+import { parseKeyCombo } from './keys.js';
+const coordinate = z.number().finite().nonnegative();
+/** A chord string checked by the xdotool parser, plus an optional rule on the parsed chord. */
+const chord = (rule = () => undefined) => z.string().max(64).superRefine((value, ctx) => {
+    let problem;
+    try {
+        problem = rule(parseKeyCombo(value));
+    }
+    catch (error) {
+        problem = error.message;
+    }
+    if (problem)
+        ctx.addIssue({ code: 'custom', message: problem });
+});
+/** Field schemas without defaults; each action decides what is required, optional or defaulted. */
+const fields = {
+    element_index: z.number().int().nonnegative()
+        .describe('Index of an element ([N]) in the latest computer_get_app_state of this app. Prefer it over coordinates.'),
+    x: coordinate.describe('Horizontal pixel in the latest screenshot of this app, from its left edge. Give together with y.'),
+    y: coordinate.describe('Vertical pixel in the latest screenshot of this app, from its top edge. Give together with x.'),
+    mouse_button: z.enum(['left', 'right', 'middle']),
+    click_count: z.number().int().min(1).max(3),
+    modifiers: chord((combo) => combo.key === null ? undefined : 'modifiers only, e.g. "shift" or "cmd+shift"')
+        .describe('Modifier keys held during the click, e.g. "shift" or "cmd+alt".'),
+    text: z.string().min(1).max(20_000),
+    key: chord().describe('One chord in xdotool syntax: "Return", "Tab", "Escape", "BackSpace", "Delete" (forward delete), "Up", "Page_Down", "F5", "KP_0", "super+c" (super = Command on macOS, Windows key on Windows, Super on Linux), "ctrl+shift+Tab".'),
+    repeat: z.number().int().min(1).max(100),
+    direction: z.enum(['up', 'down', 'left', 'right']),
+    pages: z.number().min(0.1).max(50).describe('How far to scroll, in visible pages.'),
+    value: z.string().max(100_000),
+    secondary_action: z.string().min(1).max(64).describe('An action listed for this element in the app state, e.g. "AXShowMenu". Never guess one.'),
+};
+const app = z.string().min(1).max(512)
+    .describe('App display name or bundle identifier (macOS), or app id from computer_list_apps (Windows, Linux).');
+export function resolveTarget(input) {
+    if (input.element_index !== undefined)
+        return { kind: 'element', index: input.element_index };
+    if (input.x !== undefined && input.y !== undefined)
+        return { kind: 'point', x: input.x, y: input.y };
+    return { kind: 'focused' };
+}
+function checkTarget(required) {
+    return (input, ctx) => {
+        if ((input.x === undefined) !== (input.y === undefined)) {
+            ctx.addIssue({ code: 'custom', path: [input.x === undefined ? 'x' : 'y'], message: 'x and y go together' });
+            return;
+        }
+        if (required && input.element_index === undefined && input.x === undefined) {
+            ctx.addIssue({ code: 'custom', message: `Give exactly one target: element_index, or x and y${required ? '' : ' (or neither for the focused element)'}` });
+        }
+    };
+}
+const target = { element_index: fields.element_index.optional(), x: fields.x.optional(), y: fields.y.optional() };
+const define = (shape, rule) => ({ shape, target: rule });
+const targeted = (shape, rule) => define({ ...target, ...shape }, rule);
+/**
+ * Models fill every field of a tool. null, "" and a 0,0 point are filler; a real point sent next to an element is
+ * where the model looked, so the point is the target (a control under it is still pressed through accessibility).
+ */
+function dropFiller(input, optionalTarget = false) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return input;
+    const kept = Object.fromEntries(Object.entries(input).filter(([, value]) => value !== null));
+    for (const name of ['modifiers', 'window_id'])
+        if (kept[name] === '')
+            delete kept[name];
+    const zeroPoint = kept.x === 0 && kept.y === 0;
+    const realPoint = kept.x !== undefined && kept.y !== undefined && !zeroPoint;
+    // The window itself (index 0) is no target for typing or keys, so all zeros there mean the focused element.
+    if (realPoint || (optionalTarget && kept.element_index === 0))
+        delete kept.element_index;
+    if (zeroPoint && (kept.element_index !== undefined || optionalTarget)) {
+        delete kept.x;
+        delete kept.y;
+    }
+    return kept;
+}
+function build(shape, rule) {
+    const object = z.object(shape).strict();
+    return z.preprocess((input) => dropFiller(input, rule === 'optional'), rule ? object.superRefine(checkTarget(rule === 'required')) : object);
+}
+/** Actions on one app, without the `app` field. */
+const actions = {
+    click: targeted({ mouse_button: fields.mouse_button.default('left'), click_count: fields.click_count.default(1), modifiers: fields.modifiers.optional() }, 'required'),
+    type_text: define({ element_index: fields.element_index.optional(), text: fields.text }, 'optional'),
+    press_key: define({ key: fields.key, repeat: fields.repeat.default(1) }),
+    scroll: targeted({ direction: fields.direction, pages: fields.pages.default(1) }, 'required'),
+    drag: define({
+        from_x: coordinate.describe('Where the button goes down: horizontal pixel in the latest screenshot of this app.'), from_y: coordinate,
+        to_x: coordinate.describe('Where the button comes up.'), to_y: coordinate,
+    }),
+    set_value: define({ element_index: fields.element_index, value: fields.value }),
+    perform_secondary_action: define({ element_index: fields.element_index, secondary_action: fields.secondary_action }),
+};
+export const actionNames = Object.keys(actions);
+/** The single tool for an action: the same fields with the target `app` first. */
+const onApp = (name) => build({ app, ...actions[name].shape }, actions[name].target);
+/** One step of computer_run: what to do, the element in words, and what must show afterwards. */
+export const runStepShape = z.object({
+    do: z.enum(['click', 'type', 'set_value', 'key', 'scroll']),
+    target: z.string().min(1).max(300).optional()
+        .describe('The element in words, the way it reads on screen: its label and kind, and where it is when that matters ("the Export button", "the file name field of the dialog"). Needed for click, set_value and scroll; leave it out of type to type into the focus. A key goes to the focus and takes none.'),
+    text: z.string().max(20_000).optional().describe('The exact text for type and set_value.'),
+    key: chord().optional().describe('The chord for key, in xdotool syntax.'),
+    direction: fields.direction.optional().describe('For scroll.'),
+    expect: z.string().min(1).max(300).optional()
+        .describe('What the window shows once this step worked ("an export dialog is open"). The step is checked against it and tried another way when it does not hold.'),
+}).strict();
+const needs = {
+    click: ['target'], type: ['text'], set_value: ['target', 'text'], key: ['key'], scroll: ['target', 'direction'],
+};
+/** A key goes to the focus, so it has no target: one found for it would only be another way to press the key again. */
+const uses = {
+    click: ['target'], type: ['target', 'text'], set_value: ['target', 'text'], key: ['key'], scroll: ['target', 'direction'],
+};
+export { pointsAtFocus, wordsIn };
+/**
+ * A strict provider fills every field of every step: null and "" are filler, and so is any field the step's kind
+ * does not use, and a target of typing that names nothing but the focus, where typing without a target goes.
+ * An empty text for set_value is kept; it clears the field.
+ */
+function dropStepFiller(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input))
+        return input;
+    const step = input;
+    const used = uses[step.do];
+    const focusOnly = step.do === 'type' && typeof step.target === 'string' && pointsAtFocus(step.target)
+        && wordsIn(step.target).every((word) => OF_THE_FOCUS.has(word));
+    return Object.fromEntries(Object.entries(step).filter(([name, value]) => value !== null && (value !== '' || (name === 'text' && step.do === 'set_value'))
+        && (used === undefined || name === 'do' || name === 'expect' || used.includes(name))
+        && !(name === 'target' && focusOnly)));
+}
+const runStep = z.preprocess(dropStepFiller, runStepShape.superRefine((step, ctx) => {
+    for (const field of needs[step.do]) {
+        if (step[field] === undefined || (field === 'text' && step.do === 'type' && step.text === ''))
+            ctx.addIssue({ code: 'custom', path: [field], message: `${step.do} needs ${field}` });
+    }
+}));
+const region = z.array(z.number().int().nonnegative()).length(4).refine(([x0 = 0, y0 = 0, x1 = 0, y1 = 0]) => x1 > x0 && y1 > y0, 'region must be [x0, y0, x1, y1] with x1 > x0 and y1 > y0')
+    .describe('[x0, y0, x1, y1] in the coordinate frame of the latest screenshot.');
+const AFTER = ' Returns the technical outcome and the fresh app state; check that the intended change happened.';
+export const computerTools = {
+    computer_status: {
+        description: 'Report whether Computer Use can work on this computer and which system permission is missing. Call it when a tool reports missing permissions; open_settings shows the user the settings pane to allow one.',
+        input: z.object({ open_settings: z.enum(['accessibility', 'screen_recording']).optional().describe('Open the system settings pane where the user allows this permission.') }).strict(),
+    },
+    computer_list_apps: {
+        description: 'List installed and running applications (and their windows on Windows) with the identifier to pass as `app`. No side effects.',
+        input: z.object({ query: z.string().max(256).optional().describe('Case-insensitive filter on name and identifier.'), limit: z.number().int().min(1).max(200).default(50) }).strict(),
+    },
+    computer_request_access: {
+        description: 'Ask the user, in one dialog, to let you control a set of applications for this conversation. Required before the single tools act on an app; computer_run asks for its own app. Browsers default to read-only and terminals to click-only; ask here for full control of them, for the clipboard and for system chords.',
+        input: z.object({
+            apps: z.array(app).min(1).max(32),
+            reason: z.string().min(1).max(500).describe('One sentence for the dialog: the task, not the mechanism.'),
+            clipboard_read: z.boolean().optional(),
+            clipboard_write: z.boolean().optional(),
+            system_key_combos: z.boolean().optional().describe('Also allow system chords such as quit, switch app or lock screen.'),
+            full_access: z.array(app).max(32).optional()
+                .describe('Apps from `apps` that need full control although their kind is restricted by default (browsers read-only, terminals click-only). The user sees this list before approving.'),
+        }).strict().refine((input) => (input.full_access ?? []).every((name) => input.apps.includes(name)), {
+            message: 'full_access may only name apps listed in apps', path: ['full_access'],
+        }),
+    },
+    computer_get_app_state: {
+        description: 'Observe one app: its focused window as indexed accessibility elements plus a screenshot. Launches the app in the background if needed and waits for it to settle. Returns only what changed since your last look unless disable_diff is true. Call it before the first action; every action returns the fresh state itself, so look again only when that is not enough.',
+        input: z.preprocess((input) => dropFiller(input), z.object({
+            app,
+            window_id: z.string().min(1).max(160).optional().describe('Windows only: a window from computer_list_apps. Leave it out for the app\'s main window.'),
+            disable_diff: z.boolean().default(false),
+        }).strict()),
+    },
+    computer_click: { description: `Click an element by element_index (preferred) or a point in the latest screenshot.${AFTER}`, input: onApp('click') },
+    computer_type_text: { description: `Type text into the focused element of the app, or into element_index. On a canvas or a spreadsheet cell, click the place first, then type with no element_index.${AFTER}`, input: onApp('type_text') },
+    computer_press_key: { description: `Press one key or chord in the app, in xdotool syntax.${AFTER}`, input: onApp('press_key') },
+    computer_scroll: { description: `Scroll an element or the content under a point.${AFTER}`, input: onApp('scroll') },
+    computer_drag: { description: `Drag with the left button from one screenshot point to another: moving or trimming clips on a timeline, sliders, selections. The grab point decides what happens (a clip's edge trims, its body moves), so aim it exactly.${AFTER}`, input: onApp('drag') },
+    computer_set_value: { description: `Set the value of an editable element directly (text fields, sliders, steppers).${AFTER}`, input: onApp('set_value') },
+    computer_perform_secondary_action: { description: `Run an accessibility action an element lists besides a click (show menu, expand, increment, cancel).${AFTER}`, input: onApp('perform_secondary_action') },
+    computer_run: {
+        description: 'Run several steps on one app in a row, without a round trip per step. Describe each element in words; the element is found on the live window, also on a screen you have not seen yet, each `expect` is checked, and a step that does not work is tried another way. Stops at the first step that cannot be done and returns what was done plus the fresh app state. Use it whenever the next steps are known; use the single tools for work by x and y. On an app not granted yet, approving this call grants the app for the conversation at its default level (browsers read-only, terminals click-only). Steps that send keys or text into a browser or terminal are refused at that level: call computer_request_access with full_access for it first, in the same response.',
+        input: z.object({
+            app,
+            goal: z.string().min(1).max(500).describe('What these steps achieve, in one sentence. It tells similar elements apart.'),
+            steps: z.array(runStep).min(1).max(30),
+        }).strict(),
+    },
+    computer_zoom: {
+        description: 'Look closer at a region of the latest screenshot of an app, to read small text or find an exact edge. Reading aid only: coordinates keep referring to the screenshot, never to the zoomed image.',
+        input: z.object({ app, region }).strict(),
+    },
+};
+//# sourceMappingURL=tools.js.map

package/dist/contract/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/contract/tools.ts"],"names":[],"mappings":"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"}

package/dist/contract/untrusted.d.ts

@@ -0,0 +1,3 @@
+/** Fence text read from an application so the model treats it as data, never as instructions. */
+export declare function wrapUntrusted(text: string, app: string): string;
+//# sourceMappingURL=untrusted.d.ts.map

package/dist/contract/untrusted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted.d.ts","sourceRoot":"","sources":["../../src/contract/untrusted.ts"],"names":[],"mappings":"AAEA,iGAAiG;AACjG,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/D"}

package/dist/contract/untrusted.js

@@ -0,0 +1,8 @@
+const CLOSING_TAG = /<\/(app_content)(\s*)>/gi;
+/** Fence text read from an application so the model treats it as data, never as instructions. */
+export function wrapUntrusted(text, app) {
+    const attribute = app.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+    const body = text.replace(CLOSING_TAG, '<\\/$1$2>');
+    return `<app_content app="${attribute}" trust="untrusted">\n${body}\n</app_content>`;
+}
+//# sourceMappingURL=untrusted.js.map

package/dist/contract/untrusted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"untrusted.js","sourceRoot":"","sources":["../../src/contract/untrusted.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,GAAG,0BAA0B,CAAC;AAE/C,iGAAiG;AACjG,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC3F,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;IACpD,OAAO,qBAAqB,SAAS,yBAAyB,IAAI,kBAAkB,CAAC;AACvF,CAAC"}

package/dist/helper/artifact.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+declare const manifestSchema: (protocolVersion: number) => z.ZodObject<{
+    protocolVersion: z.ZodLiteral<number>;
+    /** Absent for Windows and macOS, which the architecture alone tells apart. */
+    os: z.ZodOptional<z.ZodLiteral<"linux">>;
+    architecture: z.ZodEnum<["x64", "arm64", "x86_64", "universal"]>;
+    sha256: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    sha256: string;
+    protocolVersion: number;
+    architecture: "x64" | "arm64" | "x86_64" | "universal";
+    os?: "linux" | undefined;
+}, {
+    sha256: string;
+    protocolVersion: number;
+    architecture: "x64" | "arm64" | "x86_64" | "universal";
+    os?: "linux" | undefined;
+}>;
+type Architecture = z.infer<ReturnType<typeof manifestSchema>>['architecture'];
+/**
+ * The digest a manifest records. A Windows or Linux executable is hashed whole. A Mach-O
+ * is hashed without its code signatures, because packaging the desktop app signs
+ * every executable again after the manifest was written; macOS itself refuses to
+ * run code whose signature does not match.
+ */
+export declare function helperDigest(bytes: Buffer): string;
+export declare function validateHelperArtifact(bytes: Buffer, manifest: unknown, protocolVersion: number): void;
+export declare function verifyHelperArtifact(executable: string, protocolVersion: number): Promise<void>;
+/** Written by the native build next to the executable it just produced. */
+export declare function writeHelperManifest(executable: string, manifest: {
+    protocolVersion: number;
+    architecture: Architecture;
+    os?: 'linux';
+}): Promise<void>;
+/**
+ * Why a helper cannot be used, known without reading the executable: decides
+ * which tools a plugin offers. The full check runs before every launch.
+ */
+export declare function helperProblem(executable: string, protocolVersion: number): string | undefined;
+export {};
+//# sourceMappingURL=artifact.d.ts.map

package/dist/helper/artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.d.ts","sourceRoot":"","sources":["../../src/helper/artifact.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,cAAc,GAAI,iBAAiB,MAAM;;IAE7C,8EAA8E;;;;;;;;;;;;;;EAIrE,CAAC;AACZ,KAAK,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;AA4E/E;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,CAMtG;AAgCD,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOrG;AAED,2EAA2E;AAC3E,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE;IAAE,eAAe,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5J;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAc7F"}

package/dist/helper/artifact.js

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+import { constants, existsSync, readFileSync } from 'node:fs';
+import { lstat, open, rename, writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+const manifestSchema = (protocolVersion) => z.object({
+    protocolVersion: z.literal(protocolVersion),
+    /** Absent for Windows and macOS, which the architecture alone tells apart. */
+    os: z.literal('linux').optional(),
+    architecture: z.enum(['x64', 'arm64', 'x86_64', 'universal']),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/),
+}).strict();
+const MACH_O_64 = 0xfeedfacf;
+const MACH_O_FAT = 0xcafebabe;
+const CPU = { arm64: 0x0100000c, x86_64: 0x01000007 };
+function assertWindowsX64(bytes) {
+    if (bytes.length < 64 || bytes.toString('ascii', 0, 2) !== 'MZ')
+        throw new Error('Invalid Computer Use executable');
+    const offset = bytes.readUInt32LE(60);
+    if (offset > bytes.length - 6 || bytes.toString('ascii', offset, offset + 4) !== 'PE\0\0' || bytes.readUInt16LE(offset + 4) !== 0x8664) {
+        throw new Error('Computer Use requires a Windows x64 executable');
+    }
+}
+const ELF_MACHINE = { x64: 62, arm64: 183 };
+function assertLinux(bytes, architecture) {
+    const machine = ELF_MACHINE[architecture];
+    // 64-bit, little-endian ELF for the named machine.
+    const matches = machine !== undefined && bytes.length >= 20 && bytes.toString('latin1', 0, 4) === '\x7fELF'
+        && bytes[4] === 2 && bytes[5] === 1 && bytes.readUInt16LE(18) === machine;
+    if (!matches)
+        throw new Error(`Computer Use requires a Linux ${architecture} executable`);
+}
+function assertMacOS(bytes, architecture) {
+    const cpus = (machOSlices(bytes) ?? []).map(({ cpu }) => cpu);
+    const required = architecture === 'universal' ? [CPU.arm64, CPU.x86_64] : [CPU[architecture]];
+    if (!required.every((cpu) => cpus.includes(cpu)))
+        throw new Error(`Computer Use requires a macOS ${architecture} executable`);
+}
+const LC_SEGMENT_64 = 0x19;
+const LC_CODE_SIGNATURE = 0x1d;
+const invalid = () => new Error('Invalid Computer Use executable');
+/** One Mach-O slice without its code signature, with the fields signing rewrites set to zero. */
+function unsignedSlice(slice) {
+    if (slice.length < 32 || slice.readUInt32LE(0) !== MACH_O_64)
+        throw invalid();
+    const copy = Buffer.from(slice);
+    const commands = copy.readUInt32LE(16);
+    if (32 + copy.readUInt32LE(20) > copy.length)
+        throw invalid();
+    let end = copy.length;
+    let offset = 32;
+    for (let index = 0; index < commands; index++) {
+        if (offset + 8 > copy.length)
+            throw invalid();
+        const command = copy.readUInt32LE(offset);
+        const size = copy.readUInt32LE(offset + 4);
+        if (size < 8 || offset + size > copy.length)
+            throw invalid();
+        if (command === LC_CODE_SIGNATURE && size >= 16) {
+            end = Math.min(end, copy.readUInt32LE(offset + 8));
+            copy.fill(0, offset + 8, offset + 16);
+        }
+        else if (command === LC_SEGMENT_64 && size >= 72 && copy.toString('latin1', offset + 8, offset + 24).replace(/\0+$/, '') === '__LINKEDIT') {
+            // The signature is the tail of __LINKEDIT, so its sizes move with it.
+            copy.fill(0, offset + 32, offset + 40);
+            copy.fill(0, offset + 48, offset + 56);
+        }
+        offset += size;
+    }
+    return copy.subarray(0, end);
+}
+/** The slices of a thin or fat Mach-O with their CPU type; `undefined` when the bytes are not Mach-O. */
+function machOSlices(bytes) {
+    if (bytes.length < 8)
+        return undefined;
+    if (bytes.readUInt32LE(0) === MACH_O_64)
+        return [{ cpu: bytes.readUInt32LE(4), slice: bytes }];
+    if (bytes.readUInt32BE(0) !== MACH_O_FAT)
+        return undefined;
+    const count = bytes.readUInt32BE(4);
+    if (count > 16 || 8 + count * 20 > bytes.length)
+        throw invalid();
+    return Array.from({ length: count }, (_, index) => {
+        const entry = 8 + index * 20;
+        const start = bytes.readUInt32BE(entry + 8);
+        const size = bytes.readUInt32BE(entry + 12);
+        if (start + size > bytes.length)
+            throw invalid();
+        return { cpu: bytes.readUInt32BE(entry), slice: bytes.subarray(start, start + size) };
+    });
+}
+/**
+ * The digest a manifest records. A Windows or Linux executable is hashed whole. A Mach-O
+ * is hashed without its code signatures, because packaging the desktop app signs
+ * every executable again after the manifest was written; macOS itself refuses to
+ * run code whose signature does not match.
+ */
+export function helperDigest(bytes) {
+    const hash = createHash('sha256');
+    const slices = machOSlices(bytes);
+    if (!slices)
+        return hash.update(bytes).digest('hex');
+    for (const { cpu, slice } of slices) {
+        const header = Buffer.alloc(4);
+        header.writeUInt32BE(cpu);
+        // An empty fat entry (synthetic headers in tests) has no code to hash.
+        hash.update(header).update(slice.length === 0 ? slice : unsignedSlice(slice));
+    }
+    return hash.digest('hex');
+}
+export function validateHelperArtifact(bytes, manifest, protocolVersion) {
+    const expected = manifestSchema(protocolVersion).parse(manifest);
+    if (expected.os === 'linux')
+        assertLinux(bytes, expected.architecture);
+    else if (expected.architecture === 'x64')
+        assertWindowsX64(bytes);
+    else
+        assertMacOS(bytes, expected.architecture);
+    if (helperDigest(bytes) !== expected.sha256)
+        throw new Error('Computer Use executable checksum mismatch');
+}
+// POSIX-only; Node leaves it undefined on Windows.
+const O_NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+/**
+ * Read a regular file no larger than `limit`, checking the open handle rather
+ * than the path so the bytes that are validated are the bytes that were
+ * measured. A `stat` followed by `readFile` can be repointed in between, which
+ * would let an oversized file through the size guard.
+ */
+async function readBounded(file, limit) {
+    if (O_NOFOLLOW === 0 && (await lstat(file)).isSymbolicLink()) {
+        throw new Error('Computer Use artifact exceeds size limit');
+    }
+    let handle;
+    try {
+        handle = await open(file, constants.O_RDONLY | O_NOFOLLOW);
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > limit)
+            throw new Error('Computer Use artifact exceeds size limit');
+        return await handle.readFile();
+    }
+    catch (error) {
+        // O_NOFOLLOW reports a symlink as ELOOP.
+        if (error.code === 'ELOOP') {
+            throw new Error('Computer Use artifact exceeds size limit');
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export async function verifyHelperArtifact(executable, protocolVersion) {
+    const manifestPath = executable + '.json';
+    const [bytes, manifest] = await Promise.all([
+        readBounded(executable, 32_000_000),
+        readBounded(manifestPath, 4096),
+    ]);
+    validateHelperArtifact(bytes, JSON.parse(manifest.toString('utf8')), protocolVersion);
+}
+/** Written by the native build next to the executable it just produced. */
+export async function writeHelperManifest(executable, manifest) {
+    const sha256 = helperDigest(await readBounded(executable, 32_000_000));
+    const temporary = `${executable}.json.tmp`;
+    await writeFile(temporary, JSON.stringify({ ...manifest, sha256 }));
+    await rename(temporary, `${executable}.json`);
+}
+/**
+ * Why a helper cannot be used, known without reading the executable: decides
+ * which tools a plugin offers. The full check runs before every launch.
+ */
+export function helperProblem(executable, protocolVersion) {
+    if (!existsSync(executable))
+        return 'The Computer Use helper is missing.';
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(`${executable}.json`, 'utf8'));
+    }
+    catch {
+        return 'The Computer Use helper has no readable manifest.';
+    }
+    const found = z.object({ protocolVersion: z.number().int() }).safeParse(manifest);
+    if (!found.success)
+        return 'The Computer Use helper has no readable manifest.';
+    if (found.data.protocolVersion !== protocolVersion) {
+        return `The Computer Use helper speaks protocol ${found.data.protocolVersion}; this version needs ${protocolVersion}.`;
+    }
+    return undefined;
+}
+//# sourceMappingURL=artifact.js.map

package/dist/helper/artifact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact.js","sourceRoot":"","sources":["../../src/helper/artifact.ts"],"names":[],"mappings":"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"}

package/dist/helper/protocol.d.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+/** Per-frame byte ceiling shared by every native helper. */
+export declare const MAX_FRAME_BYTES = 3000000;
+export declare const controlCommandSchema: z.ZodEnum<["pause", "resume", "stop", "takeover"]>;
+/** The first helper protocol that understands `takeover`; older helpers are paused instead. */
+export declare const TAKEOVER_PROTOCOL_VERSION = 5;
+export declare const controlStates: readonly ["idle", "background", "foreground", "waiting_for_focus", "paused_by_user", "recovering", "stopped", "failed"];
+/** A request-correlated state change; the transport suspends the request deadline while waiting. */
+export declare const controlStateSchemaFor: (version: number) => z.ZodObject<{
+    version: z.ZodLiteral<number>;
+    event: z.ZodLiteral<"control_state">;
+    id: z.ZodString;
+    state: z.ZodEnum<["idle", "background", "foreground", "waiting_for_focus", "paused_by_user", "recovering", "stopped", "failed"]>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    state: "background" | "failed" | "idle" | "foreground" | "waiting_for_focus" | "paused_by_user" | "recovering" | "stopped";
+    version: number;
+    event: "control_state";
+}, {
+    id: string;
+    state: "background" | "failed" | "idle" | "foreground" | "waiting_for_focus" | "paused_by_user" | "recovering" | "stopped";
+    version: number;
+    event: "control_state";
+}>;
+export type ControlState = z.infer<ReturnType<typeof controlStateSchemaFor>>;
+export declare const responseSchemaFor: (version: number) => z.ZodDiscriminatedUnion<"ok", [z.ZodObject<{
+    version: z.ZodLiteral<number>;
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    version: number;
+    ok: true;
+    result?: unknown;
+}, {
+    id: string;
+    version: number;
+    ok: true;
+    result?: unknown;
+}>, z.ZodObject<{
+    version: z.ZodLiteral<number>;
+    id: z.ZodString;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        code: string;
+        message: string;
+    }, {
+        code: string;
+        message: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    version: number;
+    error: {
+        code: string;
+        message: string;
+    };
+    ok: false;
+}, {
+    id: string;
+    version: number;
+    error: {
+        code: string;
+        message: string;
+    };
+    ok: false;
+}>]>;
+/** A byte-bounded decoder; UTF-8 is decoded only after a complete frame arrives. */
+export declare class JsonLineDecoder {
+    private readonly limit;
+    private pending;
+    constructor(limit: number);
+    push(bytes: Buffer): unknown[];
+    finish(): void;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/helper/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/helper/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4DAA4D;AAC5D,eAAO,MAAM,eAAe,UAAY,CAAC;AAGzC,eAAO,MAAM,oBAAoB,oDAAkD,CAAC;AACpF,+FAA+F;AAC/F,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,aAAa,yHAA0H,CAAC;AAErJ,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM;;;;;;;;;;;;;;;EAE1C,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC;AAE7E,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAI/C,CAAC;AAEH,oFAAoF;AACpF,qBAAa,eAAe;IAEd,OAAO,CAAC,QAAQ,CAAC,KAAK;IADlC,OAAO,CAAC,OAAO,CAAmB;gBACL,KAAK,EAAE,MAAM;IAE1C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;IAkB9B,MAAM,IAAI,IAAI;CAGf"}

package/dist/helper/protocol.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+/** Per-frame byte ceiling shared by every native helper. */
+export const MAX_FRAME_BYTES = 3_000_000;
+const idSchema = z.string().min(1).max(160);
+export const controlCommandSchema = z.enum(['pause', 'resume', 'stop', 'takeover']);
+/** The first helper protocol that understands `takeover`; older helpers are paused instead. */
+export const TAKEOVER_PROTOCOL_VERSION = 5;
+export const controlStates = ['idle', 'background', 'foreground', 'waiting_for_focus', 'paused_by_user', 'recovering', 'stopped', 'failed'];
+/** A request-correlated state change; the transport suspends the request deadline while waiting. */
+export const controlStateSchemaFor = (version) => z.object({
+    version: z.literal(version), event: z.literal('control_state'), id: idSchema, state: z.enum(controlStates),
+}).strict();
+export const responseSchemaFor = (version) => z.discriminatedUnion('ok', [
+    z.object({ version: z.literal(version), id: idSchema, ok: z.literal(true), result: z.unknown() }).strict(),
+    z.object({ version: z.literal(version), id: idSchema, ok: z.literal(false),
+        error: z.object({ code: z.string().max(80), message: z.string().max(2048) }).strict() }).strict(),
+]);
+/** A byte-bounded decoder; UTF-8 is decoded only after a complete frame arrives. */
+export class JsonLineDecoder {
+    limit;
+    pending = Buffer.alloc(0);
+    constructor(limit) {
+        this.limit = limit;
+    }
+    push(bytes) {
+        const frames = [];
+        let offset = 0;
+        while (offset < bytes.length) {
+            const newline = bytes.indexOf(10, offset);
+            const end = newline < 0 ? bytes.length : newline;
+            const part = bytes.subarray(offset, end);
+            if (this.pending.length + part.length > this.limit)
+                throw new Error('Computer Use protocol frame limit exceeded');
+            this.pending = Buffer.concat([this.pending, part]);
+            if (newline < 0)
+                break;
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(this.pending);
+            frames.push(JSON.parse(text));
+            this.pending = Buffer.alloc(0);
+            offset = newline + 1;
+        }
+        return frames;
+    }
+    finish() {
+        if (this.pending.length)
+            throw new Error('Computer Use protocol incomplete frame');
+    }
+}
+//# sourceMappingURL=protocol.js.map