@yeaft/webchat-agent 0.1.442 → 0.1.443

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.442",
+  "version": "0.1.443",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/tools/agent.js

@@ -0,0 +1,89 @@
+/**
+ * agent.js — Create a sub-agent for parallel task execution.
+ *
+ * Sub-agents run in isolated contexts and can be assigned
+ * independent tasks. They communicate via send-message/wait-agent.
+ */
+
+import { defineTool } from './types.js';
+import { randomUUID } from 'crypto';
+
+/** In-memory sub-agent registry. */
+const agents = new Map();
+
+/** Get the global agents map for other tools to access. */
+export function getAgentRegistry() {
+  return agents;
+}
+
+export default defineTool({
+  name: 'Agent',
+  description: `Create a sub-agent to work on an independent task in parallel.
+
+Sub-agents run in their own context and can be given specific tasks.
+Use for parallel execution of independent subtasks.
+
+Guidelines:
+- Give each agent a clear, focused task description
+- Use unique, descriptive names
+- Sub-agents share the same tools but have independent conversations
+- Use SendMessage to communicate with agents, WaitAgent to collect results
+- Close agents with CloseAgent when done`,
+  parameters: {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'A descriptive name for the sub-agent (e.g. "test-writer", "refactor-auth")',
+      },
+      task: {
+        type: 'string',
+        description: 'The task description for the sub-agent',
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory for the sub-agent (optional, defaults to parent cwd)',
+      },
+    },
+    required: ['name', 'task'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input, ctx) {
+    const { name, task, cwd } = input;
+    if (!name) return JSON.stringify({ error: 'name is required' });
+    if (!task) return JSON.stringify({ error: 'task is required' });
+
+    // Check for name collision
+    for (const [, agent] of agents) {
+      if (agent.name === name && agent.status !== 'closed') {
+        return JSON.stringify({
+          error: `Agent "${name}" already exists. Close it first or use a different name.`,
+          agentId: agent.id,
+        });
+      }
+    }
+
+    const agentId = `agent-${randomUUID().slice(0, 8)}`;
+    const agent = {
+      id: agentId,
+      name,
+      task,
+      cwd: cwd || ctx?.cwd || process.cwd(),
+      status: 'created',
+      messages: [],
+      result: null,
+      createdAt: Date.now(),
+    };
+
+    agents.set(agentId, agent);
+
+    return JSON.stringify({
+      success: true,
+      agentId,
+      name,
+      message: `Sub-agent "${name}" created (${agentId}). Use SendMessage to give it work.`,
+    });
+  },
+});

package/unify/tools/apply-patch.js

