lazyclaw 4.2.2 → 5.0.0

package/mas/tools/coding.mjs

@@ -0,0 +1,109 @@
+// coding — sandboxed code runners (python_exec, node_exec), data tools
+// (sql_query stub, http_request that reuses web_fetch SSRF policy),
+// and a pure helper (regex_match).
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { TOOLS as webTools } from './web.mjs';
+
+function runProc(cmd, args, opts = {}) {
+  return new Promise(resolve => {
+    let p;
+    try { p = spawn(cmd, args, { cwd: opts.cwd, env: opts.env || process.env }); }
+    catch (e) { return resolve({ ok: false, error: e.message }); }
+    let out = '', err = '';
+    const timeout = setTimeout(() => { try { p.kill('SIGKILL'); } catch {} }, opts.timeoutMs || 30_000);
+    p.on('error', e => { clearTimeout(timeout); resolve({ ok: false, error: e.message }); });
+    p.stdout?.on('data', d => out += d.toString());
+    p.stderr?.on('data', d => err += d.toString());
+    p.on('close', code => { clearTimeout(timeout); resolve({ ok: code === 0, stdout: out, stderr: err, exitCode: code }); });
+    if (opts.stdin != null) { p.stdin.write(opts.stdin); p.stdin.end(); }
+  });
+}
+
+const python_exec = {
+  name: 'python_exec', category: 'coding', sensitive: true,
+  description: 'Run a Python snippet in a sandboxed subprocess. 30s timeout.',
+  parameters: {
+    type: 'object',
+    properties: { code: { type: 'string' }, timeoutMs: { type: 'number' } },
+    required: ['code'],
+  },
+  async exec(args, ctx) {
+    const py = ctx?.python || process.env.LAZYCLAW_PYTHON || 'python3';
+    return runProc(py, ['-c', args.code], { cwd: ctx?.cwd, timeoutMs: args.timeoutMs });
+  },
+};
+
+const node_exec = {
+  name: 'node_exec', category: 'coding', sensitive: true,
+  description: 'Run a Node.js snippet in a sandboxed subprocess. 30s timeout.',
+  parameters: {
+    type: 'object',
+    properties: { code: { type: 'string' }, timeoutMs: { type: 'number' } },
+    required: ['code'],
+  },
+  async exec(args, ctx) {
+    const node = ctx?.node || process.execPath;
+    return runProc(node, ['-e', args.code], { cwd: ctx?.cwd, timeoutMs: args.timeoutMs });
+  },
+};
+
+const sql_query = {
+  name: 'sql_query', category: 'coding', sensitive: true,
+  description: 'Run a read-only SQL query against the agent\'s bound database. Returns rows.',
+  parameters: {
+    type: 'object',
+    properties: { sql: { type: 'string' }, params: { type: 'array' } },
+    required: ['sql'],
+  },
+  async exec(args, ctx) {
+    const db = ctx?.db || null;
+    if (!db) return { ok: false, error: 'sql_query: no database bound to agent context' };
+    try {
+      const stmt = db.prepare(args.sql);
+      const rows = stmt.all(...(args.params || []));
+      return { ok: true, rows };
+    } catch (e) { return { ok: false, error: `sql_query: ${e.message}` }; }
+  },
+};
+
+const http_request = {
+  name: 'http_request', category: 'coding', sensitive: true,
+  description: 'Generic HTTP client. Reuses web_fetch SSRF policy.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url: { type: 'string' }, method: { type: 'string' },
+      headers: { type: 'object' }, body: { type: 'string' },
+    },
+    required: ['url'],
+  },
+  async exec(args, ctx) {
+    const wf = webTools.find(t => t.name === 'web_fetch');
+    return wf.exec(args, ctx);
+  },
+};
+
+const regex_match = {
+  name: 'regex_match', category: 'coding', sensitive: false,
+  description: 'Run a regex over a string and return the matches.',
+  parameters: {
+    type: 'object',
+    properties: { pattern: { type: 'string' }, flags: { type: 'string' }, text: { type: 'string' } },
+    required: ['pattern', 'text'],
+  },
+  async exec(args) {
+    try {
+      const re = new RegExp(args.pattern, args.flags || '');
+      const matches = args.flags?.includes('g')
+        ? [...args.text.matchAll(re)].map(m => m[0])
+        : (args.text.match(re) || []);
+      return { ok: true, matches };
+    } catch (e) { return { ok: false, error: `regex_match: ${e.message}` }; }
+  },
+};
+
+export const TOOLS = [python_exec, node_exec, sql_query, http_request, regex_match];

