codeply-cli 0.5.6 → 0.6.0

package/lib/mcp.js

@@ -1,258 +1,258 @@
-/**
- * A small Model Context Protocol client: enough to connect to MCP servers,
- * list their tools and call them. No SDK dependency; MCP is JSON-RPC 2.0
- * over either a child process's stdio (one JSON message per line) or HTTP
- * ("streamable HTTP": POST a request, get JSON or an SSE stream back).
- *
- * Servers are configured in the same shape Claude Desktop / Cursor use, so an
- * existing config can be pasted in:
- *
- *   ~/.codeply/mcp.json            (every project)
- *   <project>/.codeply/mcp.json    (this project; same name wins)
- *
- *   { "mcpServers": {
- *       "github":  { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } },
- *       "docs":    { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." } },
- *       "old":     { "command": "...", "disabled": true } } }
- *
- * Connections are kept for the life of the process and reused across turns.
- */
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawn } = require('child_process');
-const plugins = require('./plugins.js');
-
-const PROTOCOL_VERSION = '2025-06-18';
-const CONNECT_TIMEOUT_MS = 20000;
-const CALL_TIMEOUT_MS = 120000;
-const CLIENT_INFO = { name: 'codeply', version: '1.0' };
-
-function readConfig(file) {
-  try {
-    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return j.mcpServers || j.servers || {};
-  } catch { return {}; }
-}
-
-/** Merged server config for a project: project entries override global ones. */
-function loadServers(cwd) {
-  const merged = { ...plugins.mcpServers(cwd), ...readConfig(path.join(os.homedir(), '.codeply', 'mcp.json')) };
-  if (cwd) Object.assign(merged, readConfig(path.join(cwd, '.codeply', 'mcp.json')));
-  return Object.fromEntries(Object.entries(merged).filter(([, s]) => s && !s.disabled && (s.command || s.url)));
-}
-
-// ─── Transports ─────────────────────────────────────────────────────────────
-
-class StdioConnection {
-  constructor(name, spec, cwd) {
-    this.name = name;
-    this.pending = new Map();
-    this.nextId = 1;
-    this.stderr = '';
-    // npx/npm/uvx are .cmd shims on Windows and only start through a shell.
-    // A full path to a program (which may contain spaces) is started
-    // directly. Through the shell, arguments are quoted here, since Node
-    // just joins them with spaces.
-    const cmd = String(spec.command);
-    const args = (spec.args || []).map(String);
-    const viaShell = process.platform === 'win32' && !/[\\/]/.test(cmd) && !/\.exe$/i.test(cmd);
-    const quote = (a) => (/[\s"&|<>^()]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a);
-    this.proc = spawn(viaShell ? [cmd, ...args].map(quote).join(' ') : cmd, viaShell ? [] : args, {
-      cwd: spec.cwd || cwd || process.cwd(),
-      env: { ...process.env, ...(spec.env || {}) },
-      stdio: ['pipe', 'pipe', 'pipe'],
-      windowsHide: true,
-      shell: viaShell,
-    });
-    let buf = '';
-    this.proc.stdout.on('data', (d) => {
-      buf += d.toString('utf8');
-      let nl;
-      while ((nl = buf.indexOf('\n')) !== -1) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (!line) continue;
-        let msg;
-        try { msg = JSON.parse(line); } catch { continue; } // servers sometimes log to stdout
-        this.onMessage(msg);
-      }
-    });
-    this.proc.stderr.on('data', (d) => { this.stderr = (this.stderr + d.toString('utf8')).slice(-4000); });
-    this.proc.on('error', (e) => this.failAll(`could not start: ${e.message}`));
-    this.proc.on('exit', (code) => { this.closed = true; this.failAll(`exited (code ${code})${this.stderr ? `: ${this.stderr.trim().split('\n').slice(-3).join(' ')}` : ''}`); });
-  }
-
-  onMessage(msg) {
-    if (msg.id !== undefined && this.pending.has(msg.id)) {
-      const p = this.pending.get(msg.id);
-      this.pending.delete(msg.id);
-      if (msg.error) p.reject(new Error(msg.error.message || JSON.stringify(msg.error)));
-      else p.resolve(msg.result);
-    } else if (msg.method && msg.id !== undefined) {
-      // A request from the server (sampling, roots...): we offer none of those.
-      this.write({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'Not supported by this client' } });
-    }
-  }
-
-  write(obj) {
-    if (!this.closed) this.proc.stdin.write(JSON.stringify(obj) + '\n');
-  }
-
-  request(method, params, timeoutMs) {
-    return new Promise((resolve, reject) => {
-      if (this.closed) return reject(new Error(`${this.name} is not running`));
-      const id = this.nextId++;
-      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`${method} timed out after ${timeoutMs / 1000}s`)); }, timeoutMs);
-      this.pending.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } });
-      this.write({ jsonrpc: '2.0', id, method, params });
-    });
-  }
-
-  notify(method, params) { this.write({ jsonrpc: '2.0', method, ...(params ? { params } : {}) }); }
-
-  failAll(why) {
-    for (const [, p] of this.pending) p.reject(new Error(`${this.name} ${why}`));
-    this.pending.clear();
-  }
-
-  close() { try { this.proc.kill(); } catch {} }
-}
-
-class HttpConnection {
-  constructor(name, spec) {
-    this.name = name;
-    this.url = spec.url;
-    this.headers = spec.headers || {};
-    this.sessionId = null;
-    this.nextId = 1;
-  }
-
-  async post(body, timeoutMs) {
-    const res = await fetch(this.url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json, text/event-stream',
-        'MCP-Protocol-Version': PROTOCOL_VERSION,
-        ...(this.sessionId ? { 'Mcp-Session-Id': this.sessionId } : {}),
-        ...this.headers,
-      },
-      body: JSON.stringify(body),
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    const sid = res.headers.get('mcp-session-id');
-    if (sid) this.sessionId = sid;
-    return res;
-  }
-
-  async request(method, params, timeoutMs) {
-    const id = this.nextId++;
-    const res = await this.post({ jsonrpc: '2.0', id, method, params }, timeoutMs);
-    if (!res.ok) throw new Error(`${method}: HTTP ${res.status}${res.status === 401 ? ' (needs authorization - add a token under "headers")' : ''}`);
-    const type = res.headers.get('content-type') || '';
-    let msg = null;
-    if (type.includes('text/event-stream')) {
-      // Read events until the one answering our id.
-      const text = await res.text();
-      for (const block of text.split(/\r?\n\r?\n/)) {
-        const data = block.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n');
-        if (!data) continue;
-        try { const m = JSON.parse(data); if (m.id === id) { msg = m; break; } } catch {}
-      }
-    } else {
-      msg = await res.json().catch(() => null);
-    }
-    if (!msg) throw new Error(`${method}: no response`);
-    if (msg.error) throw new Error(msg.error.message || JSON.stringify(msg.error));
-    return msg.result;
-  }
-
-  async notify(method, params) {
-    try { await this.post({ jsonrpc: '2.0', method, ...(params ? { params } : {}) }, 10000); } catch {}
-  }
-
-  close() {}
-}
-
-// ─── Servers ────────────────────────────────────────────────────────────────
-
-const servers = new Map(); // key -> { name, conn, tools, error, specKey }
-
-function specKey(spec) { return JSON.stringify(spec); }
-
-async function connect(name, spec, cwd) {
-  const conn = spec.url ? new HttpConnection(name, spec) : new StdioConnection(name, spec, cwd);
-  try {
-    const init = await conn.request('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO }, CONNECT_TIMEOUT_MS);
-    await conn.notify('notifications/initialized');
-    const tools = [];
-    let cursor;
-    do {
-      const page = await conn.request('tools/list', cursor ? { cursor } : {}, CONNECT_TIMEOUT_MS);
-      tools.push(...(page.tools || []));
-      cursor = page.nextCursor;
-    } while (cursor && tools.length < 500);
-    return { name, conn, tools, instructions: init?.instructions || '', error: null };
-  } catch (e) {
-    conn.close();
-    return { name, conn: null, tools: [], instructions: '', error: e.message };
-  }
-}
-
-/**
- * Connect to every configured server for this project (reusing live
- * connections) and return what they offer. Never throws.
- * @returns {Promise<Array<{name, tools, error, instructions}>>}
- */
-async function listServers(cwd) {
-  const wanted = loadServers(cwd);
-  const out = [];
-  await Promise.all(Object.entries(wanted).map(async ([name, spec]) => {
-    const key = `${cwd}::${name}`;
-    let s = servers.get(key);
-    const stale = s && (s.specKey !== specKey(spec) || (s.conn && s.conn.closed) || s.error);
-    if (!s || stale) {
-      if (s?.conn) s.conn.close();
-      s = { ...(await connect(name, spec, cwd)), specKey: specKey(spec) };
-      servers.set(key, s);
-    }
-    out.push({ name, tools: s.tools, error: s.error, instructions: s.instructions });
-  }));
-  return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/** Tool results as plain text for the model, images kept aside as data URLs. */
-function flattenResult(result) {
-  const parts = Array.isArray(result?.content) ? result.content : [];
-  const text = [];
-  const images = [];
-  for (const p of parts) {
-    if (p.type === 'text') text.push(p.text);
-    else if (p.type === 'image' && p.data) images.push(`data:${p.mimeType || 'image/png'};base64,${p.data}`);
-    else if (p.type === 'resource') text.push(p.resource?.text || `[resource ${p.resource?.uri || ''}]`);
-    else text.push(`[${p.type} content]`);
-  }
-  if (!parts.length && result?.structuredContent) text.push(JSON.stringify(result.structuredContent, null, 1));
-  return { text: text.join('\n') || '(empty result)', images, isError: !!result?.isError };
-}
-
-async function callTool(cwd, serverName, toolName, args) {
-  const s = servers.get(`${cwd}::${serverName}`);
-  if (!s || !s.conn) throw new Error(`MCP server "${serverName}" is not connected${s?.error ? ` (${s.error})` : ''}.`);
-  const result = await s.conn.request('tools/call', { name: toolName, arguments: args || {} }, CALL_TIMEOUT_MS);
-  return flattenResult(result);
-}
-
-function findTool(cwd, serverName, toolName) {
-  const s = servers.get(`${cwd}::${serverName}`);
-  return s ? s.tools.find((t) => t.name === toolName) || null : null;
-}
-
-function closeAll() {
-  for (const [, s] of servers) if (s.conn) s.conn.close();
-  servers.clear();
-}
-process.on('exit', closeAll);
-
-module.exports = { listServers, callTool, findTool, loadServers, closeAll, flattenResult };
+/**
+ * A small Model Context Protocol client: enough to connect to MCP servers,
+ * list their tools and call them. No SDK dependency; MCP is JSON-RPC 2.0
+ * over either a child process's stdio (one JSON message per line) or HTTP
+ * ("streamable HTTP": POST a request, get JSON or an SSE stream back).
+ *
+ * Servers are configured in the same shape Claude Desktop / Cursor use, so an
+ * existing config can be pasted in:
+ *
+ *   ~/.codeply/mcp.json            (every project)
+ *   <project>/.codeply/mcp.json    (this project; same name wins)
+ *
+ *   { "mcpServers": {
+ *       "github":  { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } },
+ *       "docs":    { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." } },
+ *       "old":     { "command": "...", "disabled": true } } }
+ *
+ * Connections are kept for the life of the process and reused across turns.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const plugins = require('./plugins.js');
+
+const PROTOCOL_VERSION = '2025-06-18';
+const CONNECT_TIMEOUT_MS = 20000;
+const CALL_TIMEOUT_MS = 120000;
+const CLIENT_INFO = { name: 'codeply', version: '1.0' };
+
+function readConfig(file) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return j.mcpServers || j.servers || {};
+  } catch { return {}; }
+}
+
+/** Merged server config for a project: project entries override global ones. */
+function loadServers(cwd) {
+  const merged = { ...plugins.mcpServers(cwd), ...readConfig(path.join(os.homedir(), '.codeply', 'mcp.json')) };
+  if (cwd) Object.assign(merged, readConfig(path.join(cwd, '.codeply', 'mcp.json')));
+  return Object.fromEntries(Object.entries(merged).filter(([, s]) => s && !s.disabled && (s.command || s.url)));
+}
+
+// ─── Transports ─────────────────────────────────────────────────────────────
+
+class StdioConnection {
+  constructor(name, spec, cwd) {
+    this.name = name;
+    this.pending = new Map();
+    this.nextId = 1;
+    this.stderr = '';
+    // npx/npm/uvx are .cmd shims on Windows and only start through a shell.
+    // A full path to a program (which may contain spaces) is started
+    // directly. Through the shell, arguments are quoted here, since Node
+    // just joins them with spaces.
+    const cmd = String(spec.command);
+    const args = (spec.args || []).map(String);
+    const viaShell = process.platform === 'win32' && !/[\\/]/.test(cmd) && !/\.exe$/i.test(cmd);
+    const quote = (a) => (/[\s"&|<>^()]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a);
+    this.proc = spawn(viaShell ? [cmd, ...args].map(quote).join(' ') : cmd, viaShell ? [] : args, {
+      cwd: spec.cwd || cwd || process.cwd(),
+      env: { ...process.env, ...(spec.env || {}) },
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true,
+      shell: viaShell,
+    });
+    let buf = '';
+    this.proc.stdout.on('data', (d) => {
+      buf += d.toString('utf8');
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl).trim();
+        buf = buf.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try { msg = JSON.parse(line); } catch { continue; } // servers sometimes log to stdout
+        this.onMessage(msg);
+      }
+    });
+    this.proc.stderr.on('data', (d) => { this.stderr = (this.stderr + d.toString('utf8')).slice(-4000); });
+    this.proc.on('error', (e) => this.failAll(`could not start: ${e.message}`));
+    this.proc.on('exit', (code) => { this.closed = true; this.failAll(`exited (code ${code})${this.stderr ? `: ${this.stderr.trim().split('\n').slice(-3).join(' ')}` : ''}`); });
+  }
+
+  onMessage(msg) {
+    if (msg.id !== undefined && this.pending.has(msg.id)) {
+      const p = this.pending.get(msg.id);
+      this.pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+      else p.resolve(msg.result);
+    } else if (msg.method && msg.id !== undefined) {
+      // A request from the server (sampling, roots...): we offer none of those.
+      this.write({ jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: 'Not supported by this client' } });
+    }
+  }
+
+  write(obj) {
+    if (!this.closed) this.proc.stdin.write(JSON.stringify(obj) + '\n');
+  }
+
+  request(method, params, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      if (this.closed) return reject(new Error(`${this.name} is not running`));
+      const id = this.nextId++;
+      const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`${method} timed out after ${timeoutMs / 1000}s`)); }, timeoutMs);
+      this.pending.set(id, { resolve: (v) => { clearTimeout(timer); resolve(v); }, reject: (e) => { clearTimeout(timer); reject(e); } });
+      this.write({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  notify(method, params) { this.write({ jsonrpc: '2.0', method, ...(params ? { params } : {}) }); }
+
+  failAll(why) {
+    for (const [, p] of this.pending) p.reject(new Error(`${this.name} ${why}`));
+    this.pending.clear();
+  }
+
+  close() { try { this.proc.kill(); } catch {} }
+}
+
+class HttpConnection {
+  constructor(name, spec) {
+    this.name = name;
+    this.url = spec.url;
+    this.headers = spec.headers || {};
+    this.sessionId = null;
+    this.nextId = 1;
+  }
+
+  async post(body, timeoutMs) {
+    const res = await fetch(this.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+        'MCP-Protocol-Version': PROTOCOL_VERSION,
+        ...(this.sessionId ? { 'Mcp-Session-Id': this.sessionId } : {}),
+        ...this.headers,
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const sid = res.headers.get('mcp-session-id');
+    if (sid) this.sessionId = sid;
+    return res;
+  }
+
+  async request(method, params, timeoutMs) {
+    const id = this.nextId++;
+    const res = await this.post({ jsonrpc: '2.0', id, method, params }, timeoutMs);
+    if (!res.ok) throw new Error(`${method}: HTTP ${res.status}${res.status === 401 ? ' (needs authorization - add a token under "headers")' : ''}`);
+    const type = res.headers.get('content-type') || '';
+    let msg = null;
+    if (type.includes('text/event-stream')) {
+      // Read events until the one answering our id.
+      const text = await res.text();
+      for (const block of text.split(/\r?\n\r?\n/)) {
+        const data = block.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).trim()).join('\n');
+        if (!data) continue;
+        try { const m = JSON.parse(data); if (m.id === id) { msg = m; break; } } catch {}
+      }
+    } else {
+      msg = await res.json().catch(() => null);
+    }
+    if (!msg) throw new Error(`${method}: no response`);
+    if (msg.error) throw new Error(msg.error.message || JSON.stringify(msg.error));
+    return msg.result;
+  }
+
+  async notify(method, params) {
+    try { await this.post({ jsonrpc: '2.0', method, ...(params ? { params } : {}) }, 10000); } catch {}
+  }
+
+  close() {}
+}
+
+// ─── Servers ────────────────────────────────────────────────────────────────
+
+const servers = new Map(); // key -> { name, conn, tools, error, specKey }
+
+function specKey(spec) { return JSON.stringify(spec); }
+
+async function connect(name, spec, cwd) {
+  const conn = spec.url ? new HttpConnection(name, spec) : new StdioConnection(name, spec, cwd);
+  try {
+    const init = await conn.request('initialize', { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO }, CONNECT_TIMEOUT_MS);
+    await conn.notify('notifications/initialized');
+    const tools = [];
+    let cursor;
+    do {
+      const page = await conn.request('tools/list', cursor ? { cursor } : {}, CONNECT_TIMEOUT_MS);
+      tools.push(...(page.tools || []));
+      cursor = page.nextCursor;
+    } while (cursor && tools.length < 500);
+    return { name, conn, tools, instructions: init?.instructions || '', error: null };
+  } catch (e) {
+    conn.close();
+    return { name, conn: null, tools: [], instructions: '', error: e.message };
+  }
+}
+
+/**
+ * Connect to every configured server for this project (reusing live
+ * connections) and return what they offer. Never throws.
+ * @returns {Promise<Array<{name, tools, error, instructions}>>}
+ */
+async function listServers(cwd) {
+  const wanted = loadServers(cwd);
+  const out = [];
+  await Promise.all(Object.entries(wanted).map(async ([name, spec]) => {
+    const key = `${cwd}::${name}`;
+    let s = servers.get(key);
+    const stale = s && (s.specKey !== specKey(spec) || (s.conn && s.conn.closed) || s.error);
+    if (!s || stale) {
+      if (s?.conn) s.conn.close();
+      s = { ...(await connect(name, spec, cwd)), specKey: specKey(spec) };
+      servers.set(key, s);
+    }
+    out.push({ name, tools: s.tools, error: s.error, instructions: s.instructions });
+  }));
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Tool results as plain text for the model, images kept aside as data URLs. */
+function flattenResult(result) {
+  const parts = Array.isArray(result?.content) ? result.content : [];
+  const text = [];
+  const images = [];
+  for (const p of parts) {
+    if (p.type === 'text') text.push(p.text);
+    else if (p.type === 'image' && p.data) images.push(`data:${p.mimeType || 'image/png'};base64,${p.data}`);
+    else if (p.type === 'resource') text.push(p.resource?.text || `[resource ${p.resource?.uri || ''}]`);
+    else text.push(`[${p.type} content]`);
+  }
+  if (!parts.length && result?.structuredContent) text.push(JSON.stringify(result.structuredContent, null, 1));
+  return { text: text.join('\n') || '(empty result)', images, isError: !!result?.isError };
+}
+
+async function callTool(cwd, serverName, toolName, args) {
+  const s = servers.get(`${cwd}::${serverName}`);
+  if (!s || !s.conn) throw new Error(`MCP server "${serverName}" is not connected${s?.error ? ` (${s.error})` : ''}.`);
+  const result = await s.conn.request('tools/call', { name: toolName, arguments: args || {} }, CALL_TIMEOUT_MS);
+  return flattenResult(result);
+}
+
+function findTool(cwd, serverName, toolName) {
+  const s = servers.get(`${cwd}::${serverName}`);
+  return s ? s.tools.find((t) => t.name === toolName) || null : null;
+}
+
+function closeAll() {
+  for (const [, s] of servers) if (s.conn) s.conn.close();
+  servers.clear();
+}
+process.on('exit', closeAll);
+
+module.exports = { listServers, callTool, findTool, loadServers, closeAll, flattenResult };

package/lib/native-tools.mjs

@@ -27,17 +27,21 @@ export const TOOL_DOCS = {
   write_file: { d: 'Create a file or fully rewrite one. For changes to an existing file prefer edit_file.', req: ['path', 'content'], p: { path: 'File path.', content: 'The complete file content, verbatim.' } },
   edit_file: { d: 'Replace one exact block of an existing file.', req: ['path', 'search', 'replace'], p: { path: 'File path.', search: 'Existing text copied exactly from a read (no line-number prefixes), just enough to be unique.', replace: 'The replacement text.', all: '"true" to replace every occurrence (renames).' } },
   search: { d: 'Regex search across project files, or find files by name when only glob is given.', req: [], p: { pattern: 'Case-insensitive regex.', glob: 'Limit to paths like "**/*.ts", or alone to find files by name.', path: 'Folder or single file to search in.', context: 'Lines of surrounding code per hit (0-5).', files_only: '"true" to list matching files with hit counts.' } },
-  run: { d: 'Run a shell command in the project folder on the user\'s machine.', req: ['command'], p: { command: 'The command line.' } },
+  run: { d: 'Run a shell command in the project folder on the user\'s machine.', req: ['command'], p: { command: 'The command line.', background: '"true" for anything that keeps running (dev server, watcher): it starts, returns the first lines and a job id, and keeps going.' } },
+  job: { d: 'A background command started with run background=true: read its latest output, or stop it. No id lists every job.', req: [], p: { id: 'The job id run gave you.', stop: '"true" to stop it.' } },
   use_skill: { d: 'Load a skill\'s full instructions.', req: ['name'], p: { name: 'Skill name from the SKILLS list.' } },
   list_skills: { d: 'Search the full skill library.', req: ['query'], p: { query: 'One or two words.' } },
   fetch_image: { d: 'Download an image into the project.', req: ['url', 'path'], p: { url: 'Image URL.', path: 'Where to save it, e.g. assets/hero.jpg.' } },
   browser_check: { d: 'Open a page in a real browser and get errors plus a screenshot.', req: ['url'], p: { url: 'file:///absolute/path or http://localhost:port.', wait: 'Extra milliseconds to wait before capturing.', viewport: 'desktop (default), tablet, mobile, or WIDTHxHEIGHT.' } },
-  gmail_send: { d: 'Send a real email now. Only when the user asked for it to go out. The user sees it on an editable card first and may change it or save it as a draft instead; the result says what really happened.', req: [], p: { to: 'Recipient address.', subject: 'Subject line.', body: 'Plain-text body.', draft: 'Optional: the id of a draft saved in Codeply (from drafts_list) to send; to/subject/body then come from it.' } },
-  gmail_search: { d: 'Search the connected Gmail account. Leave query empty to list the newest mail.', req: [], p: { query: 'Gmail search syntax, e.g. "is:unread" or "from:x@y.com". Empty = newest mail.' } },
-  gmail_draft: { d: 'Save an email as a draft without sending it: in Gmail\'s Drafts when Gmail is connected, otherwise in Codeply\'s own drafts.', req: [], p: { to: 'Recipient address (optional for a draft).', subject: 'Subject line.', body: 'Plain-text body.' } },
+  gmail_send: { d: 'Send a real email now. Only when the user asked for it to go out. The user sees it on an editable card first and may change it or save it as a draft instead; the result says what really happened.', req: [], p: { to: 'Recipient address.', cc: 'Optional: addresses to copy, comma-separated.', subject: 'Subject line.', body: 'Plain-text body.', draft: 'Optional: the id of a draft saved in Codeply (from drafts_list) to send; to/subject/body then come from it.' } },
+  gmail_search: { d: 'Search the connected Gmail account. Leave query empty to list the newest mail. Results are previews, each with an [id] for gmail_read.', req: [], p: { query: 'Gmail search syntax, e.g. "is:unread" or "from:x@y.com". Empty = newest mail.' } },
+  use_computer: { d: 'Use the mouse and keyboard in another app on this computer (the Claude app, a browser, Excel...) and get a fresh screenshot back after every step. Do it yourself instead of asking the user to click or bring a window forward. Every action names the <window> it is for; it is brought to the front first, and nothing is typed or clicked if it cannot be. Typing, clicking and keys ask the user first unless they allowed it.', req: ['action'], p: { action: 'look (screenshot), focus (bring a window to the front), click, double_click, right_click, type, keys, scroll, or wait.', window: 'A few words of the app name or window title, e.g. "Claude" or "Excel". Needed for everything but look and wait.', x: 'For click and scroll: x on the latest screenshot, in its pixels.', y: 'For click and scroll: y on the latest screenshot.', target: 'What you are clicking, e.g. "New chat button" (shown to the user).', text: 'For type: the text. A newline presses Enter.', keys: 'For keys: enter, tab, escape, ctrl+n, cmd+shift+t...', amount: 'For scroll: clicks, negative scrolls up. Default 3.', seconds: 'For wait: 1 to 30. Waits, then shows the screen.' } },
+  gmail_read: { d: 'Read one whole email (sender, recipients, cc, date and the full body) by its id from gmail_search.', req: ['id'], p: { id: 'The [id] gmail_search showed for the email.' } },
+  gmail_draft: { d: 'Save an email as a draft without sending it: in Gmail\'s Drafts when Gmail is connected, otherwise in Codeply\'s own drafts.', req: [], p: { to: 'Recipient address (optional for a draft).', cc: 'Optional: addresses to copy, comma-separated.', subject: 'Subject line.', body: 'Plain-text body.' } },
   drafts_list: { d: 'List the drafts saved in Codeply (ids, subject, recipient). Send one with gmail_send and its id as draft.', req: [], p: {} },
   calendar_list: { d: 'List events on the user\'s Google Calendar in a time range (default: today). Times are local.', req: [], p: { from: 'Start: today, tomorrow, 2026-10-03 or 2026-10-03T14:00. Default today.', to: 'End (a date means through that whole day). Default: end of the from day.', max: 'Most events to return (1-50, default 20).' } },
-  calendar_add: { d: 'Add an event to the user\'s Google Calendar (asks the user first).', req: ['title', 'start'], p: { title: 'Event title.', start: 'Local start: 2026-10-03T14:00, or 2026-10-03 for an all-day event.', end: 'Local end. Default: one hour after start (all-day: the same day).', description: 'Notes for the event.', location: 'Where it is.', reminders: 'Popup reminders, minutes before, comma-separated, e.g. "10,60".' } },
+  calendar_add: { d: 'Add an event to the user\'s Google Calendar (asks the user first).', req: ['title', 'start'], p: { title: 'Event title.', start: 'Local start: 2026-10-03T14:00, or 2026-10-03 for an all-day event.', end: 'Local end. Default: one hour after start (all-day: the same day).', description: 'Notes for the event.', location: 'Where it is.', reminders: 'Popup reminders, minutes before, comma-separated, e.g. "10,60".', attendees: 'Optional: guest email addresses, comma-separated. They get an invite.' } },
+  calendar_update: { d: 'Move, rename or cancel an event already on the user\'s Google Calendar, by its [id] from calendar_list (asks the user first; guests are told). Use this to change an event, never calendar_add a second one.', req: ['id'], p: { id: 'The event [id] from calendar_list.', start: 'New local start with a time: 2026-10-03T14:00.', end: 'New local end. Default: minutes after start.', minutes: 'Length in minutes when no end is given (default 60).', title: 'New title.', location: 'New place.', description: 'New notes.', cancel: '"yes" to cancel (delete) the event.' } },
   add_model: { d: 'Add a model to the user\'s Codeply model menu when they ask (they give a name, base URL, model id and API key). Asks them first, tests it, saves it on this computer, selects it and syncs it to their phone. Any OpenAI-compatible API works; Ollama on this computer is http://localhost:11434 with no key.', req: ['base_url', 'model'], p: { name: 'Display name, e.g. "GPT-5 mini". Default: the model id.', base_url: 'OpenAI-compatible base URL, e.g. https://api.openai.com/v1, https://api.deepseek.com, https://openrouter.ai/api/v1.', model: 'The model id the provider expects, e.g. gpt-5-mini, deepseek-chat.', api_key: 'The API key the user gave (leave empty for a server with no key).' } },
   slack_post_message: { d: 'Post a real Slack message now. Only when the user asked for it.', req: ['channel', 'text'], p: { channel: 'Channel name or id.', text: 'Message text.' } },
   vercel_deploy: { d: 'Deploy a folder to the connected Vercel account (live, real).', req: [], p: { path: 'Folder to deploy. Default ".".' } },
@@ -46,6 +50,8 @@ export const TOOL_DOCS = {
   github_create_repo: { d: 'Create a GitHub repo in the connected account and push this folder to it.', req: ['name'], p: { path: 'Folder to push. Default ".".', name: 'Repository name.' } },
   design_reference_search: { d: 'Search the local library of real app screenshots for a kind of screen.', req: ['term'], p: { term: 'What the screen is, e.g. "checkout".', category: 'Optional category filter.' } },
   view_images: { d: 'Look at images (e.g. reference screenshots).', req: ['urls'], p: { urls: 'Comma-separated image URLs.' } },
+  design_direction: { d: 'Deal an art direction for a page or app from the codeply-taste research library.', req: [], p: { brief: 'One line: what it is and for whom.', sector: 'e.g. saas, restaurant, consumer-app, portfolio (list=sectors lists them).', tone: 'quiet, bold, warm, technical, playful, luxury or editorial.', sections: 'Comma-separated section roles to plan.', options: '3 to see three directions first.', direction: 'The id of the direction to deal in full.', redraw: 'Re-deal one part: type, palette, hero, photos, section:<role> or direction.', have: 'Assets that really exist: photography, product-photo, product-ui, illustration, video.', keep: 'Parts the brand already fixes: palette, type.', avoid: 'Direction ids to skip.', show: 'true to reprint the saved sheet.', list: 'sectors, directions, roles or tones.', site: 'Print one studied reference site in full.' } },
+  design_lint: { d: 'Check a design against the codeply-taste rules and a real render; returns findings and screenshots.', req: ['path'], p: { path: 'The design file, usually index.html.', kind: 'website, app, slides, doc, poster, social or logo.', widths: 'Optional comma-separated widths to render.', allow: 'Rule ids to allow, each with a reason you can state.' } },
   supabase_api: { d: 'Call the Supabase Management API.', req: ['method', 'path'], p: { method: 'GET, POST, PATCH, PUT or DELETE.', path: 'Path starting with /v1/.', body: 'JSON body.' } },
   supabase_sql: { d: 'Run SQL on a Supabase project database.', req: ['ref', 'query'], p: { ref: 'Project ref.', query: 'SQL.' } },
   vercel_api: { d: 'Call the Vercel REST API.', req: ['method', 'path'], p: { method: 'HTTP method.', path: 'Path like /v9/projects.', body: 'JSON body.' } },
@@ -58,6 +64,12 @@ export const TOOL_DOCS = {
   web_fetch: { d: 'Fetch a web page or API URL and get its content as readable text.', req: ['url'], p: { url: 'http:// or https:// URL.', format: '"text" (default, HTML converted to readable text), "html" or "raw".' } },
   reach_me: { d: 'Reach the user on their phone: how=call rings their phone with your voice (only when it is urgent or they asked for a call), how=text sends a notification (anything else). Now, or later with at.', req: ['how', 'message'], p: { how: 'call or text.', message: 'What to tell them, short and specific.', at: 'Optional: when, like 17:30, 5pm, "in 20 minutes" or an ISO time. Empty means now.', bot: 'Optional: which of the user\'s bots it comes from, by name ("tell Shella to call me" means bot=Shella). Empty means you.' } },
   watch_email: { d: 'Watch the inbox for an email from a sender and reach the user the moment one arrives (works in the background, also with Craft closed to the tray).', req: ['from', 'how'], p: { from: 'The email address, or a domain like example.com.', how: 'call or text, when it arrives.', note: 'Optional: what to say about it.', repeat: 'Optional: yes to alert on every email from them; default is once.' } },
+  look_at_screen: { d: 'See what is on the user\'s screen right now: a screenshot plus the text on it. Call it first whenever they point at something you cannot see in this chat (this, that error, her message, what is on my right, see, reply to him), instead of asking them to paste it.', req: [], p: { why: 'A few words on what you are looking for.', window: 'Optional: a few words of an earlier window or tab title (from the last 12 the user had in front) to see how it looked then, instead of the screen now.' } },
+  life_context: { d: 'Look up the user\'s life context, shared by all their bots: calendar, email (and who is waiting on a reply), calls, plans, projects, what is on their screen, what was heard around them, Slack, bot tasks.', req: [], p: { about: 'now, today, tomorrow, week, person, calls, email, activity, heard, plans, projects, slack, tasks or health (steps, workouts, sleep, if this bot may read it). Leave empty to search with query.', query: 'A name for about=person, or words to search for.' } },
+  remember: { d: 'Save one lasting thing to the user\'s shared Codeply brain (every app and bot reads it): a preference, a fact about them, a routine, how they like to work, a project decision, idea, requirement or to-do, or temporary context. Or remove one with forget.', req: [], p: { kind: 'preference, fact, routine, style, decision, idea, requirement, todo or context (temporary).', slot: 'What it is about in 1 to 4 words, the same each time (reply length, favorite color, auth provider).', value: 'The value in a few words.', text: 'One short third-person sentence, e.g. The user wants short replies.', certainty: 'stated (they said it plainly), implied, temporary, joking (sarcasm, banter: not saved), hypothetical or quoting.', project: 'The project, for decisions, ideas, requirements and to-dos. Default: this folder.', until: 'For context: when it stops being true, in the user\'s local time (17:00 or 2026-10-26T17:00). Better than ttlHours when they said when.', ttlHours: 'For context: how many hours it stays true.', forget: 'A memory id from recall, to remove it instead.' } },
+  recall: { d: 'Search the user\'s shared Codeply brain: their preferences and facts, project decisions and to-dos from any Codeply app, temporary context, lessons other bots learned.', req: [], p: { query: 'Words to look for. Empty lists the newest.', project: 'Only this project.' } },
+  hand_off: { d: 'Pass the part of a job that belongs to another bot (calendar, email, reminders, research...) and carry on without waiting. Send only what they need.', req: ['to', 'intent'], p: { to: 'A bot\'s name, or a domain: calendar, email, reminders, calls, texts, research, code, social, health, money.', intent: 'What they should get done, in one or two sentences.', facts: 'The facts they need, one per line: names, addresses, dates and times with the time zone, ids.', decision: 'What has been decided so far, if anything.' } },
+  bot_email_send: { d: 'Email someone from your own address (not the user\'s Gmail), as the user\'s AI assistant. The user sees and can edit it first unless your settings allow sending alone.', req: ['to', 'body'], p: { to: 'One email address.', subject: 'Subject. For a reply, leave empty to keep the thread\'s subject.', body: 'Plain text. Sign with your own name.', reply_to: 'Optional: the id of the received email you are answering, so it stays in the same thread.' } },
   image_search: { d: 'Search the whole web for real photos (like Google Images). Returns image URLs with sizes; download the one you pick with fetch_image.', req: ['query'], p: { query: 'What the photo should show.', num: 'Number of results (1-16, default 8).' } },
   web_search: { d: 'Search the web for current information (docs, errors, versions, news).', req: ['query'], p: { query: 'The search query.', num: 'Number of results (1-20, default 8).' } },
   apply_patch: { d: 'Change several files at once (add, update, delete, move) with one patch. Use it for multi-file changes; use edit_file for a single block.', req: ['patch'], p: { patch: 'The patch text: "*** Begin Patch", then "*** Add File: path" (lines start with +), "*** Update File: path" (optional "*** Move to: path", "@@ anchor line", then lines starting with " ", "-" or "+"), "*** Delete File: path", and "*** End Patch".' } },