lazyclaw 4.3.0 → 5.0.1

package/mas/tools/git.mjs

@@ -0,0 +1,110 @@
+// git — read-only inspection (status/diff/log/blame/branch) and two
+// sensitive writes (commit/push). All shell out to git in ctx.cwd.
+
+import { spawnSync } from 'node:child_process';
+
+function git(cwd, args, opts = {}) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  return { ok: r.status === 0, stdout: r.stdout, stderr: r.stderr, exitCode: r.status };
+}
+
+const git_status = {
+  name: 'git_status', category: 'git', sensitive: false,
+  description: 'Run `git status` in the workspace.',
+  parameters: { type: 'object', properties: {} },
+  async exec(_args, ctx) { return git(ctx?.cwd, ['status']); },
+};
+
+const git_diff = {
+  name: 'git_diff', category: 'git', sensitive: false,
+  description: 'Run `git diff [path]`. Pass {staged:true} for `--staged`.',
+  parameters: { type: 'object', properties: { path: { type: 'string' }, staged: { type: 'boolean' } } },
+  async exec(args, ctx) {
+    const ar = ['diff'];
+    if (args?.staged) ar.push('--staged');
+    if (args?.path) ar.push('--', args.path);
+    return git(ctx?.cwd, ar);
+  },
+};
+
+const git_log = {
+  name: 'git_log', category: 'git', sensitive: false,
+  description: 'Recent commits as structured objects.',
+  parameters: { type: 'object', properties: { limit: { type: 'number' } } },
+  async exec(args, ctx) {
+    const n = Math.max(1, Math.min(args?.limit || 10, 100));
+    const r = git(ctx?.cwd, ['log', `-n${n}`, '--pretty=format:%H%x09%an%x09%aI%x09%s']);
+    if (!r.ok) return r;
+    const commits = r.stdout.trim().split('\n').filter(Boolean).map(line => {
+      const [hash, author, date, subject] = line.split('\t');
+      return { hash, author, date, subject };
+    });
+    return { ok: true, commits };
+  },
+};
+
+const git_blame = {
+  name: 'git_blame', category: 'git', sensitive: false,
+  description: 'Run `git blame <path>`.',
+  parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+  async exec(args, ctx) { return git(ctx?.cwd, ['blame', '--', args.path]); },
+};
+
+const git_branch = {
+  name: 'git_branch', category: 'git', sensitive: false,
+  description: 'List branches.',
+  parameters: { type: 'object', properties: {} },
+  async exec(_args, ctx) {
+    const r = git(ctx?.cwd, ['branch', '--all', '--format=%(refname:short)%09%(upstream:short)%09%(HEAD)']);
+    if (!r.ok) return r;
+    const branches = r.stdout.trim().split('\n').filter(Boolean).map(line => {
+      const [name, upstream, head] = line.split('\t');
+      return { name, upstream, current: head === '*' };
+    });
+    return { ok: true, branches };
+  },
+};
+
+const git_commit = {
+  name: 'git_commit', category: 'git', sensitive: true,
+  description: 'Stage paths (or skip when omitted) and commit.',
+  parameters: {
+    type: 'object',
+    properties: {
+      message: { type: 'string' },
+      paths:   { type: 'array', items: { type: 'string' } },
+      amend:   { type: 'boolean' },
+    },
+    required: ['message'],
+  },
+  async exec(args, ctx) {
+    if (Array.isArray(args.paths) && args.paths.length) {
+      const a = git(ctx?.cwd, ['add', '--', ...args.paths]);
+      if (!a.ok) return a;
+    }
+    const ar = ['commit', '-m', args.message];
+    if (args.amend) ar.splice(1, 0, '--amend');
+    return git(ctx?.cwd, ar);
+  },
+};
+
+const git_push = {
+  name: 'git_push', category: 'git', sensitive: true,
+  description: 'Push to a remote. Refuses --force unless force=true explicitly.',
+  parameters: {
+    type: 'object',
+    properties: {
+      remote: { type: 'string' }, branch: { type: 'string' },
+      force:  { type: 'boolean' },
+    },
+  },
+  async exec(args, ctx) {
+    const ar = ['push'];
+    if (args?.force) ar.push('--force-with-lease');
+    if (args?.remote) ar.push(args.remote);
+    if (args?.branch) ar.push(args.branch);
+    return git(ctx?.cwd, ar);
+  },
+};
+
+export const TOOLS = [git_status, git_diff, git_log, git_blame, git_branch, git_commit, git_push];

