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

package/src/ai-chat-provider.ts

@@ -26,6 +26,7 @@ import { TaskStore } from './bot/task-store.js';
 import { SwarmController } from './bot/swarm-controller.js';
 import { SwarmEventLog } from './bot/swarm-event-log.js';
 import type { CreateTaskInput, TaskFilter } from './bot/task-types.js';
+import type { CreateProfileInput } from './bot/profile-types.js';
 
 interface AiChatToolContext {
   workspacePath: string;
@@ -145,8 +146,8 @@ const toolHandlers: Record<
     const state = controller.getStatus();
     return JSON.stringify({
       swarmStatus: state.status,
-      activeBots: Object.values(state.bots).filter(b => b.status === 'executing').length,
-      totalBots: Object.keys(state.bots).length,
+      activeBots: Object.values(state.instances).filter(i => i.status === 'executing').length,
+      totalBots: Object.keys(state.instances).length,
       tasksCompleted: state.tasksCompleted,
       tasksFailed: state.tasksFailed,
       totalTokensUsed: state.totalTokensUsed,
@@ -318,7 +319,6 @@ const toolHandlers: Record<
     const input: CreateTaskInput = {
       title: args.title as string,
       description: (args.description as string) ?? '',
-      assignedBots: args.assignedBots as string[] | undefined,
       priority: args.priority as number | undefined,
       parentId: args.parentId as string | undefined,
       dependsOn: args.dependsOn as string[] | undefined,
@@ -327,6 +327,8 @@ const toolHandlers: Record<
       timeoutMs: args.timeoutMs as number | undefined,
       maxAttempts: args.maxAttempts as number | undefined,
       createdBy: 'ai',
+      assignedProfile: args.assignedProfile as string | undefined,
+      complexity: args.complexity as CreateTaskInput['complexity'],
       subtasks: args.subtasks as CreateTaskInput['subtasks'],
     };
     const task = await store.create(input);
@@ -430,8 +432,153 @@ const toolHandlers: Record<
     const done = controller.getStatus().status === 'idle';
     return JSON.stringify({ events, done });
   },
+
+  // ---------------------------------------------------------------------------
+  // Profile CRUD tools
+  // ---------------------------------------------------------------------------
+
+  async fw_weaver_profile_list(_args: Record<string, unknown>, ctx: AiChatToolContext) {
+    const controller = SwarmController.getInstance(ctx.workspacePath);
+    const profileStore = controller.getProfileStore();
+    const instanceManager = controller.getInstanceManager();
+    const profiles = profileStore.list();
+    const enriched = profiles.map(p => ({
+      ...p,
+      activeInstances: instanceManager.listByProfile(p.id).filter(i => i.status === 'executing').length,
+      idleInstances: instanceManager.findIdle(p.id).length,
+      totalInstances: instanceManager.listByProfile(p.id).length,
+    }));
+    return JSON.stringify(enriched, null, 2);
+  },
+
+  async fw_weaver_profile_create(args: Record<string, unknown>, ctx: AiChatToolContext) {
+    const controller = SwarmController.getInstance(ctx.workspacePath);
+    const profileStore = controller.getProfileStore();
+    const input: CreateProfileInput = {
+      name: args.name as string,
+      botId: args.botId as string,
+      capabilities: args.capabilities as CreateProfileInput['capabilities'],
+      preferences: {
+        costStrategy: (args.costStrategy as 'frugal' | 'balanced' | 'performance') ?? 'balanced',
+        maxCostPerRun: args.maxCostPerRun as number | undefined,
+        maxCostPerTask: args.maxCostPerTask as number | undefined,
+        requireApproval: args.requireApproval as boolean | undefined,
+        instructions: args.instructions as string | undefined,
+      },
+      maxInstances: args.maxInstances as number | undefined,
+      description: args.description as string | undefined,
+      icon: args.icon as string | undefined,
+      color: args.color as string | undefined,
+    };
+    const profile = profileStore.create(input);
+    return JSON.stringify(profile, null, 2);
+  },
+
+  async fw_weaver_profile_update(args: Record<string, unknown>, ctx: AiChatToolContext) {
+    const controller = SwarmController.getInstance(ctx.workspacePath);
+    const profileStore = controller.getProfileStore();
+    const { id, ...rest } = args;
+
+    // Build a typed patch from the remaining args
+    const patch: Record<string, unknown> = {};
+    if (rest.name !== undefined) patch.name = rest.name;
+    if (rest.description !== undefined) patch.description = rest.description;
+    if (rest.icon !== undefined) patch.icon = rest.icon;
+    if (rest.color !== undefined) patch.color = rest.color;
+    if (rest.capabilities !== undefined) patch.capabilities = rest.capabilities;
+    if (rest.maxInstances !== undefined) patch.maxInstances = rest.maxInstances;
+    if (rest.minInstances !== undefined) patch.minInstances = rest.minInstances;
+    if (rest.costStrategy !== undefined || rest.maxCostPerRun !== undefined || rest.maxCostPerTask !== undefined || rest.requireApproval !== undefined || rest.instructions !== undefined) {
+      patch.preferences = {
+        ...(rest.costStrategy !== undefined && { costStrategy: rest.costStrategy }),
+        ...(rest.maxCostPerRun !== undefined && { maxCostPerRun: rest.maxCostPerRun }),
+        ...(rest.maxCostPerTask !== undefined && { maxCostPerTask: rest.maxCostPerTask }),
+        ...(rest.requireApproval !== undefined && { requireApproval: rest.requireApproval }),
+        ...(rest.instructions !== undefined && { instructions: rest.instructions }),
+      };
+    }
+
+    const profile = profileStore.update(id as string, patch);
+    return JSON.stringify(profile, null, 2);
+  },
+
+  async fw_weaver_profile_delete(args: Record<string, unknown>, ctx: AiChatToolContext) {
+    const controller = SwarmController.getInstance(ctx.workspacePath);
+    const profileStore = controller.getProfileStore();
+    const deleted = profileStore.delete(args.id as string);
+    return JSON.stringify({ deleted });
+  },
+
+  // ---------------------------------------------------------------------------
+  // Orchestrator tools
+  // ---------------------------------------------------------------------------
+
+  async fw_weaver_orchestrator_status(_args: Record<string, unknown>, ctx: AiChatToolContext) {
+    const controller = SwarmController.getInstance(ctx.workspacePath);
+    const { decisions, stats } = controller.getOrchestratorStatus();
+    const instanceManager = controller.getInstanceManager();
+    const allInstances = instanceManager.listAll();
+    return JSON.stringify({
+      recentDecisions: decisions.slice(-20),
+      routingStats: stats,
+      activeInstances: allInstances.filter(i => i.status === 'executing').length,
+      totalInstances: allInstances.length,
+    }, null, 2);
+  },
+
+  async fw_weaver_orchestrator_hint(args: Record<string, unknown>, ctx: AiChatToolContext) {
+    const hint = args.hint as string;
+    if (!hint) return JSON.stringify({ error: 'hint is required' });
+
+    const weaverDir = path.join(ctx.workspacePath, '.weaver');
+    fs.mkdirSync(weaverDir, { recursive: true });
+    const hintsPath = path.join(weaverDir, 'orchestrator-hints.json');
+
+    let hints: Array<{ hint: string; timestamp: number }> = [];
+    try {
+      if (fs.existsSync(hintsPath)) {
+        const raw = fs.readFileSync(hintsPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) hints = parsed;
+      }
+    } catch { /* corrupt file — start fresh */ }
+
+    hints.push({ hint, timestamp: Date.now() });
+    fs.writeFileSync(hintsPath, JSON.stringify(hints, null, 2), 'utf-8');
+    return JSON.stringify({ stored: true });
+  },
 };
 
+// ---------------------------------------------------------------------------
+// Shared handler — used by both ai-chat-provider and mcp-tools
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a weaver tool by name. Shared core for ai-chat-provider and MCP.
+ *
+ * @param toolName  One of the fw_weaver_* tool names
+ * @param args      Tool arguments (as parsed from the caller)
+ * @param projectDir  Workspace / project directory
+ * @returns The JSON-serialised result string
+ */
+export async function handleWeaverTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  projectDir: string,
+): Promise<{ result: string; isError: boolean }> {
+  const handler = toolHandlers[toolName];
+  if (!handler) {
+    return { result: `Unknown weaver tool: ${toolName}`, isError: true };
+  }
+  try {
+    const ctx: AiChatToolContext = { workspacePath: projectDir, userId: 'mcp' };
+    const result = await handler(args, ctx);
+    return { result, isError: false };
+  } catch (err) {
+    return { result: err instanceof Error ? err.message : String(err), isError: true };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Provider implementation
 // ---------------------------------------------------------------------------
@@ -442,16 +589,7 @@ export default {
     args: Record<string, unknown>,
     context: AiChatToolContext,
   ): Promise<AiChatToolResult> {
-    const handler = toolHandlers[name];
-    if (!handler) {
-      return { result: `Unknown weaver tool: ${name}`, isError: true };
-    }
-    try {
-      const result = await handler(args, context);
-      return { result, isError: false };
-    } catch (err) {
-      return { result: err instanceof Error ? err.message : String(err), isError: true };
-    }
+    return handleWeaverTool(name, args, context.workspacePath);
   },
 
   async getSystemPromptSections(
@@ -482,7 +620,7 @@ export default {
       content: `Beyond standard Flow Weaver tools, you have swarm-based task and bot management:
 
 **Task Management:**
-- \`fw_weaver_task_create\`: Create tasks (with optional subtasks via \`subtasks\` array, \`^prev\` shorthand for dependency chaining, \`assignedBots\` to target specific bots)
+- \`fw_weaver_task_create\`: Create tasks (with optional subtasks via \`subtasks\` array, \`^prev\` shorthand for dependency chaining, \`assignedProfile\` to target specific profiles)
 - \`fw_weaver_task_list\`: List tasks (filter by status, parentId, botId)
 - \`fw_weaver_task_get\`: Get task details including subtasks and context
 - \`fw_weaver_task_update\`: Update task fields (title, description, priority, status)
@@ -512,7 +650,15 @@ export default {
 - \`fw_weaver_validate_bot\`: Validate a bot's file and export
 - \`fw_weaver_eject_bot\`: Mark a bot as ejected with a new file path
 
-**Workflow:** To delegate work, create tasks with \`fw_weaver_task_create\`, then start the swarm with \`fw_weaver_swarm_start\`. Bots will automatically claim and execute tasks. Use \`fw_weaver_steer\` with a \`botId\` to control individual bots.
+**Profiles & Orchestrator:**
+- \`fw_weaver_profile_list\`: List all bot profiles with capabilities, instances, and routing info
+- \`fw_weaver_profile_create\`: Create a new bot profile with free-form capabilities (name + description pairs) and preferences (costStrategy, maxCostPerRun, maxCostPerTask, requireApproval, instructions)
+- \`fw_weaver_profile_update\`: Update a bot profile's capabilities, preferences, or scaling config
+- \`fw_weaver_profile_delete\`: Delete a bot profile
+- \`fw_weaver_orchestrator_status\`: Get orchestrator routing status — recent decisions, stats, active instances
+- \`fw_weaver_orchestrator_hint\`: Provide a routing hint to influence orchestrator decisions
+
+**Workflow:** To delegate work, create tasks with \`fw_weaver_task_create\`, then start the swarm with \`fw_weaver_swarm_start\`. The orchestrator automatically routes tasks to the best available bot instance based on free-form capability matching. Use \`fw_weaver_steer\` with a \`botId\` to control individual bots. Use \`fw_weaver_profile_create\` to create specialized profiles with capabilities (name + description pairs) and preferences (costStrategy, maxCostPerRun, instructions), then route tasks via \`assignedProfile\`.
 
 Proactively offer these when relevant.`,
       priority: 15,
@@ -574,24 +720,44 @@ Proactively offer these when relevant.`,
           sections.push({
             id: 'registered-bots',
             title: 'Registered Bots',
-            content: `The user has registered bot workflows available for swarm execution. To assign work to a bot, use \`fw_weaver_task_create\` with \`assignedBots: ["${bots[0]!.id}"]\` — do NOT use the old \`fw_weaver_bot\` tool (it has been removed).\n\n${botLines}`,
+            content: `The user has registered bot workflows available for swarm execution. To assign work, use \`fw_weaver_task_create\` with \`assignedProfile\` to route tasks to the right profile.\n\n${botLines}`,
             priority: 25,
           });
         }
       } catch { /* non-fatal */ }
     }
 
