khabotcli 1.0.0

package/tools/agent_send.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const db = require('../infrastructure/database');
+const { loadAgent } = require('../core/agent');
+const runningSessions = require('../core/running-sessions');
+
+const schema = {
+  name: 'agent_send',
+  description: 'Send a message to another agent without waiting for a response (fire-and-forget async).',
+  input_schema: {
+    type: 'object',
+    properties: {
+      agent: { type: 'string', description: 'Name of the target agent' },
+      sessionId: { type: 'string', description: 'Session ID of the target agent session to send the message to. Obtain this from agent_spawn.' },
+      message: { type: 'string', description: 'Message to send' },
+      followup: { type: 'boolean', description: 'If true, message is only delivered after the agent finishes its current task (default: false)' },
+    },
+    required: ['agent', 'sessionId', 'message'],
+  },
+  timeout: 5,
+};
+
+async function execute({ agent, message, sessionId, followup = false, _cwd, _settings, _agent: senderAgent }) {
+  try { loadAgent({ cwd: _cwd, name: agent }); } catch (err) {
+    return `Error: target agent "${agent}" not found — ${err.message}`;
+  }
+  const targetSession = db.getSession(sessionId);
+  if (!targetSession) return `Error: session "${sessionId}" not found.`;
+  if (targetSession.agent_name !== agent) return `Error: session "${sessionId}" belongs to agent "${targetSession.agent_name}", not "${agent}".`;
+
+  const fromAgent = senderAgent?.name || 'unknown';
+
+  // Idle chat session — fire-and-forget a new turn
+  if (!runningSessions.has(sessionId) && targetSession.mode === 'chat') {
+    const { runChat } = require('../core/router');
+    runChat({
+      agentName: agent,
+      message: `[Message from ${fromAgent}]: ${message}`,
+      sessionId,
+      cwd: _cwd,
+      settings: _settings,
+    }).catch(() => {});
+    return `Message sent to session "${sessionId}" (agent: ${agent}) — new chat turn triggered.`;
+  }
+
+  // Active session or non-chat idle session — inject via queue
+  const msgId = db.enqueueAgentMessage({
+    targetAgent: agent,
+    targetSessionId: sessionId,
+    fromAgent,
+    content: message,
+    followup,
+  });
+
+  // Background watcher: if the loop ends before picking up the message, fall back to runChat
+  if (targetSession.mode === 'chat') {
+    const wrappedMessage = `[Message from ${fromAgent}]: ${message}`;
+    const watchCwd = _cwd;
+    const watchSettings = _settings;
+    (async () => {
+      // Watch until the loop ends or the message is delivered — no hard deadline
+      while (runningSessions.has(sessionId)) {
+        await new Promise(r => setTimeout(r, 300));
+        const row = db.getDb().prepare('SELECT status FROM agent_messages WHERE id = ?').get(msgId);
+        if (!row || row.status !== 'pending') return; // delivered
+      }
+      // Loop ended — check if message was left undelivered
+      const row = db.getDb().prepare('SELECT status FROM agent_messages WHERE id = ?').get(msgId);
+      if (row && row.status === 'pending') {
+        db.getDb().prepare('DELETE FROM agent_messages WHERE id = ? AND status = ?').run(msgId, 'pending');
+        const { runChat } = require('../core/router');
+        runChat({ agentName: agent, message: wrappedMessage, sessionId, cwd: watchCwd, settings: watchSettings }).catch(() => {});
+      }
+    })().catch(() => {});
+  }
+
+  return `Message queued for session "${sessionId}" (agent: ${agent}, followup: ${followup}). It will be delivered at the next loop iteration of that session.`;
+}
+
+module.exports = { schema, execute };

package/tools/agent_spawn.js

