pi-claude-agent-sdk 0.8.4 → 0.8.5

package/README.md

@@ -21,7 +21,7 @@ pi install npm:pi-claude-agent-sdk
 
 ## Provider
 
-Use `/model` to select `claude-bridge/claude-fable-5-1`, `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-opus-4-8`, `claude-bridge/claude-opus-4-7`, `claude-bridge/claude-opus-4-6`, `claude-bridge/claude-sonnet-5`, `claude-bridge/claude-sonnet-4-6`, or `claude-bridge/claude-haiku-4-5`. The `fable` shortcut resolves to Fable 5.1. Fable 5.1 needs Claude Code **2.1.251 or newer**; if the SDK's bundled CLI is older, set `provider.pathToClaudeCodeExecutable` to a current `claude` binary.
+Use `/model` to select `claude-bridge/claude-fable-5-1`, `claude-bridge/claude-fable-5`, `claude-bridge/claude-opus-5`, `claude-bridge/claude-opus-4-8`, `claude-bridge/claude-opus-4-7`, `claude-bridge/claude-opus-4-6`, `claude-bridge/claude-sonnet-5`, `claude-bridge/claude-sonnet-4-6`, or `claude-bridge/claude-haiku-4-5`. The `fable` shortcut resolves to Fable 5.1. Fable 5.1 needs Claude Code **2.1.251 or newer** (the SDK's bundled CLI is 2.1.257). If you point `provider.pathToClaudeCodeExecutable` at an older binary, or a later model outruns the bundle, the bridge uses a current `claude` on PATH when it finds one.
 
 Behind the scenes, pi's tools are bridged to Claude Code but it should all work like normal in pi. Bash commands get a 120-second default timeout (matching Claude Code's default) since pi's bash has no timeout by default. Skills in pi are copied over to Claude Code's system prompt so should work as they would with any other pi provider. Steering works mid-turn: a message sent while Claude is running a tool reaches it at that tool boundary, not after the whole turn finishes.
 
@@ -49,7 +49,7 @@ Config: `~/.pi/agent/claude-bridge.json` (global) or the project Pi config direc
 - `longContextExtraUsage` — set to `true` to enable 1M models that cost money through Extra Usage. It enables Sonnet 4.6 with 1M on every plan and Opus 4.6 with 1M on Pro. Not needed for Opus 4.7 or 4.8.
 - `strictMcpConfig` — block MCP servers from `~/.claude.json` / `.mcp.json` (default `true`). Cloud MCP (Gmail/Drive via claude.ai OAuth) is always blocked.
 - `autoMemoryEnabled` — enable Claude Code's auto-memory system (default `false`)
