@ryuu-reinzz/ryuu-cli 0.0.0-stage → 0.4.0

package/src/tools/registry.js

@@ -0,0 +1,118 @@
+import { RyuuError, ToolError, ToolNotFoundError, ValidationError } from '../utils/errors.js';
+import { validateSchema } from '../utils/validation.js';
+
+export const RISK_LEVELS = ['read', 'write', 'exec', 'destructive'];
+const NAME_PATTERN = /^[a-z][a-z0-9_]{1,60}$/;
+
+/**
+ * Define a tool with validation. Every tool is: name, description, JSON schema,
+ * a risk level, an async handler, and optional preview/approval metadata.
+ */
+export function defineTool(definition) {
+  if (!definition || typeof definition !== 'object') throw new ToolError('Tool definition must be an object.');
+  const { name, description, schema, risk = 'read', handler, preview = null, requiresApproval } = definition;
+  if (typeof name !== 'string' || !NAME_PATTERN.test(name)) {
+    throw new ToolError(`Invalid tool name: ${JSON.stringify(name)} (expected lowercase snake_case).`);
+  }
+  if (typeof description !== 'string' || description.trim().length < 10) {
+    throw new ToolError(`Tool ${name} needs a descriptive description.`);
+  }
+  if (!schema || schema.type !== 'object' || typeof schema.properties !== 'object') {
+    throw new ToolError(`Tool ${name} needs an object JSON schema with properties.`);
+  }
+  if (!RISK_LEVELS.includes(risk)) {
+    throw new ToolError(`Tool ${name} has invalid risk "${risk}" (allowed: ${RISK_LEVELS.join(', ')}).`);
+  }
+  if (typeof handler !== 'function') throw new ToolError(`Tool ${name} needs a handler function.`);
+  if (preview !== null && typeof preview !== 'function') throw new ToolError(`Tool ${name} preview must be a function.`);
+  return Object.freeze({
+    ...definition,
+    risk,
+    requiresApproval: requiresApproval ?? risk !== 'read',
+  });
+}
+
+export class ToolRegistry {
+  constructor({ logger = null } = {}) {
+    this.logger = logger;
+    this.tools = new Map();
+    this.plugins = new Map();
+  }
+
+  register(toolDefinition) {
+    const tool = defineTool(toolDefinition);
+    if (this.tools.has(tool.name)) {
+      throw new ToolError(`Tool name collision: ${tool.name} is already registered.`);
+    }
+    this.tools.set(tool.name, tool);
+    this.logger?.debug('tool registered', { name: tool.name, risk: tool.risk });
+    return tool;
+  }
+
+  /**
+   * Register a group of tools as a plugin. Collisions with built-ins fail loudly
+   * so a plugin can never silently shadow workspace tooling.
+   */
+  registerPlugin(plugin) {
+    if (!plugin || typeof plugin !== 'object') throw new ToolError('Plugin must be an object.');
+    const name = String(plugin.name || '');
+    if (!/^[a-z][a-z0-9_-]{1,40}$/.test(name)) throw new ToolError(`Invalid plugin name: ${JSON.stringify(plugin.name)}`);
+    if (this.plugins.has(name)) throw new ToolError(`Plugin already registered: ${name}`);
+    if (!Array.isArray(plugin.tools) || plugin.tools.length === 0) throw new ToolError(`Plugin ${name} must expose at least one tool.`);
+    const prepared = plugin.tools.map((tool) => defineTool(tool));
+    for (const tool of prepared) {
+      if (this.tools.has(tool.name)) {
+        throw new ToolError(`Plugin ${name} tool collision: ${tool.name} is already registered.`);
+      }
+    }
+    for (const tool of prepared) this.tools.set(tool.name, tool);
+    this.plugins.set(name, { name, version: plugin.version || '0.0.0', toolNames: prepared.map((t) => t.name) });
+    return { name, tools: prepared.map((t) => t.name) };
+  }
+
+  get(name) {
+    const tool = this.tools.get(name);
+    if (!tool) throw new ToolNotFoundError(name);
+    return tool;
+  }
+
+  has(name) {
+    return this.tools.has(name);
+  }
+
+  list() {
+    return [...this.tools.values()];
+  }
+
+  /** OpenAI-compatible tool schemas for chat.completions. */
+  toOpenAITools() {
+    return this.list().map((tool) => ({
+      type: 'function',
+      function: {
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.schema,
+      },
+    }));
+  }
+
+  /** Validate arguments and run the handler. Unknown tools cannot execute. */
+  async execute(name, args, ctx = {}) {
+    const tool = this.get(name);
+    const errors = validateSchema(tool.schema, args ?? {});
+    if (errors.length > 0) {
+      throw new ValidationError(`Invalid arguments for ${name}: ${errors.join('; ')}`, { tool: name, errors });
+    }
+    const startedAt = Date.now();
+    try {
+      const result = await tool.handler(args ?? {}, ctx);
+      return { result, durationMs: Date.now() - startedAt };
+    } catch (error) {
+      if (error?.name === 'AbortError' || error?.code === 'CANCELLED') throw error;
+      // Preserve actionable semantics (path escape, secret block, approvals...).
+      if (error instanceof RyuuError) throw error;
+      throw new ToolError(`Tool ${name} failed: ${error.message}`, { tool: name, cause: error?.message });
+    }
+  }
+}
+

