@moxxy/plugin-computer-control 0.41.2 → 0.42.0

package/src/helper/artifact.ts

@@ -0,0 +1,182 @@
+import { createHash } from 'node:crypto';
+import { constants, existsSync, readFileSync } from 'node:fs';
+import { lstat, open, rename, writeFile } from 'node:fs/promises';
+import type { FileHandle } from 'node:fs/promises';
+import { z } from 'zod';
+
+const manifestSchema = (protocolVersion: number) => 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();
+type Architecture = z.infer<ReturnType<typeof manifestSchema>>['architecture'];
+
+const MACH_O_64 = 0xfeedfacf;
+const MACH_O_FAT = 0xcafebabe;
+const CPU = { arm64: 0x0100000c, x86_64: 0x01000007 } as const;
+
+function assertWindowsX64(bytes: Buffer): void {
+  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: Partial<Record<Architecture, number>> = { x64: 62, arm64: 183 };
+
+function assertLinux(bytes: Buffer, architecture: Architecture): void {
+  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: Buffer, architecture: Exclude<Architecture, 'x64'>): void {
+  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: Buffer): Buffer {
+  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: Buffer): Array<{ cpu: number; slice: Buffer }> | undefined {
+  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: Buffer): string {
+  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: Buffer, manifest: unknown, protocolVersion: number): void {
+  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: string, limit: number): Promise<Buffer> {
+  if (O_NOFOLLOW === 0 && (await lstat(file)).isSymbolicLink()) {
+    throw new Error('Computer Use artifact exceeds size limit');
+  }
+  let handle: FileHandle | undefined;
+  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 as NodeJS.ErrnoException).code === 'ELOOP') {
+      throw new Error('Computer Use artifact exceeds size limit');
+    }
+    throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+export async function verifyHelperArtifact(executable: string, protocolVersion: number): Promise<void> {
+  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: string, manifest: { protocolVersion: number; architecture: Architecture; os?: 'linux' }): Promise<void> {
+  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: string, protocolVersion: number): string | undefined {
+  if (!existsSync(executable)) return 'The Computer Use helper is missing.';
+  let manifest: unknown;
+  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;
+}

package/src/helper/protocol.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { JsonLineDecoder, responseSchemaFor } from './protocol.js';
+
+describe('bounded JSON lines', () => {
+  it('decodes split UTF-8 and multiple frames without losing bytes', () => {
+    const decoder = new JsonLineDecoder(128);
+    const bytes = Buffer.from('{"text":"żółć"}\n{}\n');
+    const result: unknown[] = [];
+    for (const byte of bytes) result.push(...decoder.push(Buffer.from([byte])));
+    expect(result).toEqual([{ text: 'żółć' }, {}]);
+  });
+  it('rejects oversize, malformed and incomplete messages', () => {
+    expect(() => new JsonLineDecoder(3).push(Buffer.from('1234'))).toThrow(/limit/);
+    expect(() => new JsonLineDecoder(100).push(Buffer.from('{bad}\n'))).toThrow();
+    const decoder = new JsonLineDecoder(100);
+    decoder.push(Buffer.from('{'));
+    expect(() => decoder.finish()).toThrow(/incomplete/);
+  });
+});
+
+describe('response envelope', () => {
+  it('accepts only the configured protocol version and a well-formed result or error', () => {
+    const response = responseSchemaFor(5);
+    expect(response.safeParse({ version: 5, id: '1', ok: true, result: {} }).success).toBe(true);
+    expect(response.safeParse({ version: 5, id: '1', ok: false, error: { code: 'x', message: 'y' } }).success).toBe(true);
+    expect(response.safeParse({ version: 4, id: '1', ok: true, result: {} }).success).toBe(false);
+    expect(response.safeParse({ version: 5, id: '1', ok: false }).success).toBe(false);
+  });
+});

package/src/helper/protocol.ts