@@ -0,0 +1,176 @@
+/**
+ * apply-patch.js — Apply a unified diff patch to files.
+ *
+ * Parses unified diff format and applies changes to the target files.
+ * Supports multiple files in a single patch.
+ */
+
+import { defineTool } from './types.js';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+/**
+ * Parse a unified diff into hunks.
+ * @param {string} patch
+ * @returns {Array<{ file: string, hunks: Array }>}
+ */
+function parsePatch(patch) {
+  const files = [];
+  const lines = patch.split('\n');
+  let currentFile = null;
+  let currentHunk = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // File header: --- a/path or +++ b/path
+    if (line.startsWith('--- ')) {
+      // Next line should be +++
+      continue;
+    }
+    if (line.startsWith('+++ ')) {
+      let filePath = line.slice(4).trim();
+      // Strip a/ or b/ prefix
+      if (filePath.startsWith('b/')) filePath = filePath.slice(2);
+      if (filePath === '/dev/null') continue;
+
+      currentFile = { file: filePath, hunks: [] };
+      files.push(currentFile);
+      continue;
+    }
+
+    // Hunk header: @@ -start,count +start,count @@
+    const hunkMatch = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/);
+    if (hunkMatch) {
+      if (!currentFile) continue;
+      currentHunk = {
+        oldStart: parseInt(hunkMatch[1], 10),
+        oldCount: hunkMatch[2] ? parseInt(hunkMatch[2], 10) : 1,
+        newStart: parseInt(hunkMatch[3], 10),
+        newCount: hunkMatch[4] ? parseInt(hunkMatch[4], 10) : 1,
+        lines: [],
+      };
+      currentFile.hunks.push(currentHunk);
+      continue;
+    }
+
+    // Diff content lines
+    if (currentHunk && (line.startsWith('+') || line.startsWith('-') || line.startsWith(' ') || line === '')) {
+      currentHunk.lines.push(line);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Apply hunks to file content.
+ */
+function applyHunks(content, hunks) {
+  const lines = content.split('\n');
+  let offset = 0; // tracks line number shifts from previous hunks
+
+  for (const hunk of hunks) {
+    const startLine = hunk.oldStart - 1 + offset; // 0-based
+    const newLines = [];
+    let removedCount = 0;
+
+    for (const diffLine of hunk.lines) {
+      if (diffLine.startsWith('+')) {
+        newLines.push(diffLine.slice(1));
+      } else if (diffLine.startsWith('-')) {
+        removedCount++;
+      } else if (diffLine.startsWith(' ') || diffLine === '') {
+        newLines.push(diffLine.startsWith(' ') ? diffLine.slice(1) : diffLine);
+      }
+    }
+
+    // Replace the old lines with new lines
+    lines.splice(startLine, removedCount + (hunk.oldCount - removedCount > 0 ? hunk.oldCount - removedCount : 0), ...newLines);
+    offset += newLines.length - hunk.oldCount;
+  }
+
+  return lines.join('\n');
+}
+
+export default defineTool({
+  name: 'ApplyPatch',
+  description: `Apply a unified diff patch to files.
+
+Parses unified diff format (like git diff output) and applies changes.
+Supports patching multiple files in a single diff.
+
+Guidelines:
+- Provide standard unified diff format (--- a/file, +++ b/file, @@ hunks)
+- Ensure the diff matches the current file content exactly
+- New files are created automatically with parent directories`,
+  parameters: {
+    type: 'object',
+    properties: {
+      patch: {
+        type: 'string',
+        description: 'The unified diff patch content',
+      },
+    },
+    required: ['patch'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  isDestructive: () => false,
+  async execute(input, ctx) {
+    const { patch } = input;
+    if (!patch) return JSON.stringify({ error: 'patch is required' });
+
+    const cwd = ctx?.cwd || process.cwd();
+
+    try {
+      const fileDiffs = parsePatch(patch);
+
+      if (fileDiffs.length === 0) {
+        return JSON.stringify({ error: 'No valid file diffs found in patch' });
+      }
+
+      const results = [];
+
+      for (const fileDiff of fileDiffs) {
+        const absPath = resolve(cwd, fileDiff.file);
+
+        try {
+          let content;
+          if (existsSync(absPath)) {
+            content = await readFile(absPath, 'utf-8');
+          } else {
+            // New file
+            await mkdir(dirname(absPath), { recursive: true });
+            content = '';
+          }
+
+          const newContent = applyHunks(content, fileDiff.hunks);
+          await writeFile(absPath, newContent, 'utf-8');
+
+          results.push({
+            file: fileDiff.file,
+            success: true,
+            hunks: fileDiff.hunks.length,
+          });
+        } catch (err) {
+          results.push({
+            file: fileDiff.file,
+            success: false,
+            error: err.message,
+          });
+        }
+      }
+
+      const successCount = results.filter(r => r.success).length;
+      return JSON.stringify({
+        results,
+        summary: `Applied patch to ${successCount}/${results.length} files`,
+      }, null, 2);
+    } catch (err) {
+      return JSON.stringify({ error: `Failed to apply patch: ${err.message}` });
+    }
+  },
+});

package/unify/tools/ask-user.js

@@ -0,0 +1,62 @@
+/**
+ * ask-user.js — Ask the user a question and wait for their response.
+ *
+ * In Unify mode this tool sends a question through the web-bridge
+ * and blocks (via Promise) until the user answers. The answer is
+ * returned as the tool result.
+ *
+ * Reference: yeaft-unify-design.md §8
+ */
+
+import { defineTool } from './types.js';
+import { randomUUID } from 'crypto';
+
+export default defineTool({
+  name: 'AskUser',
+  description: `Ask the user a question and wait for their response.
+
+Use this tool when you need additional information or clarification from the user.
+The user will see your question in the chat interface and can type a response.
+
+Guidelines:
+- Ask specific, focused questions
+- Provide context about why you need the information
+- If presenting options, list them clearly
+- Don't use this for rhetorical questions — only when you genuinely need user input`,
+  parameters: {
+    type: 'object',
+    properties: {
+      question: {
+        type: 'string',
+        description: 'The question to ask the user',
+      },
+      options: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Optional list of choices for the user to pick from',
+      },
+    },
+    required: ['question'],
+  },
+  modes: ['chat', 'work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const { question, options } = input;
+    if (!question) return JSON.stringify({ error: 'question is required' });
+
+    // Generate a unique request ID for this ask
+    const requestId = `ask_${randomUUID().slice(0, 8)}`;
+
+    // In a full web-bridge integration, this would send an ask_user event
+    // and await the answer. For now, return a formatted prompt that the
+    // LLM can see — the web-bridge handles the ask flow externally.
+    return JSON.stringify({
+      type: 'ask_user',
+      requestId,
+      question,
+      ...(options ? { options } : {}),
+      message: `Question sent to user: "${question}"${options ? ` [Options: ${options.join(', ')}]` : ''}`,
+    });
+  },
+});

package/unify/tools/bash.js

@@ -0,0 +1,189 @@
+/**
+ * bash.js — Execute shell commands.
+ *
+ * Spawns a child process to run shell commands with timeout, output
+ * truncation, working directory support, and cancellation via AbortSignal.
+ *
+ * Modeled after Claude Code's Bash tool implementation.
+ */
+
+import { defineTool } from './types.js';
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+/** Max output size in bytes before truncation (256 KB). */
+const MAX_OUTPUT = 256 * 1024;
+
+/** Default timeout in ms (2 minutes). */
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/** Max timeout in ms (10 minutes). */
+const MAX_TIMEOUT_MS = 600_000;
+
+/**
+ * Run a command in a child process.
+ * @returns {Promise<{ stdout: string, stderr: string, exitCode: number, timedOut: boolean }>}
+ */
+function runCommand(command, { cwd, timeout, signal }) {
+  return new Promise((resolve, reject) => {
+    const shell = process.env.SHELL || '/bin/bash';
+    const proc = spawn(shell, ['-c', command], {
+      cwd,
+      env: { ...process.env, TERM: 'dumb', FORCE_COLOR: '0' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout,
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let timedOut = false;
+
+    proc.stdout.on('data', (chunk) => {
+      if (stdout.length < MAX_OUTPUT) {
+        stdout += chunk.toString();
+        if (stdout.length > MAX_OUTPUT) {
+          stdout = stdout.slice(0, MAX_OUTPUT);
+          stdoutTruncated = true;
+        }
+      }
+    });
+
+    proc.stderr.on('data', (chunk) => {
+      if (stderr.length < MAX_OUTPUT) {
+        stderr += chunk.toString();
+        if (stderr.length > MAX_OUTPUT) {
+          stderr = stderr.slice(0, MAX_OUTPUT);
+          stderrTruncated = true;
+        }
+      }
+    });
+
+    // Handle abort signal
+    const onAbort = () => {
+      try { proc.kill('SIGTERM'); } catch {}
+      setTimeout(() => {
+        try { proc.kill('SIGKILL'); } catch {}
+      }, 2000);
+    };
+    if (signal) {
+      if (signal.aborted) { onAbort(); return; }
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    proc.on('close', (code) => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve({
+        stdout: stdoutTruncated ? stdout + '\n... (output truncated)' : stdout,
+        stderr: stderrTruncated ? stderr + '\n... (stderr truncated)' : stderr,
+        exitCode: code ?? 1,
+        timedOut,
+      });
+    });
+
+    proc.on('error', (err) => {
+      if (signal) signal.removeEventListener('abort', onAbort);
+      if (err.code === 'ETIMEDOUT' || err.killed) {
+        timedOut = true;
+        resolve({
+          stdout,
+          stderr: stderr + `\nProcess timed out after ${timeout}ms`,
+          exitCode: 124,
+          timedOut: true,
+        });
+      } else {
+        resolve({
+          stdout,
+          stderr: `Error spawning process: ${err.message}`,
+          exitCode: 1,
+          timedOut: false,
+        });
+      }
+    });
+  });
+}
+
+export default defineTool({
+  name: 'Bash',
+  description: `Execute a shell command and return its output.
+
+Use this tool to run CLI commands, scripts, and system operations.
+
+Guidelines:
+- Commands run in the working directory (cwd from context)
+- Timeout defaults to 2 minutes (max 10 minutes)
+- Large outputs are truncated at 256KB
+- Use absolute paths when possible
+- Avoid interactive commands (no stdin support)
+- For long-running tasks, consider redirecting output to a file
+- stderr is captured separately and included in the result`,
+  parameters: {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string',
+        description: 'The shell command to execute',
+      },
+      cwd: {
+        type: 'string',
+        description: 'Working directory for the command (default: engine cwd)',
+      },
+      timeout_ms: {
+        type: 'number',
+        description: `Timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS})`,
+      },
+    },
+    required: ['command'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  isDestructive: (input) => {
+    if (!input?.command) return false;
+    const cmd = input.command.toLowerCase();
+    return cmd.includes('rm ') || cmd.includes('rmdir') ||
+           cmd.includes('git reset --hard') || cmd.includes('git clean') ||
+           cmd.includes('dd ') || cmd.includes('mkfs') ||
+           cmd.includes('> /dev/') || cmd.includes('chmod 000');
+  },
+  async execute(input, ctx) {
+    const { command, cwd: inputCwd, timeout_ms } = input;
+    if (!command) return JSON.stringify({ error: 'command is required' });
+
+    // Resolve working directory
+    const cwd = inputCwd
+      ? resolve(inputCwd)
+      : (ctx?.cwd || process.cwd());
+
+    if (!existsSync(cwd)) {
+      return JSON.stringify({ error: `Working directory does not exist: ${cwd}` });
+    }
+
+    // Clamp timeout
+    const timeout = Math.min(Math.max(timeout_ms || DEFAULT_TIMEOUT_MS, 1000), MAX_TIMEOUT_MS);
+
+    try {
+      const result = await runCommand(command, {
+        cwd,
+        timeout,
+        signal: ctx?.signal,
+      });
+
+      // Format output similar to Claude Code
+      const parts = [];
+      if (result.stdout) parts.push(result.stdout);
+      if (result.stderr) parts.push(`STDERR:\n${result.stderr}`);
+      if (result.timedOut) parts.push(`\n(Command timed out after ${timeout}ms)`);
+
+      const output = parts.join('\n') || '(no output)';
+
+      return result.exitCode === 0
+        ? output
+        : `Exit code: ${result.exitCode}\n${output}`;
+    } catch (err) {
+      return JSON.stringify({ error: `Bash execution failed: ${err.message}` });
+    }
+  },
+});

package/unify/tools/close-agent.js

@@ -0,0 +1,58 @@
+/**
+ * close-agent.js — Close a sub-agent and clean up.
+ */
+
+import { defineTool } from './types.js';
+import { getAgentRegistry } from './agent.js';
+
+export default defineTool({
+  name: 'CloseAgent',
+  description: `Close a sub-agent and release its resources.
+
+Use when a sub-agent's task is complete or no longer needed.
+The agent's result (if any) is returned before closing.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      agent_id: {
+        type: 'string',
+        description: 'The sub-agent ID to close',
+      },
+      result: {
+        type: 'string',
+        description: 'Optional final result to set before closing',
+      },
+    },
+    required: ['agent_id'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  async execute(input, ctx) {
+    const { agent_id, result } = input;
+    if (!agent_id) return JSON.stringify({ error: 'agent_id is required' });
+
+    const agents = getAgentRegistry();
+    const agent = agents.get(agent_id);
+
+    if (!agent) {
+      return JSON.stringify({ error: `Agent not found: ${agent_id}` });
+    }
+
+    if (result) {
+      agent.result = result;
+    }
+
+    const finalResult = agent.result;
+    agent.status = 'closed';
+
+    return JSON.stringify({
+      success: true,
+      agentId: agent_id,
+      name: agent.name,
+      result: finalResult,
+      messages: agent.messages.length,
+      message: `Agent "${agent.name}" closed`,
+    });
+  },
+});

package/unify/tools/file-edit.js

@@ -0,0 +1,120 @@
+/**
+ * file-edit.js — Surgical string-replacement edits to files.
+ *
+ * Performs exact string matching and replacement within files,
+ * similar to Claude Code's Edit tool. Supports replace_all for
+ * bulk replacements across the file.
+ */
+
+import { defineTool } from './types.js';
+import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+export default defineTool({
+  name: 'FileEdit',
+  description: `Make surgical text replacements in an existing file.
+
+Replaces exact occurrences of old_string with new_string.
+The old_string must be unique in the file unless replace_all is true.
+
+Guidelines:
+- old_string must match EXACTLY (including whitespace and indentation)
+- The edit fails if old_string is not found or is not unique
+- Use replace_all: true to replace ALL occurrences
+- For creating new files or full rewrites, use FileWrite instead
+- Always read the file first to understand its current content`,
+  parameters: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'Path to the file to edit (absolute or relative to cwd)',
+      },
+      old_string: {
+        type: 'string',
+        description: 'The exact text to find and replace',
+      },
+      new_string: {
+        type: 'string',
+        description: 'The replacement text',
+      },
+      replace_all: {
+        type: 'boolean',
+        description: 'Replace all occurrences (default: false — fails if not unique)',
+      },
+    },
+    required: ['file_path', 'old_string', 'new_string'],
+  },
+  modes: ['work'],
+  isConcurrencySafe: () => false,
+  isReadOnly: () => false,
+  isDestructive: () => false,
+  async execute(input, ctx) {
+    const { file_path, old_string, new_string, replace_all = false } = input;
+    if (!file_path) return JSON.stringify({ error: 'file_path is required' });
+    if (old_string === undefined) return JSON.stringify({ error: 'old_string is required' });
+    if (new_string === undefined) return JSON.stringify({ error: 'new_string is required' });
+    if (old_string === new_string) return JSON.stringify({ error: 'old_string and new_string are identical' });
+
+    const cwd = ctx?.cwd || process.cwd();
+    const absPath = resolve(cwd, file_path);
+
+    if (!existsSync(absPath)) {
+      return JSON.stringify({ error: `File not found: ${absPath}` });
+    }
+
+    try {
+      const content = await readFile(absPath, 'utf-8');
+
+      // Count occurrences
+      let count = 0;
+      let idx = 0;
+      while (true) {
+        idx = content.indexOf(old_string, idx);
+        if (idx === -1) break;
+        count++;
+        idx += old_string.length;
+      }
+
+      if (count === 0) {
+        // Provide context for debugging
+        const preview = old_string.length > 100
+          ? old_string.slice(0, 100) + '...'
+          : old_string;
+        return JSON.stringify({
+          error: `old_string not found in file`,
+          hint: `The exact text "${preview}" was not found in ${absPath}. Check whitespace and indentation.`,
+        });
+      }
+
+      if (count > 1 && !replace_all) {
+        return JSON.stringify({
+          error: `old_string found ${count} times — not unique. Use replace_all: true to replace all occurrences, or provide more context to make it unique.`,
+          occurrences: count,
+        });
+      }
+
+      // Perform replacement
+      let newContent;
+      if (replace_all) {
+        newContent = content.split(old_string).join(new_string);
+      } else {
+        // Replace only the first occurrence (which is guaranteed unique)
+        const replaceIdx = content.indexOf(old_string);
+        newContent = content.slice(0, replaceIdx) + new_string + content.slice(replaceIdx + old_string.length);
+      }
+
+      await writeFile(absPath, newContent, 'utf-8');
+
+      return JSON.stringify({
+        success: true,
+        path: absPath,
+        replacements: replace_all ? count : 1,
+        message: `Replaced ${replace_all ? count : 1} occurrence(s) in ${absPath}`,
+      });
+    } catch (err) {
+      return JSON.stringify({ error: `Failed to edit file: ${err.message}` });
+    }
+  },
+});