@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/models/model-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-ref.js","sourceRoot":"","sources":["../../../src/core/models/model-ref.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Model source normalizer (local-model-lifecycle-design.md, \"one panel, three types\"):\n * everything a user can paste — an ollama tag, an hf.co GGUF ref, a full HuggingFace URL, a\n * copied `ollama pull ...` install command, or an API `provider/model` name — normalizes to ONE\n * typed source. Pure string work: pasted install commands are PARSED for their reference and\n * NEVER executed as shell; unknown forms are rejected with the reason.\n */\n\nexport type ModelSource =\n\t| { type: \"api\"; ref: string }\n\t| { type: \"local\"; pullRef: string }\n\t| { type: \"transformers\"; modelId: string; ref: string }\n\t| { type: \"rejected\"; reason: string };\n\nconst OLLAMA_TAG = /^[a-z0-9][a-z0-9._-]*(?::[A-Za-z0-9._-]+)?$/;\nconst HF_REF = /^hf\\.co\\/([\\w.-]+)\\/([\\w.-]+)(?::([\\w.-]+))?$/i;\nconst HF_URL = /^https?:\\/\\/(?:www\\.)?huggingface\\.co\\/([\\w.-]+)\\/([\\w.-]+)(?:\\/.*)?$/i;\nconst SHELL_METACHARS = /[;&|`$<>(){}\\\\]/;\nconst PI_MANAGED_TRANSFORMERS_MODEL_IDS = new Set([\"openbmb/MiniCPM5-1B\"]);\n\nfunction normalizeHuggingFaceReference(org: string, repo: string, quant?: string): ModelSource {\n\tconst modelId = `${org}/${repo}`;\n\tif (!quant && PI_MANAGED_TRANSFORMERS_MODEL_IDS.has(modelId)) {\n\t\treturn { type: \"transformers\", modelId, ref: `hf.co/${modelId}` };\n\t}\n\treturn { type: \"local\", pullRef: `hf.co/${modelId}${quant ? `:${quant}` : \"\"}` };\n}\n\nexport function normalizeModelSource(rawInput: string): ModelSource {\n\tconst input = rawInput.trim();\n\tif (input.length === 0) return { type: \"rejected\", reason: \"empty input\" };\n\tif (input.length > 500) return { type: \"rejected\", reason: \"input too long to be a model reference\" };\n\n\t// Pasted install command: extract the reference, never execute anything.\n\tconst installCommand = /^ollama\\s+(?:pull|run)\\s+(.+)$/i.exec(input);\n\tif (installCommand) {\n\t\tconst argument = installCommand[1]!.trim().split(/\\s+/)[0] ?? \"\";\n\t\tif (SHELL_METACHARS.test(argument)) {\n\t\t\treturn { type: \"rejected\", reason: \"install command argument contains shell metacharacters\" };\n\t\t}\n\t\tconst inner = normalizeModelSource(argument);\n\t\tif (inner.type === \"local\") return inner;\n\t\treturn { type: \"rejected\", reason: `could not extract a model reference from the install command` };\n\t}\n\n\tif (SHELL_METACHARS.test(input) || /\\s/.test(input)) {\n\t\treturn { type: \"rejected\", reason: \"not a recognized model reference (contains spaces or shell characters)\" };\n\t}\n\n\t// Full HuggingFace URL -> either a pi-managed Transformers model (curated full-base ids) or an\n\t// Ollama hf.co pull ref (GGUF/quant refs still belong to Ollama and keep their :quant suffix).\n\tconst hfUrl = HF_URL.exec(input);\n\tif (hfUrl) {\n\t\treturn normalizeHuggingFaceReference(hfUrl[1]!, hfUrl[2]!);\n\t}\n\n\t// hf.co/org/repo[:quant]\n\tconst hfRef = HF_REF.exec(input);\n\tif (hfRef) {\n\t\treturn normalizeHuggingFaceReference(hfRef[1]!, hfRef[2]!, hfRef[3]);\n\t}\n\n\tif (input.includes(\"://\")) {\n\t\treturn { type: \"rejected\", reason: \"only huggingface.co URLs are recognized as local model links\" };\n\t}\n\n\t// provider/model -> API-registered model (nothing to install; auth + selection only).\n\tif (input.includes(\"/\")) {\n\t\tconst [provider, ...rest] = input.split(\"/\");\n\t\tconst model = rest.join(\"/\");\n\t\tif (provider && model && !model.includes(\"/\")) {\n\t\t\treturn { type: \"api\", ref: `${provider}/${model}` };\n\t\t}\n\t\treturn { type: \"rejected\", reason: \"expected provider/model or hf.co/org/repo[:quant]\" };\n\t}\n\n\t// Bare ollama tag (\"qwen3:1.7b\", \"pi-lifter:latest\", \"llama3\").\n\tif (OLLAMA_TAG.test(input)) {\n\t\treturn { type: \"local\", pullRef: input };\n\t}\n\n\treturn { type: \"rejected\", reason: \"not a recognized model reference\" };\n}\n\n/**\n * Whether an installed-model listing entry (`installedName`, as `OllamaRuntime.list()` reports it)\n * is the same model as `ref` (a user-typed reference, or a `models.json`-registered id). Ollama\n * always reports installed models with an explicit tag — a pull with no tag is normalized to\n * `:latest` server-side — but a `ref` is frequently bare (\"llama3\"), so an exact string compare\n * alone misses that pairing. Exact match always counts; otherwise treat a bare ref against its\n * `:latest`-tagged listing as the same model, and the reverse (a `ref` explicitly pinned to\n * `:latest` against a bare listing), since the local-runtime interface is kept runtime-agnostic\n * (see local-runtime.ts's module docstring) and a future/alternate runtime could list bare names.\n * Shared by every ref-vs-installed-list comparison — see `AgentSession._warnIfManualModelChoiceIsRisky`\n * and `removeLocalModel` in interactive-mode.ts, which had the identical bug independently.\n */\nexport function matchesInstalledLocalModel(ref: string, installedName: string): boolean {\n\tif (ref === installedName) return true;\n\tconst hasTag = (value: string): boolean => value.includes(\":\");\n\tif (!hasTag(ref) && installedName === `${ref}:latest`) return true;\n\tif (!hasTag(installedName) && ref === `${installedName}:latest`) return true;\n\treturn false;\n}\n"]}
+{"version":3,"file":"model-ref.js","sourceRoot":"","sources":["../../../src/core/models/model-ref.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Model source normalizer (local-model-lifecycle-design.md, \"one panel, three types\"):\n * everything a user can paste — an ollama tag, an hf.co GGUF ref, a full HuggingFace URL, a\n * copied `ollama pull ...` install command, or an API `provider/model` name — normalizes to ONE\n * typed source. Pure string work: pasted install commands are PARSED for their reference and\n * NEVER executed as shell; unknown forms are rejected with the reason.\n */\n\nimport { BONSAI_27B } from \"./llamacpp-runtime.ts\";\n\nexport type ModelSource =\n\t| { type: \"api\"; ref: string }\n\t| { type: \"local\"; pullRef: string }\n\t| { type: \"transformers\"; modelId: string; ref: string }\n\t| { type: \"prism-llamacpp\"; modelId: string; ref: string }\n\t| { type: \"needle\"; ref: string }\n\t| { type: \"rejected\"; reason: string };\n\nconst OLLAMA_TAG = /^[a-z0-9][a-z0-9._-]*(?::[A-Za-z0-9._-]+)?$/;\nconst HF_REF = /^hf\\.co\\/([\\w.-]+)\\/([\\w.-]+)(?::([\\w.-]+))?$/i;\nconst HF_URL = /^https?:\\/\\/(?:www\\.)?huggingface\\.co\\/([\\w.-]+)\\/([\\w.-]+)(?:\\/.*)?$/i;\nconst SHELL_METACHARS = /[;&|`$<>(){}\\\\]/;\nconst PI_MANAGED_TRANSFORMERS_MODEL_IDS = new Set([\"openbmb/MiniCPM5-1B\"]);\n/**\n * Curated prism-ml models that require pi's managed prism llama.cpp fork (see llamacpp-runtime.ts's\n * module docstring: stock llama.cpp/Ollama cannot serve these weights). These GGUF refs route to the\n * \"prism-llamacpp\" source instead of Ollama's local pull path regardless of a supplied quant suffix\n * — the curated descriptor already pins the exact quant file to fetch, so a quant on the input ref is\n * accepted but not required. Keyed lowercase for case-insensitive matching; values are the\n * canonical-cased modelId, sourced from the descriptor itself so the two never drift apart.\n */\nconst PRISM_LLAMACPP_MODEL_IDS = new Map<string, string>([[BONSAI_27B.repo.toLowerCase(), BONSAI_27B.repo]]);\n/**\n * The single curated needle model id (see needle-runtime.ts) — a standalone function-call test\n * bench with no GGUF/quant concept at all (a pip-installed Python package + one pinned pickle\n * checkpoint), so unlike the prism route above, a quant suffix on the input is NOT accepted — it\n * falls through to the ordinary local/Ollama route instead, mirroring the transformers route's\n * `!quant` gate. Only this exact repo routes to \"needle\"; any other Cactus-Compute/* ref keeps the\n * ordinary local route.\n */\nconst NEEDLE_MODEL_ID = \"Cactus-Compute/needle\";\n\nfunction normalizeHuggingFaceReference(org: string, repo: string, quant?: string): ModelSource {\n\tconst modelId = `${org}/${repo}`;\n\tconst prismModelId = PRISM_LLAMACPP_MODEL_IDS.get(modelId.toLowerCase());\n\tif (prismModelId) {\n\t\treturn { type: \"prism-llamacpp\", modelId: prismModelId, ref: `hf.co/${prismModelId}` };\n\t}\n\tif (!quant && modelId.toLowerCase() === NEEDLE_MODEL_ID.toLowerCase()) {\n\t\treturn { type: \"needle\", ref: `hf.co/${NEEDLE_MODEL_ID}` };\n\t}\n\tif (!quant && PI_MANAGED_TRANSFORMERS_MODEL_IDS.has(modelId)) {\n\t\treturn { type: \"transformers\", modelId, ref: `hf.co/${modelId}` };\n\t}\n\treturn { type: \"local\", pullRef: `hf.co/${modelId}${quant ? `:${quant}` : \"\"}` };\n}\n\nexport function normalizeModelSource(rawInput: string): ModelSource {\n\tconst input = rawInput.trim();\n\tif (input.length === 0) return { type: \"rejected\", reason: \"empty input\" };\n\tif (input.length > 500) return { type: \"rejected\", reason: \"input too long to be a model reference\" };\n\n\t// Pasted install command: extract the reference, never execute anything.\n\tconst installCommand = /^ollama\\s+(?:pull|run)\\s+(.+)$/i.exec(input);\n\tif (installCommand) {\n\t\tconst argument = installCommand[1]!.trim().split(/\\s+/)[0] ?? \"\";\n\t\tif (SHELL_METACHARS.test(argument)) {\n\t\t\treturn { type: \"rejected\", reason: \"install command argument contains shell metacharacters\" };\n\t\t}\n\t\tconst inner = normalizeModelSource(argument);\n\t\tif (inner.type === \"local\") return inner;\n\t\treturn { type: \"rejected\", reason: `could not extract a model reference from the install command` };\n\t}\n\n\tif (SHELL_METACHARS.test(input) || /\\s/.test(input)) {\n\t\treturn { type: \"rejected\", reason: \"not a recognized model reference (contains spaces or shell characters)\" };\n\t}\n\n\t// Full HuggingFace URL -> either a pi-managed Transformers model (curated full-base ids) or an\n\t// Ollama hf.co pull ref (GGUF/quant refs still belong to Ollama and keep their :quant suffix).\n\tconst hfUrl = HF_URL.exec(input);\n\tif (hfUrl) {\n\t\treturn normalizeHuggingFaceReference(hfUrl[1]!, hfUrl[2]!);\n\t}\n\n\t// hf.co/org/repo[:quant]\n\tconst hfRef = HF_REF.exec(input);\n\tif (hfRef) {\n\t\treturn normalizeHuggingFaceReference(hfRef[1]!, hfRef[2]!, hfRef[3]);\n\t}\n\n\tif (input.includes(\"://\")) {\n\t\treturn { type: \"rejected\", reason: \"only huggingface.co URLs are recognized as local model links\" };\n\t}\n\n\t// provider/model -> API-registered model (nothing to install; auth + selection only).\n\tif (input.includes(\"/\")) {\n\t\tconst [provider, ...rest] = input.split(\"/\");\n\t\tconst model = rest.join(\"/\");\n\t\tif (provider && model && !model.includes(\"/\")) {\n\t\t\treturn { type: \"api\", ref: `${provider}/${model}` };\n\t\t}\n\t\treturn { type: \"rejected\", reason: \"expected provider/model or hf.co/org/repo[:quant]\" };\n\t}\n\n\t// Bare ollama tag (\"qwen3:1.7b\", \"pi-lifter:latest\", \"llama3\").\n\tif (OLLAMA_TAG.test(input)) {\n\t\treturn { type: \"local\", pullRef: input };\n\t}\n\n\treturn { type: \"rejected\", reason: \"not a recognized model reference\" };\n}\n\n/**\n * Whether an installed-model listing entry (`installedName`, as `OllamaRuntime.list()` reports it)\n * is the same model as `ref` (a user-typed reference, or a `models.json`-registered id). Ollama\n * always reports installed models with an explicit tag — a pull with no tag is normalized to\n * `:latest` server-side — but a `ref` is frequently bare (\"llama3\"), so an exact string compare\n * alone misses that pairing. Exact match always counts; otherwise treat a bare ref against its\n * `:latest`-tagged listing as the same model, and the reverse (a `ref` explicitly pinned to\n * `:latest` against a bare listing), since the local-runtime interface is kept runtime-agnostic\n * (see local-runtime.ts's module docstring) and a future/alternate runtime could list bare names.\n * Shared by every ref-vs-installed-list comparison — see `AgentSession._warnIfManualModelChoiceIsRisky`\n * and `removeLocalModel` in interactive-mode.ts, which had the identical bug independently.\n */\nexport function matchesInstalledLocalModel(ref: string, installedName: string): boolean {\n\tif (ref === installedName) return true;\n\tconst hasTag = (value: string): boolean => value.includes(\":\");\n\tif (!hasTag(ref) && installedName === `${ref}:latest`) return true;\n\tif (!hasTag(installedName) && ref === `${installedName}:latest`) return true;\n\treturn false;\n}\n"]}