@@ -0,0 +1,50 @@
+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'] as const;
+
+/** A request-correlated state change; the transport suspends the request deadline while waiting. */
+export const controlStateSchemaFor = (version: number) => z.object({
+  version: z.literal(version), event: z.literal('control_state'), id: idSchema, state: z.enum(controlStates),
+}).strict();
+export type ControlState = z.infer<ReturnType<typeof controlStateSchemaFor>>;
+
+export const responseSchemaFor = (version: number) => 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 {
+  private pending = Buffer.alloc(0);
+  constructor(private readonly limit: number) {}
+
+  push(bytes: Buffer): unknown[] {
+    const frames: unknown[] = [];
+    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(): void {
+    if (this.pending.length) throw new Error('Computer Use protocol incomplete frame');
+  }
+}

package/src/{windows → helper}/transport.test.ts

@@ -1,14 +1,19 @@
 import { describe, expect, it } from 'vitest';
-import { HelperTransport } from './transport.js';
+import { z } from 'zod';
+import { HelperTransport, type HelperEvent, type HelperTransportOptions } from './transport.js';
 
-// Real subprocesses exercise pipe framing/lifetime; these do not simulate Windows APIs.
+// Real subprocesses exercise pipe framing/lifetime; these do not simulate platform APIs.
+const helper = (script: string, options: Partial<HelperTransportOptions> = {}) =>
+  new HelperTransport(process.execPath, ['-e', script], { protocolVersion: 4, ...options });
 const peer = `process.stdin.once('data', bytes => {
   const request = JSON.parse(bytes.toString());
   process.stdout.write(JSON.stringify({version:4,id:request.id,ok:true,result:{received:request.method}})+'\\n');
 });`;
+const cursorEvent = z.object({ version: z.literal(4), event: z.literal('cursor'), x: z.number(), y: z.number() }).strict();
+
 describe('native helper transport', () => {
   it('reports the native panel Stop exit as cancellation, not a helper crash', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', "process.stdin.once('data', () => process.exit(20))"]);
+    const transport = helper("process.stdin.once('data', () => process.exit(20))");
     try {
       await expect(transport.request('click', {}, new AbortController().signal)).rejects.toThrow('Computer Use stopped by user');
       expect(transport.stoppedByUser).toBe(true);
@@ -17,21 +22,23 @@ describe('native helper transport', () => {
   });
   it('excludes explicit focus waiting from the active request timeout', async () => {
     const states: string[] = [];
-    const transport = new HelperTransport(process.execPath, ['-e', `process.stdin.once('data', bytes => {
+    // The budget also covers the helper's own start, which on a busy Windows
+    // runner outlasts 150 ms; the focus wait still outlasts the whole budget.
+    const transport = helper(`process.stdin.once('data', bytes => {
       const r=JSON.parse(bytes.toString());
       process.stdout.write(JSON.stringify({version:4,event:'control_state',id:r.id,state:'waiting_for_focus'})+'\\n');
       setTimeout(()=>{
         process.stdout.write(JSON.stringify({version:4,event:'control_state',id:r.id,state:'foreground'})+'\\n');
         process.stdout.write(JSON.stringify({version:4,id:r.id,ok:true,result:{delivered:false,status:'needs_observation'}})+'\\n');
-      },250);
-    });`], 150, state => states.push(state.state));
+      },1500);
+    });`, { timeoutMs: 1000, onEvent: (event) => { if (event.event === 'control_state') states.push(String(event.state)); } });
     try {
       expect(await transport.request('click', {}, new AbortController().signal)).toEqual({delivered:false,status:'needs_observation'});
       expect(states).toEqual(['waiting_for_focus','foreground']);
     } finally { await transport.close(); }
   });
   it('exchanges a correlated frame through real private pipes', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', peer]);
+    const transport = helper(peer);
     try {
       expect(await transport.request('status', {}, new AbortController().signal)).toEqual({ received: 'status' });
     } finally { await transport.close(); }
@@ -39,46 +46,66 @@ describe('native helper transport', () => {
   });
   it('cancels while focus waiting is suspended', async () => {
     const abort = new AbortController();
-    const transport = new HelperTransport(process.execPath, ['-e', `process.stdin.once('data', bytes => {
+    const transport = helper(`process.stdin.once('data', bytes => {
       const r=JSON.parse(bytes.toString());
       process.stdout.write(JSON.stringify({version:4,event:'control_state',id:r.id,state:'waiting_for_focus'})+'\\n');
       process.stdin.resume();
-    });`], 1000, () => abort.abort());
+    });`, { timeoutMs: 1000, onEvent: () => abort.abort() });
     await expect(transport.request('key', {}, abort.signal)).rejects.toThrow(/cancelled/);
     await transport.close();
     expect(transport.closed).toBe(true);
   });
   it('still times out after focus waiting ends without an operation response', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', `process.stdin.once('data', bytes => {
+    const transport = helper(`process.stdin.once('data', bytes => {
       const r=JSON.parse(bytes.toString());
       const state=s=>process.stdout.write(JSON.stringify({version:4,event:'control_state',id:r.id,state:s})+'\\n');
       state('waiting_for_focus');
       setTimeout(()=>{state('foreground');process.stdin.resume();},200);
-    });`], 150);
+    });`, { timeoutMs: 150 });
     await expect(transport.request('key', {}, new AbortController().signal)).rejects.toThrow(/timed out/);
     await transport.close();
   });
   it('rejects a control event for a different request', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', `process.stdin.once('data', () => {
+    const transport = helper(`process.stdin.once('data', () => {
       process.stdout.write(JSON.stringify({version:4,event:'control_state',id:'wrong',state:'waiting_for_focus'})+'\\n');
-    });`]);
+    });`);
     await expect(transport.request('key', {}, new AbortController().signal)).rejects.toThrow(/protocol/);
     await transport.close();
   });
+  it('keeps the helper error code on a refused request', async () => {
+    const transport = helper(`process.stdin.once('data', bytes => {
+      const request = JSON.parse(bytes.toString());
+      process.stdout.write(JSON.stringify({version:4,id:request.id,ok:false,error:{code:'tier_insufficient',message:'read only'}})+'\\n');
+      process.stdin.resume();
+    });`);
+    await expect(transport.request('act', {}, new AbortController().signal))
+      .rejects.toMatchObject({ name: 'HelperError', code: 'tier_insufficient', message: 'tier_insufficient: read only' });
+    expect(transport.closed).toBe(false);
+    await transport.close();
+  });
   it('rejects a mismatched protocol and permanently retires the peer', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', peer.replace('version:4', 'version:2')]);
+    const transport = helper(peer.replace('version:4', 'version:2'));
     await expect(transport.request('status', {}, new AbortController().signal)).rejects.toThrow(/protocol/i);
     await transport.close();
     expect(transport.closed).toBe(true);
   });
+  it('speaks the protocol version it was configured with', async () => {
+    const transport = new HelperTransport(process.execPath, ['-e', `process.stdin.once('data', bytes => {
+      const r=JSON.parse(bytes.toString());
+      process.stdout.write(JSON.stringify({version:5,id:r.id,ok:true,result:{sent:r.version}})+'\\n');
+    });`], { protocolVersion: 5 });
+    try {
+      expect(await transport.request('status', {}, new AbortController().signal)).toEqual({ sent: 5 });
+    } finally { await transport.close(); }
+  });
   it('times out without retrying an ambiguous input operation', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', 'process.stdin.resume()'], 40);
+    const transport = helper('process.stdin.resume()', { timeoutMs: 40 });
     await expect(transport.request('type', {}, new AbortController().signal)).rejects.toThrow(/not retried/);
     await expect(transport.request('type', {}, new AbortController().signal)).rejects.toThrow(/closed/);
     await transport.close();
   });
   it('cancels a real process and refuses already-cancelled requests', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', 'process.stdin.resume()']);
+    const transport = helper('process.stdin.resume()');
     const abort = new AbortController();
     const promise = transport.request('observe', {}, abort.signal);
     abort.abort();
@@ -87,20 +114,50 @@ describe('native helper transport', () => {
     expect(transport.closed).toBe(true);
   });
   it('reports process death rather than leaving requests pending', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', 'process.exit(3)']);
+    const transport = helper('process.exit(3)');
     await expect(transport.request('status', {}, new AbortController().signal)).rejects.toThrow(/exited/);
     await transport.close();
   });
   it('sends resume independently of a pending operation and permanently closes on stop', async () => {
-    const transport = new HelperTransport(process.execPath, ['-e', `const lines=require('readline').createInterface({input:process.stdin});
+    const transport: HelperTransport = helper(`const lines=require('readline').createInterface({input:process.stdin});
       let request;
       lines.on('line',line=>{const r=JSON.parse(line);
         if(r.method){request=r;process.stdout.write(JSON.stringify({version:4,event:'control_state',id:r.id,state:'paused_by_user'})+'\\n');}
         else if(r.control==='resume'){process.stdout.write(JSON.stringify({version:4,id:request.id,ok:true,result:{resumed:true}})+'\\n');}
-      });`], 1000, state => { if (state.state === 'paused_by_user') transport.control('resume'); });
+      });`, { timeoutMs: 1000, onEvent: (event) => { if (event.state === 'paused_by_user') transport.control('resume'); } });
     expect(await transport.request('click', {}, new AbortController().signal)).toEqual({resumed:true});
     transport.control('stop');
     await expect(transport.request('click', {}, new AbortController().signal)).rejects.toThrow(/closed/);
     await transport.close();
   });
 });
+
+describe('helper events', () => {
+  it('delivers a registered uncorrelated event without disturbing the pending request', async () => {
+    const events: HelperEvent[] = [];
+    const transport = helper(`process.stdin.once('data', bytes => {
+      const r=JSON.parse(bytes.toString());
+      process.stdout.write(JSON.stringify({version:4,event:'cursor',x:10,y:20})+'\\n');
+      process.stdout.write(JSON.stringify({version:4,id:r.id,ok:true,result:{clicked:true}})+'\\n');
+    });`, { events: { cursor: cursorEvent }, onEvent: (event) => events.push(event) });
+    try {
+      expect(await transport.request('click', {}, new AbortController().signal)).toEqual({ clicked: true });
+      expect(events).toEqual([{ version: 4, event: 'cursor', x: 10, y: 20 }]);
+    } finally { await transport.close(); }
+  });
+  it('delivers events that arrive while no request is pending', async () => {
+    const received = new Promise<HelperEvent>((resolve) => {
+      const transport = helper(`process.stdout.write(JSON.stringify({version:4,event:'cursor',x:1,y:2})+'\\n'); process.stdin.resume();`,
+        { events: { cursor: cursorEvent }, onEvent: (event) => { resolve(event); void transport.close(); } });
+    });
+    expect(await received).toEqual({ version: 4, event: 'cursor', x: 1, y: 2 });
+  });
+  it('treats an unregistered or malformed event as a protocol failure', async () => {
+    for (const frame of ['{version:4,event:"teleport"}', '{version:4,event:"cursor",x:"left",y:2}']) {
+      const transport = helper(`process.stdin.once('data', () => process.stdout.write(JSON.stringify(${frame})+'\\n'));`,
+        { events: { cursor: cursorEvent } });
+      await expect(transport.request('click', {}, new AbortController().signal)).rejects.toThrow(/protocol/);
+      await transport.close();
+    }
+  });
+});

package/src/{windows → helper}/transport.ts

@@ -1,7 +1,28 @@
 import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { JsonLineDecoder } from './protocol.js';
-import { MAX_FRAME_BYTES, PROTOCOL_VERSION, responseSchema, controlStateSchema, controlCommandSchema, type ControlState } from './contracts.js';
+import { z } from 'zod';
+import { JsonLineDecoder, MAX_FRAME_BYTES, TAKEOVER_PROTOCOL_VERSION, controlCommandSchema, controlStateSchemaFor, responseSchemaFor } from './protocol.js';
+
+/** A validated frame the helper emitted on its own (state changes, cursor moves, preview frames). */
+export interface HelperEvent { readonly event: string; readonly [field: string]: unknown }
+
+export interface HelperTransportOptions {
+  readonly protocolVersion: number;
+  readonly timeoutMs?: number;
+  /** Schemas for uncorrelated events by name. `control_state` is built in; any other name fails closed. */
+  readonly events?: Readonly<Record<string, z.ZodType<HelperEvent>>>;
+  readonly onEvent?: (event: HelperEvent) => void;
+}
+
+const eventFrame = z.object({ event: z.string() }).passthrough();
+
+/** A request the helper refused; `code` is the helper's machine-readable reason. */
+export class HelperError extends Error {
+  constructor(readonly code: string, readonly detail: string) {
+    super(`${code}: ${detail}`);
+    this.name = 'HelperError';
+  }
+}
 
 interface Pending {
   id: string;
@@ -22,9 +43,18 @@ export class HelperTransport {
   private stderrBytes = 0;
   get closed(): boolean { return this.stopped; }
   get stoppedByUser(): boolean { return this.userStopped; }
+  /** Settles once the helper process has exited, whatever the reason. */
+  get done(): Promise<void> { return this.exited; }
+
+  private readonly version: number;
+  private readonly timeoutMs: number;
 
-  constructor(command: string, args: string[], private readonly timeoutMs = 15_000,
-    private readonly onState: (state: ControlState) => void = () => undefined) {
+  constructor(command: string, args: string[], options: HelperTransportOptions) {
+    this.version = options.protocolVersion;
+    this.timeoutMs = options.timeoutMs ?? 15_000;
+    const onEvent = options.onEvent ?? (() => undefined);
+    const controlState = controlStateSchemaFor(this.version);
+    const response = responseSchemaFor(this.version);
     this.child = spawn(command, args, { shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
     this.exited = new Promise((resolve) => this.child.once('close', () => resolve()));
     const decoder = new JsonLineDecoder(MAX_FRAME_BYTES);
@@ -39,21 +69,28 @@ export class HelperTransport {
     this.child.stdout.on('data', (bytes: Buffer) => {
       try {
         for (const frame of decoder.push(bytes)) {
-          const event = controlStateSchema.safeParse(frame);
-          if (event.success) {
+          const tagged = eventFrame.safeParse(frame);
+          if (tagged.success && tagged.data.event === 'control_state') {
+            const state = controlState.parse(frame);
             const pending = this.pending;
-            if (!pending || event.data.id !== pending.id) throw new Error('Unmatched control state');
-            pending.waiting(event.data.state === 'waiting_for_focus' || event.data.state === 'paused_by_user');
-            this.onState(event.data);
+            if (!pending || state.id !== pending.id) throw new Error('Unmatched control state');
+            pending.waiting(state.state === 'waiting_for_focus' || state.state === 'paused_by_user');
+            onEvent(state);
+            continue;
+          }
+          if (tagged.success) {
+            const schema = options.events?.[tagged.data.event];
+            if (!schema) throw new Error('Unregistered helper event');
+            onEvent(schema.parse(frame));
             continue;
           }
-          const response = responseSchema.parse(frame);
+          const reply = response.parse(frame);
           const pending = this.pending;
-          if (!pending || pending.id !== response.id) throw new Error('Unmatched response');
+          if (!pending || pending.id !== reply.id) throw new Error('Unmatched response');
           this.pending = undefined;
           pending.dispose();
-          if (response.ok) pending.resolve(response.result);
-          else pending.reject(new Error(`${response.error.code}: ${response.error.message}`));
+          if (reply.ok) pending.resolve(reply.result);
+          else pending.reject(new HelperError(reply.error.code, reply.error.message));
         }
       } catch {
         this.fail(new Error('Computer Use protocol mismatch or invalid response; update the extension. Action not retried.'));
@@ -76,7 +113,7 @@ export class HelperTransport {
   }
 
   /** Control uses the reader side of the helper, never its blocked request queue. */
-  control(command: 'pause' | 'resume' | 'stop'): void {
+  control(command: 'pause' | 'resume' | 'stop' | 'takeover'): void {
     controlCommandSchema.parse(command);
     if (this.stopped) throw new Error('Computer Use connection closed');
     if (command === 'stop') {
@@ -84,14 +121,15 @@ export class HelperTransport {
       this.fail(new Error('Computer Use stopped by user; action not retried.'));
       return;
     }
-    this.child.stdin.write(JSON.stringify({version: PROTOCOL_VERSION, control: command}) + '\n');
+    const sent = command === 'takeover' && this.version < TAKEOVER_PROTOCOL_VERSION ? 'pause' : command;
+    this.child.stdin.write(JSON.stringify({version: this.version, control: sent}) + '\n');
   }
 
   private send(method: string, params: unknown, signal: AbortSignal): Promise<unknown> {
     if (this.stopped) return Promise.reject(new Error('Computer Use connection closed; observe again with a new connection.'));
     if (signal.aborted) return Promise.reject(new Error('Computer Use cancelled'));
     const id = randomUUID();
-    const frame = JSON.stringify({ version: PROTOCOL_VERSION, id, method, params }) + '\n';
+    const frame = JSON.stringify({ version: this.version, id, method, params }) + '\n';
     if (Buffer.byteLength(frame) > MAX_FRAME_BYTES) return Promise.reject(new Error('Computer Use request limit exceeded'));
     return new Promise((resolve, reject) => {
       const abort = () => this.fail(new Error('Computer Use cancelled; action not retried.'));