@synergenius/flow-weaver-pack-weaver 0.8.3 → 0.9.3

package/src/bot/task-queue.ts

@@ -3,6 +3,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import * as crypto from 'node:crypto';
 import { withFileLock } from './file-lock.js';
+import { parseNdjson } from './safe-json.js';
 
 export interface QueuedTask {
   id: string;
@@ -12,19 +13,67 @@ export interface QueuedTask {
   options?: Record<string, unknown>;
   priority: number;
   addedAt: number;
-  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+  status: 'pending' | 'running' | 'completed' | 'no-op' | 'failed' | 'cancelled';
+  /** Error reason (set on failure) */
+  failureReason?: string;
+}
+
+export interface AddResult {
+  id: string;
+  duplicate: boolean;
+}
+
+/** Max pending tasks before queue rejects new additions. */
+const MAX_PENDING = 200;
+/** Don't re-queue tasks completed within this window (ms). */
+const CYCLE_DEDUP_WINDOW = 3600_000; // 1 hour
+
+/**
+ * Hash a project directory path into a short filesystem-safe string.
+ * Used for per-project queue isolation.
+ */
+function hashDir(dir: string): string {
+  return crypto.createHash('sha256').update(dir).digest('hex').slice(0, 8);
 }
 
 export class TaskQueue {
-  private filePath: string;
+  readonly filePath: string;
 
   constructor(dir?: string) {
-    const base = dir ?? path.join(os.homedir(), '.weaver');
+    // Priority: explicit dir > env var > project-scoped > global fallback
+    const projectDir = process.env.WEAVER_PROJECT_DIR;
+    const base = dir
+      ?? process.env.WEAVER_QUEUE_DIR
+      ?? (projectDir
+        ? path.join(os.homedir(), '.weaver', 'projects', hashDir(projectDir))
+        : path.join(os.homedir(), '.weaver'));
     this.filePath = path.join(base, 'task-queue.ndjson');
   }
 
-  async add(task: Omit<QueuedTask, 'id' | 'addedAt' | 'status'>): Promise<string> {
+  async add(task: Omit<QueuedTask, 'id' | 'addedAt' | 'status'>): Promise<AddResult> {
     return withFileLock(this.filePath, () => {
+      const existing = this.readAll();
+
+      // Dedup: skip if a pending task with the same instruction exists
+      const pendingDup = existing.find(
+        t => t.status === 'pending' && t.instruction === task.instruction,
+      );
+      if (pendingDup) return { id: pendingDup.id, duplicate: true };
+
+      // Cycle-aware dedup: skip if same instruction was completed recently
+      const recentDup = existing.find(
+        t => (t.status === 'completed' || t.status === 'no-op')
+          && t.instruction === task.instruction
+          && Date.now() - t.addedAt < CYCLE_DEDUP_WINDOW,
+      );
+      if (recentDup) return { id: recentDup.id, duplicate: true };
+
+      // Queue size cap
+      const pendingCount = existing.filter(t => t.status === 'pending').length;
+      if (pendingCount >= MAX_PENDING) {
+        throw new Error(`Queue full (${MAX_PENDING} pending tasks). Clear or process existing tasks first.`);
+      }
+
       const entry: QueuedTask = {
         ...task,
         id: crypto.randomUUID().slice(0, 8),
@@ -34,7 +83,7 @@ export class TaskQueue {
       const dir = path.dirname(this.filePath);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       fs.appendFileSync(this.filePath, JSON.stringify(entry) + '\n', 'utf-8');
-      return entry.id;
+      return { id: entry.id, duplicate: false };
     });
   }
 
@@ -77,8 +126,66 @@ export class TaskQueue {
     await this.updateStatus(id, 'completed');
   }
 
-  async markFailed(id: string): Promise<void> {
-    await this.updateStatus(id, 'failed');
+  async markNoOp(id: string): Promise<void> {
+    await this.updateStatus(id, 'no-op');
+  }
+
+  async markFailed(id: string, reason?: string): Promise<void> {
+    return withFileLock(this.filePath, () => {
+      const tasks = this.readAll();
+      const task = tasks.find(t => t.id === id);
+      if (task) {
+        task.status = 'failed';
+        if (reason) task.failureReason = reason.slice(0, 500);
+        this.writeAll(tasks);
+      }
+    });
+  }
+
+  /** Reset a failed or running task back to pending. */
+  async retry(id: string): Promise<boolean> {
+    return withFileLock(this.filePath, () => {
+      const tasks = this.readAll();
+      const task = tasks.find(t => t.id === id && (t.status === 'failed' || t.status === 'running'));
+      if (!task) return false;
+      task.status = 'pending';
+      task.failureReason = undefined;
+      this.writeAll(tasks);
+      return true;
+    });
+  }
+
+  /** Reset ALL failed tasks back to pending. Returns count reset. */
+  async retryAll(): Promise<number> {
+    return withFileLock(this.filePath, () => {
+      const tasks = this.readAll();
+      let count = 0;
+      for (const t of tasks) {
+        if (t.status === 'failed') {
+          t.status = 'pending';
+          t.failureReason = undefined;
+          count++;
+        }
+      }
+      if (count > 0) this.writeAll(tasks);
+      return count;
+    });
+  }
+
+  /** Reset orphaned "running" tasks to pending (crash recovery). */
+  async recoverOrphans(): Promise<number> {
+    return withFileLock(this.filePath, () => {
+      const tasks = this.readAll();
+      let count = 0;
+      for (const t of tasks) {
+        if (t.status === 'running') {
+          t.status = 'pending';
+          count++;
+        }
+      }
+      if (count > 0) this.writeAll(tasks);
+      return count;
+    });
   }
 
   private async updateStatus(id: string, status: QueuedTask['status']): Promise<void> {
@@ -93,14 +200,11 @@ export class TaskQueue {
   }
 
   private readAll(): QueuedTask[] {
-    try {
-      if (!fs.existsSync(this.filePath)) return [];
-      const content = fs.readFileSync(this.filePath, 'utf-8').trim();
-      if (!content) return [];
-      return content.split('\n').map(line => JSON.parse(line) as QueuedTask);
-    } catch {
-      return [];
-    }
+    if (!fs.existsSync(this.filePath)) return [];
+    const content = fs.readFileSync(this.filePath, 'utf-8').trim();
+    if (!content) return [];
+    const { records } = parseNdjson<QueuedTask>(content, 'task-queue');
+    return records;
   }
 
   private writeAll(tasks: QueuedTask[]): void {

package/src/bot/terminal-renderer.ts

@@ -0,0 +1,241 @@
+/**
+ * Terminal renderer — centralizes all weaver CLI output through
+ * a consistent visual grammar. Pipe-safe (stderr only for decoration).
+ *
+ * Icons: ✓ success · ✗ error · ⚠ warning · ◆ action · ● running
+ * Colors: green/red/yellow/cyan/dim/bold — strict assignments
+ */
+
+import type { StreamEvent, ToolEvent } from '@synergenius/flow-weaver/agent';
+
+// ANSI helpers
+const isTTY = process.stderr.isTTY ?? false;
+const c = {
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  redBold: (s: string) => `\x1b[1;31m${s}\x1b[0m`,
+};
+
+export interface RendererOptions {
+  verbose?: boolean;
+  quiet?: boolean;
+  noColor?: boolean;
+  /** Override stderr writer (for testing) */
+  write?: (s: string) => void;
+}
+
+export interface TaskEndStats {
+  toolCalls: number;
+  inputTokens: number;
+  outputTokens: number;
+  estimatedCost: number;
+  filesModified: number;
+  elapsed: number;
+  gitMessage?: string;
+}
+
+export interface SessionEndStats {
+  tasks: number;
+  completed: number;
+  failed: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCost: number;
+  elapsed: number;
+}
+
+export class TerminalRenderer {
+  private verbose: boolean;
+  private quiet: boolean;
+  private out: (s: string) => void;
+  private taskStartTime = 0;
+  private lastToolStartTime = 0;
+  private textBuffer = '';
+  private hasActiveText = false;
+
+  constructor(opts: RendererOptions = {}) {
+    this.verbose = opts.verbose ?? false;
+    this.quiet = opts.quiet ?? false;
+    if (opts.noColor) {
+      // Strip all color functions
+      for (const key of Object.keys(c) as (keyof typeof c)[]) {
+        (c as Record<string, (s: string) => string>)[key] = (s: string) => s;
+      }
+    }
+    this.out = opts.write ?? ((s: string) => process.stderr.write(s));
+  }
+
+  // --- Session lifecycle ---
+
+  sessionStart(info: { provider: string; parallel?: number; deadline?: string }): void {
+    if (this.quiet) return;
+    this.out(`${c.bold('[weaver]')} Session started ${c.dim('(Ctrl+C to stop)')}\n`);
+    const parts = [`Provider: ${info.provider}`];
+    if (info.parallel && info.parallel > 1) parts.push(`Parallel: ${info.parallel}`);
+    if (info.deadline) parts.push(`Deadline: ${info.deadline}`);
+    this.out(`${c.bold('[weaver]')} ${c.dim(parts.join(' · '))}\n`);
+  }
+
+  sessionEnd(stats: SessionEndStats): void {
+    if (this.quiet) return;
+    this.out('\n');
+    const parts: string[] = [];
+    parts.push(`${stats.tasks} task${stats.tasks === 1 ? '' : 's'}`);
+    if (stats.completed > 0) parts.push(c.green(`${stats.completed} completed`));
+    if (stats.failed > 0) parts.push(c.red(`${stats.failed} failed`));
+    const skipped = stats.tasks - stats.completed - stats.failed;
+    if (skipped > 0) parts.push(c.yellow(`${skipped} skipped`));
+    this.out(`${c.bold('[weaver]')} Session complete: ${parts.join(' · ')}\n`);
+
+    const totalTokens = stats.totalInputTokens + stats.totalOutputTokens;
+    if (totalTokens > 0) {
+      this.out(`${c.bold('[weaver]')} ${c.dim(`Total: ${formatTokens(totalTokens)} tokens · $${stats.totalCost.toFixed(3)} · ${formatElapsed(stats.elapsed)}`)}\n`);
+    }
+  }
+
+  // --- Task lifecycle ---
+
+  taskStart(index: number, instruction: string): void {
+    if (this.quiet) return;
+    this.taskStartTime = Date.now();
+    this.hasActiveText = false;
+    this.textBuffer = '';
+    const label = instruction.length > 70 ? instruction.slice(0, 67) + '...' : instruction;
+    this.out(`\n${c.cyan('◆')} ${c.bold(`Task ${index}:`)} ${label}\n`);
+  }
+
+  taskEnd(success: boolean, stats: TaskEndStats): void {
+    if (this.quiet) return;
+    // Flush any remaining text
+    this.flushText();
+
+    const elapsed = formatElapsed(stats.elapsed);
+    const icon = success ? c.green('✓') : c.red('✗');
+    const status = success ? 'completed' : 'failed';
+    this.out(`${icon} Task ${status} ${c.dim(elapsed)}\n`);
+
+    // Summary line
+    const parts: string[] = [];
+    if (stats.toolCalls > 0) parts.push(`${stats.toolCalls} tool calls`);
+    const totalTokens = stats.inputTokens + stats.outputTokens;
+    if (totalTokens > 0) parts.push(`${formatTokens(totalTokens)} tokens`);
+    if (stats.estimatedCost > 0) parts.push(`$${stats.estimatedCost.toFixed(3)}`);
+    if (stats.filesModified > 0) parts.push(`${stats.filesModified} file${stats.filesModified === 1 ? '' : 's'} modified`);
+    if (parts.length > 0) {
+      this.out(`  ${c.dim(parts.join(' · '))}\n`);
+    }
+
+    if (stats.gitMessage) {
+      this.out(`  ${c.dim('→ Git: ' + stats.gitMessage)}\n`);
+    }
+  }
+
+  // --- Stream event handling ---
+
+  onStreamEvent(event: StreamEvent): void {
+    if (this.quiet) return;
+
+    switch (event.type) {
+      case 'thinking_delta':
+        if (this.verbose) {
+          // In verbose mode, stream thinking as dim text
+          this.flushText();
+          this.out(`  ${c.dim(event.text.replace(/\n/g, '\n  '))}`);
+        }
+        // In normal mode, thinking is completely hidden
+        break;
+
+      case 'text_delta':
+        if (this.verbose) {
+          this.flushText();
+          this.out(event.text);
+          this.hasActiveText = true;
+        }
+        // In normal mode, AI text is hidden (tool calls tell the story)
+        break;
+
+      case 'tool_result':
+        // CLI internal tool result — show as result line
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  onToolEvent(event: ToolEvent): void {
+    if (this.quiet) return;
+
+    if (event.type === 'tool_call_start') {
+      this.flushText();
+      this.lastToolStartTime = Date.now();
+      const args = event.args ?? {};
+      const preview = toolPreview(event.name, args);
+      this.out(`  ${c.cyan('◆')} ${event.name}${preview ? c.dim(`(${preview})`) : ''}\n`);
+    }
+
+    if (event.type === 'tool_call_result') {
+      const elapsed = Date.now() - this.lastToolStartTime;
+      const result = (event.result ?? '').replace(/\n/g, ' ').slice(0, 120);
+      const icon = event.isError ? c.red('✗') : c.dim('→');
+      this.out(`  ${icon} ${result} ${c.dim(formatElapsed(elapsed))}\n`);
+    }
+  }
+
+  // --- Direct messages ---
+
+  info(msg: string): void {
+    if (!this.quiet) this.out(`${c.bold('[weaver]')} ${msg}\n`);
+  }
+
+  warn(msg: string): void {
+    if (!this.quiet) this.out(`${c.yellow('⚠')} ${msg}\n`);
+  }
+
+  error(title: string, detail?: string): void {
+    this.out(`${c.redBold('✗')} ${c.red(title)}\n`);
+    if (detail) this.out(`  ${c.red(detail)}\n`);
+  }
+
+  // --- Private ---
+
+  private flushText(): void {
+    if (this.hasActiveText) {
+      this.out('\n');
+      this.hasActiveText = false;
+    }
+  }
+}
+
+// --- Formatting helpers ---
+
+export function formatTokens(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return (n / 1000).toFixed(1).replace(/\.0$/, '') + 'k';
+  return (n / 1_000_000).toFixed(1).replace(/\.0$/, '') + 'M';
+}
+
+export function formatElapsed(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  const m = Math.floor(ms / 60_000);
+  const s = Math.round((ms % 60_000) / 1000);
+  return s > 0 ? `${m}m ${s}s` : `${m}m`;
+}
+
+function toolPreview(name: string, args: Record<string, unknown>): string {
+  if (args.file) return String(args.file).split('/').pop() ?? '';
+  if (args.command) return String(args.command).slice(0, 50);
+  if (args.directory) return String(args.directory).split('/').pop() ?? '';
+  // For patch_file, show file + patch count
+  if (name === 'patch_file' && args.patches) {
+    const file = String(args.file ?? '').split('/').pop() ?? '';
+    const count = Array.isArray(args.patches) ? args.patches.length : '?';
+    return `${file}, ${count} patches`;
+  }
+  return '';
+}

package/src/bot/types.ts

@@ -171,6 +171,12 @@ export interface WorkflowResult {
 
 export type RunOutcome = 'completed' | 'failed' | 'error' | 'skipped';
 
+export interface StepLogEntry {
+  step: string;
+  status: 'ok' | 'blocked' | 'error';
+  detail?: string;
+}
+
 export interface RunRecord {
   id: string;
   workflowFile: string;
@@ -187,6 +193,7 @@ export interface RunRecord {
   provider?: string;
   pipelineName?: string;
   stageName?: string;
+  stepLog?: StepLogEntry[];
 }
 
 export interface RunFilter {
@@ -494,6 +501,7 @@ export interface WeaverContext {
   resultJson?: string;
   validationResultJson?: string;
   filesModified?: string;
+  stepLogJson?: string;
   allValid?: boolean;
   gitResultJson?: string;
 }

package/src/bot/weaver-tools.ts

@@ -0,0 +1,225 @@
+/**
+ * Weaver-specific tool definitions and executor.
+ *
+ * These are the tools the weaver bot uses: validate, read_file, patch_file,
+ * run_shell, list_files, write_file. Tool execution delegates to step-executor
+ * with all safety guards (path traversal, shrink detection, blocked commands).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { executeStep } from './step-executor.js';
+import type { ToolDefinition } from '@synergenius/flow-weaver/agent';
+
+export const WEAVER_TOOLS: ToolDefinition[] = [
+  {
+    name: 'validate',
+    description: 'Run flow-weaver validate on a workflow file. Returns JSON with errors and warnings. Use this FIRST to discover issues, and AFTER patching to confirm fixes.',
+    inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Path to the workflow file to validate' } }, required: ['file'] },
+  },
+  {
+    name: 'read_file',
+    description: 'Read a file and return its full contents. Use this to understand file structure before patching.',
+    inputSchema: { type: 'object', properties: { file: { type: 'string', description: 'Path to the file to read' } }, required: ['file'] },
+  },
+  {
+    name: 'patch_file',
+    description: 'Apply surgical find-and-replace patches to a file. Each patch must have exact "find" and "replace" strings. Preferred over write_file for modifications.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Path to the file to patch' },
+        patches: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              find: { type: 'string', description: 'Exact string to find' },
+              replace: { type: 'string', description: 'String to replace with' },
+            },
+            required: ['find', 'replace'],
+          },
+          description: 'Array of find/replace patches',
+        },
+      },
+      required: ['file', 'patches'],
+    },
+  },
+  {
+    name: 'run_shell',
+    description: 'Execute a shell command and return output. Use for: npx flow-weaver validate, git status, etc. Blocked: rm -rf, git push, sudo.',
+    inputSchema: { type: 'object', properties: { command: { type: 'string', description: 'Shell command to execute' } }, required: ['command'] },
+  },
+  {
+    name: 'list_files',
+    description: 'List files in a directory, optionally filtered by regex pattern.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        directory: { type: 'string', description: 'Directory to list' },
+        pattern: { type: 'string', description: 'Optional regex filter pattern' },
+      },
+      required: ['directory'],
+    },
+  },
+  {
+    name: 'write_file',
+    description: 'Write content to a file (creates or overwrites). Use patch_file instead for modifications to existing files.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        file: { type: 'string', description: 'Path to the file to write' },
+        content: { type: 'string', description: 'Complete file content' },
+      },
+      required: ['file', 'content'],
+    },
+  },
+  {
+    name: 'web_fetch',
+    description: 'Fetch HTTP content. Returns text body (max 10KB).',
+    inputSchema: { type: 'object', properties: { url: { type: 'string' }, method: { type: 'string', enum: ['GET', 'POST'] } }, required: ['url'] },
+  },
+  {
+    name: 'tsc_check',
+    description: 'Run TypeScript compiler check (no emit). Returns errors if any.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'run_tests',
+    description: 'Run project tests. Returns structured results with pass/fail counts.',
+    inputSchema: { type: 'object', properties: { pattern: { type: 'string', description: 'Test file pattern (optional)' } }, required: [] },
+  },
+  {
+    name: 'ask_user',
+    description: 'Ask the user a question and wait for response. Use when you need a decision.',
+    inputSchema: { type: 'object', properties: { question: { type: 'string' } }, required: ['question'] },
+  },
+  {
+    name: 'learn',
+    description: 'Store a fact for future tasks. Key should be descriptive (e.g. "file:src/agent.ts:port-issue").',
+    inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' } }, required: ['key', 'value'] },
+  },
+  {
+    name: 'recall',
+    description: 'Look up stored knowledge. Returns matching entries.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+  },
+];
+
+/** Map tool names to step-executor operations. */
+const OPERATION_MAP: Record<string, string> = {
+  validate: 'run-shell',
+  read_file: 'read-file',
+  patch_file: 'patch-file',
+  run_shell: 'run-shell',
+  list_files: 'list-files',
+  write_file: 'write-file',
+};
+
+/**
+ * Execute a weaver tool call. Delegates to step-executor with safety guards.
+ * Bound to a specific project directory via closure.
+ */
+export function createWeaverExecutor(projectDir: string) {
+  return async (
+    name: string,
+    args: Record<string, unknown>,
+  ): Promise<{ result: string; isError: boolean }> => {
+    // Handle new tools that bypass step-executor
+    switch (name) {
+      case 'web_fetch': {
+        const url = String(args.url);
+        // Safety: block localhost, internal IPs
+        if (/localhost|127\.0\.0\.1|0\.0\.0\.0|10\.\d|172\.(1[6-9]|2\d|3[01])\.|192\.168\./i.test(url)) {
+          return { result: 'Blocked: cannot fetch internal/localhost URLs.', isError: true };
+        }
+        const resp = await fetch(url, { method: (args.method as string) ?? 'GET', signal: AbortSignal.timeout(15_000) });
+        const text = await resp.text();
+        return { result: text.slice(0, 10_000), isError: !resp.ok };
+      }
+
+      case 'tsc_check': {
+        try {
+          const output = execFileSync('npx', ['tsc', '--noEmit', '--pretty'], { cwd: projectDir, encoding: 'utf-8', timeout: 60_000, stdio: ['pipe', 'pipe', 'pipe'] });
+          return { result: output.trim() || 'No TypeScript errors.', isError: false };
+        } catch (err: any) {
+          return { result: (err.stdout ?? err.message ?? '').slice(0, 5000), isError: true };
+        }
+      }
+
+      case 'run_tests': {
+        try {
+          const pattern = args.pattern ? String(args.pattern) : '';
+          const testArgs = ['vitest', 'run', '--reporter', 'json'];
+          if (pattern) testArgs.push(pattern);
+          const output = execFileSync('npx', testArgs, { cwd: projectDir, encoding: 'utf-8', timeout: 120_000, stdio: ['pipe', 'pipe', 'pipe'] });
+          try {
+            const json = JSON.parse(output);
+            const passed = json.numPassedTests ?? 0;
+            const failed = json.numFailedTests ?? 0;
+            const failures = (json.testResults ?? []).filter((t: any) => t.status === 'failed').map((t: any) => t.name).slice(0, 10);
+            return { result: JSON.stringify({ passed, failed, total: passed + failed, failures }), isError: failed > 0 };
+          } catch {
+            return { result: output.slice(0, 5000), isError: false };
+          }
+        } catch (err: any) {
+          return { result: (err.stdout ?? err.stderr ?? err.message ?? '').slice(0, 5000), isError: true };
+        }
+      }
+
+      case 'ask_user': {
+        const question = String(args.question);
+        if (process.env.WEAVER_AUTO_APPROVE) {
+          return { result: '(Auto-approved — no user input available in autonomous mode)', isError: false };
+        }
+        // In interactive mode, prompt via readline
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+        const answer = await new Promise<string>((resolve) => {
+          rl.question(`\n  Bot asks: ${question}\n  > `, (ans) => { rl.close(); resolve(ans); });
+        });
+        return { result: answer || '(no answer)', isError: false };
+      }
+
+      case 'learn': {
+        const { KnowledgeStore } = await import('./knowledge-store.js');
+        const store = new KnowledgeStore(projectDir);
+        store.learn(String(args.key), String(args.value), 'bot');
+        return { result: `Learned: ${args.key}`, isError: false };
+      }
+
+      case 'recall': {
+        const { KnowledgeStore } = await import('./knowledge-store.js');
+        const store = new KnowledgeStore(projectDir);
+        const entries = store.recall(String(args.query));
+        if (entries.length === 0) return { result: 'No knowledge found.', isError: false };
+        return { result: entries.map(e => `${e.key}: ${e.value}`).join('\n'), isError: false };
+      }
+
+      default:
+        break;
+    }
+
+    // Existing step-executor-based tools
+    const operation = OPERATION_MAP[name];
+    if (!operation) {
+      return { result: `Unknown tool: ${name}`, isError: true };
+    }
+
+    // Transform validate tool to run-shell with flow-weaver validate command
+    let stepArgs = { ...args };
+    if (name === 'validate') {
+      stepArgs = { command: `npx flow-weaver validate ${args.file} --json` };
+    }
+
+    try {
+      const result = await executeStep({ operation, args: stepArgs }, projectDir);
+      if (result.blocked) {
+        return { result: result.blockReason ?? 'Blocked by safety guard', isError: true };
+      }
+      return { result: result.output ?? 'Done', isError: false };
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { result: msg, isError: true };
+    }
+  };
+}