@synergenius/flow-weaver-pack-weaver 0.8.1

package/src/docs/weaver-config.md

@@ -0,0 +1,135 @@
+# Weaver Bot Configuration Reference
+
+The weaver bot runs workflows, executes tasks from natural language, and evolves autonomously. It auto-detects AI providers, manages approval gates, handles git operations, and sends notifications.
+
+The bot has deep knowledge of the full flow-weaver ecosystem: annotation grammar, CLI tools, node patterns, error diagnosis, and the genesis protocol (loaded dynamically from `@synergenius/flow-weaver/doc-metadata`).
+
+## Getting started
+
+Run the bot directly via CLI:
+
+```bash
+flow-weaver weaver bot "Create a workflow that processes CSV files"
+flow-weaver weaver run my-workflow.ts
+flow-weaver weaver session
+```
+
+Or scaffold a project via `flow-weaver init` and select the "AI Workflow Runner" use case.
+
+## .weaver.json
+
+Place a `.weaver.json` in your project root to configure the weaver workflow:
+
+```json
+{
+  "provider": "auto",
+  "target": "scripts/my-pipeline.ts",
+  "notify": [
+    { "channel": "discord", "url": "https://discord.com/api/webhooks/ID/TOKEN" }
+  ]
+}
+```
+
+## Provider options
+
+**Auto-detect** (tries each in order):
+```json
+{ "provider": "auto" }
+```
+
+**Anthropic API** (best quality, requires API key):
+```json
+{ "provider": "anthropic" }
+```
+
+**Claude CLI** (uses your CLI subscription, no API key needed):
+```json
+{ "provider": "claude-cli" }
+```
+
+**GitHub Copilot CLI** (uses your Copilot subscription):
+```json
+{ "provider": "copilot-cli" }
+```
+
+## Workflow nodes
+
+The weaver workflow has 6 nodes, visible and editable in Studio:
+
+1. **Load Config** - Reads `.weaver.json`, falls back to `{ provider: 'auto' }`
+2. **Detect Provider** - Auto-detects installed CLIs and API keys
+3. **Resolve Target** - Finds the workflow to run (from config or by scanning)
+4. **Execute Target** - Runs the target with an AI agent channel
+5. **Notify Result** - Sends Discord/Slack/webhook notifications
+6. **Report** - Prints summary to console
+
+You can customize any node, add pre/post-processing steps, or insert approval gates in Studio.
+
+## Full .weaver.json reference
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `provider` | string or object | `"auto"` | AI provider (see options above) |
+| `target` | string | auto-scan | Path to target workflow file |
+| `approval` | `"auto"` / `"timeout-auto"` / object | `"auto"` | Approval gate behavior |
+| `notify` | array | `[]` | Webhook notification channels |
+
+### Provider (verbose form)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | `"anthropic"` / `"claude-cli"` / `"copilot-cli"` | required | Provider name |
+| `model` | string | `"claude-sonnet-4-6"` | Model to use (Anthropic only) |
+| `maxTokens` | number | `4096` | Max response tokens (Anthropic only) |
+
+Shorthand values:
+
+- `"anthropic"` requires `ANTHROPIC_API_KEY` env var and `@anthropic-ai/sdk` package
+- `"claude-cli"` uses the Claude Code CLI (`claude -p`), requires Claude CLI installed
+- `"copilot-cli"` uses GitHub Copilot CLI (`copilot -p`), requires Copilot CLI installed
+- `"auto"` auto-detects in order: `ANTHROPIC_API_KEY` > `claude` CLI > `copilot` CLI
+
+### Approval
+
+How approval gates are handled.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mode` | `"auto"` / `"timeout-auto"` | `"auto"` | `auto`: approve immediately. `timeout-auto`: wait, then approve |
+| `timeoutSeconds` | number | `300` | Seconds to wait before auto-approving (timeout-auto only) |
+
+### Notifications
+
+Webhook notifications. Array of notification targets. Supports Discord, Slack, and custom webhooks.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `channel` | `"discord"` / `"slack"` / `"webhook"` | required | Notification target |
+| `url` | string | required | Webhook URL |
+| `events` | array | all events | Event types to send: `workflow-start`, `workflow-complete`, `error` |
+| `headers` | object | `{}` | Extra HTTP headers (custom webhooks only) |
+
+Discord notifications use rich embeds with color-coded outcomes. Slack uses Block Kit formatting.
+
+## Programmatic usage
+
+The pack also exports library functions for building custom runners:
+
+```typescript
+import {
+  createProvider,
+  detectProvider,
+  runWorkflow,
+  BotAgentChannel,
+} from '@synergenius/flow-weaver-pack-weaver';
+
+// Auto-detect and run
+const result = await runWorkflow('path/to/workflow.ts', { verbose: true });
+
+// Or build a custom agent channel
+const providerConfig = detectProvider();
+const provider = createProvider(providerConfig);
+const channel = new BotAgentChannel(provider, { ... });
+```
+
+Scheduling is left to the user: cron, GitHub Actions, git hooks, etc.

package/src/index.ts

@@ -0,0 +1,177 @@
+// Types
+export type {
+  BotConfig,
+  BotProviderConfig,
+  BotApprovalConfig,
+  BotNotifyConfig,
+  NotificationEvent,
+  NotificationEventType,
+  ExecutionEvent,
+  ExecutionEventType,
+  ApprovalMode,
+  WeaverConfig,
+  WeaverEnv,
+  ProviderInfo,
+  WorkflowResult,
+  ProviderName,
+  RunRecord,
+  RunFilter,
+  RetentionPolicy,
+  RunOutcome,
+  TokenUsage,
+  OnUsageCallback,
+  RunCostEntry,
+  RunCostSummary,
+  CostRecord,
+  CostSummary,
+  BotAgentProvider,
+  ProviderMetadata,
+  ProviderFactory,
+  ProviderFactoryConfig,
+  ProviderModule,
+  CronExpression,
+  ParsedCron,
+  CronField,
+  TriggerSource,
+  WatchDaemonOptions,
+  WatchDaemonState,
+  StageCondition,
+  StageStatus,
+  PipelineStage,
+  PipelineConfig,
+  StageResult,
+  PipelineResult,
+  DashboardEventType,
+  DashboardNodeStatus,
+  DashboardEvent,
+  DashboardNodeState,
+  DashboardServerOptions,
+} from './bot/types.js';
+
+// Providers
+export type { BotChannelContext } from './bot/index.js';
+export {
+  AnthropicAgentProvider,
+  CliAgentProvider,
+  resolveProviderConfig,
+  createProvider,
+  detectProvider,
+} from './bot/index.js';
+
+// Provider registry
+export { ProviderRegistry, defaultRegistry, loadExternalProvider, discoverProviders } from './bot/index.js';
+
+// Agent channel & notifications
+export { BotAgentChannel } from './bot/index.js';
+export {
+  WebhookNotificationChannel,
+  createNotifier,
+} from './bot/index.js';
+export type { NotificationChannel, NotificationErrorHandler } from './bot/index.js';
+
+// Approvals
+export { createApprovalHandler } from './bot/index.js';
+export type { ApprovalHandler, ApprovalResult } from './bot/index.js';
+
+// System prompt
+export { buildSystemPrompt } from './bot/index.js';
+
+// Runner
+export { runWorkflow } from './bot/index.js';
+
+// History & Cost
+export { RunStore } from './bot/index.js';
+export { CostTracker, MODEL_PRICING } from './bot/index.js';
+export { CostStore } from './bot/index.js';
+
+// Watch/Cron
+export { parseCron, cronMatches, cronNextMatch } from './bot/index.js';
+export { FileWatcher } from './bot/index.js';
+export { CronScheduler } from './bot/index.js';
+export { WatchDaemon } from './bot/index.js';
+
+// Pipelines
+export { PipelineRunner } from './bot/index.js';
+export type { PipelineRunOptions } from './bot/index.js';
+
+// Dashboard
+export { DashboardServer } from './bot/index.js';
+export { openBrowser } from './bot/index.js';
+
+// Web Approval
+export { WebApprovalHandler } from './bot/index.js';
+
+// Bot infrastructure
+export {
+  SteeringController,
+  TaskQueue,
+  SessionStore,
+  buildBotSystemPrompt,
+} from './bot/index.js';
+export type {
+  SteeringCommand,
+  QueuedTask,
+  SessionState,
+  BotTask,
+  BotPlan,
+  BotPlanStep,
+  BotValidationResult,
+  BotExecutionResult,
+  BotNotificationEventType,
+  ToolDefinition,
+  ToolUseResult,
+  StreamChunk,
+  GenesisImpactLevel,
+  GenesisOperationType,
+  GenesisConfig,
+  GenesisOperation,
+  GenesisProposal,
+  GenesisFingerprint,
+  GenesisCycleRecord,
+  GenesisHistory,
+} from './bot/index.js';
+
+// Genesis store
+export { GenesisStore } from './bot/index.js';
+
+// Node types (for use in flow-weaver workflows)
+export {
+  weaverLoadConfig,
+  weaverDetectProvider,
+  weaverResolveTarget,
+  weaverExecuteTarget,
+  weaverSendNotify,
+  weaverReport,
+  weaverReceiveTask,
+  weaverRouteTask,
+  weaverReadWorkflow,
+  weaverBuildContext,
+  weaverPlanTask,
+  weaverApprovalGate,
+  weaverAbortTask,
+  weaverExecValidateRetry,
+  weaverExecutePlan,
+  weaverValidateResult,
+  weaverFixErrors,
+  weaverGitOps,
+  weaverBotReport,
+  genesisLoadConfig,
+  genesisObserve,
+  genesisDiffFingerprint,
+  genesisCheckStabilize,
+  genesisPropose,
+  genesisValidateProposal,
+  genesisSnapshot,
+  genesisApply,
+  genesisCompileValidate,
+  genesisDiffWorkflow,
+  genesisCheckThreshold,
+  genesisApprove,
+  genesisCommit,
+  genesisUpdateHistory,
+  genesisReport,
+} from './node-types/index.js';
+
+// Eject API (for platform/studio server-side use)
+export { ejectWorkflows } from './cli-handlers.js';
+export type { EjectResult } from './cli-handlers.js';

package/src/mcp-tools.ts

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+import { fileURLToPath } from 'node:url';
+import { runWorkflow } from './bot/runner.js';
+import { RunStore } from './bot/run-store.js';
+import { CostStore } from './bot/cost-store.js';
+import { defaultRegistry, discoverProviders } from './bot/provider-registry.js';
+
+// McpServer type from the SDK, kept loose to avoid hard dependency
+type McpServer = {
+  tool(
+    name: string,
+    description: string,
+    schema: Record<string, unknown>,
+    handler: (args: { [key: string]: unknown }) => Promise<{ content: Array<{ type: string; text: string }> }>,
+  ): void;
+};
+
+export async function registerMcpTools(mcp: McpServer): Promise<void> {
+  mcp.tool(
+    'fw_weaver_run',
+    'Execute a Flow Weaver workflow with the AI runner. Returns the result summary, outcome, and cost.',
+    {
+      file: z.string().describe('Path to the workflow file'),
+      params: z.record(z.unknown()).optional().describe('Input parameters as key-value pairs'),
+      verbose: z.boolean().optional().describe('Show detailed execution info'),
+      dryRun: z.boolean().optional().describe('Preview without executing'),
+    },
+    async (args) => {
+      const result = await runWorkflow(args.file as string, {
+        params: args.params as Record<string, unknown> | undefined,
+        verbose: args.verbose as boolean | undefined,
+        dryRun: args.dryRun as boolean | undefined,
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_history',
+    'Query weaver run history. Returns recent workflow executions with outcome, duration, and summary.',
+    {
+      id: z.string().optional().describe('Specific run ID to look up'),
+      limit: z.number().optional().describe('Max number of entries (default 20)'),
+      outcome: z.enum(['completed', 'failed', 'error', 'skipped']).optional().describe('Filter by outcome'),
+      workflowFile: z.string().optional().describe('Filter by workflow file path'),
+    },
+    async (args) => {
+      const store = new RunStore();
+
+      if (args.id) {
+        const record = store.get(args.id as string);
+        if (!record) {
+          return { content: [{ type: 'text', text: `No run found matching "${args.id}"` }] };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(record, null, 2) }] };
+      }
+
+      const records = store.list({
+        outcome: args.outcome as 'completed' | 'failed' | 'error' | 'skipped' | undefined,
+        workflowFile: args.workflowFile as string | undefined,
+        limit: (args.limit as number | undefined) ?? 20,
+      });
+
+      if (records.length === 0) {
+        return { content: [{ type: 'text', text: 'No runs recorded yet.' }] };
+      }
+
+      return { content: [{ type: 'text', text: JSON.stringify(records, null, 2) }] };
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_costs',
+    'Get AI cost summary across weaver runs. Shows total tokens, estimated cost, and breakdown by model.',
+    {
+      since: z.string().optional().describe('Filter: duration like "7d", "30d", or ISO-8601 date'),
+      model: z.string().optional().describe('Filter by model name'),
+    },
+    async (args) => {
+      const store = new CostStore();
+      let sinceTs: number | undefined;
+
+      if (args.since) {
+        const spec = args.since as string;
+        const match = spec.match(/^(\d+)([dhm])$/);
+        if (match) {
+          const n = parseInt(match[1]!, 10);
+          const unit = match[2];
+          const ms = unit === 'd' ? n * 86_400_000 : unit === 'h' ? n * 3_600_000 : n * 60_000;
+          sinceTs = Date.now() - ms;
+        } else {
+          const ts = new Date(spec).getTime();
+          if (!isNaN(ts)) sinceTs = ts;
+        }
+      }
+
+      const summary = store.summarize({ since: sinceTs, model: args.model as string | undefined });
+      return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }] };
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_providers',
+    'List available AI providers for weaver workflow execution.',
+    {},
+    async () => {
+      await discoverProviders(defaultRegistry);
+      const providers = defaultRegistry.list();
+
+      const result = providers.map(({ name, metadata }) => ({
+        name,
+        source: metadata.source,
+        description: metadata.description,
+        requiredEnvVars: metadata.requiredEnvVars,
+        envVarsSet: metadata.requiredEnvVars?.every((v) => process.env[v]) ?? false,
+        detectCliCommand: metadata.detectCliCommand,
+      }));
+
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+  );
+
+  // --- Bot Tools ---
+
+  mcp.tool(
+    'fw_weaver_bot',
+    'Run the autonomous bot to create or modify a Flow Weaver workflow. Provide a natural language task description.',
+    {
+      task: z.string().describe('Natural language task description'),
+      projectDir: z.string().optional().describe('Project directory'),
+      mode: z.enum(['create', 'modify', 'read', 'batch']).optional().describe('Task mode'),
+      targets: z.array(z.string()).optional().describe('Target files for modify/read'),
+      template: z.string().optional().describe('Template to use for scaffolding'),
+      dryRun: z.boolean().optional().describe('Preview without executing'),
+      autoApprove: z.boolean().optional().describe('Skip approval gate'),
+    },
+    async (args) => {
+      const task = {
+        instruction: args.task as string,
+        mode: (args.mode as string) ?? 'create',
+        targets: args.targets as string[] | undefined,
+        options: {
+          template: args.template as string | undefined,
+          dryRun: args.dryRun as boolean | undefined,
+          autoApprove: (args.autoApprove as boolean | undefined) ?? true,
+        },
+      };
+
+      const packRoot = new URL('..', import.meta.url);
+      let workflowPath: string;
+      try {
+        const { existsSync } = await import('node:fs');
+        workflowPath = fileURLToPath(new URL('src/workflows/weaver-bot.ts', packRoot));
+        if (!existsSync(workflowPath)) {
+          workflowPath = fileURLToPath(new URL('dist/workflows/weaver-bot.js', packRoot));
+        }
+      } catch {
+        workflowPath = fileURLToPath(new URL('dist/workflows/weaver-bot.js', packRoot));
+      }
+
+      const result = await runWorkflow(
+        workflowPath,
+        {
+          params: { taskJson: JSON.stringify(task), projectDir: (args.projectDir as string) ?? process.cwd() },
+          dryRun: args.dryRun as boolean | undefined,
+        },
+      );
+
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_steer',
+    'Send a steering command to a running bot (pause, resume, cancel, redirect, queue).',
+    {
+      command: z.enum(['pause', 'resume', 'cancel', 'redirect', 'queue']).describe('Steering command'),
+      payload: z.string().optional().describe('Payload for redirect/queue commands'),
+    },
+    async (args) => {
+      const { SteeringController } = await import('./bot/steering.js');
+      const controller = new SteeringController();
+      await controller.write({
+        command: args.command as 'pause' | 'resume' | 'cancel' | 'redirect' | 'queue',
+        payload: args.payload as string | undefined,
+        timestamp: Date.now(),
+      });
+      return { content: [{ type: 'text', text: `Steering command sent: ${args.command}` }] };
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_queue',
+    'Manage the bot task queue (add, list, clear, remove tasks).',
+    {
+      action: z.enum(['add', 'list', 'clear', 'remove']).describe('Queue action'),
+      task: z.string().optional().describe('Task instruction (for add)'),
+      id: z.string().optional().describe('Task ID (for remove)'),
+    },
+    async (args) => {
+      const { TaskQueue } = await import('./bot/task-queue.js');
+      const queue = new TaskQueue();
+
+      switch (args.action) {
+        case 'add': {
+          if (!args.task) return { content: [{ type: 'text', text: 'Error: task instruction required' }] };
+          const id = await queue.add({ instruction: args.task as string, priority: 0 });
+          return { content: [{ type: 'text', text: `Task added: ${id}` }] };
+        }
+        case 'list':
+          return { content: [{ type: 'text', text: JSON.stringify(await queue.list(), null, 2) }] };
+        case 'clear': {
+          const count = await queue.clear();
+          return { content: [{ type: 'text', text: `Cleared ${count} task(s)` }] };
+        }
+        case 'remove': {
+          if (!args.id) return { content: [{ type: 'text', text: 'Error: task ID required' }] };
+          const removed = await queue.remove(args.id as string);
+          return { content: [{ type: 'text', text: removed ? `Removed ${args.id}` : `Not found: ${args.id}` }] };
+        }
+        default:
+          return { content: [{ type: 'text', text: `Unknown action: ${args.action}` }] };
+      }
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_status',
+    'Get current bot session status (idle/planning/executing/etc), current task, completed count.',
+    {},
+    async () => {
+      const { SessionStore } = await import('./bot/session-state.js');
+      const store = new SessionStore();
+      const state = store.load();
+
+      if (!state) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'no active session' }, null, 2) }] };
+      }
+
+      return { content: [{ type: 'text', text: JSON.stringify(state, null, 2) }] };
+    },
+  );
+
+  mcp.tool(
+    'fw_weaver_genesis',
+    'Run a single Genesis self-evolution cycle on a target workflow. Genesis observes the project, proposes changes within a budget, validates, and commits or rolls back.',
+    {
+      projectDir: z.string().optional().describe('Project directory (defaults to cwd)'),
+      dryRun: z.boolean().optional().describe('Preview without executing'),
+    },
+    async (args) => {
+      const packRoot = new URL('..', import.meta.url);
+      let workflowPath: string;
+      try {
+        const { existsSync } = await import('node:fs');
+        workflowPath = fileURLToPath(new URL('src/workflows/genesis-task.ts', packRoot));
+        if (!existsSync(workflowPath)) {
+          workflowPath = fileURLToPath(new URL('dist/workflows/genesis-task.js', packRoot));
+        }
+      } catch {
+        workflowPath = fileURLToPath(new URL('dist/workflows/genesis-task.js', packRoot));
+      }
+
+      const result = await runWorkflow(workflowPath, {
+        params: { projectDir: (args.projectDir as string) ?? process.cwd() },
+        dryRun: args.dryRun as boolean | undefined,
+      });
+
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    },
+  );
+}

package/src/node-types/abort-task.ts

@@ -0,0 +1,31 @@
+import type { WeaverContext } from '../bot/types.js';
+
+/**
+ * Handles the rejection path from the approval gate.
+ * Formats the rejection reason into a result compatible with the report node.
+ *
+ * @flowWeaver nodeType
+ * @expression
+ * @label Abort Task
+ * @input ctx [order:0] - Weaver context (JSON)
+ * @output ctx [order:0] - Weaver context with abort resultJson (JSON)
+ * @output onFailure [hidden]
+ */
+export function weaverAbortTask(ctx: string): { ctx: string } {
+  const context = JSON.parse(ctx) as WeaverContext;
+  const task = JSON.parse(context.taskJson!) as { instruction?: string };
+  const result = {
+    success: false,
+    outcome: 'aborted',
+    summary: `Task aborted: ${context.rejectionReason}`,
+    instruction: task.instruction,
+    filesModified: [],
+    filesCreated: [],
+  };
+
+  console.log(`\x1b[33m→ Task aborted: ${context.rejectionReason}\x1b[0m`);
+
+  context.resultJson = JSON.stringify(result);
+  context.filesModified = '[]';
+  return { ctx: JSON.stringify(context) };
+}