fix(onboard): make the Ollama model pull timeout configurable (#3037)

## Summary

The Ollama model pull was wrapped with a hardcoded 10-minute wall-clock
timeout in both pull paths, so sustained network throughput below ~8
MB/s could not complete the default 4.7 GB qwen2.5:7b pull (each retry
resumed from the last layer but still hit SIGTERM at the next 10-minute
boundary). Replace the hardcoded value with a
`NEMOCLAW_OLLAMA_PULL_TIMEOUT` env-var override (seconds) defaulting to
30 minutes, and surface the override hint in the timeout error messages.

## Related Issue

Closes #2610

## Changes

- Add `DEFAULT_OLLAMA_PULL_TIMEOUT_MS` (30 minutes),
`getOllamaPullTimeoutMs()` (parses `NEMOCLAW_OLLAMA_PULL_TIMEOUT` in
seconds with fallback for unset / empty / non-numeric / non-positive
inputs), and `pullTimeoutErrorHint()` (prints elapsed minutes, the
resume-on-retry note, and the env var hint) in
`src/lib/onboard-ollama-proxy.ts`.
- Wire the helper into `pullOllamaModelViaCli` (replacing the hardcoded
`timeout: 600_000` on `spawnSync`) and `pullOllamaModelViaHttp`
(replacing the hardcoded `TIMEOUT_MS = 600_000` on the curl `--max-time`
deadline). The HTTP-path non-timeout error path retains its existing
wording.
- Export `getOllamaPullTimeoutMs` so the unit tests can exercise the
parser without shelling out to `ollama pull`.
- Add `test/ollama-pull-timeout.test.ts` covering: default fallback when
unset, empty, or whitespace; positive integer seconds → ms conversion;
truncated fractional seconds; non-numeric fallback; zero/negative
fallback.

## Type of Change

- [x] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Verification

- [x] `npx prek run --all-files` passes
- [x] `npm test` passes
- [x] Tests added or updated for new or changed behavior
- [x] No secrets, API keys, or credentials committed
- [ ] Docs updated for user-facing behavior changes
- [ ] `make docs` builds without warnings (doc changes only)
- [ ] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---
Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added configurable Ollama model-pull timeout via environment variable
(30-minute default) with improved timeout error messaging.

* **Tests**
* Added test suite validating timeout configuration, conversion, and
error handling behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>
Signed-off-by: Aaron Erickson <aerickson@nvidia.com>
Co-authored-by: Aaron Erickson <aerickson@nvidia.com>

Author: laitingsheng

src/lib/onboard-ollama-proxy.ts

@@ -306,18 +306,37 @@ function printOllamaExposureWarning() {
   console.log("");
 }
 
+const DEFAULT_OLLAMA_PULL_TIMEOUT_MS = 30 * 60 * 1000;
+const PULL_TIMEOUT_ENV = "NEMOCLAW_OLLAMA_PULL_TIMEOUT";
+
+function getOllamaPullTimeoutMs(): number {
+  const raw = process.env[PULL_TIMEOUT_ENV];
+  if (typeof raw !== "string" || raw.trim() === "") return DEFAULT_OLLAMA_PULL_TIMEOUT_MS;
+  const seconds = Number(raw.trim());
+  if (!Number.isFinite(seconds) || seconds <= 0) return DEFAULT_OLLAMA_PULL_TIMEOUT_MS;
+  return Math.floor(seconds * 1000);
+}
+
+function pullTimeoutErrorHint(timeoutMs: number): string {
+  const minutes = Math.round(timeoutMs / 60_000);
+  return [
+    `  Model pull timed out after ${minutes} minutes.`,
+    "  Already-downloaded layers are kept; re-running the pull resumes them.",
+    `  Set ${PULL_TIMEOUT_ENV}=<seconds> to raise the wall-clock limit (default ${Math.round(DEFAULT_OLLAMA_PULL_TIMEOUT_MS / 60_000)} minutes).`,
+  ].join("\n");
+}
+
 function pullOllamaModelViaCli(model) {
+  const timeoutMs = getOllamaPullTimeoutMs();
   const result = spawnSync("bash", ["-c", `ollama pull ${shellQuote(model)}`], {
     cwd: ROOT,
     encoding: "utf8",
     stdio: "inherit",
-    timeout: 600_000,
+    timeout: timeoutMs,
     env: buildSubprocessEnv(),
   });
   if (result.signal === "SIGTERM") {
-    console.error(
-      `  Model pull timed out after 10 minutes. Try a smaller model or check your network connection.`,
-    );
+    console.error(pullTimeoutErrorHint(timeoutMs));
     return false;
   }
   return result.status === 0;
@@ -332,7 +351,7 @@ function pullOllamaModelViaHttp(model) {
     const host = getResolvedOllamaHost();
     const url = `http://${host}:${OLLAMA_PORT}/api/pull`;
     const body = JSON.stringify({ model, stream: true });
-    const TIMEOUT_MS = 600_000; // 10 min, matches the CLI path
+    const TIMEOUT_MS = getOllamaPullTimeoutMs();
     const isTTY = Boolean(process.stdout.isTTY);
     const BAR_WIDTH = 40;
 
@@ -343,7 +362,7 @@ function pullOllamaModelViaHttp(model) {
         "--connect-timeout",
         "10",
         "--max-time",
-        String(Math.floor(TIMEOUT_MS / 1000)),
+        String(TIMEOUT_MS / 1000),
         "-X",
         "POST",
         "-H",
@@ -450,11 +469,11 @@ function pullOllamaModelViaHttp(model) {
       if (code !== 0) {
         // curl exit 28 = CURLE_OPERATION_TIMEDOUT (--max-time hit).
         if (code === 28) {
-          console.error(`  Model pull timed out after ${TIMEOUT_MS / 60_000} minutes.`);
+          console.error(pullTimeoutErrorHint(TIMEOUT_MS));
         } else {
           console.error(`  Model pull exited with code ${String(code)} (network error).`);
+          console.error("  Already-downloaded layers are kept; re-running the pull resumes them.");
         }
-        console.error("  Already-downloaded layers are kept; re-running the pull resumes them.");
         resolve(false);
         return;
       }
@@ -551,6 +570,7 @@ function unloadOllamaModels() {
 export {
   ensureOllamaAuthProxy,
   getOllamaProxyToken,
+  getOllamaPullTimeoutMs,
   isProxyHealthy,
   killStaleProxy,
   persistProxyToken,

test/ollama-pull-timeout.test.ts

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawnSync } from "child_process";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { getOllamaPullTimeoutMs } from "../dist/lib/onboard-ollama-proxy.js";
+
+const ENV = "NEMOCLAW_OLLAMA_PULL_TIMEOUT";
+const DEFAULT_MS = 30 * 60 * 1000;
+
+describe("getOllamaPullTimeoutMs", () => {
+  const original = process.env[ENV];
+  afterEach(() => {
+    if (original === undefined) delete process.env[ENV];
+    else process.env[ENV] = original;
+  });
+
+  it("falls back to the 30-minute default when the env var is unset", () => {
+    delete process.env[ENV];
+    expect(getOllamaPullTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("falls back to the default when the env var is empty or whitespace", () => {
+    process.env[ENV] = "";
+    expect(getOllamaPullTimeoutMs()).toBe(DEFAULT_MS);
+    process.env[ENV] = "   ";
+    expect(getOllamaPullTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("converts a positive integer seconds value to milliseconds", () => {
+    process.env[ENV] = "1800";
+    expect(getOllamaPullTimeoutMs()).toBe(1_800_000);
+  });
+
+  it("converts fractional second inputs to milliseconds", () => {
+    process.env[ENV] = "1.5";
+    expect(getOllamaPullTimeoutMs()).toBe(1_500);
+  });
+
+  it("preserves sub-second precision when passing the HTTP pull timeout to curl", () => {
+    const repoRoot = path.join(import.meta.dirname, "..");
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-ollama-pull-timeout-"));
+    const scriptPath = path.join(tmpDir, "http-timeout-check.js");
+    const proxyPath = JSON.stringify(path.join(repoRoot, "dist", "lib", "onboard-ollama-proxy.js"));
+    const localInferencePath = JSON.stringify(path.join(repoRoot, "dist", "lib", "local-inference.js"));
+    const script = `
+const { EventEmitter } = require("events");
+const { PassThrough } = require("stream");
+const childProcess = require("child_process");
+const localInference = require(${localInferencePath});
+
+let captured = null;
+childProcess.spawn = (cmd, args) => {
+  captured = { cmd, args };
+  const child = new EventEmitter();
+  child.stdout = new PassThrough();
+  child.stderr = new PassThrough();
+  process.nextTick(() => {
+    child.stdout.end('{"status":"success"}\\n', () => {
+      setImmediate(() => child.emit("close", 0));
+    });
+  });
+  return child;
+};
+
+localInference.setResolvedOllamaHost(localInference.OLLAMA_HOST_DOCKER_INTERNAL);
+process.env.${ENV} = "0.5";
+
+const { pullOllamaModel } = require(${proxyPath});
+
+const originalLog = console.log;
+console.log = () => {};
+pullOllamaModel("qwen2.5:7b")
+  .then((ok) => {
+    console.log = originalLog;
+    originalLog(JSON.stringify({ ok, captured }));
+  })
+  .catch((error) => {
+    console.log = originalLog;
+    console.error(error);
+    process.exit(1);
+  });
+`;
+    fs.writeFileSync(scriptPath, script);
+
+    const result = spawnSync(process.execPath, [scriptPath], {
+      cwd: repoRoot,
+      encoding: "utf-8",
+    });
+
+    expect(result.status, result.stderr).toBe(0);
+    const payload = JSON.parse(result.stdout.trim());
+    expect(payload.ok).toBe(true);
+    expect(payload.captured.cmd).toBe("curl");
+    const maxTimeIndex = payload.captured.args.indexOf("--max-time");
+    expect(maxTimeIndex).toBeGreaterThanOrEqual(0);
+    expect(payload.captured.args[maxTimeIndex + 1]).toBe("0.5");
+  });
+
+  it("falls back to the default for non-numeric values", () => {
+    process.env[ENV] = "thirty-minutes";
+    expect(getOllamaPullTimeoutMs()).toBe(DEFAULT_MS);
+  });
+
+  it("falls back to the default for zero or negative values", () => {
+    process.env[ENV] = "0";
+    expect(getOllamaPullTimeoutMs()).toBe(DEFAULT_MS);
+    process.env[ENV] = "-60";
+    expect(getOllamaPullTimeoutMs()).toBe(DEFAULT_MS);
+  });
+});