-- `pathToClaudeCodeExecutable` — path to the `claude` binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run. For example, with Nix you can set the binary to e.g. `"/home/you/.nix-profile/bin/claude"`.
+- `pathToClaudeCodeExecutable` — path to the `claude` binary. Useful if your OS/filesystem has the SDK's bundled musl/glibc binaries in a place where they can't run, or to pin a specific CLI. For example, with Nix you can set the binary to e.g. `"/home/you/.nix-profile/bin/claude"`.
 
 **Extension providers and models.json:** pi's `modelOverrides` in `~/.pi/agent/models.json` do not currently apply to extension-registered providers (like claude-bridge). Overriding `contextWindow` or other fields requires editing `src/models.ts` directly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-agent-sdk",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "private": false,
   "description": "Pi extension that uses Claude Code (via Agent SDK) as a model provider.",
   "keywords": [
@@ -40,7 +40,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.141",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.257",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cc-session-io": "^0.4.0",
     "change-case": "^5.4.4"
@@ -50,7 +50,7 @@
     "@earendil-works/pi-coding-agent": ">=0.82.1"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.73.0",
+    "@anthropic-ai/sdk": "^0.93.0",
     "@earendil-works/pi-ai": "^0.83.0",
     "@earendil-works/pi-coding-agent": "^0.83.0",
     "@types/node": "^24.13.2",

package/src/claude-executable.ts

@@ -0,0 +1,149 @@
+// Pick a Claude Code CLI that can actually serve the selected model.
+// The Agent SDK bundles its own binary (`claudeCodeVersion` in its package.json).
+// Some models (Fable 5.1) 400 against an older CLI; when the bundle is below
+// the model's minimum we use a current `claude` on PATH, matching what the
+// README already told people to set via pathToClaudeCodeExecutable.
+
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join } from "node:path";
+import { minClaudeCodeVersionForModel } from "./models.js";
+
+const require = createRequire(import.meta.url);
+
+export type ClaudeVersion = { major: number; minor: number; patch: number };
+
+export type ClaudeExecutableSource = "configured" | "bundled" | "path";
+
+export type ClaudeExecutableResolution = {
+	/** Absolute path for the SDK, or undefined to use the bundled CLI. */
+	path?: string;
+	source: ClaudeExecutableSource;
+	/** Set when no available CLI meets the model's minimum version. */
+	error?: string;
+};
+
+export type ClaudeExecutableDeps = {
+	bundledVersion?: () => ClaudeVersion | undefined;
+	findOnPath?: () => string | undefined;
+	readVersion?: (executable: string) => ClaudeVersion | undefined;
+};
+
+const versionCache = new Map<string, ClaudeVersion | undefined>();
+
+export function parseClaudeVersion(text: string): ClaudeVersion | undefined {
+	const match = text.match(/(\d+)\.(\d+)\.(\d+)/);
+	if (!match) return undefined;
+	return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function formatClaudeVersion(version: ClaudeVersion): string {
+	return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+export function compareClaudeVersion(a: ClaudeVersion, b: ClaudeVersion): number {
+	return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+export function readBundledClaudeCodeVersion(): ClaudeVersion | undefined {
+	try {
+		// The SDK does not export ./package.json; read the file next to its entry.
+		const pkgPath = join(dirname(require.resolve("@anthropic-ai/claude-agent-sdk")), "package.json");
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { claudeCodeVersion?: string };
+		return parseClaudeVersion(pkg.claudeCodeVersion ?? "");
+	} catch {
+		return undefined;
+	}
+}
+
+export function findExecutableOnPath(name: string, env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const pathEnv = env.PATH ?? env.Path;
+	if (!pathEnv) return undefined;
+	const exts = process.platform === "win32"
+		? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+		: [""];
+	const names = process.platform === "win32" && !exts.some((ext) => name.toUpperCase().endsWith(ext.toUpperCase()))
+		? [name, ...exts.map((ext) => name + ext)]
+		: [name];
+	for (const dir of pathEnv.split(delimiter)) {
+		if (!dir) continue;
+		for (const candidateName of names) {
+			const candidate = join(dir, candidateName);
+			try {
+				accessSync(candidate, constants.X_OK);
+				return candidate;
+			} catch {}
+		}
+	}
+	return undefined;
+}
+
+export function readClaudeCliVersion(executable: string): ClaudeVersion | undefined {
+	if (versionCache.has(executable)) return versionCache.get(executable);
+	try {
+		const result = spawnSync(executable, ["--version"], {
+			encoding: "utf8",
+			timeout: 8000,
+			env: process.env,
+			windowsHide: true,
+		});
+		const version = parseClaudeVersion(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
+		versionCache.set(executable, version);
+		return version;
+	} catch {
+		versionCache.set(executable, undefined);
+		return undefined;
+	}
+}
+
+function tooOldError(modelId: string, min: ClaudeVersion, found: string): string {
+	return `${modelId} requires Claude Code ${formatClaudeVersion(min)} or newer (${found}). Install a current claude on PATH, or set provider.pathToClaudeCodeExecutable in ~/.pi/agent/claude-bridge.json.`;
+}
+
+export function resolveClaudeCodeExecutable(
+	modelId: string,
+	configured?: string,
+	deps: ClaudeExecutableDeps = {},
+): ClaudeExecutableResolution {
+	const bundledVersion = deps.bundledVersion ?? readBundledClaudeCodeVersion;
+	const findOnPath = deps.findOnPath ?? (() => findExecutableOnPath("claude"));
+	const readVersion = deps.readVersion ?? readClaudeCliVersion;
+	const minText = minClaudeCodeVersionForModel(modelId);
+	const min = minText ? parseClaudeVersion(minText) : undefined;
+
+	if (configured) {
+		if (min) {
+			const version = readVersion(configured);
+			if (version && compareClaudeVersion(version, min) < 0) {
+				return {
+					source: "configured",
+					error: tooOldError(modelId, min, `provider.pathToClaudeCodeExecutable is ${formatClaudeVersion(version)} at ${configured}`),
+				};
+			}
+		}
+		return { path: configured, source: "configured" };
+	}
+
+	if (!min) return { source: "bundled" };
+
+	const bundled = bundledVersion();
+	if (bundled && compareClaudeVersion(bundled, min) >= 0) {
+		return { source: "bundled" };
+	}
+
+	const pathClaude = findOnPath();
+	if (pathClaude) {
+		const version = readVersion(pathClaude);
+		if (version && compareClaudeVersion(version, min) >= 0) {
+			return { path: pathClaude, source: "path" };
+		}
+	}
+
+	if (bundled) {
+		return { source: "bundled", error: tooOldError(modelId, min, `bundled CLI is ${formatClaudeVersion(bundled)}`) };
+	}
+
+	// Bundle version unknown and PATH missing/unreadable: let the SDK try.
+	return { source: "bundled" };
+}

package/src/index.ts

@@ -24,6 +24,7 @@ import {
 import { collectCarriedAttachments, placeCarriedAttachments, type CarriedAttachment } from "./attachments.js";
 import { createToolServer } from "./mcp-server.js";
 import { CC_CHILD_ENV, resolveClaudeChildEnv, type AnthropicAuthRegistry } from "./child-env.js";
+import { resolveClaudeCodeExecutable } from "./claude-executable.js";
 
 // Compat (#2): use factory if available (pi-ai ≥0.66), else fall back to constructor (gsd-pi etc.)
 const _piAi = piAi as any;
@@ -87,7 +88,7 @@ function debug(...args: unknown[]) {
 // Per-query CLI debug capture. When CLAUDE_BRIDGE_DEBUG=1, ask the Claude Code
 // CLI subprocess to write its own debug log to a file we choose, and also
 // forward its stderr into our debug stream. Drops straight into the real SDK's
-// Options — see @anthropic-ai/claude-agent-sdk sdk.d.ts:1245 (debug, debugFile,
+// Options — see @anthropic-ai/claude-agent-sdk sdk.d.ts:2091 (debug, debugFile,
 // stderr). Without this, CC's internal view of the world is invisible to us
 // and "No conversation found" / empty-error reports are unactionable.
 let nextCliDebugSeq = 1;
@@ -430,7 +431,9 @@ async function runIsolatedSummary(
 		const promptText = extractIsolatedSummaryPrompt(context.messages);
 		const cwd = (options as { cwd?: string } | undefined)?.cwd ?? process.cwd();
 		const compactProviderSettings = loadConfig(cwd).provider;
-		const claudeExecutable = compactProviderSettings?.pathToClaudeCodeExecutable;
+		const claudeExecutableResolution = resolveClaudeCodeExecutable(model.id, compactProviderSettings?.pathToClaudeCodeExecutable);
+		if (claudeExecutableResolution.error) throw new Error(claudeExecutableResolution.error);
+		const claudeExecutable = claudeExecutableResolution.path;
 		const cliModel = claudeCodeModelId(model, longContextSettings);
 		debug(`compact summary: spawn model=${cliModel} registeredModel=${model.id} promptLen=${promptText.length}`);
 		const childEnv = await resolveClaudeChildEnv(piModelRegistry);
@@ -1492,6 +1495,19 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	const queryCtx = isReentrant ? new QueryContext() : ctx();
 	debug(`provider: fresh query setup, isReentrant=${isReentrant}, activeContexts=${activeQueryContexts.size}`);
 
+	// Fail before claiming a stream if this model needs a newer CLI than we have.
+	const claudeExecutableResolution = resolveClaudeCodeExecutable(model.id, providerSettings.pathToClaudeCodeExecutable);
+	if (claudeExecutableResolution.error) {
+		debug(`provider: ${claudeExecutableResolution.error}`);
+		stream.push({ type: "error", reason: "error", error: newAssistantOutput(model, "", "error", claudeExecutableResolution.error) });
+		stream.end();
+		return stream;
+	}
+	const claudeExecutable = claudeExecutableResolution.path;
+	if (claudeExecutableResolution.source === "path") {
+		debug(`provider: using PATH claude ${claudeExecutable} (bundled CLI is too old for ${model.id})`);
+	}
+
 	// Resolved first: an unaccountable system prompt throws, and doing that before
 	// anything is claimed or reset leaves no half-built query behind — in particular
 	// no stream claimed on the shared context that nobody will ever end.
@@ -1561,7 +1577,6 @@ function streamClaudeAgentSdk(model: Model<any>, context: Context, options?: Sim
 	// programmatically and ignore filesystem MCP entries — applied unconditionally because
 	// settingSources is left at CC's default, which loads all sources.
 	const strictMcpConfigEnabled = providerSettings.strictMcpConfig !== false;
-	const claudeExecutable = providerSettings.pathToClaudeCodeExecutable;
 
 	// Prefer the model's own thinkingLevelMap when present (pi-ai 0.72+ ships
 	// per-model overrides — e.g. opus-4-7 wants xhigh→xhigh, not xhigh→max).

package/src/models.ts

@@ -120,6 +120,14 @@ export function thinkingBoundToPrefix(modelId: string): boolean {
 	return modelId === "claude-fable-5-1" || modelId.startsWith("claude-fable-5-1[");
 }
 
+/** Minimum Claude Code CLI version that will accept this model. Undefined
+ *  means the SDK's bundled CLI is fine. Fable 5.1 400s on 2.1.141 with
+ *  "version 2.1.251 or newer is required". */
+export function minClaudeCodeVersionForModel(modelId: string): string | undefined {
+	if (modelId === "claude-fable-5-1" || modelId.startsWith("claude-fable-5-1[")) return "2.1.251";
+	return undefined;
+}
+
 export function resolveModel<T extends { id: string }>(models: T[], input: string): T | undefined {
 	const lower = input.toLowerCase();
 	// Exact match first: otherwise `claude-fable-5` would hit `claude-fable-5-1`