package/mas/tools/ha.mjs

@@ -0,0 +1,34 @@
+// Home Assistant tools — STUB only in v5.0; activated in v5.1 per spec §0.2.
+// Registered so the catalogue lists them and config / toolset definitions
+// can reference them, but exec() returns a clear deferred message.
+
+function deferred(name) {
+  return async () => ({ ok: false, error: `${name}: Home Assistant tools deferred to v5.1 (spec §0.2)` });
+}
+
+const ha_call_service = {
+  name: 'ha_call_service', category: 'iot', sensitive: true,
+  description: 'STUB — Home Assistant service call deferred to v5.1.',
+  parameters: {
+    type: 'object',
+    properties: {
+      domain: { type: 'string' }, service: { type: 'string' },
+      data: { type: 'object' },
+    },
+    required: ['domain', 'service'],
+  },
+  exec: deferred('ha_call_service'),
+};
+
+const ha_get_state = {
+  name: 'ha_get_state', category: 'iot', sensitive: true,
+  description: 'STUB — Home Assistant state read deferred to v5.1.',
+  parameters: {
+    type: 'object',
+    properties: { entity_id: { type: 'string' } },
+    required: ['entity_id'],
+  },
+  exec: deferred('ha_get_state'),
+};
+
+export const TOOLS = [ha_call_service, ha_get_state];

package/mas/tools/learning.mjs

