iflow-mcp-deeflect-smart-spawn 0.1.0

package/src/smart-spawn-client.ts

@@ -0,0 +1,183 @@
+import type { Budget, RoleConfig } from "./types.ts";
+
+interface HttpOptions {
+  method?: string;
+  body?: unknown;
+}
+
+export class SmartSpawnClient {
+  constructor(private readonly baseUrl: string) {}
+
+  async pick(params: {
+    task: string;
+    budget?: Budget;
+    context?: string;
+    exclude?: string[];
+  }): Promise<{ modelId: string; reason: string }> {
+    const query = new URLSearchParams({
+      task: params.task,
+      budget: params.budget ?? "medium",
+    });
+    if (params.context) query.set("context", params.context);
+    if (params.exclude?.length) query.set("exclude", params.exclude.join(","));
+
+    const data = await this.getJson(`/pick?${query.toString()}`);
+    const modelId = data?.data?.id as string | undefined;
+    if (!modelId) throw new Error("Smart Spawn /pick did not return data.id");
+    return { modelId, reason: String(data?.data?.reason ?? "Picked by /pick") };
+  }
+
+  async recommend(params: {
+    task: string;
+    budget?: Budget;
+    count?: number;
+    context?: string;
+    exclude?: string[];
+  }): Promise<Array<{ modelId: string; reason: string }>> {
+    const query = new URLSearchParams({
+      task: params.task,
+      budget: params.budget ?? "medium",
+      count: String(params.count ?? 3),
+    });
+    if (params.context) query.set("context", params.context);
+    if (params.exclude?.length) query.set("exclude", params.exclude.join(","));
+
+    const data = await this.getJson(`/recommend?${query.toString()}`);
+    const items = Array.isArray(data?.data) ? data.data : [];
+    return items
+      .map((item: any) => ({
+        modelId: item?.model?.id as string | undefined,
+        reason: String(item?.reason ?? "Recommended by /recommend"),
+      }))
+      .filter((item: { modelId: string | undefined }) => Boolean(item.modelId)) as Array<{ modelId: string; reason: string }>;
+  }
+
+  async decompose(params: {
+    task: string;
+    budget?: Budget;
+    context?: string;
+  }): Promise<{
+    decomposed: boolean;
+    steps: Array<{ id: string; task: string; modelId: string; wave: number; dependsOn: string[]; reason: string }>;
+  }> {
+    const data = await this.postJson("/decompose", {
+      task: params.task,
+      budget: params.budget ?? "medium",
+      context: params.context,
+    });
+
+    if (!data?.decomposed) return { decomposed: false, steps: [] };
+    const steps = Array.isArray(data?.steps) ? data.steps : [];
+    return {
+      decomposed: true,
+      steps: steps
+        .map((step: any) => ({
+          id: `step-${step.step}`,
+          task: String(step.task ?? ""),
+          modelId: step?.model?.id as string | undefined,
+          wave: Number(step.step ?? 1) - 1,
+          dependsOn: Number(step.step ?? 1) > 1 ? [`step-${Number(step.step ?? 1) - 1}`] : [],
+          reason: String(step.reason ?? "Planned by /decompose"),
+        }))
+        .filter((s: { modelId: string | undefined }) => Boolean(s.modelId)) as Array<{
+          id: string;
+          task: string;
+          modelId: string;
+          wave: number;
+          dependsOn: string[];
+          reason: string;
+        }>,
+    };
+  }
+
+  async swarm(params: {
+    task: string;
+    budget?: Budget;
+    context?: string;
+    maxParallel?: number;
+  }): Promise<{
+    decomposed: boolean;
+    tasks: Array<{ id: string; task: string; modelId: string; wave: number; dependsOn: string[]; reason: string }>;
+  }> {
+    const data = await this.postJson("/swarm", {
+      task: params.task,
+      budget: params.budget ?? "medium",
+      context: params.context,
+      maxParallel: params.maxParallel ?? 5,
+    });
+
+    if (!data?.decomposed || !data?.dag) return { decomposed: false, tasks: [] };
+    const tasks = Array.isArray(data?.dag?.tasks) ? data.dag.tasks : [];
+    return {
+      decomposed: true,
+      tasks: tasks
+        .map((task: any) => ({
+          id: String(task.id ?? ""),
+          task: String(task.description ?? task.task ?? ""),
+          modelId: task?.model?.id as string | undefined,
+          wave: Number(task.wave ?? 0),
+          dependsOn: Array.isArray(task.dependsOn) ? task.dependsOn.map((d: unknown) => String(d)) : [],
+          reason: String(task.reason ?? "Planned by /swarm"),
+        }))
+        .filter((t: { modelId: string | undefined }) => Boolean(t.modelId)) as Array<{
+          id: string;
+          task: string;
+          modelId: string;
+          wave: number;
+          dependsOn: string[];
+          reason: string;
+        }>,
+    };
+  }
+
+  async composeRole(task: string, role?: RoleConfig): Promise<string> {
+    if (!role) return task;
+    const data = await this.postJson("/roles/compose", {
+      task,
+      ...role,
+    });
+    const prompt = data?.fullPrompt as string | undefined;
+    return prompt && prompt.trim().length > 0 ? prompt : task;
+  }
+
+  async health(): Promise<{ reachable: boolean; payload: unknown | null }> {
+    try {
+      const data = await this.getJson("/status");
+      return { reachable: true, payload: data };
+    } catch {
+      return { reachable: false, payload: null };
+    }
+  }
+
+  private async getJson(path: string): Promise<any> {
+    return this.request(path, { method: "GET" });
+  }
+
+  private async postJson(path: string, body: unknown): Promise<any> {
+    return this.request(path, { method: "POST", body });
+  }
+
+  private async request(path: string, options: HttpOptions): Promise<any> {
+    const url = `${this.baseUrl.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+    const res = await fetch(url, {
+      method: options.method ?? "GET",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+    });
+
+    const raw = await res.text();
+    const data = raw ? JSON.parse(raw) : null;
+
+    if (!res.ok) {
+      const message =
+        data?.error?.message ??
+        data?.message ??
+        `${options.method ?? "GET"} ${path} failed with status ${res.status}`;
+      throw new Error(String(message));
+    }
+
+    return data;
+  }
+}

package/src/storage.ts

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export class ArtifactStorage {
+  constructor(
+    public readonly homeDir: string,
+    public readonly artifactsDir: string
+  ) {}
+
+  async ensure(): Promise<void> {
+    await mkdir(this.homeDir, { recursive: true });
+    await mkdir(this.artifactsDir, { recursive: true });
+  }
+
+  async writeArtifact(
+    runId: string,
+    nodeId: string,
+    type: "raw" | "merged" | "plan" | "log",
+    content: string,
+    extension: "json" | "md" | "txt" = "json"
+  ): Promise<{ relativePath: string; bytes: number; sha256: string }> {
+    const relativePath = join("artifacts", runId, `${nodeId}.${extension}`);
+    const absolutePath = join(this.homeDir, relativePath);
+
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, "utf-8");
+
+    const bytes = Buffer.byteLength(content, "utf-8");
+    const sha256 = createHash("sha256").update(content).digest("hex");
+
+    // `type` is part of the function signature intentionally for schema clarity.
+    void type;
+
+    return { relativePath, bytes, sha256 };
+  }
+
+  async readArtifact(relativePath: string): Promise<string> {
+    const absolutePath = join(this.homeDir, relativePath);
+    const data = await readFile(absolutePath, "utf-8");
+    return data;
+  }
+}

package/src/tools.ts

@@ -0,0 +1,273 @@
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import type { RuntimeQueue } from "./runtime/queue.ts";
+import type { RunCreateInput, RunStatus } from "./types.ts";
+
+const TOOL_DEFS = [
+  {
+    name: "smartspawn_run_create",
+    description: "Create an async Smart Spawn run. This orchestrates sub-agents and returns a run_id immediately.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: { type: "string" },
+        mode: { type: "string", enum: ["single", "collective", "cascade", "plan", "swarm"] },
+        budget: { type: "string", enum: ["low", "medium", "high", "any"] },
+        context: { type: "string" },
+        collectiveCount: { type: "number" },
+        role: {
+          type: "object",
+          properties: {
+            persona: { type: "string" },
+            stack: { type: "array", items: { type: "string" } },
+            domain: { type: "string" },
+            format: { type: "string" },
+            guardrails: { type: "array", items: { type: "string" } },
+          },
+          additionalProperties: false,
+        },
+        merge: {
+          type: "object",
+          properties: {
+            style: { type: "string", enum: ["concise", "detailed", "decision"] },
+            model: { type: "string" },
+          },
+          additionalProperties: false,
+        },
+      },
+      required: ["task", "mode"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "smartspawn_run_status",
+    description: "Get status/progress for an async run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string" },
+      },
+      required: ["run_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "smartspawn_run_result",
+    description: "Get merged result for a run (raw outputs optional).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string" },
+        include_raw: { type: "boolean" },
+      },
+      required: ["run_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "smartspawn_run_cancel",
+    description: "Cancel a queued/running run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string" },
+      },
+      required: ["run_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "smartspawn_run_list",
+    description: "List recent runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["queued", "running", "completed", "failed", "canceled"] },
+        limit: { type: "number" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "smartspawn_artifact_get",
+    description: "Read a stored artifact by run and node id (use node_id='merged' for final answer).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        run_id: { type: "string" },
+        node_id: { type: "string" },
+      },
+      required: ["run_id", "node_id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "smartspawn_health",
+    description: "Health checks for OpenRouter config, Smart Spawn API, DB, storage, and worker.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+] as const;
+
+function asToolContent(payload: unknown): { content: Array<{ type: "text"; text: string }> } {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+  };
+}
+
+function toErrorContent(message: string) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify({ error: message }) }],
+    isError: true,
+  };
+}
+
+export function listToolNames(): string[] {
+  return TOOL_DEFS.map((tool) => tool.name);
+}
+
+export function registerToolHandlers(server: any, runtime: RuntimeQueue): void {
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOL_DEFS,
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+    const name = request?.params?.name as string | undefined;
+    const args = (request?.params?.arguments ?? {}) as Record<string, unknown>;
+
+    try {
+      if (name === "smartspawn_run_create") {
+        const task = String(args.task ?? "").trim();
+        const mode = String(args.mode ?? "").trim();
+        if (!task) return toErrorContent("task is required");
+        if (!["single", "collective", "cascade", "plan", "swarm"].includes(mode)) {
+          return toErrorContent("mode must be one of single|collective|cascade|plan|swarm");
+        }
+        const runInput: RunCreateInput = {
+          task,
+          mode: mode as RunCreateInput["mode"],
+          budget: args.budget as RunCreateInput["budget"],
+          context: typeof args.context === "string" ? args.context : undefined,
+          collectiveCount: typeof args.collectiveCount === "number" ? args.collectiveCount : undefined,
+          role: typeof args.role === "object" && args.role ? (args.role as RunCreateInput["role"]) : undefined,
+          merge: typeof args.merge === "object" && args.merge ? (args.merge as RunCreateInput["merge"]) : undefined,
+        };
+        const run = await runtime.createRun(runInput);
+        return asToolContent({
+          run_id: run.id,
+          status: run.status,
+          created_at: run.createdAt,
+        });
+      }
+
+      if (name === "smartspawn_run_status") {
+        const runId = String(args.run_id ?? "");
+        if (!runId) return toErrorContent("run_id is required");
+        const run = runtime.getRun(runId);
+        if (!run) return toErrorContent(`run not found: ${runId}`);
+        const progress = runtime.getProgress(runId);
+        return asToolContent({
+          run_id: runId,
+          status: run.status,
+          progress: {
+            total_nodes: progress.totalNodes,
+            done_nodes: progress.doneNodes,
+            running_nodes: progress.runningNodes,
+            failed_nodes: progress.failedNodes,
+            percent: progress.percent,
+          },
+          last_event: runtime.getLastEvent(runId),
+          updated_at: run.updatedAt,
+        });
+      }
+
+      if (name === "smartspawn_run_result") {
+        const runId = String(args.run_id ?? "");
+        if (!runId) return toErrorContent("run_id is required");
+        const includeRaw = Boolean(args.include_raw ?? false);
+        const result = await runtime.getResult(runId, includeRaw);
+        if (!result) return toErrorContent(`run not found: ${runId}`);
+        return asToolContent({
+          status: result.status,
+          merged_output: result.mergedOutput,
+          summary: result.summary,
+          artifacts: result.artifacts.map((a) => ({
+            node_id: a.nodeId,
+            path: a.path,
+            model: a.model,
+            status: a.status,
+            type: a.type,
+          })),
+          cost: {
+            prompt_tokens: result.cost.promptTokens,
+            completion_tokens: result.cost.completionTokens,
+            usd_estimate: result.cost.usdEstimate,
+          },
+          ...(includeRaw ? { raw_outputs: result.rawOutputs } : {}),
+        });
+      }
+
+      if (name === "smartspawn_run_cancel") {
+        const runId = String(args.run_id ?? "");
+        if (!runId) return toErrorContent("run_id is required");
+        const canceled = runtime.cancelRun(runId);
+        if (!canceled) return toErrorContent(`run not found: ${runId}`);
+        return asToolContent({
+          run_id: runId,
+          status: canceled.status,
+        });
+      }
+
+      if (name === "smartspawn_run_list") {
+        const status = (args.status ? String(args.status) : undefined) as RunStatus | undefined;
+        const limit = typeof args.limit === "number" ? args.limit : undefined;
+        const runs = runtime.listRuns(status, limit);
+        return asToolContent({
+          runs: runs.map((run) => ({
+            run_id: run.id,
+            task: run.task,
+            status: run.status,
+            created_at: run.createdAt,
+            updated_at: run.updatedAt,
+          })),
+        });
+      }
+
+      if (name === "smartspawn_artifact_get") {
+        const runId = String(args.run_id ?? "");
+        const nodeId = String(args.node_id ?? "");
+        if (!runId || !nodeId) return toErrorContent("run_id and node_id are required");
+        const artifact = await runtime.getArtifact(runId, nodeId);
+        if (!artifact) return toErrorContent(`artifact not found for run=${runId} node=${nodeId}`);
+        return asToolContent({
+          artifact_type: artifact.type,
+          content: artifact.content,
+          metadata: {
+            bytes: artifact.metadata.bytes,
+            sha256: artifact.metadata.sha256,
+            created_at: artifact.metadata.createdAt,
+            path: artifact.metadata.path,
+          },
+        });
+      }
+
+      if (name === "smartspawn_health") {
+        const health = await runtime.health();
+        return asToolContent({
+          openrouter_configured: health.openrouterConfigured,
+          smart_spawn_api_reachable: health.smartSpawnApiReachable,
+          db_writable: health.dbWritable,
+          artifact_storage_writable: health.artifactStorageWritable,
+          worker_alive: health.workerAlive,
+        });
+      }
+
+      return toErrorContent(`unknown tool: ${name ?? "(missing name)"}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return toErrorContent(message);
+    }
+  });
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+export type RunMode = "single" | "collective" | "cascade" | "plan" | "swarm";
+export type Budget = "low" | "medium" | "high" | "any";
+export type RunStatus = "queued" | "running" | "completed" | "failed" | "canceled";
+export type NodeStatus = "queued" | "running" | "completed" | "failed" | "canceled" | "skipped";
+export type NodeKind = "task" | "merge";
+
+export interface RoleConfig {
+  persona?: string;
+  stack?: string[];
+  domain?: string;
+  format?: string;
+  guardrails?: string[];
+}
+
+export interface MergeConfig {
+  style?: "concise" | "detailed" | "decision";
+  model?: string;
+}
+
+export interface RunCreateInput {
+  task: string;
+  mode: RunMode;
+  budget?: Budget;
+  context?: string;
+  collectiveCount?: number;
+  role?: RoleConfig;
+  merge?: MergeConfig;
+}
+
+export interface RunRecord {
+  id: string;
+  task: string;
+  mode: RunMode;
+  budget: Budget;
+  context: string | null;
+  paramsJson: string;
+  status: RunStatus;
+  error: string | null;
+  createdAt: string;
+  updatedAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
+}
+
+export interface NodeRecord {
+  id: string;
+  runId: string;
+  kind: NodeKind;
+  wave: number;
+  dependsOnJson: string;
+  task: string;
+  model: string;
+  prompt: string;
+  metaJson: string;
+  status: NodeStatus;
+  retryCount: number;
+  maxRetries: number;
+  error: string | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  tokensPrompt: number;
+  tokensCompletion: number;
+  costUsd: number;
+}
+
+export interface ArtifactRecord {
+  id: string;
+  runId: string;
+  nodeId: string;
+  type: "raw" | "merged" | "plan" | "log";
+  path: string;
+  bytes: number;
+  sha256: string;
+  createdAt: string;
+}
+
+export interface PlannedNode {
+  id: string;
+  kind: NodeKind;
+  wave: number;
+  dependsOn: string[];
+  task: string;
+  model: string;
+  prompt: string;
+  meta?: Record<string, unknown>;
+  maxRetries?: number;
+}
+
+export interface PlannedRun {
+  nodes: PlannedNode[];
+  plannerSummary: string;
+}
+
+export interface OpenRouterExecutionResult {
+  text: string;
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
+export interface RunProgress {
+  totalNodes: number;
+  doneNodes: number;
+  runningNodes: number;
+  failedNodes: number;
+  percent: number;
+}

package/tests/clients.test.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "bun:test";
+import { buildOpenRouterHeaders } from "../src/openrouter-client.ts";
+
+test("buildOpenRouterHeaders includes bearer token", () => {
+  const headers = buildOpenRouterHeaders("test-key");
+  expect(headers.Authorization).toBe("Bearer test-key");
+});

package/tests/db.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test";
+import { McpStore } from "../src/db.ts";
+
+test("McpStore initializes core tables", () => {
+  const store = new McpStore(":memory:");
+  const run = store.createRun({
+    task: "health",
+    mode: "single",
+    budget: "low",
+  });
+
+  expect(run.status).toBe("queued");
+  expect(run.id.length).toBeGreaterThan(10);
+  store.close();
+});

package/tests/guardrails.test.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "bun:test";
+import { shouldStopForBudget } from "../src/runtime/executor.ts";
+
+test("stops run when estimated cost exceeds max", () => {
+  expect(shouldStopForBudget({ spentUsd: 5.1, maxUsd: 5 })).toBe(true);
+  expect(shouldStopForBudget({ spentUsd: 4.9, maxUsd: 5 })).toBe(false);
+});