@fusionkit/adapter-ai-sdk 0.1.0

package/dist/test/routed-model.test.js

@@ -0,0 +1,223 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { generateText } from "ai";
+import { MockLanguageModelV3 } from "ai/test";
+import { loadRouterCard, routedModel, withRoutedModel } from "../routed-model.js";
+const usage = {
+    inputTokens: {
+        total: 1,
+        noCache: 1,
+        cacheRead: undefined,
+        cacheWrite: undefined
+    },
+    outputTokens: { total: 1, text: 1, reasoning: undefined }
+};
+function textModel(id, text) {
+    return new MockLanguageModelV3({
+        modelId: id,
+        doGenerate: async () => ({
+            content: [{ type: "text", text }],
+            finishReason: { unified: "stop", raw: "stop" },
+            usage,
+            warnings: []
+        })
+    });
+}
+function failingModel(id, message) {
+    return new MockLanguageModelV3({
+        modelId: id,
+        doGenerate: async () => {
+            throw new Error(message);
+        }
+    });
+}
+// Two clusters in a 2-d embedding space: axis 0 = "math", axis 1 = "code".
+// math-llm aces cluster 0 and fails cluster 1; code-llm mirrors; generalist
+// is mediocre everywhere but cheap.
+const CARD = loadRouterCard({
+    version: "uniroute.router.v1",
+    embedder: { model: "fake-embedder", dims: 2 },
+    lambda: 0,
+    assignment: {
+        type: "centroids",
+        centroids: [
+            [1, 0],
+            [0, 1]
+        ]
+    },
+    models: [
+        { id: "math-llm", psi: [0.05, 0.9], cost: 2 },
+        { id: "code-llm", psi: [0.9, 0.05], cost: 2 },
+        { id: "generalist", psi: [0.4, 0.4], cost: 0.1 }
+    ]
+});
+/** The fake embedder the card was "fitted" with: keyword axes. */
+async function embed(text) {
+    return [text.includes("math") ? 1 : 0, text.includes("code") ? 1 : 0];
+}
+test("routes each prompt to its cluster specialist", async () => {
+    const decisions = [];
+    const model = routedModel({
+        card: CARD,
+        candidates: {
+            "math-llm": textModel("math-llm", "from math"),
+            "code-llm": textModel("code-llm", "from code"),
+            generalist: textModel("generalist", "from generalist")
+        },
+        embed,
+        onDecision: (d) => decisions.push(d)
+    });
+    const math = await generateText({ model, prompt: "math: integrate x^2" });
+    assert.equal(math.text, "from math");
+    const code = await generateText({ model, prompt: "code: write a loop" });
+    assert.equal(code.text, "from code");
+    assert.equal(decisions.length, 2);
+    assert.deepEqual(decisions.map((d) => d.model), ["math-llm", "code-llm"]);
+    assert.equal(decisions[0]?.fallback, false);
+    assert.ok(Math.abs((decisions[0]?.predictedError ?? 0) - 0.05) < 1e-9);
+});
+test("lambda trades quality for cost: large lambda picks the cheap generalist", async () => {
+    const model = routedModel({
+        card: CARD,
+        candidates: {
+            "math-llm": textModel("math-llm", "from math"),
+            "code-llm": textModel("code-llm", "from code"),
+            generalist: textModel("generalist", "from generalist")
+        },
+        embed,
+        lambda: 1 // 1 * cost(2) overwhelms any gamma difference in [0,1]
+    });
+    const result = await generateText({ model, prompt: "math: integrate x^2" });
+    assert.equal(result.text, "from generalist");
+});
+test("falls back to the next-best candidate when the chosen one fails", async () => {
+    const decisions = [];
+    const model = routedModel({
+        card: CARD,
+        candidates: {
+            "math-llm": failingModel("math-llm", "server crashed"),
+            "code-llm": textModel("code-llm", "from code"),
+            generalist: textModel("generalist", "from generalist")
+        },
+        embed,
+        onDecision: (d) => decisions.push(d)
+    });
+    const result = await generateText({ model, prompt: "math: integrate x^2" });
+    // Next-best for the math cluster at lambda 0 is the generalist (0.4 < 0.9).
+    assert.equal(result.text, "from generalist");
+    assert.equal(decisions.length, 2);
+    assert.match(decisions[0]?.reason ?? "", /call failed: server crashed/);
+    assert.equal(decisions[1]?.fallback, true);
+    assert.match(decisions[1]?.reason ?? "", /fallback/);
+});
+test("fallback: false surfaces the failure", async () => {
+    const model = routedModel({
+        card: CARD,
+        candidates: {
+            "math-llm": failingModel("math-llm", "server crashed"),
+            "code-llm": textModel("code-llm", "x"),
+            generalist: textModel("generalist", "x")
+        },
+        embed,
+        fallback: false
+    });
+    await assert.rejects(generateText({ model, prompt: "math: integrate x^2" }), /server crashed/);
+});
+test("softmax assignment cards route through the learned map", async () => {
+    // theta rows (with bias column) reproduce the keyword axes sharply.
+    const card = loadRouterCard({
+        version: "uniroute.router.v1",
+        embedder: { model: "fake-embedder", dims: 2 },
+        lambda: 0,
+        assignment: {
+            type: "softmax",
+            theta: [
+                [10, -10, 0],
+                [-10, 10, 0]
+            ]
+        },
+        models: [
+            { id: "math-llm", psi: [0.05, 0.9], cost: 1 },
+            { id: "code-llm", psi: [0.9, 0.05], cost: 1 }
+        ]
+    });
+    const model = routedModel({
+        card,
+        candidates: {
+            "math-llm": textModel("math-llm", "from math"),
+            "code-llm": textModel("code-llm", "from code")
+        },
+        embed
+    });
+    const result = await generateText({ model, prompt: "code: refactor this" });
+    assert.equal(result.text, "from code");
+});
+test("card validation fails closed", () => {
+    assert.throws(() => loadRouterCard({
+        version: "uniroute.router.v2",
+        embedder: { model: "e", dims: 2 },
+        lambda: 0,
+        assignment: { type: "centroids", centroids: [[0, 0]] },
+        models: [{ id: "a", psi: [0], cost: 1 }]
+    }), /version/);
+    assert.throws(() => loadRouterCard({
+        version: "uniroute.router.v1",
+        embedder: { model: "e", dims: 3 }, // centroids are 2-wide
+        lambda: 0,
+        assignment: { type: "centroids", centroids: [[0, 0]] },
+        models: [{ id: "a", psi: [0], cost: 1 }]
+    }), /dims/);
+    assert.throws(() => loadRouterCard({
+        version: "uniroute.router.v1",
+        embedder: { model: "e", dims: 2 },
+        lambda: 0,
+        assignment: { type: "centroids", centroids: [[0, 0]] },
+        models: [{ id: "a", psi: [0, 0], cost: 1 }] // psi length != clusters
+    }), /psi length/);
+});
+test("a candidate missing for a card model is rejected at construction", () => {
+    assert.throws(() => routedModel({
+        card: CARD,
+        candidates: { "math-llm": textModel("math-llm", "x") },
+        embed
+    }), /without candidates: code-llm, generalist/);
+});
+test("embedding dimension mismatches are rejected per call", async () => {
+    const model = routedModel({
+        card: CARD,
+        candidates: {
+            "math-llm": textModel("math-llm", "x"),
+            "code-llm": textModel("code-llm", "x"),
+            generalist: textModel("generalist", "x")
+        },
+        embed: async () => [1, 0, 0] // 3 dims against a 2-dim card
+    });
+    await assert.rejects(generateText({ model, prompt: "math" }), /dims/);
+});
+test("withRoutedModel reports decisions into the handoff trace shape", async () => {
+    const noted = [];
+    const stubHandoff = {
+        noteModelDecision: (decision) => noted.push(decision)
+    };
+    const h = withRoutedModel(
+    // Only noteModelDecision is exercised by the wiring under test.
+    stubHandoff, {
+        card: CARD,
+        candidates: {
+            "math-llm": failingModel("math-llm", "boom"),
+            "code-llm": textModel("code-llm", "x"),
+            generalist: textModel("generalist", "from generalist")
+        },
+        embed,
+        localModels: ["math-llm", "generalist"]
+    });
+    const result = await generateText({ model: h.model, prompt: "math: 1+1" });
+    assert.equal(result.text, "from generalist");
+    assert.deepEqual(noted.map((d) => {
+        const decision = d;
+        return [decision.model, decision.route, decision.escalated];
+    }), [
+        ["math-llm", "local", false],
+        ["generalist", "local", true]
+    ]);
+});