@@ -0,0 +1,168 @@
+// learning — agent tools that read/write the skill bank, layered memory,
+// and the persistent USER.md (Honcho-equivalent, spec §1.6, §4.10).
+// USER.md path canonical (C6) = <configDir>/memory/USER.md.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function resolveConfigDir(ctx) {
+  return ctx?.configDir || process.env.LAZYCLAW_CONFIG_DIR || path.join(process.env.HOME || '.', '.lazyclaw');
+}
+
+function skillsDir(ctx) { return path.join(resolveConfigDir(ctx), 'skills'); }
+function memoryDir(ctx) { return path.join(resolveConfigDir(ctx), 'memory'); }
+function userMdPath(ctx) { return path.join(memoryDir(ctx), 'USER.md'); }
+
+const skill_view = {
+  name: 'skill_view', category: 'learning', sensitive: false,
+  description: 'Return the body of an installed skill (by name).',
+  parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+  async exec(args, ctx) {
+    if (!args?.name) return { ok: false, error: 'skill_view: name required' };
+    const file = path.join(skillsDir(ctx), args.name, 'SKILL.md');
+    if (!fs.existsSync(file)) return { ok: false, error: `skill_view: ${args.name} not installed` };
+    return { ok: true, name: args.name, content: fs.readFileSync(file, 'utf8') };
+  },
+};
+
+const skill_create = {
+  name: 'skill_create', category: 'learning', sensitive: true,
+  description: 'Create a new skill at <configDir>/skills/<name>/SKILL.md. Fails if already exists.',
+  parameters: {
+    type: 'object',
+    properties: {
+      name: { type: 'string' }, body: { type: 'string' },
+      description: { type: 'string' }, group: { type: 'string' },
+    },
+    required: ['name', 'body'],
+  },
+  async exec(args, ctx) {
+    if (!args?.name || !args?.body) return { ok: false, error: 'skill_create: name + body required' };
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(args.name)) return { ok: false, error: 'skill_create: kebab-case name only' };
+    const dir = path.join(skillsDir(ctx), args.name);
+    const file = path.join(dir, 'SKILL.md');
+    if (fs.existsSync(file)) return { ok: false, error: `skill_create: ${args.name} already exists; use skill_edit` };
+    fs.mkdirSync(dir, { recursive: true });
+    const fm = [
+      '---',
+      `name: ${args.name}`,
+      `description: ${args.description || args.body.split('\n')[0].slice(0, 200)}`,
+      `group: ${args.group || (args.name.includes('-') ? args.name.split('-')[0] : 'legacy')}`,
+      'version: 1',
+      'trained_by: user',
+      `created_at: ${new Date().toISOString().slice(0, 10)}`,
+      '---',
+      '',
+    ].join('\n');
+    fs.writeFileSync(file, fm + args.body + (args.body.endsWith('\n') ? '' : '\n'));
+    return { ok: true, name: args.name, file };
+  },
+};
+
+const skill_edit = {
+  name: 'skill_edit', category: 'learning', sensitive: true,
+  description: 'Replace the body of an existing skill. Preserves frontmatter, bumps version.',
+  parameters: {
+    type: 'object',
+    properties: { name: { type: 'string' }, body: { type: 'string' } },
+    required: ['name', 'body'],
+  },
+  async exec(args, ctx) {
+    const file = path.join(skillsDir(ctx), args.name, 'SKILL.md');
+    if (!fs.existsSync(file)) return { ok: false, error: `skill_edit: ${args.name} not installed` };
+    const src = fs.readFileSync(file, 'utf8');
+    const m = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(src);
+    if (!m) return { ok: false, error: 'skill_edit: missing frontmatter' };
+    let fm = m[1];
+    fm = fm.replace(/version:\s*(\d+)/, (_, v) => `version: ${Number(v) + 1}`);
+    fs.writeFileSync(file, `---\n${fm}\n---\n${args.body}${args.body.endsWith('\n') ? '' : '\n'}`);
+    return { ok: true, name: args.name };
+  },
+};
+
+const memory_write = {
+  name: 'memory_write', category: 'learning', sensitive: true,
+  description: 'Append to layered memory. kind=recent appends a JSONL line; kind=core overwrites core.md; kind=episodic writes episodic/<topic>.md.',
+  parameters: {
+    type: 'object',
+    properties: {
+      kind:    { type: 'string', enum: ['recent', 'core', 'episodic'] },
+      content: { type: 'string' },
+      topic:   { type: 'string' },
+    },
+    required: ['kind', 'content'],
+  },
+  async exec(args, ctx) {
+    const dir = memoryDir(ctx);
+    fs.mkdirSync(dir, { recursive: true });
+    if (args.kind === 'recent') {
+      fs.appendFileSync(path.join(dir, 'recent.jsonl'), JSON.stringify({ ts: Date.now(), content: args.content }) + '\n');
+    } else if (args.kind === 'core') {
+      fs.writeFileSync(path.join(dir, 'core.md'), args.content);
+    } else if (args.kind === 'episodic') {
+      if (!args.topic) return { ok: false, error: 'memory_write: topic required for episodic' };
+      fs.mkdirSync(path.join(dir, 'episodic'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'episodic', `${args.topic}.md`), args.content);
+    } else {
+      return { ok: false, error: `memory_write: unknown kind ${args.kind}` };
+    }
+    return { ok: true, kind: args.kind };
+  },
+};
+
+const memory_read = {
+  name: 'memory_read', category: 'learning', sensitive: false,
+  description: 'Read layered memory. kind=recent returns last N JSONL entries; kind=core returns core.md; kind=episodic returns episodic/<topic>.md.',
+  parameters: {
+    type: 'object',
+    properties: {
+      kind:  { type: 'string', enum: ['recent', 'core', 'episodic'] },
+      topic: { type: 'string' },
+      limit: { type: 'number' },
+    },
+    required: ['kind'],
+  },
+  async exec(args, ctx) {
+    const dir = memoryDir(ctx);
+    if (args.kind === 'recent') {
+      const f = path.join(dir, 'recent.jsonl');
+      if (!fs.existsSync(f)) return { ok: true, entries: [] };
+      const lines = fs.readFileSync(f, 'utf8').trim().split('\n').filter(Boolean);
+      const limit = Math.max(1, Math.min(200, args.limit || 20));
+      return { ok: true, entries: lines.slice(-limit).map(l => { try { return JSON.parse(l); } catch { return { content: l }; } }) };
+    }
+    if (args.kind === 'core') {
+      const f = path.join(dir, 'core.md');
+      return { ok: true, content: fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '' };
+    }
+    if (args.kind === 'episodic') {
+      if (!args.topic) return { ok: false, error: 'memory_read: topic required for episodic' };
+      const f = path.join(dir, 'episodic', `${args.topic}.md`);
+      return { ok: true, content: fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '' };
+    }
+    return { ok: false, error: `memory_read: unknown kind ${args.kind}` };
+  },
+};
+
+const user_view = {
+  name: 'user_view', category: 'learning', sensitive: false,
+  description: 'Read the persistent USER.md (Honcho-equivalent user model).',
+  parameters: { type: 'object', properties: {} },
+  async exec(_args, ctx) {
+    const f = userMdPath(ctx);
+    return { ok: true, content: fs.existsSync(f) ? fs.readFileSync(f, 'utf8') : '' };
+  },
+};
+
+const user_update = {
+  name: 'user_update', category: 'learning', sensitive: true,
+  description: 'Overwrite USER.md (the persistent user model). Use sparingly — usually the user_modeler does this.',
+  parameters: { type: 'object', properties: { content: { type: 'string' } }, required: ['content'] },
+  async exec(args, ctx) {
+    fs.mkdirSync(memoryDir(ctx), { recursive: true });
+    fs.writeFileSync(userMdPath(ctx), args.content);
+    return { ok: true, path: userMdPath(ctx) };
+  },
+};
+
+export const TOOLS = [skill_view, skill_create, skill_edit, memory_write, memory_read, user_view, user_update];

