@deeflectcom/smart-spawn 1.0.0

package/index.ts

@@ -0,0 +1,655 @@
+import { ApiClient } from "./src/api-client.ts";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+
+const CATEGORY_KEYWORDS: Record<string, string[]> = {
+  coding: [
+    "code", "coding", "program", "debug", "fix", "implement", "refactor",
+    "typescript", "python", "javascript", "rust", "api", "function", "test", "bug",
+  ],
+  reasoning: [
+    "reason", "reasoning", "analysis", "think", "logic",
+    "math", "prove", "evaluate", "strategy", "plan", "deduce", "infer",
+  ],
+  creative: [
+    "creative", "write", "story", "poem", "essay", "blog", "content",
+    "marketing", "brainstorm", "idea", "narrative", "fiction",
+  ],
+  research: [
+    "research", "search", "find", "investigate", "summarize",
+    "report", "literature", "paper", "study",
+    "cause", "explain", "history", "compare", "overview", "background", "origin",
+  ],
+  "fast-cheap": [
+    "quick", "fast", "simple", "brief", "classify", "label", "tag",
+    "extract", "parse", "format", "convert",
+    "add", "sum", "subtract", "multiply", "divide", "calculate",
+  ],
+  vision: [
+    "image", "picture", "photo", "screenshot", "diagram", "visual", "ocr",
+    "analyze", "look", "see", "describe", "identify", "detect", "recognize",
+  ],
+};
+
+function classifyTask(text: string): string {
+  const lower = (text || "").toLowerCase();
+  let best = "general";
+  let bestScore = 0;
+  for (const [category, keywords] of Object.entries(CATEGORY_KEYWORDS)) {
+    const score = keywords.filter((kw) => lower.includes(kw)).length;
+    if (score > bestScore) {
+      bestScore = score;
+      best = category;
+    }
+  }
+  return best;
+}
+
+/**
+ * Build set of providers the user has direct keys for.
+ * Auth profile IDs follow the pattern: "{provider}:{identifier}"
+ * e.g. "anthropic:default", "openai:oauth", "google-gemini:api_key"
+ */
+function detectDirectProviders(api: any): Set<string> {
+  const profiles = api.config?.auth?.profiles ?? {};
+  const direct = new Set<string>();
+  for (const [profileId, profile] of Object.entries(profiles) as [string, any][]) {
+    const provider = profile?.provider ?? profileId.split(":")[0];
+    if (provider && provider !== "openrouter") {
+      direct.add(provider);
+    }
+  }
+  // Also check models.providers for custom provider configs
+  const providers = api.config?.models?.providers ?? {};
+  for (const key of Object.keys(providers)) {
+    if (key !== "openrouter") direct.add(key);
+  }
+  return direct;
+}
+
+/**
+ * Map provider names from auth profiles to OpenRouter model ID prefixes.
+ * Auth uses "anthropic", "google-gemini", etc. Model IDs use "anthropic/", "google/", etc.
+ */
+const PROVIDER_TO_MODEL_PREFIX: Record<string, string> = {
+  anthropic: "anthropic",
+  openai: "openai",
+  "google-gemini": "google",
+  "google-gemini-cli": "google",
+  "aws-bedrock": "amazon",
+};
+
+/**
+ * Route model to cheapest available provider.
+ * If user has a direct key for the model's provider, skip OpenRouter.
+ */
+function routeModel(modelId: string, directProviders: Set<string>): string {
+  if (modelId.startsWith("openrouter/")) modelId = modelId.replace(/^openrouter\//, "");
+  const provider = modelId.split("/")[0]; // e.g. "anthropic" from "anthropic/claude-opus-4-6"
+
+  // Check if any direct provider matches this model's provider
+  for (const [authProvider, modelPrefix] of Object.entries(PROVIDER_TO_MODEL_PREFIX)) {
+    if (modelPrefix === provider && directProviders.has(authProvider)) {
+      return modelId; // Use direct — no openrouter/ prefix
+    }
+  }
+
+  // Also check if provider name directly matches (e.g. "anthropic" in both)
+  if (directProviders.has(provider)) {
+    return modelId;
+  }
+
+  // Fallback to OpenRouter
+  return `openrouter/${modelId}`;
+}
+
+/** Get or create a persistent instance ID for community telemetry */
+function getInstanceId(pluginDir: string): string {
+  // Try multiple paths: explicit dir, home-based fallback
+  const candidates = [
+    join(pluginDir, ".instance-id"),
+    join(process.env.HOME ?? "/tmp", ".smart-spawn-instance-id"),
+  ];
+
+  for (const idPath of candidates) {
+    try {
+      if (existsSync(idPath)) {
+        return readFileSync(idPath, "utf-8").trim();
+      }
+    } catch { /* ignore */ }
+  }
+
+  const id = randomUUID();
+  for (const idPath of candidates) {
+    try {
+      writeFileSync(idPath, id, "utf-8");
+      return id;
+    } catch { /* ignore, try next */ }
+  }
+  return id;
+}
+
+export default function (api: any) {
+  const pluginConfig =
+    api.config?.plugins?.entries?.["smart-spawn"]?.config ?? {};
+
+  const apiUrl = pluginConfig.apiUrl ?? "https://ss.deeflect.com";
+  const defaultBudget = pluginConfig.defaultBudget ?? "medium";
+  const defaultMode = pluginConfig.defaultMode ?? "single";
+  const collectiveCount = pluginConfig.collectiveCount ?? 3;
+  const telemetryOptIn = pluginConfig.telemetryOptIn ?? false;
+  const communityUrl = pluginConfig.communityUrl ?? apiUrl;
+
+  // Detect which providers the user has direct access to
+  const directProviders = detectDirectProviders(api);
+  const hasOpenRouter = Object.keys(api.config?.auth?.profiles ?? {})
+    .some((id: string) => id.startsWith("openrouter:"));
+
+  if (directProviders.size > 0) {
+    console.log(`[smart-spawn] Direct providers detected: ${[...directProviders].join(", ")}`);
+  }
+  if (hasOpenRouter) {
+    console.log(`[smart-spawn] OpenRouter auth detected — will use for models without direct provider`);
+  }
+  if (!hasOpenRouter && directProviders.size === 0) {
+    console.warn(`[smart-spawn] WARNING: No auth profiles detected! Models will fail to spawn.`);
+    console.warn(`[smart-spawn] Run: openclaw auth add openrouter   (or add a direct provider key)`);
+  }
+
+  const RAW_FALLBACKS: Record<string, string> = {
+    coding: "anthropic/claude-opus-4-6",
+    reasoning: "anthropic/claude-opus-4-6",
+    creative: "anthropic/claude-opus-4-6",
+    research: "google/gemini-2.5-flash",
+    "fast-cheap": "moonshotai/kimi-k2.5",
+    general: "anthropic/claude-sonnet-4",
+    vision: "anthropic/claude-sonnet-4",
+  };
+  function getFallback(category: string): string {
+    return routeModel(RAW_FALLBACKS[category] ?? RAW_FALLBACKS.general, directProviders);
+  }
+
+  const client = new ApiClient(apiUrl, communityUrl);
+
+  // Instance ID for community telemetry (lazy-loaded)
+  let instanceId: string | null = null;
+  function getOrCreateInstanceId(): string {
+    if (!instanceId) {
+      instanceId = getInstanceId(typeof __dirname !== 'undefined' ? __dirname : new URL('.', import.meta.url).pathname);
+    }
+    return instanceId;
+  }
+
+  /** Build a fallback-to-single-mode response when the API is unavailable */
+  function buildFallbackResponse(category: string, budget: string, enrichedTask: string, context?: string) {
+    const modelId = getFallback(category);
+    client.logSpawn({ model: modelId, category, budget, mode: "single", role: "primary", source: "fallback", context });
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          action: "spawn",
+          model: modelId,
+          task: enrichedTask,
+          category,
+          budget,
+          reason: "API unavailable, falling back to single mode",
+          source: "fallback",
+        }),
+      }],
+    };
+  }
+
+  api.registerTool({
+    name: "smart_spawn",
+    description: `Intelligently spawn sub-agent(s) for a task. Automatically selects the best model(s) based on task type, budget, and strategy. Use this instead of sessions_spawn when you want optimal model selection. Do NOT use this when the user explicitly requests a specific agent or model.`,
+    parameters: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description: "The task to delegate. Be specific.",
+        },
+        category: {
+          type: "string",
+          enum: [
+            "coding", "reasoning", "creative", "research",
+            "general", "fast-cheap", "vision", "auto",
+          ],
+          description: "Task category. 'auto' (default) lets the system classify it.",
+        },
+        mode: {
+          type: "string",
+          enum: ["single", "collective", "cascade", "plan", "swarm"],
+          description: "Spawning strategy. 'single' (default): one optimal model. 'collective': N diverse models + merge. 'cascade': cheap first, escalate if needed. 'plan': decompose multi-step task sequentially. 'swarm': decompose into a dependency DAG, maximize parallelism.",
+        },
+        budget: {
+          type: "string",
+          enum: ["low", "medium", "high", "any"],
+          description: "Budget tier for model selection.",
+        },
+        collectiveCount: {
+          type: "number",
+          description: "Number of models for collective mode (default: 3).",
+        },
+        label: {
+          type: "string",
+          description: "Optional label for the spawned session.",
+        },
+        context: {
+          type: "string",
+          description: "Project context tags, comma-separated (e.g. 'typescript,nextjs,supabase'). Improves model selection for specific tech stacks.",
+        },
+        persona: {
+          type: "string",
+          description: "Role persona for the sub-agent (e.g. 'frontend-engineer', 'security-engineer', 'copywriter', 'data-analyst'). See SKILL.md for full list.",
+        },
+        stack: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tech stack blocks to include in role instructions (e.g. ['react', 'nextjs', 'supabase', 'stripe']). See SKILL.md for available blocks.",
+        },
+        domain: {
+          type: "string",
+          description: "Industry/domain block (e.g. 'saas', 'fintech', 'healthcare', 'crypto', 'ecommerce'). Adds domain-specific expertise.",
+        },
+        format: {
+          type: "string",
+          description: "Output format block (e.g. 'full-implementation', 'review', 'comparison', 'documentation', 'pitch-deck'). Shapes how the sub-agent structures its response.",
+        },
+        guardrails: {
+          type: "array",
+          items: { type: "string" },
+          description: "Quality guardrails (e.g. ['code', 'security', 'production']). Adds constraints to prevent common mistakes.",
+        },
+      },
+      required: ["task"],
+    },
+    async execute(_callId: string, input: any) {
+      const task = input.task || "";
+      const category =
+        input.category === "auto" || !input.category
+          ? classifyTask(task)
+          : input.category;
+      const budget = input.budget ?? defaultBudget;
+      const mode = input.mode ?? defaultMode;
+      const context = input.context || undefined;
+
+      // Compose role-enriched task if agent specified blocks
+      const enrichedTask = await client.composeTaskPrompt({
+        task,
+        persona: input.persona,
+        stack: input.stack,
+        domain: input.domain,
+        format: input.format,
+        guardrails: input.guardrails,
+      }) ?? task;
+
+      // --- SINGLE MODE ---
+      if (mode === "single") {
+        let modelId: string;
+        let reason: string;
+        let source = "api";
+
+        try {
+          const pick = await client.pick(category, budget, undefined, context);
+          modelId = routeModel(pick.data.id, directProviders);
+          reason = pick.data.reason;
+        } catch {
+          modelId = getFallback(category);
+          reason = `API unavailable, using fallback for ${category}`;
+          source = "fallback";
+        }
+
+        const label = input.label ?? `smart-spawn: ${category} (${modelId.split("/").pop()})`;
+
+        client.logSpawn({ model: modelId, category, budget, mode, role: "primary", source, context });
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              action: "spawn",
+              model: modelId,
+              task: enrichedTask,
+              category,
+              budget,
+              reason,
+              source,
+              label,
+            }),
+          }],
+        };
+      }
+
+      // --- COLLECTIVE MODE ---
+      if (mode === "collective") {
+        const count = input.collectiveCount ?? collectiveCount;
+        try {
+          const rec = await client.recommend({ task: category, budget, count, context });
+          const models = rec.data.map((r) => ({
+            id: routeModel(r.model.id, directProviders),
+            reason: r.reason,
+          }));
+          for (const m of models) {
+            client.logSpawn({ model: m.id, category, budget, mode, role: "collective_worker", source: "api", context });
+          }
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                action: "collective",
+                models: models.map((m, i) => ({
+                  ...m,
+                  label: `smart-spawn-collective-${i + 1}: ${category} (${m.id.split("/").pop()})`,
+                })),
+                task: enrichedTask,
+                category,
+                budget,
+                count,
+                mergeLabel: `smart-spawn-merge: ${category}`,
+              }),
+            }],
+          };
+        } catch {
+          return buildFallbackResponse(category, budget, enrichedTask, context);
+        }
+      }
+
+      // --- CASCADE MODE ---
+      if (mode === "cascade") {
+        try {
+          const cheapPick = await client.pick(category, "low", undefined, context);
+          const cheapId = cheapPick.data.id;
+          // Exclude the cheap model so premium is guaranteed different
+          const premiumPick = await client.pick(category, "high", [cheapId], context);
+          const routedCheap = routeModel(cheapId, directProviders);
+          const routedPremium = routeModel(premiumPick.data.id, directProviders);
+          client.logSpawn({ model: routedCheap, category, budget: "low", mode, role: "cascade_cheap", source: "api", context });
+          client.logSpawn({ model: routedPremium, category, budget: "high", mode, role: "cascade_premium", source: "api", context });
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                action: "cascade",
+                cheapModel: routedCheap,
+                cheapScore: cheapPick.data.score,
+                cheapPricing: cheapPick.data.pricing,
+                premiumModel: routedPremium,
+                premiumScore: premiumPick.data.score,
+                premiumPricing: premiumPick.data.pricing,
+                cheapLabel: `smart-spawn-cascade-cheap: ${category} (${cheapId.split("/").pop()})`,
+                premiumLabel: `smart-spawn-cascade-premium: ${category} (${premiumPick.data.id.split("/").pop()})`,
+                task: enrichedTask,
+                category,
+                escalationHint: "If the cheap model's response is incomplete, incorrect, or low quality, escalate to the premium model.",
+              }),
+            }],
+          };
+        } catch {
+          return buildFallbackResponse(category, budget, enrichedTask, context);
+        }
+      }
+
+      // --- PLAN MODE ---
+      if (mode === "plan") {
+        try {
+          const decomposition = await client.decompose({ task, budget, context });
+
+          // If task can't be decomposed, fall back to single mode
+          if (!decomposition.decomposed || !decomposition.steps?.length) {
+            let modelId: string;
+            let reason: string;
+            let source = "api";
+
+            try {
+              const pick = await client.pick(category, budget, undefined, context);
+              modelId = routeModel(pick.data.id, directProviders);
+              reason = pick.data.reason;
+            } catch {
+              modelId = getFallback(category);
+              reason = `API unavailable, using fallback for ${category}`;
+              source = "fallback";
+            }
+
+            const lbl = input.label ?? `smart-spawn: ${category} (${modelId.split("/").pop()})`;
+            client.logSpawn({ model: modelId, category, budget, mode: "single", role: "primary", source, context });
+
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  action: "spawn",
+                  model: modelId,
+                  task: enrichedTask,
+                  category,
+                  budget,
+                  reason: `Task not decomposable — ${reason}`,
+                  source,
+                  label: lbl,
+                }),
+              }],
+            };
+          }
+
+          // Build plan response with routed models
+          const subtasks = decomposition.steps.map((step) => {
+            const modelId = step.model
+              ? routeModel(step.model.id, directProviders)
+              : getFallback(step.category);
+
+            client.logSpawn({
+              model: modelId,
+              category: step.category,
+              budget: step.budget,
+              mode: "plan",
+              role: `plan_step_${step.step}`,
+              source: step.model ? "api" : "fallback",
+              context,
+            });
+
+            // Plan mode steps use task as-is — blocks are top-level only
+            const stepTask = step.task;
+
+            return {
+              step: step.step,
+              task: stepTask,
+              category: step.category,
+              model: modelId,
+              budget: step.budget,
+              reason: step.reason,
+              label: `smart-spawn-plan-${step.step}: ${step.category} (${modelId.split("/").pop()})`,
+            };
+          });
+
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                action: "plan",
+                subtasks,
+                originalTask: task,
+                totalSteps: subtasks.length,
+                executionHint: "Execute steps sequentially. Pass each step's output as context to the next.",
+              }),
+            }],
+          };
+        } catch {
+          return buildFallbackResponse(category, budget, enrichedTask, context);
+        }
+      }
+
+      // --- SWARM MODE ---
+      if (mode === "swarm") {
+        try {
+          const swarmResult = await client.swarm({ task, budget, context });
+
+          // If task can't be decomposed, fall back to single mode
+          if (!swarmResult.decomposed || !swarmResult.dag?.tasks?.length) {
+            let modelId: string;
+            let reason: string;
+            let source = "api";
+
+            try {
+              const pick = await client.pick(category, budget, undefined, context);
+              modelId = routeModel(pick.data.id, directProviders);
+              reason = pick.data.reason;
+            } catch {
+              modelId = getFallback(category);
+              reason = `API unavailable, using fallback for ${category}`;
+              source = "fallback";
+            }
+
+            const lbl = input.label ?? `smart-spawn: ${category} (${modelId.split("/").pop()})`;
+            client.logSpawn({ model: modelId, category, budget, mode: "single", role: "primary", source, context });
+
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  action: "spawn",
+                  model: modelId,
+                  task: enrichedTask,
+                  category,
+                  budget,
+                  reason: `Task not decomposable — ${reason}`,
+                  source,
+                  label: lbl,
+                }),
+              }],
+            };
+          }
+
+          // Build swarm response with routed models
+          const dag = swarmResult.dag;
+          const dagTasks = dag.tasks.map((t) => {
+            const modelId = t.model
+              ? routeModel(t.model.id, directProviders)
+              : getFallback(t.category);
+
+            client.logSpawn({
+              model: modelId,
+              category: t.category,
+              budget: t.budget,
+              mode: "swarm",
+              role: `swarm_${t.id}`,
+              source: t.model ? "api" : "fallback",
+              context,
+            });
+
+            return {
+              id: t.id,
+              task: t.description,
+              category: t.category,
+              model: modelId,
+              budget: t.budget,
+              persona: t.persona,
+              dependsOn: t.dependsOn,
+              wave: t.wave,
+              reason: t.reason,
+              label: `smart-spawn-${t.id}: ${t.category} (${modelId.split("/").pop()})`,
+            };
+          });
+
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                action: "swarm",
+                dag: {
+                  tasks: dagTasks,
+                  waves: dag.waves,
+                  edges: dag.edges,
+                  totalTasks: dag.totalTasks,
+                  totalWaves: dag.totalWaves,
+                  estimatedCost: dag.estimatedCost,
+                  ...(dag.warning ? { warning: dag.warning } : {}),
+                },
+                originalTask: task,
+                executionHint: "Execute wave-by-wave. Spawn all tasks within a wave in parallel. Pass outputs from completed tasks as context to their dependents in the next wave.",
+              }),
+            }],
+          };
+        } catch {
+          return buildFallbackResponse(category, budget, enrichedTask, context);
+        }
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            action: "error",
+            error: `Unknown mode: ${mode}`,
+            validModes: ["single", "collective", "cascade", "plan", "swarm"],
+          }),
+        }],
+        isError: true,
+      };
+    },
+  });
+
+  // --- FEEDBACK TOOL (learning loop) ---
+  api.registerTool({
+    name: "smart_spawn_feedback",
+    description: `Report quality feedback after a smart_spawn task completes. Rate the spawned model's output 1-5 (1=terrible, 5=excellent). This feedback improves future model recommendations for your specific use patterns.`,
+    parameters: {
+      type: "object",
+      properties: {
+        model: {
+          type: "string",
+          description: "The model ID that was spawned (from the smart_spawn response).",
+        },
+        category: {
+          type: "string",
+          enum: ["coding", "reasoning", "creative", "research", "general", "fast-cheap", "vision"],
+          description: "The task category.",
+        },
+        rating: {
+          type: "number",
+          description: "Quality rating 1-5. 1=terrible, 2=poor, 3=acceptable, 4=good, 5=excellent.",
+        },
+        context: {
+          type: "string",
+          description: "Project context tags from the original smart_spawn call (e.g. 'typescript,nextjs').",
+        },
+      },
+      required: ["model", "category", "rating"],
+    },
+    async execute(_callId: string, input: any) {
+      const model = input.model || "";
+      const category = input.category || "general";
+      const rating = Math.max(1, Math.min(5, Math.round(input.rating ?? 3)));
+      const context = input.context || undefined;
+
+      client.logOutcome({ model, category, rating, context });
+
+      // Community telemetry (opt-in)
+      if (telemetryOptIn) {
+        client.reportCommunity({
+          model,
+          category,
+          rating,
+          instanceId: getOrCreateInstanceId(),
+        });
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            recorded: true,
+            model,
+            category,
+            rating,
+            communityReported: telemetryOptIn,
+            message: rating >= 3
+              ? "Positive feedback recorded — this model will be favored for similar tasks."
+              : "Negative feedback recorded — this model will be deprioritized for similar tasks.",
+          }),
+        }],
+      };
+    },
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,40 @@
+{
+  "id": "smart-spawn",
+  "name": "Smart Spawn",
+  "description": "Intelligent sub-agent spawning with automatic model selection, role composition, and multi-agent orchestration.",
+  "version": "1.1.0",
+  "author": "deeflect",
+  "skills": ["skills/smart-spawn"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiUrl": {
+        "type": "string",
+        "description": "Model Intelligence API URL"
+      },
+      "defaultBudget": {
+        "type": "string",
+        "enum": ["low", "medium", "high", "any"],
+        "description": "Default budget tier"
+      },
+      "defaultMode": {
+        "type": "string",
+        "enum": ["single", "collective", "cascade", "plan", "swarm"],
+        "description": "Default spawn mode"
+      },
+      "collectiveCount": {
+        "type": "number",
+        "description": "Number of models for collective mode (2-5)"
+      },
+      "telemetryOptIn": {
+        "type": "boolean",
+        "description": "Opt-in to anonymous community telemetry"
+      },
+      "communityUrl": {
+        "type": "string",
+        "description": "Community API URL for shared telemetry"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@deeflectcom/smart-spawn",
+  "version": "1.0.0",
+  "description": "Intelligent sub-agent spawning with automatic model selection for OpenClaw",
+  "main": "index.ts",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "src/",
+    "skills/",
+    "openclaw.plugin.json"
+  ],
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "author": "deeflect",
+  "license": "MIT",
+  "keywords": ["openclaw", "plugin", "llm", "model-selection", "agent", "smart-spawn"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deeflect/smart-spawn.git",
+    "directory": "smart-spawn"
+  },
+  "homepage": "https://github.com/deeflect/smart-spawn#readme"
+}