package/dist/test/swarm-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/swarm-tools.test.js

@@ -0,0 +1,157 @@
+import assert from "node:assert/strict";
+import { existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import { agents, localFirst } from "@fusionkit/handoff";
+import { makeRepo, startStack } from "@fusionkit/testkit";
+import { swarmTools } from "../swarm-tools.js";
+const POOL = "swarm-pool";
+const TOOL_CTX = { toolCallId: "call", messages: [] };
+let stack;
+before(async () => {
+    // A concurrent runner so a worker fan-out actually runs in parallel; mock
+    // workers keep the test deterministic and key-free. Both worker and cloud
+    // (escalation) runs use the mock agent on the process tier here — the real
+    // swarm uses pi workers and a claude-code cloud target.
+    stack = await startStack({
+        pool: POOL,
+        startRunner: true,
+        concurrency: 4,
+        pollIntervalMs: 25,
+        policy: (policy) => {
+            policy.agents.allow = ["mock"];
+        }
+    });
+});
+after(async () => {
+    await stack.stop();
+});
+function makeSwarm(repoDir, overrides = {}) {
+    return swarmTools({
+        workspace: repoDir,
+        plane: { url: stack.planeUrl, adminToken: stack.adminToken },
+        workerPool: POOL,
+        cloudPool: POOL,
+        actor: { kind: "human", id: "orchestrator" },
+        // Mock workers and a mock cloud agent on the process tier keep CI key-free.
+        workerAgent: agents.mock(),
+        workerSession: "process",
+        cloudAgent: agents.mock(),
+        cloudSession: "process",
+        ...overrides
+    });
+}
+test("dispatch fans workers out and a completed worker is judged from evidence and pulled", async () => {
+    const repoDir = makeRepo({ files: { "README.md": "# swarm fixture\n" } });
+    try {
+        const swarm = makeSwarm(repoDir);
+        const dispatch = swarm.tools.dispatch_workers.execute;
+        const pull = swarm.tools.pull_worker.execute;
+        assert.ok(dispatch && pull);
+        const dispatched = (await dispatch({ tasks: [{ prompt: "improve the docs", fileScope: ["MOCK_AGENT.md"] }] }, TOOL_CTX));
+        assert.equal(dispatched.budgetExceeded, false);
+        assert.equal(dispatched.dispatched.length, 1);
+        const runId = dispatched.dispatched[0]?.runId;
+        assert.ok(runId);
+        const pulled = (await pull({ runId }, TOOL_CTX));
+        assert.equal(pulled.verdict, "accepted");
+        assert.equal(pulled.status, "completed");
+        assert.ok(pulled.filesChanged.includes("MOCK_AGENT.md"));
+        assert.ok(pulled.scorecard, "an accepted worker carries a deterministic scorecard");
+        assert.equal(pulled.scorecard?.status, "completed");
+        assert.equal(pulled.scorecard?.exitCode, 0);
+        assert.ok(pulled.receipt?.verified, "the receipt must verify offline");
+        assert.match(pulled.receipt?.contractHash ?? "", /^[0-9a-f]{64}$/);
+        // The worker's change landed on the workspace of record.
+        assert.ok(existsSync(join(repoDir, "MOCK_AGENT.md")));
+        // The evidence record reflects the accepted verdict.
+        const records = swarm.calls();
+        assert.ok(records.some((r) => r.tool === "pull_worker" && r.verdict === "accepted" && r.runId === runId));
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("a worker overlapping already-pulled files is downgraded to escalate, not pulled", async () => {
+    const repoDir = makeRepo({ files: { "README.md": "# overlap fixture\n" } });
+    try {
+        const swarm = makeSwarm(repoDir);
+        const dispatch = swarm.tools.dispatch_workers.execute;
+        const pull = swarm.tools.pull_worker.execute;
+        assert.ok(dispatch && pull);
+        // Two mock workers both write MOCK_AGENT.md, so they necessarily collide.
+        const dispatched = (await dispatch({ tasks: [{ prompt: "task one" }, { prompt: "task two" }] }, TOOL_CTX));
+        assert.equal(dispatched.dispatched.length, 2);
+        const [a, b] = dispatched.dispatched;
+        assert.ok(a && b);
+        const first = (await pull({ runId: a.runId }, TOOL_CTX));
+        assert.equal(first.verdict, "accepted");
+        const second = (await pull({ runId: b.runId }, TOOL_CTX));
+        assert.equal(second.verdict, "escalate");
+        assert.ok(second.conflictingPaths?.includes("MOCK_AGENT.md"));
+        assert.match(second.reason, /overlaps already-pulled/);
+        // Evidence is still attached to the refused pull.
+        assert.ok(second.receipt?.verified);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("worker_status reports without blocking and flags unknown ids", async () => {
+    const repoDir = makeRepo({ files: { "README.md": "# status fixture\n" } });
+    try {
+        const swarm = makeSwarm(repoDir);
+        const dispatch = swarm.tools.dispatch_workers.execute;
+        const status = swarm.tools.worker_status.execute;
+        assert.ok(dispatch && status);
+        const dispatched = (await dispatch({ tasks: [{ prompt: "do work" }] }, TOOL_CTX));
+        const runId = dispatched.dispatched[0]?.runId;
+        assert.ok(runId);
+        const reported = (await status({ runIds: [runId, "run_does_not_exist"] }, TOOL_CTX));
+        assert.equal(reported.statuses.length, 2);
+        assert.equal(reported.statuses.find((s) => s.runId === runId)?.known, true);
+        assert.equal(reported.statuses.find((s) => s.runId === "run_does_not_exist")?.known, false);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("dispatch beyond the fan-out ceiling is refused with budgetExceeded", async () => {
+    const repoDir = makeRepo({ files: { "README.md": "# budget fixture\n" } });
+    try {
+        const swarm = makeSwarm(repoDir, {
+            policy: localFirst({ allowPools: [POOL], maxParallelRuns: 1 })
+        });
+        const dispatch = swarm.tools.dispatch_workers.execute;
+        assert.ok(dispatch);
+        const dispatched = (await dispatch({ tasks: [{ prompt: "one" }, { prompt: "two" }] }, TOOL_CTX));
+        assert.equal(dispatched.budgetExceeded, true);
+        assert.equal(dispatched.dispatched.length, 0);
+        assert.match(dispatched.reason, /exceeds policy ceiling/);
+        assert.equal(swarm.calls().length, 0, "a refused dispatch produces no records");
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});
+test("escalate_task runs the cloud agent as a governed run and is budget-bounded", async () => {
+    const repoDir = makeRepo({ files: { "README.md": "# escalate fixture\n" } });
+    try {
+        const swarm = makeSwarm(repoDir, { maxEscalations: 1 });
+        const escalate = swarm.tools.escalate_task.execute;
+        assert.ok(escalate);
+        const first = (await escalate({ task: "fix it properly" }, TOOL_CTX));
+        assert.equal(first.budgetExceeded, false);
+        assert.equal(first.status, "completed");
+        assert.ok(first.receipt?.verified);
+        assert.match(first.receipt?.contractHash ?? "", /^[0-9a-f]{64}$/);
+        const second = (await escalate({ task: "and again" }, TOOL_CTX));
+        assert.equal(second.budgetExceeded, true);
+        assert.match(second.reason, /budget exhausted/);
+        const records = swarm.calls();
+        assert.equal(records.filter((r) => r.tool === "escalate_task").length, 1);
+    }
+    finally {
+        rmSync(repoDir, { recursive: true, force: true });
+    }
+});

package/dist/worktree-agent.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A uniform, real model-driven agent loop for trajectory-level fusion. One
+ * panel model drives an AI SDK tool loop over a real git worktree (read/list/
+ * grep/write/run), and the full reasoning/tool-call/observation/output sequence
+ * is captured as a normalized trajectory (`harness-trajectory.v1` shaped). No
+ * virtual filesystem and no mocks: the worktree is the isolation boundary and
+ * the tools touch it directly.
+ */
+export type TrajectoryStepType = "reasoning" | "tool_call" | "observation" | "output";
+export type TrajectoryStep = {
+    index: number;
+    type: TrajectoryStepType;
+    text?: string;
+    tool_name?: string;
+    tool_call_id?: string;
+    tool_input?: string;
+    is_error?: boolean;
+};
+export type WorktreeAgentResult = {
+    status: "succeeded" | "failed";
+    steps: TrajectoryStep[];
+    finalOutput: string;
+    finishReason: string;
+    toolCallCount: number;
+};
+export type WorktreeAgentInput = {
+    /** Absolute path to the candidate's git worktree; all tools are scoped here. */
+    worktree: string;
+    /** The user's task/prompt for this turn. */
+    prompt: string;
+    /** OpenAI-compatible base URL for this candidate's model (without `/v1`). */
+    baseUrl: string;
+    /** Model name to request from the endpoint. */
+    model: string;
+    apiKey?: string;
+    /** Max agent steps (tool round-trips) before stopping. Defaults to 12. */
+    maxSteps?: number;
+    /** Per-`run` command timeout in ms. Defaults to 120000. */
+    commandTimeoutMs?: number;
+    abortSignal?: AbortSignal;
+    /** Observability correlation id; when set, steps and model calls are traced. */
+    traceId?: string;
+    /** Candidate id this agent run belongs to (for trace correlation). */
+    candidateId?: string;
+    /** Parent span (e.g. the ensemble candidate span) for waterfall linking. */
+    parentSpanId?: string;
+    /** User-turn index this run belongs to (stamped on model.call events). */
+    turn?: number;
+};
+/** Run one panel model as a real agent over the worktree and capture its trajectory. */
+export declare function runWorktreeAgent(input: WorktreeAgentInput): Promise<WorktreeAgentResult>;
+/** Compute the worktree's staged diff against a base ref (for patch evidence). */
+export declare function worktreeDiff(root: string, baseGitSha: string): string;