@caupulican/pi-adaptative 0.81.32 → 0.81.37

package/dist/core/default-tool-surface.js

@@ -4,15 +4,34 @@
  * RuntimeBuilder still registers additional opt-in tools, while model capability and UAC profile
  * filters may only narrow this request. Keeping the SDK and direct-runtime paths on one list avoids
  * silently losing goal/delegation/toolkit capabilities in SDK-created interactive sessions.
+ *
+ * `bash` is the stable agent shell contract on every platform; its finite grammar routes to
+ * PowerShell on Windows. `python` is a separate bounded, uv-managed execution contract.
  */
-export const DEFAULT_ACTIVE_TOOL_NAMES = [
-    "read",
-    "bash",
-    "edit",
-    "write",
-    "context_audit",
-    "goal",
-    "delegate",
-    "run_toolkit_script",
-];
+export function getDefaultActiveToolNames(_platform = process.platform) {
+    return [
+        "read",
+        "bash",
+        "python",
+        "edit",
+        "write",
+        "context_audit",
+        "goal",
+        "task_steps",
+        "delegate",
+        "run_toolkit_script",
+    ];
+}
+/** Current-process default tool request. */
+export const DEFAULT_ACTIVE_TOOL_NAMES = getDefaultActiveToolNames();
+/** Map legacy/platform-specific shell names to the stable Bash-like agent contract. */
+export function mapToolNamesForPlatform(names, _platform = process.platform) {
+    const mapped = [];
+    for (const name of names) {
+        const resolved = name === "powershell" ? "bash" : name;
+        if (!mapped.includes(resolved))
+            mapped.push(resolved);
+    }
+    return mapped;
+}
 //# sourceMappingURL=default-tool-surface.js.map