@@ -0,0 +1,44 @@
+'use strict';
+
+const { loadAgent } = require('../core/agent');
+
+const schema = {
+  name: 'agent_spawn',
+  description: 'Start a new chat session with an agent and send the first message. Returns the sessionId and the agent response. Use the returned sessionId with agent_message for follow-up exchanges in the same conversation.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      agent: { type: 'string', description: 'Name of the agent to start a session with' },
+      message: { type: 'string', description: 'First message to send to the agent' },
+      returnMode: { type: 'string', enum: ['full', 'responseOnly'], description: 'full = { sessionId, response } (default), responseOnly = response text only' },
+    },
+    required: ['agent', 'message'],
+  },
+  timeout: 86400,
+};
+
+async function execute({ agent, message, returnMode = 'full', _cwd, _settings }) {
+  try { loadAgent({ cwd: _cwd, name: agent }); } catch (err) {
+    return `Error: agent "${agent}" not found — ${err.message}`;
+  }
+
+  try {
+    const { runChat } = require('../core/router');
+    const result = await runChat({
+      agentName: agent,
+      message,
+      sessionId: undefined,
+      cwd: _cwd,
+      settings: _settings,
+    });
+
+    if (returnMode === 'responseOnly') {
+      return result.content || '(no response)';
+    }
+    return JSON.stringify({ sessionId: result.sessionId, response: result.content });
+  } catch (err) {
+    return `Error spawning session with "${agent}": ${err.message}`;
+  }
+}
+
+module.exports = { schema, execute };

package/tools/bash.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { execSync } = require('child_process');
+
+const schema = {
+  name: 'bash',
+  description: 'Execute a shell command and return its output. Use for running scripts, tests, builds, and system operations.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'The shell command to execute' },
+      timeout: { type: 'integer', description: 'Timeout in seconds (default: 30)', minimum: 1 },
+      workingDir: { type: 'string', description: 'Working directory for the command (default: project cwd)' },
+    },
+    required: ['command'],
+  },
+  timeout: 86400,
+};
+
+/**
+ * @param {{ command: string, timeout?: number, workingDir?: string, _cwd: string }} input
+ */
+async function execute({ command, timeout = 30, workingDir, _cwd }) {
+  const cwd = workingDir || _cwd;
+  const timeoutMs = timeout * 1000;
+
+  try {
+    const output = execSync(command, {
+      cwd,
+      timeout: timeoutMs,
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024, // 10MB
+      env: process.env,
+    });
+    return output || '(no output)';
+  } catch (err) {
+    const stdout = err.stdout ? err.stdout.toString().trim() : '';
+    const stderr = err.stderr ? err.stderr.toString().trim() : '';
+    const exitCode = err.status || 1;
+
+    let result = `Exit code: ${exitCode}`;
+    if (stdout) result += `\nstdout:\n${stdout}`;
+    if (stderr) result += `\nstderr:\n${stderr}`;
+    if (err.killed) result = `Command timed out after ${timeout}s\n` + result;
+    return result;
+  }
+}
+
+module.exports = { schema, execute };

package/tools/edit_file.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const schema = {
+  name: 'edit_file',
+  description: 'Search-and-replace edit on a file. Finds old_string and replaces with new_string. The old_string must match exactly (including whitespace). Read the file first before editing.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', description: 'Path to the file (relative to cwd or absolute)' },
+      old_string: { type: 'string', description: 'Exact string to find and replace' },
+      new_string: { type: 'string', description: 'String to replace it with' },
+    },
+    required: ['file', 'old_string', 'new_string'],
+  },
+  timeout: 10,
+};
+
+async function execute({ file, old_string, new_string, _cwd }) {
+  const filePath = path.isAbsolute(file) ? file : path.resolve(_cwd, file);
+
+  if (!fs.existsSync(filePath)) return `File not found: ${filePath}`;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const occurrences = content.split(old_string).length - 1;
+
+  if (occurrences === 0) {
+    return `old_string not found in ${filePath}. The string must match exactly including whitespace and newlines.`;
+  }
+  if (occurrences > 1) {
+    return `old_string appears ${occurrences} times in ${filePath}. Provide a more unique string to avoid ambiguity.`;
+  }
+
+  const newContent = content.replace(old_string, new_string);
+  fs.writeFileSync(filePath, newContent, 'utf8');
+  return `Edited ${filePath}: replaced 1 occurrence`;
+}
+
+module.exports = { schema, execute };