package/mas/tools/media.mjs

@@ -0,0 +1,105 @@
+// media — image_describe (vision provider), image_generate (FAL/DALL-E
+// optional via env key), tts_speak (deferred to v5.1 per spec §0.2),
+// transcribe (whisper.cpp local OR OpenAI whisper API by env key).
+// Provider integrations are opt-in via env vars; all return a structured
+// "configure X" error otherwise.
+
+import fs from 'node:fs';
+import { fetch } from 'undici';
+
+const image_describe = {
+  name: 'image_describe', category: 'media', sensitive: true,
+  description: 'Describe an image. Requires OPENAI_API_KEY (gpt-4o vision) or ANTHROPIC_API_KEY (claude vision).',
+  parameters: {
+    type: 'object',
+    properties: { path: { type: 'string' }, prompt: { type: 'string' } },
+    required: ['path'],
+  },
+  async exec(args, ctx) {
+    const env = ctx?.env || process.env;
+    if (!fs.existsSync(args.path)) return { ok: false, error: `image_describe: file not found ${args.path}` };
+    const b64 = fs.readFileSync(args.path).toString('base64');
+    const prompt = args.prompt || 'Describe this image briefly.';
+    if (env.OPENAI_API_KEY) {
+      try {
+        const r = await fetch('https://api.openai.com/v1/chat/completions', {
+          method: 'POST', headers: { 'Authorization': `Bearer ${env.OPENAI_API_KEY}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ model: 'gpt-4o-mini', messages: [{ role: 'user', content: [
+            { type: 'text', text: prompt },
+            { type: 'image_url', image_url: { url: `data:image/png;base64,${b64}` } },
+          ] }] }),
+        });
+        const j = await r.json();
+        return { ok: true, description: j?.choices?.[0]?.message?.content || '' };
+      } catch (e) { return { ok: false, error: `image_describe: ${e.message}` }; }
+    }
+    return { ok: false, error: 'image_describe: set OPENAI_API_KEY (gpt-4o vision)' };
+  },
+};
+
+const image_generate = {
+  name: 'image_generate', category: 'media', sensitive: true,
+  description: 'Generate an image. Requires OPENAI_API_KEY (DALL-E) or FAL_KEY.',
+  parameters: {
+    type: 'object',
+    properties: { prompt: { type: 'string' }, outPath: { type: 'string' } },
+    required: ['prompt'],
+  },
+  async exec(args, ctx) {
+    const env = ctx?.env || process.env;
+    if (!env.OPENAI_API_KEY && !env.FAL_KEY) return { ok: false, error: 'image_generate: set OPENAI_API_KEY or FAL_KEY' };
+    if (env.OPENAI_API_KEY) {
+      try {
+        const r = await fetch('https://api.openai.com/v1/images/generations', {
+          method: 'POST', headers: { 'Authorization': `Bearer ${env.OPENAI_API_KEY}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ model: 'gpt-image-1', prompt: args.prompt, size: '1024x1024' }),
+        });
+        const j = await r.json();
+        const b64 = j?.data?.[0]?.b64_json;
+        if (!b64) return { ok: false, error: `image_generate: no data (${JSON.stringify(j).slice(0, 200)})` };
+        if (args.outPath) fs.writeFileSync(args.outPath, Buffer.from(b64, 'base64'));
+        return { ok: true, outPath: args.outPath || null, b64: args.outPath ? null : b64 };
+      } catch (e) { return { ok: false, error: `image_generate: ${e.message}` }; }
+    }
+    return { ok: false, error: 'image_generate: FAL_KEY path not implemented in v5.0 (configure OPENAI_API_KEY)' };
+  },
+};
+
+const tts_speak = {
+  name: 'tts_speak', category: 'media', sensitive: true,
+  description: 'STUB — TTS reply deferred to v5.1 per spec §0.2.',
+  parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+  async exec() {
+    return { ok: false, error: 'tts_speak: deferred to v5.1 (spec §0.2)' };
+  },
+};
+
+const transcribe = {
+  name: 'transcribe', category: 'media', sensitive: true,
+  description: 'Transcribe audio. Requires OPENAI_API_KEY (whisper) or a local whisper.cpp binary at WHISPER_CPP.',
+  parameters: {
+    type: 'object',
+    properties: { path: { type: 'string' }, language: { type: 'string' } },
+    required: ['path'],
+  },
+  async exec(args, ctx) {
+    const env = ctx?.env || process.env;
+    if (!fs.existsSync(args.path)) return { ok: false, error: `transcribe: file not found ${args.path}` };
+    if (env.OPENAI_API_KEY) {
+      try {
+        const fd = new FormData();
+        fd.append('file', new Blob([fs.readFileSync(args.path)]), 'audio');
+        fd.append('model', 'whisper-1');
+        if (args.language) fd.append('language', args.language);
+        const r = await fetch('https://api.openai.com/v1/audio/transcriptions', {
+          method: 'POST', headers: { 'Authorization': `Bearer ${env.OPENAI_API_KEY}` }, body: fd,
+        });
+        const j = await r.json();
+        return { ok: true, text: j?.text || '' };
+      } catch (e) { return { ok: false, error: `transcribe: ${e.message}` }; }
+    }
+    return { ok: false, error: 'transcribe: set OPENAI_API_KEY (whisper-1)' };
+  },
+};
+
+export const TOOLS = [image_describe, image_generate, tts_speak, transcribe];

