@fusionkit/adapter-ai-sdk 0.1.0

package/dist/mlx-env.js

@@ -0,0 +1,371 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+/**
+ * Warrant-owned MLX environment.
+ *
+ * The managed MLX backend does not shell out to whatever `mlx_lm.server`
+ * happens to be on PATH — it owns the entire stack. This provisioner
+ * materializes and maintains a dedicated directory containing:
+ *
+ *   <dir>/venv/      a private Python venv with mlx-lm at an exact pin
+ *   <dir>/env.json   a manifest of what was provisioned (and from where)
+ *   <dir>/hf-cache/  HF_HOME, so model weights live inside the owned dir
+ *   <dir>/logs/      server stdout/stderr
+ *
+ * The whole footprint is one directory: inspectable (info), verifiable
+ * (verify), repairable (re-provision on pin mismatch), and removable
+ * (destroy). The server process is always spawned via the venv's own
+ * interpreter — never a PATH lookup.
+ *
+ * The mlx-lm pin follows the same trusted-pin policy as the repo's npm
+ * allowlist: exact version, bumped only as a reviewed code change.
+ *
+ * Toolchain: provisioning prefers `uv` when available (an explicit path,
+ * WARRANT_UV, or PATH discovery) — it is much faster and can supply its own
+ * managed CPython, removing even the system-python requirement. Without uv
+ * it falls back to stdlib `python3 -m venv` + pip, so uv is an upgrade,
+ * never a dependency. uv's caches and managed interpreters are contained
+ * inside the owned directory, so destroy() removes them too.
+ */
+/** Exact-pinned mlx-lm version this provisioner installs. */
+export const MLX_LM_PIN = "0.31.3";
+/**
+ * The velum-labs/mlx-lm fork installed in structured mode: upstream mlx-lm
+ * plus the self-contained mlx_lm.structured package (see the fork's
+ * STRUCTURED.md). Pinned to the current reviewed head of the fork's main
+ * branch; refresh this SHA when we intentionally pick up fork fixes.
+ */
+export const MLX_LM_STRUCTURED_PIN = "mlx-lm[structured] @ git+https://github.com/velum-labs/mlx-lm@2ee2d570d365a1fcee9ba90a298f1bae865fccda";
+/** Python version requested from uv (which can download it if absent). */
+export const PYTHON_PIN = "3.12";
+/** Minimum Python the venv may be built from. */
+const MIN_PYTHON = { major: 3, minor: 9 };
+/** Default owned directory for the MLX stack. */
+export function defaultMlxDir() {
+    return join(homedir(), ".warrant", "mlx");
+}
+/** A capability the current host cannot satisfy (wrong OS, no Python). */
+export class MlxCapabilityError extends Error {
+    code = "capability_mismatch";
+    constructor(message) {
+        super(message);
+        this.name = "MlxCapabilityError";
+    }
+}
+/** Run a command; `extraEnv` overlays (never replaces) the process env. */
+function run(cmd, args, extraEnv) {
+    const result = spawnSync(cmd, args, {
+        encoding: "utf8",
+        ...(extraEnv ? { env: { ...process.env, ...extraEnv } } : {})
+    });
+    if (result.error) {
+        return { status: 127, stdout: "", stderr: result.error.message };
+    }
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? ""
+    };
+}
+function directorySizeBytes(dir) {
+    let total = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            total += directorySizeBytes(full);
+        else if (entry.isFile())
+            total += statSync(full).size;
+    }
+    return total;
+}
+export class MlxEnv {
+    dir;
+    packageSpec;
+    extraPackageSpecs;
+    importName;
+    extraImportNames;
+    serverModule;
+    requirePlatform;
+    explicitPython;
+    uvOption;
+    pythonVersion;
+    installHook;
+    provisionPromise;
+    constructor(options = {}) {
+        this.dir = options.dir ?? defaultMlxDir();
+        this.packageSpec = options.packageSpec ?? `mlx-lm==${MLX_LM_PIN}`;
+        this.extraPackageSpecs = options.extraPackageSpecs ?? [];
+        this.importName = options.importName ?? "mlx_lm";
+        this.extraImportNames = options.extraImportNames ?? [];
+        this.serverModule = options.serverModule;
+        this.requirePlatform = options.requirePlatform ?? true;
+        this.explicitPython = options.python;
+        this.uvOption = options.uv;
+        this.pythonVersion = options.pythonVersion ?? PYTHON_PIN;
+        this.installHook = options.install;
+    }
+    get manifestPath() {
+        return join(this.dir, "env.json");
+    }
+    get venvDir() {
+        return join(this.dir, "venv");
+    }
+    get venvPython() {
+        const binDir = process.platform === "win32" ? "Scripts" : "bin";
+        const exe = process.platform === "win32" ? "python.exe" : "python";
+        return join(this.venvDir, binDir, exe);
+    }
+    get hfCacheDir() {
+        return join(this.dir, "hf-cache");
+    }
+    get logsDir() {
+        return join(this.dir, "logs");
+    }
+    /** uv's caches and managed interpreters, contained in the owned dir. */
+    get uvEnv() {
+        return {
+            UV_CACHE_DIR: join(this.dir, "uv-cache"),
+            UV_PYTHON_INSTALL_DIR: join(this.dir, "uv-python")
+        };
+    }
+    readManifest() {
+        if (!existsSync(this.manifestPath))
+            return undefined;
+        try {
+            const parsed = JSON.parse(readFileSync(this.manifestPath, "utf8"));
+            if (parsed.version !== "warrant.mlxenv.v1" ||
+                typeof parsed.packageSpec !== "string" ||
+                typeof parsed.interpreterPath !== "string") {
+                return undefined;
+            }
+            if (parsed.extraPackageSpecs !== undefined &&
+                !(Array.isArray(parsed.extraPackageSpecs) &&
+                    parsed.extraPackageSpecs.every((spec) => typeof spec === "string"))) {
+                return undefined;
+            }
+            return parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    assertPlatform() {
+        if (!this.requirePlatform)
+            return;
+        if (process.platform !== "darwin" || process.arch !== "arm64") {
+            throw new MlxCapabilityError(`MLX requires macOS on Apple Silicon; this host is ${process.platform}/${process.arch}. ` +
+                "Use a cloud model (or handoffModel escalation) on this machine.");
+        }
+    }
+    /**
+     * Pick the provisioning toolchain. An explicit `python` option forces
+     * stdlib venv+pip with that interpreter; otherwise uv is preferred
+     * (explicit path, WARRANT_UV, or PATH discovery) with venv+pip as the
+     * no-extra-requirements fallback.
+     */
+    resolveToolchain() {
+        if (this.explicitPython !== undefined) {
+            return { kind: "venv-pip", python: this.checkPython(this.explicitPython) };
+        }
+        if (this.uvOption !== false) {
+            const explicitUv = this.uvOption ?? process.env.WARRANT_UV;
+            const candidate = explicitUv ?? "uv";
+            const probe = run(candidate, ["--version"]);
+            if (probe.status === 0) {
+                return {
+                    kind: "uv",
+                    bin: candidate,
+                    version: probe.stdout.trim().replace(/^uv\s+/, "")
+                };
+            }
+            // An explicitly requested uv that does not run is an error, not a
+            // silent fallback; PATH discovery falling through is expected.
+            if (explicitUv !== undefined) {
+                throw new MlxCapabilityError(`requested uv ("${candidate}") is not runnable: ${probe.stderr.trim() || "not found"}`);
+            }
+        }
+        return { kind: "venv-pip", python: this.checkPython("python3") };
+    }
+    /** Sanity-check a base interpreter for the stdlib venv+pip path. */
+    checkPython(candidate) {
+        const probe = run(candidate, [
+            "-c",
+            "import sys; print(f'{sys.version_info[0]}.{sys.version_info[1]}')"
+        ]);
+        if (probe.status !== 0) {
+            throw new MlxCapabilityError(`no usable Python interpreter ("${candidate}"): ${probe.stderr.trim() || "not found"} ` +
+                "(install python3, or install uv and Warrant will manage Python itself)");
+        }
+        const [major = 0, minor = 0] = probe.stdout.trim().split(".").map(Number);
+        if (major < MIN_PYTHON.major ||
+            (major === MIN_PYTHON.major && minor < MIN_PYTHON.minor)) {
+            throw new MlxCapabilityError(`Python ${probe.stdout.trim()} is too old; mlx-lm needs >= ${MIN_PYTHON.major}.${MIN_PYTHON.minor}`);
+        }
+        return candidate;
+    }
+    /** Does the venv interpreter exist and import the managed packages? */
+    importWorks() {
+        if (!existsSync(this.venvPython))
+            return false;
+        const imports = [this.importName, ...this.extraImportNames].join(", ");
+        return run(this.venvPython, ["-c", `import ${imports}`]).status === 0;
+    }
+    extrasMatch(manifest) {
+        const recorded = manifest.extraPackageSpecs ?? [];
+        return (recorded.length === this.extraPackageSpecs.length &&
+            recorded.every((spec, i) => spec === this.extraPackageSpecs[i]));
+    }
+    /** Manifest matches the current pins and the env actually works. */
+    verify() {
+        const manifest = this.readManifest();
+        return (manifest !== undefined &&
+            manifest.packageSpec === this.packageSpec &&
+            this.extrasMatch(manifest) &&
+            manifest.importName === this.importName &&
+            this.importWorks());
+    }
+    /** Manifest plus on-disk footprint of the owned directory. */
+    info() {
+        const manifest = this.readManifest();
+        return {
+            dir: this.dir,
+            provisioned: this.verify(),
+            ...(manifest ? { manifest } : {}),
+            diskBytes: existsSync(this.dir) ? directorySizeBytes(this.dir) : 0
+        };
+    }
+    /** Remove the entire owned footprint: venv, manifest, weights, logs. */
+    destroy() {
+        this.provisionPromise = undefined;
+        rmSync(this.dir, { recursive: true, force: true });
+    }
+    /**
+     * Idempotently provision the env. A matching manifest plus a passing
+     * import check is a no-op; anything else (fresh host, pin bump, broken
+     * venv) provisions in place. Concurrent callers share one provision run.
+     */
+    ensureProvisioned() {
+        const existing = this.readManifest();
+        if (existing && this.verify())
+            return Promise.resolve(existing);
+        if (!this.provisionPromise) {
+            this.provisionPromise = this.provision().finally(() => {
+                this.provisionPromise = undefined;
+            });
+        }
+        return this.provisionPromise;
+    }
+    async provision() {
+        this.assertPlatform();
+        const toolchain = this.resolveToolchain();
+        mkdirSync(this.dir, { recursive: true });
+        mkdirSync(this.hfCacheDir, { recursive: true });
+        mkdirSync(this.logsDir, { recursive: true });
+        // A stale or pin-mismatched venv is rebuilt from scratch rather than
+        // upgraded in place: rebuilds are cheap and exact, upgrades are neither.
+        if (existsSync(this.venvDir)) {
+            rmSync(this.venvDir, { recursive: true, force: true });
+        }
+        this.createVenv(toolchain);
+        if (this.installHook) {
+            this.installHook(this.venvPython, this.packageSpec, this.extraPackageSpecs);
+        }
+        else {
+            this.installPackages(toolchain);
+        }
+        if (!this.importWorks()) {
+            const imports = [this.importName, ...this.extraImportNames].join(", ");
+            throw new Error(`provisioned env cannot import "${imports}"; the install is broken`);
+        }
+        const versionProbe = run(this.venvPython, [
+            "-c",
+            "import sys; print(f'{sys.version_info[0]}.{sys.version_info[1]}.{sys.version_info[2]}')"
+        ]);
+        const manifest = {
+            version: "warrant.mlxenv.v1",
+            packageSpec: this.packageSpec,
+            extraPackageSpecs: this.extraPackageSpecs,
+            importName: this.importName,
+            toolchain: toolchain.kind === "uv"
+                ? `uv ${toolchain.version}`
+                : `venv+pip via ${toolchain.python}`,
+            interpreterPath: this.venvPython,
+            pythonVersion: versionProbe.stdout.trim(),
+            createdAt: new Date().toISOString()
+        };
+        writeFileSync(this.manifestPath, JSON.stringify(manifest, null, 2));
+        return manifest;
+    }
+    createVenv(toolchain) {
+        if (toolchain.kind === "uv") {
+            // uv resolves the pinned Python from the system or downloads a
+            // managed CPython into the owned dir — no system-python requirement.
+            const result = run(toolchain.bin, ["venv", "--python", this.pythonVersion, this.venvDir], this.uvEnv);
+            if (result.status !== 0) {
+                throw new MlxCapabilityError(`uv venv (python ${this.pythonVersion}) failed: ${result.stderr.trim() || result.stdout.trim()}`);
+            }
+            return;
+        }
+        const result = run(toolchain.python, ["-m", "venv", this.venvDir]);
+        if (result.status !== 0) {
+            throw new MlxCapabilityError(`failed to create venv with ${toolchain.python} -m venv: ${result.stderr.trim() || result.stdout.trim()}`);
+        }
+    }
+    installPackages(toolchain) {
+        const specs = [this.packageSpec, ...this.extraPackageSpecs];
+        const result = toolchain.kind === "uv"
+            ? run(toolchain.bin, ["pip", "install", "--python", this.venvPython, ...specs], this.uvEnv)
+            : run(this.venvPython, [
+                "-m",
+                "pip",
+                "install",
+                "--no-input",
+                "--disable-pip-version-check",
+                ...specs
+            ]);
+        if (result.status !== 0) {
+            throw new Error(`installing ${specs.join(", ")} failed: ${result.stderr.trim().slice(-2000)}`);
+        }
+    }
+    /**
+     * Provision (if needed) and produce the spawn spec for the server:
+     * the venv's interpreter running `-m mlx_lm server` with a minimal,
+     * explicit environment whose caches live inside the owned dir.
+     */
+    async prepare(model, port, extraArgs = []) {
+        await this.ensureProvisioned();
+        // The stock entry point is the `server` subcommand of the mlx_lm
+        // module; an override (e.g. the structured overlay) is a module that is
+        // itself the server and takes the same flags.
+        const moduleArgs = this.serverModule
+            ? ["-m", this.serverModule]
+            : ["-m", "mlx_lm", "server"];
+        return {
+            cmd: this.venvPython,
+            args: [
+                ...moduleArgs,
+                "--model",
+                model,
+                "--host",
+                "127.0.0.1",
+                "--port",
+                String(port),
+                ...extraArgs
+            ],
+            env: {
+                // Explicit, minimal environment: the venv's bin first (so any
+                // helper the server execs resolves inside the env), model caches
+                // contained in the owned dir, no inherited surprises.
+                PATH: [dirname(this.venvPython), "/usr/bin", "/bin"].join(delimiter),
+                HOME: homedir(),
+                HF_HOME: this.hfCacheDir,
+                HF_HUB_DISABLE_TELEMETRY: "1",
+                VIRTUAL_ENV: this.venvDir
+            },
+            cwd: this.dir,
+            logFile: join(this.logsDir, "server.log")
+        };
+    }
+}

package/dist/model.d.ts

@@ -0,0 +1,88 @@
+import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3StreamResult } from "@ai-sdk/provider";
+import type { Handoff, ModelDecision } from "@fusionkit/handoff";
+/**
+ * Why a call left the local model. Deterministic and observable: an error
+ * from the local provider, a context/token-length failure (classified from
+ * the error), a prompt-size threshold, or sticky escalation after a prior
+ * failure.
+ */
+export type EscalationReason = "local-error" | "context-overflow" | "prompt-threshold" | "sticky";
+export type HandoffModelConfig = {
+    /** The model work starts on. */
+    local: LanguageModelV3;
+    /** The model work escalates to. */
+    cloud: LanguageModelV3;
+    /**
+     * Escalate without trying local when the serialized prompt exceeds this
+     * many bytes — the deterministic stand-in for "context too large".
+     */
+    maxLocalPromptBytes?: number;
+    /**
+     * Once escalated, stay on the cloud model for subsequent calls in this
+     * model instance. Defaults to true: thrash-free and easier to reason
+     * about than per-call retries.
+     */
+    sticky?: boolean;
+    /** Observer for every routing decision (withModel wires this to h.trace). */
+    onDecision?: (decision: ModelDecision) => void;
+    /**
+     * Override the overflow classifier. Providers do not standardize
+     * context-overflow errors, so the default is a message heuristic; supply
+     * a provider-specific predicate when you know the exact error shape.
+     */
+    isContextOverflow?: (error: unknown) => boolean;
+};
+/**
+ * An AI SDK-compatible model that starts local and escalates to cloud
+ * under deterministic, explainable conditions. Honest semantics:
+ *
+ * - Escalation happens *between* generate/stream calls (a failed local call
+ *   is retried in full on the cloud model). There is no mid-generation
+ *   handoff: once a stream has started emitting, it belongs to the model
+ *   that produced it. A local stream that fails to *start* escalates; a
+ *   stream that dies midway surfaces the error to the caller.
+ * - Every routing decision is reported via onDecision, so a Handoff context
+ *   can record it (`model.routed` trace events) and triggers.modelEscalated()
+ *   can gate continuation.
+ */
+export declare class HandoffModel implements LanguageModelV3 {
+    readonly specificationVersion: "v3";
+    readonly provider = "warrant-handoff";
+    readonly modelId: string;
+    private readonly config;
+    private escalatedSticky;
+    constructor(config: HandoffModelConfig);
+    get supportedUrls(): LanguageModelV3["supportedUrls"];
+    private decide;
+    private note;
+    private markEscalated;
+    /**
+     * The one dispatch shared by doGenerate and doStream: route per `decide`,
+     * try local, classify a local failure, escalate to cloud, and report
+     * every decision. The two entry points differ only in which provider
+     * method runs and how a local failure is phrased.
+     */
+    private dispatch;
+    doGenerate(options: LanguageModelV3CallOptions): Promise<LanguageModelV3GenerateResult>;
+    doStream(options: LanguageModelV3CallOptions): Promise<LanguageModelV3StreamResult>;
+}
+/** Create an escalating local-first model. */
+export declare function handoffModel(config: HandoffModelConfig): HandoffModel;
+/**
+ * Attach a model to a continuation context as `h.model`. The single
+ * golden-shape attach used by both `withModel` and `withRoutedModel`;
+ * decision-to-trace mapping stays with each adapter, the composition does
+ * not.
+ */
+export declare function attachModel<H extends Handoff, M>(h: H, model: M): H & {
+    model: M;
+};
+/**
+ * The golden-shape composition for the model half: attach `h.model` to a
+ * continuation context. Routing decisions land in the context's trace as
+ * `model.routed` events, and escalations make triggers.modelEscalated()
+ * fire for `h.needs(...)`.
+ */
+export declare function withModel<H extends Handoff>(h: H, config: Omit<HandoffModelConfig, "onDecision">): H & {
+    model: HandoffModel;
+};

package/dist/model.js

@@ -0,0 +1,149 @@
+// Providers report context overflow as free-text error messages with no
+// standard code, so a message heuristic is the only provider-agnostic
+// default. Either reason escalates to cloud; the classification only
+// affects the recorded reason. Override via config.isContextOverflow.
+const OVERFLOW_PATTERN = /context|token|length|too.?(long|large)/i;
+function classify(error, isOverflow) {
+    if (isOverflow)
+        return isOverflow(error) ? "context-overflow" : "local-error";
+    const message = error instanceof Error ? error.message : String(error);
+    return OVERFLOW_PATTERN.test(message) ? "context-overflow" : "local-error";
+}
+/**
+ * Deterministic proxy for prompt size: the byte length of the serialized
+ * prompt. The threshold gate needs a cheap, stable measure that correlates
+ * with token count, not an exact tokenizer (which would be model-specific).
+ */
+function promptBytes(options) {
+    try {
+        return Buffer.byteLength(JSON.stringify(options.prompt), "utf8");
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * An AI SDK-compatible model that starts local and escalates to cloud
+ * under deterministic, explainable conditions. Honest semantics:
+ *
+ * - Escalation happens *between* generate/stream calls (a failed local call
+ *   is retried in full on the cloud model). There is no mid-generation
+ *   handoff: once a stream has started emitting, it belongs to the model
+ *   that produced it. A local stream that fails to *start* escalates; a
+ *   stream that dies midway surfaces the error to the caller.
+ * - Every routing decision is reported via onDecision, so a Handoff context
+ *   can record it (`model.routed` trace events) and triggers.modelEscalated()
+ *   can gate continuation.
+ */
+export class HandoffModel {
+    specificationVersion = "v3";
+    provider = "warrant-handoff";
+    modelId;
+    config;
+    escalatedSticky = false;
+    constructor(config) {
+        this.config = config;
+        this.modelId = `local-first(${config.local.modelId} → ${config.cloud.modelId})`;
+    }
+    get supportedUrls() {
+        return this.config.local.supportedUrls;
+    }
+    decide(options) {
+        if (this.escalatedSticky) {
+            return {
+                model: this.config.cloud,
+                route: "cloud",
+                escalated: false,
+                reason: "sticky escalation from an earlier local failure"
+            };
+        }
+        const threshold = this.config.maxLocalPromptBytes;
+        if (threshold !== undefined) {
+            const bytes = promptBytes(options);
+            if (bytes > threshold) {
+                return {
+                    model: this.config.cloud,
+                    route: "cloud",
+                    escalated: true,
+                    reason: `prompt is ${bytes} bytes, over the local threshold of ${threshold}`
+                };
+            }
+        }
+        return {
+            model: this.config.local,
+            route: "local",
+            escalated: false,
+            reason: "local-first policy"
+        };
+    }
+    note(route, escalated, reason) {
+        this.config.onDecision?.({
+            model: route === "local" ? this.config.local.modelId : this.config.cloud.modelId,
+            route,
+            escalated,
+            reason
+        });
+    }
+    markEscalated() {
+        if (this.config.sticky ?? true)
+            this.escalatedSticky = true;
+    }
+    /**
+     * The one dispatch shared by doGenerate and doStream: route per `decide`,
+     * try local, classify a local failure, escalate to cloud, and report
+     * every decision. The two entry points differ only in which provider
+     * method runs and how a local failure is phrased.
+     */
+    async dispatch(options, call, localFailurePhrase) {
+        const decision = this.decide(options);
+        if (decision.route === "cloud") {
+            if (decision.escalated)
+                this.markEscalated();
+            this.note("cloud", decision.escalated, decision.reason);
+            return call(this.config.cloud);
+        }
+        try {
+            const result = await call(this.config.local);
+            this.note("local", false, decision.reason);
+            return result;
+        }
+        catch (error) {
+            const why = classify(error, this.config.isContextOverflow);
+            this.markEscalated();
+            const reason = `${localFailurePhrase} (${why}): ${error instanceof Error ? error.message : String(error)}`;
+            this.note("cloud", true, reason);
+            return call(this.config.cloud);
+        }
+    }
+    async doGenerate(options) {
+        return this.dispatch(options, (model) => model.doGenerate(options), "local model failed");
+    }
+    async doStream(options) {
+        return this.dispatch(options, (model) => model.doStream(options), "local model failed to start streaming");
+    }
+}
+/** Create an escalating local-first model. */
+export function handoffModel(config) {
+    return new HandoffModel(config);
+}
+/**
+ * Attach a model to a continuation context as `h.model`. The single
+ * golden-shape attach used by both `withModel` and `withRoutedModel`;
+ * decision-to-trace mapping stays with each adapter, the composition does
+ * not.
+ */
+export function attachModel(h, model) {
+    return Object.assign(h, { model });
+}
+/**
+ * The golden-shape composition for the model half: attach `h.model` to a
+ * continuation context. Routing decisions land in the context's trace as
+ * `model.routed` events, and escalations make triggers.modelEscalated()
+ * fire for `h.needs(...)`.
+ */
+export function withModel(h, config) {
+    return attachModel(h, handoffModel({
+        ...config,
+        onDecision: (decision) => h.noteModelDecision(decision)
+    }));
+}

package/dist/remote-tools.d.ts

@@ -0,0 +1,56 @@
+import type { Tool } from "ai";
+import { Handoff } from "@fusionkit/handoff";
+import type { CommandHarnessConfig, GovernedRunRecord } from "@fusionkit/handoff";
+import type { RunStatus } from "@fusionkit/protocol";
+export type RemoteToolsConfig = CommandHarnessConfig & {
+    /** Pull workspace changes back after each call. Defaults to true. */
+    pullResults?: boolean;
+};
+/**
+ * Alternative wiring: attach the remote tools to an existing continuation
+ * context (e.g. the golden-interface `handoff(...)`) so tool calls,
+ * continuations, and sandbox commands share one workspace, policy, and
+ * trace instead of forking a second context.
+ */
+export type RemoteToolsContextConfig = {
+    context: Handoff;
+    /** Runner pool that executes the tool calls. */
+    pool: string;
+    /** Pull workspace changes back after each call. Defaults to true. */
+    pullResults?: boolean;
+    /** Per-call wait ceiling. Defaults to 5 minutes. */
+    timeoutMs?: number;
+};
+export type ShellToolInput = {
+    command: string;
+};
+export type ShellToolOutput = {
+    runId: string;
+    status: RunStatus;
+    exitCode: number | undefined;
+    output: string;
+};
+export type RemoteToolCallRecord = GovernedRunRecord & {
+    toolName: "shell";
+};
+export type RemoteToolSet = {
+    shell: Tool<ShellToolInput, ShellToolOutput>;
+};
+export type RemoteTools = {
+    /** AI SDK-compatible tools; pass directly to generateText/streamText. */
+    tools: RemoteToolSet;
+    /** One record per executed tool call: run id, receipt hash, verification. */
+    calls(): RemoteToolCallRecord[];
+    /** The underlying continuation context (trace, lastEnvelope, …). */
+    context: Handoff;
+};
+/**
+ * App-owned loops, honestly labeled (spec §6.2): the model loop stays in the
+ * caller's process and carries no durability claim. What Warrant adds is the
+ * execution boundary — every tool call becomes a signed run contract executed
+ * in a governed session and returns alongside an offline-verifiable receipt.
+ *
+ * There is no `handoff-needed` stream event and no mid-generation
+ * continuation; those are deliberately out of scope.
+ */
+export declare function remoteTools(config: RemoteToolsConfig | RemoteToolsContextConfig): RemoteTools;