@fusionkit/ensemble 0.1.0

package/dist/unified.js

@@ -0,0 +1,422 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { newSpanId, TRACE_ID_HEADER, TRACE_SPAN_HEADER } from "@fusionkit/protocol";
+import { gitText } from "@fusionkit/workspace";
+import { createAgentHarness } from "./agent.js";
+import { claudeCodeHarness } from "./claude-code.js";
+import { createCommandHarness } from "./command.js";
+import { codexHarness } from "./codex.js";
+import { createMockHarness } from "./mock.js";
+import { runEnsemble } from "./run.js";
+function normalizeFusionBackendUrl(value) {
+    return value.replace(/\/+$/, "");
+}
+function chatCompletionsUrl(baseUrl) {
+    const normalized = normalizeFusionBackendUrl(baseUrl);
+    return normalized.endsWith("/v1")
+        ? `${normalized}/chat/completions`
+        : `${normalized}/v1/chat/completions`;
+}
+function sideEffectsForHarness(kind) {
+    switch (kind) {
+        case "mock":
+            return "read_only";
+        case "command":
+            return "tool_execution";
+        case "agent":
+            return "writes_workspace";
+        case "codex":
+        case "claude-code":
+        case "cursor-acp":
+        case "cursor-desktop":
+            return "writes_workspace";
+        default: {
+            const exhausted = kind;
+            throw new Error(`unsupported unified harness: ${String(exhausted)}`);
+        }
+    }
+}
+function harnessAdapter(kind, options) {
+    switch (kind) {
+        case "mock":
+            return createMockHarness();
+        case "agent":
+            return createAgentHarness({
+                modelEndpoints: options.modelEndpoints ?? {},
+                fallbackBaseUrl: normalizeFusionBackendUrl(options.fusionBackendUrl),
+                ...(options.fusionApiKey !== undefined ? { apiKey: options.fusionApiKey } : {}),
+                ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+                ...(options.traceId !== undefined ? { traceId: options.traceId } : {}),
+                ...(options.parentSpanId !== undefined ? { parentSpanId: options.parentSpanId } : {}),
+                ...(options.turn !== undefined ? { turn: options.turn } : {})
+            });
+        case "command": {
+            if (!options.command) {
+                throw new Error("--command is required for the command unified harness");
+            }
+            return createCommandHarness({
+                command: options.command,
+                timeoutMs: options.timeoutMs,
+                env: ({ model }) => {
+                    const backend = options.modelEndpoints?.[model.id] ?? options.fusionBackendUrl;
+                    return {
+                        FUSIONKIT_BASE_URL: normalizeFusionBackendUrl(backend),
+                        FUSIONKIT_CHAT_COMPLETIONS_URL: chatCompletionsUrl(backend),
+                        FUSIONKIT_MODEL: model.model,
+                        FUSIONKIT_MODEL_ID: model.id,
+                        ...(options.fusionApiKey ? { FUSIONKIT_API_KEY: options.fusionApiKey } : {}),
+                        ...(options.traceId ? { FUSION_TRACE_ID: options.traceId } : {})
+                    };
+                }
+            });
+        }
+        case "codex":
+            return codexHarness({
+                timeoutMs: options.timeoutMs,
+                provider: {
+                    kind: "openai-compatible",
+                    baseUrl: normalizeFusionBackendUrl(options.fusionBackendUrl),
+                    ...(options.fusionApiKey ? { apiKey: options.fusionApiKey } : {})
+                }
+            });
+        case "claude-code":
+            return claudeCodeHarness({ timeoutMs: options.timeoutMs });
+        case "cursor-acp":
+        case "cursor-desktop":
+            throw new Error(`${kind} runs through the Cursor harness adapter path`);
+        default: {
+            const exhausted = kind;
+            throw new Error(`unsupported unified harness: ${String(exhausted)}`);
+        }
+    }
+}
+function responseShapeFor(kind) {
+    switch (kind) {
+        case "mock":
+        case "command":
+            return "Return a concise markdown summary and include any final patch guidance.";
+        case "agent":
+            return ("Respond to the user in the natural shape the request calls for: a direct answer, " +
+                "a plan, or the concrete code change. Reply in first person as the assistant.");
+        case "codex":
+            return "Return a Codex-style result summary with patch and verification evidence.";
+        case "claude-code":
+            return "Return a Claude Code-style transcript summary with patch/worktree evidence.";
+        case "cursor-acp":
+        case "cursor-desktop":
+            return "Return text suitable for Cursor ACP session/update plus route evidence notes.";
+        default: {
+            const exhausted = kind;
+            throw new Error(`unsupported unified harness: ${String(exhausted)}`);
+        }
+    }
+}
+function trajectoryFuseUrl(baseUrl) {
+    return `${normalizeFusionBackendUrl(baseUrl)}/v1/fusion/trajectories:fuse`;
+}
+function trajectoryToWire(trajectory) {
+    return {
+        trajectory_id: trajectory.trajectoryId,
+        model_id: trajectory.modelId,
+        status: trajectory.status,
+        steps: trajectory.steps,
+        final_output: trajectory.finalOutput,
+        ...(trajectory.candidateId !== undefined ? { candidate_id: trajectory.candidateId } : {}),
+        ...(trajectory.model !== undefined ? { model: trajectory.model } : {}),
+        ...(trajectory.harnessKind !== undefined ? { harness_kind: trajectory.harnessKind } : {}),
+        ...(trajectory.diff !== undefined && trajectory.diff.length > 0 ? { diff: trajectory.diff } : {}),
+        ...(trajectory.verification !== undefined
+            ? {
+                verification: {
+                    status: trajectory.verification.status,
+                    evidence: trajectory.verification.evidence,
+                    ...(trajectory.verification.exitCode !== undefined
+                        ? { exit_code: trajectory.verification.exitCode }
+                        : {})
+                }
+            }
+            : {})
+    };
+}
+export function createFusionKitJudgeSynthesizer(input) {
+    const authHeaders = input.apiKey
+        ? { authorization: `Bearer ${input.apiKey}` }
+        : {};
+    const traceHeaders = input.traceId !== undefined
+        ? { [TRACE_ID_HEADER]: input.traceId, [TRACE_SPAN_HEADER]: newSpanId() }
+        : {};
+    return {
+        async synthesize(judgeInput) {
+            // Trajectory-level fusion: when candidates carry agent trajectories, fuse
+            // them through FusionKit's trajectory-aware, intent-agnostic synthesizer,
+            // which returns the answer in the request's native shape and first person.
+            const trajectories = judgeInput.candidates
+                .map((candidate) => candidate.trajectory)
+                .filter((trajectory) => trajectory !== undefined);
+            if (trajectories.length > 0) {
+                const fuseResponse = await fetch(trajectoryFuseUrl(input.fusionBackendUrl), {
+                    method: "POST",
+                    headers: { "content-type": "application/json", ...authHeaders, ...traceHeaders },
+                    body: JSON.stringify({
+                        messages: [{ role: "user", content: judgeInput.descriptor.prompt }],
+                        trajectories: trajectories.map(trajectoryToWire)
+                    })
+                });
+                if (!fuseResponse.ok) {
+                    throw new Error(`FusionKit trajectory fusion failed: ${fuseResponse.status} ${(await fuseResponse.text()).slice(0, 500)}`);
+                }
+                const fused = (await fuseResponse.json());
+                return {
+                    decision: "synthesize",
+                    finalOutput: fused.final_output ?? "",
+                    rationale: fused.rationale ?? "FusionKit trajectory fusion",
+                    contributions: trajectories.map((trajectory) => ({
+                        candidateId: trajectory.candidateId ?? trajectory.trajectoryId,
+                        reason: `fused ${trajectory.status} trajectory`
+                    }))
+                };
+            }
+            const response = await fetch(chatCompletionsUrl(input.fusionBackendUrl), {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    ...(input.apiKey ? { authorization: `Bearer ${input.apiKey}` } : {})
+                },
+                body: JSON.stringify({
+                    model: input.model,
+                    messages: [
+                        {
+                            role: "system",
+                            content: "You synthesize coding harness candidate evidence. " +
+                                input.responseShape
+                        },
+                        {
+                            role: "user",
+                            content: JSON.stringify({
+                                prompt: judgeInput.descriptor.prompt,
+                                candidates: judgeInput.candidates,
+                                toolRecords: judgeInput.toolRecords,
+                                artifacts: judgeInput.artifacts
+                            })
+                        }
+                    ],
+                    temperature: 0,
+                    max_tokens: 800
+                })
+            });
+            if (!response.ok) {
+                throw new Error(`FusionKit judge request failed: ${response.status}`);
+            }
+            const body = (await response.json());
+            const finalOutput = body.choices?.[0]?.message?.content ?? "";
+            return {
+                decision: "synthesize",
+                finalOutput,
+                rationale: "FusionKit judge synthesis",
+                contributions: judgeInput.candidates.map((candidate) => ({
+                    candidateId: candidate.candidateId,
+                    reason: `included ${candidate.status} candidate evidence`
+                }))
+            };
+        }
+    };
+}
+/**
+ * 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 async function runFusionPanels(options) {
+    let captured = [];
+    const e2eOptions = {
+        id: options.id ?? `panels_${Date.now()}`,
+        fusionBackendUrl: options.fusionBackendUrl,
+        repo: options.repo,
+        outputRoot: options.outputRoot,
+        prompt: options.prompt,
+        harnesses: ["agent"],
+        models: options.models,
+        ...(options.modelEndpoints !== undefined ? { modelEndpoints: options.modelEndpoints } : {}),
+        ...(options.fusionApiKey !== undefined ? { fusionApiKey: options.fusionApiKey } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.traceId !== undefined ? { traceId: options.traceId } : {}),
+        ...(options.parentSpanId !== undefined ? { parentSpanId: options.parentSpanId } : {}),
+        ...(options.turn !== undefined ? { turn: options.turn } : {})
+    };
+    const descriptor = descriptorFor("agent", e2eOptions);
+    descriptor.judge = {
+        id: "panel-capture",
+        synthesizer: {
+            synthesize(judgeInput) {
+                captured = judgeInput.candidates
+                    .map((candidate) => candidate.trajectory)
+                    .filter((trajectory) => trajectory !== undefined);
+                // The trajectories are the product; this output is discarded. A
+                // non-empty final_output is required by the synthesis record contract.
+                return { decision: "synthesize", finalOutput: `captured ${captured.length} panel trajectories` };
+            }
+        }
+    };
+    await runEnsemble(descriptor);
+    return captured.map(trajectoryToWire);
+}
+function descriptorFor(kind, options) {
+    const id = `${options.id ?? "unified_e2e"}_${kind.replace(/-/g, "_")}`;
+    return {
+        id,
+        harness: harnessAdapter(kind, options),
+        models: options.models,
+        runtime: { id: "unified-local" },
+        judge: {
+            id: "fusionkit-judge",
+            model: options.judgeModel ?? options.models[0]?.model ?? "fusionkit/router",
+            synthesizer: createFusionKitJudgeSynthesizer({
+                fusionBackendUrl: options.fusionBackendUrl,
+                model: options.judgeModel ?? options.models[0]?.model ?? "fusionkit/router",
+                apiKey: options.fusionApiKey,
+                responseShape: responseShapeFor(kind),
+                ...(options.traceId !== undefined ? { traceId: options.traceId } : {})
+            })
+        },
+        policy: {
+            id: "unified-e2e",
+            allowedTools: ["read_file", "write_file", "apply_patch", "run_tests", "shell_command"],
+            sideEffects: sideEffectsForHarness(kind),
+            timeoutMs: options.timeoutMs
+        },
+        prompt: options.prompt,
+        sourceRepo: "handoffkit",
+        baseGitSha: gitText(options.repo, ["rev-parse", "HEAD"]).trim(),
+        workspace: options.repo,
+        outputRoot: options.outputRoot,
+        cleanupWorktrees: true,
+        metadata: {
+            unified_harness_e2e: true,
+            fusion_backend_url: normalizeFusionBackendUrl(options.fusionBackendUrl),
+            response_shape: responseShapeFor(kind)
+        }
+    };
+}
+function statusForResult(result) {
+    return result.failureSummary ? "failed" : result.harnessRunResult.status;
+}
+async function defaultCursorRunner(input) {
+    if (!input.cursorKitDir) {
+        return {
+            status: "skipped",
+            message: "Cursorkit directory not configured",
+            details: { reason: "cursor_kit_dir_missing" }
+        };
+    }
+    const suite = input.kind === "cursor-acp" ? "acp" : "desktop-route";
+    const args = [
+        "test:harness",
+        "--",
+        "--suite",
+        suite,
+        "--base-url",
+        normalizeFusionBackendUrl(input.fusionBackendUrl),
+        "--model",
+        input.model.id,
+        "--provider-model",
+        input.model.model,
+        "--timeout-ms",
+        String(input.timeoutMs ?? 60_000)
+    ];
+    mkdirSync(input.outDir, { recursive: true });
+    return await new Promise((resolveResult) => {
+        const child = spawn("pnpm", args, {
+            cwd: input.cursorKitDir,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("exit", (code) => {
+            const logPath = join(input.outDir, `${input.kind}-${input.model.id}.log`);
+            writeFileSync(logPath, [stdout, stderr].filter(Boolean).join("\n"));
+            resolveResult({
+                status: code === 0 ? "succeeded" : "failed",
+                message: code === 0 ? `${input.kind} completed` : `${input.kind} failed`,
+                artifacts: { log: logPath },
+                details: { exitCode: code ?? 1 }
+            });
+        });
+    });
+}
+async function runCursorHarness(kind, options) {
+    const runner = options.cursorRunner ?? defaultCursorRunner;
+    const perModel = await Promise.all(options.models.map((model) => runner({
+        kind,
+        model,
+        fusionBackendUrl: options.fusionBackendUrl,
+        repo: options.repo,
+        outDir: join(options.outputRoot, `${kind}-${model.id}`),
+        timeoutMs: options.timeoutMs,
+        cursorKitDir: options.cursorKitDir
+    })));
+    const failed = perModel.find((result) => result.status === "failed");
+    const skipped = perModel.every((result) => result.status === "skipped");
+    return {
+        harness: kind,
+        modelIds: options.models.map((model) => model.id),
+        status: failed ? "failed" : skipped ? "skipped" : "succeeded",
+        message: failed?.message ?? (skipped ? "all Cursor model probes skipped" : "Cursor probes completed"),
+        artifacts: Object.assign({}, ...perModel.map((result) => result.artifacts ?? {})),
+        details: {
+            perModel: perModel.map((result) => ({
+                status: result.status,
+                message: result.message,
+                ...(result.details ?? {})
+            }))
+        }
+    };
+}
+export async function runUnifiedHarnessE2E(options) {
+    const outputRoot = resolve(options.outputRoot);
+    mkdirSync(outputRoot, { recursive: true });
+    const results = [];
+    for (const kind of options.harnesses) {
+        if (kind === "cursor-acp" || kind === "cursor-desktop") {
+            results.push(await runCursorHarness(kind, options));
+            continue;
+        }
+        const descriptor = descriptorFor(kind, options);
+        const ensembleResult = await runEnsemble(descriptor);
+        results.push({
+            harness: kind,
+            modelIds: options.models.map((model) => model.id),
+            status: statusForResult(ensembleResult),
+            message: ensembleResult.harnessRunResult.output_summary ?? "",
+            ensemble: ensembleResult,
+            artifacts: {
+                ...(ensembleResult.summaryPath ? { summary: ensembleResult.summaryPath } : {})
+            },
+            details: {
+                candidateCount: ensembleResult.candidates.length,
+                artifactCount: ensembleResult.artifacts.length,
+                toolRecordCount: ensembleResult.toolRecords.length,
+                modelCallRecordCount: ensembleResult.modelCallRecords.length,
+                judgeSynthesis: ensembleResult.judgeSynthesisRecord !== undefined
+            }
+        });
+    }
+    const report = {
+        id: options.id ?? "unified_e2e",
+        generatedAt: new Date().toISOString(),
+        fusionBackendUrl: normalizeFusionBackendUrl(options.fusionBackendUrl),
+        repo: resolve(options.repo),
+        results
+    };
+    const reportPath = join(outputRoot, "unified-e2e-report.json");
+    writeFileSync(reportPath, JSON.stringify(report, null, 2) + "\n");
+    return { ...report, reportPath };
+}

package/dist/worktree.d.ts

@@ -0,0 +1,25 @@
+import type { EnsembleDescriptor, EnsembleModel } from "./harness.js";
+export type CandidateWorktree = {
+    candidateId: string;
+    modelId: string;
+    branchName: string;
+    path: string;
+    baseGitSha: string;
+    snapshotHash: string;
+    sealed: boolean;
+    cleaned: boolean;
+};
+export type WorktreePlan = {
+    workspace: string;
+    baseGitSha: string;
+    snapshotHash: string;
+    root: string;
+    worktrees: CandidateWorktree[];
+};
+export declare function defaultOutputRoot(descriptor: EnsembleDescriptor): string;
+export declare function candidateId(descriptor: EnsembleDescriptor, model: EnsembleModel, ordinal: number): string;
+export declare function createWorktreePlan(descriptor: EnsembleDescriptor): WorktreePlan | undefined;
+export declare function sealCandidateWorktree(worktree: CandidateWorktree): CandidateWorktree;
+export declare function cleanupCandidateWorktree(workspace: string, worktree: CandidateWorktree): CandidateWorktree;
+export declare function cleanupWorktreePlan(plan: WorktreePlan): CandidateWorktree[];
+export declare function diffCandidateWorktree(worktree: CandidateWorktree): string;

package/dist/worktree.js

@@ -0,0 +1,75 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { hashCanonicalSha256 } from "@fusionkit/protocol";
+import { gitText } from "@fusionkit/workspace";
+function safeSegment(value) {
+    return value.replace(/[^A-Za-z0-9_.:-]/g, "_");
+}
+export function defaultOutputRoot(descriptor) {
+    const base = descriptor.outputRoot ?? join(descriptor.workspace ?? tmpdir(), ".warrant", "ensemble");
+    return resolve(base, safeSegment(descriptor.id));
+}
+export function candidateId(descriptor, model, ordinal) {
+    return `${descriptor.id}_${model.id}_${ordinal}`.replace(/[^A-Za-z0-9_.:-]/g, "_");
+}
+export function createWorktreePlan(descriptor) {
+    if (!descriptor.workspace)
+        return undefined;
+    const workspace = resolve(descriptor.workspace);
+    const baseGitSha = descriptor.baseGitSha || gitText(workspace, ["rev-parse", "HEAD"]).trim();
+    const root = mkdtempSync(join(tmpdir(), `warrant-ensemble-${safeSegment(descriptor.id)}-`));
+    const snapshotHash = hashCanonicalSha256({
+        workspace,
+        baseGitSha,
+        descriptorId: descriptor.id,
+        models: descriptor.models.map((model) => model.id)
+    });
+    const worktrees = [];
+    try {
+        for (const [ordinal, model] of descriptor.models.entries()) {
+            const id = candidateId(descriptor, model, ordinal);
+            const path = join(root, id);
+            const branchName = `warrant/ensemble/${safeSegment(descriptor.id)}/${safeSegment(model.id)}`;
+            gitText(workspace, ["worktree", "add", "--detach", path, baseGitSha]);
+            worktrees.push({
+                candidateId: id,
+                modelId: model.id,
+                branchName,
+                path,
+                baseGitSha,
+                snapshotHash,
+                sealed: false,
+                cleaned: false
+            });
+        }
+    }
+    catch (error) {
+        // A mid-loop failure must not leak the worktrees already added or the root.
+        for (const worktree of worktrees) {
+            gitText(workspace, ["worktree", "remove", "--force", worktree.path], { allowFail: true });
+        }
+        rmSync(root, { recursive: true, force: true });
+        throw error;
+    }
+    return { workspace, baseGitSha, snapshotHash, root, worktrees };
+}
+export function sealCandidateWorktree(worktree) {
+    return Object.freeze({ ...worktree, sealed: true });
+}
+export function cleanupCandidateWorktree(workspace, worktree) {
+    gitText(workspace, ["worktree", "remove", "--force", worktree.path], { allowFail: true });
+    rmSync(worktree.path, { recursive: true, force: true });
+    return Object.freeze({ ...worktree, cleaned: true });
+}
+export function cleanupWorktreePlan(plan) {
+    const cleaned = plan.worktrees.map((worktree) => cleanupCandidateWorktree(plan.workspace, worktree));
+    rmSync(plan.root, { recursive: true, force: true });
+    return cleaned;
+}
+export function diffCandidateWorktree(worktree) {
+    gitText(worktree.path, ["add", "-A"], { allowFail: true });
+    return gitText(worktree.path, ["diff", "--cached", "--binary", worktree.baseGitSha], {
+        allowFail: true
+    });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@fusionkit/ensemble",
+  "private": false,
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/ensemble"
+  },
+  "description": "Harness-agnostic ensemble runner that emits model-fusion protocol records.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@fusionkit/adapter-ai-sdk": "0.1.0",
+    "@fusionkit/protocol": "0.1.0",
+    "@fusionkit/model-gateway": "0.1.0",
+    "@fusionkit/runner": "0.1.0",
+    "@fusionkit/session-harness": "0.1.0",
+    "@fusionkit/workspace": "0.1.0"
+  }
+}