mouaif 0.3.0

package/src/tools/shell.js

@@ -0,0 +1,341 @@
+'use strict';
+
+// Native `shell` tool — lets the model run a command in the project's
+// working directory. Implements docs/features/shell-tool.md.
+//
+// Public surface:
+//   runShell({ projectDir, cmd, timeoutMs, maxBytes }) ->
+//     Promise<{ ok, stdout, stderr, exitCode, durationMs }>
+//                | { ok: false, error, code, durationMs }
+//   SPEC  — the OpenAI-compatible tool spec advertised to the model.
+//
+// The runner is built on node:child_process.spawn only; no third-party
+// shell wrappers, no new runtime dependencies. Every child is tracked
+// in a module-level Set and killed on parent exit so a server shutdown
+// does not leak zombies.
+
+const { spawn } = require('node:child_process');
+const { StringDecoder } = require('node:string_decoder');
+const fs = require('node:fs');
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 10 * 60 * 1000; // 10 min ceiling
+const DEFAULT_MAX_CHARS = 256 * 1024; // 256K chars per stream
+const DEFAULT_MAX_BYTES = DEFAULT_MAX_CHARS; // legacy export alias
+const KILL_GRACE_MS = 5_000; // SIGTERM -> SIGKILL grace
+
+// Environment variables stripped from the child to prevent trivial
+// tool escape via preloading / injected node options.
+const ENV_DENYLIST = [
+  'LD_PRELOAD',
+  'LD_LIBRARY_PATH',
+  'DYLD_INSERT_LIBRARIES',
+  'NODE_OPTIONS'
+];
+
+// Live children, reaped on parent exit.
+const liveChildren = new Set();
+let exitHooked = false;
+function hookExit() {
+  if (exitHooked) return;
+  exitHooked = true;
+  const reap = () => {
+    for (const child of liveChildren) {
+      try { child.kill('SIGKILL'); } catch { /* already gone */ }
+    }
+    liveChildren.clear();
+  };
+  process.on('exit', reap);
+  process.on('SIGINT', () => { reap(); process.exit(130); });
+  process.on('SIGTERM', () => { reap(); process.exit(143); });
+}
+
+// Human-readable label for the platform shell ("PowerShell 7 (pwsh)",
+// "bash (bash)", ...). Computed once at module load from the exact
+// interpreter the runner will spawn, so the model-facing description
+// and the result metadata always agree with what actually ran.
+//
+// Windows note: cmd.exe is a COMMAND.COM-style shell whose quoting,
+// escaping and environment differ from POSIX sh. `SHELL` is
+// conventionally unset on Windows, so we never consult it there; the
+// child always runs under `ComSpec` (cmd.exe by default).
+function shellLabelFor(shellPath) {
+  if (process.platform === 'win32') {
+    const base = shellPath.split(/[\\/]/).pop().toLowerCase();
+    if (base === 'pwsh.exe' || base === 'pwsh') return 'PowerShell 7 (pwsh)';
+    if (base === 'powershell.exe' || base === 'powershell') return 'Windows PowerShell (powershell)';
+    if (base === 'cmd.exe' || base === 'cmd') return 'Command Prompt (cmd.exe)';
+    return 'Windows shell (' + shellPath + ')';
+  }
+  const base = shellPath.split('/').pop() || shellPath;
+  return base + ' (' + shellPath + ')';
+}
+
+function shellLabel() {
+  return shellLabelFor(process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : (process.env.SHELL || '/bin/sh'));
+}
+
+function osLabel() {
+  if (process.platform === 'win32') return 'Windows';
+  if (process.platform === 'darwin') return 'macOS';
+  return process.platform;
+}
+
+// Shell-family summary for the model, e.g. "Command Prompt (cmd.exe) —
+// Windows command-line syntax, not POSIX sh". This makes the
+// interpreter's dialect explicit so the model does not assume bash.
+function shellDialectHint() {
+  const label = shellLabel();
+  if (process.platform === 'win32') {
+    return label + ' — Windows command-line syntax (cmd.exe batch-style quoting and escaping; not POSIX sh/bash)';
+  }
+  return label + ' — POSIX sh syntax';
+}
+
+// "The exact interpreter that runs commands, e.g. 'C:\Windows\system32\cmd.exe'."
+function shellExeDescription() {
+  if (process.platform === 'win32') {
+    const comspec = process.env.ComSpec || 'cmd.exe';
+    return 'The exact interpreter that runs commands, e.g. ' + JSON.stringify(comspec) + '.';
+  }
+  return "The exact interpreter that runs commands, e.g. '/bin/sh' or the user's \$SHELL.";
+}
+
+// The model-facing tool spec (OpenAI-compatible function shape).
+const SPEC = {
+  type: 'function',
+  function: {
+    name: 'shell',
+    description: 'Run a shell command in the project directory through mouaif, the local AI coding assistant that provides this chat. Commands execute on ' + osLabel() + ' via ' + shellDialectHint() + '. Returns stdout, stderr, and exit code. Non-interactive only: the child has no stdin, so REPLs, prompts, and commands that read from stdin fail or exit immediately — run the one-shot/flagged form instead (e.g. "node -e ...", "npm test", not bare "node" or "cmd").',
+    parameters: {
+      type: 'object',
+      properties: {
+        cmd: { type: 'string', description: 'The command to run, as a single string. Must be non-interactive (no stdin input, no REPL, no prompts).' },
+        shell: { type: 'string', description: shellExeDescription() },
+        timeoutMs: { type: 'integer', description: 'Optional per-call timeout, 1 ms - 10 min. Default 30000.' }
+      },
+      required: ['cmd'],
+      additionalProperties: false
+    }
+  }
+};
+
+// Resolve and validate the working directory. Returns the real,
+// absolute project dir or throws a typed error.
+function resolveSandbox(projectDir) {
+  if (!projectDir || typeof projectDir !== 'string') {
+    const e = new Error('projectDir is required'); e.code = 'EBADINPUT'; throw e;
+  }
+  let real;
+  try { real = fs.realpathSync(projectDir); }
+  catch { const e = new Error('project directory not found'); e.code = 'ENOENT'; throw e; }
+  let st;
+  try { st = fs.statSync(real); }
+  catch { const e = new Error('project directory not found'); e.code = 'ENOENT'; throw e; }
+  if (!st.isDirectory()) {
+    const e = new Error('projectDir is not a directory'); e.code = 'ENOTDIR'; throw e;
+  }
+  return real;
+}
+
+// Build the child environment: parent env minus the denylist.
+function childEnv() {
+  const env = Object.assign({}, process.env);
+  for (const key of ENV_DENYLIST) delete env[key];
+  return env;
+}
+
+// Truncate a Buffer/string to maxChars characters, appending a
+// truncation marker. Counts UTF-16 code units (String.length) rather
+// than bytes so the cap and the marker match how the model and the UI
+// read the text; multi-byte output can no longer be split mid-codepoint.
+function truncate(buf, maxChars) {
+  const s = Buffer.isBuffer(buf) ? buf.toString('utf8') : String(buf);
+  if (s.length <= maxChars) return s;
+  return s.slice(0, maxChars) + '\n...[truncated at ' + maxChars + ' chars]';
+}
+
+// The platform shell: cmd.exe on Windows, $SHELL (or /bin/sh) on POSIX.
+//
+// Windows needs two non-obvious tweaks:
+//   1. The flags must be separate argv elements; passing "/d /s /c" as one
+//      element makes Node quote it ("/d /s /c") and cmd.exe mis-parse it.
+//   2. With /s, cmd.exe strips the first and last quote of the command line,
+//      mangling inner quotes ("node -e \"console.log(1+1)\"" silently
+//      produces no output). Wrapping the whole command in an extra pair of
+//      quotes plus windowsVerbatimArguments preserves it exactly.
+function platformShell() {
+  if (process.platform === 'win32') {
+    return { file: process.env.ComSpec || 'cmd.exe', flags: ['/d', '/s', '/c'], wrapQuotes: true, verbatim: true };
+  }
+  return { file: process.env.SHELL || '/bin/sh', flags: ['-c'], wrapQuotes: false, verbatim: false };
+}
+
+// runShell — execute cmd in projectDir, capturing stdout/stderr.
+// Optional opts.onOutput(stream, delta) fires per decoded output chunk
+// while the command is still running so callers can stream a live
+// preview to the chat UI.
+async function runShell(opts) {
+  const projectDir = opts && opts.projectDir;
+  const cmd = opts && opts.cmd;
+  const onOutput = opts && typeof opts.onOutput === 'function' ? opts.onOutput : null;
+  let timeoutMs = opts && typeof opts.timeoutMs === 'number' ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const maxChars = opts && typeof opts.maxChars === 'number' ? opts.maxChars
+    : (opts && typeof opts.maxBytes === 'number' ? opts.maxBytes : DEFAULT_MAX_CHARS);
+
+  if (!cmd || typeof cmd !== 'string' || !cmd.trim()) {
+    return { ok: false, error: 'cmd is required', code: 'EBADINPUT', durationMs: 0 };
+  }
+  // Optional explicit interpreter override (Windows: cmd.exe / pwsh /
+  // powershell.exe; POSIX: a path to a sh-compatible binary). The
+  // override is validated below and reuses the platform flags, so it
+  // cannot turn into an arbitrary-args injection.
+  let shellOverride = opts && typeof opts.shell === 'string' ? opts.shell.trim() : '';
+  if (shellOverride && shellOverride !== 'default') {
+    const lower = shellOverride.toLowerCase();
+    const knownWin = ['cmd.exe', 'cmd', 'pwsh.exe', 'pwsh', 'powershell.exe', 'powershell'];
+    if (process.platform === 'win32' && !knownWin.includes(lower)) {
+      return { ok: false, error: 'unsupported shell override on Windows: ' + shellOverride + ' (expected cmd.exe, pwsh, or powershell)', code: 'EBADINPUT', durationMs: 0 };
+    }
+    if (process.platform !== 'win32' && (lower.endsWith('.exe') || lower.includes('\\') || !lower.includes('/'))) {
+      return { ok: false, error: 'unsupported shell override: ' + shellOverride + ' (expected a path to a sh-compatible binary)', code: 'EBADINPUT', durationMs: 0 };
+    }
+  } else {
+    shellOverride = '';
+  }
+  // Clamp timeout to [1, MAX_TIMEOUT_MS].
+  if (!(timeoutMs >= 1)) timeoutMs = DEFAULT_TIMEOUT_MS;
+  if (timeoutMs > MAX_TIMEOUT_MS) timeoutMs = MAX_TIMEOUT_MS;
+
+  // Identity of this runner, surfaced in the tool result and prepended
+  // to the first model-facing tool message, so the model always knows
+  // which software and which shell executed the command.
+  let identity = 'mouaif shell · ' + osLabel() + ' · ' + shellLabel();
+
+  let cwd;
+  try { cwd = resolveSandbox(projectDir); }
+  catch (e) { return { ok: false, error: e.message, code: e.code || 'EOUTSIDE_PROJECT', durationMs: 0 }; }
+
+  hookExit();
+
+  const base = platformShell();
+  const override = shellOverride || '';
+  const file = override || base.file;
+  // cmd.exe (and cmd aliases) must keep the wrapper-quote handling;
+  // any POSIX-style interpreter gets the plain `-c` flag path.
+  const isCmd = process.platform === 'win32' && (!override || ['cmd.exe', 'cmd'].includes(override.toLowerCase()));
+  const flags = isCmd ? base.flags : ['-c'];
+  const wrapQuotes = isCmd;
+  const verbatim = isCmd;
+  const args = flags.concat(wrapQuotes ? '"' + cmd + '"' : cmd);
+  // Identity reflects the interpreter that actually runs the command,
+  // which is the override when one was requested.
+  if (override) identity = 'mouaif shell · ' + osLabel() + ' · ' + shellLabelFor(file);
+  const startedAt = Date.now();
+
+  return await new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(file, args, {
+        cwd,
+        env: childEnv(),
+        windowsHide: true,
+        windowsVerbatimArguments: verbatim,
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+    } catch (e) {
+      return resolve({ ok: false, error: e.message, code: 'ESPAWN', durationMs: Date.now() - startedAt });
+    }
+
+    liveChildren.add(child);
+
+    // Output is accumulated as decoded text (StringDecoder keeps
+    // multi-byte UTF-8 sequences intact across chunk boundaries) so
+    // both the char cap and the live preview deltas are codepoint-safe.
+    const outDec = new StringDecoder('utf8');
+    const errDec = new StringDecoder('utf8');
+    let outText = '';
+    let errText = '';
+    let settled = false;
+    let killGrace = null;
+
+    const appendCapped = (existing, decoder, chunk, stream) => {
+      const text = decoder.write(chunk);
+      if (text && onOutput) {
+        try { onOutput(stream, text); } catch { /* preview is best-effort */ }
+      }
+      // Stop growing the buffer once we exceed the cap (leave room for
+      // the marker in truncate()); we still drain the stream so the
+      // child does not block on a full pipe.
+      if (existing.length >= maxChars) return existing;
+      return existing + text;
+    };
+
+    child.stdout.on('data', (c) => { outText = appendCapped(outText, outDec, c, 'stdout'); });
+    child.stderr.on('data', (c) => { errText = appendCapped(errText, errDec, c, 'stderr'); });
+
+    const timer = setTimeout(() => {
+      // Timed out: SIGTERM, then SIGKILL after the grace window.
+      try { child.kill('SIGTERM'); } catch { /* gone */ }
+      killGrace = setTimeout(() => {
+        try { child.kill('SIGKILL'); } catch { /* gone */ }
+      }, KILL_GRACE_MS);
+      killGrace.unref && killGrace.unref();
+      if (!settled) {
+        settled = true;
+        // Note: the child may still be alive (waiting out the SIGKILL
+        // grace window). Keep it in liveChildren so the exit hook can
+        // reap it; its late 'close' is a no-op because `settled` is true.
+        resolve({
+          ok: false,
+          error: 'timed out',
+          code: 'ETIMEDOUT',
+          stdout: truncate(outText, maxChars),
+          stderr: truncate(errText, maxChars),
+          identity,
+          durationMs: Date.now() - startedAt
+        });
+      }
+    }, timeoutMs);
+    timer.unref && timer.unref();
+
+    child.on('error', (e) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killGrace) clearTimeout(killGrace);
+      liveChildren.delete(child);
+      resolve({ ok: false, error: e.message, code: 'ESPAWN', durationMs: Date.now() - startedAt });
+    });
+
+    child.on('close', (exitCode) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (killGrace) clearTimeout(killGrace);
+      liveChildren.delete(child);
+      resolve({
+        ok: exitCode === 0,
+        stdout: truncate(outText, maxChars),
+        stderr: truncate(errText, maxChars),
+        exitCode: exitCode == null ? -1 : exitCode,
+        identity,
+        durationMs: Date.now() - startedAt
+      });
+    });
+  });
+}
+
+module.exports = {
+  runShell,
+  resolveSandbox,
+  truncate,
+  SPEC,
+  DEFAULT_TIMEOUT_MS,
+  MAX_TIMEOUT_MS,
+  DEFAULT_MAX_CHARS,
+  DEFAULT_MAX_BYTES,
+  shellLabel,
+  shellDialectHint,
+  platformShell
+};

