@fusionkit/cli 0.1.0

package/dist/fusion-quickstart.d.ts

@@ -0,0 +1,182 @@
+/**
+ * `fusionkit <tool>` — one command, everything real.
+ *
+ * Spawns a real model panel (a cloud trio by default, or the local MLX trio
+ * with `--local`), starts the Fusion Harness Gateway over a real model-backed
+ * coding harness (each panel model produces a real candidate patch in its own
+ * git worktree on a real repo) with real judge synthesis (FusionKit, run via
+ * `uvx`), then launches the chosen coding agent (Codex / Claude Code / Cursor)
+ * pre-wired to the gateway. One Ctrl+C tears the whole stack down.
+ *
+ * No mocks: the panel is real models, candidates are real patches verified by
+ * really running the repo's tests, and the judge is a real model.
+ */
+import type { ChildProcess } from "node:child_process";
+import type { EnsembleModel } from "@fusionkit/ensemble";
+export type FusionTool = "codex" | "claude" | "cursor" | "serve";
+export declare const FUSION_TOOLS: readonly FusionTool[];
+export type PanelProvider = "mlx" | "openai" | "anthropic" | "google" | "openai-compatible";
+/**
+ * One panel model. `mlx` models run locally via the in-repo provisioner; cloud
+ * providers (openai/anthropic/google/openai-compatible) are fronted as
+ * OpenAI-compatible endpoints by FusionKit's `serve-endpoint` command, run via
+ * `uvx fusionkit` (no checkout required).
+ */
+export type PanelModelSpec = {
+    id: string;
+    model: string;
+    provider?: PanelProvider;
+    baseUrl?: string;
+    keyEnv?: string;
+};
+/**
+ * The PyPI version of the `fusionkit` Python distribution that provides the
+ * synthesizer (`fusionkit serve`) and the single-model OpenAI shim
+ * (`fusionkit serve-endpoint`). Pinned so `uvx` resolves a reproducible build.
+ */
+export declare const FUSIONKIT_PYPI_VERSION = "0.1.0";
+/**
+ * Default cloud panel — works cross-platform with only `OPENAI_API_KEY` and
+ * `ANTHROPIC_API_KEY` set. The judge defaults to the first entry.
+ */
+export declare const DEFAULT_CLOUD_PANEL: readonly PanelModelSpec[];
+/** The locally cached MLX trio (Apple Silicon only) used behind `--local`. */
+export declare const DEFAULT_TRIO: readonly PanelModelSpec[];
+/**
+ * How to invoke the `fusionkit` Python CLI: from PyPI via `uvx` by default
+ * (no checkout), or from a local checkout via `uv run` when `fusionkitDir` is
+ * given (a dev override). Returns the command plus the argv prefix that
+ * precedes the subcommand (`serve`, `serve-endpoint`, ...).
+ */
+export declare function fusionkitPyCommand(fusionkitDir?: string): {
+    command: string;
+    prefix: string[];
+    cwd?: string;
+};
+/**
+ * Parse a `.env` file (KEY=VALUE lines, `#` comments, optional `export`,
+ * single/double quotes) and fill any keys not already present in `env`.
+ * Existing env values win, so an explicitly exported key is never overridden.
+ */
+export declare function loadEnvFileInto(path: string, env: Record<string, string | undefined>): void;
+/** Default env var holding the API key for each cloud provider. */
+export declare function defaultKeyEnv(provider: PanelProvider): string | undefined;
+/** The git repository root containing `dir`, or undefined if it is not in a repo. */
+export declare function gitToplevel(dir: string): string | undefined;
+/**
+ * Compute the binaries and API keys the run requires given the tool, panel, and
+ * options. Pre-running endpoints (`--model-endpoint`) and a pre-running
+ * `--synthesis-url` drop the corresponding requirements.
+ */
+export declare function preflightRequirements(tool: FusionTool, models: PanelModelSpec[], options: RunFusionOptions): {
+    requiredBins: string[];
+    requiredEnv: string[];
+};
+/** Fixed port for the local observability dashboard (the scope app). */
+export declare const SCOPE_DASHBOARD_PORT = 4317;
+/**
+ * Locate the isolated scope dashboard app (handoffkit/apps/scope) by walking up
+ * from this module. Works from both the compiled dist and src layouts.
+ */
+export declare function findScopeAppDir(): string;
+export type Observability = {
+    url: string;
+    ingestUrl: string;
+    traceDir: string;
+    close: () => Promise<void>;
+};
+/**
+ * Build the scope dashboard once and `next start` it on the fixed port, backed
+ * by a fresh per-run SQLite file and trace dir. Returns the URLs the caller
+ * injects (as FUSION_TRACE_URL / FUSION_TRACE_DIR) into every spawned process.
+ */
+export declare function startObservability(input: {
+    log: (line: string) => void;
+}): Promise<Observability>;
+export type ModelServers = {
+    endpoints: Record<string, string>;
+    judgeUrl: string;
+    judgeModel: string;
+    models: EnsembleModel[];
+    close: () => Promise<void>;
+};
+/**
+ * Bring up one real model server per panel model and return an id -> base URL
+ * map. `mlx` specs run locally; cloud specs are fronted by FusionKit. When
+ * `endpoints` is supplied (pre-running servers or tests), those are used
+ * verbatim and nothing is spawned.
+ */
+export declare function startModelServers(options: {
+    specs: PanelModelSpec[];
+    endpoints?: Record<string, string>;
+    fusionkitDir?: string;
+    log: (line: string) => void;
+}): Promise<ModelServers>;
+export type FusionStack = {
+    fusionUrl: string;
+    endpoints: Record<string, string>;
+    close: () => Promise<void>;
+};
+export type StartFusionStackOptions = {
+    repo: string;
+    outputRoot: string;
+    models: PanelModelSpec[];
+    endpoints?: Record<string, string>;
+    fusionkitDir?: string;
+    judgeModel?: string;
+    /** Pre-running fusionkit serve URL for trajectory synthesis (skips spawn). */
+    synthesisUrl?: string;
+    host?: string;
+    port?: number;
+    authToken?: string;
+    timeoutMs?: number;
+    log: (line: string) => void;
+};
+/**
+ * Spawn a `fusionkit serve` as the trajectory-synthesis backend, configured
+ * with the judge model. FusionKit owns synthesis, so the agent harness fuses
+ * its trajectories through this server's `/v1/fusion/trajectories:fuse`.
+ */
+export declare function startSynthesisServer(input: {
+    fusionkitDir?: string;
+    judgeModel: string;
+    judgeBaseUrl: string;
+    env: Record<string, string | undefined>;
+    log: (line: string) => void;
+}): Promise<{
+    url: string;
+    child: ChildProcess;
+}>;
+export declare function startFusionStack(options: StartFusionStackOptions): Promise<FusionStack>;
+/**
+ * Start the Cursorkit bridge with its local-model backend pointed at the fusion
+ * gateway, and resolve once it is listening. Returns the child and its port.
+ */
+export declare function startCursorBridge(input: {
+    cursorKitDir: string;
+    fusionUrl: string;
+    log: (line: string) => void;
+}): Promise<{
+    child: ChildProcess;
+    port: number;
+}>;
+export type RunFusionOptions = {
+    models?: PanelModelSpec[];
+    endpoints?: Record<string, string>;
+    fusionkitDir?: string;
+    repo?: string;
+    judgeModel?: string;
+    synthesisUrl?: string;
+    cursorKitDir?: string;
+    authToken?: string;
+    port?: number;
+    timeoutMs?: number;
+    /** Use the local MLX panel trio (Apple Silicon) instead of the cloud panel. */
+    local?: boolean;
+    /** Boot the local scope dashboard and stream trace events into it. */
+    observe?: boolean;
+    log?: (line: string) => void;
+};
+export declare function runFusion(tool: FusionTool, toolArgs: string[], options?: RunFusionOptions): Promise<number>;
+/** Interactive tool picker for when no `--tool` was provided on a TTY. */
+export declare function pickTool(): Promise<FusionTool>;