@fusionkit/ensemble 0.1.0

package/dist/test/tool-executor.test.js

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { assertToolExecutionRecordV1 } from "@fusionkit/protocol";
+import { createToolExecutor, registerDemoTools } from "../tool-executor.js";
+import { createMockHarness } from "../mock.js";
+import { runEnsemble } from "../run.js";
+function contract(overrides = {}) {
+    return {
+        executor_id: "exec_demo",
+        mode: "demo_safe",
+        environment_id: "env_a",
+        tool_policy_id: "policy_read",
+        allowed_tools: ["read_file", "echo"],
+        side_effects: ["none", "read"],
+        limits: { timeoutMs: 1000 },
+        audit_sink: "memory",
+        ...overrides
+    };
+}
+function repoFixture() {
+    const root = mkdtempSync(join(tmpdir(), "tool-executor-"));
+    const repo = join(root, "repo");
+    mkdirSync(repo);
+    writeFileSync(join(repo, "README.md"), "hello tools\n");
+    return { repo, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+test("read-only duplicate calls dedupe only under matching policy and environment", async () => {
+    const fixture = repoFixture();
+    try {
+        const executor = createToolExecutor(contract());
+        registerDemoTools(executor, fixture.repo);
+        const request = {
+            tool_name: "read_file",
+            arguments: { path: "README.md" },
+            side_effects: "read"
+        };
+        const first = await executor.execute(request);
+        const second = await executor.execute(request);
+        assert.equal(first.deduped, false);
+        assert.equal(second.deduped, true);
+        assert.equal(second.record.execution_id, first.record.execution_id);
+        const other = createToolExecutor(contract({ environment_id: "env_b" }));
+        registerDemoTools(other, fixture.repo);
+        const third = await other.execute(request);
+        assert.notEqual(third.record.execution_id, first.record.execution_id);
+    }
+    finally {
+        fixture.cleanup();
+    }
+});
+test("write and external calls are denied by default", async () => {
+    const executor = createToolExecutor(contract({ allowed_tools: ["write_file", "fetch"] }));
+    const write = await executor.execute({
+        tool_name: "write_file",
+        arguments: { path: "README.md" },
+        side_effects: "write"
+    });
+    const external = await executor.execute({
+        tool_name: "fetch",
+        arguments: { url: "https://example.com" },
+        side_effects: "external"
+    });
+    assert.equal(write.record.status, "failed");
+    assert.equal(write.record.error?.kind, "tool_denied");
+    assert.equal(external.record.status, "failed");
+    assert.equal(external.record.error?.kind, "tool_denied");
+});
+test("allowed read-only tools emit valid tool-execution-record.v1", async () => {
+    const fixture = repoFixture();
+    try {
+        const executor = createToolExecutor(contract());
+        registerDemoTools(executor, fixture.repo);
+        const result = await executor.execute({
+            tool_name: "read_file",
+            arguments: { path: "README.md" },
+            side_effects: "read"
+        });
+        assertToolExecutionRecordV1(result.record);
+        assert.equal(result.record.status, "succeeded");
+        assert.ok(result.record.output_hash?.startsWith("sha256:"));
+    }
+    finally {
+        fixture.cleanup();
+    }
+});
+test("candidate summaries include tool execution ids", async () => {
+    const toolRecord = {
+        execution_id: "exec_candidate_read",
+        plan_id: "plan_candidate_read",
+        status: "succeeded",
+        output_hash: "sha256:" + "a".repeat(64)
+    };
+    const result = await runEnsemble({
+        id: "tool_summary",
+        harness: createMockHarness({
+            candidates: {
+                fast: { toolRecords: [toolRecord] }
+            }
+        }),
+        models: [{ id: "fast", model: "fake-fast" }],
+        runtime: { id: "local" },
+        judge: { id: "none" },
+        policy: { id: "policy", allowedTools: ["read_file"], sideEffects: "read_only" },
+        prompt: "tool summary",
+        sourceRepo: "handoffkit",
+        baseGitSha: "a".repeat(40)
+    });
+    assert.equal(result.toolRecords[0]?.execution_id, "exec_candidate_read");
+    assert.deepEqual(result.summary?.candidates[0]?.toolExecutionIds, ["exec_candidate_read"]);
+});

package/dist/test/unified.test.d.ts

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

package/dist/test/unified.test.js

@@ -0,0 +1,150 @@
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+import { runUnifiedHarnessE2E } from "../unified.js";
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+async function closeServer(server) {
+    await new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+}
+async function startFusionBackend() {
+    const models = [];
+    const server = createServer((req, res) => {
+        void (async () => {
+            if (req.method !== "POST" || req.url !== "/v1/chat/completions") {
+                res.writeHead(404).end();
+                return;
+            }
+            const body = JSON.parse((await readBody(req)).toString("utf8"));
+            const model = body.model ?? "unknown";
+            models.push(model);
+            const system = body.messages?.find((message) => message.role === "system")?.content ?? "";
+            const content = system.includes("synthesize coding harness candidate evidence")
+                ? `JUDGE_FINAL:${model}`
+                : `MODEL_REPLY:${model}`;
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(JSON.stringify({
+                choices: [{ message: { role: "assistant", content } }]
+            }));
+        })().catch((error) => {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: String(error) }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    assert.ok(typeof address === "object" && address !== null);
+    return {
+        url: `http://127.0.0.1:${address.port}`,
+        models,
+        close: () => closeServer(server)
+    };
+}
+function makeRepo() {
+    const root = mkdtempSync(join(tmpdir(), "unified-harness-e2e-"));
+    const repo = join(root, "repo");
+    const outputRoot = join(root, "out");
+    mkdirSync(repo);
+    spawnSync("git", ["init", "--quiet", "--initial-branch=main"], { cwd: repo });
+    spawnSync("git", ["config", "user.email", "unified@warrant.local"], { cwd: repo });
+    spawnSync("git", ["config", "user.name", "unified"], { cwd: repo });
+    writeFileSync(join(repo, "README.md"), "# unified fixture\n");
+    writeFileSync(join(repo, "candidate.js"), [
+        "const fs = require('node:fs');",
+        "(async () => {",
+        "  const response = await fetch(process.env.FUSIONKIT_CHAT_COMPLETIONS_URL, {",
+        "    method: 'POST',",
+        "    headers: { 'content-type': 'application/json' },",
+        "    body: JSON.stringify({",
+        "      model: process.env.FUSIONKIT_MODEL,",
+        "      messages: [{ role: 'user', content: 'candidate probe' }]",
+        "    })",
+        "  });",
+        "  const body = await response.json();",
+        "  fs.writeFileSync(`result-${process.env.HARNESS_MODEL_ID}.txt`, body.choices[0].message.content);",
+        "  console.log(`MODEL_OK:${process.env.HARNESS_MODEL_ID}`);",
+        "})().catch((error) => { console.error(error); process.exit(1); });",
+        ""
+    ].join("\n"));
+    spawnSync("git", ["add", "-A"], { cwd: repo });
+    spawnSync("git", ["commit", "--quiet", "-m", "init"], { cwd: repo });
+    return { root, repo, outputRoot, cleanup: () => rmSync(root, { recursive: true, force: true }) };
+}
+test("unified runner routes each command candidate through FusionKit and synthesizes", async () => {
+    const fixture = makeRepo();
+    const backend = await startFusionBackend();
+    try {
+        const result = await runUnifiedHarnessE2E({
+            id: "unified_test",
+            fusionBackendUrl: backend.url,
+            repo: fixture.repo,
+            outputRoot: fixture.outputRoot,
+            prompt: "Run the candidate script and synthesize the result.",
+            harnesses: ["command"],
+            models: [
+                { id: "alpha", model: "fusion-alpha" },
+                { id: "beta", model: "fusion-beta" }
+            ],
+            judgeModel: "fusion-judge",
+            command: "node candidate.js",
+            timeoutMs: 10_000
+        });
+        const row = result.results[0];
+        assert.equal(row?.status, "succeeded");
+        assert.equal(row?.ensemble?.candidates.length, 2);
+        assert.equal(row?.ensemble?.judgeSynthesisRecord?.final_output, "JUDGE_FINAL:fusion-judge");
+        assert.ok(row?.ensemble?.artifacts.some((artifact) => artifact.kind === "patch"));
+        assert.deepEqual(backend.models.sort(), ["fusion-alpha", "fusion-beta", "fusion-judge"]);
+        assert.ok(result.reportPath?.endsWith("unified-e2e-report.json"));
+    }
+    finally {
+        await backend.close();
+        fixture.cleanup();
+    }
+});
+test("unified runner includes Cursor ACP and desktop adapter results", async () => {
+    const fixture = makeRepo();
+    try {
+        const seen = [];
+        const result = await runUnifiedHarnessE2E({
+            id: "unified_cursor_test",
+            fusionBackendUrl: "http://127.0.0.1:9999",
+            repo: fixture.repo,
+            outputRoot: fixture.outputRoot,
+            prompt: "Run Cursor probes.",
+            harnesses: ["cursor-acp", "cursor-desktop"],
+            models: [{ id: "cursor-local", model: "local-model" }],
+            cursorRunner: async (input) => {
+                seen.push(input);
+                return {
+                    status: "succeeded",
+                    message: `${input.kind} ok`,
+                    artifacts: { report: join(input.outDir, "report.json") },
+                    details: { model: input.model.id }
+                };
+            }
+        });
+        assert.deepEqual(result.results.map((row) => row.harness), ["cursor-acp", "cursor-desktop"]);
+        assert.deepEqual(result.results.map((row) => row.status), ["succeeded", "succeeded"]);
+        assert.deepEqual(seen.map((input) => input.kind), ["cursor-acp", "cursor-desktop"]);
+    }
+    finally {
+        fixture.cleanup();
+    }
+});

package/dist/tool-executor.d.ts

@@ -0,0 +1,14 @@
+import { modelFusionSideEffects } from "@fusionkit/protocol";
+import type { JsonValue, ToolDefinition, ToolExecutionRequest, ToolExecutionResult, ToolExecutorContract, ToolSideEffectClass } from "@fusionkit/protocol";
+export type ToolImplementation = {
+    definition: ToolDefinition;
+    execute(args: JsonValue): Promise<JsonValue> | JsonValue;
+};
+export type ToolExecutor = {
+    contract: ToolExecutorContract;
+    register(tool: ToolImplementation): void;
+    execute(request: ToolExecutionRequest): Promise<ToolExecutionResult>;
+};
+export declare function createToolExecutor(contract: ToolExecutorContract): ToolExecutor;
+export declare function registerDemoTools(executor: ToolExecutor, workspace: string): void;
+export declare function sideEffectsForTool(sideEffects: ToolSideEffectClass): ReturnType<typeof modelFusionSideEffects>;

package/dist/tool-executor.js

@@ -0,0 +1,156 @@
+import { readFileSync } from "node:fs";
+import { artifactHash, assertToolExecutionRecordV1, evaluateToolPolicy, MODEL_FUSION_SCHEMA_BUNDLE_HASH, modelFusionSideEffects, toolArgumentsHash, toolCallKey } from "@fusionkit/protocol";
+import { resolveInsideWorkspace } from "@fusionkit/workspace";
+function metadata(createdAt) {
+    return {
+        schema: "tool-execution-record.v1",
+        schema_version: "v1",
+        schema_bundle_hash: MODEL_FUSION_SCHEMA_BUNDLE_HASH,
+        producer: "handoffkit-ensemble",
+        producer_version: "0.1.0",
+        producer_git_sha: "0".repeat(40),
+        created_at: createdAt
+    };
+}
+function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function executionRecord(input) {
+    const argumentsHash = toolArgumentsHash(input.request.arguments);
+    const record = {
+        ...metadata(input.createdAt),
+        execution_id: `tool_exec_${toolCallKey({
+            contract: input.contract,
+            request: input.request
+        }).slice(0, 16)}`,
+        plan_id: input.request.plan_id ??
+            `tool_plan_${argumentsHash.slice("sha256:".length, "sha256:".length + 16)}`,
+        status: input.status,
+        ...(input.output !== undefined ? { output_hash: artifactHash(JSON.stringify(input.output)) } : {}),
+        ...(input.status !== "succeeded"
+            ? {
+                error: {
+                    kind: input.decision.decision === "deny" ? input.decision.errorKind : "internal_error",
+                    message: input.decision.reason,
+                    retryable: false
+                }
+            }
+            : {})
+    };
+    assertToolExecutionRecordV1(record);
+    return record;
+}
+export function createToolExecutor(contract) {
+    const tools = new Map();
+    const dedupe = new Map();
+    return {
+        contract,
+        register(tool) {
+            tools.set(tool.definition.tool_name, tool);
+        },
+        async execute(request) {
+            const decision = evaluateToolPolicy(contract, request);
+            const createdAt = new Date().toISOString();
+            if (decision.decision === "deny") {
+                return {
+                    record: executionRecord({
+                        contract,
+                        request,
+                        status: "failed",
+                        decision,
+                        createdAt
+                    }),
+                    deduped: false,
+                    decision
+                };
+            }
+            if (decision.dedupeKey !== undefined && dedupe.has(decision.dedupeKey)) {
+                const cached = dedupe.get(decision.dedupeKey);
+                if (cached !== undefined) {
+                    return {
+                        record: executionRecord({
+                            contract,
+                            request,
+                            status: cached.record.status,
+                            output: cached.output,
+                            decision,
+                            createdAt
+                        }),
+                        ...(cached.output !== undefined ? { output: cached.output } : {}),
+                        deduped: true,
+                        decision
+                    };
+                }
+            }
+            const tool = tools.get(request.tool_name);
+            if (tool === undefined) {
+                const denied = {
+                    decision: "deny",
+                    reason: `tool ${request.tool_name} is not registered`,
+                    errorKind: "capability_missing"
+                };
+                return {
+                    record: executionRecord({
+                        contract,
+                        request,
+                        status: "unsupported",
+                        decision: denied,
+                        createdAt
+                    }),
+                    deduped: false,
+                    decision: denied
+                };
+            }
+            const output = await tool.execute(request.arguments);
+            const result = {
+                record: executionRecord({
+                    contract,
+                    request,
+                    status: "succeeded",
+                    output,
+                    decision,
+                    createdAt
+                }),
+                output,
+                deduped: false,
+                decision
+            };
+            if (decision.dedupeKey !== undefined)
+                dedupe.set(decision.dedupeKey, result);
+            return result;
+        }
+    };
+}
+export function registerDemoTools(executor, workspace) {
+    executor.register({
+        definition: {
+            tool_name: "read_file",
+            side_effects: "read",
+            description: "Read a workspace-relative file."
+        },
+        execute(args) {
+            const path = asObject(args).path;
+            if (typeof path !== "string")
+                throw new Error("read_file requires path");
+            return {
+                path,
+                content: readFileSync(resolveInsideWorkspace(workspace, path), "utf8")
+            };
+        }
+    });
+    executor.register({
+        definition: {
+            tool_name: "echo",
+            side_effects: "none",
+            description: "Echo a JSON-safe value."
+        },
+        execute(args) {
+            return args;
+        }
+    });
+}
+export function sideEffectsForTool(sideEffects) {
+    return modelFusionSideEffects(sideEffects);
+}

package/dist/trace.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Ensemble-facing surface for the fusion-trace emitter. The canonical
+ * implementation lives in `@fusionkit/protocol` (a dependency-free leaf) so the
+ * gateway, the AI SDK worktree agent, and the CLI can share it without import
+ * cycles; this module simply re-exports it for ensemble call sites.
+ */
+export { ambientTraceId, emitTrace, getTraceEmitter, newSpanId, newTraceId, TRACE_CANDIDATE_HEADER, TRACE_ID_HEADER, TRACE_PARENT_SPAN_HEADER, TRACE_SPAN_HEADER, TraceEmitter } from "@fusionkit/protocol";
+export type { EmitInput, FusionTraceComponent, FusionTraceEvent, FusionTraceEventType } from "@fusionkit/protocol";

package/dist/trace.js

@@ -0,0 +1,7 @@
+/**
+ * Ensemble-facing surface for the fusion-trace emitter. The canonical
+ * implementation lives in `@fusionkit/protocol` (a dependency-free leaf) so the
+ * gateway, the AI SDK worktree agent, and the CLI can share it without import
+ * cycles; this module simply re-exports it for ensemble call sites.
+ */
+export { ambientTraceId, emitTrace, getTraceEmitter, newSpanId, newTraceId, TRACE_CANDIDATE_HEADER, TRACE_ID_HEADER, TRACE_PARENT_SPAN_HEADER, TRACE_SPAN_HEADER, TraceEmitter } from "@fusionkit/protocol";

package/dist/unified.d.ts

@@ -0,0 +1,101 @@
+import type { JsonValue, ModelFusionStatus } from "@fusionkit/protocol";
+import type { EnsembleModel, EnsembleRunResult } from "./harness.js";
+import type { JudgeSynthesizer } from "./judge.js";
+export type UnifiedHarnessKind = "mock" | "command" | "agent" | "codex" | "claude-code" | "cursor-acp" | "cursor-desktop";
+export type UnifiedHarnessMatrixResult = {
+    harness: UnifiedHarnessKind;
+    modelIds: string[];
+    status: ModelFusionStatus;
+    message: string;
+    ensemble?: EnsembleRunResult;
+    artifacts: Record<string, string>;
+    details: Record<string, JsonValue>;
+};
+export type UnifiedHarnessE2EResult = {
+    id: string;
+    generatedAt: string;
+    fusionBackendUrl: string;
+    repo: string;
+    results: UnifiedHarnessMatrixResult[];
+    reportPath?: string;
+};
+export type CursorHarnessRunnerInput = {
+    kind: Extract<UnifiedHarnessKind, "cursor-acp" | "cursor-desktop">;
+    model: EnsembleModel;
+    fusionBackendUrl: string;
+    repo: string;
+    outDir: string;
+    timeoutMs?: number;
+    cursorKitDir?: string;
+};
+export type CursorHarnessRunnerResult = {
+    status: ModelFusionStatus;
+    message: string;
+    artifacts?: Record<string, string>;
+    details?: Record<string, JsonValue>;
+};
+export type UnifiedHarnessE2EOptions = {
+    id?: string;
+    fusionBackendUrl: string;
+    fusionApiKey?: string;
+    repo: string;
+    outputRoot: string;
+    prompt: string;
+    harnesses: UnifiedHarnessKind[];
+    models: EnsembleModel[];
+    command?: string;
+    timeoutMs?: number;
+    judgeModel?: string;
+    cursorKitDir?: string;
+    cursorRunner?: (input: CursorHarnessRunnerInput) => Promise<CursorHarnessRunnerResult>;
+    /**
+     * Per-candidate model backend URLs keyed by `EnsembleModel.id`. When a
+     * candidate's model id is present, its command harness is pointed at that
+     * endpoint instead of the shared `fusionBackendUrl`, so each panel model can
+     * back its own real candidate (e.g. a local MLX trio).
+     */
+    modelEndpoints?: Record<string, string>;
+    /**
+     * Observability correlation id. When set, the agent harness, panel-model
+     * calls, and the FusionKit trajectory synthesis are all tagged with this
+     * trace so the companion app can reconstruct one session.
+     */
+    traceId?: string;
+    /** Session root span; panel candidate spans parent under it. */
+    parentSpanId?: string;
+    /** User-turn index this panel run belongs to (stamped on candidate events). */
+    turn?: number;
+};
+export declare function createFusionKitJudgeSynthesizer(input: {
+    fusionBackendUrl: string;
+    model: string;
+    apiKey?: string;
+    responseShape: string;
+    traceId?: string;
+}): JudgeSynthesizer;
+export type FusionPanelOptions = {
+    id?: string;
+    repo: string;
+    outputRoot: string;
+    prompt: string;
+    models: EnsembleModel[];
+    modelEndpoints?: Record<string, string>;
+    /** Fallback agent backend URL for models without a dedicated endpoint. */
+    fusionBackendUrl: string;
+    fusionApiKey?: string;
+    timeoutMs?: number;
+    traceId?: string;
+    /** Session root span so panel candidate spans nest under the session. */
+    parentSpanId?: string;
+    /** User-turn index this panel run belongs to (for per-turn grouping). */
+    turn?: number;
+};
+/**
+ * Run the panel once: each panel model executes the task as a real coding agent
+ * in its own git worktree, and we capture the resulting trajectories (the
+ * candidate reference solutions the judge fuses). This reuses the full agent
+ * harness via `runEnsemble` with a capturing judge — no fusion/synthesis call is
+ * made here; the trajectories are the product.
+ */
+export declare function runFusionPanels(options: FusionPanelOptions): Promise<Record<string, unknown>[]>;
+export declare function runUnifiedHarnessE2E(options: UnifiedHarnessE2EOptions): Promise<UnifiedHarnessE2EResult>;