@synergenius/flow-weaver-pack-weaver 0.9.62 → 0.9.78

package/src/bot/orchestrator.ts

@@ -0,0 +1,244 @@
+/**
+ * Orchestrator — the routing brain that decides which tasks go to which bot instances.
+ *
+ * Pure routing logic: no side-effects beyond decision logging.
+ * Fast-path cascade: exact-match → single-eligible → ai-routed → round-robin.
+ */
+
+import type {
+  BotInstance,
+  BotProfile,
+  OrchestratorDecision,
+  OrchestratorInput,
+  OrchestratorOutput,
+} from './profile-types.js';
+
+type Task = OrchestratorInput['pendingTasks'][number];
+type Assignment = OrchestratorOutput['assignments'][number];
+type ScaleAction = OrchestratorOutput['scaleActions'][number];
+
+// ---------------------------------------------------------------------------
+// AI Router types
+// ---------------------------------------------------------------------------
+
+export interface AIRouterResult {
+  profileId: string;
+  reason: string;
+  confidence: number;
+}
+
+export interface AIRouter {
+  route(task: OrchestratorInput['pendingTasks'][0], candidates: BotProfile[]): Promise<AIRouterResult>;
+}
+
+export interface OrchestratorOptions {
+  aiRouter?: AIRouter;
+}
+
+export class Orchestrator {
+  private _decisionLog: OrchestratorDecision[] = [];
+  private _nextDecisionId = 1;
+  private _aiRouter?: AIRouter;
+
+  constructor(options?: OrchestratorOptions) {
+    this._aiRouter = options?.aiRouter;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  async route(input: OrchestratorInput): Promise<OrchestratorOutput> {
+    const assignments: Assignment[] = [];
+    const scaleActions: ScaleAction[] = [];
+    const skippedTasks: OrchestratorOutput['skippedTasks'] = [];
+
+    // Track instances claimed during this routing cycle to avoid double-assignment.
+    const claimedInstanceIds = new Set<string>();
+
+    // Sort tasks by priority DESC (higher number = higher priority).
+    const sorted = [...input.pendingTasks].sort((a, b) => b.priority - a.priority);
+
+    for (const task of sorted) {
+      // Budget guard
+      if (input.budgetRemaining.tokens <= 0 || input.budgetRemaining.cost <= 0) {
+        skippedTasks.push({ taskId: task.id, reason: 'budget-exhausted' });
+        continue;
+      }
+
+      const eligible = this._findEligible(task, input.profiles);
+
+      if (eligible.length === 0) {
+        skippedTasks.push({ taskId: task.id, reason: 'no-eligible-profile' });
+        continue;
+      }
+
+      const result = await this._selectInstance(task, eligible, input.instances, claimedInstanceIds);
+
+      if (result) {
+        claimedInstanceIds.add(result.instanceId);
+        assignments.push({
+          taskId: task.id,
+          profileId: result.profileId,
+          instanceId: result.instanceId,
+          reason: result.reason,
+          method: result.method,
+          confidence: result.confidence,
+        });
+        this._recordDecision(task, result, eligible);
+      } else {
+        // No idle instance available — request scale-up if possible.
+        const scaleProfile = eligible[0];
+        const currentCount = input.instances.filter(
+          (i) => i.profileId === scaleProfile.id,
+        ).length;
+
+        if (currentCount < scaleProfile.maxInstances) {
+          // Only add one scale-up action per profile.
+          if (!scaleActions.some((sa) => sa.profileId === scaleProfile.id)) {
+            scaleActions.push({
+              profileId: scaleProfile.id,
+              action: 'scale-up',
+              targetInstances: currentCount + 1,
+              reason: `idle instances exhausted for profile ${scaleProfile.id}`,
+            });
+          }
+        }
+
+        skippedTasks.push({ taskId: task.id, reason: 'no-idle-instance' });
+      }
+    }
+
+    return { assignments, scaleActions, skippedTasks };
+  }
+
+  getDecisionLog(limit?: number): OrchestratorDecision[] {
+    if (limit === undefined) return [...this._decisionLog];
+    return this._decisionLog.slice(-limit);
+  }
+
+  clearDecisionLog(): void {
+    this._decisionLog = [];
+    this._nextDecisionId = 1;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  /** Find profiles eligible for a task. */
+  private _findEligible(task: Task, profiles: BotProfile[]): BotProfile[] {
+    if (task.assignedProfile) {
+      const match = profiles.filter(p => p.id === task.assignedProfile);
+      if (match.length > 0) return match;
+    }
+    return profiles;
+  }
+
+  /** Select the best instance for a task from eligible profiles. */
+  private async _selectInstance(
+    task: Task,
+    eligible: BotProfile[],
+    instances: BotInstance[],
+    claimed: Set<string>,
+  ): Promise<{ profileId: string; instanceId: string; method: OrchestratorDecision['method']; reason: string; confidence?: number } | null> {
+    // Determine routing method
+    let method = this._routingMethod(task, eligible);
+
+    if (eligible.length === 1) {
+      const profile = eligible[0];
+      const idle = instances.find(
+        (i) => i.profileId === profile.id && i.status === 'idle' && !claimed.has(i.instanceId),
+      );
+      if (!idle) return null;
+      return {
+        profileId: profile.id,
+        instanceId: idle.instanceId,
+        method,
+        reason: `${method}: ${profile.id}`,
+      };
+    }
+
+    // AI routing: when multiple eligible profiles and AI router is provided
+    if (this._aiRouter && eligible.length > 1) {
+      try {
+        const aiResult = await this._aiRouter.route(task, eligible);
+        const aiProfile = eligible.find((p) => p.id === aiResult.profileId);
+        if (aiProfile) {
+          const idle = instances.find(
+            (i) => i.profileId === aiProfile.id && i.status === 'idle' && !claimed.has(i.instanceId),
+          );
+          if (idle) {
+            return {
+              profileId: aiProfile.id,
+              instanceId: idle.instanceId,
+              method: 'ai-routed',
+              reason: `ai-routed: ${aiProfile.id} — ${aiResult.reason}`,
+              confidence: aiResult.confidence,
+            };
+          }
+          // AI chose a profile but no idle instance — fall through to round-robin
+        }
+        // AI returned unknown profile — fall through to round-robin
+      } catch {
+        // AI call failed — fall through to round-robin
+      }
+    }
+
+    // Round-robin: pick profile with most idle instances
+    method = 'round-robin';
+    let bestProfile: BotProfile | null = null;
+    let bestIdleCount = -1;
+    let bestInstance: BotInstance | null = null;
+
+    for (const profile of eligible) {
+      const idleInstances = instances.filter(
+        (i) => i.profileId === profile.id && i.status === 'idle' && !claimed.has(i.instanceId),
+      );
+      if (idleInstances.length > bestIdleCount) {
+        bestIdleCount = idleInstances.length;
+        bestProfile = profile;
+        bestInstance = idleInstances[0] ?? null;
+      }
+    }
+
+    if (!bestProfile || !bestInstance) return null;
+
+    return {
+      profileId: bestProfile.id,
+      instanceId: bestInstance.instanceId,
+      method,
+      reason: `${method}: ${bestProfile.id}`,
+    };
+  }
+
+  /** Determine which routing method was used. */
+  private _routingMethod(
+    task: Task,
+    eligible: BotProfile[],
+  ): OrchestratorDecision['method'] {
+    if (task.assignedProfile) return 'exact-match';
+    if (eligible.length === 1) return 'single-eligible';
+    return 'round-robin';
+  }
+
+  /** Record a decision in the log. */
+  private _recordDecision(
+    task: Task,
+    result: { profileId: string; instanceId: string; method: OrchestratorDecision['method']; reason: string; confidence?: number },
+    eligible: BotProfile[],
+  ): void {
+    this._decisionLog.push({
+      id: this._nextDecisionId++,
+      timestamp: Date.now(),
+      taskId: task.id,
+      taskTitle: task.title,
+      assignedProfileId: result.profileId,
+      assignedInstanceId: result.instanceId,
+      reason: result.reason,
+      method: result.method,
+      candidateProfiles: eligible.map((p) => p.id),
+      confidence: result.confidence,
+    });
+  }
+}

package/src/bot/profile-store.ts

@@ -0,0 +1,225 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import type { BotProfile, CreateProfileInput, Capability } from './profile-types.js';
+
+// ---------------------------------------------------------------------------
+// Default profiles — enterprise-ready starting kit
+// ---------------------------------------------------------------------------
+
+const DEFAULT_PROFILES: Record<string, Array<Omit<CreateProfileInput, 'botId'>>> = {
+  'weaver-bot': [
+    {
+      name: 'Developer',
+      description: 'Builds features, fixes bugs, writes tests. The everyday workhorse.',
+      icon: 'code',
+      color: 'color-node-blue-icon',
+      capabilities: [
+        { name: 'feature-development', description: 'Build new features end-to-end from specs or tickets' },
+        { name: 'bug-fixing', description: 'Diagnose and fix bugs from error reports or failing tests' },
+        { name: 'testing', description: 'Write and maintain unit, integration, and e2e tests' },
+        { name: 'refactoring', description: 'Improve code structure without changing behavior' },
+      ],
+      preferences: { costStrategy: 'balanced', requireApproval: false },
+    },
+    {
+      name: 'Reviewer',
+      description: 'Reviews code, validates architecture, writes documentation. Quality gate.',
+      icon: 'verified',
+      color: 'color-node-green-icon',
+      capabilities: [
+        { name: 'code-review', description: 'Review code for correctness, security, and maintainability' },
+        { name: 'architecture-review', description: 'Validate system design and architectural decisions' },
+        { name: 'documentation', description: 'Write technical docs, ADRs, and changelogs' },
+      ],
+      preferences: { costStrategy: 'performance', requireApproval: true, instructions: 'Be thorough. Prioritize correctness and security over speed.' },
+    },
+    {
+      name: 'Ops',
+      description: 'Handles deployments, CI/CD, monitoring, and infrastructure.',
+      icon: 'rocketLaunch',
+      color: 'color-node-orange-icon',
+      capabilities: [
+        { name: 'deployment', description: 'Deploy services, manage releases, run migrations' },
+        { name: 'ci-cd', description: 'Configure and maintain CI/CD pipelines' },
+        { name: 'monitoring', description: 'Set up alerts, dashboards, and health checks' },
+      ],
+      preferences: { costStrategy: 'balanced', requireApproval: true, instructions: 'Production changes require care. Verify before applying.' },
+    },
+  ],
+  'weaver-genesis': [
+    {
+      name: 'Evolution',
+      description: 'Self-improvement cycles. Analyzes and evolves workflows autonomously.',
+      icon: 'autoAwesome',
+      color: 'color-node-cyan-icon',
+      capabilities: [
+        { name: 'workflow-evolution', description: 'Analyze and improve existing Flow Weaver workflows' },
+        { name: 'self-improvement', description: 'Identify and fix issues in bot behavior and prompts' },
+      ],
+      preferences: { costStrategy: 'performance', requireApproval: true, instructions: 'Evolution changes affect the system itself. Always require approval.' },
+    },
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// ProfileStore
+// ---------------------------------------------------------------------------
+
+export class ProfileStore {
+  private readonly filePath: string;
+  private profiles: BotProfile[];
+
+  constructor(private readonly projectDir: string) {
+    const dir = path.join(projectDir, '.weaver');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    this.filePath = path.join(dir, 'profiles.json');
+    this.profiles = this._loadFromDisk();
+  }
+
+  // ---------------------------------------------------------------------------
+  // CRUD
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create a new profile. Note: `botId` is NOT validated against BotRegistry
+   * here to avoid a circular dependency. Validation happens at dispatch time
+   * in SwarmController when building the profileBotMap.
+   */
+  create(input: CreateProfileInput): BotProfile {
+    const now = new Date().toISOString();
+
+    let id = this._slugify(input.name);
+    if (this.profiles.some(p => p.id === id)) {
+      id = `${id}-${crypto.randomBytes(3).toString('hex')}`;
+    }
+
+    const profile: BotProfile = {
+      id,
+      name: input.name,
+      description: input.description ?? '',
+      icon: input.icon ?? 'smartToy',
+      color: input.color ?? 'color-node-blue-icon',
+      botId: input.botId,
+      capabilities: input.capabilities ?? [],
+      preferences: {
+        costStrategy: input.preferences?.costStrategy ?? 'balanced',
+        maxCostPerRun: input.preferences?.maxCostPerRun,
+        maxCostPerTask: input.preferences?.maxCostPerTask,
+        requireApproval: input.preferences?.requireApproval ?? false,
+        instructions: input.preferences?.instructions,
+      },
+      minInstances: input.minInstances ?? 0,
+      maxInstances: input.maxInstances ?? 1,
+      currentInstances: 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    this.profiles.push(profile);
+    this._save();
+    return profile;
+  }
+
+  list(): BotProfile[] {
+    return [...this.profiles];
+  }
+
+  get(id: string): BotProfile | null {
+    return this.profiles.find(p => p.id === id) ?? null;
+  }
+
+  update(id: string, patch: Partial<Omit<BotProfile, 'id' | 'createdAt'>>): BotProfile {
+    const idx = this.profiles.findIndex(p => p.id === id);
+    if (idx === -1) throw new Error(`Profile not found: ${id}`);
+
+    // Prevent overriding immutable fields
+    const { id: _id, createdAt: _createdAt, ...safePatch } = patch as Record<string, unknown>;
+
+    const profile = this.profiles[idx];
+    Object.assign(profile, safePatch, { updatedAt: new Date().toISOString() });
+    this.profiles[idx] = profile;
+    this._save();
+    return profile;
+  }
+
+  delete(id: string): boolean {
+    const idx = this.profiles.findIndex(p => p.id === id);
+    if (idx === -1) return false;
+    this.profiles.splice(idx, 1);
+    this._save();
+    return true;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Capability search
+  // ---------------------------------------------------------------------------
+
+  findByCapabilities(required: string[]): BotProfile[] {
+    return this.profiles.filter(p =>
+      required.every(name => p.capabilities.some(c => c.name === name)),
+    );
+  }
+
+  // ---------------------------------------------------------------------------
+  // Default profiles
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create enterprise-ready default profiles for registered bots.
+   * Only creates profiles if none exist for a given botId.
+   *
+   * For weaver-bot: Developer, Reviewer, Ops
+   * For genesis: Evolution
+   * For unknown bots: one generic profile
+   */
+  ensureDefaultProfiles(bots: Array<{ id: string; name: string; icon?: string; color?: string }>): void {
+    for (const bot of bots) {
+      if (this.profiles.some(p => p.botId === bot.id)) continue;
+
+      const defaults = DEFAULT_PROFILES[bot.id];
+      if (defaults) {
+        for (const def of defaults) {
+          if (this.profiles.some(p => p.id === def.name.toLowerCase().replace(/[^a-z0-9]+/g, '-'))) continue;
+          this.create({ ...def, botId: bot.id });
+        }
+      } else {
+        this.create({
+          name: bot.name,
+          botId: bot.id,
+          icon: bot.icon,
+          color: bot.color,
+          capabilities: [{ name: 'general', description: 'General-purpose task execution' }],
+        });
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // File I/O — atomic write via temp + rename
+  // ---------------------------------------------------------------------------
+
+  private _loadFromDisk(): BotProfile[] {
+    if (!fs.existsSync(this.filePath)) return [];
+    try {
+      const raw = fs.readFileSync(this.filePath, 'utf-8');
+      const data = JSON.parse(raw);
+      return Array.isArray(data) ? data : [];
+    } catch {
+      return [];
+    }
+  }
+
+  private _save(): void {
+    const tmpPath = this.filePath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(this.profiles, null, 2), 'utf-8');
+    fs.renameSync(tmpPath, this.filePath);
+  }
+
+  private _slugify(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+  }
+}

package/src/bot/profile-types.ts

@@ -0,0 +1,141 @@
+/**
+ * Bot profile and orchestrator types for the Weaver Swarm.
+ * Profiles wrap BotRegistry entries with scaling, budget, and routing config.
+ * The orchestrator uses these types to route tasks to the best available bot.
+ */
+
+/** A free-form capability that a bot profile can declare. */
+export interface Capability {
+  name: string;
+  description: string;
+}
+
+/** Intent-based cost strategy for execution preferences. */
+export type CostStrategy = 'frugal' | 'balanced' | 'performance';
+
+/** Execution preferences for a bot profile. */
+export interface ProfilePreferences {
+  costStrategy: CostStrategy;
+  maxCostPerRun?: number;
+  maxCostPerTask?: number;
+  requireApproval: boolean;
+  instructions?: string;
+}
+
+/** A bot profile wrapping a BotRegistry entry with scaling and budget config. */
+export interface BotProfile {
+  id: string;
+  name: string;
+  description: string;
+  icon: string;
+  color: string;
+
+  /** References an entry in BotRegistry. */
+  botId: string;
+
+  /** Declared capabilities for routing. */
+  capabilities: Capability[];
+
+  /** Execution preferences (cost strategy, approval, instructions). */
+  preferences: ProfilePreferences;
+
+  // Scaling
+  /** Minimum running instances (0 = scale to zero). */
+  minInstances: number;
+  maxInstances: number;
+  currentInstances: number;
+
+  // Metadata
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** A running worker instance of a bot profile. */
+export interface BotInstance {
+  /** Format: `${profileId}-${index}` */
+  instanceId: string;
+  profileId: string;
+  index: number;
+  status: 'idle' | 'executing' | 'paused' | 'stopped';
+
+  currentTaskId?: string;
+  currentRunId?: string;
+  startedAt?: string;
+
+  // Counters
+  tokensUsed: number;
+  cost: number;
+  tasksCompleted: number;
+  tasksFailed: number;
+}
+
+/** A recorded routing decision made by the orchestrator. */
+export interface OrchestratorDecision {
+  /** Sequential decision ID. */
+  id: number;
+  timestamp: number;
+  taskId: string;
+  taskTitle: string;
+  assignedProfileId: string;
+  assignedInstanceId: string;
+  reason: string;
+  method: 'exact-match' | 'single-eligible' | 'ai-routed' | 'round-robin' | 'manual';
+  candidateProfiles: string[];
+  confidence?: number;
+}
+
+/** Input to the orchestrator routing logic. */
+export interface OrchestratorInput {
+  pendingTasks: Array<{
+    id: string;
+    title: string;
+    description: string;
+    priority: number;
+    complexity: 'trivial' | 'simple' | 'moderate' | 'complex';
+    assignedProfile?: string;
+    context: {
+      runSummaries: Array<{ outcome: string; botId: string }>;
+    };
+  }>;
+  profiles: BotProfile[];
+  instances: BotInstance[];
+  budgetRemaining: {
+    tokens: number;
+    cost: number;
+  };
+}
+
+/** Output from the orchestrator routing logic. */
+export interface OrchestratorOutput {
+  assignments: Array<{
+    taskId: string;
+    profileId: string;
+    instanceId: string;
+    reason: string;
+    method: OrchestratorDecision['method'];
+    confidence?: number;
+  }>;
+  scaleActions: Array<{
+    profileId: string;
+    action: 'scale-up' | 'scale-down';
+    targetInstances: number;
+    reason: string;
+  }>;
+  skippedTasks: Array<{
+    taskId: string;
+    reason: string;
+  }>;
+}
+
+/** Input for creating a new bot profile. */
+export interface CreateProfileInput {
+  name: string;
+  description?: string;
+  icon?: string;
+  color?: string;
+  botId: string;
+  capabilities?: Capability[];
+  preferences?: Partial<ProfilePreferences>;
+  minInstances?: number;
+  maxInstances?: number;
+}