package/skills/SKILL.md

@@ -0,0 +1,214 @@
+# Smart Spawn
+
+When delegating tasks to sub-agents, prefer `smart_spawn` over `sessions_spawn` unless:
+- The user explicitly requests a specific agent or model
+- You're doing a trivial task where you already know the right model
+
+## How It Works
+
+`smart_spawn` returns a **JSON response** with a recommended model and action. You MUST then call `sessions_spawn` yourself with the recommended model and task. The tool cannot spawn directly — it only recommends.
+
+## Handling Responses
+
+After calling `smart_spawn`, parse the JSON response and act on the `action` field:
+
+### action: "spawn" (single mode)
+
+The tool picked one model. Spawn it:
+
+```json
+{
+  "action": "spawn",
+  "model": "openrouter/anthropic/claude-opus-4-6",
+  "task": "...",
+  "category": "coding",
+  "budget": "medium",
+  "reason": "Best coding model at medium budget ($0-5/M) — score: 82",
+  "source": "api",
+  "label": "smart-spawn: coding (claude-opus-4-6)"
+}
+```
+
+**You do:** Call `sessions_spawn` with the `model`, `task`, and `label` from the response.
+
+### action: "collective"
+
+The tool picked N diverse models. Spawn all of them on the same task, then merge:
+
+```json
+{
+  "action": "collective",
+  "models": [
+    { "id": "openrouter/anthropic/claude-opus-4-6", "reason": "...", "label": "smart-spawn-collective-1: coding (claude-opus-4-6)" },
+    { "id": "openrouter/google/gemini-2.5-pro", "reason": "...", "label": "smart-spawn-collective-2: coding (gemini-2.5-pro)" }
+  ],
+  "task": "...",
+  "category": "coding",
+  "budget": "medium",
+  "count": 2,
+  "mergeLabel": "smart-spawn-merge: coding"
+}
+```
+
+**You do:**
+1. Call `sessions_spawn` for each model using its `id`, the `task`, and its `label`, with `waitForCompletion: true`
+2. Collect all outputs
+3. Call `sessions_spawn` with a fast model, giving it all outputs to synthesize the best answer, using the `mergeLabel`
+
+### action: "cascade"
+
+The tool picked a cheap and premium model. Try cheap first, escalate if quality is insufficient:
+
+```json
+{
+  "action": "cascade",
+  "cheapModel": "openrouter/deepseek/deepseek-chat-v3-0324",
+  "cheapScore": 71,
+  "cheapPricing": { "prompt": 0.27, "completion": 1.1 },
+  "premiumModel": "openrouter/anthropic/claude-opus-4-6",
+  "premiumScore": 82,
+  "premiumPricing": { "prompt": 5, "completion": 25 },
+  "cheapLabel": "smart-spawn-cascade-cheap: coding (deepseek-chat-v3-0324)",
+  "premiumLabel": "smart-spawn-cascade-premium: coding (claude-opus-4-6)",
+  "task": "...",
+  "category": "coding",
+  "escalationHint": "If the cheap model's response is incomplete, incorrect, or low quality, escalate to the premium model."
+}
+```
+
+**You do:**
+1. Call `sessions_spawn` with `cheapModel`, the `task`, and `cheapLabel`, with `waitForCompletion: true`
+2. Evaluate the output quality — escalate if you see:
+   - Incomplete or partial answers
+   - Syntax errors or incorrect code
+   - Vague or generic responses that don't address the task
+   - Missing key requirements
+3. If good enough: use that result, done (saved money!)
+4. If not good enough: call `sessions_spawn` with `premiumModel` and `premiumLabel`, include the cheap output as context for improvement
+
+### action: "swarm"
+
+The tool decomposed a complex task into a dependency DAG with parallel waves:
+
+```json
+{
+  "action": "swarm",
+  "dag": {
+    "tasks": [
+      { "id": "swarm-1", "task": "Design database schema", "category": "coding", "model": "openrouter/anthropic/claude-sonnet-4", "budget": "medium", "persona": "database-architect", "dependsOn": [], "wave": 0, "reason": "...", "label": "smart-spawn-swarm-1: coding (claude-sonnet-4)" },
+      { "id": "swarm-2", "task": "Build REST API", "category": "coding", "model": "openrouter/anthropic/claude-sonnet-4", "budget": "medium", "persona": "backend-engineer", "dependsOn": ["swarm-1"], "wave": 1, "reason": "...", "label": "smart-spawn-swarm-2: coding (claude-sonnet-4)" },
+      { "id": "swarm-3", "task": "Create React frontend", "category": "coding", "model": "openrouter/anthropic/claude-sonnet-4", "budget": "medium", "persona": "frontend-engineer", "dependsOn": ["swarm-1"], "wave": 1, "reason": "...", "label": "smart-spawn-swarm-3: coding (claude-sonnet-4)" },
+      { "id": "swarm-4", "task": "Write integration tests", "category": "coding", "model": "openrouter/deepseek/deepseek-chat-v3-0324", "budget": "low", "persona": "software-engineer", "dependsOn": ["swarm-2", "swarm-3"], "wave": 2, "reason": "...", "label": "smart-spawn-swarm-4: coding (deepseek-chat-v3-0324)" }
+    ],
+    "waves": [
+      { "wave": 0, "taskIds": ["swarm-1"], "description": "1 task" },
+      { "wave": 1, "taskIds": ["swarm-2", "swarm-3"], "description": "2 parallel tasks" },
+      { "wave": 2, "taskIds": ["swarm-4"], "description": "1 task" }
+    ],
+    "edges": [
+      { "from": "swarm-1", "to": "swarm-2", "type": "phase" },
+      { "from": "swarm-1", "to": "swarm-3", "type": "phase" },
+      { "from": "swarm-2", "to": "swarm-4", "type": "phase" },
+      { "from": "swarm-3", "to": "swarm-4", "type": "phase" }
+    ],
+    "totalTasks": 4,
+    "totalWaves": 3,
+    "estimatedCost": { "low": 0.02, "high": 0.18 }
+  },
+  "originalTask": "...",
+  "executionHint": "Execute wave-by-wave. Spawn all tasks within a wave in parallel. Pass outputs from completed tasks as context to their dependents in the next wave."
+}
+```
+
+**You do:**
+1. Execute **wave by wave** — process all waves in order (wave 0, then wave 1, etc.)
+2. Within each wave, spawn **all tasks in parallel** — call `sessions_spawn` for each task using its `model`, `task`, and `label`, with `waitForCompletion: true`
+3. When a task has `dependsOn`, include the outputs from those dependency tasks as context in the task prompt
+4. After each wave completes, collect outputs before moving to the next wave
+5. After all waves complete, synthesize the results if needed
+6. Call `smart_spawn_feedback` for each completed task to rate the model's output
+
+**Key differences from plan mode:**
+- Plan is sequential (step 1, then step 2, then step 3...)
+- Swarm maximizes parallelism — independent tasks run simultaneously
+- Each task has a `persona` for role-specific prompting
+- Tasks declare explicit `dependsOn` relationships
+
+### action: "plan"
+
+The tool decomposed a multi-step task into subtasks, each with its own optimal model:
+
+```json
+{
+  "action": "plan",
+  "subtasks": [
+    { "step": 1, "task": "Set up database schema", "category": "coding", "model": "openrouter/anthropic/claude-sonnet-4", "budget": "medium", "reason": "Best coding model at medium budget ($0-5/M) — score: 78", "label": "smart-spawn-plan-1: coding (claude-sonnet-4)" },
+    { "step": 2, "task": "Implement REST API", "category": "coding", "model": "openrouter/anthropic/claude-sonnet-4", "budget": "medium", "reason": "...", "label": "smart-spawn-plan-2: coding (claude-sonnet-4)" },
+    { "step": 3, "task": "Write unit tests", "category": "coding", "model": "openrouter/deepseek/deepseek-chat-v3-0324", "budget": "low", "reason": "...", "label": "smart-spawn-plan-3: coding (deepseek-chat-v3-0324)" }
+  ],
+  "originalTask": "1. Set up database schema\n2. Implement REST API\n3. Write unit tests",
+  "totalSteps": 3,
+  "executionHint": "Execute steps sequentially. Pass each step's output as context to the next."
+}
+```
+
+**You do:**
+1. Execute steps **sequentially** — call `sessions_spawn` for step 1, wait for completion
+2. Pass each step's output as context to the next step (include the previous result in the task prompt)
+3. After each step completes, call `smart_spawn_feedback` to rate that step's model
+4. If a step fails, you may retry with the same model or skip to the next step with a note
+
+**When plan mode is useful:**
+- The user provides a numbered list or multi-step instructions
+- The task naturally decomposes into sequential phases (e.g. "design, implement, test")
+- Different steps benefit from different model strengths (e.g. reasoning for architecture, coding for implementation)
+
+## When to Use Each Mode
+
+- **single** (default) — most tasks. Fast, one model.
+- **collective** — important decisions, creative work, or when diverse perspectives help. Costs 3-4x more.
+- **cascade** — cost-sensitive tasks where a cheap model might suffice. Saves money when cheap model is good enough.
+- **plan** — structured multi-step tasks that must run sequentially. Decomposes into subtasks, picks the best model for each step.
+- **swarm** — complex projects with parallelizable subtasks. Builds a dependency DAG, assigns personas, runs independent tasks simultaneously. Best for multi-component projects (e.g. "build API + frontend + tests + deploy").
+
+## Examples
+
+```
+smart_spawn(task: "Write a Python function to merge two sorted arrays")
+smart_spawn(task: "Analyze this architecture", category: "reasoning", budget: "high")
+smart_spawn(task: "Write a product launch email", mode: "collective", category: "creative")
+smart_spawn(task: "Convert this JSON to YAML", mode: "cascade")
+smart_spawn(task: "1. Design the database schema\n2. Implement the API endpoints\n3. Write integration tests", mode: "plan")
+smart_spawn(task: "1. Design database schema\n2. Build REST API\n3. Create React frontend\n4. Write integration tests\n5. Deploy to AWS", mode: "swarm", context: "typescript,nextjs,postgres")
+```
+
+## Feedback (Learning Loop)
+
+After receiving a spawned agent's output, you SHOULD call `smart_spawn_feedback` to rate its quality. This trains the system to pick better models for your tasks over time.
+
+```
+smart_spawn_feedback(model: "anthropic/claude-opus-4-6", category: "coding", rating: 5)
+```
+
+**Rating scale:**
+- **5** — Excellent. Fully solved the task, high quality.
+- **4** — Good. Completed the task with minor issues.
+- **3** — Acceptable. Got the job done but not great.
+- **2** — Poor. Missed key requirements or had significant issues.
+- **1** — Terrible. Failed the task or produced unusable output.
+
+**When to rate:**
+- Always rate after single mode spawns
+- In cascade mode: rate the cheap model's output (this determines if escalation was needed)
+- In collective mode: rate the final merged output
+- Use the `model` and `category` from the original `smart_spawn` response
+
+After enough feedback (3+ ratings per model+category), the system starts blending your personal scores into recommendations. Models you rate highly get boosted; models you rate poorly get deprioritized.
+
+## Tips
+
+- Let `category: "auto"` do its job — it's right most of the time
+- Use `collective` sparingly — it costs 3-4x more
+- If the API is down, the tool falls back to hardcoded defaults (still works)
+- Model IDs may or may not have `openrouter/` prefix depending on user's auth — pass them as-is to `sessions_spawn`
+- Always provide feedback — it makes future picks better for your specific workflow