package/dist/core/default-tool-surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"default-tool-surface.js","sourceRoot":"","sources":["../../src/core/default-tool-surface.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAsB;IAC3D,MAAM;IACN,MAAM;IACN,MAAM;IACN,OAAO;IACP,eAAe;IACf,MAAM;IACN,UAAU;IACV,oBAAoB;CACpB,CAAC","sourcesContent":["/**\n * Default built-in tool request shared by every AgentSession construction path.\n *\n * RuntimeBuilder still registers additional opt-in tools, while model capability and UAC profile\n * filters may only narrow this request. Keeping the SDK and direct-runtime paths on one list avoids\n * silently losing goal/delegation/toolkit capabilities in SDK-created interactive sessions.\n */\nexport const DEFAULT_ACTIVE_TOOL_NAMES: readonly string[] = [\n\t\"read\",\n\t\"bash\",\n\t\"edit\",\n\t\"write\",\n\t\"context_audit\",\n\t\"goal\",\n\t\"delegate\",\n\t\"run_toolkit_script\",\n];\n"]}
+{"version":3,"file":"default-tool-surface.js","sourceRoot":"","sources":["../../src/core/default-tool-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAS,GAAoB,OAAO,CAAC,QAAQ,EAAqB;IAC3G,OAAO;QACN,MAAM;QACN,MAAM;QACN,QAAQ;QACR,MAAM;QACN,OAAO;QACP,eAAe;QACf,MAAM;QACN,YAAY;QACZ,UAAU;QACV,oBAAoB;KACpB,CAAC;AAAA,CACF;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,yBAAyB,GAAsB,yBAAyB,EAAE,CAAC;AAExF,uFAAuF;AACvF,MAAM,UAAU,uBAAuB,CACtC,KAAwB,EACxB,SAAS,GAAoB,OAAO,CAAC,QAAQ,EAClC;IACX,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd","sourcesContent":["/**\n * Default built-in tool request shared by every AgentSession construction path.\n *\n * RuntimeBuilder still registers additional opt-in tools, while model capability and UAC profile\n * filters may only narrow this request. Keeping the SDK and direct-runtime paths on one list avoids\n * silently losing goal/delegation/toolkit capabilities in SDK-created interactive sessions.\n *\n * `bash` is the stable agent shell contract on every platform; its finite grammar routes to\n * PowerShell on Windows. `python` is a separate bounded, uv-managed execution contract.\n */\nexport function getDefaultActiveToolNames(_platform: NodeJS.Platform = process.platform): readonly string[] {\n\treturn [\n\t\t\"read\",\n\t\t\"bash\",\n\t\t\"python\",\n\t\t\"edit\",\n\t\t\"write\",\n\t\t\"context_audit\",\n\t\t\"goal\",\n\t\t\"task_steps\",\n\t\t\"delegate\",\n\t\t\"run_toolkit_script\",\n\t];\n}\n\n/** Current-process default tool request. */\nexport const DEFAULT_ACTIVE_TOOL_NAMES: readonly string[] = getDefaultActiveToolNames();\n\n/** Map legacy/platform-specific shell names to the stable Bash-like agent contract. */\nexport function mapToolNamesForPlatform(\n\tnames: readonly string[],\n\t_platform: NodeJS.Platform = process.platform,\n): string[] {\n\tconst mapped: string[] = [];\n\tfor (const name of names) {\n\t\tconst resolved = name === \"powershell\" ? \"bash\" : name;\n\t\tif (!mapped.includes(resolved)) mapped.push(resolved);\n\t}\n\treturn mapped;\n}\n"]}

package/dist/core/doctor.d.ts

@@ -1,5 +1,6 @@
-import { type FffInstallOutcome, type SystemToolStatus } from "../utils/tools-manager.ts";
+import { type FffInstallOutcome } from "../utils/tools-manager.ts";
 import { OllamaRuntime } from "./models/local-runtime.ts";
+import { type PythonRuntimeOutcome } from "./python-runtime.ts";
 /**
  * Environment doctor: verifies required tooling and installs what it safely
  * can, instead of leaving provisioning entirely to lazy first-use (the exact
@@ -8,13 +9,10 @@ import { OllamaRuntime } from "./models/local-runtime.ts";
  * for the underlying lazy-install fix; this module is the proactive half).
  *
  * Two tool kinds, two different postures:
- * - "managed": pi already owns the install path (fff-node into
- *   ~/.pi/agent/bin via tools-manager.ts's ensureFffNodePackage). The doctor
- *   actually attempts the install when missing.
- * - "system": pi does not own the install (ripgrep, ollama, python). GUIDE
- *   MODE only -- exact manual steps are reported, never executed, never
- *   `curl | sh`, never `sudo`. This matches the harness's deliberate
- *   no-silent-installer stance for tooling outside its own managed bin dir.
+ * - "managed": pi owns provisioning and attempts it when absent (fff-node,
+ *   plus pinned uv and the Python interpreter resolved through it).
+ * - "system": pi does not own the install (ripgrep and ollama). GUIDE MODE
+ *   only -- exact manual steps are reported, never executed.
  */
 export type DoctorToolKind = "managed" | "system";
 export interface DoctorCheck {
@@ -41,7 +39,9 @@ export interface DoctorDeps {
     ensureFffNodePackage: (silent?: boolean) => Promise<unknown | undefined>;
     getLastFffInstallOutcome: () => FffInstallOutcome | undefined;
     getRgPath: () => string | null;
-    detectPython: () => SystemToolStatus;
+    ensurePythonRuntime: (options: {
+        silent: boolean;
+    }) => Promise<PythonRuntimeOutcome>;
     /** Best-effort `<command> --version` probe; undefined if it can't be run. Used only to enrich a status line, never for presence detection. */
     probeVersion: (command: string, versionArgs?: readonly string[]) => string | undefined;
     ollamaRuntime: DoctorOllamaRuntime;
@@ -62,5 +62,5 @@ export declare function formatDoctorReport(report: DoctorReport): string;
  * succeeds. Must never fail the update itself: any error here is swallowed
  * and reported as a skipped check, not surfaced as an update failure.
  */
-export declare function runUpdatePreflight(): Promise<void>;
+export declare function runUpdatePreflight(deps?: DoctorDeps): Promise<void>;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/core/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,EAGN,KAAK,iBAAiB,EAKtB,KAAK,gBAAgB,EACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE1D;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,WAAW;IAC3B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,qHAAqH;AACrH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,cAAc,CAAC,CAAC;AAEjF,MAAM,WAAW,UAAU;IAC1B,2BAA2B,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IACvD,oBAAoB,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IACzE,wBAAwB,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAC;IAC9D,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,MAAM,gBAAgB,CAAC;IACrC,8IAA8I;IAC9I,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;IACvF,aAAa,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAyHD,wBAAsB,SAAS,CAC9B,IAAI,GAAE,UAA2B,EACjC,OAAO,GAAE,gBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAIvB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAW/D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOxD","sourcesContent":["import chalk from \"chalk\";\nimport { getAgentDir } from \"../config.ts\";\nimport {\n\tdetectPython,\n\tensureFffNodePackage,\n\ttype FffInstallOutcome,\n\tgetLastFffInstallOutcome,\n\tgetToolPath,\n\tloadAvailableFffNodePackage,\n\tprobeVersion,\n\ttype SystemToolStatus,\n} from \"../utils/tools-manager.ts\";\nimport { OllamaRuntime } from \"./models/local-runtime.ts\";\n\n/**\n * Environment doctor: verifies required tooling and installs what it safely\n * can, instead of leaving provisioning entirely to lazy first-use (the exact\n * gap behind \"ran `pi-adaptative update` on another machine and fff-node\n * never got installed\" -- see fff-lazy-install.test.ts/fff-search-tools.test.ts\n * for the underlying lazy-install fix; this module is the proactive half).\n *\n * Two tool kinds, two different postures:\n * - \"managed\": pi already owns the install path (fff-node into\n *   ~/.pi/agent/bin via tools-manager.ts's ensureFffNodePackage). The doctor\n *   actually attempts the install when missing.\n * - \"system\": pi does not own the install (ripgrep, ollama, python). GUIDE\n *   MODE only -- exact manual steps are reported, never executed, never\n *   `curl | sh`, never `sudo`. This matches the harness's deliberate\n *   no-silent-installer stance for tooling outside its own managed bin dir.\n */\n\nexport type DoctorToolKind = \"managed\" | \"system\";\n\nexport interface DoctorCheck {\n\t/** Stable identifier, e.g. \"fff-node\", \"ripgrep\", \"ollama\", \"python\". */\n\tid: string;\n\t/** Human-readable label for the report. */\n\tlabel: string;\n\tkind: DoctorToolKind;\n\tpresent: boolean;\n\t/** Version/path/status summary, present or not. */\n\tdetail?: string;\n\t/** Only set for a \"managed\" tool: whether an install was just attempted. */\n\tinstallAttempted?: boolean;\n\t/** Only set for a \"system\" tool that's missing: exact manual steps, never executed. */\n\tguide?: string[];\n}\n\nexport interface DoctorReport {\n\tchecks: DoctorCheck[];\n}\n\n/** Minimal slice of OllamaRuntime the doctor needs -- lets tests inject a fake without touching the real runtime. */\nexport type DoctorOllamaRuntime = Pick<OllamaRuntime, \"detect\" | \"installGuide\">;\n\nexport interface DoctorDeps {\n\tloadAvailableFffNodePackage: () => unknown | undefined;\n\tensureFffNodePackage: (silent?: boolean) => Promise<unknown | undefined>;\n\tgetLastFffInstallOutcome: () => FffInstallOutcome | undefined;\n\tgetRgPath: () => string | null;\n\tdetectPython: () => SystemToolStatus;\n\t/** Best-effort `<command> --version` probe; undefined if it can't be run. Used only to enrich a status line, never for presence detection. */\n\tprobeVersion: (command: string, versionArgs?: readonly string[]) => string | undefined;\n\tollamaRuntime: DoctorOllamaRuntime;\n}\n\nexport interface RunDoctorOptions {\n\t/**\n\t * Whether the fff-node managed install (if one is attempted) stays quiet.\n\t * Default true, matching runUpdatePreflight's existing background\n\t * behavior. The interactive `doctor` command passes `false` so a\n\t * multi-second install doesn't read as a silent hang.\n\t */\n\tsilent?: boolean;\n}\n\nconst realDoctorDeps: DoctorDeps = {\n\tloadAvailableFffNodePackage,\n\tensureFffNodePackage,\n\tgetLastFffInstallOutcome,\n\tgetRgPath: () => getToolPath(\"rg\"),\n\tdetectPython: () => detectPython(),\n\tprobeVersion,\n\tollamaRuntime: new OllamaRuntime({ agentDir: getAgentDir() }),\n};\n\nconst RIPGREP_GUIDE = [\n\t\"ripgrep (rg) was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):\",\n\t\"  - macOS (Homebrew): brew install ripgrep\",\n\t\"  - Debian/Ubuntu: apt install ripgrep\",\n\t\"  - Arch: pacman -S ripgrep\",\n\t\"  - Or download a release: https://github.com/BurntSushi/ripgrep/releases\",\n];\n\nconst PYTHON_GUIDE = [\n\t\"python3 was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):\",\n\t\"  - macOS (Homebrew): brew install python3\",\n\t\"  - Debian/Ubuntu: apt install python3\",\n\t\"  - Arch: pacman -S python\",\n\t\"  - Or download from https://www.python.org/downloads/\",\n];\n\nfunction describeFffOutcome(outcome: FffInstallOutcome | undefined): string {\n\tswitch (outcome?.status) {\n\t\tcase \"already-available\":\n\t\t\treturn \"already available\";\n\t\tcase \"installed\":\n\t\t\treturn \"installed just now\";\n\t\tcase \"offline\":\n\t\t\treturn \"offline mode enabled, skipped\";\n\t\tcase \"unsupported-platform\":\n\t\t\treturn \"no native build for this platform\";\n\t\tcase \"install-failed\":\n\t\t\treturn `install failed: ${outcome.reason}`;\n\t\tdefault:\n\t\t\treturn \"unavailable\";\n\t}\n}\n\n/** First line only -- a compiled-features/build-flags tail (e.g. rg --version) is noise in a one-line status report. */\nfunction firstLine(text: string | undefined): string | undefined {\n\treturn text?.split(\"\\n\")[0];\n}\n\n/** MANAGED tool: pi owns this install path, so the doctor actually attempts it when missing. */\nasync function checkFffNode(deps: DoctorDeps, silent: boolean): Promise<DoctorCheck> {\n\t// Delegate entirely to ensureFffNodePackage rather than re-deriving \"is it\n\t// already there\" here: that function (and its offline/unsupported-platform/\n\t// cooldown handling, see tools-manager.ts) is the single source of truth for\n\t// whether an install should even be attempted -- the doctor must not\n\t// duplicate or second-guess that logic, only report its outcome honestly.\n\tconst installed = await deps.ensureFffNodePackage(silent);\n\tconst outcome = deps.getLastFffInstallOutcome();\n\treturn {\n\t\tid: \"fff-node\",\n\t\tlabel: \"FFF native search (@ff-labs/fff-node)\",\n\t\tkind: \"managed\",\n\t\tpresent: Boolean(installed),\n\t\tinstallAttempted: outcome !== undefined && outcome.status !== \"already-available\",\n\t\tdetail: describeFffOutcome(outcome),\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor. */\nfunction checkRipgrep(deps: DoctorDeps): DoctorCheck {\n\tconst path = deps.getRgPath();\n\tif (!path) {\n\t\treturn { id: \"ripgrep\", label: \"ripgrep (rg)\", kind: \"system\", present: false, guide: RIPGREP_GUIDE };\n\t}\n\tconst version = firstLine(deps.probeVersion(path));\n\treturn {\n\t\tid: \"ripgrep\",\n\t\tlabel: \"ripgrep (rg)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: version ? `${path} (${version})` : path,\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor (OllamaRuntime.installGuide() is itself already guide-mode-only). */\nasync function checkOllama(deps: DoctorDeps): Promise<DoctorCheck> {\n\tconst status = await deps.ollamaRuntime.detect();\n\tif (!status.binaryPath) {\n\t\treturn {\n\t\t\tid: \"ollama\",\n\t\t\tlabel: \"Ollama (local model runtime)\",\n\t\t\tkind: \"system\",\n\t\t\tpresent: false,\n\t\t\tguide: deps.ollamaRuntime.installGuide(),\n\t\t};\n\t}\n\tconst version = firstLine(deps.probeVersion(status.binaryPath));\n\tconst versionSuffix = version ? `, ${version}` : \"\";\n\tconst activeStore = status.activeStore\n\t\t? `${status.activeStore.path} [${status.activeStore.kind}, ${status.activeStore.modelCount} model(s)]`\n\t\t: `none; pi-owned store ${status.ownedModelsDir} has ${status.ownedStore.modelCount} model(s)`;\n\treturn {\n\t\tid: \"ollama\",\n\t\tlabel: \"Ollama (local model runtime)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: `binary: ${status.binaryPath} [${status.binarySource}]${versionSuffix}; server: ${status.serverUp ? \"up\" : \"down\"} at ${status.serverUrl}; active store: ${activeStore}`,\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor. */\nfunction checkPython(deps: DoctorDeps): DoctorCheck {\n\tconst status = deps.detectPython();\n\tif (!status.present) {\n\t\treturn { id: \"python\", label: \"Python (python3)\", kind: \"system\", present: false, guide: PYTHON_GUIDE };\n\t}\n\tconst detail = status.version ? `${status.command} (${status.version})` : status.command;\n\treturn { id: \"python\", label: \"Python (python3)\", kind: \"system\", present: true, detail };\n}\n\nexport async function runDoctor(\n\tdeps: DoctorDeps = realDoctorDeps,\n\toptions: RunDoctorOptions = {},\n): Promise<DoctorReport> {\n\tconst silent = options.silent ?? true;\n\tconst [fffNode, ollama] = await Promise.all([checkFffNode(deps, silent), checkOllama(deps)]);\n\treturn { checks: [fffNode, checkRipgrep(deps), ollama, checkPython(deps)] };\n}\n\nexport function formatDoctorReport(report: DoctorReport): string {\n\tconst lines: string[] = [];\n\tfor (const check of report.checks) {\n\t\tconst status = check.present ? chalk.green(\"[OK]\") : chalk.yellow(\"[MISSING]\");\n\t\tconst detail = check.detail ? ` -- ${check.detail}` : \"\";\n\t\tlines.push(`${status} ${check.label}${detail}`);\n\t\tif (!check.present && check.guide) {\n\t\t\tfor (const guideLine of check.guide) lines.push(`  ${guideLine}`);\n\t\t}\n\t}\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Best-effort preflight meant to be called right after `pi-adaptative update`\n * succeeds. Must never fail the update itself: any error here is swallowed\n * and reported as a skipped check, not surfaced as an update failure.\n */\nexport async function runUpdatePreflight(): Promise<void> {\n\ttry {\n\t\tconst report = await runDoctor();\n\t\tconsole.log(`\\n${formatDoctorReport(report)}\\n`);\n\t} catch (error) {\n\t\tconsole.log(chalk.dim(`(environment check skipped: ${error instanceof Error ? error.message : String(error)})`));\n\t}\n}\n"]}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"AAEA,OAAO,EAEN,KAAK,iBAAiB,EAKtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAErF;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,WAAW;IAC3B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,qHAAqH;AACrH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,cAAc,CAAC,CAAC;AAEjF,MAAM,WAAW,UAAU;IAC1B,2BAA2B,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IACvD,oBAAoB,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IACzE,wBAAwB,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAC;IAC9D,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC/B,mBAAmB,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrF,8IAA8I;IAC9I,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,GAAG,SAAS,CAAC;IACvF,aAAa,EAAE,mBAAmB,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AA6HD,wBAAsB,SAAS,CAC9B,IAAI,GAAE,UAA2B,EACjC,OAAO,GAAE,gBAAqB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAQvB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAW/D;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,UAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOzF","sourcesContent":["import chalk from \"chalk\";\nimport { getAgentDir } from \"../config.ts\";\nimport {\n\tensureFffNodePackage,\n\ttype FffInstallOutcome,\n\tgetLastFffInstallOutcome,\n\tgetToolPath,\n\tloadAvailableFffNodePackage,\n\tprobeVersion,\n} from \"../utils/tools-manager.ts\";\nimport { OllamaRuntime } from \"./models/local-runtime.ts\";\nimport { ensurePythonRuntime, type PythonRuntimeOutcome } from \"./python-runtime.ts\";\n\n/**\n * Environment doctor: verifies required tooling and installs what it safely\n * can, instead of leaving provisioning entirely to lazy first-use (the exact\n * gap behind \"ran `pi-adaptative update` on another machine and fff-node\n * never got installed\" -- see fff-lazy-install.test.ts/fff-search-tools.test.ts\n * for the underlying lazy-install fix; this module is the proactive half).\n *\n * Two tool kinds, two different postures:\n * - \"managed\": pi owns provisioning and attempts it when absent (fff-node,\n *   plus pinned uv and the Python interpreter resolved through it).\n * - \"system\": pi does not own the install (ripgrep and ollama). GUIDE MODE\n *   only -- exact manual steps are reported, never executed.\n */\n\nexport type DoctorToolKind = \"managed\" | \"system\";\n\nexport interface DoctorCheck {\n\t/** Stable identifier, e.g. \"fff-node\", \"ripgrep\", \"ollama\", \"python\". */\n\tid: string;\n\t/** Human-readable label for the report. */\n\tlabel: string;\n\tkind: DoctorToolKind;\n\tpresent: boolean;\n\t/** Version/path/status summary, present or not. */\n\tdetail?: string;\n\t/** Only set for a \"managed\" tool: whether an install was just attempted. */\n\tinstallAttempted?: boolean;\n\t/** Only set for a \"system\" tool that's missing: exact manual steps, never executed. */\n\tguide?: string[];\n}\n\nexport interface DoctorReport {\n\tchecks: DoctorCheck[];\n}\n\n/** Minimal slice of OllamaRuntime the doctor needs -- lets tests inject a fake without touching the real runtime. */\nexport type DoctorOllamaRuntime = Pick<OllamaRuntime, \"detect\" | \"installGuide\">;\n\nexport interface DoctorDeps {\n\tloadAvailableFffNodePackage: () => unknown | undefined;\n\tensureFffNodePackage: (silent?: boolean) => Promise<unknown | undefined>;\n\tgetLastFffInstallOutcome: () => FffInstallOutcome | undefined;\n\tgetRgPath: () => string | null;\n\tensurePythonRuntime: (options: { silent: boolean }) => Promise<PythonRuntimeOutcome>;\n\t/** Best-effort `<command> --version` probe; undefined if it can't be run. Used only to enrich a status line, never for presence detection. */\n\tprobeVersion: (command: string, versionArgs?: readonly string[]) => string | undefined;\n\tollamaRuntime: DoctorOllamaRuntime;\n}\n\nexport interface RunDoctorOptions {\n\t/**\n\t * Whether the fff-node managed install (if one is attempted) stays quiet.\n\t * Default true, matching runUpdatePreflight's existing background\n\t * behavior. The interactive `doctor` command passes `false` so a\n\t * multi-second install doesn't read as a silent hang.\n\t */\n\tsilent?: boolean;\n}\n\nconst realDoctorDeps: DoctorDeps = {\n\tloadAvailableFffNodePackage,\n\tensureFffNodePackage,\n\tgetLastFffInstallOutcome,\n\tgetRgPath: () => getToolPath(\"rg\"),\n\tensurePythonRuntime,\n\tprobeVersion,\n\tollamaRuntime: new OllamaRuntime({ agentDir: getAgentDir() }),\n};\n\nconst RIPGREP_GUIDE = [\n\t\"ripgrep (rg) was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):\",\n\t\"  - macOS (Homebrew): brew install ripgrep\",\n\t\"  - Debian/Ubuntu: apt install ripgrep\",\n\t\"  - Arch: pacman -S ripgrep\",\n\t\"  - Or download a release: https://github.com/BurntSushi/ripgrep/releases\",\n];\n\nfunction describeFffOutcome(outcome: FffInstallOutcome | undefined): string {\n\tswitch (outcome?.status) {\n\t\tcase \"already-available\":\n\t\t\treturn \"already available\";\n\t\tcase \"installed\":\n\t\t\treturn \"installed just now\";\n\t\tcase \"offline\":\n\t\t\treturn \"offline mode enabled, skipped\";\n\t\tcase \"unsupported-platform\":\n\t\t\treturn \"no native build for this platform\";\n\t\tcase \"install-failed\":\n\t\t\treturn `install failed: ${outcome.reason}`;\n\t\tdefault:\n\t\t\treturn \"unavailable\";\n\t}\n}\n\n/** First line only -- a compiled-features/build-flags tail (e.g. rg --version) is noise in a one-line status report. */\nfunction firstLine(text: string | undefined): string | undefined {\n\treturn text?.split(\"\\n\")[0];\n}\n\n/** MANAGED tool: pi owns this install path, so the doctor actually attempts it when missing. */\nasync function checkFffNode(deps: DoctorDeps, silent: boolean): Promise<DoctorCheck> {\n\t// Delegate entirely to ensureFffNodePackage rather than re-deriving \"is it\n\t// already there\" here: that function (and its offline/unsupported-platform/\n\t// cooldown handling, see tools-manager.ts) is the single source of truth for\n\t// whether an install should even be attempted -- the doctor must not\n\t// duplicate or second-guess that logic, only report its outcome honestly.\n\tconst installed = await deps.ensureFffNodePackage(silent);\n\tconst outcome = deps.getLastFffInstallOutcome();\n\treturn {\n\t\tid: \"fff-node\",\n\t\tlabel: \"FFF native search (@ff-labs/fff-node)\",\n\t\tkind: \"managed\",\n\t\tpresent: Boolean(installed),\n\t\tinstallAttempted: outcome !== undefined && outcome.status !== \"already-available\",\n\t\tdetail: describeFffOutcome(outcome),\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor. */\nfunction checkRipgrep(deps: DoctorDeps): DoctorCheck {\n\tconst path = deps.getRgPath();\n\tif (!path) {\n\t\treturn { id: \"ripgrep\", label: \"ripgrep (rg)\", kind: \"system\", present: false, guide: RIPGREP_GUIDE };\n\t}\n\tconst version = firstLine(deps.probeVersion(path));\n\treturn {\n\t\tid: \"ripgrep\",\n\t\tlabel: \"ripgrep (rg)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: version ? `${path} (${version})` : path,\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor (OllamaRuntime.installGuide() is itself already guide-mode-only). */\nasync function checkOllama(deps: DoctorDeps): Promise<DoctorCheck> {\n\tconst status = await deps.ollamaRuntime.detect();\n\tif (!status.binaryPath) {\n\t\treturn {\n\t\t\tid: \"ollama\",\n\t\t\tlabel: \"Ollama (local model runtime)\",\n\t\t\tkind: \"system\",\n\t\t\tpresent: false,\n\t\t\tguide: deps.ollamaRuntime.installGuide(),\n\t\t};\n\t}\n\tconst version = firstLine(deps.probeVersion(status.binaryPath));\n\tconst versionSuffix = version ? `, ${version}` : \"\";\n\tconst activeStore = status.activeStore\n\t\t? `${status.activeStore.path} [${status.activeStore.kind}, ${status.activeStore.modelCount} model(s)]`\n\t\t: `none; pi-owned store ${status.ownedModelsDir} has ${status.ownedStore.modelCount} model(s)`;\n\treturn {\n\t\tid: \"ollama\",\n\t\tlabel: \"Ollama (local model runtime)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: `binary: ${status.binaryPath} [${status.binarySource}]${versionSuffix}; server: ${status.serverUp ? \"up\" : \"down\"} at ${status.serverUrl}; active store: ${activeStore}`,\n\t};\n}\n\n/** MANAGED tool: uv and Python share one deduplicated runtime manager with bounded provisioning. */\nasync function checkPython(deps: DoctorDeps, silent: boolean): Promise<DoctorCheck> {\n\tconst outcome = await deps.ensurePythonRuntime({ silent });\n\tif (outcome.status !== \"ready\") {\n\t\treturn {\n\t\t\tid: \"python\",\n\t\t\tlabel: \"Python (uv-managed)\",\n\t\t\tkind: \"managed\",\n\t\t\tpresent: false,\n\t\t\tdetail: outcome.reason,\n\t\t};\n\t}\n\treturn {\n\t\tid: \"python\",\n\t\tlabel: \"Python (uv-managed)\",\n\t\tkind: \"managed\",\n\t\tpresent: true,\n\t\tinstallAttempted: outcome.pythonInstalled,\n\t\tdetail: `uv: ${outcome.uvPath}; python: ${outcome.pythonPath}${outcome.pythonInstalled ? \" (installed just now)\" : \"\"}`,\n\t};\n}\n\nexport async function runDoctor(\n\tdeps: DoctorDeps = realDoctorDeps,\n\toptions: RunDoctorOptions = {},\n): Promise<DoctorReport> {\n\tconst silent = options.silent ?? true;\n\tconst [fffNode, ollama, python] = await Promise.all([\n\t\tcheckFffNode(deps, silent),\n\t\tcheckOllama(deps),\n\t\tcheckPython(deps, silent),\n\t]);\n\treturn { checks: [fffNode, checkRipgrep(deps), ollama, python] };\n}\n\nexport function formatDoctorReport(report: DoctorReport): string {\n\tconst lines: string[] = [];\n\tfor (const check of report.checks) {\n\t\tconst status = check.present ? chalk.green(\"[OK]\") : chalk.yellow(\"[MISSING]\");\n\t\tconst detail = check.detail ? ` -- ${check.detail}` : \"\";\n\t\tlines.push(`${status} ${check.label}${detail}`);\n\t\tif (!check.present && check.guide) {\n\t\t\tfor (const guideLine of check.guide) lines.push(`  ${guideLine}`);\n\t\t}\n\t}\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Best-effort preflight meant to be called right after `pi-adaptative update`\n * succeeds. Must never fail the update itself: any error here is swallowed\n * and reported as a skipped check, not surfaced as an update failure.\n */\nexport async function runUpdatePreflight(deps: DoctorDeps = realDoctorDeps): Promise<void> {\n\ttry {\n\t\tconst report = await runDoctor(deps);\n\t\tconsole.log(`\\n${formatDoctorReport(report)}\\n`);\n\t} catch (error) {\n\t\tconsole.log(chalk.dim(`(environment check skipped: ${error instanceof Error ? error.message : String(error)})`));\n\t}\n}\n"]}