package/src/tools/search.js

@@ -0,0 +1,210 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { defineTool } from './registry.js';
+import { isIgnoredName, isSecretPath } from '../services/workspace.js';
+import { ToolError } from '../utils/errors.js';
+
+const MAX_VISITED = 20000;
+const MAX_FILES = 5000;
+const MAX_LINE_PREVIEW = 240;
+
+/**
+ * Build the search service. Bounded in every dimension so a large repository
+ * cannot hang the agent or flood the context window.
+ */
+export function createSearchService({ workspace, config, logger = null }) {
+  return async function searchFiles({
+    query,
+    target = 'both',
+    path: startPath = '.',
+    regex = false,
+    caseSensitive = false,
+    maxResults,
+    includeGenerated = false,
+  }) {
+    if (typeof query !== 'string' || query.length === 0) throw new ToolError('query must be a non-empty string.');
+    const limit = Math.max(1, Math.min(maxResults ?? config.maxSearchResults, config.maxSearchResults));
+    const root = workspace.resolve(startPath || '.');
+    let rootStat;
+    try {
+      rootStat = await fsp.stat(root.absPath);
+    } catch {
+      throw new ToolError(`Search path not found: ${root.relPath}`);
+    }
+
+    let matcher;
+    if (regex) {
+      try {
+        matcher = new RegExp(query, `${caseSensitive ? '' : 'i'}g`);
+      } catch (error) {
+        throw new ToolError(`Invalid regular expression: ${error.message}`);
+      }
+    } else {
+      matcher = null;
+    }
+
+    const matches = [];
+    let visited = 0;
+    let filesScanned = 0;
+    let directories = 0;
+    let truncated = false;
+    const warnings = [];
+
+    const matchText = (text) => {
+      if (matcher) {
+        matcher.lastIndex = 0;
+        return matcher.test(text);
+      }
+      return caseSensitive ? text.includes(query) : text.toLowerCase().includes(query.toLowerCase());
+    };
+
+    const searchContent = async (absFile, relFile, size) => {
+      if (size > config.maxFileBytes) {
+        warnings.push(`Skipped large file (${size} bytes): ${relFile}`);
+        return;
+      }
+      let buffer;
+      try {
+        buffer = await fsp.readFile(absFile);
+      } catch (error) {
+        warnings.push(`Unreadable file: ${relFile} (${error.code || error.message})`);
+        return;
+      }
+      if (buffer.includes(0)) return;
+      const text = new TextDecoder('utf-8').decode(buffer);
+      if (text.includes('\uFFFD')) {
+        warnings.push(`Skipped non-UTF-8 file: ${relFile}`);
+        return;
+      }
+      filesScanned += 1;
+      const lines = text.split(/\r?\n/);
+      for (let index = 0; index < lines.length && matches.length < limit; index += 1) {
+        const line = lines[index];
+        if (!matchText(line)) continue;
+        let column = 1;
+        if (matcher) {
+          matcher.lastIndex = 0;
+          const found = matcher.exec(line);
+          column = (found?.index ?? 0) + 1;
+        } else {
+          const found = caseSensitive ? line.indexOf(query) : line.toLowerCase().indexOf(query.toLowerCase());
+          column = (found < 0 ? 0 : found) + 1;
+        }
+        const preview = line.length > MAX_LINE_PREVIEW ? `${line.slice(0, MAX_LINE_PREVIEW)}…` : line;
+        matches.push({ type: 'content', file: relFile, line: index + 1, column, text: preview });
+      }
+    };
+
+    const consider = async (absFile, relFile, size) => {
+      if (matches.length >= limit) {
+        truncated = true;
+        return;
+      }
+      if (target === 'name' || target === 'both') {
+        if (matchText(path.basename(relFile))) {
+          matches.push({ type: 'name', file: relFile, size });
+        }
+      }
+      if ((target === 'content' || target === 'both') && matches.length < limit) {
+        await searchContent(absFile, relFile, size);
+      }
+    };
+
+    if (rootStat.isFile()) {
+      const rel = root.relPath;
+      if (!isSecretPath(rel)) await consider(root.absPath, rel, rootStat.size);
+    } else if (rootStat.isDirectory()) {
+      const stack = [{ abs: root.absPath, rel: root.relPath }];
+      outer: while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+          entries = await fsp.readdir(dir.abs, { withFileTypes: true });
+        } catch (error) {
+          warnings.push(`Unreadable directory: ${dir.rel} (${error.code || error.message})`);
+          continue;
+        }
+        directories += 1;
+        for (const entry of entries) {
+          visited += 1;
+          if (visited > MAX_VISITED) {
+            truncated = true;
+            break outer;
+          }
+          const rel = dir.rel === '.' ? entry.name : `${dir.rel}/${entry.name}`;
+          if (isSecretPath(rel)) continue;
+          if (!includeGenerated && isIgnoredName(entry.name)) continue;
+          if (entry.name.startsWith('.ryuu-tmp-')) continue;
+          if (entry.isSymbolicLink()) continue;
+          if (entry.isDirectory()) {
+            stack.push({ abs: path.join(dir.abs, entry.name), rel });
+            continue;
+          }
+          if (!entry.isFile()) continue;
+          if (filesScanned >= MAX_FILES) {
+            truncated = true;
+            break outer;
+          }
+          let stat;
+          try {
+            stat = await fsp.stat(path.join(dir.abs, entry.name));
+          } catch {
+            continue;
+          }
+          await consider(path.join(dir.abs, entry.name), rel, stat.size);
+          if (matches.length >= limit) {
+            truncated = true;
+            break outer;
+          }
+        }
+      }
+    }
+
+    logger?.debug('search complete', { query: query.slice(0, 80), matches: matches.length, visited });
+    return {
+      query: regex ? `/${query}/` : query,
+      target,
+      root: root.relPath,
+      matches,
+      count: matches.length,
+      truncated,
+      limits: { maxResults: limit, visited, maxVisited: MAX_VISITED, filesScanned, maxFiles: MAX_FILES, directories },
+      warnings: warnings.slice(0, 10),
+    };
+  };
+}
+
+export function createSearchTools({ workspace, config, logger }) {
+  const searchFiles = createSearchService({ workspace, config, logger });
+  return [
+    defineTool({
+      name: 'search_files',
+      description:
+        'Search file names and/or text contents in the workspace. Skips secret files, binaries, generated directories and oversized files. Results are bounded; refine the path or query when truncated.',
+      risk: 'read',
+      schema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', minLength: 1, maxLength: 500, description: 'Literal text or regular expression.' },
+          target: { type: 'string', enum: ['content', 'name', 'both'], description: 'What to search (default both).' },
+          path: { type: 'string', minLength: 1, maxLength: 4096, description: 'Directory to search (default workspace root).' },
+          regex: { type: 'boolean', description: 'Interpret query as a regular expression.' },
+          case_sensitive: { type: 'boolean' },
+          max_results: { type: 'integer', minimum: 1, maximum: 500 },
+          include_generated: { type: 'boolean', description: 'Include node_modules/.git/dist (default false).' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      handler: async (args) => searchFiles({
+        query: args.query,
+        target: args.target ?? 'both',
+        path: args.path ?? '.',
+        regex: args.regex ?? false,
+        caseSensitive: args.case_sensitive ?? false,
+        maxResults: args.max_results,
+        includeGenerated: args.include_generated ?? false,
+      }),
+    }),
+  ];
+}

package/src/tools/shell.js

@@ -0,0 +1,279 @@
+import { defineTool } from './registry.js';
+import { ToolError } from '../utils/errors.js';
+
+/** Read-only binaries that are reasonable to run during debugging. */
+const SAFE_BINARIES = new Set(['git', 'node', 'npm', 'npx', 'pnpm', 'yarn', 'python', 'python3', 'pytest', 'go', 'cargo', 'rustc', 'tsc', 'eslint', 'vitest', 'jest', 'mocha', 'ls', 'cat', 'grep', 'rg', 'find', 'head', 'tail', 'wc', 'diff']);
+
+const CRITICAL_BINARIES = new Set(['sudo', 'su', 'doas', 'pkexec', 'mkfs', 'mkfs.ext4', 'dd', 'shutdown', 'reboot', 'halt', 'poweroff', 'fdisk', 'parted']);
+
+/**
+ * Static, best-effort command assessment. This is a UX signal for the approval
+ * prompt, not a security boundary: any approval-gated command can still be
+ * dangerous, and shell execution is explicitly not a sandbox.
+ */
+export function assessCommand(argv) {
+  const reasons = [];
+  let level = 'normal';
+  const command = argv[0] || '';
+  const rest = argv.slice(1);
+  const base = command.split('/').pop();
+
+  if (CRITICAL_BINARIES.has(base)) {
+    level = 'critical';
+    reasons.push(`privileged/destructive binary: ${base}`);
+  }
+  if (/^(rm|unlink|rmdir)$/.test(base)) {
+    const recursive = rest.some((arg) => /^-[a-zA-Z]*[rR]/.test(arg));
+    const targets = rest.filter((arg) => !arg.startsWith('-'));
+    if (recursive && targets.some((target) => target === '/' || target === '~' || target === '..' || /^\/(\*|$)/.test(target))) {
+      level = 'critical';
+      reasons.push('recursive delete of a root/home/parent path');
+    } else {
+      if (level === 'normal') level = 'high';
+      reasons.push('file deletion');
+    }
+  }
+  if (base === 'git' && rest.some((arg) => ['push', 'reset', 'clean', 'checkout'].includes(arg))) {
+    const force = rest.some((arg) => ['--force', '-f', '--hard', '-fd', '-df'].includes(arg));
+    if (force) {
+      level = 'critical';
+      reasons.push('destructive git operation with force/hard flags');
+    } else {
+      if (level === 'normal') level = 'high';
+      reasons.push('git operation that can modify history or working tree');
+    }
+  }
+  if (base === 'npm' && ['publish', 'unpublish'].includes(rest[0])) {
+    level = 'critical';
+    reasons.push('publishes packages to a registry');
+  }
+  if (['npx', 'bunx'].includes(base) || (base === 'npm' && rest[0] === 'exec')) {
+    if (level === 'normal') level = 'high';
+    reasons.push('downloads and executes a remote package');
+  }
+  if ((base === 'npm' || base === 'pnpm' || base === 'yarn') && ['install', 'add', 'i'].includes(rest[0])) {
+    if (level === 'normal') level = 'high';
+    reasons.push('dependency installation (network + scripts)');
+  }
+  if (['chmod', 'chown', 'chgrp'].includes(base)) {
+    if (level === 'normal') level = 'high';
+    reasons.push('permission/ownership change');
+  }
+  if (base === 'kill' || base === 'pkill' || base === 'killall') {
+    if (level === 'normal') level = 'high';
+    reasons.push('signals other processes');
+  }
+  if (base.startsWith('curl') || base === 'wget') {
+    if (level === 'normal') level = 'high';
+    reasons.push('network download');
+  }
+  if (!SAFE_BINARIES.has(base) && level === 'normal') {
+    reasons.push('non-standard binary (review carefully)');
+  }
+  return { level, reasons };
+}
+
+export function assessShellString(command) {
+  const reasons = [];
+  let level = 'high';
+  const text = String(command || '');
+  if (/\bsudo\b|\bsu\s/.test(text)) {
+    level = 'critical';
+    reasons.push('privilege escalation');
+  }
+  if (/\brm\s+(-[a-zA-Z]*[rR][a-zA-Z]*\s+)?\/(\s|$|\*)/.test(text) || /\brm\s+-rf\s+~/.test(text)) {
+    level = 'critical';
+    reasons.push('recursive delete at filesystem root or home');
+  }
+  if (/\|\s*(ba)?sh\b|\|\s*python/.test(text)) {
+    level = 'critical';
+    reasons.push('pipes a remote/untrusted payload into an interpreter');
+  }
+  if (/mkfs|\bdd\s+.*of=\/dev|>\s*\/dev\/sd/.test(text)) {
+    level = 'critical';
+    reasons.push('writes directly to block devices');
+  }
+  if (level !== 'critical') reasons.push('raw shell syntax: pipes, redirects or chaining may run anything');
+  return { level, reasons };
+}
+
+const outputLimit = (config) => Math.max(4000, Math.min(config.maxToolOutputBytes, 200000));
+
+export function createShellTools({ workspace, config, processes, logger = null }) {
+  return [
+    defineTool({
+      name: 'run_command',
+      description:
+        'Run a command in the workspace and wait for completion. Prefer argv (e.g. ["npm","test"]); shell:false is used. Raw shell syntax requires agent.allowShell=true in config.json and an explicit approval. Every execution is approval-gated. Shell execution is NOT a sandbox.',
+      risk: 'exec',
+      requiresApproval: true,
+      schema: {
+        type: 'object',
+        properties: {
+          argv: {
+            type: 'array',
+            items: { type: 'string', minLength: 1, maxLength: 20000 },
+            minItems: 1,
+            maxItems: 200,
+            description: 'Command and arguments, e.g. ["npm", "test"].',
+          },
+          shell_command: { type: 'string', minLength: 1, maxLength: 4000, description: 'Raw shell string (only when agent.allowShell=true).' },
+          cwd: { type: 'string', minLength: 1, maxLength: 4096, description: 'Workspace-relative working directory.' },
+          timeout_ms: { type: 'integer', minimum: 1000, maximum: 600000, description: 'Timeout (default 120000).' },
+          description: { type: 'string', maxLength: 200, description: 'Why this command is needed.' },
+        },
+        additionalProperties: false,
+      },
+      assess: (args) => (args.shell_command ? assessShellString(args.shell_command) : assessCommand(args.argv || [])),
+      preview: async (args) => {
+        const display = args.shell_command ? `$ ${args.shell_command}\n(shell syntax)` : `$ ${(args.argv || []).join(' ')}`;
+        const cwd = args.cwd || '.';
+        const assessment = args.shell_command ? assessShellString(args.shell_command) : assessCommand(args.argv || []);
+        const lines = [`${display}\ncwd: ${workspace.resolve(cwd).relPath}`, `risk: ${assessment.level}`];
+        if (assessment.reasons.length > 0) lines.push(`notes:\n- ${assessment.reasons.join('\n- ')}`);
+        lines.push('Shell execution is not a sandbox.');
+        return lines.join('\n');
+      },
+      handler: async (args, ctx = {}) => {
+        if (args.argv && args.shell_command) {
+          throw new ToolError('Provide either argv or shell_command, not both.');
+        }
+        if (args.shell_command && !config.allowShell) {
+          throw new ToolError(
+            'Shell syntax is disabled. Pass an argv array instead, or ask the user to set agent.allowShell=true in config.json and approve the raw command.',
+          );
+        }
+        if (!args.argv && !args.shell_command) throw new ToolError('Provide argv (preferred) or shell_command.');
+        const assessment = args.shell_command ? assessShellString(args.shell_command) : assessCommand(args.argv);
+        const record = processes.start({
+          argv: args.argv,
+          shellCommand: args.shell_command || null,
+          cwd: args.cwd || '.',
+          timeoutMs: args.timeout_ms ?? 120000,
+          allowShell: config.allowShell,
+          label: args.description || undefined,
+        });
+        const onAbort = () => {
+          processes.stop(record.id, { graceMs: 1000 }).catch(() => {});
+        };
+        ctx.signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+          await record.done;
+        } finally {
+          ctx.signal?.removeEventListener('abort', onAbort);
+        }
+        const limit = outputLimit(config);
+        const stdout = record.stdout.text;
+        const stderr = record.stderr.text;
+        logger?.info('command finished', {
+          id: record.id,
+          argv: record.argv,
+          exitCode: record.exitCode,
+          status: record.status,
+          durationMs: record.durationMs,
+        });
+        return {
+          process_id: record.id,
+          argv: record.argv,
+          cwd: record.cwd,
+          status: record.status,
+          exit_code: record.exitCode,
+          signal: record.signal,
+          duration_ms: record.durationMs,
+          timed_out: record.timedOut,
+          risk: assessment,
+          stdout: stdout.length > limit ? `…[tail of output]…\n${stdout.slice(-limit)}` : stdout,
+          stderr: stderr.length > limit ? `…[tail of output]…\n${stderr.slice(-limit)}` : stderr,
+          truncated: record.truncated,
+          ok: record.status === 'exited' && record.exitCode === 0,
+        };
+      },
+    }),
+
+    defineTool({
+      name: 'start_process',
+      description:
+        'Start a long-running process (dev server, watcher) without blocking the agent. Returns a process id immediately. Use get_process_output to poll it and stop_process to stop it. Approval-gated.',
+      risk: 'exec',
+      requiresApproval: true,
+      schema: {
+        type: 'object',
+        properties: {
+          argv: { type: 'array', items: { type: 'string', minLength: 1, maxLength: 20000 }, minItems: 1, maxItems: 200 },
+          cwd: { type: 'string', minLength: 1, maxLength: 4096 },
+          label: { type: 'string', maxLength: 120 },
+          timeout_ms: { type: 'integer', minimum: 0, maximum: 3600000, description: '0 means no timeout (default 0 for background processes).' },
+        },
+        required: ['argv'],
+        additionalProperties: false,
+      },
+      assess: (args) => assessCommand(args.argv),
+      preview: async (args) => `Start background process: ${args.argv.join(' ')}\ncwd: ${workspace.resolve(args.cwd || '.').relPath}`,
+      handler: async (args) => {
+        const assessment = assessCommand(args.argv);
+        const record = processes.start({
+          argv: args.argv,
+          cwd: args.cwd || '.',
+          timeoutMs: args.timeout_ms ?? 0,
+          label: args.label,
+        });
+        return {
+          process_id: record.id,
+          pid: record.pid,
+          status: record.status,
+          argv: record.argv,
+          cwd: record.cwd,
+          risk: assessment,
+          note: 'Verify with get_process_output before assuming the service is ready.',
+        };
+      },
+    }),
+
+    defineTool({
+      name: 'list_processes',
+      description: 'List running and recently completed processes started in this session.',
+      risk: 'read',
+      schema: { type: 'object', properties: {}, additionalProperties: false },
+      handler: async () => ({ processes: processes.list() }),
+    }),
+
+    defineTool({
+      name: 'get_process_output',
+      description: 'Read captured stdout/stderr and status for a process started in this session.',
+      risk: 'read',
+      schema: {
+        type: 'object',
+        properties: {
+          process_id: { type: 'string', minLength: 1, maxLength: 40 },
+          stream: { type: 'string', enum: ['stdout', 'stderr', 'both'] },
+          tail_bytes: { type: 'integer', minimum: 100, maximum: 200000 },
+        },
+        required: ['process_id'],
+        additionalProperties: false,
+      },
+      handler: async (args) => processes.getOutput(args.process_id, {
+        stream: args.stream ?? 'both',
+        tailBytes: args.tail_bytes ?? outputLimit(config),
+      }),
+    }),
+
+    defineTool({
+      name: 'stop_process',
+      description: 'Stop a running process with SIGTERM, escalating to SIGKILL after a grace period. Approval-gated.',
+      risk: 'exec',
+      requiresApproval: true,
+      schema: {
+        type: 'object',
+        properties: {
+          process_id: { type: 'string', minLength: 1, maxLength: 40 },
+          grace_ms: { type: 'integer', minimum: 100, maximum: 10000 },
+        },
+        required: ['process_id'],
+        additionalProperties: false,
+      },
+      assess: () => ({ level: 'high', reasons: ['terminates a running process started in this session'] }),
+      preview: async (args) => `Stop process ${args.process_id}`,
+      handler: async (args) => processes.stop(args.process_id, { graceMs: args.grace_ms ?? 3000 }),
+    }),
+  ];
+}