package/skills/smart-spawn/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: smart-spawn
+description: "Intelligent sub-agent spawning with automatic model selection and role composition. Use instead of sessions_spawn for optimal model routing."
+---
+
+# Smart Spawn
+
+Use `smart_spawn` to delegate tasks to sub-agents. It picks the best model and can inject expert role instructions that make cheap models perform like specialists.
+
+## Flow
+
+1. Analyze the task → pick role blocks if relevant
+2. Call `smart_spawn` → get JSON with model + enriched task
+3. Call `sessions_spawn` with the returned values
+
+## Modes
+
+| Mode | When to use |
+|------|------------|
+| `single` | Default. One optimal model. |
+| `collective` | Need diverse perspectives. Spawns N models, you merge results. |
+| `cascade` | Cost-sensitive. Cheap model first, escalate to premium if quality is poor. |
+| `plan` | Multi-step sequential tasks. Format task as numbered list. |
+| `swarm` | Complex tasks with parallel subtasks. API builds a dependency DAG. |
+
+## Role Blocks
+
+Analyze the task and specify blocks that match. **Only include what's clearly relevant — omit if unsure.** Guardrails auto-apply based on persona when not specified.
+
+### persona — who the sub-agent is
+
+**Engineering:** `software-engineer` `frontend-engineer` `backend-engineer` `fullstack-engineer` `devops-engineer` `data-engineer` `mobile-engineer` `systems-engineer` `security-engineer` `ml-engineer` `performance-engineer`
+
+**Architecture:** `architect` `api-designer` `database-architect`
+
+**Analysis:** `analyst` `data-analyst` `market-analyst` `financial-analyst`
+
+**Problem Solving:** `problem-solver` `debugger` `mathematician`
+
+**Content:** `writer` `technical-writer` `copywriter` `editor` `social-media`
+
+**Product/Business:** `product-manager` `strategist` `ux-researcher` `project-manager`
+
+**Design:** `ui-designer` `brand-designer`
+
+**Other:** `sysadmin` `teacher` `legal-analyst` `assistant`
+
+### stack — tech expertise (array, max 4)
+
+**Frontend:** `react` `nextjs` `vue` `svelte` `angular` `tailwind` `shadcn` `css` `animation` `threejs`
+
+**Languages:** `typescript` `python` `rust` `go` `java` `csharp` `php` `ruby` `elixir` `swift` `kotlin`
+
+**Backend:** `nodejs` `fastapi` `django` `flask` `react-native` `flutter`
+
+**Data:** `sql` `postgres` `mysql` `supabase` `prisma` `drizzle` `mongodb` `redis` `elasticsearch` `kafka` `rabbitmq`
+
+**APIs:** `graphql` `rest` `grpc` `websocket` `auth` `stripe` `payment-general`
+
+**DevOps:** `docker` `kubernetes` `cicd` `terraform` `aws` `gcp` `nginx` `caddy` `monitoring`
+
+**AI/ML:** `llm` `rag` `langchain` `fine-tuning` `pytorch` `pandas`
+
+**Web3:** `solidity` `web3-frontend`
+
+**Platforms:** `vercel` `railway` `cloudflare` `firebase` `convex`
+
+**Other:** `bash` `powershell` `markdown` `astro` `json` `yaml` `regex` `email` `a11y` `seo` `performance` `i18n` `git` `testing` `playwright`
+
+### domain — industry (one)
+
+`fintech` `ecommerce` `saas` `marketplace` `gaming` `crypto` `healthcare` `education` `media` `iot` `logistics` `real-estate` `social-platform` `legal` `developer-tools`
+
+### format — output shape (one)
+
+`full-implementation` `fix-debug` `refactor` `explain` `review` `comparison` `planning` `documentation` `copywriting` `social-post` `data-report` `migration` `pitch-deck` `project-proposal` `user-story` `email` `legal-doc`
+
+### guardrails — quality rules (array, auto-applied if omitted)
+
+`code` `research` `concise` `security` `production` `accuracy`
+
+## Acting on Results
+
+### `action: "spawn"` (single/fallback)
+```
+sessions_spawn(task: result.task, model: result.model, label: result.label)
+```
+
+### `action: "collective"`
+Spawn each model, wait for all, merge the best parts:
+```
+for model in result.models:
+  sessions_spawn(task: result.task, model: model.id, label: model.label)
+```
+
+### `action: "cascade"`
+1. Spawn `cheapModel` first
+2. Check quality via `sessions_history`
+3. Escalate to `premiumModel` if: incomplete, wrong, vague, or too short for the task
+4. Return whichever result is good
+
+### `action: "plan"`
+Execute steps sequentially, pass each output as context to the next.
+
+### `action: "swarm"`
+Execute wave-by-wave. Spawn all tasks in a wave in parallel. Pass outputs to dependents in the next wave.
+
+## Rules
+
+- **Always spawn after smart_spawn returns** — don't just report the recommendation
+- Use the exact `model` and `task` strings from the result
+- **Don't guess blocks** — if unsure, omit and the task goes raw
+- For plan mode, format tasks as numbered lists
+- After completion, consider calling `smart_spawn_feedback` with a 1-5 rating

