@miruzero/zero-agent 0.3.6 → 0.3.8

package/src/local-server.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const zero = require('./zero');
+
+const json = (res, status, body) => {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+};
+
+const htmlEscape = (value) => String(value)
+  .replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+  .replaceAll('"', '&quot;').replaceAll("'", '&#39;');
+
+const html = (res, status, body) => {
+  res.writeHead(status, { 'content-type': 'text/html; charset=utf-8' });
+  res.end(String(body));
+};
+
+const preflightHeaders = {
+  'content-type': 'application/json',
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'GET, OPTIONS',
+  'access-control-allow-private-network': 'true',
+  'cache-control': 'no-store'
+};
+
+const preflightJson = (res, status, body) => {
+  res.writeHead(status, preflightHeaders);
+  res.end(JSON.stringify(body));
+};
+
+const loadSessionProvider = (env) => {
+  if (!env.ZERO_CHATGPT_SESSION_MODULE) return zero.chatgptSession;
+  const resolved = require.resolve(env.ZERO_CHATGPT_SESSION_MODULE);
+  delete require.cache[resolved];
+  return require(resolved);
+};
+
+const reportCompletion = async ({ device, ticket, authStatus, errorCode = '' }) => {
+  const coreBase = String(device.server).replace(/\/$/, '');
+  const result = await zero.http.requestJson(coreBase + '/setup/chatgpt-auth/complete', {
+    method: 'POST',
+    body: { ticket, device: device.name || '', auth_status: authStatus, error_code: errorCode },
+    timeoutMs: 3000
+  });
+  if (!result.ok) {
+    const error = new Error('Zero setup completion failed');
+    error.code = 'ZERO_SETUP_COMPLETE_FAILED';
+    throw error;
+  }
+  return result;
+};
+
+const reportReadiness = async ({ device, ticket, state, checks = {}, errorCode = '', httpStatus = null }) => {
+  const coreBase = String(device.server).replace(/\/$/, '');
+  const result = await zero.http.requestJson(coreBase + '/setup/chatgpt-auth/report', {
+    method: 'POST',
+    body: { ticket, device: device.name || '', state, checks, error_code: errorCode, http_status: httpStatus },
+    timeoutMs: 3000
+  });
+  if (!result.ok) {
+    const error = new Error('Zero readiness report failed');
+    error.code = 'ZERO_READINESS_REPORT_FAILED';
+    throw error;
+  }
+  return result;
+};
+
+const reportFailure = async ({ device, ticket, code }) => {
+  try { await reportCompletion({ device, ticket, authStatus: 'failed', errorCode: code }); } catch {}
+};
+
+exports.startLocalServer = ({ port, env = process.env } = {}) => {
+  const listenPort = port ?? Number(env.ZERO_AGENT_LOCAL_PORT || 8051);
+  const server = zero.nodeHttp.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+    if (req.method === 'GET' && url.pathname === '/zero/status') {
+      return json(res, 200, { ok: true, agent: 'zero-agent', device: zero.agent.getPairedDevice(env)?.name || null });
+    }
+
+    if (req.method === 'OPTIONS' && url.pathname === '/zero/preflight') {
+      res.writeHead(204, preflightHeaders);
+      return res.end();
+    }
+
+    if (req.method === 'GET' && url.pathname === '/zero/preflight') {
+      const ticket = url.searchParams.get('ticket') || '';
+      const device = zero.agent.getPairedDevice(env);
+      if (!ticket) return preflightJson(res, 400, { ok: false, state: 'ticket_required', reported: false });
+      if (!device?.server) return preflightJson(res, 503, { ok: false, state: 'agent_unpaired', reported: false });
+      let auth;
+      try {
+        auth = zero.chatgptAuth.status({ env });
+      } catch {
+        let reported = false;
+        try {
+          await reportReadiness({
+            device, ticket, state: 'runtime_unavailable', errorCode: 'CHATGPT_RUNTIME_UNAVAILABLE',
+            checks: { local: 'ready', agent: 'ready', runtime: 'unavailable', auth: 'unknown' }
+          });
+          reported = true;
+        } catch {}
+        return preflightJson(res, 503, { ok: false, state: 'runtime_unavailable', reported });
+      }
+      const valid = Boolean(auth?.auth?.present && auth.auth.status === 'valid');
+      const state = valid ? 'auth_valid' : 'auth_required';
+      try {
+        await reportReadiness({
+          device, ticket, state,
+          checks: { local: 'ready', agent: 'ready', runtime: 'ready', auth: valid ? 'valid' : 'required' }
+        });
+      } catch {
+        return preflightJson(res, 502, { ok: false, state: 'core_report_failed', reported: false });
+      }
+      return preflightJson(res, 200, { ok: true, state: 'reported' });
+    }
+
+    if (req.method === 'GET' && url.pathname === '/zero/login') {
+      const ticket = url.searchParams.get('ticket') || '';
+      const device = zero.agent.getPairedDevice(env);
+      if (!ticket) return html(res, 400, '<h1>Missing Zero setup ticket</h1>');
+      if (!device?.server) return html(res, 503, '<h1>Zero Agent is not paired</h1>');
+
+      let existingAuth;
+      try { existingAuth = zero.chatgptAuth.status({ env }); } catch {
+        await reportFailure({ device, ticket, code: 'CHATGPT_RUNTIME_UNAVAILABLE' });
+        return html(res, 502, '<h1>ChatGPT runtime unavailable</h1>');
+      }
+      if (!existingAuth.auth.present || existingAuth.auth.status !== 'valid') {
+        try {
+          await reportReadiness({
+            device, ticket, state: 'auth_checking',
+            checks: { local: 'ready', agent: 'ready', runtime: 'ready', auth: 'checking' }
+          });
+          const sessionResult = await loadSessionProvider(env).fetchSession({ env });
+          zero.chatgptAuth.importAuth({
+            input: JSON.stringify(sessionResult.body),
+            env,
+            source: 'zero-agent-session-api'
+          });
+        } catch (error) {
+          const rawCode = String(error.code || 'CHATGPT_SESSION_FETCH_FAILED');
+          await reportFailure({ device, ticket, code: rawCode });
+          return html(res, 502, `<h1>ChatGPT session fetch failed</h1><p>${htmlEscape(rawCode)}</p>`);
+        }
+      }
+
+      const auth = zero.chatgptAuth.status({ env });
+      try {
+        await reportCompletion({ device, ticket, authStatus: auth.auth.status || 'unknown' });
+      } catch {
+        return html(res, 502, '<!doctype html><html><head><meta charset="utf-8"><title>Zero Login Failed</title></head><body><h1>Zero login failed</h1><p>ZERO_SETUP_COMPLETE_FAILED</p></body></html>');
+      }
+      return html(res, 200, `<!doctype html><html><head><meta charset="utf-8"><title>Zero Connected</title></head><body><h1>Zero connected</h1><p>Device: ${htmlEscape(device.name || 'unknown')}</p><p>ChatGPT auth: ${htmlEscape(auth.auth.status || 'unknown')}</p><script>history.replaceState(null,'','/zero/login');setTimeout(()=>window.close(),450);</script></body></html>`);
+    }
+
+    if (req.method !== 'POST' || url.pathname !== '/zero/action') {
+      return json(res, 404, { ok: false, error: 'NOT_FOUND' });
+    }
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      try {
+        const task = JSON.parse(body || '{}');
+        json(res, 200, { ok: true, result: zero.agent.executeTask(task, env) });
+      } catch (error) {
+        json(res, 400, { ok: false, error: { code: error.code || 'LOCAL_ACTION_ERROR', message: error.message || String(error) } });
+      }
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(listenPort, '127.0.0.1', () => resolve({ server, port: server.address().port }));
+  });
+};