package/tools/glob.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const schema = {
+  name: 'glob',
+  description: 'Find files matching a glob pattern. Returns matching file paths.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Glob pattern (e.g. "**/*.js", "src/**/*.test.js")' },
+      dir: { type: 'string', description: 'Base directory to search from (default: cwd)' },
+      ignore: { type: 'array', items: { type: 'string' }, description: 'Patterns to ignore (e.g. ["node_modules/**"])' },
+    },
+    required: ['pattern'],
+  },
+  timeout: 15,
+};
+
+/**
+ * Simple recursive glob matcher.
+ */
+function matchGlob(filePath, pattern) {
+  const regexStr = pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '__DS__')
+    .replace(/\*/g, '[^/]*')
+    .replace(/__DS__/g, '.*');
+  return new RegExp(`^${regexStr}$`).test(filePath);
+}
+
+function walkDir(dir, baseDir, ignore = []) {
+  const results = [];
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+
+    if (ignore.some(p => matchGlob(relPath, p) || relPath.startsWith(p.replace('/**', '')))) continue;
+
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, baseDir, ignore));
+    } else {
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
+async function execute({ pattern, dir, ignore = [], _cwd }) {
+  const baseDir = dir ? (path.isAbsolute(dir) ? dir : path.resolve(_cwd, dir)) : _cwd;
+  const defaultIgnore = ['node_modules/**', '.git/**', ...ignore];
+
+  const allFiles = walkDir(baseDir, baseDir, defaultIgnore);
+  const matches = allFiles.filter(f => matchGlob(f, pattern));
+
+  if (matches.length === 0) return `No files matched pattern: ${pattern}`;
+  return matches.join('\n');
+}
+
+module.exports = { schema, execute };

package/tools/grep.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const schema = {
+  name: 'grep',
+  description: 'Search file contents for a pattern. Returns matching lines with file paths and line numbers.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Search pattern (string or regex)' },
+      dir: { type: 'string', description: 'Directory to search (default: cwd)' },
+      file: { type: 'string', description: 'Specific file to search instead of directory' },
+      include: { type: 'string', description: 'File glob to include (e.g. "*.js")' },
+      ignoreCase: { type: 'boolean', description: 'Case-insensitive search (default: false)' },
+      maxResults: { type: 'integer', description: 'Maximum number of results (default: 50)', minimum: 1, maximum: 500 },
+    },
+    required: ['pattern'],
+  },
+  timeout: 20,
+};
+
+function matchesInclude(filename, include) {
+  if (!include) return true;
+  const pattern = include.replace(/\*/g, '.*').replace(/\?/g, '.');
+  return new RegExp(`^${pattern}$`).test(filename);
+}
+
+function searchFile(filePath, regex, results, maxResults) {
+  if (results.length >= maxResults) return;
+  let content;
+  try { content = fs.readFileSync(filePath, 'utf8'); } catch { return; }
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (results.length >= maxResults) break;
+    if (regex.test(lines[i])) {
+      results.push(`${filePath}:${i + 1}: ${lines[i]}`);
+    }
+  }
+}
+
+function walkDir(dir, regex, include, results, maxResults, ignoreList = ['node_modules', '.git']) {
+  if (results.length >= maxResults) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    if (ignoreList.includes(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkDir(fullPath, regex, include, results, maxResults, ignoreList);
+    } else if (matchesInclude(entry.name, include)) {
+      searchFile(fullPath, regex, results, maxResults);
+    }
+  }
+}
+
+async function execute({ pattern, dir, file, include, ignoreCase = false, maxResults = 50, _cwd }) {
+  const flags = ignoreCase ? 'gi' : 'g';
+  let regex;
+  try {
+    regex = new RegExp(pattern, flags);
+  } catch {
+    regex = new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags);
+  }
+
+  const results = [];
+
+  if (file) {
+    const filePath = path.isAbsolute(file) ? file : path.resolve(_cwd, file);
+    searchFile(filePath, regex, results, maxResults);
+  } else {
+    const searchDir = dir ? (path.isAbsolute(dir) ? dir : path.resolve(_cwd, dir)) : _cwd;
+    walkDir(searchDir, regex, include, results, maxResults);
+  }
+
+  if (results.length === 0) return `No matches found for: ${pattern}`;
+  const truncated = results.length >= maxResults ? `\n(results truncated at ${maxResults})` : '';
+  return results.join('\n') + truncated;
+}
+
+module.exports = { schema, execute };

package/tools/list_dir.js