package/dist/core/models/needle-runtime.d.ts

@@ -0,0 +1,257 @@
+import type { RuntimeCommandRunner } from "./local-runtime.ts";
+/**
+ * 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 declare 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 declare const NEEDLE_PINNED_COMMIT = "ffb1c5144c5a16cb8ec650dbc8a6f6fd3854f8f2";
+/**
+ * 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 declare const NEEDLE_WEIGHTS_SHA256 = "40a32e91d1d4197bf15ba559b74f6727c342dc8746918742fc7d8e2c1f18df40";
+export declare const NEEDLE_WEIGHTS_BYTES = 52633098;
+export interface NeedleDetectResult {
+    installed: boolean;
+    installDir?: string;
+    commit?: string;
+    pythonAvailable: boolean;
+    checkpointPresent: boolean;
+}
+export interface NeedleFunctionCallRequest {
+    query: string;
+    /** A JSON-serializable tool schema value (never a pre-stringified JSON string) — serialized
+     * exactly once by {@link NeedleRuntime.runFunctionCall}, never by the caller. */
+    tools: unknown;
+}
+export interface NeedleFunctionCall {
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export type NeedleFunctionCallResult = {
+    ok: true;
+    call: NeedleFunctionCall;
+} | {
+    ok: false;
+    error: string;
+    rawOutput: string;
+};
+export interface NeedleSmokeTestResult {
+    ok: boolean;
+    latencyMs: number;
+    call?: NeedleFunctionCall;
+    error?: string;
+}
+export interface NeedleWeightsDownloadResult {
+    ok: boolean;
+    path?: string;
+    skipped?: boolean;
+    error?: string;
+}
+interface NeedleWeightsIntegrity {
+    sha256: string;
+    bytes: number;
+}
+export interface NeedleRuntimeDeps {
+    existsFn?: (path: string) => boolean;
+    fetchFn?: typeof fetch;
+    /** Runs git/pip/python commands. Injectable so installManaged/runFunctionCall's orchestration is
+     * testable without a real clone/venv/inference. Defaults to a real spawn-and-collect-output
+     * runner (installs can run long; a single inference call is comparatively quick but still shells
+     * out to a real interpreter). */
+    runCommand?: RuntimeCommandRunner;
+    /** Whether a named command exists on PATH (git, python3, nvidia-smi). */
+    hasCommand?: (command: string) => boolean;
+    hasNvidiaGpu?: () => boolean;
+    platform?: () => string;
+    /** Expected weights sha256+size. Defaults to {@link NEEDLE_WEIGHTS_SHA256}/{@link
+     * NEEDLE_WEIGHTS_BYTES} — the real pinned values. Overridable ONLY so tests can exercise the full
+     * download+verify path with small synthetic content instead of the real 52MB pickle; this is a
+     * constructor-level seam for a trusted caller, the same trust boundary every other injectable dep
+     * in this class already relies on (fetchFn/runCommand could equally be used to bypass anything).
+     */
+    weightsIntegrity?: NeedleWeightsIntegrity;
+}
+export declare class NeedleRuntime {
+    private readonly _agentDir;
+    private readonly _exists;
+    private readonly _fetch;
+    private readonly _runCommand;
+    private readonly _hasCommand;
+    private readonly _hasNvidiaGpu;
+    private readonly _platform;
+    private readonly _weightsIntegrity;
+    constructor(args: {
+        agentDir: string;
+        deps?: NeedleRuntimeDeps;
+    });
+    runtimeDir(): string;
+    modelsDir(): string;
+    checkpointPath(): string;
+    private _srcDir;
+    private _venvDir;
+    private _pythonPath;
+    /** 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. */
+    private _entryPath;
+    private _manifestPath;
+    private _readManifest;
+    private _writeManifest;
+    detect(): Promise<NeedleDetectResult>;
+    /**
+     * 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.
+     */
+    installManaged(onProgress?: (status: string) => void): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    private _cloneAtPinnedCommit;
+    /**
+     * 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.
+     */
+    downloadWeights(onProgress?: (status: string) => void): Promise<NeedleWeightsDownloadResult>;
+    private _fileSizeBytes;
+    private _cleanupPartial;
+    /**
+     * 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.
+     */
+    runFunctionCall(request: NeedleFunctionCallRequest, options?: {
+        checkpointPath?: string;
+    }): Promise<NeedleFunctionCallResult>;
+    /**
+     * 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.
+     */
+    private _parseFunctionCall;
+    /** Canned get_weather query/tool through {@link runFunctionCall}; the wiring task uses this as the
+     * post-install verification step. */
+    smokeTest(onProgress?: (status: string) => void): Promise<NeedleSmokeTestResult>;
+    /**
+     * 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(): void;
+}
+export {};
+//# sourceMappingURL=needle-runtime.d.ts.map

package/dist/core/models/needle-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"needle-runtime.d.ts","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"]}