@gtrabanco/pi-nan-provider 1.2.1 → 1.3.0

package/AGENTS.md

@@ -344,8 +344,26 @@ Since 1.0.0 the package version **aligns its MAJOR.MINOR with the pi release lin
   `src/reasoning-only-stream-guard.ts` (issue #21) keys on that marker;
   earlier comment/message text said "60,000 characters" and was corrected to
   the documented figures.
-- **pi 1.2.0 / pi-ai 1.2.0 compat** (verified 2026-10-14, the current verified
-  baseline): the peer range stays `">=0.99.0 <2"` (1.2.0 is inside it). The pi-ai
+- **pi 1.3.0 / pi-ai 1.3.0 compat** (verified 2026-10-15, the current verified
+  baseline): devDependencies bumped 1.2.0 → 1.3.0; the peer range stays
+  `">=0.99.0 <2"`. The pi-ai 1.3.0 `compat.d.ts` and `api/openai-completions.d.ts`
+  surfaces are byte-identical to 1.2.0; `index.d.ts` only drops the
+  `utils/assistant-message-frame` re-export (unused here), and the
+  `thinkingLevelMap.off` branch in `buildRequest` still fires. **pi-ai 1.3.0 lands
+  the upstream fix for issue #3**: `transformMessages` now DROPS cross-model
+  `thinking` blocks (`if (!isSameModel) return []`) instead of downgrading them to
+  unbounded text — the cross-model-thinking guard is therefore VERSION-GATED
+  (`CROSS_MODEL_GUARD_PI_AI_CEILING = "1.3.0"`; registers only on hosts older than
+  that, unknown version keeps it on) and is DEPRECATED for removal in the next
+  package release once the peer floor reaches `>=1.3.0`. `RETRYABLE_PROVIDER_ERROR_PATTERN`
+  expands with gateway/upstream wording ("service is temporarily unavailable" #10965,
+  upstream wrapper text #10842) and #10926 fixes OpenAI-compatible streams where
+  LiteLLM sends reasoning and content in the same chunk — both relevant to NaN's
+  LiteLLM gateway, both upstream-side. Package tests (319) and typecheck pass against
+  1.3.0; the issue-3 acceptance tests were re-pointed at the new upstream reality
+  (thinking scenario pins pi-ai's drop; the opaque-400 reclassification contract is
+  exercised via oversized user content pi-ai cannot shrink).
+- **pi 1.2.0 / pi-ai 1.2.0 compat** (verified 2026-10-14): the peer range stays `">=0.99.0 <2"` (1.2.0 is inside it). The pi-ai
   1.2.0 index/compat type surface is byte-identical to 1.0.0 (`index.d.ts` diff is
   empty); the only additions are `KnownProvider` gaining `"azure"` (renamed from
   `"azure-openai-responses"` in pi 1.0.3 — not used here), a new

package/README.es.md

@@ -52,6 +52,8 @@ Al cambiar de modelo, pi-ai reenvía el razonamiento del modelo anterior como te
 
 Este paquete **elimina todos los bloques de razonamiento cross-model reenviados**, de modo que cambiar de un modelo de 1M de contexto a uno de 262K (`qwen3.6`) ya no desborda la ventana. Las respuestas y los tool results de los modelos no se tocan — solo se quitan sus trazas internas de razonamiento, así que `qwen3.6` puede seguir respondiendo sobre lo que hizo otro modelo. El razonamiento del mismo modelo no se toca nunca, y el guard solo actúa sobre peticiones dirigidas a los proveedores de este paquete. Pon `NAN_THINKING_GUARD=0` para desactivarlo.
 
+> **pi 1.3.0+: este guard ya no se registra.** pi-ai 1.3.0 elimina el thinking cross-model por sí mismo (el fix upstream ya está publicado), así que el guard solo se activa en pi < 1.3.0 y está **deprecado — se eliminará en la próxima versión del paquete**. Si usas pi < 1.3.0, actualiza pi para mantener la mitigación; en pi ≥ 1.3.0 no hay que hacer nada.
+
 Si una petición sigue desbordando — guard desactivado, inflado que no es un bloque de razonamiento (tool outputs grandes, imágenes) o una ventana de destino más pequeña — NaN responde con el mismo 400 genérico en lugar de nombrar el desbordamiento, y la auto-compactación de pi no lo reconoce, así que la sesión se queda atascada en el techo. Por eso el proveedor **vuelve a comprobar el tamaño de la petición a la salida**: cuando llega ese 400 genérico para una petición estimada por encima de la ventana del modelo, el error se reescribe como un mensaje de context overflow que pi reconoce, de modo que compacta y reintenta en vez de bloquearse. Un 400 genérico en una petición dentro de la ventana no se toca, así que nunca se etiquetan mal errores no relacionados.
 
 ### ⏱️ Streams truncados intermitentes (auto-retry, sin stall silencioso)
@@ -239,6 +241,12 @@ bun run check-nan-mcp-server --json     # JSON para máquinas
 bun run check-nan-mcp-server --issue    # crea/refresca el issue
 ```
 
+Las actualizaciones del SDK de pi (`@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent`)
+también están automatizadas: el workflow semanal `check-pi-sdk-versions` abre el issue
+`sdk-monitor` **y** prepara un PR con el bump de devDependencies (`bun test` +
+`bun run typecheck` + diff de superficie de tipos incluidos) para revisión humana — ver
+`docs/sdk-version-monitoring.md`.
+
 ---
 
 ## 📊 Uso de Cuotas: `/nan-usage`

package/README.md

@@ -52,6 +52,8 @@ When you switch models, pi-ai replays the previous model's reasoning as plain as
 
 This package **drops every replayed cross-model reasoning block**, so switching from a 1M-context model to a 262K one (`qwen3.6`) no longer overflows the window. The models' answers and tool results are untouched — only their internal reasoning traces are removed, so `qwen3.6` can still answer about what another model did. Same-model reasoning is never altered, and the guard only acts on requests targeting this package's providers. Set `NAN_THINKING_GUARD=0` to disable it.
 
+> **pi 1.3.0+: this guard no longer registers.** pi-ai 1.3.0 drops cross-model thinking itself (the upstream fix landed), so the guard only activates on pi < 1.3.0 and is **deprecated — it will be removed in the next package release**. If you run pi < 1.3.0, update pi to keep the mitigation; no action is needed on pi ≥ 1.3.0.
+
 If a request still overflows — the guard is disabled, the inflation is not a reasoning block (large tool outputs, images), or the destination window is simply smaller — NaN answers the same generic 400 instead of naming the overflow, and pi's auto-compaction does not recognize it, so the session wedges at the ceiling. The provider therefore **re-checks the request size on the way out**: when that generic 400 arrives for a request estimated over the model's window, the error is rewritten into a context-overflow message pi recognizes, so it compacts and retries instead of stalling. A generic 400 on a within-window request is left untouched, so unrelated errors are never mislabelled.
 
 ### ⏱️ Intermittent truncated streams (auto-retry, no silent stall)
@@ -236,6 +238,11 @@ bun run check-nan-mcp-server --json     # machine-readable JSON
 bun run check-nan-mcp-server --issue    # create/refresh the issue
 ```
 
+PI SDK updates (`@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent`) are automated
+too: the weekly `check-pi-sdk-versions` workflow files the `sdk-monitor` issue **and**
+prepares a devDependencies-bump PR (`bun test` + `bun run typecheck` + type-surface diff
+included) for human review — see `docs/sdk-version-monitoring.md`.
+
 ---
 
 ## 📊 Quota Usage: `/nan-usage`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gtrabanco/pi-nan-provider",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "NaN Builders (api.nan.builders) model provider for pi - OpenAI-compatible registration with a models.dev-generated fallback, tier-aware live catalog, and an optional community media MCP bridge",
 	"keywords": [
 		"pi",
@@ -46,8 +46,8 @@
 		"@earendil-works/pi-coding-agent": ">=0.99.0 <2"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "1.2.0",
-		"@earendil-works/pi-coding-agent": "1.2.0",
+		"@earendil-works/pi-ai": "1.3.0",
+		"@earendil-works/pi-coding-agent": "1.3.0",
 		"@types/bun": "1.4",
 		"typescript": "7"
 	},

package/scripts/models.generated.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by scripts/generate-models.ts
 // Do not edit manually — run `bun run generate-models` to update.
 //
-// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-16T17:43:45.590Z
+// Source: https://models.dev/api.json (provider "nan"), fetched 2026-10-19T22:52:49.128Z
 // Provenance: every contextWindow/maxTokens/input/cost value traces to
 // models.dev or to the per-entry notes below. Nothing is invented; entries
 // models.dev documents incompletely are omitted and flagged instead.
@@ -459,7 +459,7 @@ export const NAN_GENERATED_MODELS: readonly GeneratedModelEntry[] = [
 export const GENERATED_CATALOG_META = {
 	source: "https://models.dev/api.json",
 	modelsDevProvider: "nan",
-	fetchedAt: "2026-10-16T17:43:45.590Z",
+	fetchedAt: "2026-10-19T22:52:49.128Z",
 	modelCount: 6,
 	models: ["deepseek-v4-flash","gemma4","glm5.3-flash","mimo-v2.6-flash","qwen3.6","qwen3.8-flash"],
 	notes: [

package/scripts/prepare-sdk-update-pr.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Prepare an SDK update PR for the packages monitored by
+ * scripts/check-pi-sdk-versions.mjs: bump their devDependencies in
+ * package.json and emit the branch/PR metadata the
+ * `.github/workflows/check-pi-sdk-versions.yml` workflow needs to open the PR.
+ *
+ * This script ONLY edits package.json. Installing, testing, typechecking, the
+ * type-surface diff, git and `gh pr create` stay in the workflow so a failure
+ * anywhere aborts the PR.
+ *
+ * Usage:
+ *   node scripts/prepare-sdk-update-pr.mjs --body-file /tmp/pr-body.md
+ *
+ * Output (stdout, single JSON line):
+ *   {"updates":false}
+ *   {"updates":true,"branch":"chore/pi-sdk-1.3.0","title":"...","bodyFile":"...",
+ *    "bumps":[{"name":"@earendil-works/pi-ai","from":"1.2.0","to":"1.3.0"}]}
+ *
+ * Exit codes: 0 = nothing to do or prepared; 2 = unexpected failure.
+ */
+
+import https from "node:https";
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const SDK_PACKAGES = ["@earendil-works/pi-ai", "@earendil-works/pi-coding-agent"];
+
+function npmLatest(packageName) {
+	return new Promise((resolve, reject) => {
+		const req = https.get(
+			`https://registry.npmjs.org/${encodeURIComponent(packageName)}`,
+			{ headers: { accept: "application/json" } },
+			(res) => {
+				if (res.statusCode !== 200) {
+					reject(new Error(`npm registry returned ${res.statusCode} for ${packageName}`));
+					return;
+				}
+				let data = "";
+				res.on("data", (chunk) => (data += chunk));
+				res.on("end", () => {
+					const latest = JSON.parse(data)["dist-tags"]?.["latest"];
+					if (!latest) reject(new Error(`No "latest" dist-tag for ${packageName}`));
+					else resolve(latest);
+				});
+			},
+		);
+		req.on("error", reject);
+		req.setTimeout(15_000, () => {
+			req.destroy();
+			reject(new Error(`Timeout fetching ${packageName} from npm`));
+		});
+	});
+}
+
+async function main() {
+	const bodyFileArg = process.argv.indexOf("--body-file");
+	const bodyFile =
+		bodyFileArg !== -1 ? process.argv[bodyFileArg + 1] : "/tmp/sdk-update-pr-body.md";
+
+	const packageUrl = new URL("../package.json", import.meta.url);
+	const raw = readFileSync(packageUrl, "utf-8");
+	const pkg = JSON.parse(raw);
+
+	const bumps = [];
+	for (const name of SDK_PACKAGES) {
+		const from = pkg.devDependencies?.[name];
+		if (!from) throw new Error(`${name} is not a devDependency of this package`);
+		const to = await npmLatest(name);
+		if (to !== from) bumps.push({ name, from, to });
+	}
+
+	if (bumps.length === 0) {
+		console.log(JSON.stringify({ updates: false }));
+		return;
+	}
+
+	// Bump via exact-string replacement so the rest of package.json (ordering,
+	// indentation, other fields) is untouched.
+	let updated = raw;
+	for (const bump of bumps) {
+		const needle = `"${bump.name}": "${bump.from}"`;
+		if (!updated.includes(needle)) {
+			throw new Error(`Could not locate ${needle} in package.json to bump it`);
+		}
+		updated = updated.replace(needle, `"${bump.name}": "${bump.to}"`);
+	}
+	writeFileSync(packageUrl, updated);
+
+	const versionTag = bumps.map((b) => b.to).join("-");
+	const branch = `chore/pi-sdk-${versionTag}`;
+	const title = `chore: bump PI SDK to ${bumps.map((b) => `${b.name.split("/")[1]} ${b.to}`).join(" / ")}`;
+	const peer = pkg.peerDependencies ?? {};
+
+	const body = `## PI SDK update (automated)
+
+Prepared from the weekly \`check-pi-sdk-versions\` run. Resolves the \`sdk-monitor\` issue
+for this cycle. **A human must review the upstream changelog before merging** — a minor
+pi release can change provider-relevant behavior (see \`AGENTS.md\` "Verified API facts").
+
+### Version bumps
+
+| Package | From | To | Peer range |
+| --- | --- | --- | --- |
+${bumps.map((b) => `| \`${b.name}\` | ${b.from} | **${b.to}** | \`${peer[b.name] ?? "n/a"}\` |`).join("\n")}
+
+### Review checklist
+
+- [ ] Upstream release notes reviewed (https://pi.dev/changelog)
+- [ ] \`bun test\` + \`bun run typecheck\` green (executed by CI before this PR was opened)
+- [ ] Type-surface diff (below) contains no removals this package uses
+- [ ] Version policy applied: package MAJOR.MINOR realigns with the pi release line
+      (\`package.json\` version bump included in this PR when the pi MINOR moved)
+
+The results of the two sections below were produced by CI while preparing this PR.
+
+## Verification
+
+<!-- VERIFICATION -->
+
+## Type-surface diff (previous → new)
+
+<details><summary>Click to expand</summary>
+
+<!-- SURFACE_DIFF -->
+
+</details>
+`;
+
+	writeFileSync(bodyFile, body);
+	console.log(
+		JSON.stringify({
+			updates: true,
+			branch,
+			title,
+			bodyFile,
+			bumps,
+		}),
+	);
+}
+
+main().catch((err) => {
+	console.error("Fatal:", err.message);
+	process.exit(2);
+});

package/src/cross-model-thinking-guard.ts

@@ -27,14 +27,53 @@
  * provider stream). It therefore sees the original `thinking` blocks and can
  * remove them before they become text.
  *
- * This is a bounded mitigation, not the fix: the unbounded conversion (and pi
- * not re-checking the context size on a model switch) belongs upstream. See
- * https://github.com/gtrabanco/pi-nan-provider/issues/3.
+ * UPSTREAM UPDATE (pi-ai 1.3.0, verified 2026-10-15): `transformMessages` now
+ * drops cross-model `thinking` blocks itself (`if (!isSameModel) return []`),
+ * which is the upstream fix this guard was mitigating. The guard is therefore
+ * GATED BY VERSION: it only registers when the host's pi-ai is older than
+ * {@link CROSS_MODEL_GUARD_PI_AI_CEILING} (1.3.0). An unknown host version
+ * keeps the guard on — the conservative default, since the guard is harmless
+ * where pi-ai already drops the blocks and essential where it still replays
+ * them.
+ *
+ * DEPRECATED — REMOVE THIS MODULE when the peer range floor rises to
+ * `>=1.3.0`: at that point every supported pi ships the upstream drop and this
+ * file (plus the `NAN_THINKING_GUARD` opt-out) is dead code. Users on
+ * pi < 1.3.0 should update pi to keep getting the mitigation for free.
  */
 
+import { parsePiAiVersion } from "./pi-ai-version.ts";
+
 /** Env var that opts out of the guard (`0`, `false`, `no` or `off`). Default: enabled. */
 export const NAN_THINKING_GUARD_ENV = "NAN_THINKING_GUARD";
 
+/**
+ * Exclusive pi-ai version ceiling for this guard: it registers only while the
+ * host's pi-ai is OLDER than this version. pi-ai 1.3.0 drops cross-model
+ * thinking in `transformMessages` (upstream fix for issue #3), so from 1.3.0
+ * on the guard is redundant. Remove this constant together with the module
+ * once the peer range floor reaches this version.
+ */
+export const CROSS_MODEL_GUARD_PI_AI_CEILING = "1.3.0";
+
+/**
+ * Whether the guard still applies to a host running the given pi-ai version.
+ * `undefined`/`null` (unknown host version) and unparseable versions return
+ * `true` — the conservative older-pi default. `false` means the host's pi-ai
+ * already drops cross-model thinking itself and the guard must not register.
+ */
+export function crossModelThinkingGuardCovers(piAiVersion: string | null | undefined): boolean {
+	if (piAiVersion === null || piAiVersion === undefined) return true;
+	const parsed = parsePiAiVersion(piAiVersion);
+	if (!parsed) return true;
+	const ceiling = parsePiAiVersion(CROSS_MODEL_GUARD_PI_AI_CEILING);
+	if (!ceiling) return true;
+	return (
+		parsed.major < ceiling.major ||
+		(parsed.major === ceiling.major && parsed.minor < ceiling.minor)
+	);
+}
+
 export interface CrossModelThinkingGuardOptions {
 	/** Provider ids this guard applies to (the caller's registered providers). */
 	providerIds: ReadonlySet<string>;

package/src/index.ts

@@ -30,9 +30,11 @@ import type { Provider } from "@earendil-works/pi-ai";
 import { registerNanMcpCommand } from "./commands.ts";
 import { registerNanUsageCommand } from "./usage.ts";
 import {
+	crossModelThinkingGuardCovers,
 	crossModelThinkingGuardEnabled,
 	stripCrossModelThinking,
 } from "./cross-model-thinking-guard.ts";
+import { resolvePiAiVersion } from "./pi-ai-version.ts";
 import { baselineModels } from "./fetch-models.ts";
 import { createNanCompatibleProvider, type OpenAICompatibleProviderConfig } from "./provider-factory.ts";
 import { PROVIDERS } from "./providers.ts";
@@ -146,21 +148,34 @@ async function registerMcpServersNative(pi: ExtensionAPI): Promise<void> {
 /**
  * Drop the reasoning pi-ai replays across a model switch.
  *
- * pi-ai's `transformMessages` downgrades a previous model's `thinking` blocks
- * to plain text with no size bound (verified on 0.87.1), and nothing
- * bounds the sum across messages — measured at 30–60% of the whole context on
- * real sessions. Switching from a 1M-context model to a 262K one (`qwen3.6`)
- * then overflows the window, and NaN's gateway answers a generic
+ * On pi-ai < 1.3.0, `transformMessages` downgrades a previous model's
+ * `thinking` blocks to plain text with no size bound (verified on 0.87.1), and
+ * nothing bounds the sum across messages — measured at 30–60% of the whole
+ * context on real sessions. Switching from a 1M-context model to a 262K one
+ * (`qwen3.6`) then overflows the window, and NaN's gateway answers a generic
  * `400 Invalid request. Check your request parameters.` This hook runs before
  * pi-ai converts the blocks, so removing the cross-model reasoning here keeps
  * the replayed context small. Answers and tool results are untouched. See
  * src/cross-model-thinking-guard.ts.
  *
+ * VERSION-GATED: pi-ai 1.3.0 drops cross-model thinking itself (upstream fix
+ * for issue #3), so the guard only registers when the host's resolved pi-ai is
+ * older than 1.3.0; an undeterminable host version keeps it on (conservative
+ * older-pi default). DEPRECATED — remove this whole guard once the peer range
+ * floor rises to `>=1.3.0`; users on pi < 1.3.0 should update pi.
+ *
  * Scope: only requests targeting this package's providers are touched, and
  * only messages from a DIFFERENT model — same-model reasoning is never removed.
  */
-export function registerCrossModelThinkingGuard(pi: ExtensionAPI): void {
+export function registerCrossModelThinkingGuard(
+	pi: ExtensionAPI,
+	options: { piAiVersion?: string | null } = {},
+): void {
 	if (typeof pi.on !== "function") return; // old pi without the context hook
+	// `null` forces the unknown-version path (guard on); omitted resolves the
+	// host's pi-ai version at runtime; a string pins the version (tests).
+	const piAiVersion = options.piAiVersion !== undefined ? options.piAiVersion : resolvePiAiVersion();
+	if (!crossModelThinkingGuardCovers(piAiVersion)) return;
 	const providerIds = new Set(PROVIDERS.map((provider) => provider.id));
 	pi.on("context", (event, ctx) => {
 		if (!crossModelThinkingGuardEnabled()) return;

package/src/pi-ai-version.ts

@@ -0,0 +1,92 @@
+/**
+ * Runtime pi-ai version detection.
+ *
+ * Resolves the `@earendil-works/pi-ai` package instance the HOST loaded — the
+ * same host-anchored strategy `src/pi-ai-loader.ts` uses, because an
+ * extension-relative resolve can return a stale copy from the extension's own
+ * npm tree (issue #8) — and reads that copy's package.json version. The result
+ * feeds version-gated behavior, currently the cross-model thinking guard
+ * (registered only while the host's pi-ai is older than 1.3.0, where pi-ai
+ * still replays cross-model thinking as unbounded text).
+ *
+ * Failure is NOT an error: an unresolvable package or an unreadable version
+ * returns `undefined`, and callers fall back to the conservative older-pi
+ * behavior (the guard stays on — harmless on modern hosts, essential on old
+ * ones). Guarded by `test/pi-ai-version.test.ts`.
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hostAnchorUrl, PI_AI_PACKAGE_SPECIFIER, resolvePiAiSpecifier } from "./pi-ai-loader.ts";
+
+/** A parsed semver triple (`1.3.0-beta.1` → `{ major: 1, minor: 3, patch: 0 }`). */
+export interface PiAiVersion {
+	major: number;
+	minor: number;
+	patch: number;
+}
+
+/** Parse a semver string; prerelease/build suffixes are ignored. */
+export function parsePiAiVersion(version: string): PiAiVersion | undefined {
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
+	if (!match) return undefined;
+	return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+/**
+ * Read the pi-ai version from a resolved specifier (path or `file://` URL) of
+ * any entry file inside the package. Walks up from the entry's directory until
+ * a package.json whose `name` is exactly `@earendil-works/pi-ai` is found —
+ * matching the name prevents picking up an unrelated package.json in a
+ * workspace layout — and returns its `version`. Bounded walk (8 levels);
+ * `undefined` when nothing matches.
+ */
+export function piAiVersionFromResolvedEntry(entry: string): string | undefined {
+	let dir: string;
+	try {
+		dir = dirname(entry.startsWith("file://") ? fileURLToPath(entry) : entry);
+	} catch {
+		return undefined;
+	}
+	for (let depth = 0; depth < 8; depth++) {
+		try {
+			const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as {
+				name?: unknown;
+				version?: unknown;
+			};
+			if (pkg.name === PI_AI_PACKAGE_SPECIFIER && typeof pkg.version === "string") {
+				return pkg.version;
+			}
+		} catch {
+			// No readable package.json at this level — keep walking up.
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
+	return undefined;
+}
+
+/** Cache for {@link resolvePiAiVersion}; resolution runs once per process. */
+let cachedVersion: string | undefined;
+let resolved = false;
+
+/**
+ * Version of the pi-ai instance the host loaded, or `undefined` when it cannot
+ * be determined (unresolvable specifier, unreadable package.json, odd runtime).
+ * Resolution happens once and is cached for the process lifetime.
+ */
+export function resolvePiAiVersion(): string | undefined {
+	if (resolved) return cachedVersion;
+	resolved = true;
+	try {
+		const entry = resolvePiAiSpecifier(PI_AI_PACKAGE_SPECIFIER, {
+			anchorUrl: hostAnchorUrl(process.argv[1]),
+		});
+		cachedVersion = piAiVersionFromResolvedEntry(entry);
+	} catch {
+		cachedVersion = undefined;
+	}
+	return cachedVersion;
+}