package/src/tools/subagent.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// Native `subagent` tool — delegates a focused prompt to a nested model call.
+// The nested call uses the same model and the same project tool surface (except
+// subagent itself, to avoid recursive delegation loops). Tool authorization is
+// still enforced by the normal gate. The result is returned as an ordinary tool
+// result for the parent assistant to summarize or use. When the model emits
+// several subagent calls in one turn, the tool loop runs them concurrently
+// (see the parallel branch in src/ai.js).
+
+const BASE_DESCRIPTION = 'Delegate a focused analysis or planning task to a nested AI call. The subagent can use the project tools and MCP tools, with normal authorization prompts. You may call subagent multiple times in a single turn; same-turn subagent calls run in parallel.';
+
+const AGENT_DESCRIPTION = 'Optional project agent name (from Settings → Project → Agents) to use for this delegation.';
+
+const SPEC = {
+  type: 'function',
+  function: {
+    name: 'subagent',
+    description: BASE_DESCRIPTION,
+    parameters: {
+      type: 'object',
+      properties: {
+        task: { type: 'string', description: 'The focused task or question for the subagent.' },
+        context: { type: 'string', description: 'Optional relevant context to include with the task.' },
+        agent: { type: 'string', description: AGENT_DESCRIPTION }
+      },
+      required: ['task'],
+      additionalProperties: false
+    }
+  }
+};
+
+// buildSpec(agentNames)
+//
+// Return the tool spec with the `agent` parameter description listing
+// the project's currently-defined agent names, so the model sees
+// exactly what it can pass. With no agents the base spec is returned.
+function buildSpec(agentNames) {
+  const names = Array.isArray(agentNames) ? agentNames.filter(Boolean) : [];
+  if (!names.length) return SPEC;
+  const spec = JSON.parse(JSON.stringify(SPEC));
+  spec.function.parameters.properties.agent.description =
+    AGENT_DESCRIPTION + ' Available agents: ' + names.join(', ') + '.';
+  return spec;
+}
+
+module.exports = { SPEC, buildSpec };