@@ -0,0 +1,63 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const schema = {
+  name: 'list_dir',
+  description: 'List directory contents with file sizes and types.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      dir: { type: 'string', description: 'Directory path (relative to cwd or absolute)' },
+      recursive: { type: 'boolean', description: 'List recursively (default: false)' },
+    },
+    required: ['dir'],
+  },
+  timeout: 10,
+};
+
+function listRecursive(dirPath, baseDir, depth = 0) {
+  const lines = [];
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const indent = '  '.repeat(depth);
+    const fullPath = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      lines.push(`${indent}${entry.name}/`);
+      lines.push(...listRecursive(fullPath, baseDir, depth + 1));
+    } else {
+      const stat = fs.statSync(fullPath);
+      lines.push(`${indent}${entry.name} (${formatSize(stat.size)})`);
+    }
+  }
+  return lines;
+}
+
+function formatSize(bytes) {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+async function execute({ dir, recursive = false, _cwd }) {
+  const dirPath = path.isAbsolute(dir) ? dir : path.resolve(_cwd, dir);
+  if (!fs.existsSync(dirPath)) return `Directory not found: ${dirPath}`;
+  if (!fs.statSync(dirPath).isDirectory()) return `Not a directory: ${dirPath}`;
+
+  if (recursive) {
+    const lines = listRecursive(dirPath, dirPath);
+    return lines.length > 0 ? lines.join('\n') : '(empty directory)';
+  }
+
+  const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+  if (entries.length === 0) return '(empty directory)';
+
+  return entries.map(entry => {
+    if (entry.isDirectory()) return `${entry.name}/`;
+    const stat = fs.statSync(path.join(dirPath, entry.name));
+    return `${entry.name} (${formatSize(stat.size)})`;
+  }).join('\n');
+}
+
+module.exports = { schema, execute };

package/tools/log_write.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const db = require('../infrastructure/database');
+
+const schema = {
+  name: 'log_write',
+  description: 'Write a progress entry to the task log. Use to report milestones, status updates, and custom events.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      message: { type: 'string', description: 'Log message' },
+      level: { type: 'string', enum: ['info', 'warn', 'error'], description: 'Log level (default: info)' },
+      metadata: { type: 'object', description: 'Optional structured metadata' },
+    },
+    required: ['message'],
+  },
+  timeout: 5,
+};
+
+async function execute({ message, level = 'info', metadata, _taskId }) {
+  if (_taskId) {
+    db.addTaskEvent({
+      taskId: _taskId,
+      type: 'custom',
+      data: { level, message, metadata: metadata || null },
+    });
+  }
+  return `Logged [${level}]: ${message}`;
+}
+
+module.exports = { schema, execute };

package/tools/memory_read.js

@@ -0,0 +1,38 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const paths = require('../utils/paths');
+
+const schema = {
+  name: 'memory_read',
+  description: 'Read agent memory files. Defaults to MEMORY.md for the current agent.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', description: 'Memory file name (default: MEMORY.md). Can be a topic file like "research.md"' },
+      scope: { type: 'string', enum: ['agent', 'global'], description: 'Memory scope: "agent" (default) or "global" (project-level)' },
+    },
+  },
+  timeout: 10,
+};
+
+async function execute({ file = 'MEMORY.md', scope = 'agent', _cwd, _agent }) {
+  let memoryDir;
+
+  if (scope === 'global') {
+    memoryDir = paths.getProjectMemoryDir(_cwd);
+  } else {
+    memoryDir = paths.getAgentMemoryDir(_cwd, _agent.name);
+  }
+
+  const memoryFile = path.join(memoryDir, file);
+
+  if (!fs.existsSync(memoryFile)) {
+    return `Memory file not found: ${memoryFile} (no memories saved yet)`;
+  }
+
+  return fs.readFileSync(memoryFile, 'utf8');
+}
+
+module.exports = { schema, execute };

package/tools/memory_search.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const paths = require('../utils/paths');
+
+const schema = {
+  name: 'memory_search',
+  description: 'Search across project memory files for relevant content.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+      scope: { type: 'string', enum: ['project', 'agent'], description: 'Search scope: "project" (all project memory) or "agent" (current agent only). Default: "project"' },
+    },
+    required: ['query'],
+  },
+  timeout: 10,
+};
+
+function searchInFile(filePath, queryWords) {
+  if (!fs.existsSync(filePath)) return [];
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  const results = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].toLowerCase();
+    if (queryWords.some(w => line.includes(w))) {
+      results.push(`${filePath}:${i + 1}: ${lines[i].trim()}`);
+    }
+  }
+  return results;
+}
+
+function searchDir(dir, queryWords, results, maxResults = 50) {
+  if (!fs.existsSync(dir)) return;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (results.length >= maxResults) break;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      searchDir(fullPath, queryWords, results, maxResults);
+    } else if (entry.name.endsWith('.md')) {
+      results.push(...searchInFile(fullPath, queryWords).slice(0, maxResults - results.length));
+    }
+  }
+}
+
+async function execute({ query, scope = 'project', _cwd, _agent }) {
+  const queryWords = query.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+  if (queryWords.length === 0) return 'Query too short';
+
+  const results = [];
+
+  if (scope === 'project') {
+    searchDir(paths.getProjectMemoryDir(_cwd), queryWords, results);
+  } else {
+    searchDir(paths.getAgentMemoryDir(_cwd, _agent.name), queryWords, results);
+  }
+
+  if (results.length === 0) return `No memory matches found for: ${query}`;
+  return `Memory search results for "${query}":\n\n${results.join('\n')}`;
+}
+
+module.exports = { schema, execute };

