rootrework 1.0.2 → 1.0.4

package/src/backend.mjs

@@ -0,0 +1,391 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { spawn } from 'node:child_process';
+import { CHUNK_BYTES, finished, delay, fail, validateInput, integer, text, json, atomic, privateDir, executable, shells, shellArgs, alive, processIdentity, platformInfo } from './process.mjs';
+
+const moduleRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const S = { type: 'string' }, I = { type: 'integer', minimum: 0 }, B = { type: 'boolean' };
+const taskId = { task_id: S };
+function tool(name, description, properties, required = []) { const readOnly = ['system_info', 'task_get', 'task_events', 'task_list'].includes(name); return { name, description, inputSchema: { type: 'object', properties, required, additionalProperties: false }, annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly && name !== 'search', openWorldHint: !readOnly } }; }
+const execFields = { executable: S, args: { type: 'array', items: S }, cwd: S, env: { type: 'object', additionalProperties: { type: ['string', 'null'] } }, shell: S, command: S, stdin: S, stdin_encoding: { enum: ['utf8', 'base64'] }, timeout_ms: I, wait_ms: I, request_id: S };
+const schemas = [
+  tool('system_info', 'Discover this device, platform, current runtime, executable shells and available backend features.', {}),
+  tool('filesystem', 'Read and modify native paths. Byte reads and writes are bounded with continuation. Offset writes accept exact replay and reject gaps. Use expected_size or expected_text to detect concurrent edits. A list cursor is a stable snapshot.', { operation: { enum: ['stat', 'list', 'read', 'write', 'append', 'edit', 'mkdir', 'copy', 'move', 'delete'] }, path: S, destination: S, cursor: S, limit: I, offset: I, length: I, encoding: { enum: ['utf8', 'base64'] }, data: S, expected_size: I, expected_text: S, old_text: S, new_text: S, expected_occurrences: I, recursive: B, overwrite: B, create_parents: B, mode: I }, ['operation']),
+  tool('search', 'Search names or UTF-8/UTF-16 text in a detached cancellable task. Continue using cursor; every page includes errors and explicit exclusions. Symlinks are followed only when requested and cycles are reported. Results persist across reconnects.', { path: S, query: S, mode: { enum: ['filename', 'content'] }, regex: B, case_sensitive: B, follow_symlinks: B, include_hidden: B, cursor: S, limit: I, wait_ms: I, request_id: S }, []),
+  tool('exec', 'Execute an executable plus exact argument array, or a command with an explicit shell. Native environment defaults are inherited; env adds or removes exact values. Optional stdin bytes are followed by EOF. Returns durable task state; output is available through task_events. Reuse request_id to reconcile an uncertain launch; commands are never automatically retried.', execFields),
+  tool('task_get', 'Get durable process state and output sizes. A lost supervisor is reported as unknown_outcome, never a successful completion.', { ...taskId, wait_ms: I }, ['task_id']),
+  tool('task_events', 'Read raw output by byte offset. Each stream has its own offset; base64 preserves arbitrary bytes and split UTF-8 sequences. Continue until the returned byte totals are reached.', { ...taskId, stream: { enum: ['stdout', 'stderr', 'terminal'] }, offset: I, length: I }, ['task_id']),
+  tool('task_list', 'List persistent tasks with pagination; command arguments and environment values are not included.', { cursor: S, limit: I }),
+  tool('task_cancel', 'Cancel the owned process tree. A transport timeout does not imply cancellation; inspect the returned task state.', { ...taskId, wait_ms: I }, ['task_id']),
+  tool('terminal_open', 'Open a real native PTY or ConPTY. Its supervisor survives agent reconnects. Use task_events with stream terminal for exact output and the returned task_id for reattachment.', { ...execFields, cols: { type: 'integer', minimum: 1 }, rows: { type: 'integer', minimum: 1 } }),
+  tool('terminal_input', 'Write exact text or base64 bytes to a live terminal. No newline is added automatically.', { ...taskId, data: S, encoding: { enum: ['utf8', 'base64'] }, request_id: S }, ['task_id', 'data']),
+  tool('terminal_resize', 'Resize the actual native terminal.', { ...taskId, cols: { type: 'integer', minimum: 1 }, rows: { type: 'integer', minimum: 1 } }, ['task_id', 'cols', 'rows']),
+  tool('terminal_interrupt', 'Send Ctrl-C to the native terminal foreground process group.', taskId, ['task_id']),
+  tool('terminal_close', 'Terminate this terminal and its owned process tree. Does not revoke a device or remove persisted results.', { ...taskId, wait_ms: I }, ['task_id'])
+];
+function decode(data, encoding = 'utf8') {
+  text(data, 'data');
+  if (encoding !== 'utf8' && encoding !== 'base64') fail('INVALID_ARGUMENT', 'encoding must be utf8 or base64.');
+  if (encoding === 'base64' && !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) fail('INVALID_ARGUMENT', 'Malformed base64.');
+  const b = Buffer.from(data, encoding);
+  if (b.length > CHUNK_BYTES) fail('CHUNK_TOO_LARGE', `Use chunks of at most ${CHUNK_BYTES} bytes.`);
+  return b;
+}
+function cursor(value) { return Buffer.from(JSON.stringify(value)).toString('base64url'); }
+function uncursor(value, kind) {
+  try { const v = JSON.parse(Buffer.from(text(value), 'base64url').toString()); if (v.kind !== kind || typeof v.id !== 'string' || !/^[\w-]+$/.test(v.id)) throw 0; integer(v.offset, 0); return v; }
+  catch { fail('INVALID_CURSOR', 'The continuation cursor is invalid.'); }
+}
+function metadata(s) { return { type: s.isSymbolicLink() ? 'symlink' : s.isDirectory() ? 'directory' : s.isFile() ? 'file' : 'other', size: s.size, mode: s.mode & 0o7777, modified_at: s.mtime.toISOString(), created_at: s.birthtime.toISOString(), uid: s.uid, gid: s.gid }; }
+function safeId(id) { if (typeof id !== 'string' || !/^[\w-]{1,128}$/.test(id)) fail('INVALID_ARGUMENT', 'Invalid task identifier.'); return id; }
+function stable(value) { if (Array.isArray(value)) return '[' + value.map(stable).join(',') + ']'; if (value && typeof value === 'object') return '{' + Object.keys(value).sort().map(k => JSON.stringify(k) + ':' + stable(value[k])).join(',') + '}'; return JSON.stringify(value); }
+function commandIdentity(spec) { const { packageRoot, ...operation } = spec; return stable(operation); }
+function sameCommand(saved, spec) {
+  if (saved === commandIdentity(spec)) return true;
+  try { return commandIdentity(JSON.parse(saved)) === commandIdentity(spec); } catch { return false; }
+}
+async function claimJSON(file) {
+  const until = Date.now() + 1500;
+  while (true) {
+    try { return await json(file); }
+    catch (e) { if (!(e instanceof SyntaxError)) throw e; if (Date.now() >= until) fail('UNKNOWN_OUTCOME', 'A prior operation record is incomplete; it was not retried.'); await delay(25); }
+  }
+}
+
+export function createBackend({ stateDir, packageRoot = moduleRoot, deviceId } = {}) {
+  if (!stateDir) fail('INVALID_ARGUMENT', 'stateDir is required.');
+  stateDir = path.resolve(stateDir); packageRoot = path.resolve(packageRoot);
+  const tasksDir = path.join(stateDir, 'tasks'), requestsDir = path.join(stateDir, 'requests'), cursorsDir = path.join(stateDir, 'cursors');
+  const ready = Promise.all([privateDir(tasksDir), privateDir(requestsDir), privateDir(cursorsDir)]);
+  const locks = new Map(), supervisors = new Map();
+  let closed = false, ptyAvailable = false;
+  try { createRequire(path.join(packageRoot, 'package.json'))('@lydell/node-pty'); ptyAvailable = true; } catch {}
+  const tools = schemas.filter(t => ptyAvailable || !t.name.startsWith('terminal_'));
+  const dirFor = id => path.join(tasksDir, safeId(id));
+  async function withLock(file, operation) {
+    const before = locks.get(file) || Promise.resolve();
+    const next = before.catch(() => {}).then(operation); locks.set(file, next);
+    try { return await next; } finally { if (locks.get(file) === next) locks.delete(file); }
+  }
+  async function get(id, wait = 0) {
+    const dir = dirFor(id); let state;
+    const until = Date.now() + integer(wait, 0, 10000);
+    do {
+      state = await json(path.join(dir, 'state.json'));
+      if (finished.has(state.state)) break;
+      const launch = await json(path.join(dir, 'launch.json')).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+      const pid = state.supervisor_pid || launch?.supervisor_pid;
+      const running = pid ? await alive(pid, state.supervisor_identity || launch?.supervisor_identity) : await alive(launch?.launcher_pid, launch?.launcher_identity);
+      if (pid && !state.supervisor_pid) state.supervisor_pid = pid;
+      const stale = Date.now() - Date.parse(state.updated_at);
+      if (!running && stale > 3000) {
+        const final = await json(path.join(dir, 'state.json'));
+        if (finished.has(final.state)) { state = final; break; }
+        if (final.updated_at !== state.updated_at || final.state !== state.state || final.supervisor_pid && final.supervisor_pid !== pid) { state = final; continue; }
+        const failure = await json(path.join(dir, 'supervisor-error.json')).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+        state = { ...state, state: 'unknown_outcome', observed_state: final.state, uncertainty: 'Supervisor is unavailable; command effects may have occurred. The command was not retried.', ...(failure ? { supervisor_error: failure } : {}), ...(launch?.exited_at ? { supervisor_exit: { code: launch.exit_code, signal: launch.signal, at: launch.exited_at } } : {}) }; break;
+      }
+      if (running && stale > 15000) state.heartbeat_stale = true;
+      if (Date.now() >= until) break;
+      await delay(Math.min(75, until - Date.now()));
+    } while (true);
+    for (const stream of ['stdout', 'stderr', 'terminal']) {
+      try { state.output_bytes ||= {}; state.output_bytes[stream] = (await fs.stat(path.join(dir, `${stream}.bin`))).size; } catch {}
+    }
+    const { supervisor_identity, ...visible } = state;
+    return visible;
+  }
+  async function launch(kind, args) {
+    const cwd = path.resolve(args.cwd === undefined ? process.cwd() : text(args.cwd, 'cwd'));
+    if (!(await fs.stat(cwd)).isDirectory()) fail('NOT_DIRECTORY', 'cwd is not a directory.');
+    let file, argv;
+    if (args.shell !== undefined) {
+      if (args.executable !== undefined || args.args !== undefined || args.command === undefined) fail('INVALID_ARGUMENT', 'Use shell plus command, or executable plus args.');
+      file = await executable(text(args.shell)); if (!file) fail('ENOENT', 'Selected shell is unavailable.');
+      argv = shellArgs(file, text(args.command, 'command'));
+    } else {
+      if (args.command !== undefined) fail('INVALID_ARGUMENT', 'command requires an explicit shell.');
+      file = args.executable === undefined && kind === 'terminal' ? (await shells())[0] : text(args.executable, 'executable');
+      if (!file) fail('ENOENT', 'No executable shell is available.');
+      argv = args.args === undefined ? [] : args.args;
+      if (!Array.isArray(argv)) fail('INVALID_ARGUMENT', 'args must be an array.');
+      argv = argv.map(a => text(a, 'argument'));
+    }
+    if (kind === 'terminal' && !ptyAvailable) fail('UNAVAILABLE', 'Native terminal support is not installed for this platform.');
+    const spec = { kind, executable: file, args: argv, cwd, env: args.env || {}, timeout_ms: integer(args.timeout_ms, 0), packageRoot };
+    if (args.stdin !== undefined) spec.stdin = decode(args.stdin, args.stdin_encoding).toString('base64');
+    if (kind === 'terminal') { spec.cols = integer(args.cols, 80, 32767); spec.rows = integer(args.rows, 24, 32767); if (!spec.cols || !spec.rows) fail('INVALID_ARGUMENT', 'Terminal dimensions must be positive.'); }
+    if (args.request_id !== undefined) {
+      text(args.request_id, 'request_id');
+      if (!args.request_id.length || Buffer.byteLength(args.request_id) > 128) fail('INVALID_ARGUMENT', 'request_id must contain 1 to 128 bytes.');
+      const key = path.join(requestsDir, Buffer.from(args.request_id).toString('base64url') + '.json');
+      return withLock(key, async () => {
+        try {
+          const previous = await claimJSON(key);
+          if (!sameCommand(previous.specification, spec)) fail('REQUEST_CONFLICT', 'request_id is already associated with a different operation.');
+          return { ...(await get(previous.task_id, args.wait_ms)), reused: true };
+        } catch (e) { if (e.code !== 'ENOENT') throw e; }
+        return start(spec, args, key);
+      });
+    }
+    return start(spec, args);
+  }
+  async function start(spec, args, requestFile) {
+    const id = randomUUID(), dir = dirFor(id), now = new Date().toISOString();
+    await privateDir(dir); await privateDir(path.join(dir, 'controls'));
+    await atomic(path.join(dir, 'spec.json'), spec);
+    await atomic(path.join(dir, 'state.json'), { task_id: id, device_id: deviceId, kind: spec.kind, state: 'queued', created_at: now, updated_at: now, output_bytes: { stdout: 0, stderr: 0, terminal: 0 }, cwd: spec.cwd, executable: spec.executable });
+    if (requestFile) {
+      try { const h = await fs.open(requestFile, 'wx', 0o600); try { await h.writeFile(JSON.stringify({ task_id: id, specification: commandIdentity(spec) })); await h.sync(); } finally { await h.close(); } }
+      catch (e) {
+        await fs.rm(dir, { recursive: true, force: true });
+        if (e.code !== 'EEXIST') throw e;
+        const previous = await claimJSON(requestFile);
+        if (!sameCommand(previous.specification, spec)) fail('REQUEST_CONFLICT', 'request_id is already associated with a different operation.');
+        return { ...(await get(previous.task_id, args.wait_ms)), reused: true };
+      }
+    }
+    let child;
+    try {
+      const launchFile = path.join(dir, 'launch.json');
+      await atomic(launchFile, { launcher_pid: process.pid, launcher_identity: await processIdentity(process.pid), created_at: new Date().toISOString() });
+      const updateLaunch = values => withLock(launchFile, async () => atomic(launchFile, { ...await json(launchFile), ...values }));
+      child = spawn(process.execPath, [path.join(moduleRoot, 'src', 'supervisor.mjs'), dir], { detached: true, stdio: 'ignore', windowsHide: true, cwd: spec.cwd });
+      const exited = new Promise(resolve => {
+        child.once('exit', (code, signal) => { void updateLaunch({ exit_code: code, signal, exited_at: new Date().toISOString() }).catch(() => {}).finally(resolve); });
+        child.once('error', resolve);
+      });
+      supervisors.set(id, { child, exited });
+      void exited.then(() => supervisors.delete(id));
+      await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+      child.unref();
+      await updateLaunch({ supervisor_pid: child.pid, supervisor_identity: await processIdentity(child.pid), launched_at: new Date().toISOString() });
+    } catch (e) {
+      if (child?.pid) return { ...await get(id, args.wait_ms === undefined ? 100 : args.wait_ms), launch_warning: 'The supervisor started, but its launch identity could not be saved. Inspect this task before retrying.' };
+      const s = await json(path.join(dir, 'state.json'));
+      await atomic(path.join(dir, 'state.json'), { ...s, state: 'completed_failure', error: { code: e.code || 'SPAWN_FAILED', message: 'Supervisor could not start.' }, finished_at: new Date().toISOString() });
+      await fs.rm(path.join(dir, 'spec.json'), { force: true });
+    }
+    return get(id, args.wait_ms === undefined ? 100 : args.wait_ms);
+  }
+  async function events(args) {
+    const state = await get(args.task_id);
+    const stream = args.stream || (state.kind === 'terminal' ? 'terminal' : 'stdout');
+    if (!['stdout', 'stderr', 'terminal'].includes(stream)) fail('INVALID_ARGUMENT', 'Invalid output stream.');
+    const offset = integer(args.offset, 0), length = integer(args.length, CHUNK_BYTES, CHUNK_BYTES);
+    let bytes = Buffer.alloc(0), size = 0;
+    try {
+      const h = await fs.open(path.join(dirFor(args.task_id), `${stream}.bin`), 'r');
+      try { size = (await h.stat()).size; if (offset > size) fail('INVALID_OFFSET', 'Offset is beyond available output.'); const b = Buffer.alloc(Math.min(length, size - offset)); const read = await h.read(b, 0, b.length, offset); bytes = b.subarray(0, read.bytesRead); } finally { await h.close(); }
+    } catch (e) { if (e.code !== 'ENOENT') throw e; }
+    return { task_id: args.task_id, state: state.state, stream, offset, next_offset: offset + bytes.length, total_bytes: size, data: bytes.toString('base64'), encoding: 'base64', has_more: offset + bytes.length < size, complete: finished.has(state.state) && state.state !== 'unknown_outcome' && offset + bytes.length >= size, truncated: false };
+  }
+  async function control(args, operation, extra = {}) {
+    const state = await get(args.task_id);
+    if (finished.has(state.state)) return { task: state, accepted: false };
+    if (operation !== 'cancel' && state.kind !== 'terminal') fail('NOT_TERMINAL', 'This task is not a terminal.');
+    const id = args.request_id === undefined ? randomUUID() : safeId(args.request_id);
+    const dir = path.join(dirFor(args.task_id), 'controls');
+    const request = path.join(dir, `${id}.request.json`), resultFile = path.join(dir, `${id}.result.json`), claim = path.join(dir, `${id}.command.json`);
+    const specification = { operation, ...extra };
+    let created = false;
+    try { const h = await fs.open(claim, 'wx', 0o600); try { await h.writeFile(JSON.stringify(specification)); await h.sync(); created = true; } finally { await h.close(); } }
+    catch (e) { if (e.code !== 'EEXIST') throw e; if (stable(await claimJSON(claim)) !== stable(specification)) fail('REQUEST_CONFLICT', 'Control request_id already identifies a different input.'); }
+    if (created) await atomic(request, specification);
+    const until = Date.now() + 3000;
+    do {
+      try { const result = await json(resultFile); return { ...result, task_id: args.task_id, control_id: id, reused: !created, task: await get(args.task_id, args.wait_ms || 0) }; }
+      catch (e) { if (e.code !== 'ENOENT') throw e; }
+      if (Date.now() >= until) return { task_id: args.task_id, control_id: id, accepted: null, state: 'pending', task: await get(args.task_id) };
+      await delay(50);
+    } while (true);
+  }
+  async function paged(kind, values, args) {
+    let key, offset = 0;
+    if (args.cursor) { const c = uncursor(args.cursor, kind); key = c.id; offset = c.offset; values = await json(path.join(cursorsDir, `${key}.json`)); }
+    else { key = randomUUID(); await atomic(path.join(cursorsDir, `${key}.json`), values); }
+    const limit = integer(args.limit, 100, 1000);
+    if (!limit) fail('INVALID_ARGUMENT', 'limit must be positive.');
+    const entries = []; let size = 0;
+    for (const entry of values.slice(offset, offset + limit)) { const n = Buffer.byteLength(JSON.stringify(entry)); if (size + n > CHUNK_BYTES && entries.length) break; entries.push(entry); size += n; }
+    const next = offset + entries.length;
+    return { entries, total: values.length, cursor: next < values.length ? cursor({ kind, id: key, offset: next }) : null, snapshot: true, truncated: false };
+  }
+  async function filesystem(args) {
+    if (args.operation === 'list' && args.cursor) return paged('list', null, args);
+    const file = path.resolve(text(args.path, 'path'));
+    if (args.operation === 'stat') { const s = await fs.lstat(file); return { path: file, ...metadata(s), ...(s.isSymbolicLink() ? { target: await fs.readlink(file) } : {}) }; }
+    if (args.operation === 'list') {
+      const entries = [];
+      for await (const d of await fs.opendir(file)) {
+        const target = path.join(file, d.name);
+        try { entries.push({ name: d.name, path: target, ...metadata(await fs.lstat(target)) }); }
+        catch (e) { entries.push({ name: d.name, path: target, error: e.code }); }
+      }
+      entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+      return { path: file, ...(await paged('list', entries, args)) };
+    }
+    if (args.operation === 'read') {
+      const offset = integer(args.offset, 0), length = integer(args.length, CHUNK_BYTES, CHUNK_BYTES);
+      const h = await fs.open(file, 'r');
+      try {
+        const before = await h.stat(); if (!before.isFile()) fail('NOT_FILE', 'Only regular file bytes can be read.');
+        if (offset > before.size) fail('INVALID_OFFSET', 'Offset is beyond the file.');
+        const buffer = Buffer.alloc(Math.min(length, before.size - offset)); const { bytesRead } = await h.read(buffer, 0, buffer.length, offset); const b = buffer.subarray(0, bytesRead);
+        const result = { path: file, offset, next_offset: offset + bytesRead, size: before.size, data: b.toString('base64'), encoding: 'base64', eof: offset + bytesRead >= before.size, modified_at: before.mtime.toISOString(), truncated: false };
+        if (args.encoding === 'utf8') {
+          try {
+            const value = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(b);
+            if (Buffer.byteLength(JSON.stringify(value)) <= 90000) { result.data = value; result.encoding = 'utf8'; }
+            else result.text_reason = 'JSON escaping exceeds the response budget; exact bytes are returned as base64.';
+          }
+          catch { result.text_reason = 'The byte chunk includes invalid or partial UTF-8. Exact bytes are returned as base64.'; }
+        } else if (args.encoding !== undefined && args.encoding !== 'base64') fail('INVALID_ARGUMENT', 'Invalid encoding.');
+        return result;
+      } finally { await h.close(); }
+    }
+    return withLock(file, async () => {
+      if (args.operation === 'mkdir') { await fs.mkdir(file, { recursive: !!args.recursive, mode: args.mode === undefined ? undefined : integer(args.mode, 0, 0o7777) }); return { path: file, ...(metadata(await fs.stat(file))) }; }
+      if (args.operation === 'delete') { await fs.rm(file, { recursive: !!args.recursive }); return { path: file, deleted: true }; }
+      if (args.operation === 'copy' || args.operation === 'move') {
+        const destination = path.resolve(text(args.destination, 'destination'));
+        if (file === destination || destination.startsWith(file + path.sep)) fail('INVALID_ARGUMENT', 'Destination must be outside the source.');
+        let exists = false; try { await fs.lstat(destination); exists = true; } catch (e) { if (e.code !== 'ENOENT') throw e; }
+        if (exists && !args.overwrite) fail('EEXIST', 'Destination exists.');
+        if (args.create_parents) await fs.mkdir(path.dirname(destination), { recursive: true });
+        if (args.operation === 'move') {
+          try { await fs.rename(file, destination); return { path: destination, moved: true }; }
+          catch (e) { if (e.code !== 'EXDEV') throw e; }
+        }
+        await fs.cp(file, destination, { recursive: !!args.recursive, force: !!args.overwrite, errorOnExist: !args.overwrite, preserveTimestamps: true, verbatimSymlinks: true });
+        if (args.operation === 'move') { await compareTree(file, destination); await fs.rm(file, { recursive: !!args.recursive }); }
+        return { path: destination, copied: true, moved: args.operation === 'move' };
+      }
+      if (!['write', 'append', 'edit'].includes(args.operation)) fail('INVALID_ARGUMENT', 'Unsupported filesystem operation.');
+      if (args.create_parents) await fs.mkdir(path.dirname(file), { recursive: true });
+      let current;
+      try { const descriptor = await fs.open(file, 'r'); try { current = await descriptor.stat({ bigint: true }); } finally { await descriptor.close(); } }
+      catch (e) { if (e.code !== 'ENOENT') throw e; }
+      if (current && !current.isFile()) fail('NOT_FILE', 'Target is not a regular file.');
+      if (args.expected_size !== undefined && BigInt(integer(args.expected_size)) !== (current?.size || 0n)) fail('REVISION_CONFLICT', 'File size changed.');
+      if (args.operation === 'edit') {
+        const original = await fs.readFile(file);
+        let before; try { before = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(original); } catch { fail('INVALID_ENCODING', 'Text editing requires valid UTF-8. Use byte writes for binary data.'); }
+        if (args.expected_text !== undefined && before !== text(args.expected_text)) fail('REVISION_CONFLICT', 'File content changed.');
+        const old = text(args.old_text, 'old_text'), replacement = text(args.new_text, 'new_text');
+        if (!old.length) fail('INVALID_ARGUMENT', 'old_text must not be empty.');
+        const occurrences = before.split(old).length - 1;
+        if (occurrences !== integer(args.expected_occurrences, 1)) fail('REVISION_CONFLICT', 'The number of matching occurrences differs from the expected count.');
+        await replaceContents(file, Buffer.from(before.split(old).join(replacement)), current, original);
+        return { path: file, replacements: occurrences, size: (await fs.stat(file)).size };
+      }
+      const bytes = decode(args.data, args.encoding);
+      if (args.operation === 'write' && args.offset === undefined) {
+        const expected = args.expected_text === undefined ? null : Buffer.from(text(args.expected_text));
+        await replaceContents(file, bytes, current, expected, args.mode === undefined ? 0o600 : integer(args.mode, 0, 0o7777));
+        return { path: file, bytes_written: bytes.length, size: bytes.length, next_offset: bytes.length, verified: (await fs.readFile(file)).equals(bytes) };
+      }
+      const offset = args.operation === 'append' ? Number(current?.size || 0n) : integer(args.offset);
+      const h = await fs.open(file, current ? 'r+' : 'wx+', current ? undefined : 0o600);
+      try {
+        const size = (await h.stat()).size;
+        if (args.expected_size !== undefined && size !== args.expected_size) fail('REVISION_CONFLICT', 'File size changed.');
+        if (offset > size) fail('INVALID_OFFSET', 'Chunk would leave a gap.');
+        let prefix = 0;
+        if (offset < size) {
+          const old = Buffer.alloc(Math.min(bytes.length, size - offset)); await h.read(old, 0, old.length, offset);
+          if (!old.equals(bytes.subarray(0, old.length))) fail('REVISION_CONFLICT', 'This offset contains different bytes.');
+          if (old.length === bytes.length) return { path: file, replayed: true, bytes_written: 0, next_offset: offset + bytes.length, size };
+          prefix = old.length;
+        }
+        let done = prefix; while (done < bytes.length) done += (await h.write(bytes, done, bytes.length - done, offset + done)).bytesWritten;
+        await h.sync();
+        return { path: file, bytes_written: done - prefix, resumed_bytes: prefix, next_offset: offset + done, size: (await h.stat()).size };
+      } finally { await h.close(); }
+    });
+  }
+  async function replaceContents(file, bytes, previous, expected, mode = 0o600) {
+    const h = await fs.open(file, previous ? 'r+' : 'wx+', mode);
+    try {
+      const now = await h.stat({ bigint: true });
+      if (previous && (now.dev !== previous.dev || now.ino !== previous.ino || now.size !== previous.size || now.mtimeNs !== previous.mtimeNs)) fail('REVISION_CONFLICT', 'File changed before writing.');
+      if (expected !== null && expected !== undefined) {
+        const actual = await h.readFile(); if (!actual.equals(expected)) fail('REVISION_CONFLICT', 'File content changed.');
+      }
+      let at = 0; while (at < bytes.length) at += (await h.write(bytes, at, bytes.length - at, at)).bytesWritten;
+      await h.truncate(bytes.length); await h.sync();
+    } finally { await h.close(); }
+  }
+  async function compareTree(source, target) {
+    const a = await fs.lstat(source), b = await fs.lstat(target);
+    if (a.isSymbolicLink()) { if (!b.isSymbolicLink() || await fs.readlink(source) !== await fs.readlink(target)) fail('VERIFY_FAILED', 'Copied link differs.'); }
+    else if (a.isDirectory()) {
+      const names = (await fs.readdir(source)).sort(); if (JSON.stringify(names) !== JSON.stringify((await fs.readdir(target)).sort())) fail('VERIFY_FAILED', 'Copied directory differs.');
+      for (const name of names) await compareTree(path.join(source, name), path.join(target, name));
+    } else {
+      if (a.size !== b.size || !a.isFile() || !b.isFile()) fail('VERIFY_FAILED', 'Copied file differs.');
+      const x = await fs.open(source), y = await fs.open(target);
+      try { for (let at = 0; at < a.size; at += CHUNK_BYTES) { const left = Buffer.alloc(Math.min(CHUNK_BYTES, a.size - at)), right = Buffer.alloc(left.length); await x.read(left, 0, left.length, at); await y.read(right, 0, right.length, at); if (!left.equals(right)) fail('VERIFY_FAILED', 'Copied bytes differ.'); } }
+      finally { await x.close(); await y.close(); }
+    }
+  }
+  async function search(args) {
+    let id, offset = 0;
+    if (args.cursor) { const c = uncursor(args.cursor, 'search'); id = c.id; offset = c.offset; }
+    else {
+      const options = { path: path.resolve(text(args.path, 'path')), query: text(args.query, 'query'), mode: args.mode || 'filename', regex: !!args.regex, case_sensitive: !!args.case_sensitive, follow_symlinks: !!args.follow_symlinks, include_hidden: args.include_hidden !== false };
+      if (!['filename', 'content'].includes(options.mode)) fail('INVALID_ARGUMENT', 'Invalid search mode.');
+      if (options.regex) { try { new RegExp(options.query, options.case_sensitive ? 'u' : 'iu'); } catch { fail('INVALID_ARGUMENT', 'Invalid regular expression.'); } }
+      const task = await launch('search', { executable: process.execPath, args: [path.join(moduleRoot, 'src', 'search-worker.mjs'), JSON.stringify(options)], request_id: args.request_id, wait_ms: args.wait_ms === undefined ? 250 : args.wait_ms });
+      id = task.task_id;
+    }
+    const task = await get(id, args.wait_ms || 0);
+    if (task.kind !== 'search') fail('INVALID_CURSOR', 'Cursor is not a search.');
+    const h = await fs.open(path.join(dirFor(id), 'stdout.bin'), 'r').catch(e => { if (e.code === 'ENOENT') return null; throw e; });
+    let entries = [], next = offset;
+    if (h) {
+      try {
+        const size = (await h.stat()).size, b = Buffer.alloc(Math.min(CHUNK_BYTES, Math.max(0, size - offset))); const read = await h.read(b, 0, b.length, offset); const buffer = b.subarray(0, read.bytesRead);
+        const limit = integer(args.limit, 100, 1000); if (!limit) fail('INVALID_ARGUMENT', 'limit must be positive.');
+        let from = 0;
+        while (entries.length < limit) { const end = buffer.indexOf(10, from); if (end < 0) break; entries.push(JSON.parse(buffer.subarray(from, end).toString('utf8'))); next = offset + end + 1; from = end + 1; }
+      } finally { await h.close(); }
+    }
+    const complete = finished.has(task.state) && next >= (task.output_bytes.stdout || 0);
+    return { task_id: id, state: task.state, entries, cursor: complete ? null : cursor({ kind: 'search', id, offset: next }), complete, truncated: false, error: task.error || null };
+  }
+  return {
+    tools,
+    async call(name, args = {}) {
+      await ready; if (closed) fail('CLOSED', 'Backend is closed.');
+      if (!tools.some(t => t.name === name)) fail('UNKNOWN_TOOL', 'Tool is not available on this device.');
+      if (!args || typeof args !== 'object' || Array.isArray(args)) fail('INVALID_ARGUMENT', 'Arguments must be an object.');
+      validateInput(args, tools.find(tool => tool.name === name).inputSchema);
+      if (name === 'system_info') return { device_id: deviceId, ...(await platformInfo()), features: { durable_tasks: true, native_terminal: ptyAvailable, byte_chunks: CHUNK_BYTES, terminal_survives_agent_restart: true, terminal_survives_os_reboot: false } };
+      if (name === 'filesystem') return filesystem(args);
+      if (name === 'search') return search(args);
+      if (name === 'exec' || name === 'terminal_open') return launch(name === 'exec' ? 'exec' : 'terminal', args);
+      if (name === 'task_get') return get(args.task_id, args.wait_ms);
+      if (name === 'task_events') return events(args);
+      if (name === 'task_list') { if (args.cursor) return paged('tasks', null, args); const list = []; for (const id of await fs.readdir(tasksDir)) { try { list.push(await get(id)); } catch {} } list.sort((a, b) => a.created_at.localeCompare(b.created_at)); return paged('tasks', list, args); }
+      if (name === 'task_cancel' || name === 'terminal_close') return control(args, name === 'task_cancel' ? 'cancel' : 'close');
+      if (name === 'terminal_input') return control(args, 'input', { data: decode(args.data, args.encoding).toString('base64') });
+      if (name === 'terminal_resize') { const cols = integer(args.cols, undefined, 32767), rows = integer(args.rows, undefined, 32767); if (!cols || !rows) fail('INVALID_ARGUMENT', 'Terminal dimensions must be positive.'); return control(args, 'resize', { cols, rows }); }
+      if (name === 'terminal_interrupt') return control(args, 'interrupt');
+    },
+    async close() {
+      closed = true; await ready;
+      await Promise.all([...supervisors].map(async ([id, { child, exited }]) => {
+        const state = await json(path.join(dirFor(id), 'state.json'));
+        if (finished.has(state.state)) {
+          child.ref();
+          try { await exited; } finally { child.unref(); }
+        }
+      }));
+      await Promise.allSettled(locks.values());
+    }
+  };
+}