package/dist/core/doctor.js

@@ -1,13 +1,14 @@
 import chalk from "chalk";
 import { getAgentDir } from "../config.js";
-import { detectPython, ensureFffNodePackage, getLastFffInstallOutcome, getToolPath, loadAvailableFffNodePackage, probeVersion, } from "../utils/tools-manager.js";
+import { ensureFffNodePackage, getLastFffInstallOutcome, getToolPath, loadAvailableFffNodePackage, probeVersion, } from "../utils/tools-manager.js";
 import { OllamaRuntime } from "./models/local-runtime.js";
+import { ensurePythonRuntime } from "./python-runtime.js";
 const realDoctorDeps = {
     loadAvailableFffNodePackage,
     ensureFffNodePackage,
     getLastFffInstallOutcome,
     getRgPath: () => getToolPath("rg"),
-    detectPython: () => detectPython(),
+    ensurePythonRuntime,
     probeVersion,
     ollamaRuntime: new OllamaRuntime({ agentDir: getAgentDir() }),
 };
@@ -18,13 +19,6 @@ const RIPGREP_GUIDE = [
     "  - Arch: pacman -S ripgrep",
     "  - Or download a release: https://github.com/BurntSushi/ripgrep/releases",
 ];
-const PYTHON_GUIDE = [
-    "python3 was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):",
-    "  - macOS (Homebrew): brew install python3",
-    "  - Debian/Ubuntu: apt install python3",
-    "  - Arch: pacman -S python",
-    "  - Or download from https://www.python.org/downloads/",
-];
 function describeFffOutcome(outcome) {
     switch (outcome?.status) {
         case "already-available":
@@ -103,19 +97,35 @@ async function checkOllama(deps) {
         detail: `binary: ${status.binaryPath} [${status.binarySource}]${versionSuffix}; server: ${status.serverUp ? "up" : "down"} at ${status.serverUrl}; active store: ${activeStore}`,
     };
 }
-/** SYSTEM tool: guide mode only, never installed by the doctor. */
-function checkPython(deps) {
-    const status = deps.detectPython();
-    if (!status.present) {
-        return { id: "python", label: "Python (python3)", kind: "system", present: false, guide: PYTHON_GUIDE };
+/** MANAGED tool: uv and Python share one deduplicated runtime manager with bounded provisioning. */
+async function checkPython(deps, silent) {
+    const outcome = await deps.ensurePythonRuntime({ silent });
+    if (outcome.status !== "ready") {
+        return {
+            id: "python",
+            label: "Python (uv-managed)",
+            kind: "managed",
+            present: false,
+            detail: outcome.reason,
+        };
     }
-    const detail = status.version ? `${status.command} (${status.version})` : status.command;
-    return { id: "python", label: "Python (python3)", kind: "system", present: true, detail };
+    return {
+        id: "python",
+        label: "Python (uv-managed)",
+        kind: "managed",
+        present: true,
+        installAttempted: outcome.pythonInstalled,
+        detail: `uv: ${outcome.uvPath}; python: ${outcome.pythonPath}${outcome.pythonInstalled ? " (installed just now)" : ""}`,
+    };
 }
 export async function runDoctor(deps = realDoctorDeps, options = {}) {
     const silent = options.silent ?? true;
-    const [fffNode, ollama] = await Promise.all([checkFffNode(deps, silent), checkOllama(deps)]);
-    return { checks: [fffNode, checkRipgrep(deps), ollama, checkPython(deps)] };
+    const [fffNode, ollama, python] = await Promise.all([
+        checkFffNode(deps, silent),
+        checkOllama(deps),
+        checkPython(deps, silent),
+    ]);
+    return { checks: [fffNode, checkRipgrep(deps), ollama, python] };
 }
 export function formatDoctorReport(report) {
     const lines = [];
@@ -135,9 +145,9 @@ export function formatDoctorReport(report) {
  * succeeds. Must never fail the update itself: any error here is swallowed
  * and reported as a skipped check, not surfaced as an update failure.
  */
-export async function runUpdatePreflight() {
+export async function runUpdatePreflight(deps = realDoctorDeps) {
     try {
-        const report = await runDoctor();
+        const report = await runDoctor(deps);
         console.log(`\n${formatDoctorReport(report)}\n`);
     }
     catch (error) {

package/dist/core/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["import chalk from \"chalk\";\nimport { getAgentDir } from \"../config.ts\";\nimport {\n\tdetectPython,\n\tensureFffNodePackage,\n\ttype FffInstallOutcome,\n\tgetLastFffInstallOutcome,\n\tgetToolPath,\n\tloadAvailableFffNodePackage,\n\tprobeVersion,\n\ttype SystemToolStatus,\n} from \"../utils/tools-manager.ts\";\nimport { OllamaRuntime } from \"./models/local-runtime.ts\";\n\n/**\n * Environment doctor: verifies required tooling and installs what it safely\n * can, instead of leaving provisioning entirely to lazy first-use (the exact\n * gap behind \"ran `pi-adaptative update` on another machine and fff-node\n * never got installed\" -- see fff-lazy-install.test.ts/fff-search-tools.test.ts\n * for the underlying lazy-install fix; this module is the proactive half).\n *\n * Two tool kinds, two different postures:\n * - \"managed\": pi already owns the install path (fff-node into\n *   ~/.pi/agent/bin via tools-manager.ts's ensureFffNodePackage). The doctor\n *   actually attempts the install when missing.\n * - \"system\": pi does not own the install (ripgrep, ollama, python). GUIDE\n *   MODE only -- exact manual steps are reported, never executed, never\n *   `curl | sh`, never `sudo`. This matches the harness's deliberate\n *   no-silent-installer stance for tooling outside its own managed bin dir.\n */\n\nexport type DoctorToolKind = \"managed\" | \"system\";\n\nexport interface DoctorCheck {\n\t/** Stable identifier, e.g. \"fff-node\", \"ripgrep\", \"ollama\", \"python\". */\n\tid: string;\n\t/** Human-readable label for the report. */\n\tlabel: string;\n\tkind: DoctorToolKind;\n\tpresent: boolean;\n\t/** Version/path/status summary, present or not. */\n\tdetail?: string;\n\t/** Only set for a \"managed\" tool: whether an install was just attempted. */\n\tinstallAttempted?: boolean;\n\t/** Only set for a \"system\" tool that's missing: exact manual steps, never executed. */\n\tguide?: string[];\n}\n\nexport interface DoctorReport {\n\tchecks: DoctorCheck[];\n}\n\n/** Minimal slice of OllamaRuntime the doctor needs -- lets tests inject a fake without touching the real runtime. */\nexport type DoctorOllamaRuntime = Pick<OllamaRuntime, \"detect\" | \"installGuide\">;\n\nexport interface DoctorDeps {\n\tloadAvailableFffNodePackage: () => unknown | undefined;\n\tensureFffNodePackage: (silent?: boolean) => Promise<unknown | undefined>;\n\tgetLastFffInstallOutcome: () => FffInstallOutcome | undefined;\n\tgetRgPath: () => string | null;\n\tdetectPython: () => SystemToolStatus;\n\t/** Best-effort `<command> --version` probe; undefined if it can't be run. Used only to enrich a status line, never for presence detection. */\n\tprobeVersion: (command: string, versionArgs?: readonly string[]) => string | undefined;\n\tollamaRuntime: DoctorOllamaRuntime;\n}\n\nexport interface RunDoctorOptions {\n\t/**\n\t * Whether the fff-node managed install (if one is attempted) stays quiet.\n\t * Default true, matching runUpdatePreflight's existing background\n\t * behavior. The interactive `doctor` command passes `false` so a\n\t * multi-second install doesn't read as a silent hang.\n\t */\n\tsilent?: boolean;\n}\n\nconst realDoctorDeps: DoctorDeps = {\n\tloadAvailableFffNodePackage,\n\tensureFffNodePackage,\n\tgetLastFffInstallOutcome,\n\tgetRgPath: () => getToolPath(\"rg\"),\n\tdetectPython: () => detectPython(),\n\tprobeVersion,\n\tollamaRuntime: new OllamaRuntime({ agentDir: getAgentDir() }),\n};\n\nconst RIPGREP_GUIDE = [\n\t\"ripgrep (rg) was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):\",\n\t\"  - macOS (Homebrew): brew install ripgrep\",\n\t\"  - Debian/Ubuntu: apt install ripgrep\",\n\t\"  - Arch: pacman -S ripgrep\",\n\t\"  - Or download a release: https://github.com/BurntSushi/ripgrep/releases\",\n];\n\nconst PYTHON_GUIDE = [\n\t\"python3 was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):\",\n\t\"  - macOS (Homebrew): brew install python3\",\n\t\"  - Debian/Ubuntu: apt install python3\",\n\t\"  - Arch: pacman -S python\",\n\t\"  - Or download from https://www.python.org/downloads/\",\n];\n\nfunction describeFffOutcome(outcome: FffInstallOutcome | undefined): string {\n\tswitch (outcome?.status) {\n\t\tcase \"already-available\":\n\t\t\treturn \"already available\";\n\t\tcase \"installed\":\n\t\t\treturn \"installed just now\";\n\t\tcase \"offline\":\n\t\t\treturn \"offline mode enabled, skipped\";\n\t\tcase \"unsupported-platform\":\n\t\t\treturn \"no native build for this platform\";\n\t\tcase \"install-failed\":\n\t\t\treturn `install failed: ${outcome.reason}`;\n\t\tdefault:\n\t\t\treturn \"unavailable\";\n\t}\n}\n\n/** First line only -- a compiled-features/build-flags tail (e.g. rg --version) is noise in a one-line status report. */\nfunction firstLine(text: string | undefined): string | undefined {\n\treturn text?.split(\"\\n\")[0];\n}\n\n/** MANAGED tool: pi owns this install path, so the doctor actually attempts it when missing. */\nasync function checkFffNode(deps: DoctorDeps, silent: boolean): Promise<DoctorCheck> {\n\t// Delegate entirely to ensureFffNodePackage rather than re-deriving \"is it\n\t// already there\" here: that function (and its offline/unsupported-platform/\n\t// cooldown handling, see tools-manager.ts) is the single source of truth for\n\t// whether an install should even be attempted -- the doctor must not\n\t// duplicate or second-guess that logic, only report its outcome honestly.\n\tconst installed = await deps.ensureFffNodePackage(silent);\n\tconst outcome = deps.getLastFffInstallOutcome();\n\treturn {\n\t\tid: \"fff-node\",\n\t\tlabel: \"FFF native search (@ff-labs/fff-node)\",\n\t\tkind: \"managed\",\n\t\tpresent: Boolean(installed),\n\t\tinstallAttempted: outcome !== undefined && outcome.status !== \"already-available\",\n\t\tdetail: describeFffOutcome(outcome),\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor. */\nfunction checkRipgrep(deps: DoctorDeps): DoctorCheck {\n\tconst path = deps.getRgPath();\n\tif (!path) {\n\t\treturn { id: \"ripgrep\", label: \"ripgrep (rg)\", kind: \"system\", present: false, guide: RIPGREP_GUIDE };\n\t}\n\tconst version = firstLine(deps.probeVersion(path));\n\treturn {\n\t\tid: \"ripgrep\",\n\t\tlabel: \"ripgrep (rg)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: version ? `${path} (${version})` : path,\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor (OllamaRuntime.installGuide() is itself already guide-mode-only). */\nasync function checkOllama(deps: DoctorDeps): Promise<DoctorCheck> {\n\tconst status = await deps.ollamaRuntime.detect();\n\tif (!status.binaryPath) {\n\t\treturn {\n\t\t\tid: \"ollama\",\n\t\t\tlabel: \"Ollama (local model runtime)\",\n\t\t\tkind: \"system\",\n\t\t\tpresent: false,\n\t\t\tguide: deps.ollamaRuntime.installGuide(),\n\t\t};\n\t}\n\tconst version = firstLine(deps.probeVersion(status.binaryPath));\n\tconst versionSuffix = version ? `, ${version}` : \"\";\n\tconst activeStore = status.activeStore\n\t\t? `${status.activeStore.path} [${status.activeStore.kind}, ${status.activeStore.modelCount} model(s)]`\n\t\t: `none; pi-owned store ${status.ownedModelsDir} has ${status.ownedStore.modelCount} model(s)`;\n\treturn {\n\t\tid: \"ollama\",\n\t\tlabel: \"Ollama (local model runtime)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: `binary: ${status.binaryPath} [${status.binarySource}]${versionSuffix}; server: ${status.serverUp ? \"up\" : \"down\"} at ${status.serverUrl}; active store: ${activeStore}`,\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor. */\nfunction checkPython(deps: DoctorDeps): DoctorCheck {\n\tconst status = deps.detectPython();\n\tif (!status.present) {\n\t\treturn { id: \"python\", label: \"Python (python3)\", kind: \"system\", present: false, guide: PYTHON_GUIDE };\n\t}\n\tconst detail = status.version ? `${status.command} (${status.version})` : status.command;\n\treturn { id: \"python\", label: \"Python (python3)\", kind: \"system\", present: true, detail };\n}\n\nexport async function runDoctor(\n\tdeps: DoctorDeps = realDoctorDeps,\n\toptions: RunDoctorOptions = {},\n): Promise<DoctorReport> {\n\tconst silent = options.silent ?? true;\n\tconst [fffNode, ollama] = await Promise.all([checkFffNode(deps, silent), checkOllama(deps)]);\n\treturn { checks: [fffNode, checkRipgrep(deps), ollama, checkPython(deps)] };\n}\n\nexport function formatDoctorReport(report: DoctorReport): string {\n\tconst lines: string[] = [];\n\tfor (const check of report.checks) {\n\t\tconst status = check.present ? chalk.green(\"[OK]\") : chalk.yellow(\"[MISSING]\");\n\t\tconst detail = check.detail ? ` -- ${check.detail}` : \"\";\n\t\tlines.push(`${status} ${check.label}${detail}`);\n\t\tif (!check.present && check.guide) {\n\t\t\tfor (const guideLine of check.guide) lines.push(`  ${guideLine}`);\n\t\t}\n\t}\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Best-effort preflight meant to be called right after `pi-adaptative update`\n * succeeds. Must never fail the update itself: any error here is swallowed\n * and reported as a skipped check, not surfaced as an update failure.\n */\nexport async function runUpdatePreflight(): Promise<void> {\n\ttry {\n\t\tconst report = await runDoctor();\n\t\tconsole.log(`\\n${formatDoctorReport(report)}\\n`);\n\t} catch (error) {\n\t\tconsole.log(chalk.dim(`(environment check skipped: ${error instanceof Error ? error.message : String(error)})`));\n\t}\n}\n"]}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"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","sourcesContent":["import chalk from \"chalk\";\nimport { getAgentDir } from \"../config.ts\";\nimport {\n\tensureFffNodePackage,\n\ttype FffInstallOutcome,\n\tgetLastFffInstallOutcome,\n\tgetToolPath,\n\tloadAvailableFffNodePackage,\n\tprobeVersion,\n} from \"../utils/tools-manager.ts\";\nimport { OllamaRuntime } from \"./models/local-runtime.ts\";\nimport { ensurePythonRuntime, type PythonRuntimeOutcome } from \"./python-runtime.ts\";\n\n/**\n * Environment doctor: verifies required tooling and installs what it safely\n * can, instead of leaving provisioning entirely to lazy first-use (the exact\n * gap behind \"ran `pi-adaptative update` on another machine and fff-node\n * never got installed\" -- see fff-lazy-install.test.ts/fff-search-tools.test.ts\n * for the underlying lazy-install fix; this module is the proactive half).\n *\n * Two tool kinds, two different postures:\n * - \"managed\": pi owns provisioning and attempts it when absent (fff-node,\n *   plus pinned uv and the Python interpreter resolved through it).\n * - \"system\": pi does not own the install (ripgrep and ollama). GUIDE MODE\n *   only -- exact manual steps are reported, never executed.\n */\n\nexport type DoctorToolKind = \"managed\" | \"system\";\n\nexport interface DoctorCheck {\n\t/** Stable identifier, e.g. \"fff-node\", \"ripgrep\", \"ollama\", \"python\". */\n\tid: string;\n\t/** Human-readable label for the report. */\n\tlabel: string;\n\tkind: DoctorToolKind;\n\tpresent: boolean;\n\t/** Version/path/status summary, present or not. */\n\tdetail?: string;\n\t/** Only set for a \"managed\" tool: whether an install was just attempted. */\n\tinstallAttempted?: boolean;\n\t/** Only set for a \"system\" tool that's missing: exact manual steps, never executed. */\n\tguide?: string[];\n}\n\nexport interface DoctorReport {\n\tchecks: DoctorCheck[];\n}\n\n/** Minimal slice of OllamaRuntime the doctor needs -- lets tests inject a fake without touching the real runtime. */\nexport type DoctorOllamaRuntime = Pick<OllamaRuntime, \"detect\" | \"installGuide\">;\n\nexport interface DoctorDeps {\n\tloadAvailableFffNodePackage: () => unknown | undefined;\n\tensureFffNodePackage: (silent?: boolean) => Promise<unknown | undefined>;\n\tgetLastFffInstallOutcome: () => FffInstallOutcome | undefined;\n\tgetRgPath: () => string | null;\n\tensurePythonRuntime: (options: { silent: boolean }) => Promise<PythonRuntimeOutcome>;\n\t/** Best-effort `<command> --version` probe; undefined if it can't be run. Used only to enrich a status line, never for presence detection. */\n\tprobeVersion: (command: string, versionArgs?: readonly string[]) => string | undefined;\n\tollamaRuntime: DoctorOllamaRuntime;\n}\n\nexport interface RunDoctorOptions {\n\t/**\n\t * Whether the fff-node managed install (if one is attempted) stays quiet.\n\t * Default true, matching runUpdatePreflight's existing background\n\t * behavior. The interactive `doctor` command passes `false` so a\n\t * multi-second install doesn't read as a silent hang.\n\t */\n\tsilent?: boolean;\n}\n\nconst realDoctorDeps: DoctorDeps = {\n\tloadAvailableFffNodePackage,\n\tensureFffNodePackage,\n\tgetLastFffInstallOutcome,\n\tgetRgPath: () => getToolPath(\"rg\"),\n\tensurePythonRuntime,\n\tprobeVersion,\n\tollamaRuntime: new OllamaRuntime({ agentDir: getAgentDir() }),\n};\n\nconst RIPGREP_GUIDE = [\n\t\"ripgrep (rg) was not found. Pi never runs installers itself -- manual steps (user-level, no sudo):\",\n\t\"  - macOS (Homebrew): brew install ripgrep\",\n\t\"  - Debian/Ubuntu: apt install ripgrep\",\n\t\"  - Arch: pacman -S ripgrep\",\n\t\"  - Or download a release: https://github.com/BurntSushi/ripgrep/releases\",\n];\n\nfunction describeFffOutcome(outcome: FffInstallOutcome | undefined): string {\n\tswitch (outcome?.status) {\n\t\tcase \"already-available\":\n\t\t\treturn \"already available\";\n\t\tcase \"installed\":\n\t\t\treturn \"installed just now\";\n\t\tcase \"offline\":\n\t\t\treturn \"offline mode enabled, skipped\";\n\t\tcase \"unsupported-platform\":\n\t\t\treturn \"no native build for this platform\";\n\t\tcase \"install-failed\":\n\t\t\treturn `install failed: ${outcome.reason}`;\n\t\tdefault:\n\t\t\treturn \"unavailable\";\n\t}\n}\n\n/** First line only -- a compiled-features/build-flags tail (e.g. rg --version) is noise in a one-line status report. */\nfunction firstLine(text: string | undefined): string | undefined {\n\treturn text?.split(\"\\n\")[0];\n}\n\n/** MANAGED tool: pi owns this install path, so the doctor actually attempts it when missing. */\nasync function checkFffNode(deps: DoctorDeps, silent: boolean): Promise<DoctorCheck> {\n\t// Delegate entirely to ensureFffNodePackage rather than re-deriving \"is it\n\t// already there\" here: that function (and its offline/unsupported-platform/\n\t// cooldown handling, see tools-manager.ts) is the single source of truth for\n\t// whether an install should even be attempted -- the doctor must not\n\t// duplicate or second-guess that logic, only report its outcome honestly.\n\tconst installed = await deps.ensureFffNodePackage(silent);\n\tconst outcome = deps.getLastFffInstallOutcome();\n\treturn {\n\t\tid: \"fff-node\",\n\t\tlabel: \"FFF native search (@ff-labs/fff-node)\",\n\t\tkind: \"managed\",\n\t\tpresent: Boolean(installed),\n\t\tinstallAttempted: outcome !== undefined && outcome.status !== \"already-available\",\n\t\tdetail: describeFffOutcome(outcome),\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor. */\nfunction checkRipgrep(deps: DoctorDeps): DoctorCheck {\n\tconst path = deps.getRgPath();\n\tif (!path) {\n\t\treturn { id: \"ripgrep\", label: \"ripgrep (rg)\", kind: \"system\", present: false, guide: RIPGREP_GUIDE };\n\t}\n\tconst version = firstLine(deps.probeVersion(path));\n\treturn {\n\t\tid: \"ripgrep\",\n\t\tlabel: \"ripgrep (rg)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: version ? `${path} (${version})` : path,\n\t};\n}\n\n/** SYSTEM tool: guide mode only, never installed by the doctor (OllamaRuntime.installGuide() is itself already guide-mode-only). */\nasync function checkOllama(deps: DoctorDeps): Promise<DoctorCheck> {\n\tconst status = await deps.ollamaRuntime.detect();\n\tif (!status.binaryPath) {\n\t\treturn {\n\t\t\tid: \"ollama\",\n\t\t\tlabel: \"Ollama (local model runtime)\",\n\t\t\tkind: \"system\",\n\t\t\tpresent: false,\n\t\t\tguide: deps.ollamaRuntime.installGuide(),\n\t\t};\n\t}\n\tconst version = firstLine(deps.probeVersion(status.binaryPath));\n\tconst versionSuffix = version ? `, ${version}` : \"\";\n\tconst activeStore = status.activeStore\n\t\t? `${status.activeStore.path} [${status.activeStore.kind}, ${status.activeStore.modelCount} model(s)]`\n\t\t: `none; pi-owned store ${status.ownedModelsDir} has ${status.ownedStore.modelCount} model(s)`;\n\treturn {\n\t\tid: \"ollama\",\n\t\tlabel: \"Ollama (local model runtime)\",\n\t\tkind: \"system\",\n\t\tpresent: true,\n\t\tdetail: `binary: ${status.binaryPath} [${status.binarySource}]${versionSuffix}; server: ${status.serverUp ? \"up\" : \"down\"} at ${status.serverUrl}; active store: ${activeStore}`,\n\t};\n}\n\n/** MANAGED tool: uv and Python share one deduplicated runtime manager with bounded provisioning. */\nasync function checkPython(deps: DoctorDeps, silent: boolean): Promise<DoctorCheck> {\n\tconst outcome = await deps.ensurePythonRuntime({ silent });\n\tif (outcome.status !== \"ready\") {\n\t\treturn {\n\t\t\tid: \"python\",\n\t\t\tlabel: \"Python (uv-managed)\",\n\t\t\tkind: \"managed\",\n\t\t\tpresent: false,\n\t\t\tdetail: outcome.reason,\n\t\t};\n\t}\n\treturn {\n\t\tid: \"python\",\n\t\tlabel: \"Python (uv-managed)\",\n\t\tkind: \"managed\",\n\t\tpresent: true,\n\t\tinstallAttempted: outcome.pythonInstalled,\n\t\tdetail: `uv: ${outcome.uvPath}; python: ${outcome.pythonPath}${outcome.pythonInstalled ? \" (installed just now)\" : \"\"}`,\n\t};\n}\n\nexport async function runDoctor(\n\tdeps: DoctorDeps = realDoctorDeps,\n\toptions: RunDoctorOptions = {},\n): Promise<DoctorReport> {\n\tconst silent = options.silent ?? true;\n\tconst [fffNode, ollama, python] = await Promise.all([\n\t\tcheckFffNode(deps, silent),\n\t\tcheckOllama(deps),\n\t\tcheckPython(deps, silent),\n\t]);\n\treturn { checks: [fffNode, checkRipgrep(deps), ollama, python] };\n}\n\nexport function formatDoctorReport(report: DoctorReport): string {\n\tconst lines: string[] = [];\n\tfor (const check of report.checks) {\n\t\tconst status = check.present ? chalk.green(\"[OK]\") : chalk.yellow(\"[MISSING]\");\n\t\tconst detail = check.detail ? ` -- ${check.detail}` : \"\";\n\t\tlines.push(`${status} ${check.label}${detail}`);\n\t\tif (!check.present && check.guide) {\n\t\t\tfor (const guideLine of check.guide) lines.push(`  ${guideLine}`);\n\t\t}\n\t}\n\treturn lines.join(\"\\n\");\n}\n\n/**\n * Best-effort preflight meant to be called right after `pi-adaptative update`\n * succeeds. Must never fail the update itself: any error here is swallowed\n * and reported as a skipped check, not surfaced as an update failure.\n */\nexport async function runUpdatePreflight(deps: DoctorDeps = realDoctorDeps): Promise<void> {\n\ttry {\n\t\tconst report = await runDoctor(deps);\n\t\tconsole.log(`\\n${formatDoctorReport(report)}\\n`);\n\t} catch (error) {\n\t\tconsole.log(chalk.dim(`(environment check skipped: ${error instanceof Error ? error.message : String(error)})`));\n\t}\n}\n"]}

package/dist/core/exec.d.ts

@@ -11,6 +11,8 @@ export interface ExecOptions {
     timeout?: number;
     /** Working directory */
     cwd?: string;
+    /** Environment for the child process. Defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
     /**
      * Maximum output retained per stream, in UTF-16 code units (~bytes for ASCII).
      * Output is kept as a rolling tail; when exceeded, the oldest output is dropped

package/dist/core/exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;IACzB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,IAAI,MAAM,CAAC;IACf,SAAS,IAAI,OAAO,CAAC;CACrB;AAED,uGAAuG;AACvG,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAyB/E;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAmFrB","sourcesContent":["/**\n * Shared command execution utilities for extensions and custom tools.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { killTree } from \"@caupulican/pi-agent-core/node\";\nimport { waitForChildProcess } from \"../utils/child-process.ts\";\n\n/** Default per-stream retention for command output, in UTF-16 code units (~bytes for ASCII). */\nconst DEFAULT_EXEC_MAX_BUFFER = 16 * 1024 * 1024;\n\n/**\n * Options for executing shell commands.\n */\nexport interface ExecOptions {\n\t/** AbortSignal to cancel the command */\n\tsignal?: AbortSignal;\n\t/** Timeout in milliseconds */\n\ttimeout?: number;\n\t/** Working directory */\n\tcwd?: string;\n\t/**\n\t * Maximum output retained per stream, in UTF-16 code units (~bytes for ASCII).\n\t * Output is kept as a rolling tail; when exceeded, the oldest output is dropped\n\t * and the matching truncation flag is set on the result. Defaults to 16 MiB.\n\t */\n\tmaxBuffer?: number;\n}\n\n/**\n * Result of executing a shell command.\n */\nexport interface ExecResult {\n\tstdout: string;\n\tstderr: string;\n\tcode: number;\n\tkilled: boolean;\n\t/** True when stdout exceeded maxBuffer and only its tail was retained. */\n\tstdoutTruncated: boolean;\n\t/** True when stderr exceeded maxBuffer and only its tail was retained. */\n\tstderrTruncated: boolean;\n\t/** Present when the process failed to spawn (e.g. ENOENT); code is 1 in that case. */\n\terrorMessage?: string;\n}\n\nexport interface RollingOutputBuffer {\n\tpush(chunk: string): void;\n\ttext(): string;\n\ttruncated(): boolean;\n}\n\n/** Bounded child-process output accumulator: keeps a rolling tail of at most maxUnits UTF-16 units. */\nexport function createRollingOutputBuffer(maxUnits: number): RollingOutputBuffer {\n\tconst chunks: string[] = [];\n\tlet units = 0;\n\tlet truncated = false;\n\treturn {\n\t\tpush(chunk: string): void {\n\t\t\tchunks.push(chunk);\n\t\t\tunits += chunk.length;\n\t\t\twhile (units > maxUnits && chunks.length > 1) {\n\t\t\t\tunits -= chunks.shift()?.length ?? 0;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t\tif (units > maxUnits) {\n\t\t\t\tchunks[0] = chunks[0].slice(-maxUnits);\n\t\t\t\tunits = chunks[0].length;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t},\n\t\ttext(): string {\n\t\t\treturn chunks.join(\"\");\n\t\t},\n\t\ttruncated(): boolean {\n\t\t\treturn truncated;\n\t\t},\n\t};\n}\n\n/**\n * Execute a shell command and return stdout/stderr/code.\n * Supports timeout and abort signal. Output retention per stream is bounded\n * (rolling tail, see ExecOptions.maxBuffer) so a chatty child process cannot\n * grow the host heap without bound.\n */\nexport async function execCommand(\n\tcommand: string,\n\targs: string[],\n\tcwd: string,\n\toptions?: ExecOptions,\n): Promise<ExecResult> {\n\treturn new Promise((resolve) => {\n\t\tconst proc = spawn(command, args, {\n\t\t\tcwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t});\n\n\t\tlet spawnError: string | undefined;\n\t\tproc.once(\"error\", (err) => {\n\t\t\tspawnError = err.message;\n\t\t});\n\n\t\tconst maxBuffer =\n\t\t\toptions?.maxBuffer !== undefined && options.maxBuffer > 0 ? options.maxBuffer : DEFAULT_EXEC_MAX_BUFFER;\n\t\tconst stdout = createRollingOutputBuffer(maxBuffer);\n\t\tconst stderr = createRollingOutputBuffer(maxBuffer);\n\t\tconst stdoutDecoder = new StringDecoder(\"utf8\");\n\t\tconst stderrDecoder = new StringDecoder(\"utf8\");\n\t\tlet killed = false;\n\t\tlet timeoutId: NodeJS.Timeout | undefined;\n\n\t\tconst killProcess = () => {\n\t\t\tif (!killed && proc.pid) {\n\t\t\t\tkilled = true;\n\t\t\t\tvoid killTree(proc.pid, { graceMs: 5000 });\n\t\t\t}\n\t\t};\n\n\t\t// Handle abort signal\n\t\tif (options?.signal) {\n\t\t\tif (options.signal.aborted) {\n\t\t\t\tkillProcess();\n\t\t\t} else {\n\t\t\t\toptions.signal.addEventListener(\"abort\", killProcess, { once: true });\n\t\t\t}\n\t\t}\n\n\t\t// Handle timeout\n\t\tif (options?.timeout && options.timeout > 0) {\n\t\t\ttimeoutId = setTimeout(() => {\n\t\t\t\tkillProcess();\n\t\t\t}, options.timeout);\n\t\t}\n\n\t\tproc.stdout?.on(\"data\", (data: Buffer) => {\n\t\t\tstdout.push(stdoutDecoder.write(data));\n\t\t});\n\n\t\tproc.stderr?.on(\"data\", (data: Buffer) => {\n\t\t\tstderr.push(stderrDecoder.write(data));\n\t\t});\n\n\t\tconst settle = (code: number) => {\n\t\t\tstdout.push(stdoutDecoder.end());\n\t\t\tstderr.push(stderrDecoder.end());\n\t\t\tif (timeoutId) clearTimeout(timeoutId);\n\t\t\tif (options?.signal) {\n\t\t\t\toptions.signal.removeEventListener(\"abort\", killProcess);\n\t\t\t}\n\t\t\tresolve({\n\t\t\t\tstdout: stdout.text(),\n\t\t\t\tstderr: stderr.text(),\n\t\t\t\tcode,\n\t\t\t\tkilled,\n\t\t\t\tstdoutTruncated: stdout.truncated(),\n\t\t\t\tstderrTruncated: stderr.truncated(),\n\t\t\t\t...(spawnError !== undefined ? { errorMessage: spawnError } : {}),\n\t\t\t});\n\t\t};\n\n\t\t// Wait for process termination without hanging on inherited stdio handles\n\t\t// held open by detached descendants.\n\t\twaitForChildProcess(proc)\n\t\t\t.then((code) => settle(code ?? 0))\n\t\t\t.catch((err) => {\n\t\t\t\tif (spawnError === undefined) {\n\t\t\t\t\tspawnError = err instanceof Error ? err.message : String(err);\n\t\t\t\t}\n\t\t\t\tsettle(1);\n\t\t\t});\n\t});\n}\n"]}
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,wCAAwC;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8BAA8B;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;IACzB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,IAAI,MAAM,CAAC;IACf,SAAS,IAAI,OAAO,CAAC;CACrB;AAED,uGAAuG;AACvG,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAyB/E;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAmErB","sourcesContent":["/**\n * Shared command execution utilities for extensions and custom tools.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { waitForChildProcessWithTermination } from \"../utils/child-process.ts\";\n\n/** Default per-stream retention for command output, in UTF-16 code units (~bytes for ASCII). */\nconst DEFAULT_EXEC_MAX_BUFFER = 16 * 1024 * 1024;\nconst DEFAULT_EXEC_TIMEOUT_MS = 10 * 60_000;\nconst EXEC_KILL_GRACE_MS = 5_000;\n\n/**\n * Options for executing shell commands.\n */\nexport interface ExecOptions {\n\t/** AbortSignal to cancel the command */\n\tsignal?: AbortSignal;\n\t/** Timeout in milliseconds */\n\ttimeout?: number;\n\t/** Working directory */\n\tcwd?: string;\n\t/** Environment for the child process. Defaults to process.env. */\n\tenv?: NodeJS.ProcessEnv;\n\t/**\n\t * Maximum output retained per stream, in UTF-16 code units (~bytes for ASCII).\n\t * Output is kept as a rolling tail; when exceeded, the oldest output is dropped\n\t * and the matching truncation flag is set on the result. Defaults to 16 MiB.\n\t */\n\tmaxBuffer?: number;\n}\n\n/**\n * Result of executing a shell command.\n */\nexport interface ExecResult {\n\tstdout: string;\n\tstderr: string;\n\tcode: number;\n\tkilled: boolean;\n\t/** True when stdout exceeded maxBuffer and only its tail was retained. */\n\tstdoutTruncated: boolean;\n\t/** True when stderr exceeded maxBuffer and only its tail was retained. */\n\tstderrTruncated: boolean;\n\t/** Present when the process failed to spawn (e.g. ENOENT); code is 1 in that case. */\n\terrorMessage?: string;\n}\n\nexport interface RollingOutputBuffer {\n\tpush(chunk: string): void;\n\ttext(): string;\n\ttruncated(): boolean;\n}\n\n/** Bounded child-process output accumulator: keeps a rolling tail of at most maxUnits UTF-16 units. */\nexport function createRollingOutputBuffer(maxUnits: number): RollingOutputBuffer {\n\tconst chunks: string[] = [];\n\tlet units = 0;\n\tlet truncated = false;\n\treturn {\n\t\tpush(chunk: string): void {\n\t\t\tchunks.push(chunk);\n\t\t\tunits += chunk.length;\n\t\t\twhile (units > maxUnits && chunks.length > 1) {\n\t\t\t\tunits -= chunks.shift()?.length ?? 0;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t\tif (units > maxUnits) {\n\t\t\t\tchunks[0] = chunks[0].slice(-maxUnits);\n\t\t\t\tunits = chunks[0].length;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t},\n\t\ttext(): string {\n\t\t\treturn chunks.join(\"\");\n\t\t},\n\t\ttruncated(): boolean {\n\t\t\treturn truncated;\n\t\t},\n\t};\n}\n\n/**\n * Execute a shell command and return stdout/stderr/code.\n * Supports timeout and abort signal. Output retention per stream is bounded\n * (rolling tail, see ExecOptions.maxBuffer) so a chatty child process cannot\n * grow the host heap without bound.\n */\nexport async function execCommand(\n\tcommand: string,\n\targs: string[],\n\tcwd: string,\n\toptions?: ExecOptions,\n): Promise<ExecResult> {\n\treturn new Promise((resolve) => {\n\t\tconst proc = spawn(command, args, {\n\t\t\tcwd,\n\t\t\tenv: options?.env,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t});\n\n\t\tlet spawnError: string | undefined;\n\t\tproc.once(\"error\", (err) => {\n\t\t\tspawnError = err.message;\n\t\t});\n\n\t\tconst maxBuffer =\n\t\t\toptions?.maxBuffer !== undefined && options.maxBuffer > 0 ? options.maxBuffer : DEFAULT_EXEC_MAX_BUFFER;\n\t\tconst stdout = createRollingOutputBuffer(maxBuffer);\n\t\tconst stderr = createRollingOutputBuffer(maxBuffer);\n\t\tconst stdoutDecoder = new StringDecoder(\"utf8\");\n\t\tconst stderrDecoder = new StringDecoder(\"utf8\");\n\n\t\tproc.stdout?.on(\"data\", (data: Buffer) => {\n\t\t\tstdout.push(stdoutDecoder.write(data));\n\t\t});\n\n\t\tproc.stderr?.on(\"data\", (data: Buffer) => {\n\t\t\tstderr.push(stderrDecoder.write(data));\n\t\t});\n\n\t\t// Settle from the child's terminal event or a bounded abort/timeout escalation.\n\t\t// This never waits for a second close event after termination has been acknowledged.\n\t\twaitForChildProcessWithTermination(proc, {\n\t\t\tsignal: options?.signal,\n\t\t\ttimeoutMs: options?.timeout && options.timeout > 0 ? options.timeout : DEFAULT_EXEC_TIMEOUT_MS,\n\t\t\tkillGraceMs: EXEC_KILL_GRACE_MS,\n\t\t})\n\t\t\t.then((terminal) => {\n\t\t\t\tstdout.push(stdoutDecoder.end());\n\t\t\t\tstderr.push(stderrDecoder.end());\n\t\t\t\tresolve({\n\t\t\t\t\tstdout: stdout.text(),\n\t\t\t\t\tstderr: stderr.text(),\n\t\t\t\t\tcode: terminal.code ?? 1,\n\t\t\t\t\tkilled: terminal.reason !== \"exited\",\n\t\t\t\t\tstdoutTruncated: stdout.truncated(),\n\t\t\t\t\tstderrTruncated: stderr.truncated(),\n\t\t\t\t\t...(spawnError !== undefined ? { errorMessage: spawnError } : {}),\n\t\t\t\t});\n\t\t\t})\n\t\t\t.catch((err) => {\n\t\t\t\tstdout.push(stdoutDecoder.end());\n\t\t\t\tstderr.push(stderrDecoder.end());\n\t\t\t\tif (spawnError === undefined) {\n\t\t\t\t\tspawnError = err instanceof Error ? err.message : String(err);\n\t\t\t\t}\n\t\t\t\tresolve({\n\t\t\t\t\tstdout: stdout.text(),\n\t\t\t\t\tstderr: stderr.text(),\n\t\t\t\t\tcode: 1,\n\t\t\t\t\tkilled: false,\n\t\t\t\t\tstdoutTruncated: stdout.truncated(),\n\t\t\t\t\tstderrTruncated: stderr.truncated(),\n\t\t\t\t\terrorMessage: spawnError,\n\t\t\t\t});\n\t\t\t});\n\t});\n}\n"]}

package/dist/core/exec.js

@@ -3,10 +3,11 @@
  */
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
-import { killTree } from "@caupulican/pi-agent-core/node";
-import { waitForChildProcess } from "../utils/child-process.js";
+import { waitForChildProcessWithTermination } from "../utils/child-process.js";
 /** Default per-stream retention for command output, in UTF-16 code units (~bytes for ASCII). */
 const DEFAULT_EXEC_MAX_BUFFER = 16 * 1024 * 1024;
+const DEFAULT_EXEC_TIMEOUT_MS = 10 * 60_000;
+const EXEC_KILL_GRACE_MS = 5_000;
 /** Bounded child-process output accumulator: keeps a rolling tail of at most maxUnits UTF-16 units. */
 export function createRollingOutputBuffer(maxUnits) {
     const chunks = [];
@@ -44,6 +45,7 @@ export async function execCommand(command, args, cwd, options) {
     return new Promise((resolve) => {
         const proc = spawn(command, args, {
             cwd,
+            env: options?.env,
             shell: false,
             stdio: ["ignore", "pipe", "pipe"],
             detached: process.platform !== "win32",
@@ -57,62 +59,47 @@ export async function execCommand(command, args, cwd, options) {
         const stderr = createRollingOutputBuffer(maxBuffer);
         const stdoutDecoder = new StringDecoder("utf8");
         const stderrDecoder = new StringDecoder("utf8");
-        let killed = false;
-        let timeoutId;
-        const killProcess = () => {
-            if (!killed && proc.pid) {
-                killed = true;
-                void killTree(proc.pid, { graceMs: 5000 });
-            }
-        };
-        // Handle abort signal
-        if (options?.signal) {
-            if (options.signal.aborted) {
-                killProcess();
-            }
-            else {
-                options.signal.addEventListener("abort", killProcess, { once: true });
-            }
-        }
-        // Handle timeout
-        if (options?.timeout && options.timeout > 0) {
-            timeoutId = setTimeout(() => {
-                killProcess();
-            }, options.timeout);
-        }
         proc.stdout?.on("data", (data) => {
             stdout.push(stdoutDecoder.write(data));
         });
         proc.stderr?.on("data", (data) => {
             stderr.push(stderrDecoder.write(data));
         });
-        const settle = (code) => {
+        // Settle from the child's terminal event or a bounded abort/timeout escalation.
+        // This never waits for a second close event after termination has been acknowledged.
+        waitForChildProcessWithTermination(proc, {
+            signal: options?.signal,
+            timeoutMs: options?.timeout && options.timeout > 0 ? options.timeout : DEFAULT_EXEC_TIMEOUT_MS,
+            killGraceMs: EXEC_KILL_GRACE_MS,
+        })
+            .then((terminal) => {
             stdout.push(stdoutDecoder.end());
             stderr.push(stderrDecoder.end());
-            if (timeoutId)
-                clearTimeout(timeoutId);
-            if (options?.signal) {
-                options.signal.removeEventListener("abort", killProcess);
-            }
             resolve({
                 stdout: stdout.text(),
                 stderr: stderr.text(),
-                code,
-                killed,
+                code: terminal.code ?? 1,
+                killed: terminal.reason !== "exited",
                 stdoutTruncated: stdout.truncated(),
                 stderrTruncated: stderr.truncated(),
                 ...(spawnError !== undefined ? { errorMessage: spawnError } : {}),
             });
-        };
-        // Wait for process termination without hanging on inherited stdio handles
-        // held open by detached descendants.
-        waitForChildProcess(proc)
-            .then((code) => settle(code ?? 0))
+        })
             .catch((err) => {
+            stdout.push(stdoutDecoder.end());
+            stderr.push(stderrDecoder.end());
             if (spawnError === undefined) {
                 spawnError = err instanceof Error ? err.message : String(err);
             }
-            settle(1);
+            resolve({
+                stdout: stdout.text(),
+                stderr: stderr.text(),
+                code: 1,
+                killed: false,
+                stdoutTruncated: stdout.truncated(),
+                stderrTruncated: stderr.truncated(),
+                errorMessage: spawnError,
+            });
         });
     });
 }

package/dist/core/exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared command execution utilities for extensions and custom tools.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { killTree } from \"@caupulican/pi-agent-core/node\";\nimport { waitForChildProcess } from \"../utils/child-process.ts\";\n\n/** Default per-stream retention for command output, in UTF-16 code units (~bytes for ASCII). */\nconst DEFAULT_EXEC_MAX_BUFFER = 16 * 1024 * 1024;\n\n/**\n * Options for executing shell commands.\n */\nexport interface ExecOptions {\n\t/** AbortSignal to cancel the command */\n\tsignal?: AbortSignal;\n\t/** Timeout in milliseconds */\n\ttimeout?: number;\n\t/** Working directory */\n\tcwd?: string;\n\t/**\n\t * Maximum output retained per stream, in UTF-16 code units (~bytes for ASCII).\n\t * Output is kept as a rolling tail; when exceeded, the oldest output is dropped\n\t * and the matching truncation flag is set on the result. Defaults to 16 MiB.\n\t */\n\tmaxBuffer?: number;\n}\n\n/**\n * Result of executing a shell command.\n */\nexport interface ExecResult {\n\tstdout: string;\n\tstderr: string;\n\tcode: number;\n\tkilled: boolean;\n\t/** True when stdout exceeded maxBuffer and only its tail was retained. */\n\tstdoutTruncated: boolean;\n\t/** True when stderr exceeded maxBuffer and only its tail was retained. */\n\tstderrTruncated: boolean;\n\t/** Present when the process failed to spawn (e.g. ENOENT); code is 1 in that case. */\n\terrorMessage?: string;\n}\n\nexport interface RollingOutputBuffer {\n\tpush(chunk: string): void;\n\ttext(): string;\n\ttruncated(): boolean;\n}\n\n/** Bounded child-process output accumulator: keeps a rolling tail of at most maxUnits UTF-16 units. */\nexport function createRollingOutputBuffer(maxUnits: number): RollingOutputBuffer {\n\tconst chunks: string[] = [];\n\tlet units = 0;\n\tlet truncated = false;\n\treturn {\n\t\tpush(chunk: string): void {\n\t\t\tchunks.push(chunk);\n\t\t\tunits += chunk.length;\n\t\t\twhile (units > maxUnits && chunks.length > 1) {\n\t\t\t\tunits -= chunks.shift()?.length ?? 0;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t\tif (units > maxUnits) {\n\t\t\t\tchunks[0] = chunks[0].slice(-maxUnits);\n\t\t\t\tunits = chunks[0].length;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t},\n\t\ttext(): string {\n\t\t\treturn chunks.join(\"\");\n\t\t},\n\t\ttruncated(): boolean {\n\t\t\treturn truncated;\n\t\t},\n\t};\n}\n\n/**\n * Execute a shell command and return stdout/stderr/code.\n * Supports timeout and abort signal. Output retention per stream is bounded\n * (rolling tail, see ExecOptions.maxBuffer) so a chatty child process cannot\n * grow the host heap without bound.\n */\nexport async function execCommand(\n\tcommand: string,\n\targs: string[],\n\tcwd: string,\n\toptions?: ExecOptions,\n): Promise<ExecResult> {\n\treturn new Promise((resolve) => {\n\t\tconst proc = spawn(command, args, {\n\t\t\tcwd,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t});\n\n\t\tlet spawnError: string | undefined;\n\t\tproc.once(\"error\", (err) => {\n\t\t\tspawnError = err.message;\n\t\t});\n\n\t\tconst maxBuffer =\n\t\t\toptions?.maxBuffer !== undefined && options.maxBuffer > 0 ? options.maxBuffer : DEFAULT_EXEC_MAX_BUFFER;\n\t\tconst stdout = createRollingOutputBuffer(maxBuffer);\n\t\tconst stderr = createRollingOutputBuffer(maxBuffer);\n\t\tconst stdoutDecoder = new StringDecoder(\"utf8\");\n\t\tconst stderrDecoder = new StringDecoder(\"utf8\");\n\t\tlet killed = false;\n\t\tlet timeoutId: NodeJS.Timeout | undefined;\n\n\t\tconst killProcess = () => {\n\t\t\tif (!killed && proc.pid) {\n\t\t\t\tkilled = true;\n\t\t\t\tvoid killTree(proc.pid, { graceMs: 5000 });\n\t\t\t}\n\t\t};\n\n\t\t// Handle abort signal\n\t\tif (options?.signal) {\n\t\t\tif (options.signal.aborted) {\n\t\t\t\tkillProcess();\n\t\t\t} else {\n\t\t\t\toptions.signal.addEventListener(\"abort\", killProcess, { once: true });\n\t\t\t}\n\t\t}\n\n\t\t// Handle timeout\n\t\tif (options?.timeout && options.timeout > 0) {\n\t\t\ttimeoutId = setTimeout(() => {\n\t\t\t\tkillProcess();\n\t\t\t}, options.timeout);\n\t\t}\n\n\t\tproc.stdout?.on(\"data\", (data: Buffer) => {\n\t\t\tstdout.push(stdoutDecoder.write(data));\n\t\t});\n\n\t\tproc.stderr?.on(\"data\", (data: Buffer) => {\n\t\t\tstderr.push(stderrDecoder.write(data));\n\t\t});\n\n\t\tconst settle = (code: number) => {\n\t\t\tstdout.push(stdoutDecoder.end());\n\t\t\tstderr.push(stderrDecoder.end());\n\t\t\tif (timeoutId) clearTimeout(timeoutId);\n\t\t\tif (options?.signal) {\n\t\t\t\toptions.signal.removeEventListener(\"abort\", killProcess);\n\t\t\t}\n\t\t\tresolve({\n\t\t\t\tstdout: stdout.text(),\n\t\t\t\tstderr: stderr.text(),\n\t\t\t\tcode,\n\t\t\t\tkilled,\n\t\t\t\tstdoutTruncated: stdout.truncated(),\n\t\t\t\tstderrTruncated: stderr.truncated(),\n\t\t\t\t...(spawnError !== undefined ? { errorMessage: spawnError } : {}),\n\t\t\t});\n\t\t};\n\n\t\t// Wait for process termination without hanging on inherited stdio handles\n\t\t// held open by detached descendants.\n\t\twaitForChildProcess(proc)\n\t\t\t.then((code) => settle(code ?? 0))\n\t\t\t.catch((err) => {\n\t\t\t\tif (spawnError === undefined) {\n\t\t\t\t\tspawnError = err instanceof Error ? err.message : String(err);\n\t\t\t\t}\n\t\t\t\tsettle(1);\n\t\t\t});\n\t});\n}\n"]}
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/core/exec.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared command execution utilities for extensions and custom tools.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport { waitForChildProcessWithTermination } from \"../utils/child-process.ts\";\n\n/** Default per-stream retention for command output, in UTF-16 code units (~bytes for ASCII). */\nconst DEFAULT_EXEC_MAX_BUFFER = 16 * 1024 * 1024;\nconst DEFAULT_EXEC_TIMEOUT_MS = 10 * 60_000;\nconst EXEC_KILL_GRACE_MS = 5_000;\n\n/**\n * Options for executing shell commands.\n */\nexport interface ExecOptions {\n\t/** AbortSignal to cancel the command */\n\tsignal?: AbortSignal;\n\t/** Timeout in milliseconds */\n\ttimeout?: number;\n\t/** Working directory */\n\tcwd?: string;\n\t/** Environment for the child process. Defaults to process.env. */\n\tenv?: NodeJS.ProcessEnv;\n\t/**\n\t * Maximum output retained per stream, in UTF-16 code units (~bytes for ASCII).\n\t * Output is kept as a rolling tail; when exceeded, the oldest output is dropped\n\t * and the matching truncation flag is set on the result. Defaults to 16 MiB.\n\t */\n\tmaxBuffer?: number;\n}\n\n/**\n * Result of executing a shell command.\n */\nexport interface ExecResult {\n\tstdout: string;\n\tstderr: string;\n\tcode: number;\n\tkilled: boolean;\n\t/** True when stdout exceeded maxBuffer and only its tail was retained. */\n\tstdoutTruncated: boolean;\n\t/** True when stderr exceeded maxBuffer and only its tail was retained. */\n\tstderrTruncated: boolean;\n\t/** Present when the process failed to spawn (e.g. ENOENT); code is 1 in that case. */\n\terrorMessage?: string;\n}\n\nexport interface RollingOutputBuffer {\n\tpush(chunk: string): void;\n\ttext(): string;\n\ttruncated(): boolean;\n}\n\n/** Bounded child-process output accumulator: keeps a rolling tail of at most maxUnits UTF-16 units. */\nexport function createRollingOutputBuffer(maxUnits: number): RollingOutputBuffer {\n\tconst chunks: string[] = [];\n\tlet units = 0;\n\tlet truncated = false;\n\treturn {\n\t\tpush(chunk: string): void {\n\t\t\tchunks.push(chunk);\n\t\t\tunits += chunk.length;\n\t\t\twhile (units > maxUnits && chunks.length > 1) {\n\t\t\t\tunits -= chunks.shift()?.length ?? 0;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t\tif (units > maxUnits) {\n\t\t\t\tchunks[0] = chunks[0].slice(-maxUnits);\n\t\t\t\tunits = chunks[0].length;\n\t\t\t\ttruncated = true;\n\t\t\t}\n\t\t},\n\t\ttext(): string {\n\t\t\treturn chunks.join(\"\");\n\t\t},\n\t\ttruncated(): boolean {\n\t\t\treturn truncated;\n\t\t},\n\t};\n}\n\n/**\n * Execute a shell command and return stdout/stderr/code.\n * Supports timeout and abort signal. Output retention per stream is bounded\n * (rolling tail, see ExecOptions.maxBuffer) so a chatty child process cannot\n * grow the host heap without bound.\n */\nexport async function execCommand(\n\tcommand: string,\n\targs: string[],\n\tcwd: string,\n\toptions?: ExecOptions,\n): Promise<ExecResult> {\n\treturn new Promise((resolve) => {\n\t\tconst proc = spawn(command, args, {\n\t\t\tcwd,\n\t\t\tenv: options?.env,\n\t\t\tshell: false,\n\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\tdetached: process.platform !== \"win32\",\n\t\t});\n\n\t\tlet spawnError: string | undefined;\n\t\tproc.once(\"error\", (err) => {\n\t\t\tspawnError = err.message;\n\t\t});\n\n\t\tconst maxBuffer =\n\t\t\toptions?.maxBuffer !== undefined && options.maxBuffer > 0 ? options.maxBuffer : DEFAULT_EXEC_MAX_BUFFER;\n\t\tconst stdout = createRollingOutputBuffer(maxBuffer);\n\t\tconst stderr = createRollingOutputBuffer(maxBuffer);\n\t\tconst stdoutDecoder = new StringDecoder(\"utf8\");\n\t\tconst stderrDecoder = new StringDecoder(\"utf8\");\n\n\t\tproc.stdout?.on(\"data\", (data: Buffer) => {\n\t\t\tstdout.push(stdoutDecoder.write(data));\n\t\t});\n\n\t\tproc.stderr?.on(\"data\", (data: Buffer) => {\n\t\t\tstderr.push(stderrDecoder.write(data));\n\t\t});\n\n\t\t// Settle from the child's terminal event or a bounded abort/timeout escalation.\n\t\t// This never waits for a second close event after termination has been acknowledged.\n\t\twaitForChildProcessWithTermination(proc, {\n\t\t\tsignal: options?.signal,\n\t\t\ttimeoutMs: options?.timeout && options.timeout > 0 ? options.timeout : DEFAULT_EXEC_TIMEOUT_MS,\n\t\t\tkillGraceMs: EXEC_KILL_GRACE_MS,\n\t\t})\n\t\t\t.then((terminal) => {\n\t\t\t\tstdout.push(stdoutDecoder.end());\n\t\t\t\tstderr.push(stderrDecoder.end());\n\t\t\t\tresolve({\n\t\t\t\t\tstdout: stdout.text(),\n\t\t\t\t\tstderr: stderr.text(),\n\t\t\t\t\tcode: terminal.code ?? 1,\n\t\t\t\t\tkilled: terminal.reason !== \"exited\",\n\t\t\t\t\tstdoutTruncated: stdout.truncated(),\n\t\t\t\t\tstderrTruncated: stderr.truncated(),\n\t\t\t\t\t...(spawnError !== undefined ? { errorMessage: spawnError } : {}),\n\t\t\t\t});\n\t\t\t})\n\t\t\t.catch((err) => {\n\t\t\t\tstdout.push(stdoutDecoder.end());\n\t\t\t\tstderr.push(stderrDecoder.end());\n\t\t\t\tif (spawnError === undefined) {\n\t\t\t\t\tspawnError = err instanceof Error ? err.message : String(err);\n\t\t\t\t}\n\t\t\t\tresolve({\n\t\t\t\t\tstdout: stdout.text(),\n\t\t\t\t\tstderr: stderr.text(),\n\t\t\t\t\tcode: 1,\n\t\t\t\t\tkilled: false,\n\t\t\t\t\tstdoutTruncated: stdout.truncated(),\n\t\t\t\t\tstderrTruncated: stderr.truncated(),\n\t\t\t\t\terrorMessage: spawnError,\n\t\t\t\t});\n\t\t\t});\n\t});\n}\n"]}

package/dist/core/extensions/loader.d.ts

@@ -15,9 +15,14 @@ export declare function createExtensionRuntime(): ExtensionRuntime;
  * previous generation's handlers subscribed, pinning the old module graph in memory
  * and double-processing events.
  */
-export declare function disposeExtensionEventSubscriptions(extensions: Extension[]): Promise<void>;
+export declare function disposeExtensionEventSubscriptions(extensions: Extension[], options?: {
+    deactivate?: boolean;
+    timeoutMs?: number;
+}): Promise<void>;
 export declare function loadExtension(extensionPath: string, cwd: string, eventBus: EventBus, runtime: ExtensionRuntime, opts?: {
     fresh?: boolean;
+    factoryTimeoutMs?: number;
+    moduleTimeoutMs?: number;
 }): Promise<{
     extension: Extension | null;
     error: string | null;
@@ -25,7 +30,9 @@ export declare function loadExtension(extensionPath: string, cwd: string, eventB
 /**
  * Create an Extension from an inline factory function.
  */
-export declare function loadExtensionFromFactory(factory: ExtensionFactory, cwd: string, eventBus: EventBus, runtime: ExtensionRuntime, extensionPath?: string): Promise<Extension>;
+export declare function loadExtensionFromFactory(factory: ExtensionFactory, cwd: string, eventBus: EventBus, runtime: ExtensionRuntime, extensionPath?: string, options?: {
+    factoryTimeoutMs?: number;
+}): Promise<Extension>;
 /**
  * Load extensions from paths.
  */