package/mas/tools/os.mjs

@@ -0,0 +1,152 @@
+// os — clipboard, screenshot, notify, open_url, file_dialog. macOS and
+// linux paths implemented; everything else returns "unsupported".
+// ctx.platform overrideable for tests.
+
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function platformOf(ctx) { return ctx?.platform || process.platform; }
+
+function runCmd(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, opts);
+    let out = '', err = '';
+    child.stdout?.on('data', d => out += d.toString());
+    child.stderr?.on('data', d => err += d.toString());
+    child.on('error', e => resolve({ ok: false, error: e.message }));
+    child.on('close', code => resolve({ ok: code === 0, stdout: out, stderr: err, exitCode: code }));
+    if (opts.stdin) { child.stdin.write(opts.stdin); child.stdin.end(); }
+  });
+}
+
+const clipboard_read = {
+  name: 'clipboard_read', category: 'os', sensitive: true,
+  description: 'Read the OS clipboard (text).',
+  parameters: { type: 'object', properties: {} },
+  async exec(_args, ctx) {
+    const p = platformOf(ctx);
+    if (p === 'darwin') {
+      const r = spawnSync('pbpaste', [], { encoding: 'utf8' });
+      return r.status === 0 ? { ok: true, text: r.stdout } : { ok: false, error: r.stderr || 'pbpaste failed' };
+    }
+    if (p === 'linux') {
+      for (const [bin, args] of [['wl-paste', []], ['xclip', ['-selection', 'clipboard', '-o']], ['xsel', ['--clipboard', '--output']]]) {
+        const r = spawnSync(bin, args, { encoding: 'utf8' });
+        if (r.status === 0) return { ok: true, text: r.stdout };
+      }
+      return { ok: false, error: 'clipboard_read: no clipboard helper (install wl-clipboard or xclip)' };
+    }
+    return { ok: false, error: `clipboard_read: unsupported platform ${p}` };
+  },
+};
+
+const clipboard_write = {
+  name: 'clipboard_write', category: 'os', sensitive: true,
+  description: 'Write text to the OS clipboard.',
+  parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    if (p === 'darwin') return runCmd('pbcopy', [], { stdin: args.text });
+    if (p === 'linux') {
+      for (const [bin, ar] of [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]]) {
+        const r = await runCmd(bin, ar, { stdin: args.text });
+        if (r.ok) return { ok: true };
+      }
+      return { ok: false, error: 'clipboard_write: no clipboard helper' };
+    }
+    return { ok: false, error: `clipboard_write: unsupported platform ${p}` };
+  },
+};
+
+const screenshot = {
+  name: 'screenshot', category: 'os', sensitive: true,
+  description: 'Capture a screenshot and write it to a PNG path (defaults to a tmpfile). Returns {path}.',
+  parameters: { type: 'object', properties: { path: { type: 'string' } } },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    const out = args?.path || path.join(os.tmpdir(), `lzc-${Date.now()}.png`);
+    if (p === 'darwin') {
+      const r = spawnSync('screencapture', ['-x', out]);
+      return r.status === 0 ? { ok: true, path: out } : { ok: false, error: 'screencapture failed' };
+    }
+    if (p === 'linux') {
+      for (const [bin, ar] of [['grim', [out]], ['gnome-screenshot', ['-f', out]], ['scrot', [out]]]) {
+        const r = spawnSync(bin, ar);
+        if (r.status === 0) return { ok: true, path: out };
+      }
+      return { ok: false, error: 'screenshot: no helper found (grim/gnome-screenshot/scrot)' };
+    }
+    return { ok: false, error: `screenshot: unsupported platform ${p}` };
+  },
+};
+
+const notify = {
+  name: 'notify', category: 'os', sensitive: false,
+  description: 'Post a desktop notification. Best-effort; failures do not surface to the user.',
+  parameters: {
+    type: 'object',
+    properties: { title: { type: 'string' }, body: { type: 'string' } },
+    required: ['title'],
+  },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    const title = args.title;
+    const body = args.body || '';
+    if (p === 'darwin') {
+      spawnSync('osascript', ['-e', `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`]);
+      return { ok: true };
+    }
+    if (p === 'linux') {
+      spawnSync('notify-send', [title, body]);
+      return { ok: true };
+    }
+    return { ok: false, error: `notify: unsupported platform ${p}` };
+  },
+};
+
+const open_url = {
+  name: 'open_url', category: 'os', sensitive: true,
+  description: 'Open a public URL in the default browser. http(s) only.',
+  parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+  async exec(args, ctx) {
+    try {
+      const u = new URL(args.url);
+      if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, error: 'open_url: http(s) only' };
+    } catch { return { ok: false, error: 'open_url: bad URL' }; }
+    const p = platformOf(ctx);
+    if (p === 'darwin') return runCmd('open', [args.url]);
+    if (p === 'linux') return runCmd('xdg-open', [args.url]);
+    return { ok: false, error: `open_url: unsupported platform ${p}` };
+  },
+};
+
+const file_dialog = {
+  name: 'file_dialog', category: 'os', sensitive: true,
+  description: 'Show an OS file picker. Returns selected path (or null on cancel).',
+  parameters: {
+    type: 'object',
+    properties: { kind: { type: 'string', enum: ['open', 'save'] }, prompt: { type: 'string' } },
+  },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    if (p === 'darwin') {
+      const script = (args.kind === 'save')
+        ? 'POSIX path of (choose file name with prompt "' + (args.prompt || 'Save').replace(/"/g, '\\"') + '")'
+        : 'POSIX path of (choose file with prompt "'      + (args.prompt || 'Choose').replace(/"/g, '\\"') + '")';
+      const r = spawnSync('osascript', ['-e', script], { encoding: 'utf8' });
+      if (r.status !== 0) return { ok: true, path: null };
+      return { ok: true, path: r.stdout.trim() };
+    }
+    if (p === 'linux') {
+      const ar = args.kind === 'save' ? ['--file-selection', '--save'] : ['--file-selection'];
+      const r = spawnSync('zenity', ar, { encoding: 'utf8' });
+      if (r.status !== 0) return { ok: true, path: null };
+      return { ok: true, path: r.stdout.trim() };
+    }
+    return { ok: false, error: `file_dialog: unsupported platform ${p}` };
+  },
+};
+
+export const TOOLS = [clipboard_read, clipboard_write, screenshot, notify, open_url, file_dialog];

package/mas/tools/patch.mjs

@@ -0,0 +1,91 @@
+// patch — apply a unified-diff to one or more files. Uses a strict parser:
+// a hunk must match context lines exactly or the entire patch is rejected
+// so partial application can't corrupt the workspace.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const TOOL = {
+  name: 'patch',
+  category: 'fs',
+  sensitive: true,
+  description: 'Apply a unified-diff patch (multi-file allowed). Fails atomically on any context mismatch.',
+  parameters: {
+    type: 'object',
+    properties: { diff: { type: 'string', description: 'Unified diff body.' } },
+    required: ['diff'],
+  },
+  async exec(args, { cwd = process.cwd() } = {}) {
+    if (!args || typeof args.diff !== 'string' || !args.diff.trim()) return { ok: false, error: 'patch: diff required' };
+    const files = parseUnifiedDiff(args.diff);
+    if (!files.length) return { ok: false, error: 'patch: no file hunks parsed' };
+    const stage = []; // {abs, content}
+    for (const file of files) {
+      const abs = path.resolve(cwd, file.path);
+      if (!abs.startsWith(path.resolve(cwd))) return { ok: false, error: `patch: path escapes workspace: ${file.path}` };
+      let src;
+      try { src = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : ''; }
+      catch (e) { return { ok: false, error: `patch: read ${file.path}: ${e.message}` }; }
+      const applied = applyHunks(src, file.hunks);
+      if (!applied.ok) return { ok: false, error: `patch: ${file.path}: ${applied.error}` };
+      stage.push({ abs, content: applied.content });
+    }
+    for (const s of stage) fs.writeFileSync(s.abs, s.content);
+    return { ok: true, filesWritten: stage.length };
+  },
+};
+
+function parseUnifiedDiff(diff) {
+  const lines = diff.split('\n');
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i].startsWith('--- ') && lines[i + 1]?.startsWith('+++ ')) {
+      const newPath = lines[i + 1].slice(4).replace(/^b\//, '').trim();
+      i += 2;
+      const hunks = [];
+      while (i < lines.length && lines[i].startsWith('@@')) {
+        const header = lines[i++];
+        const body = [];
+        while (i < lines.length && !lines[i].startsWith('@@') && !lines[i].startsWith('--- ')) {
+          body.push(lines[i++]);
+        }
+        hunks.push({ header, body });
+      }
+      out.push({ path: newPath, hunks });
+    } else {
+      i++;
+    }
+  }
+  return out;
+}
+
+function applyHunks(src, hunks) {
+  let lines = src.split('\n');
+  let cursor = 0;
+  for (const hunk of hunks) {
+    const m = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(hunk.header);
+    if (!m) return { ok: false, error: `bad hunk header: ${hunk.header}` };
+    let lineIdx = Math.max(0, parseInt(m[1], 10) - 1);
+    const out = lines.slice(0, lineIdx);
+    for (const b of hunk.body) {
+      if (b === '') continue;
+      const op = b[0];
+      const text = b.slice(1);
+      if (op === ' ') {
+        if ((lines[lineIdx] ?? '') !== text) return { ok: false, error: `context mismatch at line ${lineIdx + 1}` };
+        out.push(text); lineIdx++;
+      } else if (op === '-') {
+        if ((lines[lineIdx] ?? '') !== text) return { ok: false, error: `delete mismatch at line ${lineIdx + 1}` };
+        lineIdx++;
+      } else if (op === '+') {
+        out.push(text);
+      } else if (op === '\\') {
+        //  — ignore
+      }
+    }
+    lines = out.concat(lines.slice(lineIdx));
+    cursor = lineIdx;
+  }
+  return { ok: true, content: lines.join('\n') };
+}