@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/models/needle-runtime.js

@@ -0,0 +1,519 @@
+import { createHash } from "node:crypto";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
+import { join } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { spawnProcess, spawnProcessSync, waitForChildProcessWithTermination } from "../../utils/child-process.js";
+import { modelsDir as agentModelsDir, runtimesDir as agentRuntimesDir } from "../agent-paths.js";
+/**
+ * Managed runtime for needle (https://github.com/cactus-compute/needle), a 26M-parameter single-shot
+ * function-calling model. Needle exposes no server — the only integration surface is CLI/library
+ * invocation — so this module owns clone+build of a pinned commit into a contained venv, base
+ * checkpoint download, and one-shot `needle run` invocation/parsing. Mirrors local-runtime.ts's
+ * OllamaRuntime/TransformersRuntime and llamacpp-runtime.ts's PrismLlamaCppRuntime: injectable seams
+ * for exists/fetch/run-command, pi-owned directories under agentDir (runtimes/, models/), onProgress
+ * as best-effort UI feedback, and honest error taxonomies instead of silent fallbacks.
+ *
+ * Investigation findings (verified against a real clone + real venv + real CPU inference run, not
+ * just the README):
+ *
+ * - `needle run` (the CLI's single-inference subcommand) takes a REQUIRED `--checkpoint` and does
+ *   NOT auto-download one — unlike `needle playground`/`finetune`, which resolve a checkpoint
+ *   internally. The pretrained base checkpoint (`needle.pkl`) lives on `Cactus-Compute/needle` on
+ *   Hugging Face and is fetched directly by {@link NeedleRuntime.downloadWeights} (never invoked
+ *   implicitly by installManaged/runFunctionCall — this module never silently starts a large
+ *   download on the caller's behalf).
+ * - SECURITY (owner-flagged, verified during investigation): `Cactus-Compute/needle` on Hugging Face
+ *   publishes THREE weight artifacts — `needle.pkl` (52,633,098 bytes), `model.safetensors`
+ *   (reported as a different param count on the HF model card, 30.4M vs the 26,315,421 a real
+ *   `needle run` printed — likely not even the same checkpoint), and `needle-cq4.zip`. I grepped the
+ *   ENTIRE needle package (cli.py, model/run.py, model/export.py, model/quantize.py,
+ *   training/{finetune,pretrain,train}.py, utils/distributed.py, ui/server.py — every `pickle`/`.zip`
+ *   hit in the repo) and confirmed every checkpoint load/save path in the codebase — including the
+ *   one `needle run` uses — is `pickle.load`/`pickle.dump` on a `.pkl` file. There is NO safetensors
+ *   reader anywhere in the package; `model.safetensors` is not consumed by any code this module
+ *   drives. `needle-cq4.zip` ("Cactus Quantized 4-bit"?) isn't referenced by any code here either —
+ *   the README states production inference runs on the separate Cactus C++ engine
+ *   (cactus-compute/cactus), which very plausibly consumes its own format; that repo was not audited
+ *   here. Bottom line: **this module has no choice but to fetch and deserialize `needle.pkl` via
+ *   Python's `pickle` module, which executes arbitrary code by construction** — there is no
+ *   safetensors alternative available in the code path we drive. Given that, {@link
+ *   NeedleRuntime.downloadWeights} pins the exact sha256 ({@link NEEDLE_WEIGHTS_SHA256}) and byte
+ *   count ({@link NEEDLE_WEIGHTS_BYTES}) of the file as verified on 2026-07-18 (direct `sha256sum` of
+ *   a real download, cross-checked against Hugging Face's own `x-linked-etag`/`x-linked-size`
+ *   headers on the resolve redirect, at repo commit `5f89b4307696d669c3df1d38ae057e6e1728b107`) and
+ *   VERIFIES every download against that pin, refusing to keep any file that doesn't match — this
+ *   catches a compromised/tampered/swapped artifact but does NOT make loading a pickle file safe in
+ *   the abstract; the actual `pickle.load` execution happens entirely inside needle's own Python
+ *   process, outside this module's control. The owner should decide whether serving this model at
+ *   all is acceptable given upstream's format choice.
+ * - The upstream `setup` script does more than a contained managed install can honor: it can `sudo
+ *   apt-get install` a newer Python or `python3-venv`, `sudo modprobe` TPU kernel modules, toggle
+ *   transparent hugepages via a root-owned sysfs write, and interactively prompts for a
+ *   WANDB_API_KEY. None of that is available under containment (no writes outside the pi-owned dir,
+ *   no sudo, no interactive prompts, no global installs) and none of it is required for the
+ *   documented Mac/PC single-inference quickstart path. {@link NeedleRuntime.installManaged} instead
+ *   replicates only the containable core: `python3 -m venv`, `pip install -e <clonedRepo>` (the
+ *   script's own `pip install -e . -q`), and the CPU (or CUDA, when an NVIDIA GPU is detected) JAX
+ *   backend install. TPU support and the sudo-gated OS package/kernel-module steps are intentionally
+ *   NOT replicated.
+ * - `needle run`'s console-script entry point (`<venv>/bin/needle`, installed by
+ *   `pip install -e .` from the `[project.scripts]` table) is the only way to invoke the CLI:
+ *   `needle/cli.py` has no `if __name__ == "__main__":` guard, so `python -m needle.cli` silently
+ *   does nothing — the installed console script is required.
+ * - A verified real stdout capture of `needle run --checkpoint <path> --query "..." --tools '[...]'`
+ *   is multi-line diagnostic prose followed by the tool call:
+ *   ```
+ *   Loading checkpoint: <path>
+ *   Downloading pretrained tokenizer from HuggingFace...   (first run only — cached after)
+ *   Model parameters: 26,315,421
+ *
+ *   Query: <query>
+ *   Tools: <tools JSON, truncated to 80 chars>...
+ *
+ *   <tool_call>[{"name":"get_weather","arguments":{"location":"SanFrancisco"}}]
+ *   ```
+ *   The `<tool_call>` marker is a literal SentencePiece user-defined-symbol token, always emitted as
+ *   the first generated token per the model's own answer format. {@link NeedleRuntime}'s stdout
+ *   parser locates that marker and strictly `JSON.parse`s everything after it — never guessing a
+ *   result from unparseable output.
+ * - Known upstream quirk (verified against a live run with a camelCase tool name): `needle run`'s CLI
+ *   wrapper (`main()` in `needle/model/run.py`) streams tokens straight to stdout and never applies
+ *   the tool-name restoration its own `generate()` return value receives — a tool name that wasn't
+ *   already snake_case (e.g. `getWeatherNow`) is reported back snake-cased (`get_weather_now`), not
+ *   in its original casing. This is a limitation of the upstream CLI, not something patched here.
+ * - Pinned commit `ffb1c5144c5a16cb8ec650dbc8a6f6fd3854f8f2` was captured via a real `git clone` of
+ *   the repo's default branch HEAD on 2026-07-18 (the repo's own history shows no pushes since
+ *   2026-07-01, so this is not stale). A plain `git clone --depth 1` only reliably lands on a pinned
+ *   commit when it still happens to be the remote's current tip; {@link NeedleRuntime.installManaged}
+ *   instead fetches the exact commit SHA directly (`git fetch --depth 1 origin <sha>`), which GitHub
+ *   serves for any reachable commit on a public repo, so the pin holds even after upstream moves on.
+ */
+export const NEEDLE_REPO_URL = "https://github.com/cactus-compute/needle.git";
+/**
+ * Pinned needle commit — captured via a real `git clone` of the repo's default-branch HEAD on
+ * 2026-07-18 (`git ls-remote https://github.com/cactus-compute/needle HEAD` resolves to the same
+ * SHA). Bump here (re-verify with the same command) when a newer commit is needed.
+ */
+export const NEEDLE_PINNED_COMMIT = "ffb1c5144c5a16cb8ec650dbc8a6f6fd3854f8f2";
+const NEEDLE_HF_MODEL_REPO = "Cactus-Compute/needle";
+const NEEDLE_CHECKPOINT_FILENAME = "needle.pkl";
+const NEEDLE_TOOL_CALL_MARKER = "<tool_call>";
+/**
+ * Pinned integrity for `needle.pkl` — see the module-level SECURITY note: this is a pickle file
+ * (arbitrary code execution on load by construction), so every download is verified against this
+ * exact sha256+size before being kept. Captured 2026-07-18: `sha256sum` of a real download matched
+ * Hugging Face's `x-linked-etag` header on the resolve redirect at repo commit
+ * `5f89b4307696d669c3df1d38ae057e6e1728b107`. Bump both together (re-verify the same way) only for a
+ * deliberate, reviewed upstream weights update.
+ */
+export const NEEDLE_WEIGHTS_SHA256 = "40a32e91d1d4197bf15ba559b74f6727c342dc8746918742fc7d8e2c1f18df40";
+export const NEEDLE_WEIGHTS_BYTES = 52_633_098;
+const NEEDLE_COMMAND_TIMEOUT_MS = 10 * 60_000;
+const NEEDLE_KILL_GRACE_MS = 2_000;
+const NEEDLE_SMOKE_QUERY = "What's the weather in San Francisco?";
+const NEEDLE_SMOKE_TOOLS = [
+    {
+        name: "get_weather",
+        description: "Get current weather for a city.",
+        parameters: { location: { type: "string", description: "City name.", required: true } },
+    },
+];
+function tailLines(value, count = 3) {
+    return value?.trim().split("\n").slice(-count).join("\n") || "unknown error";
+}
+/** Pass bytes through unchanged while feeding them into a running hash — lets a single `pipeline()`
+ * call both write the download to disk and compute its sha256 in one streaming pass. */
+function hashingPassThrough(hash) {
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            hash.update(chunk);
+            callback(null, chunk);
+        },
+    });
+}
+async function defaultRunCommand(command, args, options = {}) {
+    try {
+        const proc = spawnProcess(command, args, {
+            detached: process.platform !== "win32",
+            stdio: ["ignore", "pipe", "pipe"],
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.setEncoding("utf8");
+        proc.stderr.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => {
+            stdout = `${stdout}${chunk}`.slice(-1024 * 1024);
+            options.onOutput?.(chunk);
+        });
+        proc.stderr.on("data", (chunk) => {
+            stderr = `${stderr}${chunk}`.slice(-1024 * 1024);
+            options.onOutput?.(chunk);
+        });
+        const terminal = await waitForChildProcessWithTermination(proc, {
+            timeoutMs: NEEDLE_COMMAND_TIMEOUT_MS,
+            killGraceMs: NEEDLE_KILL_GRACE_MS,
+        });
+        const timedOut = terminal.reason === "timeout";
+        return {
+            ok: terminal.code === 0,
+            stdout,
+            stderr,
+            code: terminal.code,
+            ...(terminal.code === 0
+                ? {}
+                : {
+                    error: timedOut
+                        ? `${command} timed out after ${NEEDLE_COMMAND_TIMEOUT_MS}ms`
+                        : stderr.trim() || stdout.trim() || `exit code ${terminal.code ?? "unknown"}`,
+                }),
+        };
+    }
+    catch (error) {
+        return { ok: false, stdout: "", stderr: "", error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export class NeedleRuntime {
+    _agentDir;
+    _exists;
+    _fetch;
+    _runCommand;
+    _hasCommand;
+    _hasNvidiaGpu;
+    _platform;
+    _weightsIntegrity;
+    constructor(args) {
+        this._agentDir = args.agentDir;
+        this._exists = args.deps?.existsFn ?? existsSync;
+        this._fetch = args.deps?.fetchFn ?? fetch;
+        this._runCommand = args.deps?.runCommand ?? defaultRunCommand;
+        this._hasCommand =
+            args.deps?.hasCommand ??
+                ((command) => spawnProcessSync(command, ["--version"], { encoding: "utf8", timeout: 5_000 }).error === undefined);
+        this._hasNvidiaGpu = args.deps?.hasNvidiaGpu ?? (() => this._hasCommand("nvidia-smi"));
+        this._platform = args.deps?.platform ?? osPlatform;
+        this._weightsIntegrity = args.deps?.weightsIntegrity ?? {
+            sha256: NEEDLE_WEIGHTS_SHA256,
+            bytes: NEEDLE_WEIGHTS_BYTES,
+        };
+    }
+    runtimeDir() {
+        return agentRuntimesDir("needle", this._agentDir);
+    }
+    modelsDir() {
+        return agentModelsDir("needle", this._agentDir);
+    }
+    checkpointPath() {
+        return join(this.modelsDir(), NEEDLE_CHECKPOINT_FILENAME);
+    }
+    _srcDir() {
+        return join(this.runtimeDir(), "src");
+    }
+    _venvDir() {
+        return join(this.runtimeDir(), "venv");
+    }
+    _pythonPath() {
+        return this._platform() === "win32"
+            ? join(this._venvDir(), "Scripts", "python.exe")
+            : join(this._venvDir(), "bin", "python");
+    }
+    /** The installed `needle` console script (from `[project.scripts]`, written by `pip install -e`)
+     * — the only invokable entry point, since `needle/cli.py` has no `__main__` guard. */
+    _entryPath() {
+        return this._platform() === "win32"
+            ? join(this._venvDir(), "Scripts", "needle.exe")
+            : join(this._venvDir(), "bin", "needle");
+    }
+    _manifestPath() {
+        return join(this.runtimeDir(), "install.json");
+    }
+    _readManifest() {
+        try {
+            const parsed = JSON.parse(readFileSync(this._manifestPath(), "utf8"));
+            return typeof parsed.commit === "string" && typeof parsed.entryCommand === "string"
+                ? { commit: parsed.commit, entryCommand: parsed.entryCommand }
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    _writeManifest(metadata) {
+        writeFileSync(this._manifestPath(), JSON.stringify(metadata, null, "\t"));
+    }
+    async detect() {
+        const installed = this._exists(this._entryPath());
+        return {
+            installed,
+            installDir: installed ? this.runtimeDir() : undefined,
+            commit: this._readManifest()?.commit,
+            pythonAvailable: this._hasCommand("python3"),
+            checkpointPresent: this._exists(this.checkpointPath()),
+        };
+    }
+    /**
+     * Clone the pinned needle commit and build a contained, pi-owned runtime (consent-gated by the
+     * caller, same contract as OllamaRuntime#installManaged / PrismLlamaCppRuntime#installManaged —
+     * this method only does the mechanical clone+build+verify and reports the outcome honestly). See
+     * the module docstring for exactly which upstream `setup` steps are and are not replicated under
+     * containment.
+     */
+    async installManaged(onProgress) {
+        if (!this._hasCommand("git")) {
+            return {
+                ok: false,
+                error: `git-missing: git is required to clone needle (${NEEDLE_REPO_URL}). Install git (e.g. \`apt-get install git\`, \`brew install git\`) and try again.`,
+            };
+        }
+        if (!this._hasCommand("python3")) {
+            return {
+                ok: false,
+                error: "python-missing: python3 (>=3.11) is required to run needle. Install Python 3.11+ (e.g. `apt-get install python3 python3-venv`, `brew install python@3.12`) and try again.",
+            };
+        }
+        mkdirSync(this.runtimeDir(), { recursive: true });
+        const srcDir = this._srcDir();
+        if (this._exists(srcDir))
+            rmSync(srcDir, { recursive: true, force: true });
+        onProgress?.(`Cloning ${NEEDLE_REPO_URL}…`);
+        const cloned = await this._cloneAtPinnedCommit(srcDir);
+        if (!cloned.ok)
+            return cloned;
+        onProgress?.(`Creating isolated Python venv at ${this._venvDir()}…`);
+        const venv = await this._runCommand("python3", ["-m", "venv", this._venvDir()]);
+        if (!venv.ok)
+            return { ok: false, error: `setup-fail: ${tailLines(venv.error ?? venv.stderr)}` };
+        if (!this._exists(this._pythonPath())) {
+            return { ok: false, error: `setup-fail: venv created but ${this._pythonPath()} was not found` };
+        }
+        onProgress?.("Upgrading pip inside the pi-managed venv…");
+        const pipUpgrade = await this._runCommand(this._pythonPath(), ["-m", "pip", "install", "--upgrade", "pip"]);
+        if (!pipUpgrade.ok) {
+            return { ok: false, error: `setup-fail: ${tailLines(pipUpgrade.error ?? pipUpgrade.stderr)}` };
+        }
+        onProgress?.("Installing needle (editable) into the pi-managed venv…");
+        const install = await this._runCommand(this._pythonPath(), ["-m", "pip", "install", "-e", srcDir]);
+        if (!install.ok)
+            return { ok: false, error: `setup-fail: ${tailLines(install.error ?? install.stderr)}` };
+        const cudaAvailable = this._hasNvidiaGpu();
+        onProgress?.(cudaAvailable ? "Installing JAX (CUDA 12 backend)…" : "Installing JAX (CPU backend)…");
+        const jaxArgs = cudaAvailable ? ["jax[cuda12]"] : ["jax"];
+        const jax = await this._runCommand(this._pythonPath(), ["-m", "pip", "install", "-U", ...jaxArgs]);
+        if (!jax.ok)
+            return { ok: false, error: `setup-fail: ${tailLines(jax.error ?? jax.stderr)}` };
+        onProgress?.("Verifying the needle install…");
+        const verify = await this._runCommand(this._pythonPath(), ["-c", "import jax, needle; print(needle.__file__)"]);
+        if (!verify.ok)
+            return { ok: false, error: `verify-fail: ${tailLines(verify.error ?? verify.stderr)}` };
+        const entryCommand = this._entryPath();
+        if (!this._exists(entryCommand)) {
+            return { ok: false, error: `verify-fail: install reported success but ${entryCommand} was not found` };
+        }
+        this._writeManifest({ commit: NEEDLE_PINNED_COMMIT, entryCommand });
+        onProgress?.("needle installed.");
+        return { ok: true };
+    }
+    /**
+     * A plain `git clone --depth 1` only lands on {@link NEEDLE_PINNED_COMMIT} when it still happens
+     * to be the remote's current default-branch tip. Fetching the exact SHA directly instead (verified
+     * against the real repo) pins reliably even after upstream moves on: GitHub serves any reachable
+     * commit for a public repo via `git fetch <sha>`, not just refs.
+     */
+    async _cloneAtPinnedCommit(srcDir) {
+        const init = await this._runCommand("git", ["init", "-q", srcDir]);
+        if (!init.ok)
+            return { ok: false, error: `clone-fail: ${tailLines(init.error ?? init.stderr)}` };
+        const remote = await this._runCommand("git", ["-C", srcDir, "remote", "add", "origin", NEEDLE_REPO_URL]);
+        if (!remote.ok)
+            return { ok: false, error: `clone-fail: ${tailLines(remote.error ?? remote.stderr)}` };
+        const fetched = await this._runCommand("git", [
+            "-C",
+            srcDir,
+            "fetch",
+            "--depth",
+            "1",
+            "origin",
+            NEEDLE_PINNED_COMMIT,
+        ]);
+        if (!fetched.ok)
+            return { ok: false, error: `clone-fail: ${tailLines(fetched.error ?? fetched.stderr)}` };
+        const checkout = await this._runCommand("git", ["-C", srcDir, "checkout", "-q", "FETCH_HEAD"]);
+        if (!checkout.ok)
+            return { ok: false, error: `clone-fail: ${tailLines(checkout.error ?? checkout.stderr)}` };
+        return { ok: true };
+    }
+    /**
+     * Download the pretrained base weights (`needle.pkl`). `needle run` takes an explicit
+     * `--checkpoint` and does NOT auto-download one (unlike `needle playground`/`finetune`) — see the
+     * module docstring. Never called implicitly by installManaged/runFunctionCall; the caller decides
+     * when to pull weights.
+     *
+     * `needle.pkl` is a pickle file — arbitrary code execution on load by construction (see the
+     * module-level SECURITY note) — so every download is verified against the pinned sha256+size
+     * ({@link NEEDLE_WEIGHTS_SHA256}/{@link NEEDLE_WEIGHTS_BYTES}, overridable only via the
+     * `weightsIntegrity` test seam) computed in the same streaming pass that writes the file, with the
+     * partial/mismatched file deleted on ANY failure — this never leaves an unverified or wrong pickle
+     * sitting where {@link runFunctionCall} would load it.
+     */
+    async downloadWeights(onProgress) {
+        const destPath = this.checkpointPath();
+        const url = `https://huggingface.co/${NEEDLE_HF_MODEL_REPO}/resolve/main/${NEEDLE_CHECKPOINT_FILENAME}`;
+        mkdirSync(this.modelsDir(), { recursive: true });
+        if (this._exists(destPath) && this._fileSizeBytes(destPath) === this._weightsIntegrity.bytes) {
+            onProgress?.(`${NEEDLE_CHECKPOINT_FILENAME} already downloaded (${this._weightsIntegrity.bytes} bytes) — skipping.`);
+            return { ok: true, path: destPath, skipped: true };
+        }
+        onProgress?.(`Downloading ${NEEDLE_CHECKPOINT_FILENAME} from ${NEEDLE_HF_MODEL_REPO}…`);
+        let response;
+        try {
+            response = await this._fetch(url);
+        }
+        catch (error) {
+            return { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        if (!response.ok || !response.body) {
+            return { ok: false, error: `download-fail: HTTP ${response.status}` };
+        }
+        const hash = createHash("sha256");
+        try {
+            await pipeline(response.body, hashingPassThrough(hash), createWriteStream(destPath));
+        }
+        catch (error) {
+            this._cleanupPartial(destPath);
+            return { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };
+        }
+        const actualBytes = this._fileSizeBytes(destPath);
+        const actualSha256 = hash.digest("hex");
+        if (actualBytes !== this._weightsIntegrity.bytes || actualSha256 !== this._weightsIntegrity.sha256) {
+            this._cleanupPartial(destPath);
+            return {
+                ok: false,
+                error: `integrity-fail: downloaded ${NEEDLE_CHECKPOINT_FILENAME} does not match the pinned checksum — expected sha256 ${this._weightsIntegrity.sha256} (${this._weightsIntegrity.bytes} bytes), got ${actualSha256} (${actualBytes ?? 0} bytes). Refusing to keep a pickle file that failed integrity verification.`,
+            };
+        }
+        onProgress?.(`${NEEDLE_CHECKPOINT_FILENAME} downloaded and verified (sha256 ${actualSha256}).`);
+        return { ok: true, path: destPath };
+    }
+    _fileSizeBytes(path) {
+        try {
+            return statSync(path).size;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    _cleanupPartial(path) {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    /**
+     * Run one single-shot inference through `needle run --checkpoint ... --query ... --tools ...`
+     * inside the contained venv's installed console script. Argv is passed as an array to the
+     * injected `runCommand` seam — never a shell string — so query/tools text containing quotes,
+     * spaces, or other shell-hostile characters is passed through literally (verified against a real
+     * invocation; see the module docstring). `tools` is serialized with `JSON.stringify` exactly once.
+     */
+    async runFunctionCall(request, options) {
+        const entryCommand = this._entryPath();
+        if (!this._exists(entryCommand)) {
+            return { ok: false, error: "not-installed: run installManaged() first", rawOutput: "" };
+        }
+        const checkpointPath = options?.checkpointPath ?? this.checkpointPath();
+        if (!this._exists(checkpointPath)) {
+            return {
+                ok: false,
+                error: `checkpoint-missing: no checkpoint at ${checkpointPath} — run downloadWeights() first`,
+                rawOutput: "",
+            };
+        }
+        const argv = [
+            "run",
+            "--checkpoint",
+            checkpointPath,
+            "--query",
+            request.query,
+            "--tools",
+            JSON.stringify(request.tools),
+        ];
+        const result = await this._runCommand(entryCommand, argv);
+        const rawOutput = [result.stdout, result.stderr].filter(Boolean).join("\n");
+        if (!result.ok) {
+            return { ok: false, error: `run-fail: ${tailLines(result.error ?? result.stderr)}`, rawOutput };
+        }
+        return this._parseFunctionCall(result.stdout, rawOutput);
+    }
+    /**
+     * Strictly parse a real `needle run` stdout capture:
+     * ```
+     * Loading checkpoint: <path>
+     * Model parameters: <n>
+     *
+     * Query: <query>
+     * Tools: <tools, truncated to 80 chars>...
+     *
+     * <tool_call>[{"name":"...","arguments":{...}}]
+     * ```
+     * (diagnostic lines above the marker vary — e.g. a one-time "Downloading pretrained tokenizer..."
+     * line on a cold cache — so parsing locates the `<tool_call>` marker rather than assuming a fixed
+     * line count/position). Unparseable output is always an error carrying the raw text, never a
+     * guessed result.
+     */
+    _parseFunctionCall(stdout, rawOutput) {
+        const markerIndex = stdout.indexOf(NEEDLE_TOOL_CALL_MARKER);
+        if (markerIndex < 0) {
+            return { ok: false, error: `unparseable-output: no ${NEEDLE_TOOL_CALL_MARKER} marker in stdout`, rawOutput };
+        }
+        const jsonText = stdout.slice(markerIndex + NEEDLE_TOOL_CALL_MARKER.length).trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(jsonText);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: `unparseable-output: ${error instanceof Error ? error.message : String(error)}`,
+                rawOutput,
+            };
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0) {
+            return { ok: false, error: "unparseable-output: expected a non-empty tool-call array", rawOutput };
+        }
+        const first = parsed[0];
+        if (typeof first !== "object" ||
+            first === null ||
+            typeof first.name !== "string" ||
+            typeof first.arguments !== "object" ||
+            first.arguments === null) {
+            return { ok: false, error: "unparseable-output: tool call missing name/arguments", rawOutput };
+        }
+        return { ok: true, call: { name: first.name, arguments: first.arguments } };
+    }
+    /** Canned get_weather query/tool through {@link runFunctionCall}; the wiring task uses this as the
+     * post-install verification step. */
+    async smokeTest(onProgress) {
+        onProgress?.("Running needle smoke test…");
+        const startedAt = Date.now();
+        const result = await this.runFunctionCall({ query: NEEDLE_SMOKE_QUERY, tools: NEEDLE_SMOKE_TOOLS });
+        const latencyMs = Date.now() - startedAt;
+        if (!result.ok) {
+            onProgress?.(`Smoke test failed: ${result.error}`);
+            return { ok: false, latencyMs, error: result.error };
+        }
+        onProgress?.(`Smoke test ok (${latencyMs}ms): ${result.call.name}`);
+        return { ok: true, latencyMs, call: result.call };
+    }
+    /**
+     * No-op: every needle invocation here is a single-shot `runCommand` call that spawns, waits for
+     * exit, and returns — there is no persistent/detached child process this runtime owns between
+     * calls for dispose() to track or kill (contrast OllamaRuntime/PrismLlamaCppRuntime's long-lived
+     * `serve()` child).
+     */
+    dispose() { }
+}
+//# sourceMappingURL=needle-runtime.js.map

package/dist/core/models/needle-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"needle-runtime.js","sourceRoot":"","sources":["../../../src/core/models/needle-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from \"node:fs\";\nimport { platform as osPlatform } from \"node:os\";\nimport { join } from \"node:path\";\nimport { type Readable, Transform } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport { spawnProcess, spawnProcessSync, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport { modelsDir as agentModelsDir, runtimesDir as agentRuntimesDir } from \"../agent-paths.ts\";\nimport type { RuntimeCommandResult, RuntimeCommandRunner } from \"./local-runtime.ts\";\n\n/**\n * Managed runtime for needle (https://github.com/cactus-compute/needle), a 26M-parameter single-shot\n * function-calling model. Needle exposes no server — the only integration surface is CLI/library\n * invocation — so this module owns clone+build of a pinned commit into a contained venv, base\n * checkpoint download, and one-shot `needle run` invocation/parsing. Mirrors local-runtime.ts's\n * OllamaRuntime/TransformersRuntime and llamacpp-runtime.ts's PrismLlamaCppRuntime: injectable seams\n * for exists/fetch/run-command, pi-owned directories under agentDir (runtimes/, models/), onProgress\n * as best-effort UI feedback, and honest error taxonomies instead of silent fallbacks.\n *\n * Investigation findings (verified against a real clone + real venv + real CPU inference run, not\n * just the README):\n *\n * - `needle run` (the CLI's single-inference subcommand) takes a REQUIRED `--checkpoint` and does\n *   NOT auto-download one — unlike `needle playground`/`finetune`, which resolve a checkpoint\n *   internally. The pretrained base checkpoint (`needle.pkl`) lives on `Cactus-Compute/needle` on\n *   Hugging Face and is fetched directly by {@link NeedleRuntime.downloadWeights} (never invoked\n *   implicitly by installManaged/runFunctionCall — this module never silently starts a large\n *   download on the caller's behalf).\n * - SECURITY (owner-flagged, verified during investigation): `Cactus-Compute/needle` on Hugging Face\n *   publishes THREE weight artifacts — `needle.pkl` (52,633,098 bytes), `model.safetensors`\n *   (reported as a different param count on the HF model card, 30.4M vs the 26,315,421 a real\n *   `needle run` printed — likely not even the same checkpoint), and `needle-cq4.zip`. I grepped the\n *   ENTIRE needle package (cli.py, model/run.py, model/export.py, model/quantize.py,\n *   training/{finetune,pretrain,train}.py, utils/distributed.py, ui/server.py — every `pickle`/`.zip`\n *   hit in the repo) and confirmed every checkpoint load/save path in the codebase — including the\n *   one `needle run` uses — is `pickle.load`/`pickle.dump` on a `.pkl` file. There is NO safetensors\n *   reader anywhere in the package; `model.safetensors` is not consumed by any code this module\n *   drives. `needle-cq4.zip` (\"Cactus Quantized 4-bit\"?) isn't referenced by any code here either —\n *   the README states production inference runs on the separate Cactus C++ engine\n *   (cactus-compute/cactus), which very plausibly consumes its own format; that repo was not audited\n *   here. Bottom line: **this module has no choice but to fetch and deserialize `needle.pkl` via\n *   Python's `pickle` module, which executes arbitrary code by construction** — there is no\n *   safetensors alternative available in the code path we drive. Given that, {@link\n *   NeedleRuntime.downloadWeights} pins the exact sha256 ({@link NEEDLE_WEIGHTS_SHA256}) and byte\n *   count ({@link NEEDLE_WEIGHTS_BYTES}) of the file as verified on 2026-07-18 (direct `sha256sum` of\n *   a real download, cross-checked against Hugging Face's own `x-linked-etag`/`x-linked-size`\n *   headers on the resolve redirect, at repo commit `5f89b4307696d669c3df1d38ae057e6e1728b107`) and\n *   VERIFIES every download against that pin, refusing to keep any file that doesn't match — this\n *   catches a compromised/tampered/swapped artifact but does NOT make loading a pickle file safe in\n *   the abstract; the actual `pickle.load` execution happens entirely inside needle's own Python\n *   process, outside this module's control. The owner should decide whether serving this model at\n *   all is acceptable given upstream's format choice.\n * - The upstream `setup` script does more than a contained managed install can honor: it can `sudo\n *   apt-get install` a newer Python or `python3-venv`, `sudo modprobe` TPU kernel modules, toggle\n *   transparent hugepages via a root-owned sysfs write, and interactively prompts for a\n *   WANDB_API_KEY. None of that is available under containment (no writes outside the pi-owned dir,\n *   no sudo, no interactive prompts, no global installs) and none of it is required for the\n *   documented Mac/PC single-inference quickstart path. {@link NeedleRuntime.installManaged} instead\n *   replicates only the containable core: `python3 -m venv`, `pip install -e <clonedRepo>` (the\n *   script's own `pip install -e . -q`), and the CPU (or CUDA, when an NVIDIA GPU is detected) JAX\n *   backend install. TPU support and the sudo-gated OS package/kernel-module steps are intentionally\n *   NOT replicated.\n * - `needle run`'s console-script entry point (`<venv>/bin/needle`, installed by\n *   `pip install -e .` from the `[project.scripts]` table) is the only way to invoke the CLI:\n *   `needle/cli.py` has no `if __name__ == \"__main__\":` guard, so `python -m needle.cli` silently\n *   does nothing — the installed console script is required.\n * - A verified real stdout capture of `needle run --checkpoint <path> --query \"...\" --tools '[...]'`\n *   is multi-line diagnostic prose followed by the tool call:\n *   ```\n *   Loading checkpoint: <path>\n *   Downloading pretrained tokenizer from HuggingFace...   (first run only — cached after)\n *   Model parameters: 26,315,421\n *\n *   Query: <query>\n *   Tools: <tools JSON, truncated to 80 chars>...\n *\n *   <tool_call>[{\"name\":\"get_weather\",\"arguments\":{\"location\":\"SanFrancisco\"}}]\n *   ```\n *   The `<tool_call>` marker is a literal SentencePiece user-defined-symbol token, always emitted as\n *   the first generated token per the model's own answer format. {@link NeedleRuntime}'s stdout\n *   parser locates that marker and strictly `JSON.parse`s everything after it — never guessing a\n *   result from unparseable output.\n * - Known upstream quirk (verified against a live run with a camelCase tool name): `needle run`'s CLI\n *   wrapper (`main()` in `needle/model/run.py`) streams tokens straight to stdout and never applies\n *   the tool-name restoration its own `generate()` return value receives — a tool name that wasn't\n *   already snake_case (e.g. `getWeatherNow`) is reported back snake-cased (`get_weather_now`), not\n *   in its original casing. This is a limitation of the upstream CLI, not something patched here.\n * - Pinned commit `ffb1c5144c5a16cb8ec650dbc8a6f6fd3854f8f2` was captured via a real `git clone` of\n *   the repo's default branch HEAD on 2026-07-18 (the repo's own history shows no pushes since\n *   2026-07-01, so this is not stale). A plain `git clone --depth 1` only reliably lands on a pinned\n *   commit when it still happens to be the remote's current tip; {@link NeedleRuntime.installManaged}\n *   instead fetches the exact commit SHA directly (`git fetch --depth 1 origin <sha>`), which GitHub\n *   serves for any reachable commit on a public repo, so the pin holds even after upstream moves on.\n */\n\nexport const NEEDLE_REPO_URL = \"https://github.com/cactus-compute/needle.git\";\n\n/**\n * Pinned needle commit — captured via a real `git clone` of the repo's default-branch HEAD on\n * 2026-07-18 (`git ls-remote https://github.com/cactus-compute/needle HEAD` resolves to the same\n * SHA). Bump here (re-verify with the same command) when a newer commit is needed.\n */\nexport const NEEDLE_PINNED_COMMIT = \"ffb1c5144c5a16cb8ec650dbc8a6f6fd3854f8f2\";\n\nconst NEEDLE_HF_MODEL_REPO = \"Cactus-Compute/needle\";\nconst NEEDLE_CHECKPOINT_FILENAME = \"needle.pkl\";\nconst NEEDLE_TOOL_CALL_MARKER = \"<tool_call>\";\n\n/**\n * Pinned integrity for `needle.pkl` — see the module-level SECURITY note: this is a pickle file\n * (arbitrary code execution on load by construction), so every download is verified against this\n * exact sha256+size before being kept. Captured 2026-07-18: `sha256sum` of a real download matched\n * Hugging Face's `x-linked-etag` header on the resolve redirect at repo commit\n * `5f89b4307696d669c3df1d38ae057e6e1728b107`. Bump both together (re-verify the same way) only for a\n * deliberate, reviewed upstream weights update.\n */\nexport const NEEDLE_WEIGHTS_SHA256 = \"40a32e91d1d4197bf15ba559b74f6727c342dc8746918742fc7d8e2c1f18df40\";\nexport const NEEDLE_WEIGHTS_BYTES = 52_633_098;\n\nconst NEEDLE_COMMAND_TIMEOUT_MS = 10 * 60_000;\nconst NEEDLE_KILL_GRACE_MS = 2_000;\n\nconst NEEDLE_SMOKE_QUERY = \"What's the weather in San Francisco?\";\nconst NEEDLE_SMOKE_TOOLS = [\n\t{\n\t\tname: \"get_weather\",\n\t\tdescription: \"Get current weather for a city.\",\n\t\tparameters: { location: { type: \"string\", description: \"City name.\", required: true } },\n\t},\n];\n\nexport interface NeedleDetectResult {\n\tinstalled: boolean;\n\tinstallDir?: string;\n\tcommit?: string;\n\tpythonAvailable: boolean;\n\tcheckpointPresent: boolean;\n}\n\nexport interface NeedleFunctionCallRequest {\n\tquery: string;\n\t/** A JSON-serializable tool schema value (never a pre-stringified JSON string) — serialized\n\t * exactly once by {@link NeedleRuntime.runFunctionCall}, never by the caller. */\n\ttools: unknown;\n}\n\nexport interface NeedleFunctionCall {\n\tname: string;\n\targuments: Record<string, unknown>;\n}\n\nexport type NeedleFunctionCallResult =\n\t| { ok: true; call: NeedleFunctionCall }\n\t| { ok: false; error: string; rawOutput: string };\n\nexport interface NeedleSmokeTestResult {\n\tok: boolean;\n\tlatencyMs: number;\n\tcall?: NeedleFunctionCall;\n\terror?: string;\n}\n\nexport interface NeedleWeightsDownloadResult {\n\tok: boolean;\n\tpath?: string;\n\tskipped?: boolean;\n\terror?: string;\n}\n\ninterface NeedleWeightsIntegrity {\n\tsha256: string;\n\tbytes: number;\n}\n\nexport interface NeedleRuntimeDeps {\n\texistsFn?: (path: string) => boolean;\n\tfetchFn?: typeof fetch;\n\t/** Runs git/pip/python commands. Injectable so installManaged/runFunctionCall's orchestration is\n\t * testable without a real clone/venv/inference. Defaults to a real spawn-and-collect-output\n\t * runner (installs can run long; a single inference call is comparatively quick but still shells\n\t * out to a real interpreter). */\n\trunCommand?: RuntimeCommandRunner;\n\t/** Whether a named command exists on PATH (git, python3, nvidia-smi). */\n\thasCommand?: (command: string) => boolean;\n\thasNvidiaGpu?: () => boolean;\n\tplatform?: () => string;\n\t/** Expected weights sha256+size. Defaults to {@link NEEDLE_WEIGHTS_SHA256}/{@link\n\t * NEEDLE_WEIGHTS_BYTES} — the real pinned values. Overridable ONLY so tests can exercise the full\n\t * download+verify path with small synthetic content instead of the real 52MB pickle; this is a\n\t * constructor-level seam for a trusted caller, the same trust boundary every other injectable dep\n\t * in this class already relies on (fetchFn/runCommand could equally be used to bypass anything).\n\t */\n\tweightsIntegrity?: NeedleWeightsIntegrity;\n}\n\ninterface NeedleInstallMetadata {\n\tcommit: string;\n\tentryCommand: string;\n}\n\nfunction tailLines(value: string | undefined, count = 3): string {\n\treturn value?.trim().split(\"\\n\").slice(-count).join(\"\\n\") || \"unknown error\";\n}\n\n/** Pass bytes through unchanged while feeding them into a running hash — lets a single `pipeline()`\n * call both write the download to disk and compute its sha256 in one streaming pass. */\nfunction hashingPassThrough(hash: ReturnType<typeof createHash>): Transform {\n\treturn new Transform({\n\t\ttransform(chunk: Buffer, _encoding, callback) {\n\t\t\thash.update(chunk);\n\t\t\tcallback(null, chunk);\n\t\t},\n\t});\n}\n\nasync function defaultRunCommand(\n\tcommand: string,\n\targs: string[],\n\toptions: { env?: NodeJS.ProcessEnv; onOutput?: (chunk: string) => void } = {},\n): Promise<RuntimeCommandResult> {\n\ttry {\n\t\tconst proc = spawnProcess(command, args, {\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\tenv: options.env ? { ...process.env, ...options.env } : process.env,\n\t\t});\n\t\tlet stdout = \"\";\n\t\tlet stderr = \"\";\n\t\tproc.stdout.setEncoding(\"utf8\");\n\t\tproc.stderr.setEncoding(\"utf8\");\n\t\tproc.stdout.on(\"data\", (chunk: string) => {\n\t\t\tstdout = `${stdout}${chunk}`.slice(-1024 * 1024);\n\t\t\toptions.onOutput?.(chunk);\n\t\t});\n\t\tproc.stderr.on(\"data\", (chunk: string) => {\n\t\t\tstderr = `${stderr}${chunk}`.slice(-1024 * 1024);\n\t\t\toptions.onOutput?.(chunk);\n\t\t});\n\t\tconst terminal = await waitForChildProcessWithTermination(proc, {\n\t\t\ttimeoutMs: NEEDLE_COMMAND_TIMEOUT_MS,\n\t\t\tkillGraceMs: NEEDLE_KILL_GRACE_MS,\n\t\t});\n\t\tconst timedOut = terminal.reason === \"timeout\";\n\t\treturn {\n\t\t\tok: terminal.code === 0,\n\t\t\tstdout,\n\t\t\tstderr,\n\t\t\tcode: terminal.code,\n\t\t\t...(terminal.code === 0\n\t\t\t\t? {}\n\t\t\t\t: {\n\t\t\t\t\t\terror: timedOut\n\t\t\t\t\t\t\t? `${command} timed out after ${NEEDLE_COMMAND_TIMEOUT_MS}ms`\n\t\t\t\t\t\t\t: stderr.trim() || stdout.trim() || `exit code ${terminal.code ?? \"unknown\"}`,\n\t\t\t\t\t}),\n\t\t};\n\t} catch (error) {\n\t\treturn { ok: false, stdout: \"\", stderr: \"\", error: error instanceof Error ? error.message : String(error) };\n\t}\n}\n\nexport class NeedleRuntime {\n\tprivate readonly _agentDir: string;\n\tprivate readonly _exists: (path: string) => boolean;\n\tprivate readonly _fetch: typeof fetch;\n\tprivate readonly _runCommand: RuntimeCommandRunner;\n\tprivate readonly _hasCommand: (command: string) => boolean;\n\tprivate readonly _hasNvidiaGpu: () => boolean;\n\tprivate readonly _platform: () => string;\n\tprivate readonly _weightsIntegrity: NeedleWeightsIntegrity;\n\n\tconstructor(args: { agentDir: string; deps?: NeedleRuntimeDeps }) {\n\t\tthis._agentDir = args.agentDir;\n\t\tthis._exists = args.deps?.existsFn ?? existsSync;\n\t\tthis._fetch = args.deps?.fetchFn ?? fetch;\n\t\tthis._runCommand = args.deps?.runCommand ?? defaultRunCommand;\n\t\tthis._hasCommand =\n\t\t\targs.deps?.hasCommand ??\n\t\t\t((command) =>\n\t\t\t\tspawnProcessSync(command, [\"--version\"], { encoding: \"utf8\", timeout: 5_000 }).error === undefined);\n\t\tthis._hasNvidiaGpu = args.deps?.hasNvidiaGpu ?? (() => this._hasCommand(\"nvidia-smi\"));\n\t\tthis._platform = args.deps?.platform ?? osPlatform;\n\t\tthis._weightsIntegrity = args.deps?.weightsIntegrity ?? {\n\t\t\tsha256: NEEDLE_WEIGHTS_SHA256,\n\t\t\tbytes: NEEDLE_WEIGHTS_BYTES,\n\t\t};\n\t}\n\n\truntimeDir(): string {\n\t\treturn agentRuntimesDir(\"needle\", this._agentDir);\n\t}\n\n\tmodelsDir(): string {\n\t\treturn agentModelsDir(\"needle\", this._agentDir);\n\t}\n\n\tcheckpointPath(): string {\n\t\treturn join(this.modelsDir(), NEEDLE_CHECKPOINT_FILENAME);\n\t}\n\n\tprivate _srcDir(): string {\n\t\treturn join(this.runtimeDir(), \"src\");\n\t}\n\n\tprivate _venvDir(): string {\n\t\treturn join(this.runtimeDir(), \"venv\");\n\t}\n\n\tprivate _pythonPath(): string {\n\t\treturn this._platform() === \"win32\"\n\t\t\t? join(this._venvDir(), \"Scripts\", \"python.exe\")\n\t\t\t: join(this._venvDir(), \"bin\", \"python\");\n\t}\n\n\t/** The installed `needle` console script (from `[project.scripts]`, written by `pip install -e`)\n\t * — the only invokable entry point, since `needle/cli.py` has no `__main__` guard. */\n\tprivate _entryPath(): string {\n\t\treturn this._platform() === \"win32\"\n\t\t\t? join(this._venvDir(), \"Scripts\", \"needle.exe\")\n\t\t\t: join(this._venvDir(), \"bin\", \"needle\");\n\t}\n\n\tprivate _manifestPath(): string {\n\t\treturn join(this.runtimeDir(), \"install.json\");\n\t}\n\n\tprivate _readManifest(): NeedleInstallMetadata | undefined {\n\t\ttry {\n\t\t\tconst parsed = JSON.parse(readFileSync(this._manifestPath(), \"utf8\")) as {\n\t\t\t\tcommit?: unknown;\n\t\t\t\tentryCommand?: unknown;\n\t\t\t};\n\t\t\treturn typeof parsed.commit === \"string\" && typeof parsed.entryCommand === \"string\"\n\t\t\t\t? { commit: parsed.commit, entryCommand: parsed.entryCommand }\n\t\t\t\t: undefined;\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\tprivate _writeManifest(metadata: NeedleInstallMetadata): void {\n\t\twriteFileSync(this._manifestPath(), JSON.stringify(metadata, null, \"\\t\"));\n\t}\n\n\tasync detect(): Promise<NeedleDetectResult> {\n\t\tconst installed = this._exists(this._entryPath());\n\t\treturn {\n\t\t\tinstalled,\n\t\t\tinstallDir: installed ? this.runtimeDir() : undefined,\n\t\t\tcommit: this._readManifest()?.commit,\n\t\t\tpythonAvailable: this._hasCommand(\"python3\"),\n\t\t\tcheckpointPresent: this._exists(this.checkpointPath()),\n\t\t};\n\t}\n\n\t/**\n\t * Clone the pinned needle commit and build a contained, pi-owned runtime (consent-gated by the\n\t * caller, same contract as OllamaRuntime#installManaged / PrismLlamaCppRuntime#installManaged —\n\t * this method only does the mechanical clone+build+verify and reports the outcome honestly). See\n\t * the module docstring for exactly which upstream `setup` steps are and are not replicated under\n\t * containment.\n\t */\n\tasync installManaged(onProgress?: (status: string) => void): Promise<{ ok: boolean; error?: string }> {\n\t\tif (!this._hasCommand(\"git\")) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: `git-missing: git is required to clone needle (${NEEDLE_REPO_URL}). Install git (e.g. \\`apt-get install git\\`, \\`brew install git\\`) and try again.`,\n\t\t\t};\n\t\t}\n\t\tif (!this._hasCommand(\"python3\")) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: \"python-missing: python3 (>=3.11) is required to run needle. Install Python 3.11+ (e.g. `apt-get install python3 python3-venv`, `brew install python@3.12`) and try again.\",\n\t\t\t};\n\t\t}\n\n\t\tmkdirSync(this.runtimeDir(), { recursive: true });\n\t\tconst srcDir = this._srcDir();\n\t\tif (this._exists(srcDir)) rmSync(srcDir, { recursive: true, force: true });\n\n\t\tonProgress?.(`Cloning ${NEEDLE_REPO_URL}…`);\n\t\tconst cloned = await this._cloneAtPinnedCommit(srcDir);\n\t\tif (!cloned.ok) return cloned;\n\n\t\tonProgress?.(`Creating isolated Python venv at ${this._venvDir()}…`);\n\t\tconst venv = await this._runCommand(\"python3\", [\"-m\", \"venv\", this._venvDir()]);\n\t\tif (!venv.ok) return { ok: false, error: `setup-fail: ${tailLines(venv.error ?? venv.stderr)}` };\n\t\tif (!this._exists(this._pythonPath())) {\n\t\t\treturn { ok: false, error: `setup-fail: venv created but ${this._pythonPath()} was not found` };\n\t\t}\n\n\t\tonProgress?.(\"Upgrading pip inside the pi-managed venv…\");\n\t\tconst pipUpgrade = await this._runCommand(this._pythonPath(), [\"-m\", \"pip\", \"install\", \"--upgrade\", \"pip\"]);\n\t\tif (!pipUpgrade.ok) {\n\t\t\treturn { ok: false, error: `setup-fail: ${tailLines(pipUpgrade.error ?? pipUpgrade.stderr)}` };\n\t\t}\n\n\t\tonProgress?.(\"Installing needle (editable) into the pi-managed venv…\");\n\t\tconst install = await this._runCommand(this._pythonPath(), [\"-m\", \"pip\", \"install\", \"-e\", srcDir]);\n\t\tif (!install.ok) return { ok: false, error: `setup-fail: ${tailLines(install.error ?? install.stderr)}` };\n\n\t\tconst cudaAvailable = this._hasNvidiaGpu();\n\t\tonProgress?.(cudaAvailable ? \"Installing JAX (CUDA 12 backend)…\" : \"Installing JAX (CPU backend)…\");\n\t\tconst jaxArgs = cudaAvailable ? [\"jax[cuda12]\"] : [\"jax\"];\n\t\tconst jax = await this._runCommand(this._pythonPath(), [\"-m\", \"pip\", \"install\", \"-U\", ...jaxArgs]);\n\t\tif (!jax.ok) return { ok: false, error: `setup-fail: ${tailLines(jax.error ?? jax.stderr)}` };\n\n\t\tonProgress?.(\"Verifying the needle install…\");\n\t\tconst verify = await this._runCommand(this._pythonPath(), [\"-c\", \"import jax, needle; print(needle.__file__)\"]);\n\t\tif (!verify.ok) return { ok: false, error: `verify-fail: ${tailLines(verify.error ?? verify.stderr)}` };\n\n\t\tconst entryCommand = this._entryPath();\n\t\tif (!this._exists(entryCommand)) {\n\t\t\treturn { ok: false, error: `verify-fail: install reported success but ${entryCommand} was not found` };\n\t\t}\n\n\t\tthis._writeManifest({ commit: NEEDLE_PINNED_COMMIT, entryCommand });\n\t\tonProgress?.(\"needle installed.\");\n\t\treturn { ok: true };\n\t}\n\n\t/**\n\t * A plain `git clone --depth 1` only lands on {@link NEEDLE_PINNED_COMMIT} when it still happens\n\t * to be the remote's current default-branch tip. Fetching the exact SHA directly instead (verified\n\t * against the real repo) pins reliably even after upstream moves on: GitHub serves any reachable\n\t * commit for a public repo via `git fetch <sha>`, not just refs.\n\t */\n\tprivate async _cloneAtPinnedCommit(srcDir: string): Promise<{ ok: boolean; error?: string }> {\n\t\tconst init = await this._runCommand(\"git\", [\"init\", \"-q\", srcDir]);\n\t\tif (!init.ok) return { ok: false, error: `clone-fail: ${tailLines(init.error ?? init.stderr)}` };\n\t\tconst remote = await this._runCommand(\"git\", [\"-C\", srcDir, \"remote\", \"add\", \"origin\", NEEDLE_REPO_URL]);\n\t\tif (!remote.ok) return { ok: false, error: `clone-fail: ${tailLines(remote.error ?? remote.stderr)}` };\n\t\tconst fetched = await this._runCommand(\"git\", [\n\t\t\t\"-C\",\n\t\t\tsrcDir,\n\t\t\t\"fetch\",\n\t\t\t\"--depth\",\n\t\t\t\"1\",\n\t\t\t\"origin\",\n\t\t\tNEEDLE_PINNED_COMMIT,\n\t\t]);\n\t\tif (!fetched.ok) return { ok: false, error: `clone-fail: ${tailLines(fetched.error ?? fetched.stderr)}` };\n\t\tconst checkout = await this._runCommand(\"git\", [\"-C\", srcDir, \"checkout\", \"-q\", \"FETCH_HEAD\"]);\n\t\tif (!checkout.ok) return { ok: false, error: `clone-fail: ${tailLines(checkout.error ?? checkout.stderr)}` };\n\t\treturn { ok: true };\n\t}\n\n\t/**\n\t * Download the pretrained base weights (`needle.pkl`). `needle run` takes an explicit\n\t * `--checkpoint` and does NOT auto-download one (unlike `needle playground`/`finetune`) — see the\n\t * module docstring. Never called implicitly by installManaged/runFunctionCall; the caller decides\n\t * when to pull weights.\n\t *\n\t * `needle.pkl` is a pickle file — arbitrary code execution on load by construction (see the\n\t * module-level SECURITY note) — so every download is verified against the pinned sha256+size\n\t * ({@link NEEDLE_WEIGHTS_SHA256}/{@link NEEDLE_WEIGHTS_BYTES}, overridable only via the\n\t * `weightsIntegrity` test seam) computed in the same streaming pass that writes the file, with the\n\t * partial/mismatched file deleted on ANY failure — this never leaves an unverified or wrong pickle\n\t * sitting where {@link runFunctionCall} would load it.\n\t */\n\tasync downloadWeights(onProgress?: (status: string) => void): Promise<NeedleWeightsDownloadResult> {\n\t\tconst destPath = this.checkpointPath();\n\t\tconst url = `https://huggingface.co/${NEEDLE_HF_MODEL_REPO}/resolve/main/${NEEDLE_CHECKPOINT_FILENAME}`;\n\t\tmkdirSync(this.modelsDir(), { recursive: true });\n\n\t\tif (this._exists(destPath) && this._fileSizeBytes(destPath) === this._weightsIntegrity.bytes) {\n\t\t\tonProgress?.(\n\t\t\t\t`${NEEDLE_CHECKPOINT_FILENAME} already downloaded (${this._weightsIntegrity.bytes} bytes) — skipping.`,\n\t\t\t);\n\t\t\treturn { ok: true, path: destPath, skipped: true };\n\t\t}\n\n\t\tonProgress?.(`Downloading ${NEEDLE_CHECKPOINT_FILENAME} from ${NEEDLE_HF_MODEL_REPO}…`);\n\t\tlet response: Response;\n\t\ttry {\n\t\t\tresponse = await this._fetch(url);\n\t\t} catch (error) {\n\t\t\treturn { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };\n\t\t}\n\t\tif (!response.ok || !response.body) {\n\t\t\treturn { ok: false, error: `download-fail: HTTP ${response.status}` };\n\t\t}\n\n\t\tconst hash = createHash(\"sha256\");\n\t\ttry {\n\t\t\tawait pipeline(response.body as unknown as Readable, hashingPassThrough(hash), createWriteStream(destPath));\n\t\t} catch (error) {\n\t\t\tthis._cleanupPartial(destPath);\n\t\t\treturn { ok: false, error: `download-fail: ${error instanceof Error ? error.message : String(error)}` };\n\t\t}\n\n\t\tconst actualBytes = this._fileSizeBytes(destPath);\n\t\tconst actualSha256 = hash.digest(\"hex\");\n\t\tif (actualBytes !== this._weightsIntegrity.bytes || actualSha256 !== this._weightsIntegrity.sha256) {\n\t\t\tthis._cleanupPartial(destPath);\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: `integrity-fail: downloaded ${NEEDLE_CHECKPOINT_FILENAME} does not match the pinned checksum — expected sha256 ${this._weightsIntegrity.sha256} (${this._weightsIntegrity.bytes} bytes), got ${actualSha256} (${actualBytes ?? 0} bytes). Refusing to keep a pickle file that failed integrity verification.`,\n\t\t\t};\n\t\t}\n\n\t\tonProgress?.(`${NEEDLE_CHECKPOINT_FILENAME} downloaded and verified (sha256 ${actualSha256}).`);\n\t\treturn { ok: true, path: destPath };\n\t}\n\n\tprivate _fileSizeBytes(path: string): number | undefined {\n\t\ttry {\n\t\t\treturn statSync(path).size;\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\n\tprivate _cleanupPartial(path: string): void {\n\t\ttry {\n\t\t\trmSync(path, { force: true });\n\t\t} catch {\n\t\t\t// best-effort cleanup\n\t\t}\n\t}\n\n\t/**\n\t * Run one single-shot inference through `needle run --checkpoint ... --query ... --tools ...`\n\t * inside the contained venv's installed console script. Argv is passed as an array to the\n\t * injected `runCommand` seam — never a shell string — so query/tools text containing quotes,\n\t * spaces, or other shell-hostile characters is passed through literally (verified against a real\n\t * invocation; see the module docstring). `tools` is serialized with `JSON.stringify` exactly once.\n\t */\n\tasync runFunctionCall(\n\t\trequest: NeedleFunctionCallRequest,\n\t\toptions?: { checkpointPath?: string },\n\t): Promise<NeedleFunctionCallResult> {\n\t\tconst entryCommand = this._entryPath();\n\t\tif (!this._exists(entryCommand)) {\n\t\t\treturn { ok: false, error: \"not-installed: run installManaged() first\", rawOutput: \"\" };\n\t\t}\n\t\tconst checkpointPath = options?.checkpointPath ?? this.checkpointPath();\n\t\tif (!this._exists(checkpointPath)) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: `checkpoint-missing: no checkpoint at ${checkpointPath} — run downloadWeights() first`,\n\t\t\t\trawOutput: \"\",\n\t\t\t};\n\t\t}\n\n\t\tconst argv = [\n\t\t\t\"run\",\n\t\t\t\"--checkpoint\",\n\t\t\tcheckpointPath,\n\t\t\t\"--query\",\n\t\t\trequest.query,\n\t\t\t\"--tools\",\n\t\t\tJSON.stringify(request.tools),\n\t\t];\n\t\tconst result = await this._runCommand(entryCommand, argv);\n\t\tconst rawOutput = [result.stdout, result.stderr].filter(Boolean).join(\"\\n\");\n\t\tif (!result.ok) {\n\t\t\treturn { ok: false, error: `run-fail: ${tailLines(result.error ?? result.stderr)}`, rawOutput };\n\t\t}\n\t\treturn this._parseFunctionCall(result.stdout, rawOutput);\n\t}\n\n\t/**\n\t * Strictly parse a real `needle run` stdout capture:\n\t * ```\n\t * Loading checkpoint: <path>\n\t * Model parameters: <n>\n\t *\n\t * Query: <query>\n\t * Tools: <tools, truncated to 80 chars>...\n\t *\n\t * <tool_call>[{\"name\":\"...\",\"arguments\":{...}}]\n\t * ```\n\t * (diagnostic lines above the marker vary — e.g. a one-time \"Downloading pretrained tokenizer...\"\n\t * line on a cold cache — so parsing locates the `<tool_call>` marker rather than assuming a fixed\n\t * line count/position). Unparseable output is always an error carrying the raw text, never a\n\t * guessed result.\n\t */\n\tprivate _parseFunctionCall(stdout: string, rawOutput: string): NeedleFunctionCallResult {\n\t\tconst markerIndex = stdout.indexOf(NEEDLE_TOOL_CALL_MARKER);\n\t\tif (markerIndex < 0) {\n\t\t\treturn { ok: false, error: `unparseable-output: no ${NEEDLE_TOOL_CALL_MARKER} marker in stdout`, rawOutput };\n\t\t}\n\t\tconst jsonText = stdout.slice(markerIndex + NEEDLE_TOOL_CALL_MARKER.length).trim();\n\t\tlet parsed: unknown;\n\t\ttry {\n\t\t\tparsed = JSON.parse(jsonText);\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tok: false,\n\t\t\t\terror: `unparseable-output: ${error instanceof Error ? error.message : String(error)}`,\n\t\t\t\trawOutput,\n\t\t\t};\n\t\t}\n\t\tif (!Array.isArray(parsed) || parsed.length === 0) {\n\t\t\treturn { ok: false, error: \"unparseable-output: expected a non-empty tool-call array\", rawOutput };\n\t\t}\n\t\tconst first = parsed[0] as { name?: unknown; arguments?: unknown };\n\t\tif (\n\t\t\ttypeof first !== \"object\" ||\n\t\t\tfirst === null ||\n\t\t\ttypeof first.name !== \"string\" ||\n\t\t\ttypeof first.arguments !== \"object\" ||\n\t\t\tfirst.arguments === null\n\t\t) {\n\t\t\treturn { ok: false, error: \"unparseable-output: tool call missing name/arguments\", rawOutput };\n\t\t}\n\t\treturn { ok: true, call: { name: first.name, arguments: first.arguments as Record<string, unknown> } };\n\t}\n\n\t/** Canned get_weather query/tool through {@link runFunctionCall}; the wiring task uses this as the\n\t * post-install verification step. */\n\tasync smokeTest(onProgress?: (status: string) => void): Promise<NeedleSmokeTestResult> {\n\t\tonProgress?.(\"Running needle smoke test…\");\n\t\tconst startedAt = Date.now();\n\t\tconst result = await this.runFunctionCall({ query: NEEDLE_SMOKE_QUERY, tools: NEEDLE_SMOKE_TOOLS });\n\t\tconst latencyMs = Date.now() - startedAt;\n\t\tif (!result.ok) {\n\t\t\tonProgress?.(`Smoke test failed: ${result.error}`);\n\t\t\treturn { ok: false, latencyMs, error: result.error };\n\t\t}\n\t\tonProgress?.(`Smoke test ok (${latencyMs}ms): ${result.call.name}`);\n\t\treturn { ok: true, latencyMs, call: result.call };\n\t}\n\n\t/**\n\t * No-op: every needle invocation here is a single-shot `runCommand` call that spawns, waits for\n\t * exit, and returns — there is no persistent/detached child process this runtime owns between\n\t * calls for dispose() to track or kill (contrast OllamaRuntime/PrismLlamaCppRuntime's long-lived\n\t * `serve()` child).\n\t */\n\tdispose(): void {}\n}\n"]}