package/mas/tools/delegation.mjs

@@ -0,0 +1,53 @@
+// delegation — task_spawn (named agent), delegate (worker provider).
+// Both lazy-import providers/orchestrator.mjs / mas/agent_turn.mjs to
+// avoid pulling those into every process that imports the registry.
+
+let _dispatcher = null;
+export function __setDispatcher(fn) { _dispatcher = fn; }
+
+async function dispatchDelegate(job) {
+  if (_dispatcher) return _dispatcher(job);
+  const orch = await import('../../providers/orchestrator.mjs').catch(() => null);
+  if (!orch || typeof orch.dispatchWorker !== 'function') {
+    return { ok: false, error: 'delegate: orchestrator.dispatchWorker unavailable' };
+  }
+  return orch.dispatchWorker(job);
+}
+
+async function dispatchSpawn(job) {
+  const at = await import('../agent_turn.mjs').catch(() => null);
+  if (!at || typeof at.runAgentTurn !== 'function') {
+    return { ok: false, error: 'task_spawn: agent_turn.runAgentTurn unavailable' };
+  }
+  return at.runAgentTurn(job);
+}
+
+const task_spawn = {
+  name: 'task_spawn', category: 'agents', sensitive: true,
+  description: 'Spawn an agent by name with a prompt; returns the final answer.',
+  parameters: {
+    type: 'object',
+    properties: { agent: { type: 'string' }, prompt: { type: 'string' } },
+    required: ['agent', 'prompt'],
+  },
+  async exec(args) {
+    if (!args?.agent || !args?.prompt) return { ok: false, error: 'task_spawn: agent + prompt required' };
+    return dispatchSpawn({ agent: args.agent, prompt: args.prompt });
+  },
+};
+
+const delegate = {
+  name: 'delegate', category: 'agents', sensitive: true,
+  description: 'Dispatch a subtask to a worker provider (claude-cli, codex-cli, gemini-cli, anthropic, openai, gemini, ollama).',
+  parameters: {
+    type: 'object',
+    properties: { worker: { type: 'string' }, prompt: { type: 'string' }, model: { type: 'string' } },
+    required: ['worker', 'prompt'],
+  },
+  async exec(args) {
+    if (!args?.worker || !args?.prompt) return { ok: false, error: 'delegate: worker + prompt required' };
+    return dispatchDelegate({ worker: args.worker, prompt: args.prompt, model: args.model });
+  },
+};
+
+export const TOOLS = [task_spawn, delegate];

package/mas/tools/edit.mjs

@@ -0,0 +1,36 @@
+// edit — find/replace exactly one occurrence of `old` with `new` inside a file
+// rooted at the agent cwd. Refuses when `old` is missing or not unique so the
+// LLM cannot silently overwrite the wrong span (spec §7 sub-bullet 1).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const TOOL = {
+  name: 'edit',
+  category: 'fs',
+  sensitive: true,
+  description: 'Replace exactly one occurrence of `old` with `new` inside a workspace file. Fails if `old` is missing or appears more than once.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path relative to cwd.' },
+      old:  { type: 'string', description: 'Exact substring to replace.' },
+      new:  { type: 'string', description: 'Replacement text.' },
+    },
+    required: ['path', 'old', 'new'],
+  },
+  async exec(args, { cwd = process.cwd() } = {}) {
+    if (!args || typeof args.path !== 'string') return { ok: false, error: 'edit: path required' };
+    if (typeof args.old !== 'string' || typeof args.new !== 'string') return { ok: false, error: 'edit: old/new strings required' };
+    const abs = path.resolve(cwd, args.path);
+    if (!abs.startsWith(path.resolve(cwd))) return { ok: false, error: 'edit: path escapes workspace' };
+    let src;
+    try { src = fs.readFileSync(abs, 'utf8'); } catch (e) { return { ok: false, error: `edit: ${e.message}` }; }
+    const idx = src.indexOf(args.old);
+    if (idx === -1) return { ok: false, error: `edit: \`old\` not found in ${args.path}` };
+    if (src.indexOf(args.old, idx + 1) !== -1) return { ok: false, error: `edit: \`old\` not unique in ${args.path}` };
+    const next = src.slice(0, idx) + args.new + src.slice(idx + args.old.length);
+    fs.writeFileSync(abs, next);
+    return { ok: true, path: args.path, bytesWritten: Buffer.byteLength(next) };
+  },
+};

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];