package/src/api-client.ts

@@ -0,0 +1,280 @@
+export interface SwarmResponse {
+  decomposed: boolean;
+  reason?: string;
+  dag?: {
+    tasks: Array<{
+      id: string;
+      description: string;
+      category: string;
+      budget: string;
+      persona: string;
+      dependsOn: string[];
+      model: {
+        id: string;
+        name: string;
+        provider: string;
+        score: number;
+        pricing: { prompt: number; completion: number };
+      } | null;
+      reason: string;
+      wave: number;
+    }>;
+    waves: Array<{
+      wave: number;
+      taskIds: string[];
+      description: string;
+    }>;
+    edges: Array<{
+      from: string;
+      to: string;
+      type: string;
+    }>;
+    totalTasks: number;
+    totalWaves: number;
+    originalTask: string;
+    context: string | null;
+    estimatedCost: { low: number; high: number };
+    warning?: string;
+  };
+}
+
+export interface DecomposeResponse {
+  decomposed: boolean;
+  reason?: string;
+  totalSteps?: number;
+  originalTask?: string;
+  context?: string | null;
+  steps?: Array<{
+    step: number;
+    task: string;
+    category: string;
+    budget: string;
+    model: {
+      id: string;
+      name: string;
+      provider: string;
+      score: number;
+      pricing: { prompt: number; completion: number };
+    } | null;
+    reason: string;
+  }>;
+}
+
+export interface PickResponse {
+  data: {
+    id: string;
+    name: string;
+    provider: string;
+    score: number;
+    pricing: { prompt: number; completion: number };
+    reason: string;
+    contextBoost?: number;
+    contextTags?: string[];
+  };
+}
+
+export interface RecommendResponse {
+  data: Array<{
+    model: {
+      id: string;
+      name: string;
+      provider: string;
+      scores: Record<string, number>;
+      tier: string;
+    };
+    reason: string;
+    confidence: number;
+  }>;
+  meta: {
+    task: string;
+    budget: string;
+    candidatesConsidered: number;
+  };
+}
+
+export class ApiClient {
+  private baseUrl: string;
+  private communityUrl: string;
+
+  constructor(baseUrl: string, communityUrl?: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.communityUrl = (communityUrl ?? baseUrl).replace(/\/$/, "");
+  }
+
+  async pick(
+    task: string,
+    budget?: string,
+    exclude?: string[],
+    context?: string
+  ): Promise<PickResponse> {
+    const params = new URLSearchParams({ task });
+    if (budget) params.set("budget", budget);
+    if (exclude?.length) params.set("exclude", exclude.join(","));
+    if (context) params.set("context", context);
+
+    const res = await fetch(`${this.baseUrl}/pick?${params}`);
+    if (!res.ok) {
+      throw new Error(`API /pick failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json() as Promise<PickResponse>;
+  }
+
+  async recommend(opts: {
+    task: string;
+    budget?: string;
+    count?: number;
+    exclude?: string[];
+    require?: string[];
+    minContext?: number;
+    context?: string;
+  }): Promise<RecommendResponse> {
+    const params = new URLSearchParams({ task: opts.task });
+    if (opts.budget) params.set("budget", opts.budget);
+    if (opts.count) params.set("count", String(opts.count));
+    if (opts.exclude?.length) params.set("exclude", opts.exclude.join(","));
+    if (opts.require?.length) params.set("require", opts.require.join(","));
+    if (opts.minContext) params.set("minContext", String(opts.minContext));
+    if (opts.context) params.set("context", opts.context);
+
+    const res = await fetch(`${this.baseUrl}/recommend?${params}`);
+    if (!res.ok) {
+      throw new Error(
+        `API /recommend failed: ${res.status} ${res.statusText}`
+      );
+    }
+    return res.json() as Promise<RecommendResponse>;
+  }
+
+  async decompose(opts: {
+    task: string;
+    budget?: string;
+    context?: string;
+  }): Promise<DecomposeResponse> {
+    const res = await fetch(`${this.baseUrl}/decompose`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(opts),
+    });
+    if (!res.ok) {
+      throw new Error(`API /decompose failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json() as Promise<DecomposeResponse>;
+  }
+
+  async swarm(opts: {
+    task: string;
+    budget?: string;
+    context?: string;
+    maxParallel?: number;
+  }): Promise<SwarmResponse> {
+    const res = await fetch(`${this.baseUrl}/swarm`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(opts),
+    });
+    if (!res.ok) {
+      throw new Error(`API /swarm failed: ${res.status} ${res.statusText}`);
+    }
+    return res.json() as Promise<SwarmResponse>;
+  }
+
+  async health(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/status`);
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Compose a role-enriched task prompt via explicit block selection.
+   * Agent specifies what blocks it wants — API assembles them.
+   * Returns null if no blocks specified (task sent raw).
+   */
+  async composeTaskPrompt(opts: {
+    task: string;
+    persona?: string;
+    stack?: string[];
+    domain?: string;
+    format?: string;
+    guardrails?: string[];
+  }): Promise<string | null> {
+    // If agent didn't specify any blocks, skip — no role prompt
+    const hasBlocks = opts.persona || opts.stack?.length || opts.domain || opts.format || opts.guardrails?.length;
+    if (!hasBlocks) return null;
+
+    try {
+      const res = await fetch(`${this.baseUrl}/roles/compose`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(opts),
+      });
+      if (!res.ok) {
+        console.warn(`[smart-spawn] Role composition failed (${res.status}) — sending task without role blocks`);
+        return null;
+      }
+      const data = await res.json() as { hasRole: boolean; fullPrompt: string };
+      return data.hasRole ? data.fullPrompt : null;
+    } catch {
+      console.warn(`[smart-spawn] Role composition unavailable — sending task without role blocks`);
+      return null;
+    }
+  }
+
+  private logFailCount = 0;
+  private logFailWarned = false;
+
+  private handleLogError(endpoint: string, err: unknown): void {
+    this.logFailCount++;
+    if (!this.logFailWarned && this.logFailCount >= 3) {
+      console.warn(`[smart-spawn] Spawn logging unavailable (${endpoint}) — tracking data may be lost. Is the API running?`);
+      this.logFailWarned = true;
+    }
+  }
+
+  /** Fire-and-forget spawn log for cost tracking */
+  logSpawn(entry: {
+    model: string;
+    category: string;
+    budget: string;
+    mode: string;
+    role: string;
+    source: string;
+    context?: string;
+  }): void {
+    fetch(`${this.baseUrl}/spawn-log`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(entry),
+    }).catch((e) => this.handleLogError("/spawn-log", e));
+  }
+
+  /** Fire-and-forget outcome feedback for learning loop */
+  logOutcome(entry: {
+    model: string;
+    category: string;
+    rating: number;
+    context?: string;
+  }): void {
+    fetch(`${this.baseUrl}/spawn-log/outcome`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(entry),
+    }).catch((e) => this.handleLogError("/spawn-log/outcome", e));
+  }
+
+  /** Fire-and-forget community outcome report */
+  reportCommunity(entry: {
+    model: string;
+    category: string;
+    rating: number;
+    instanceId: string;
+  }): void {
+    fetch(`${this.communityUrl}/community/report`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(entry),
+    }).catch((e) => this.handleLogError("/community/report", e));
+  }
+}