package/src/local-tools.js

@@ -1,205 +1,205 @@
-'use strict';
-
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const readFileModule = require('./command/filesystem/read-file');
-
-const textDecoder = new TextDecoder('utf-8', { fatal: false });
-const err = (code, message) => Object.assign(new Error(message), { code });
-const normalize = (value) => path.resolve(String(value)).toLowerCase();
-
-const rootsFor = (env = process.env) => {
-  const configured = String(env.ZERO_AGENT_ROOTS || '')
-    .split(';')
-    .map((item) => item.trim())
-    .filter(Boolean);
-  const roots = configured.length ? configured : [os.homedir(), process.cwd()];
-  return roots.map((item) => path.resolve(item));
-};
-
-const resolveAllowed = (inputPath, env = process.env) => {
-  if (!inputPath || typeof inputPath !== 'string') throw err('INVALID_PATH', 'path is required');
-  const roots = rootsFor(env);
-  const target = path.resolve(inputPath);
-  const targetNorm = normalize(target);
-  const ok = roots.some((root) => {
-    const rootNorm = normalize(root);
-    return targetNorm === rootNorm || targetNorm.startsWith(rootNorm + path.sep.toLowerCase());
-  });
-  if (!ok) throw err('PATH_NOT_ALLOWED', 'path is outside agent allowed roots');
-  return target;
-};
-
-const readUtf8 = (file) => {
-  const data = fs.readFileSync(file);
-  if (data.includes(0)) throw err('BINARY_FILE', 'binary file is not supported');
-  return textDecoder.decode(data);
-};
-
-const entry = (fullPath, root) => {
-  const stat = fs.statSync(fullPath);
-  return {
-    path: fullPath,
-    relativePath: path.relative(root, fullPath).replace(/\\/g, '/'),
-    type: stat.isDirectory() ? 'directory' : 'file',
-    size: stat.size
-  };
-};
-
-const walk = (root, options = {}) => {
-  const depth = options.depth ?? Infinity;
-  const filesOnly = options.filesOnly === true;
-  const out = [];
-  const visit = (dir, level) => {
-    if (level > depth) return;
-    for (const name of fs.readdirSync(dir)) {
-      const full = path.join(dir, name);
-      const item = entry(full, root);
-      if (!filesOnly || item.type === 'file') out.push(item);
-      if (item.type === 'directory') visit(full, level + 1);
-    }
-  };
-  visit(root, 1);
-  return out;
-};
-
-const wildcard = (pattern) => new RegExp('^' + String(pattern)
-  .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-  .replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i');
-
-const numbered = (lines, startIndex) => lines
-  .map((line, index) => String(startIndex + index + 1).padStart(4, ' ') + '\t' + line)
-  .join('\n');
-
-const listDirectory = (args, env) => {
-  const root = resolveAllowed(args.path, env);
-  const depth = Math.max(1, Math.min(args.depth || 2, 5));
-  return { ok: true, path: root, depth, entries: walk(root, { depth }) };
-};
-
-const getFileInfo = (args, env) => {
-  const target = resolveAllowed(args.path, env);
-  const stat = fs.statSync(target);
-  return {
-    ok: true,
-    path: target,
-    type: stat.isDirectory() ? 'directory' : 'file',
-    size: stat.size,
-    createdAt: stat.birthtime.toISOString(),
-    modifiedAt: stat.mtime.toISOString(),
-    lineCount: stat.isFile() ? readUtf8(target).split(/\r?\n/).length : null
-  };
-};
-
-const readFiles = (args = {}, env) => {
-  const requests = Array.isArray(args.files) && args.files.length
-    ? args.files.map((item) => ({ path: item.path, offset: item.offset, length: item.length }))
-    : (Array.isArray(args.paths) ? args.paths : []).map((inputPath) => ({ path: inputPath, offset: args.offset, length: args.length }));
-  if (!requests.length) throw err('INVALID_PATHS', 'paths or files must contain at least one file');
-  if (requests.length > 50) throw err('TOO_MANY_PATHS', 'readFiles supports up to 50 files');
-  const files = requests.map((request) => {
-    try { return readFileModule.readFile(request, { env }); }
-    catch (error) { return { ok: false, path: String(request.path), error: { code: error.code || 'READ_FAILED', message: error.message || String(error) } }; }
-  });
-  const succeeded = files.filter((item) => item.ok).length;
-  return { ok: succeeded === files.length, count: files.length, succeeded, failed: files.length - succeeded, files };
-};
-
-const writeFile = (args, env) => {
-  const file = resolveAllowed(args.path, env);
-  const mode = args.mode === 'append' ? 'append' : 'overwrite';
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  const data = String(args.content ?? '');
-  if (mode === 'append') fs.appendFileSync(file, data, 'utf8');
-  else fs.writeFileSync(file, data, 'utf8');
-  return { ok: true, path: file, mode, bytes: Buffer.byteLength(data) };
-};
-
-const replaceFile = (args, env) => {
-  const file = resolveAllowed(args.path, env);
-  const oldString = String(args.oldString ?? '');
-  if (!oldString) throw err('INVALID_REPLACE', 'oldString must not be empty');
-  const newString = String(args.newString ?? '');
-  const text = readUtf8(file);
-  const replacements = text.split(oldString).length - 1;
-  if (Number.isInteger(args.expectedReplacements) && replacements !== args.expectedReplacements) {
-    throw err('REPLACE_COUNT_MISMATCH', `expected ${args.expectedReplacements} replacements, got ${replacements}`);
-  }
-  fs.writeFileSync(file, text.split(oldString).join(newString), 'utf8');
-  return { ok: true, path: file, replacements };
-};
-
-const createDirectory = (args, env) => {
-  const dir = resolveAllowed(args.path, env);
-  fs.mkdirSync(dir, { recursive: true });
-  return { ok: true, path: dir, created: fs.existsSync(dir) && fs.statSync(dir).isDirectory() };
-};
-
-const deleteFile = (args, env) => {
-  const file = resolveAllowed(args.path, env);
-  if (!fs.existsSync(file)) throw err('FILE_NOT_FOUND', 'file does not exist');
-  const stat = fs.statSync(file);
-  if (!stat.isFile()) throw err('NOT_A_FILE', 'deleteFile supports files only');
-  fs.unlinkSync(file);
-  return { ok: true, path: file, deleted: true };
-};
-
-const globFiles = (args, env) => {
-  const root = resolveAllowed(args.path, env);
-  const rx = wildcard(args.pattern || '*');
-  const max = Math.max(1, Math.min(args.maxResults || 200, 1000));
-  const files = walk(root, { filesOnly: true })
-    .filter((item) => rx.test(path.basename(item.path)) || rx.test(item.relativePath))
-    .slice(0, max);
-  return { ok: true, path: root, pattern: args.pattern, files };
-};
-
-const grepFiles = (args, env) => {
-  const root = resolveAllowed(args.path, env);
-  const max = Math.max(1, Math.min(args.maxResults || 200, 1000));
-  const rx = args.literal ? null : new RegExp(String(args.pattern), 'i');
-  const fileRx = args.filePattern ? wildcard(args.filePattern) : null;
-  const matches = [];
-  for (const file of walk(root, { filesOnly: true })) {
-    if (fileRx && !fileRx.test(path.basename(file.path)) && !fileRx.test(file.relativePath)) continue;
-    let text;
-    try { text = readUtf8(file.path); } catch { continue; }
-    const lines = text.split(/\r?\n/);
-    for (let index = 0; index < lines.length; index += 1) {
-      const line = lines[index];
-      const hit = args.literal ? line.includes(String(args.pattern)) : rx.test(line);
-      if (!hit) continue;
-      matches.push({ path: file.path, relativePath: file.relativePath, line: index + 1, text: line });
-      if (matches.length >= max) return { ok: true, path: root, pattern: args.pattern, matches };
-    }
-  }
-  return { ok: true, path: root, pattern: args.pattern, matches };
-};
-
-const handlers = { readFile: (args, env) => readFileModule.readFile(args, { env }), readFiles, writeFile, replaceFile, createDirectory, deleteFile, listDirectory, getFileInfo, globFiles, grepFiles };
-
-const schemaObject = (properties, required = []) => ({ type: 'object', properties, required });
-const toolSchemas = [
-  { name: 'listDirectory', description: 'List files and folders inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, depth: { type: 'number' } }, ['path']) },
-  { name: 'getFileInfo', description: 'Get metadata for a file or directory inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' } }, ['path']) },
-  { name: 'readFile', description: readFileModule.descriptor.description, inputSchema: readFileModule.descriptor.inputSchema },
-  { name: 'readFiles', description: 'Read multiple UTF-8 text files inside ZERO_AGENT_ROOTS. Accept paths[] or files[].', inputSchema: schemaObject({ paths: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 50 }, files: { type: 'array', minItems: 1, maxItems: 50, items: schemaObject({ path: { type: 'string' }, offset: { type: 'number' }, length: { type: 'number' } }, ['path']) }, offset: { type: 'number' }, length: { type: 'number' } }) },
-  { name: 'writeFile', description: 'Write or append a UTF-8 text file inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, content: { type: 'string' }, mode: { type: 'string', enum: ['overwrite', 'append'] } }, ['path', 'content']) },
-  { name: 'replaceFile', description: 'Replace exact text inside a UTF-8 file in ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, oldString: { type: 'string' }, newString: { type: 'string' }, expectedReplacements: { type: 'number' } }, ['path', 'oldString', 'newString']) },
-  { name: 'createDirectory', description: 'Create a directory recursively inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' } }, ['path']) },
-  { name: 'deleteFile', description: 'Delete one file inside ZERO_AGENT_ROOTS. Directories are rejected.', inputSchema: schemaObject({ path: { type: 'string' } }, ['path']) },
-  { name: 'globFiles', description: 'Find files by wildcard pattern inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, pattern: { type: 'string' }, maxResults: { type: 'number' } }, ['path']) },
-  { name: 'grepFiles', description: 'Search text files inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, pattern: { type: 'string' }, literal: { type: 'boolean' }, filePattern: { type: 'string' }, maxResults: { type: 'number' } }, ['path', 'pattern']) }
-];
-
-const execute = (tool, args = {}, env = process.env) => {
-  const cleanTool = String(tool || '').replace(/^zero\.command\./, '').replace(/^command\./, '');
-  const handler = handlers[cleanTool];
-  if (!handler) throw err('UNKNOWN_AGENT_TOOL', 'unknown or unsafe agent tool: ' + tool);
-  return handler(args, env);
-};
-const listTools = () => toolSchemas.map((tool) => ({ ...tool }));
-
-const localTools = { execute, listTools, _private: { rootsFor, resolveAllowed, wildcard } };
-Object.assign(exports, localTools);
+'use strict';
+
+const zero = require('./zero');
+
+
+const textDecoder = new TextDecoder('utf-8', { fatal: false });
+const err = (code, message) => Object.assign(new Error(message), { code });
+const normalize = (value) => zero.path.resolve(String(value)).toLowerCase();
+
+const rootsFor = (env = process.env) => {
+  const configured = String(env.ZERO_AGENT_ROOTS || '')
+    .split(';')
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const roots = configured.length ? configured : [zero.os.homedir(), process.cwd()];
+  return roots.map((item) => zero.path.resolve(item));
+};
+
+const resolveAllowed = (inputPath, env = process.env) => {
+  if (!inputPath || typeof inputPath !== 'string') throw err('INVALID_PATH', 'path is required');
+  const roots = rootsFor(env);
+  const target = zero.path.resolve(inputPath);
+  const targetNorm = normalize(target);
+  const ok = roots.some((root) => {
+    const rootNorm = normalize(root);
+    return targetNorm === rootNorm || targetNorm.startsWith(rootNorm + zero.path.sep.toLowerCase());
+  });
+  if (!ok) throw err('PATH_NOT_ALLOWED', 'path is outside agent allowed roots');
+  return target;
+};
+
+const readUtf8 = (file) => {
+  const data = zero.fs.readFileSync(file);
+  if (data.includes(0)) throw err('BINARY_FILE', 'binary file is not supported');
+  return textDecoder.decode(data);
+};
+
+const entry = (fullPath, root) => {
+  const stat = zero.fs.statSync(fullPath);
+  return {
+    path: fullPath,
+    relativePath: zero.path.relative(root, fullPath).replace(/\\/g, '/'),
+    type: stat.isDirectory() ? 'directory' : 'file',
+    size: stat.size
+  };
+};
+
+const walk = (root, options = {}) => {
+  const depth = options.depth ?? Infinity;
+  const filesOnly = options.filesOnly === true;
+  const out = [];
+  const visit = (dir, level) => {
+    if (level > depth) return;
+    for (const name of zero.fs.readdirSync(dir)) {
+      const full = zero.path.join(dir, name);
+      const item = entry(full, root);
+      if (!filesOnly || item.type === 'file') out.push(item);
+      if (item.type === 'directory') visit(full, level + 1);
+    }
+  };
+  visit(root, 1);
+  return out;
+};
+
+const wildcard = (pattern) => new RegExp('^' + String(pattern)
+  .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  .replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i');
+
+const numbered = (lines, startIndex) => lines
+  .map((line, index) => String(startIndex + index + 1).padStart(4, ' ') + '\t' + line)
+  .join('\n');
+
+const listDirectory = (args, env) => {
+  const root = resolveAllowed(args.path, env);
+  const depth = Math.max(1, Math.min(args.depth || 2, 5));
+  return { ok: true, path: root, depth, entries: walk(root, { depth }) };
+};
+
+const getFileInfo = (args, env) => {
+  const target = resolveAllowed(args.path, env);
+  const stat = zero.fs.statSync(target);
+  return {
+    ok: true,
+    path: target,
+    type: stat.isDirectory() ? 'directory' : 'file',
+    size: stat.size,
+    createdAt: stat.birthtime.toISOString(),
+    modifiedAt: stat.mtime.toISOString(),
+    lineCount: stat.isFile() ? readUtf8(target).split(/\r?\n/).length : null
+  };
+};
+
+const readFiles = (args = {}, env) => {
+  const requests = Array.isArray(args.files) && args.files.length
+    ? args.files.map((item) => ({ path: item.path, offset: item.offset, length: item.length }))
+    : (Array.isArray(args.paths) ? args.paths : []).map((inputPath) => ({ path: inputPath, offset: args.offset, length: args.length }));
+  if (!requests.length) throw err('INVALID_PATHS', 'paths or files must contain at least one file');
+  if (requests.length > 50) throw err('TOO_MANY_PATHS', 'readFiles supports up to 50 files');
+  const files = requests.map((request) => {
+    try { return zero.readFileTool.readFile(request, { env }); }
+    catch (error) { return { ok: false, path: String(request.path), error: { code: error.code || 'READ_FAILED', message: error.message || String(error) } }; }
+  });
+  const succeeded = files.filter((item) => item.ok).length;
+  return { ok: succeeded === files.length, count: files.length, succeeded, failed: files.length - succeeded, files };
+};
+
+const writeFile = (args, env) => {
+  const file = resolveAllowed(args.path, env);
+  const mode = args.mode === 'append' ? 'append' : 'overwrite';
+  zero.fs.mkdirSync(zero.path.dirname(file), { recursive: true });
+  const data = String(args.content ?? '');
+  if (mode === 'append') zero.fs.appendFileSync(file, data, 'utf8');
+  else zero.fs.writeFileSync(file, data, 'utf8');
+  return { ok: true, path: file, mode, bytes: Buffer.byteLength(data) };
+};
+
+const replaceFile = (args, env) => {
+  const file = resolveAllowed(args.path, env);
+  const oldString = String(args.oldString ?? '');
+  if (!oldString) throw err('INVALID_REPLACE', 'oldString must not be empty');
+  const newString = String(args.newString ?? '');
+  const text = readUtf8(file);
+  const replacements = text.split(oldString).length - 1;
+  if (Number.isInteger(args.expectedReplacements) && replacements !== args.expectedReplacements) {
+    throw err('REPLACE_COUNT_MISMATCH', `expected ${args.expectedReplacements} replacements, got ${replacements}`);
+  }
+  zero.fs.writeFileSync(file, text.split(oldString).join(newString), 'utf8');
+  return { ok: true, path: file, replacements };
+};
+
+const createDirectory = (args, env) => {
+  const dir = resolveAllowed(args.path, env);
+  zero.fs.mkdirSync(dir, { recursive: true });
+  return { ok: true, path: dir, created: zero.fs.existsSync(dir) && zero.fs.statSync(dir).isDirectory() };
+};
+
+const deleteFile = (args, env) => {
+  const file = resolveAllowed(args.path, env);
+  if (!zero.fs.existsSync(file)) throw err('FILE_NOT_FOUND', 'file does not exist');
+  const stat = zero.fs.statSync(file);
+  if (!stat.isFile()) throw err('NOT_A_FILE', 'deleteFile supports files only');
+  zero.fs.unlinkSync(file);
+  return { ok: true, path: file, deleted: true };
+};
+
+const globFiles = (args, env) => {
+  const root = resolveAllowed(args.path, env);
+  const rx = wildcard(args.pattern || '*');
+  const max = Math.max(1, Math.min(args.maxResults || 200, 1000));
+  const files = walk(root, { filesOnly: true })
+    .filter((item) => rx.test(zero.path.basename(item.path)) || rx.test(item.relativePath))
+    .slice(0, max);
+  return { ok: true, path: root, pattern: args.pattern, files };
+};
+
+const grepFiles = (args, env) => {
+  const root = resolveAllowed(args.path, env);
+  const max = Math.max(1, Math.min(args.maxResults || 200, 1000));
+  const rx = args.literal ? null : new RegExp(String(args.pattern), 'i');
+  const fileRx = args.filePattern ? wildcard(args.filePattern) : null;
+  const matches = [];
+  for (const file of walk(root, { filesOnly: true })) {
+    if (fileRx && !fileRx.test(zero.path.basename(file.path)) && !fileRx.test(file.relativePath)) continue;
+    let text;
+    try { text = readUtf8(file.path); } catch { continue; }
+    const lines = text.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      const hit = args.literal ? line.includes(String(args.pattern)) : rx.test(line);
+      if (!hit) continue;
+      matches.push({ path: file.path, relativePath: file.relativePath, line: index + 1, text: line });
+      if (matches.length >= max) return { ok: true, path: root, pattern: args.pattern, matches };
+    }
+  }
+  return { ok: true, path: root, pattern: args.pattern, matches };
+};
+
+const handlers = { readFile: (args, env) => zero.readFileTool.readFile(args, { env }), readFiles, writeFile, replaceFile, createDirectory, deleteFile, listDirectory, getFileInfo, globFiles, grepFiles };
+
+const schemaObject = (properties, required = []) => ({ type: 'object', properties, required });
+const toolSchemas = [
+  { name: 'listDirectory', description: 'List files and folders inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, depth: { type: 'number' } }, ['path']) },
+  { name: 'getFileInfo', description: 'Get metadata for a file or directory inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' } }, ['path']) },
+  { name: 'readFile', description: zero.readFileTool.descriptor.description, inputSchema: zero.readFileTool.descriptor.inputSchema },
+  { name: 'readFiles', description: 'Read multiple UTF-8 text files inside ZERO_AGENT_ROOTS. Accept paths[] or files[].', inputSchema: schemaObject({ paths: { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 50 }, files: { type: 'array', minItems: 1, maxItems: 50, items: schemaObject({ path: { type: 'string' }, offset: { type: 'number' }, length: { type: 'number' } }, ['path']) }, offset: { type: 'number' }, length: { type: 'number' } }) },
+  { name: 'writeFile', description: 'Write or append a UTF-8 text file inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, content: { type: 'string' }, mode: { type: 'string', enum: ['overwrite', 'append'] } }, ['path', 'content']) },
+  { name: 'replaceFile', description: 'Replace exact text inside a UTF-8 file in ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, oldString: { type: 'string' }, newString: { type: 'string' }, expectedReplacements: { type: 'number' } }, ['path', 'oldString', 'newString']) },
+  { name: 'createDirectory', description: 'Create a directory recursively inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' } }, ['path']) },
+  { name: 'deleteFile', description: 'Delete one file inside ZERO_AGENT_ROOTS. Directories are rejected.', inputSchema: schemaObject({ path: { type: 'string' } }, ['path']) },
+  { name: 'globFiles', description: 'Find files by wildcard pattern inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, pattern: { type: 'string' }, maxResults: { type: 'number' } }, ['path']) },
+  { name: 'grepFiles', description: 'Search text files inside ZERO_AGENT_ROOTS.', inputSchema: schemaObject({ path: { type: 'string' }, pattern: { type: 'string' }, literal: { type: 'boolean' }, filePattern: { type: 'string' }, maxResults: { type: 'number' } }, ['path', 'pattern']) }
+];
+
+exports.execute = (tool, args = {}, env = process.env) => {
+  const cleanTool = String(tool || '').replace(/^zero\.command\./, '').replace(/^command\./, '');
+  const handler = handlers[cleanTool];
+  if (!handler) throw err('UNKNOWN_AGENT_TOOL', 'unknown or unsafe agent tool: ' + tool);
+  return handler(args, env);
+};
+exports.listTools = () => toolSchemas.map((tool) => ({ ...tool }));
+
+exports._private = {};
+exports._private.rootsFor = rootsFor;
+exports._private.resolveAllowed = resolveAllowed;
+exports._private.wildcard = wildcard;