+    // Bot profiles — capabilities, scaling, routing info
+    if (context.workspacePath) {
+      try {
+        const controller = SwarmController.getInstance(context.workspacePath);
+        const profileStore = controller.getProfileStore();
+        const profiles = profileStore.list();
+        if (profiles.length > 0) {
+          const profileLines = profiles.map(p =>
+            `- ${p.name} (${p.id}): capabilities=[${p.capabilities.map(c => c.name).join(', ')}], maxInstances=${p.maxInstances}, costStrategy=${p.preferences.costStrategy}`,
+          ).join('\n');
+          sections.push({
+            id: 'bot-profiles',
+            title: 'Bot Profiles',
+            content: `${profileLines}\n\nUse fw_weaver_profile_create to create new profiles. Use fw_weaver_task_create with assignedProfile to route tasks to the right profiles.`,
+            priority: 22,
+          });
+        }
+      } catch { /* non-fatal */ }
+    }
+
     // Swarm status — include if swarm is active
     if (context.workspacePath) {
       try {
         const controller = SwarmController.getInstance(context.workspacePath);
         const swarmState = controller.getStatus();
         if (swarmState.status !== 'idle') {
-          const activeBots = Object.values(swarmState.bots).filter(b => b.status === 'executing').length;
+          const activeInstances = Object.values(swarmState.instances).filter(i => i.status === 'executing').length;
           sections.push({
             id: 'swarm-status',
             title: 'Swarm Status',
-            content: `The swarm is currently **${swarmState.status}** with ${activeBots} active bot(s) out of ${Object.keys(swarmState.bots).length} total. Tasks completed: ${swarmState.tasksCompleted}, failed: ${swarmState.tasksFailed}. Total cost: $${swarmState.totalCost.toFixed(4)}, tokens: ${swarmState.totalTokensUsed}.`,
+            content: `The swarm is currently **${swarmState.status}** with ${activeInstances} active instance(s) out of ${Object.keys(swarmState.instances).length} total. Tasks completed: ${swarmState.tasksCompleted}, failed: ${swarmState.tasksFailed}. Total cost: $${swarmState.totalCost.toFixed(4)}, tokens: ${swarmState.totalTokensUsed}.`,
             priority: 12,
           });
         }

package/src/bot/ai-router.ts

@@ -0,0 +1,132 @@
+/**
+ * AIRouterImpl — LLM-powered routing for ambiguous profile selection.
+ *
+ * When multiple bot profiles match a task, the orchestrator delegates
+ * to this router to pick the best one.
+ * Uses the project's configured AI provider via the callAI infrastructure.
+ */
+
+import type { AIRouter, AIRouterResult } from './orchestrator.js';
+import type { BotProfile, OrchestratorInput } from './profile-types.js';
+import type { ProviderInfo } from './types.js';
+import { callAI, parseJsonResponse } from './ai-client.js';
+import { resolveProviderConfig, detectProvider } from './agent-provider.js';
+
+type Task = OrchestratorInput['pendingTasks'][number];
+
+// ---------------------------------------------------------------------------
+// Provider resolution — map BotProviderConfig.name to ProviderInfo.type
+// ---------------------------------------------------------------------------
+
+const NAME_TO_TYPE: Record<string, ProviderInfo['type']> = {
+  anthropic: 'anthropic',
+  'claude-cli': 'claude-cli',
+  'copilot-cli': 'copilot-cli',
+  platform: 'platform',
+};
+
+function resolveProviderInfo(projectDir: string): Pick<ProviderInfo, 'type' | 'apiKey' | 'model' | 'maxTokens'> {
+  // Try reading .weaver.json from the project directory
+  let providerInput: string | { name: string; model?: string; maxTokens?: number } = 'auto';
+  try {
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const configPath = path.join(projectDir, '.weaver.json');
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (config.provider) providerInput = config.provider;
+    }
+  } catch { /* use auto detection */ }
+
+  const resolved = resolveProviderConfig(providerInput);
+  const type = NAME_TO_TYPE[resolved.name] ?? 'claude-cli';
+
+  return {
+    type,
+    model: resolved.model,
+    maxTokens: resolved.maxTokens,
+    apiKey: type === 'anthropic' ? process.env.ANTHROPIC_API_KEY : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AIRouterImpl
+// ---------------------------------------------------------------------------
+
+const SYSTEM_PROMPT =
+  'You are a task routing orchestrator. Given a task and candidate bot profiles, ' +
+  'select the best profile to handle the task. Respond with ONLY valid JSON: ' +
+  '{ "profileId": "...", "reason": "...", "confidence": 0.0-1.0 }';
+
+export class AIRouterImpl implements AIRouter {
+  private projectDir: string;
+
+  constructor(projectDir: string) {
+    this.projectDir = projectDir;
+  }
+
+  async route(task: Task, candidates: BotProfile[]): Promise<AIRouterResult> {
+    const prompt = this._buildPrompt(task, candidates);
+    const providerInfo = resolveProviderInfo(this.projectDir);
+
+    // Use a low max-tokens since this is just a routing decision
+    const response = await callAI(providerInfo, SYSTEM_PROMPT, prompt, 256);
+
+    const result = parseJsonResponse(response) as {
+      profileId?: string;
+      reason?: string;
+      confidence?: number;
+    };
+
+    if (!result.profileId) {
+      throw new Error('AI router returned no profileId');
+    }
+
+    return {
+      profileId: result.profileId,
+      reason: result.reason || 'AI-selected',
+      confidence: typeof result.confidence === 'number' ? result.confidence : 0.5,
+    };
+  }
+
+  /** @internal — exposed for testing */
+  _buildPrompt(task: Task, candidates: BotProfile[]): string {
+    const lines = [
+      `Task: "${task.title}"`,
+      task.description ? `Description: ${task.description}` : '',
+      task.complexity ? `Complexity: ${task.complexity}` : '',
+      '',
+      'Candidate profiles:',
+      ...candidates.map((p) => {
+        const parts = [`- ${p.id} (${p.name}):`];
+        if (p.capabilities.length > 0) {
+          parts.push('  Capabilities:');
+          for (const cap of p.capabilities) {
+            parts.push(`    - ${cap.name}: ${cap.description}`);
+          }
+        }
+        parts.push(`  Cost strategy: ${p.preferences.costStrategy}`);
+        if (p.preferences.instructions) {
+          parts.push(`  Instructions: ${p.preferences.instructions}`);
+        }
+        parts.push(`  maxInstances=${p.maxInstances}`);
+        return parts.join('\n');
+      }),
+    ];
+
+    // Add previous attempt info if available
+    const failures = task.context.runSummaries.filter((r) => r.outcome !== 'success');
+    if (failures.length > 0) {
+      lines.push(
+        '',
+        `Previous attempts: ${task.context.runSummaries.length} (${failures.length} failed)`,
+      );
+      for (const f of failures.slice(-3)) {
+        lines.push(`  - ${f.botId}: ${f.outcome}`);
+      }
+    }
+
+    lines.push('', 'Select the best profile. Respond with JSON only.');
+    return lines.filter(Boolean).join('\n');
+  }
+}

package/src/bot/bot-registry.ts

@@ -1,5 +1,5 @@
 /**
- * Bot registry — manages .fw/bots.json in the user's workspace.
+ * Bot registry — manages .weaver/bots.json in the user's workspace.
  * Reads, writes, validates bot registrations.
  */
 import * as fs from 'node:fs';
@@ -19,7 +19,7 @@ export interface BotRegistration {
   ejected?: boolean;
 }
 
-const BOTS_FILE = '.fw/bots.json';
+const BOTS_FILE = '.weaver/bots.json';
 
 export class BotRegistry {
   private _cache: BotRegistration[] | null = null;

package/src/bot/conversation-store.ts

@@ -26,6 +26,7 @@ export interface ConversationRecord {
   createdAt: number;
   lastMessageAt: number;
   botIds: string[];
+  cloudConversationId?: string;
 }
 
 interface StoredMessage {
@@ -221,7 +222,7 @@ export class ConversationStore {
         },
         body: JSON.stringify({
           message: `[Synced from CLI] ${message}`,
-          conversationId: (conversation as any).cloudConversationId,
+          conversationId: conversation.cloudConversationId,
         }),
       }).catch(() => {}); // fire-and-forget
     } catch { /* sync not available */ }

package/src/bot/improve-loop.ts

@@ -526,9 +526,9 @@ function emptyResult(startedAt: string, branch: string, worktreePath: string, re
 
 // --- Helpers ---
 
-let cachedProvider: unknown = null;
-let cachedTools: unknown[] = [];
-let cachedExecutor: unknown = null;
+let cachedProvider: import('@synergenius/flow-weaver/agent').AgentProvider | null = null;
+let cachedTools: import('@synergenius/flow-weaver/agent').ToolDefinition[] = [];
+let cachedExecutor: import('@synergenius/flow-weaver/agent').ToolExecutor | null = null;
 
 async function runAssistantInDir(worktreeDir: string, message: string, _conversationId: string, steeringEngine?: import('./steering-engine.js').SteeringEngine): Promise<string> {
   const originalCwd = process.cwd();
@@ -562,9 +562,9 @@ async function runAssistantInDir(worktreeDir: string, message: string, _conversa
     const toolCalls: Array<{ name: string; isError: boolean }> = [];
 
     const result = await runAgentLoop(
-      cachedProvider as any,
-      cachedTools as any,
-      cachedExecutor as any,
+      cachedProvider!,
+      cachedTools,
+      cachedExecutor!,
       [{ role: 'user' as const, content: message }],
       {
         maxIterations: 20,

package/src/bot/instance-manager.ts

@@ -0,0 +1,128 @@
+/**
+ * InstanceManager — manages in-memory bot instances (workers) per profile.
+ * Instances represent running workers that don't survive process restart.
+ */
+
+import type { BotProfile, BotInstance } from './profile-types.js';
+
+export class InstanceManager {
+  private instances = new Map<string, BotInstance>();
+
+  /** Spawn a new instance for the given profile. Throws if maxInstances reached. */
+  spawn(profile: BotProfile): BotInstance {
+    const existing = this.listByProfile(profile.id);
+    if (existing.length >= profile.maxInstances) {
+      throw new Error(
+        `Cannot spawn: profile "${profile.id}" already at max instances (${profile.maxInstances})`,
+      );
+    }
+
+    const usedIndices = new Set(existing.map((i) => i.index));
+    let index = 0;
+    while (usedIndices.has(index)) index++;
+
+    const instance: BotInstance = {
+      instanceId: `${profile.id}-${index}`,
+      profileId: profile.id,
+      index,
+      status: 'idle',
+      tokensUsed: 0,
+      cost: 0,
+      tasksCompleted: 0,
+      tasksFailed: 0,
+    };
+
+    this.instances.set(instance.instanceId, instance);
+    return { ...instance };
+  }
+
+  /** Get instance by ID (returns a copy), or null if not found. */
+  get(instanceId: string): BotInstance | null {
+    const inst = this.instances.get(instanceId);
+    return inst ? { ...inst } : null;
+  }
+
+  /** Return copies of all instances. */
+  listAll(): BotInstance[] {
+    return [...this.instances.values()].map((i) => ({ ...i }));
+  }
+
+  /** Return copies of instances belonging to a specific profile. */
+  listByProfile(profileId: string): BotInstance[] {
+    return [...this.instances.values()]
+      .filter((i) => i.profileId === profileId)
+      .map((i) => ({ ...i }));
+  }
+
+  /** Return idle instances for a given profile. */
+  findIdle(profileId: string): BotInstance[] {
+    return [...this.instances.values()]
+      .filter((i) => i.profileId === profileId && i.status === 'idle')
+      .map((i) => ({ ...i }));
+  }
+
+  /** Mark an instance as executing a specific task/run. */
+  markExecuting(instanceId: string, taskId: string, runId: string): void {
+    const inst = this.instances.get(instanceId);
+    if (!inst) throw new Error(`Instance not found: ${instanceId}`);
+    inst.status = 'executing';
+    inst.currentTaskId = taskId;
+    inst.currentRunId = runId;
+    inst.startedAt = new Date().toISOString();
+  }
+
+  /** Mark an instance as idle after task completion/failure. */
+  markIdle(instanceId: string, success: boolean): void {
+    const inst = this.instances.get(instanceId);
+    if (!inst) throw new Error(`Instance not found: ${instanceId}`);
+    inst.status = 'idle';
+    inst.currentTaskId = undefined;
+    inst.currentRunId = undefined;
+    inst.startedAt = undefined;
+    if (success) {
+      inst.tasksCompleted++;
+    } else {
+      inst.tasksFailed++;
+    }
+  }
+
+  /** Record token/cost usage for an instance. */
+  recordUsage(instanceId: string, tokens: number, cost: number): void {
+    const inst = this.instances.get(instanceId);
+    if (!inst) throw new Error(`Instance not found: ${instanceId}`);
+    inst.tokensUsed += tokens;
+    inst.cost += cost;
+  }
+
+  /** Stop and remove an instance. Returns true if it existed. */
+  stop(instanceId: string): boolean {
+    return this.instances.delete(instanceId);
+  }
+
+  /** Stop and remove all instances. */
+  stopAll(): void {
+    this.instances.clear();
+  }
+
+  /** Scale instances for a profile to the target count. Clamps to [0, maxInstances]. */
+  scaleTo(profile: BotProfile, target: number): void {
+    const clamped = Math.max(0, Math.min(target, profile.maxInstances));
+    const current = this.listByProfile(profile.id);
+
+    if (current.length < clamped) {
+      // Spawn more
+      const toSpawn = clamped - current.length;
+      for (let i = 0; i < toSpawn; i++) {
+        this.spawn(profile);
+      }
+    } else if (current.length > clamped) {
+      // Stop idle instances first
+      const idle = current.filter((i) => i.status === 'idle');
+      const toStop = current.length - clamped;
+      const stopped = idle.slice(0, toStop);
+      for (const inst of stopped) {
+        this.stop(inst.instanceId);
+      }
+    }
+  }
+}