@yeaft/webchat-agent 0.1.408 → 0.1.410

package/unify/tools/exit-worktree.js

@@ -0,0 +1,131 @@
+/**
+ * exit-worktree.js — Remove or keep a git worktree
+ *
+ * Exits and optionally removes a worktree created by EnterWorktree.
+ * Can keep the worktree (preserve branch) or remove it cleanly.
+ *
+ * Reference: yeaft-unify-design.md §8
+ */
+
+import { defineTool } from './types.js';
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+export default defineTool({
+  name: 'ExitWorktree',
+  description: `Exit a git worktree session.
+
+Options:
+- "keep": Leave the worktree and branch on disk (can return later)
+- "remove": Delete the worktree directory and its branch
+
+If removing and there are uncommitted changes, the operation will fail
+unless discard_changes is set to true.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      path: {
+        type: 'string',
+        description: 'Path to the worktree to exit (required)',
+      },
+      action: {
+        type: 'string',
+        enum: ['keep', 'remove'],
+        description: '"keep" leaves the worktree on disk; "remove" deletes it',
+      },
+      discard_changes: {
+        type: 'boolean',
+        description: 'Force remove even with uncommitted changes (default: false)',
+      },
+    },
+    required: ['path', 'action'],
+  },
+  modes: ['work'],
+  isDestructive: (input) => input?.action === 'remove',
+  async execute(input, ctx) {
+    const worktreePath = resolve(input.path);
+    const mainCwd = ctx?.cwd || process.cwd();
+
+    if (!existsSync(worktreePath)) {
+      return JSON.stringify({
+        error: `Worktree path does not exist: ${worktreePath}`,
+      });
+    }
+
+    if (input.action === 'keep') {
+      return JSON.stringify({
+        success: true,
+        action: 'keep',
+        path: worktreePath,
+        message: `Worktree at ${worktreePath} kept on disk. Branch preserved.`,
+      });
+    }
+
+    // action === 'remove'
+    try {
+      // Check for uncommitted changes
+      if (!input.discard_changes) {
+        try {
+          const status = execSync('git status --porcelain', {
+            cwd: worktreePath,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+          }).trim();
+
+          if (status) {
+            return JSON.stringify({
+              error: 'Worktree has uncommitted changes. Set discard_changes=true to force remove.',
+              uncommittedFiles: status.split('\n').slice(0, 10),
+            });
+          }
+        } catch {
+          // If we can't check status, proceed with caution
+        }
+      }
+
+      // Get branch name before removal
+      let branchName = null;
+      try {
+        branchName = execSync('git rev-parse --abbrev-ref HEAD', {
+          cwd: worktreePath,
+          encoding: 'utf8',
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+      } catch {
+        // ignore
+      }
+
+      // Remove worktree
+      const forceFlag = input.discard_changes ? ' --force' : '';
+      execSync(`git worktree remove "${worktreePath}"${forceFlag}`, {
+        cwd: mainCwd,
+        stdio: 'pipe',
+      });
+
+      // Remove the branch if it was a yeaft worktree branch
+      if (branchName && branchName.startsWith('yeaft-wt/')) {
+        try {
+          execSync(`git branch -D "${branchName}"`, {
+            cwd: mainCwd,
+            stdio: 'pipe',
+          });
+        } catch {
+          // Branch might already be deleted or not exist
+        }
+      }
+
+      return JSON.stringify({
+        success: true,
+        action: 'remove',
+        path: worktreePath,
+        branch: branchName,
+        message: `Worktree removed: ${worktreePath}${branchName ? `, branch ${branchName} deleted` : ''}`,
+      });
+    } catch (err) {
+      return JSON.stringify({
+        error: `Failed to remove worktree: ${err.message}`,
+      });
+    }
+  },
+});

package/unify/tools/mcp-tools.js

@@ -0,0 +1,133 @@
+/**
+ * mcp-tools.js — MCP (Model Context Protocol) tool bridge
+ *
+ * Provides two tools for interacting with MCP servers:
+ * - mcp_list_tools: Discover available MCP tools from connected servers
+ * - mcp_call_tool: Invoke an MCP tool by name with arguments
+ *
+ * These are exported as an array (unlike other tool files that export a single tool).
+ *
+ * Reference: yeaft-unify-design.md §8
+ */
+
+import { defineTool } from './types.js';
+
+export const mcpListTools = defineTool({
+  name: 'mcp_list_tools',
+  description: `List all tools available from connected MCP (Model Context Protocol) servers.
+
+Usage guidelines:
+- Use to discover what MCP tools are available in the current session
+- Returns tool names, descriptions, and parameter schemas from all connected MCP servers
+- Each tool is prefixed with the server name (e.g. "github__list_prs", "slack__send_message")
+- Use this before mcp_call_tool to understand available capabilities
+- MCP servers are configured by the user — if none are connected, returns an empty list`,
+  parameters: {
+    type: 'object',
+    properties: {
+      server: {
+        type: 'string',
+        description: 'Filter tools from a specific MCP server (optional)',
+      },
+    },
+  },
+  modes: ['chat', 'work'],
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const mcpManager = ctx?.mcpManager;
+
+    if (!mcpManager || !mcpManager.hasServers) {
+      return JSON.stringify({
+        tools: [],
+        message: 'No MCP servers are connected. Configure MCP servers in ~/.yeaft/config.md',
+      });
+    }
+
+    const tools = mcpManager.listTools(input.server || undefined);
+
+    return JSON.stringify({
+      tools: tools.map(t => ({
+        name: t.name,
+        server: t.server,
+        description: t.description,
+        inputSchema: t.inputSchema,
+      })),
+      totalCount: tools.length,
+      servers: mcpManager.status(),
+    }, null, 2);
+  },
+});
+
+export const mcpCallTool = defineTool({
+  name: 'mcp_call_tool',
+  description: `Call a tool on a connected MCP (Model Context Protocol) server.
+
+Usage guidelines:
+- Use after discovering tools via mcp_list_tools
+- Provide the full tool name including server prefix (e.g. "github__create_issue")
+- Arguments must match the tool's parameter schema exactly
+- The tool executes on the MCP server and returns the result
+- Timeouts depend on the MCP server — use timeout_ms if the operation is slow
+- Errors from the MCP server are returned as structured error objects`,
+  parameters: {
+    type: 'object',
+    properties: {
+      tool_name: {
+        type: 'string',
+        description: 'Full tool name including server prefix (e.g. "github__list_prs")',
+      },
+      arguments: {
+        type: 'object',
+        description: 'Arguments to pass to the MCP tool (must match its schema)',
+      },
+      timeout_ms: {
+        type: 'number',
+        description: 'Timeout in milliseconds (default: 30000)',
+      },
+    },
+    required: ['tool_name'],
+  },
+  modes: ['chat', 'work'],
+  async execute(input, ctx) {
+    const mcpManager = ctx?.mcpManager;
+
+    if (!mcpManager || !mcpManager.hasServers) {
+      return JSON.stringify({
+        error: 'No MCP servers are connected. Configure MCP servers in ~/.yeaft/config.md',
+      });
+    }
+
+    const { tool_name, arguments: args = {}, timeout_ms } = input;
+
+    if (!tool_name) {
+      return JSON.stringify({ error: 'tool_name is required' });
+    }
+
+    try {
+      const result = await mcpManager.callTool(tool_name, args, timeout_ms || 30000);
+
+      // Format MCP result
+      if (result?.content) {
+        // MCP standard response format
+        const textParts = result.content
+          .filter(c => c.type === 'text')
+          .map(c => c.text);
+        if (textParts.length > 0) {
+          return textParts.join('\n');
+        }
+      }
+
+      return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+
+    } catch (err) {
+      return JSON.stringify({
+        error: err.message,
+        tool: tool_name,
+      });
+    }
+  },
+});
+
+// Default export as array for compatibility with bulk registration
+export default [mcpListTools, mcpCallTool];

package/unify/tools/registry.js

@@ -0,0 +1,146 @@
+/**
+ * registry.js — Tool registration center for Yeaft Unify
+ *
+ * Manages tool registration, mode-based filtering, and execution dispatch.
+ * The engine uses this to get tool definitions for the LLM and to execute tool calls.
+ */
+
+/**
+ * Mode normalization map.
+ * 'coordinator' and 'worker' inherit 'work' tools.
+ * 'dream' has no tools by design (returns empty).
+ */
+const MODE_ALIASES = {
+  coordinator: 'work',
+  worker: 'work',
+};
+
+export class ToolRegistry {
+  /** @type {Map<string, import('./types.js').ToolDef>} */
+  #tools = new Map();
+
+  /**
+   * Register a single tool.
+   * @param {import('./types.js').ToolDef} tool
+   * @returns {ToolRegistry}
+   */
+  register(tool) {
+    if (!tool || !tool.name) throw new Error('Tool must have a name');
+    this.#tools.set(tool.name, tool);
+    return this;
+  }
+
+  /**
+   * Register multiple tools.
+   * @param {import('./types.js').ToolDef[]} tools
+   * @returns {ToolRegistry}
+   */
+  registerAll(tools) {
+    for (const tool of tools) this.register(tool);
+    return this;
+  }
+
+  /**
+   * Unregister a tool by name.
+   * @param {string} name
+   * @returns {ToolRegistry}
+   */
+  unregister(name) {
+    this.#tools.delete(name);
+    return this;
+  }
+
+  /**
+   * Get a tool by name.
+   * @param {string} name
+   * @returns {import('./types.js').ToolDef | null}
+   */
+  get(name) {
+    return this.#tools.get(name) || null;
+  }
+
+  /**
+   * Check if a tool is registered.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this.#tools.has(name);
+  }
+
+  /**
+   * Resolve a mode to its effective tool mode.
+   * @param {string} mode
+   * @returns {string}
+   */
+  static resolveMode(mode) {
+    return MODE_ALIASES[mode] || mode;
+  }
+
+  /**
+   * Get all tools available in a given mode.
+   * @param {string} mode
+   * @returns {import('./types.js').ToolDef[]}
+   */
+  getToolsForMode(mode) {
+    const effectiveMode = ToolRegistry.resolveMode(mode);
+    const result = [];
+    for (const [, tool] of this.#tools) {
+      if (tool.modes.includes(effectiveMode)) result.push(tool);
+    }
+    return result;
+  }
+
+  /**
+   * Get tool definitions for the LLM adapter.
+   * @param {string} mode
+   * @returns {{ name: string, description: string, parameters: object }[]}
+   */
+  getToolDefs(mode) {
+    return this.getToolsForMode(mode).map(t => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    }));
+  }
+
+  /**
+   * Get tool names available in a given mode.
+   * @param {string} mode
+   * @returns {string[]}
+   */
+  getToolNames(mode) {
+    return this.getToolsForMode(mode).map(t => t.name);
+  }
+
+  /**
+   * Execute a tool by name.
+   * @param {string} name
+   * @param {object} input
+   * @param {import('./types.js').ToolContext} [ctx={}]
+   * @returns {Promise<string>}
+   */
+  async execute(name, input, ctx = {}) {
+    const tool = this.#tools.get(name);
+    if (!tool) throw new Error(`Unknown tool: ${name}`);
+    return tool.execute(input, ctx);
+  }
+
+  /** Number of registered tools. */
+  get size() {
+    return this.#tools.size;
+  }
+
+  /** All registered tool names. */
+  get names() {
+    return Array.from(this.#tools.keys());
+  }
+}
+
+/**
+ * Create an empty registry.
+ * @returns {ToolRegistry}
+ */
+export function createEmptyRegistry() {
+  return new ToolRegistry();
+}

package/unify/tools/skill.js

@@ -0,0 +1,107 @@
+/**
+ * skill.js — Skill invocation tool
+ *
+ * Allows the LLM to load and activate skills from the skill library.
+ * Skills are specialized behaviors defined in ~/.yeaft/skills/*.md.
+ *
+ * Reference: yeaft-unify-design.md §8
+ */
+
+import { defineTool } from './types.js';
+
+export default defineTool({
+  name: 'Skill',
+  description: `Load and activate a skill from the Yeaft skill library.
+
+Skills are specialized behaviors or workflows defined in ~/.yeaft/skills/.
+Use this tool to:
+- List available skills
+- Load a specific skill's instructions
+- Find relevant skills for the current context
+
+Skills provide domain-specific guidance and workflows that enhance your capabilities.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['list', 'load', 'search'],
+        description: '"list" lists all skills, "load" loads a specific skill, "search" finds relevant skills',
+      },
+      name: {
+        type: 'string',
+        description: 'Skill name (for "load" action)',
+      },
+      query: {
+        type: 'string',
+        description: 'Search query (for "search" action)',
+      },
+    },
+    required: ['action'],
+  },
+  modes: ['chat', 'work'],
+  isConcurrencySafe: () => true,
+  isReadOnly: () => true,
+  async execute(input, ctx) {
+    const skillManager = ctx?.skillManager;
+
+    if (!skillManager) {
+      return JSON.stringify({
+        error: 'Skill system not initialized. Skills directory: ~/.yeaft/skills/',
+      });
+    }
+
+    switch (input.action) {
+      case 'list': {
+        const skills = skillManager.list();
+        if (skills.length === 0) {
+          return JSON.stringify({
+            skills: [],
+            message: 'No skills found. Add .md files to ~/.yeaft/skills/ to create skills.',
+          });
+        }
+        return JSON.stringify({
+          skills: skills.map(s => ({
+            name: s.name,
+            description: s.description || '',
+            trigger: s.trigger || '',
+            mode: s.mode || 'both',
+          })),
+          totalCount: skills.length,
+        }, null, 2);
+      }
+
+      case 'load': {
+        if (!input.name) {
+          return JSON.stringify({ error: 'Skill name is required for "load" action' });
+        }
+        const content = skillManager.getPromptContent(input.name);
+        if (!content) {
+          return JSON.stringify({
+            error: `Skill "${input.name}" not found`,
+            available: skillManager.list().map(s => s.name),
+          });
+        }
+        return content;
+      }
+
+      case 'search': {
+        if (!input.query) {
+          return JSON.stringify({ error: 'Query is required for "search" action' });
+        }
+        const results = skillManager.findRelevant(input.query);
+        return JSON.stringify({
+          results: results.map(s => ({
+            name: s.name,
+            description: s.description || '',
+            trigger: s.trigger || '',
+          })),
+          totalResults: results.length,
+        }, null, 2);
+      }
+
+      default:
+        return JSON.stringify({ error: `Unknown action: ${input.action}. Use "list", "load", or "search".` });
+    }
+  },
+});