package/src/tools/task.js

@@ -0,0 +1,234 @@
+'use strict';
+
+// Native `task` tool — lets the model define structured tasks with subtasks,
+// track progress, and mark items done. Tasks are stored in-memory per chat
+// (they are ephemeral and do not survive a server restart). Each task has an
+// auto-generated id so the model can reference it across turns.
+//
+// Public surface:
+//   SPEC           — the OpenAI-compatible tool spec advertised to the model.
+//   validateArgs   — validate and normalize the incoming arguments.
+//   buildResult    — shape the runner result.
+//   dispatchTask   — execute a task action and return the result.
+//   clearChat      — remove all tasks for a chat (called on chat delete).
+//   listChatTasks  — return the task list for a chat (for UI queries).
+
+const crypto = require('node:crypto');
+
+// In-memory store: Map<chatId, Map<taskId, task>>
+const taskStore = new Map();
+
+function tasksFor(chatId) {
+  if (!chatId || typeof chatId !== 'string') return null;
+  if (!taskStore.has(chatId)) taskStore.set(chatId, new Map());
+  return taskStore.get(chatId);
+}
+
+function nextId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+const MAX_TITLE_CHARS = 60;
+const MAX_DESC_CHARS = 2000;
+const MAX_SUBTASK_TITLE_CHARS = 200;
+const MAX_TASKS_PER_CHAT = 50;
+
+const SPEC = {
+  type: 'function',
+  function: {
+    name: 'task',
+    description: 'Create, update, track progress on, and list structured tasks with subtasks. Use this to break down complex work into manageable pieces and show progress to the user. Each task gets an auto-generated ID you reference in later calls.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['create', 'update_progress', 'list', 'complete'],
+          description: 'Action to perform: create a new task, update progress on an existing task, list all tasks in the current chat, or mark a task complete.'
+        },
+        title: {
+          type: 'string',
+          description: 'Task title (required when action is "create", max 60 chars). Keep it short — a few words.'
+        },
+        description: {
+          type: 'string',
+          description: 'Optional task description (max 2000 chars).'
+        },
+        taskId: {
+          type: 'string',
+          description: 'The task ID returned when the task was created. Required for "update_progress", "complete".'
+        },
+        current: {
+          type: 'number',
+          description: 'Current progress count (0-based). Required for "update_progress". Ignored for other actions.'
+        },
+        total: {
+          type: 'number',
+          description: 'Total progress count. Required for "update_progress". Ignored for other actions.'
+        }
+      },
+      required: ['action'],
+      additionalProperties: false
+    }
+  }
+};
+
+function trimString(value, max) {
+  if (typeof value !== 'string') return '';
+  const s = value.trim();
+  if (s.length <= max) return s;
+  return s.slice(0, max);
+}
+
+function validateArgs(args) {
+  if (!args || typeof args !== 'object') {
+    const e = new Error('args is required'); e.code = 'EBADINPUT'; throw e;
+  }
+  const action = args.action;
+  if (action !== 'create' && action !== 'update_progress' && action !== 'list' && action !== 'complete') {
+    const e = new Error('action must be "create", "update_progress", "list", or "complete"'); e.code = 'EBADINPUT'; throw e;
+  }
+  if (action === 'create') {
+    const title = trimString(args.title, MAX_TITLE_CHARS);
+    if (!title) {
+      const e = new Error('title is required when action is "create"'); e.code = 'EBADINPUT'; throw e;
+    }
+    return {
+      action: 'create',
+      title,
+      description: trimString(args.description, MAX_DESC_CHARS)
+    };
+  }
+  if (action === 'update_progress') {
+    const taskId = typeof args.taskId === 'string' && args.taskId.trim() ? args.taskId.trim() : null;
+    if (!taskId) {
+      const e = new Error('taskId is required when action is "update_progress"'); e.code = 'EBADINPUT'; throw e;
+    }
+    const current = Number.isFinite(args.current) ? Math.max(0, Math.round(args.current)) : null;
+    const total = Number.isFinite(args.total) ? Math.max(1, Math.round(args.total)) : null;
+    if (current == null || total == null) {
+      const e = new Error('current and total are required when action is "update_progress"'); e.code = 'EBADINPUT'; throw e;
+    }
+    return { action: 'update_progress', taskId, current, total };
+  }
+  if (action === 'complete') {
+    const taskId = typeof args.taskId === 'string' && args.taskId.trim() ? args.taskId.trim() : null;
+    if (!taskId) {
+      const e = new Error('taskId is required when action is "complete"'); e.code = 'EBADINPUT'; throw e;
+    }
+    return { action: 'complete', taskId };
+  }
+  // list — no extra args
+  return { action: 'list' };
+}
+
+// dispatchTask(chatId, args) -> { ok, content, result }
+//
+// args must already be validated by validateArgs.
+function dispatchTask(chatId, validated) {
+  if (!chatId) {
+    return { ok: false, content: JSON.stringify({ error: 'chatId is required' }), result: { error: 'chatId is required' } };
+  }
+
+  if (validated.action === 'list') {
+    const tasks = tasksFor(chatId);
+    if (!tasks || !tasks.size) {
+      const result = { tasks: [] };
+      return { ok: true, content: JSON.stringify(result), result };
+    }
+    const taskList = [];
+    for (const t of tasks.values()) {
+      taskList.push(t);
+    }
+    // Sort by creation order
+    taskList.sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
+    const result = { tasks: taskList };
+    return { ok: true, content: JSON.stringify(result), result };
+  }
+
+  if (validated.action === 'create') {
+    const tasks = tasksFor(chatId);
+    if (!tasks) {
+      return { ok: false, content: JSON.stringify({ error: 'No chat context' }), result: { error: 'No chat context' } };
+    }
+    if (tasks.size >= MAX_TASKS_PER_CHAT) {
+      return { ok: false, content: JSON.stringify({ error: 'Maximum tasks per chat reached (' + MAX_TASKS_PER_CHAT + ')' }), result: { error: 'Maximum tasks per chat reached' } };
+    }
+    const id = nextId();
+    const task = {
+      id,
+      title: validated.title,
+      description: validated.description || '',
+      status: 'in_progress',
+      current: 0,
+      total: 100,
+      createdAt: Date.now()
+    };
+    tasks.set(id, task);
+    const result = { task, action: 'created' };
+    return { ok: true, content: JSON.stringify(result), result };
+  }
+
+  if (validated.action === 'update_progress') {
+    const tasks = tasksFor(chatId);
+    if (!tasks || !tasks.has(validated.taskId)) {
+      return { ok: false, content: JSON.stringify({ error: 'task not found', taskId: validated.taskId }), result: { error: 'task not found', taskId: validated.taskId } };
+    }
+    const task = tasks.get(validated.taskId);
+    task.current = validated.current;
+    task.total = validated.total;
+    const result = {
+      task: {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        current: task.current,
+        total: task.total
+      },
+      action: 'progress_updated'
+    };
+    return { ok: true, content: JSON.stringify(result), result };
+  }
+
+  if (validated.action === 'complete') {
+    const tasks = tasksFor(chatId);
+    if (!tasks || !tasks.has(validated.taskId)) {
+      return { ok: false, content: JSON.stringify({ error: 'task not found', taskId: validated.taskId }), result: { error: 'task not found', taskId: validated.taskId } };
+    }
+    const task = tasks.get(validated.taskId);
+    task.status = 'completed';
+    task.current = task.total;
+    const result = {
+      task: {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        current: task.current,
+        total: task.total
+      },
+      action: 'completed'
+    };
+    return { ok: true, content: JSON.stringify(result), result };
+  }
+
+  return { ok: false, content: JSON.stringify({ error: 'unknown action' }), result: { error: 'unknown action' } };
+}
+
+function clearChat(chatId) {
+  taskStore.delete(chatId);
+}
+
+function listChatTasks(chatId) {
+  const tasks = taskStore.get(chatId);
+  if (!tasks) return [];
+  return Array.from(tasks.values()).sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
+}
+
+module.exports = {
+  SPEC,
+  validateArgs,
+  dispatchTask,
+  clearChat,
+  listChatTasks,
+  MAX_TASKS_PER_CHAT
+};