package/tools/memory_write.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const paths = require('../utils/paths');
+
+const schema = {
+  name: 'memory_write',
+  description: 'Write to persistent memory. Agent-scoped by default. Use scope "global" to write to project-level memory.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      content: { type: 'string', description: 'Content to append to memory' },
+      scope: { type: 'string', enum: ['agent', 'global'], description: 'Memory scope: "agent" (default) or "global" (project-level)' },
+    },
+    required: ['content'],
+  },
+  timeout: 10,
+};
+
+async function execute({ content, scope = 'agent', _cwd, _agent }) {
+  let memoryDir, memoryFile;
+
+  if (scope === 'global') {
+    memoryDir = paths.getProjectMemoryDir(_cwd);
+    memoryFile = path.join(memoryDir, 'MEMORY.md');
+  } else {
+    memoryDir = paths.getAgentMemoryDir(_cwd, _agent.name);
+    memoryFile = path.join(memoryDir, 'MEMORY.md');
+  }
+
+  fs.mkdirSync(memoryDir, { recursive: true });
+
+  const timestamp = new Date().toISOString().slice(0, 10);
+  const entry = `\n\n<!-- ${timestamp} -->\n${content.trim()}`;
+
+  fs.appendFileSync(memoryFile, entry, 'utf8');
+
+  return `Memory written to ${scope} scope (${memoryFile})`;
+}
+
+module.exports = { schema, execute };

package/tools/read_file.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const schema = {
+  name: 'read_file',
+  description: 'Read the contents of a file. Supports offset and limit for large files.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      file: { type: 'string', description: 'Path to the file (relative to cwd or absolute)' },
+      offset: { type: 'integer', description: 'Line number to start reading from (1-indexed)', minimum: 1 },
+      limit: { type: 'integer', description: 'Maximum number of lines to read', minimum: 1 },
+    },
+    required: ['file'],
+  },
+  timeout: 10,
+};
+
+async function execute({ file, offset, limit, _cwd }) {
+  const filePath = path.isAbsolute(file) ? file : path.resolve(_cwd, file);
+
+  if (!fs.existsSync(filePath)) {
+    return `File not found: ${filePath}`;
+  }
+
+  const stat = fs.statSync(filePath);
+  if (stat.isDirectory()) return `Path is a directory: ${filePath}`;
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  const total = lines.length;
+
+  let start = 0;
+  let end = lines.length;
+
+  if (offset !== undefined) start = Math.max(0, offset - 1);
+  if (limit !== undefined) end = Math.min(lines.length, start + limit);
+
+  const selected = lines.slice(start, end);
+  const numbered = selected.map((l, i) => `${String(start + i + 1).padStart(4)} | ${l}`).join('\n');
+
+  const header = (offset || limit) ? `Lines ${start + 1}-${start + selected.length} of ${total} total:\n` : '';
+  return header + numbered;
+}
+
+module.exports = { schema, execute };

package/tools/sleep.js

@@ -0,0 +1,22 @@
+'use strict';
+
+const schema = {
+  name: 'sleep',
+  description: 'Wait for a specified duration. Counts against maxDurationSeconds but not maxIterations.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      seconds: { type: 'number', description: 'Number of seconds to wait (max: 300)', minimum: 0.1, maximum: 300 },
+    },
+    required: ['seconds'],
+  },
+  timeout: 305,
+};
+
+async function execute({ seconds }) {
+  const ms = Math.min(seconds, 300) * 1000;
+  await new Promise(r => setTimeout(r, ms));
+  return `Slept for ${seconds}s`;
+}
+
+module.exports = { schema, execute };