package/unify/tools/types.js

@@ -0,0 +1,71 @@
+/**
+ * types.js — Tool definition interface for Yeaft Unify
+ *
+ * All tools use the defineTool() function to create tool definitions.
+ * This ensures consistent shape and API-format conversion.
+ *
+ * Reference: yeaft-unify-core-systems.md §3.1
+ */
+
+/**
+ * @typedef {Object} ToolContext
+ * @property {AbortSignal} [signal] — cancellation signal
+ * @property {string} [yeaftDir] — Yeaft data directory
+ * @property {string} [cwd] — working directory
+ * @property {import('../mcp.js').MCPManager} [mcpManager] — MCP manager
+ * @property {object} [skillManager] — Skill manager
+ * @property {object} [trace] — debug trace
+ * @property {object} [config] — engine config
+ */
+
+/**
+ * @typedef {Object} ToolDef
+ * @property {string} name — unique tool name (e.g. 'Bash', 'FileRead')
+ * @property {string} description — LLM-facing description
+ * @property {object} parameters — JSON Schema for input
+ * @property {(input: object, ctx?: ToolContext) => Promise<string>} execute — execution function
+ * @property {string[]} modes — which modes can use this tool: ['chat', 'work']
+ * @property {(input?: object) => boolean} [isConcurrencySafe] — can run in parallel?
+ * @property {(input?: object) => boolean} [isReadOnly] — read-only operation?
+ * @property {(input?: object) => boolean} [isDestructive] — destructive operation?
+ */
+
+/**
+ * Define a tool with consistent defaults.
+ *
+ * @param {{
+ *   name: string,
+ *   description: string,
+ *   parameters: object,
+ *   execute: (input: object, ctx?: ToolContext) => Promise<string>,
+ *   modes?: string[],
+ *   isConcurrencySafe?: (input?: object) => boolean,
+ *   isReadOnly?: (input?: object) => boolean,
+ *   isDestructive?: (input?: object) => boolean,
+ * }} def
+ * @returns {ToolDef}
+ */
+export function defineTool({
+  name,
+  description,
+  parameters,
+  execute,
+  modes = ['chat', 'work'],
+  isConcurrencySafe = () => false,
+  isReadOnly = () => false,
+  isDestructive = () => false,
+}) {
+  if (!name) throw new Error('Tool must have a name');
+  if (!execute) throw new Error(`Tool "${name}" must have an execute function`);
+
+  return {
+    name,
+    description: description || `Tool: ${name}`,
+    parameters: parameters || { type: 'object', properties: {} },
+    execute,
+    modes,
+    isConcurrencySafe,
+    isReadOnly,
+    isDestructive,
+  };
+}