@fusionkit/tools 0.1.6

package/dist/candidate.d.ts

@@ -0,0 +1,17 @@
+import type { JsonValue } from "@fusionkit/protocol";
+import type { EnsembleDescriptor, EnsembleModel, HarnessCandidateOutput } from "@fusionkit/ensemble";
+/**
+ * Build the standard "skipped" candidate output shared by the per-tool harness
+ * adapters (a capability gate failed, the binary was missing, the runner threw,
+ * ...). Each adapter supplies its lowercase `adapter` id, the human transcript,
+ * and any adapter-specific metadata.
+ */
+export declare function buildSkippedCandidate(input: {
+    descriptor: EnsembleDescriptor;
+    model: EnsembleModel;
+    ordinal: number;
+    reason: string;
+    adapter: string;
+    transcript: string;
+    metadata?: Record<string, JsonValue>;
+}): HarnessCandidateOutput;

package/dist/candidate.js

@@ -0,0 +1,40 @@
+import { artifactHash } from "@fusionkit/protocol";
+/**
+ * Build the standard "skipped" candidate output shared by the per-tool harness
+ * adapters (a capability gate failed, the binary was missing, the runner threw,
+ * ...). Each adapter supplies its lowercase `adapter` id, the human transcript,
+ * and any adapter-specific metadata.
+ */
+export function buildSkippedCandidate(input) {
+    const { descriptor, model, ordinal, reason, adapter, transcript } = input;
+    const hash = artifactHash(transcript);
+    return {
+        candidateId: `${descriptor.id}_${model.id}_${ordinal}`,
+        model,
+        status: "skipped",
+        transcript,
+        log: transcript,
+        artifacts: [
+            {
+                artifact_id: `artifact_${descriptor.id}_${model.id}_${adapter}_skip`,
+                kind: "log",
+                hash,
+                redaction_status: "synthetic"
+            }
+        ],
+        verification: {
+            status: "skipped",
+            evidence: [reason]
+        },
+        error: {
+            kind: "capability_missing",
+            message: reason,
+            retryable: false
+        },
+        metadata: {
+            adapter,
+            ...input.metadata,
+            skip_reason: reason
+        }
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared brand/model constants used by the launchers and the Cursor bridge, kept
+ * in one place so the value is defined once rather than copied per tool package.
+ */
+/** Provider/model label a tool advertises for the gateway-backed local model. */
+export declare const LOCAL_MODEL_LABEL = "fusionkit-local";
+/** The model name the Cursor bridge exposes to cursor-agent. */
+export declare const CURSOR_BRIDGE_MODEL_NAME = "local-fusion";
+/** The model label the fusion panel is fronted under. */
+export declare const FUSION_PANEL_MODEL = "fusion-panel";

package/dist/constants.js

@@ -0,0 +1,10 @@
+/**
+ * Shared brand/model constants used by the launchers and the Cursor bridge, kept
+ * in one place so the value is defined once rather than copied per tool package.
+ */
+/** Provider/model label a tool advertises for the gateway-backed local model. */
+export const LOCAL_MODEL_LABEL = "fusionkit-local";
+/** The model name the Cursor bridge exposes to cursor-agent. */
+export const CURSOR_BRIDGE_MODEL_NAME = "local-fusion";
+/** The model label the fusion panel is fronted under. */
+export const FUSION_PANEL_MODEL = "fusion-panel";

package/dist/env-compat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Naming compatibility: the project is standardizing on `FUSIONKIT_*` env vars
+ * but still accepts the legacy `WARRANT_*` names. Read canonical names through
+ * these helpers so both keep working; prefer the canonical name in new code,
+ * docs, and help text.
+ */
+type Env = Record<string, string | undefined>;
+/** The legacy `WARRANT_*` spelling of a canonical `FUSIONKIT_*` name, if any. */
+export declare function legacyEnvName(name: string): string | undefined;
+/** Read a canonical `FUSIONKIT_*` env var, falling back to the legacy `WARRANT_*` name. */
+export declare function readEnv(env: Env, name: string): string | undefined;
+/** True when the canonical or legacy env flag is set to `1`/`true`. */
+export declare function envFlagEnabled(env: Env, name: string): boolean;
+export {};

package/dist/env-compat.js

@@ -0,0 +1,27 @@
+/**
+ * Naming compatibility: the project is standardizing on `FUSIONKIT_*` env vars
+ * but still accepts the legacy `WARRANT_*` names. Read canonical names through
+ * these helpers so both keep working; prefer the canonical name in new code,
+ * docs, and help text.
+ */
+const CANONICAL_ENV_PREFIX = "FUSIONKIT_";
+const LEGACY_ENV_PREFIX = "WARRANT_";
+/** The legacy `WARRANT_*` spelling of a canonical `FUSIONKIT_*` name, if any. */
+export function legacyEnvName(name) {
+    return name.startsWith(CANONICAL_ENV_PREFIX)
+        ? LEGACY_ENV_PREFIX + name.slice(CANONICAL_ENV_PREFIX.length)
+        : undefined;
+}
+/** Read a canonical `FUSIONKIT_*` env var, falling back to the legacy `WARRANT_*` name. */
+export function readEnv(env, name) {
+    const direct = env[name];
+    if (direct !== undefined)
+        return direct;
+    const legacy = legacyEnvName(name);
+    return legacy !== undefined ? env[legacy] : undefined;
+}
+/** True when the canonical or legacy env flag is set to `1`/`true`. */
+export function envFlagEnabled(env, name) {
+    const value = readEnv(env, name);
+    return value === "1" || value?.toLowerCase() === "true";
+}

package/dist/env.d.ts

@@ -0,0 +1,15 @@
+/** Shared environment helpers used by the per-tool harness/launch packages. */
+type ToolEnv = Record<string, string | undefined>;
+/** Drop `undefined` values so the result is a concrete `Record<string,string>`. */
+export declare function definedEnv(env: ToolEnv): Record<string, string>;
+/** Ensure an OpenAI-style base URL ends in `/v1` (trimming trailing slashes). */
+export declare function normalizeApiBaseUrl(baseUrl: string): string;
+/** Default env prefixes scrubbed before spawning a Cursorkit bridge. */
+export declare const DEFAULT_BRIDGE_SCRUB_PREFIXES: readonly ["BRIDGE_", "MODEL_", "CURSOR_UPSTREAM"];
+/**
+ * Copy `env` dropping `undefined` values and any key starting with one of
+ * `prefixes`, so a parent's leftover bridge/model config never leaks into a
+ * freshly spawned bridge process.
+ */
+export declare function scrubBridgeEnv(env: ToolEnv, prefixes?: readonly string[]): Record<string, string>;
+export {};

package/dist/env.js

@@ -0,0 +1,37 @@
+/** Shared environment helpers used by the per-tool harness/launch packages. */
+/** Drop `undefined` values so the result is a concrete `Record<string,string>`. */
+export function definedEnv(env) {
+    const result = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
+/** Ensure an OpenAI-style base URL ends in `/v1` (trimming trailing slashes). */
+export function normalizeApiBaseUrl(baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
+}
+/** Default env prefixes scrubbed before spawning a Cursorkit bridge. */
+export const DEFAULT_BRIDGE_SCRUB_PREFIXES = [
+    "BRIDGE_",
+    "MODEL_",
+    "CURSOR_UPSTREAM"
+];
+/**
+ * Copy `env` dropping `undefined` values and any key starting with one of
+ * `prefixes`, so a parent's leftover bridge/model config never leaks into a
+ * freshly spawned bridge process.
+ */
+export function scrubBridgeEnv(env, prefixes = DEFAULT_BRIDGE_SCRUB_PREFIXES) {
+    const result = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (prefixes.some((prefix) => key.startsWith(prefix)))
+            continue;
+        result[key] = value;
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { distillLog, freePort, sleep, spawnLogged, spawnTool, terminate, waitForHttp, waitForOutput } from "./proc.js";
+export type { LoggedChild, LoggedSpawnOptions } from "./proc.js";
+export type { ToolDashboardLiveSmoke, ToolDashboardMetadata, ToolDashboardSmoke, ToolHarnessMetadata, ToolIntegration, ToolLaunchContext, ToolLaunchMode } from "./types.js";
+export { createToolRegistry } from "./registry.js";
+export type { ToolRegistry } from "./registry.js";
+export { CURSOR_BRIDGE_MODEL_NAME, FUSION_PANEL_MODEL, LOCAL_MODEL_LABEL } from "./constants.js";
+export { envFlagEnabled, legacyEnvName, readEnv } from "./env-compat.js";
+export { DEFAULT_BRIDGE_SCRUB_PREFIXES, definedEnv, normalizeApiBaseUrl, scrubBridgeEnv } from "./env.js";
+export { buildSkippedCandidate } from "./candidate.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { distillLog, freePort, sleep, spawnLogged, spawnTool, terminate, waitForHttp, waitForOutput } from "./proc.js";
+export { createToolRegistry } from "./registry.js";
+export { CURSOR_BRIDGE_MODEL_NAME, FUSION_PANEL_MODEL, LOCAL_MODEL_LABEL } from "./constants.js";
+export { envFlagEnabled, legacyEnvName, readEnv } from "./env-compat.js";
+export { DEFAULT_BRIDGE_SCRUB_PREFIXES, definedEnv, normalizeApiBaseUrl, scrubBridgeEnv } from "./env.js";
+export { buildSkippedCandidate } from "./candidate.js";

package/dist/proc.d.ts

@@ -0,0 +1,72 @@
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+/** Shared process helpers for the CLI's launcher/gateway flows and tool packages. */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Reserve an ephemeral loopback port and return it. The probe socket is closed
+ * before returning (children bind it themselves), but the number is held out of
+ * circulation briefly so concurrent callers do not collide. Retries a bounded
+ * number of times if the OS hands back a number we just reserved.
+ */
+export declare function freePort(): Promise<number>;
+/**
+ * Spawn a foreground tool with inherited stdio and resolve with its exit code.
+ * A spawn failure (e.g. binary not on PATH) rejects rather than emitting an
+ * unhandled `error` event.
+ */
+export declare function spawnTool(command: string, args: string[], env: Record<string, string>, cwd?: string): Promise<number>;
+export type LoggedSpawnOptions = SpawnOptions & {
+    /** Tee the child's full stdout+stderr to this path for post-mortem. */
+    logFile?: string;
+    /** Cap the in-memory ring buffer (default 256 KiB). */
+    maxLogBytes?: number;
+};
+/**
+ * A spawned background child with captured output and a recorded spawn error.
+ * Always attaches an `'error'` listener so a missing binary surfaces as a clear
+ * message via {@link waitForHttp} instead of crashing the process. The captured
+ * log is a bounded ring buffer (so long sessions cannot leak memory); the full,
+ * untruncated output is written to `logFile` when one is provided.
+ */
+export type LoggedChild = {
+    child: ChildProcess;
+    /** The most recent captured stdout+stderr, up to the ring-buffer cap. */
+    log: () => string;
+    /** The spawn `'error'` (e.g. ENOENT), if one was emitted. */
+    spawnError: () => Error | undefined;
+    /** The full log file path, when teeing was requested. */
+    logFile: () => string | undefined;
+    /** Flush and close the log file stream (best-effort). */
+    closeLog: () => void;
+};
+export declare function spawnLogged(command: string, args: string[], options?: LoggedSpawnOptions): LoggedChild;
+/**
+ * Distill the most useful slice of captured output for an error message. Prefers
+ * lines that look like errors (so the root cause is not buried under `uvx`
+ * resolve/build noise), then falls back to the head and tail of the log. The
+ * full log lives in the child's `logFile` when one was provided.
+ */
+export declare function distillLog(raw: string, options?: {
+    maxLines?: number;
+}): string;
+/**
+ * Poll `probeUrl` until it answers (optionally requiring a 2xx), the child fails
+ * to spawn, the child exits, or the timeout elapses. Distinguishes a failed
+ * spawn ("uv: not found") from a slow start.
+ */
+export declare function waitForHttp(probeUrl: string, proc: LoggedChild, options: {
+    timeoutMs: number;
+    label: string;
+    requireOk?: boolean;
+}): Promise<void>;
+/** Resolve once `pattern` is seen on the child's output, or reject on exit/timeout. */
+export declare function waitForOutput(proc: LoggedChild, pattern: RegExp, options: {
+    timeoutMs: number;
+    label: string;
+}): Promise<void>;
+/**
+ * SIGTERM a child's whole process group, escalating to SIGKILL if it ignores the
+ * grace period. Killing the group (`process.kill(-pid, ...)`) tears down wrapper
+ * trees like `uvx -> uv -> python`; if the child was not spawned detached (no
+ * group), it falls back to signalling the child directly.
+ */
+export declare function terminate(child: ChildProcess, graceMs?: number): void;

package/dist/proc.js

@@ -0,0 +1,230 @@
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { createServer } from "node:net";
+/** Shared process helpers for the CLI's launcher/gateway flows and tool packages. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Ports we have handed out very recently but whose child may not have bound
+// yet. Holding them out of circulation for a short window closes the race where
+// two concurrent `freePort()` callers (parallel server startup) receive the
+// same number between the probe socket closing and the child binding.
+const recentlyReserved = new Map();
+const RESERVATION_MS = 5000;
+function reserve(port) {
+    const existing = recentlyReserved.get(port);
+    if (existing !== undefined)
+        clearTimeout(existing);
+    const timer = setTimeout(() => recentlyReserved.delete(port), RESERVATION_MS);
+    timer.unref();
+    recentlyReserved.set(port, timer);
+}
+/**
+ * Reserve an ephemeral loopback port and return it. The probe socket is closed
+ * before returning (children bind it themselves), but the number is held out of
+ * circulation briefly so concurrent callers do not collide. Retries a bounded
+ * number of times if the OS hands back a number we just reserved.
+ */
+export async function freePort() {
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const port = await probeEphemeralPort();
+        if (!recentlyReserved.has(port)) {
+            reserve(port);
+            return port;
+        }
+    }
+    // Extremely unlikely; fall back to whatever the OS last offered.
+    const port = await probeEphemeralPort();
+    reserve(port);
+    return port;
+}
+function probeEphemeralPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            const port = typeof address === "object" && address !== null ? address.port : 0;
+            server.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * Spawn a foreground tool with inherited stdio and resolve with its exit code.
+ * A spawn failure (e.g. binary not on PATH) rejects rather than emitting an
+ * unhandled `error` event.
+ */
+export function spawnTool(command, args, env, cwd) {
+    return new Promise((resolveExit, reject) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            env: { ...process.env, ...env },
+            ...(cwd !== undefined ? { cwd } : {})
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => resolveExit(code ?? 0));
+    });
+}
+/** Keep at most this many bytes of a child's captured output in memory. */
+const DEFAULT_MAX_LOG_BYTES = 256 * 1024;
+export function spawnLogged(command, args, options = {}) {
+    const { logFile, maxLogBytes, ...spawnOptions } = options;
+    const cap = maxLogBytes ?? DEFAULT_MAX_LOG_BYTES;
+    // `detached: true` makes the child its own process-group leader so that
+    // `terminate()` can signal the whole tree. This matters for wrappers like
+    // `uvx` (uvx -> uv -> python): signalling only the immediate child would
+    // orphan the grandchildren. Output is still piped; we never `unref()`, so the
+    // parent keeps managing the child's lifecycle.
+    const child = spawn(command, args, { ...spawnOptions, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    let buffer = "";
+    let spawnError;
+    let file;
+    if (logFile !== undefined) {
+        try {
+            file = createWriteStream(logFile, { flags: "a" });
+            // A broken log sink must never crash the run.
+            file.on("error", () => { });
+        }
+        catch {
+            file = undefined;
+        }
+    }
+    const onChunk = (chunk) => {
+        const text = chunk.toString("utf8");
+        file?.write(text);
+        buffer += text;
+        if (buffer.length > cap)
+            buffer = buffer.slice(buffer.length - cap);
+    };
+    child.stdout?.on("data", onChunk);
+    child.stderr?.on("data", onChunk);
+    child.on("error", (error) => (spawnError = error));
+    return {
+        child,
+        log: () => buffer,
+        spawnError: () => spawnError,
+        logFile: () => logFile,
+        closeLog: () => {
+            try {
+                file?.end();
+            }
+            catch {
+                // already closed
+            }
+        }
+    };
+}
+/**
+ * Distill the most useful slice of captured output for an error message. Prefers
+ * lines that look like errors (so the root cause is not buried under `uvx`
+ * resolve/build noise), then falls back to the head and tail of the log. The
+ * full log lives in the child's `logFile` when one was provided.
+ */
+export function distillLog(raw, options = {}) {
+    const maxLines = options.maxLines ?? 16;
+    const lines = raw.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length === 0)
+        return "";
+    const errorPattern = /error|exception|traceback|fatal|denied|unauthorized|forbidden|invalid|not found|refused|timed? ?out|missing|failed|panic|429|401|403|500/i;
+    const errorLines = lines.filter((line) => errorPattern.test(line));
+    if (errorLines.length > 0) {
+        return errorLines.slice(-maxLines).join("\n");
+    }
+    if (lines.length <= maxLines)
+        return lines.join("\n");
+    const head = lines.slice(0, Math.ceil(maxLines / 2));
+    const tail = lines.slice(-Math.floor(maxLines / 2));
+    return [...head, "...", ...tail].join("\n");
+}
+function failureDetail(proc) {
+    const distilled = distillLog(proc.log());
+    const logPath = proc.logFile();
+    const pathNote = logPath !== undefined ? `\n(full log: ${logPath})` : "";
+    return `${distilled}${pathNote}`;
+}
+/**
+ * Poll `probeUrl` until it answers (optionally requiring a 2xx), the child fails
+ * to spawn, the child exits, or the timeout elapses. Distinguishes a failed
+ * spawn ("uv: not found") from a slow start.
+ */
+export async function waitForHttp(probeUrl, proc, options) {
+    const deadline = Date.now() + options.timeoutMs;
+    let lastError = "";
+    while (Date.now() < deadline) {
+        const spawnError = proc.spawnError();
+        if (spawnError !== undefined) {
+            throw new Error(`${options.label} failed to start: ${spawnError.message}\n${failureDetail(proc)}`);
+        }
+        if (proc.child.exitCode !== null) {
+            throw new Error(`${options.label} exited (code ${proc.child.exitCode}) before becoming ready\n${failureDetail(proc)}`);
+        }
+        try {
+            const response = await fetch(probeUrl);
+            if (options.requireOk !== true || response.ok)
+                return;
+            lastError = `status ${response.status}`;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await sleep(400);
+    }
+    throw new Error(`${options.label} did not become ready within ${options.timeoutMs}ms (${lastError})\n${failureDetail(proc)}`);
+}
+/** Resolve once `pattern` is seen on the child's output, or reject on exit/timeout. */
+export function waitForOutput(proc, pattern, options) {
+    return new Promise((resolve, reject) => {
+        const deadline = setTimeout(() => {
+            cleanup();
+            reject(new Error(`${options.label} did not start within ${options.timeoutMs}ms:\n${failureDetail(proc)}`));
+        }, options.timeoutMs);
+        const poll = setInterval(() => {
+            if (proc.spawnError() !== undefined) {
+                cleanup();
+                reject(new Error(`${options.label} failed to start: ${proc.spawnError()?.message}\n${failureDetail(proc)}`));
+            }
+            else if (pattern.test(proc.log())) {
+                cleanup();
+                resolve();
+            }
+        }, 100);
+        const onExit = () => {
+            cleanup();
+            reject(new Error(`${options.label} exited before becoming ready:\n${failureDetail(proc)}`));
+        };
+        proc.child.once("exit", onExit);
+        function cleanup() {
+            clearTimeout(deadline);
+            clearInterval(poll);
+            proc.child.off("exit", onExit);
+        }
+    });
+}
+/**
+ * SIGTERM a child's whole process group, escalating to SIGKILL if it ignores the
+ * grace period. Killing the group (`process.kill(-pid, ...)`) tears down wrapper
+ * trees like `uvx -> uv -> python`; if the child was not spawned detached (no
+ * group), it falls back to signalling the child directly.
+ */
+export function terminate(child, graceMs = 5000) {
+    if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null)
+        return;
+    const pid = child.pid;
+    const signal = (sig) => {
+        try {
+            process.kill(-pid, sig);
+        }
+        catch {
+            try {
+                child.kill(sig);
+            }
+            catch {
+                // already gone
+            }
+        }
+    };
+    signal("SIGTERM");
+    const timer = setTimeout(() => signal("SIGKILL"), graceMs);
+    timer.unref();
+    child.once("exit", () => clearTimeout(timer));
+}

package/dist/registry.d.ts

@@ -0,0 +1,31 @@
+import type { HarnessAdapter, ToolHarnessResolveOptions, UnifiedHarnessKind } from "@fusionkit/ensemble";
+import type { ModelFusionSideEffects } from "@fusionkit/protocol";
+import type { ToolDashboardMetadata, ToolIntegration } from "./types.js";
+export type ToolRegistry = {
+    /** Resolve a tool by id or alias. */
+    get(idOrAlias: string): ToolIntegration | undefined;
+    /** All registered tools, in registration order. */
+    list(): ToolIntegration[];
+    /** Tools that can be launched behind the fusion panel. */
+    launchableFusion(): ToolIntegration[];
+    /** Tools that can be launched against a single local model. */
+    launchableLocal(): ToolIntegration[];
+    /** Build the ensemble harness adapter for a unified harness kind. */
+    harnessForKind(kind: UnifiedHarnessKind, options: ToolHarnessResolveOptions): HarnessAdapter;
+    /** Policy side-effects for a tool-backed harness kind. */
+    sideEffectsForKind(kind: UnifiedHarnessKind): ModelFusionSideEffects;
+    /** Judge response-shape hint for a tool-backed harness kind. */
+    responseShapeForKind(kind: UnifiedHarnessKind): string;
+    /** All unified harness kinds answered by a registered tool. */
+    harnessKinds(): UnifiedHarnessKind[];
+    /** Dashboard metadata for tools that provide it, in registration order. */
+    dashboardTools(): ToolDashboardMetadata[];
+};
+/**
+ * Assemble a tool registry from a fixed list of integrations. The CLI is the
+ * single place that knows every tool package, so it builds the registry here and
+ * wires it into both the launchers and (via `setToolAdapterResolver`) the
+ * ensemble harness gateway. Adding a tool is one new package plus one entry in
+ * the list the CLI passes here.
+ */
+export declare function createToolRegistry(integrations: readonly ToolIntegration[]): ToolRegistry;

package/dist/registry.js

@@ -0,0 +1,60 @@
+/**
+ * Assemble a tool registry from a fixed list of integrations. The CLI is the
+ * single place that knows every tool package, so it builds the registry here and
+ * wires it into both the launchers and (via `setToolAdapterResolver`) the
+ * ensemble harness gateway. Adding a tool is one new package plus one entry in
+ * the list the CLI passes here.
+ */
+export function createToolRegistry(integrations) {
+    const byKey = new Map();
+    for (const integration of integrations) {
+        byKey.set(integration.id, integration);
+        for (const alias of integration.aliases ?? []) {
+            byKey.set(alias, integration);
+        }
+    }
+    const harnessIndex = new Map();
+    for (const integration of integrations) {
+        for (const kind of integration.harnessKinds) {
+            harnessIndex.set(kind, integration);
+        }
+    }
+    const toolForKind = (kind) => {
+        const integration = harnessIndex.get(kind);
+        if (integration === undefined) {
+            throw new Error(`no tool integration provides a harness for kind "${kind}"`);
+        }
+        return integration;
+    };
+    return {
+        get: (idOrAlias) => byKey.get(idOrAlias),
+        list: () => [...integrations],
+        launchableFusion: () => integrations.filter((tool) => tool.modes.includes("fusion")),
+        launchableLocal: () => integrations.filter((tool) => tool.modes.includes("local")),
+        harnessForKind: (kind, options) => {
+            const integration = toolForKind(kind);
+            if (integration.createHarness === undefined) {
+                throw new Error(`tool "${integration.id}" has no harness factory for kind "${kind}"`);
+            }
+            return integration.createHarness(kind, options);
+        },
+        sideEffectsForKind: (kind) => {
+            const harness = toolForKind(kind).harness;
+            if (harness === undefined) {
+                throw new Error(`tool for kind "${kind}" has no harness metadata`);
+            }
+            return harness.sideEffects;
+        },
+        responseShapeForKind: (kind) => {
+            const harness = toolForKind(kind).harness;
+            if (harness === undefined) {
+                throw new Error(`tool for kind "${kind}" has no harness metadata`);
+            }
+            return harness.responseShape;
+        },
+        harnessKinds: () => integrations.flatMap((tool) => [...tool.harnessKinds]),
+        dashboardTools: () => integrations
+            .map((tool) => tool.dashboard)
+            .filter((dashboard) => dashboard !== undefined)
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,133 @@
+import type { EnsembleModel, HarnessAdapter, HarnessCapabilities, ToolHarnessResolveOptions, UnifiedHarnessKind } from "@fusionkit/ensemble";
+import type { ModelFusionHarnessKind, ModelFusionSideEffects } from "@fusionkit/protocol";
+type ToolEnv = Record<string, string | undefined>;
+/**
+ * How a tool is being launched: behind the real fusion panel (`fusion`) or
+ * backed by a single local model (`local`). The same `ToolIntegration.launch`
+ * handles both; the context's `mode` lets a tool branch where the two differ
+ * (e.g. Cursor spawns a bridge in fusion mode but prints tunnel setup locally).
+ */
+export type ToolLaunchMode = "fusion" | "local";
+/**
+ * Everything a tool needs from the host to launch its real binary, injected so
+ * tool packages never import the CLI (which would be a dependency cycle). The
+ * host wires these to its process/portless/teardown machinery.
+ */
+export type ToolLaunchContext = {
+    mode: ToolLaunchMode;
+    /** Gateway base URL the tool should point its model provider at. */
+    gatewayUrl: string;
+    /** The model name/label the launched tool advertises in its own UI. */
+    modelLabel: string;
+    /** Arguments forwarded verbatim to the tool binary. */
+    toolArgs: string[];
+    /** The repository the tool runs in (defaults to the process cwd). */
+    repo?: string;
+    /** Bearer token the gateway requires, when set. */
+    authToken?: string;
+    /** Portless CA path so spawned children trust the proxy's HTTPS routes. */
+    caCertPath?: string;
+    /** Directory for per-tool log files (e.g. the Cursor bridge log). */
+    logsDir?: string;
+    /** Public tunnel URL for tools that cannot reach loopback (local Cursor). */
+    publicUrl?: string;
+    /** Line logger. */
+    log: (line: string) => void;
+    /**
+     * Quiesce host UI (live checklist, cursor) before the tool inherits the
+     * terminal. A no-op in non-interactive/local flows.
+     */
+    prepareForPassthrough: () => void;
+    /** Register a named port with the host (e.g. portless) and return its URL. */
+    registerPort: (name: string, port: number) => string;
+    /** Release a previously registered named port. */
+    unregisterPort: (name: string) => void;
+    /** Register a teardown callback run on shutdown (reverse order). */
+    registerDisposer: (dispose: () => void | Promise<void>) => void;
+};
+/**
+ * Harness-level metadata for a tool, used by the ensemble harness gateway/e2e
+ * matrix so it never has to `switch` over tool names. Applies to every
+ * `harnessKind` the tool answers for.
+ */
+export type ToolHarnessMetadata = {
+    /** Protocol harness kind stamped on records. */
+    harnessKind: ModelFusionHarnessKind;
+    /** Policy side-effects the harness needs. */
+    sideEffects: ModelFusionSideEffects;
+    /** Judge response-shape hint for synthesis. */
+    responseShape: string;
+};
+/** The credential-skip-style smoke run for the dashboard's `credential-skip` task. */
+export type ToolDashboardSmoke = {
+    taskId: string;
+    model: EnsembleModel;
+    sideEffects: ModelFusionSideEffects;
+    allowedTools: string[];
+    /** Build the harness used for the (empty-env) credential-skip smoke. */
+    makeHarness: () => HarnessAdapter;
+};
+/** The optional env-gated live smoke for the dashboard's `live` task. */
+export type ToolDashboardLiveSmoke = {
+    taskId: string;
+    /** Per-tool env flag that enables this live smoke. */
+    envName: string;
+    prompt: string;
+    /** Env var holding a model override, and the default when unset. */
+    modelEnvName: string;
+    defaultModel: string;
+    /** Build the live harness (real credentials) for the given env. */
+    makeHarness: (env: ToolEnv) => HarnessAdapter;
+};
+/**
+ * Dashboard metadata for a tool, used by `fusionkit ensemble dashboard` to build
+ * the capability matrix, smoke records, and readiness rows from the registry
+ * instead of a hardcoded per-tool table.
+ */
+export type ToolDashboardMetadata = {
+    /** Dashboard target id (e.g. "claude-code"), may differ from the tool id. */
+    id: string;
+    harnessKind: ModelFusionHarnessKind;
+    displayName: string;
+    availability: "available" | "credential_gated" | "missing";
+    /** Capability overlay merged onto the adapter's own capabilities. */
+    capabilities: HarnessCapabilities;
+    notes: string[];
+    /** Build the harness whose capabilities seed the matrix row. */
+    makeMatrixHarness: (env: ToolEnv) => HarnessAdapter;
+    /** Why the tool would skip for lack of credentials (undefined = ready). */
+    credentialSkipReason: (env: ToolEnv) => string | undefined;
+    smoke: ToolDashboardSmoke;
+    liveSmoke?: ToolDashboardLiveSmoke;
+};
+/**
+ * A single tool integration: its launcher (used by `fusionkit <tool>` and
+ * `fusionkit local <tool>`) plus, optionally, its ensemble harness factory (used
+ * by the harness gateway / e2e matrix). One package implements one of these and
+ * the CLI registers it.
+ */
+export type ToolIntegration = {
+    /** Stable id (e.g. "codex"). */
+    id: string;
+    /** Alternate selectors that resolve to this tool. */
+    aliases?: readonly string[];
+    /** Human-facing name for pickers and dashboards. */
+    displayName: string;
+    /** One-line hint shown in the interactive picker. */
+    pickerHint: string;
+    /** The PATH binary launched, when the tool spawns one. */
+    binary?: string;
+    /** Launch modes this tool supports. */
+    modes: readonly ToolLaunchMode[];
+    /** The unified harness kinds this tool's adapter answers for. */
+    harnessKinds: readonly UnifiedHarnessKind[];
+    /** Boot the tool against the host context; resolves with its exit code. */
+    launch(ctx: ToolLaunchContext): Promise<number>;
+    /** Build the ensemble harness adapter for one of this tool's kinds. */
+    createHarness?(kind: UnifiedHarnessKind, options: ToolHarnessResolveOptions): HarnessAdapter;
+    /** Harness metadata for the gateway/e2e matrix (set when `createHarness` is). */
+    harness?: ToolHarnessMetadata;
+    /** Dashboard metadata for `ensemble dashboard` (set when the tool has a harness). */
+    dashboard?: ToolDashboardMetadata;
+};
+export {};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@fusionkit/tools",
+  "private": false,
+  "version": "0.1.6",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/tools"
+  },
+  "description": "Tool integration contract (launcher + harness adapter) and registry that the fusionkit CLI wires per-tool packages into.",
+  "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/ensemble": "0.1.6",
+    "@fusionkit/protocol": "0.1.6"
+  }
+}