pi-subagents-router 1.0.2

package/dist/Supvisor.js

@@ -0,0 +1,310 @@
+/**
+ * Supvisor — The agent routing supervisor.
+ *
+ * Extracts the agent management logic from agent-router.ts and provides
+ * two entry points:
+ *   - routeAgent() — single-agent routing (same behavior as old)
+ *   - planAndRoute() — multi-agent workflow (NEW)
+ */
+import { BUILTIN_AGENTS } from "./BuiltinAgents.js";
+async function spawnSubAgent(pi, subagentType, prompt, description, runInBackground = false, options = {}) {
+    const PI_SUBAGENTS_REPO = "https://github.com/tintinweb/pi-subagents";
+    const requestId = `router-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    return new Promise((resolve) => {
+        let unsub = null;
+        const timeout = setTimeout(() => {
+            if (unsub)
+                unsub();
+            resolve({
+                success: false,
+                error: `Timed out waiting for pi-subagents RPC reply. Is ${PI_SUBAGENTS_REPO} installed and loaded?`,
+            });
+        }, 10_000);
+        let emitError;
+        try {
+            pi.events.emit("subagents:rpc:spawn", {
+                requestId,
+                type: subagentType,
+                prompt,
+                options: {
+                    description,
+                    run_in_background: runInBackground,
+                    thinking: options.thinking,
+                    model: options.model,
+                    inherit_context: options.inheritContext,
+                    inherit_skills: options.inheritSkills,
+                },
+            });
+        }
+        catch (err) {
+            emitError = err.message || "Unknown emit error";
+        }
+        if (emitError) {
+            clearTimeout(timeout);
+            resolve({
+                success: false,
+                error: `Failed to emit spawn event to pi-subagents: ${emitError}`,
+            });
+            return;
+        }
+        unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
+            clearTimeout(timeout);
+            unsub();
+            if (!reply?.success) {
+                resolve({
+                    success: false,
+                    error: reply?.error || "Unknown pi-subagents RPC error",
+                });
+                return;
+            }
+            resolve({ success: true, agentId: reply.data?.id });
+        });
+    });
+}
+// ============================================================================
+// Helper: Analyze task description and determine best agent
+// (Same as the old analyzeTaskDescription, extracted and made static)
+// ============================================================================
+export function analyzeTaskDescription(taskDescription, agents) {
+    const lowerTask = taskDescription.toLowerCase();
+    // FIX: Check ALL triggers across ALL agents, then pick earliest position in input text
+    let bestTriggerAgent = null;
+    for (const agent of agents) {
+        if (agent.triggers) {
+            for (const trigger of agent.triggers) {
+                const position = lowerTask.indexOf(trigger.toLowerCase());
+                if (position >= 0) {
+                    if (!bestTriggerAgent ||
+                        position < bestTriggerAgent.position) {
+                        bestTriggerAgent = {
+                            name: agent.name,
+                            trigger,
+                            position,
+                        };
+                    }
+                }
+            }
+        }
+    }
+    if (bestTriggerAgent) {
+        return {
+            agentType: bestTriggerAgent.name,
+            reason: `Trigger match: "${bestTriggerAgent.trigger}"`,
+        };
+    }
+    // Check useWhen criteria
+    const useWhenScores = [];
+    for (const agent of agents) {
+        if (agent.useWhen) {
+            const matches = agent.useWhen.filter((criterion) => lowerTask.includes(criterion.toLowerCase()));
+            if (matches.length > 0) {
+                useWhenScores.push({
+                    agent: agent.name,
+                    score: matches.length,
+                    matches: matches,
+                });
+            }
+        }
+    }
+    // Check avoidWhen penalties
+    const avoidWhenPenalties = [];
+    for (const agent of agents) {
+        if (agent.avoidWhen) {
+            const penalties = agent.avoidWhen.filter((criterion) => lowerTask.includes(criterion.toLowerCase()));
+            if (penalties.length > 0) {
+                avoidWhenPenalties.push({ agent: agent.name, penalties });
+            }
+        }
+    }
+    // Find best match with second-best fallback
+    if (useWhenScores.length > 0) {
+        useWhenScores.sort((a, b) => b.score - a.score);
+        const topCandidate = useWhenScores[0];
+        const topPenalty = avoidWhenPenalties.find((p) => p.agent === topCandidate.agent);
+        if (!topPenalty) {
+            return {
+                agentType: topCandidate.agent,
+                reason: `useWhen match: "${topCandidate.matches.join(", ")}" (score: ${topCandidate.score})`,
+            };
+        }
+        // Second-best fallback — try next best non-penalized agent
+        for (let i = 1; i < useWhenScores.length; i++) {
+            const candidate = useWhenScores[i];
+            const candidatePenalty = avoidWhenPenalties.find((p) => p.agent === candidate.agent);
+            if (!candidatePenalty) {
+                return {
+                    agentType: candidate.agent,
+                    reason: `useWhen match: "${candidate.matches.join(", ")}" (score: ${candidate.score}), fallback from penalized "${topCandidate.agent}"`,
+                };
+            }
+        }
+        // No non-penalized match — fall back to second-best
+        const secondBest = useWhenScores[1];
+        if (secondBest) {
+            return {
+                agentType: secondBest.agent,
+                reason: `FALLBACK: "${topCandidate.agent}" penalized (${topPenalty.penalties.join(", ")}), using "${secondBest.agent}"`,
+            };
+        }
+    }
+    return {
+        agentType: "general-purpose",
+        reason: "No clear match - using general-purpose agent",
+    };
+}
+// ============================================================================
+// Supervisor — The main agent routing supervisor class
+// ============================================================================
+export class Supervisor {
+    agents;
+    pi;
+    constructor(agents, pi) {
+        this.agents = agents;
+        this.pi = pi;
+    }
+    // ========================================================================
+    // Single-Agent Routing (UNCHANGED behavior from old code)
+    // ========================================================================
+    async routeAgent(taskDescription, forceAgent, runInBackground, thinking, model) {
+        // If forceAgent is specified, use it directly
+        if (forceAgent) {
+            const agent = this.agents.find((a) => a.name === forceAgent);
+            if (agent) {
+                const spawnResult = await spawnSubAgent(this.pi, agent.name, taskDescription, taskDescription.substring(0, 50) +
+                    (taskDescription.length > 50 ? "..." : ""), runInBackground || false, { thinking: thinking || agent.thinking, model });
+                if (spawnResult.success) {
+                    return {
+                        success: true,
+                        agentType: forceAgent,
+                        agentId: spawnResult.agentId,
+                        reason: "Forced by user",
+                    };
+                }
+                else {
+                    return {
+                        success: false,
+                        error: `Failed to spawn agent '${forceAgent}': ${spawnResult.error}`,
+                    };
+                }
+            }
+            else {
+                return {
+                    success: false,
+                    error: `Agent not found: ${forceAgent}`,
+                };
+            }
+        }
+        // Analyze task description against agent criteria
+        const routingDecision = analyzeTaskDescription(taskDescription, this.agents);
+        const selectedAgent = this.agents.find((a) => a.name === routingDecision.agentType);
+        if (!selectedAgent) {
+            return {
+                success: true,
+                agentType: "general-purpose",
+                reason: routingDecision.reason,
+            };
+        }
+        // Spawn the sub-agent via pi-subagents RPC
+        const spawnResult = await spawnSubAgent(this.pi, selectedAgent.name, taskDescription, taskDescription.substring(0, 50) +
+            (taskDescription.length > 50 ? "..." : ""), runInBackground || false, { thinking: thinking || selectedAgent.thinking, model });
+        if (spawnResult.success) {
+            return {
+                success: true,
+                agentType: selectedAgent.name,
+                reason: routingDecision.reason,
+                agentId: spawnResult.agentId,
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: `Failed to spawn agent '${selectedAgent.name}': ${spawnResult.error}`,
+            };
+        }
+    }
+    // ========================================================================
+    // Multi-Agent Routing (NEW — planAndRoute)
+    // ========================================================================
+    /**
+     * Plan and route a workflow for multiple agents.
+     * Uses keyword matching to find relevant agents, then executes
+     * them in parallel (where dependencies allow).
+     */
+    async planAndRoute(goal, options) {
+        // Step 1: Find relevant agents via keyword matching
+        const relevantAgents = options?.forceAgents
+            ? this.agents.filter((a) => options.forceAgents.includes(a.name))
+            : this._findRelevantAgents(goal);
+        if (relevantAgents.length === 0) {
+            return { success: false, error: "No agents matched for goal" };
+        }
+        // Step 2: Execute agents in parallel (no dependencies in v2.0)
+        const results = {};
+        const steps = [];
+        const promises = relevantAgents.map(async (agent) => {
+            const spawnResult = await spawnSubAgent(this.pi, agent.name, goal, goal.substring(0, 50) + (goal.length > 50 ? "..." : ""), options?.background || false, { model: undefined });
+            if (spawnResult.success) {
+                results[agent.name] = { success: true, agentId: spawnResult.agentId };
+                steps.push(`✅ ${agent.name}: spawned (id: ${spawnResult.agentId})`);
+            }
+            else {
+                results[agent.name] = { success: false, error: spawnResult.error };
+                steps.push(`❌ ${agent.name}: failed (${spawnResult.error})`);
+            }
+        });
+        await Promise.all(promises);
+        return {
+            success: true,
+            agents: relevantAgents.map((a) => a.name),
+            results,
+            steps,
+        };
+    }
+    // ========================================================================
+    // Internal: Find relevant agents by keyword matching
+    // ========================================================================
+    _findRelevantAgents(goal) {
+        const lowerGoal = goal.toLowerCase();
+        const scores = new Map();
+        for (const agent of this.agents) {
+            let score = 0;
+            // Check triggers (highest priority)
+            if (agent.triggers) {
+                for (const trigger of agent.triggers) {
+                    if (lowerGoal.includes(trigger.toLowerCase())) {
+                        score += 10;
+                    }
+                }
+            }
+            // Check useWhen
+            if (agent.useWhen) {
+                for (const when of agent.useWhen) {
+                    if (lowerGoal.includes(when.toLowerCase())) {
+                        score += 5;
+                    }
+                }
+            }
+            // Subtract for avoidWhen
+            if (agent.avoidWhen) {
+                for (const when of agent.avoidWhen) {
+                    if (lowerGoal.includes(when.toLowerCase())) {
+                        score -= 3;
+                    }
+                }
+            }
+            if (score > 0)
+                scores.set(agent.name, score);
+        }
+        // Return agents with score > 0, sorted by score descending
+        return Array.from(scores.entries())
+            .sort((a, b) => b[1] - a[1])
+            .map(([name]) => this.agents.find((a) => a.name === name))
+            .filter(Boolean);
+    }
+    // ========================================================================
+    // Helper: Get all agents (builtin + filesystem)
+    // ========================================================================
+    static async getAllAgents() {
+        return BUILTIN_AGENTS;
+    }
+}

package/dist/agent-router.d.ts

@@ -0,0 +1,16 @@
+/**
+ * pi-subagents — Agent Router Extension
+ *
+ * v2.0: Supervisor-based routing (refactored from monolithic agent-router.ts)
+ *
+ * Entry point that wires the Supervisor into the VS Code extension host.
+ * Exposes:
+ *   - "route_agent" tool       (single-agent, same behavior as v1)
+ *   - "plan_and_route" tool   (multi-agent workflow, NEW)
+ *   - "/assign-agent" command  (backward-compatible shortcut)
+ *   - "list_agents" tool      (list all available agents)
+ *
+ * @see https://github.com/tintinweb/pi-subagents
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export default function (pi: ExtensionAPI): Promise<void>;

package/dist/agent-router.js

@@ -0,0 +1,209 @@
+/**
+ * pi-subagents — Agent Router Extension
+ *
+ * v2.0: Supervisor-based routing (refactored from monolithic agent-router.ts)
+ *
+ * Entry point that wires the Supervisor into the VS Code extension host.
+ * Exposes:
+ *   - "route_agent" tool       (single-agent, same behavior as v1)
+ *   - "plan_and_route" tool   (multi-agent workflow, NEW)
+ *   - "/assign-agent" command  (backward-compatible shortcut)
+ *   - "list_agents" tool      (list all available agents)
+ *
+ * @see https://github.com/tintinweb/pi-subagents
+ */
+import { Type } from "typebox";
+import { Supervisor } from "./Supvisor.js";
+import { BUILTIN_AGENTS } from "./BuiltinAgents.js";
+const PI_SUBAGENTS_REPO = "https://github.com/tintinweb/pi-subagents";
+// ============================================================================
+// Entry point
+// ============================================================================
+export default async function (pi) {
+    // Build the supervisor with builtin agents
+    const supervisor = new Supervisor([...BUILTIN_AGENTS], pi);
+    // ---- Register route_agent tool (UNCHANGED behavior) ------------------
+    pi.registerTool({
+        name: "route_agent",
+        label: "Route Agent",
+        description: `Route tasks to appropriate sub-agents via pi-subagents (${PI_SUBAGENTS_REPO})`,
+        parameters: Type.Object({
+            taskDescription: Type.String({ description: "Description of the task to be performed" }),
+            forceAgent: Type.Optional(Type.String({ description: "Optionally force a specific agent type" })),
+            runInBackground: Type.Optional(Type.Boolean({ description: "Run the agent in background (non-blocking)" })),
+            thinking: Type.Optional(Type.String({ description: "Thinking level" })),
+            model: Type.Optional(Type.String({ description: "Model to use" })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const { taskDescription, forceAgent, runInBackground, thinking, model } = params;
+            // If forceAgent is specified, use it directly
+            if (forceAgent) {
+                const result = await supervisor.routeAgent(taskDescription, forceAgent, runInBackground, thinking, model);
+                if (result.success) {
+                    const agent = BUILTIN_AGENTS.find((a) => a.name === result.agentType);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Routed to agent: ${result.agentType} via pi-subagents\n\n${agent?.description ?? ""}\n\nAgent ID: ${result.agentId ?? "foreground"}\n\nExecuted by: ${PI_SUBAGENTS_REPO}`,
+                            }],
+                        details: {
+                            agentType: result.agentType,
+                            reason: result.reason ?? "Forced by user",
+                            subagentRepo: PI_SUBAGENTS_REPO,
+                            agentId: result.agentId,
+                        },
+                    };
+                }
+                else {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Failed to spawn agent '${forceAgent}': ${result.error}`,
+                            }],
+                        details: { error: result.error },
+                    };
+                }
+            }
+            // Otherwise, analyze and route normally
+            const result = await supervisor.routeAgent(taskDescription, undefined, runInBackground, thinking, model);
+            if (result.success) {
+                const agent = BUILTIN_AGENTS.find((a) => a.name === result.agentType);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Routed to agent: ${result.agentType} via pi-subagents\n\nDescription: ${agent?.description ?? ""}\n\nReason: ${result.reason ?? ""}\n\nAgent ID: ${result.agentId ?? "foreground"}\n\nExecuted by: ${PI_SUBAGENTS_REPO}`,
+                        }],
+                    details: {
+                        agentType: result.agentType,
+                        reason: result.reason,
+                        subagentRepo: PI_SUBAGENTS_REPO,
+                        agentId: result.agentId,
+                    },
+                };
+            }
+            else {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Failed to spawn agent: ${result.error}`,
+                        }],
+                    details: { error: result.error },
+                };
+            }
+        },
+    });
+    // ---- Register plan_and_route tool (NEW — multi-agent workflow) --------
+    pi.registerTool({
+        name: "plan_and_route",
+        label: "Plan and Route",
+        description: `Plan a multi-agent workflow via pi-subagents (${PI_SUBAGENTS_REPO}). Launches multiple agents in parallel based on goal keywords.`,
+        parameters: Type.Object({
+            goal: Type.String({ description: "The goal description for multi-agent execution" }),
+            forceAgents: Type.Optional(Type.Array(Type.String({ description: "Agent names to force" }))),
+            runInBackground: Type.Optional(Type.Boolean({ description: "Run agents in background" })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            const { goal, forceAgents, runInBackground } = params;
+            const result = await supervisor.planAndRoute(goal, { forceAgents, background: runInBackground });
+            if (result.success) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Multi-agent workflow launched successfully!\n\nAgents: ${(result.agents ?? []).join(", ")}\nSteps:\n${(result.steps ?? []).join("\n")}`,
+                        }],
+                    details: {
+                        agents: result.agents,
+                        results: result.results,
+                        subagentRepo: PI_SUBAGENTS_REPO,
+                    },
+                };
+            }
+            else {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Failed to plan workflow: ${result.error}`,
+                        }],
+                    details: { error: result.error },
+                };
+            }
+        },
+    });
+    // ---- Register /assign-agent command (UNCHANGED behavior) --------------
+    pi.registerCommand("assign-agent", {
+        description: `Route tasks to appropriate sub-agents via pi-subagents (${PI_SUBAGENTS_REPO})`,
+        handler: async (input, ctx) => {
+            if (!input) {
+                ctx.ui.notify("Please provide a task description", "error");
+                return;
+            }
+            const result = await supervisor.routeAgent(input, undefined, false);
+            if (result.success) {
+                ctx.ui.notify(`Routed to ${result.agentType}: ${result.reason ?? ""} (via pi-subagents)`, "info");
+            }
+            else {
+                ctx.ui.notify(`Failed to spawn agent: ${result.error}`, "error");
+            }
+        },
+    });
+    // ---- Register list_agents tool (UNCHANGED behavior) ------------------
+    pi.registerTool({
+        name: "list_agents",
+        label: "List Agents",
+        description: `List all available agents and their routing criteria (${PI_SUBAGENTS_REPO})`,
+        parameters: Type.Object({}),
+        async execute() {
+            const agents = [
+                ...BUILTIN_AGENTS,
+                // TODO: add filesystem agents here when implemented
+            ];
+            let response = `Available Agents (routed via pi-subagents):\n\n`;
+            agents.forEach((agent, index) => {
+                response += `${index + 1}. **${agent.name}**\n`;
+                response += `   Description: ${agent.description}\n`;
+                response += `   Thinking: ${agent.thinking ?? "medium"}\n`;
+                response += `   Triggers: ${agent.triggers?.join(", ") ?? "none"}\n`;
+                response += `   Use When: ${agent.useWhen?.join(", ") ?? "any"}\n`;
+                response += `   Avoid When: ${agent.avoidWhen?.join(", ") ?? "none"}\n`;
+                response += `   Tools: ${agent.tools?.join(", ") ?? "default"}\n\n`;
+            });
+            return {
+                content: [{ type: "text", text: response }],
+                details: {
+                    agents: agents.map((a) => ({
+                        name: a.name,
+                        description: a.description,
+                        useWhen: a.useWhen,
+                        avoidWhen: a.avoidWhen,
+                    })),
+                    subagentRepo: PI_SUBAGENTS_REPO,
+                },
+            };
+        },
+    });
+    // ---- Intercept input (UNCHANGED behavior from old code) --------------
+    pi.on("input", async (event, ctx) => {
+        // Skip commands / special prefixes
+        if (event.text.startsWith("/") || event.text.startsWith("!")) {
+            return { action: "continue" };
+        }
+        // Analyze and route
+        const result = await supervisor.routeAgent(event.text, undefined, true);
+        if (result.success) {
+            ctx.ui.notify(`Auto-routed to ${result.agentType}: ${result.reason ?? ""} (via pi-subagents)`, "info");
+            return { action: "handled" };
+        }
+        else {
+            // Fallback to text transformation instead of suppressing
+            ctx.ui.notify(`Auto-routing failed: ${result.error}`, "warning");
+            return {
+                action: "transform",
+                text: `[ROUTED] ${event.text}`,
+            };
+        }
+    });
+    // ---- Session start notification (UNCHANGED) --------------------------
+    pi.on("session_start", async (_event, ctx) => {
+        ctx.ui.notify(`${PI_SUBAGENTS_REPO} engine loaded — route_agent and plan_and_route available`, "info");
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-subagents-router",
+  "version": "1.0.2",
+  "description": "A Pi extension that routes agents based on task descriptions using useWhen and avoidWhen criteria",
+  "type": "module",
+  "main": "./dist/agent-router.js",
+  "types": "./dist/agent-router.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/agent-router.d.ts",
+        "default": "./dist/agent-router.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "node --require ts-node/register test/test-supervisor.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "extension",
+    "agent",
+    "routing",
+    "ai"
+  ],
+  "author": "Asdrubal",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "typebox": "^1.3.0"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/agent-router.js"
+    ]
+  }
+}

package/src/AgentConfig.ts

@@ -0,0 +1,59 @@
+/**
+ * AgentConfig — Shared type for all agents (builtin + filesystem).
+ *
+ * This file extracts the AgentConfig interface from the monolithic
+ * agent-router.ts so it can be imported by all modules.
+ */
+
+export type AgentSource = "builtin" | "filesystem";
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  thinking?: string;
+  tools?: string[];
+  systemPromptMode?: string;
+  inheritProjectContext?: boolean;
+  inheritSkills?: boolean;
+  triggers?: string[];
+  useWhen?: string[];
+  avoidWhen?: string[];
+
+  // NEW (Phase 1+): capability-based routing
+  capabilities?: string[]; // capabilities this agent provides
+  consumes?: string[];     // dependencies (inputs needed)
+  produces?: string[];     // dependencies (outputs produced)
+  dependsOn?: string[];    // agents this agent depends on
+  source?: AgentSource;    // "builtin" | "filesystem"
+}
+
+/**
+ * Simple routing decision
+ */
+export interface RoutingDecision {
+  agentType: string;
+  reason: string;
+}
+
+/**
+ * Route result — single agent
+ */
+export interface RouteResult {
+  success: boolean;
+  error?: string;
+  agentId?: string;
+  agentType?: string;
+  reason?: string;
+  details?: Record<string, any>;
+}
+
+/**
+ * Plan result — multi-agent workflow
+ */
+export interface PlanResult {
+  success: boolean;
+  error?: string;
+  agents?: string[];     // names of agents to execute
+  steps?: string[];      // executed step descriptions
+  results?: Record<string, any>; // results keyed by agent name
+}