@oh-my-pi/pi-ai 16.2.8 → 16.2.9

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [16.2.9] - 2026-06-30
+
+### Added
+
+- Added `OAuthCallbackFlowOptions.allowPortFallback` to allow disabling random-port fallback, enabling strict port enforcement and early configuration errors for OAuth flows with static redirect URIs.
+
+### Changed
+
+- Improved `OAuthCallbackFlow` port conflict error messages to include the busy port, configured redirect URI, and actionable remediation steps.
+
+### Fixed
+
+- Fixed an issue where malformed tool-call JSON from local Ollama or llama.cpp models was incorrectly retried as generic 500 errors, now surfacing a clear recovery message.
+- Fixed a race condition in OAuth callback flows where abort signals triggered before the callback listener was registered were ignored.
+
 ## [16.2.7] - 2026-06-30
 
 ### Added

package/dist/types/error/flags.d.ts

@@ -23,6 +23,13 @@ export declare const Flag: {
 export type Flag = (typeof Flag)[keyof typeof Flag];
 export declare const STREAM_READ_ERROR_PATTERN: RegExp;
 export declare const TRANSIENT_TRANSPORT_PATTERN: RegExp;
+/**
+ * Local llama.cpp / Ollama deterministic tool-call argument JSON parse failure.
+ * The model emitted invalid JSON in a tool call and the server returned HTTP 500
+ * with this exact text — replaying the same prompt yields the same malformed
+ * output, so callers strip {@link Flag.Transient} when this matches.
+ */
+export declare const LLAMA_CPP_TOOL_CALL_PARSE_PATTERN: RegExp;
 /** Whether an OAuth refresh error message means the grant is definitively dead. */
 export declare function isOAuthExpiry(errorMessage: string): boolean;
 export declare function create(...flags: number[]): number;

package/dist/types/error/format.d.ts

@@ -5,7 +5,7 @@ export interface FormatMessageOptions {
     rawRequestDump?: RawHttpRequestDump;
     /** Captured non-2xx response body, appended to the message when available. */
     capturedErrorResponse?: CapturedHttpErrorResponse;
-    /** Provider id; `"github-copilot"` triggers the copilot message rewrite. */
+    /** Provider id; gates provider-specific user-facing rewrites. */
     provider?: string;
 }
 /**

package/dist/types/registry/oauth/callback-server.d.ts

@@ -9,6 +9,20 @@ export interface OAuthCallbackFlowOptions {
     callbackHostname?: string;
     /** Exact redirect URI advertised to the provider; disables port fallback. */
     redirectUri?: string;
+    /**
+     * Whether the flow may bind to a random port when {@link preferredPort} is
+     * unavailable. Defaults to `true` so historical AI-provider flows (which
+     * pick uncommon ports and tolerate any loopback callback) keep working.
+     *
+     * Set to `false` for providers that validate the redirect URI against a
+     * registered callback — silently advertising a random-port URI would be
+     * rejected by the authorization server, leaving the browser on an opaque
+     * 500 page and the local callback waiting until the 5-minute timeout fires.
+     * With fallback disabled, {@link OAuthCallbackFlow.login} throws a
+     * {@link AIError.ConfigurationError} immediately so the caller can surface
+     * an actionable message before opening the browser.
+     */
+    allowPortFallback?: boolean;
 }
 /**
  * Abstract base class for OAuth flows with local callback servers.
@@ -20,6 +34,7 @@ export declare abstract class OAuthCallbackFlow {
     callbackPath: string;
     callbackHostname: string;
     redirectUri?: string;
+    allowPortFallback: boolean;
     constructor(ctrl: OAuthController, preferredPortOrOptions: number | OAuthCallbackFlowOptions, callbackPath?: string);
     /**
      * Generate provider-specific authorization URL.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "16.2.8",
+	"version": "16.2.9",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,9 +38,9 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "16.2.8",
-		"@oh-my-pi/pi-utils": "16.2.8",
-		"@oh-my-pi/pi-wire": "16.2.8",
+		"@oh-my-pi/pi-catalog": "16.2.9",
+		"@oh-my-pi/pi-utils": "16.2.9",
+		"@oh-my-pi/pi-wire": "16.2.9",
 		"arktype": "^2.2.0",
 		"zod": "^4"
 	},

package/src/error/flags.ts

@@ -94,6 +94,14 @@ const MALFORMED_FUNCTION_CALL_PATTERN = /\bmalformed.?function.?call\b/i;
 const PROVIDER_FINISH_ERROR_PATTERN = /\bProvider (?:returned error finish_reason|finish_reason:\s*error)\b/i;
 const STALE_RESPONSE_ITEM_PATTERNS = [/\bItem with id ['"][^'"]+['"] not found\.?/i, /previous[ _]?response/i] as const;
 const STALE_RESPONSE_ITEM_DETAIL_PATTERN = /not[ _]?found|invalid|expired|stale|zero[ _-]?data[ _-]?retention/i;
+/**
+ * Local llama.cpp / Ollama deterministic tool-call argument JSON parse failure.
+ * The model emitted invalid JSON in a tool call and the server returned HTTP 500
+ * with this exact text — replaying the same prompt yields the same malformed
+ * output, so callers strip {@link Flag.Transient} when this matches.
+ */
+export const LLAMA_CPP_TOOL_CALL_PARSE_PATTERN =
+	/failed to parse tool call arguments as json|\[json\.exception\.parse_error\.101\]/i;
 
 // Copilot routing flap: HTTP 400 `model_not_supported` (structural code on the
 // error, also surfaced in text). Treated as transient — a retry usually lands
@@ -441,7 +449,13 @@ export function classifyMessage(message: {
 	const currentStatus = message.errorStatus ?? statusFromId(existingId);
 	const textId = classifyText(message.errorMessage, currentStatus, message.api);
 
-	const kinds = ((existingId ?? 0) | textId) & KIND_MASK;
+	let kinds = ((existingId ?? 0) | textId) & KIND_MASK;
+	if (message.errorMessage && LLAMA_CPP_TOOL_CALL_PARSE_PATTERN.test(message.errorMessage)) {
+		// Deterministic local-model tool-call JSON parse failure: HTTP 500 is misleading
+		// because the same prompt reproduces the same malformed output, so the agent-level
+		// auto-retry would loop. Strip Transient so the recovery message surfaces immediately.
+		kinds &= ~Flag.Transient;
+	}
 	const id = kinds !== 0 ? create(kinds) : (statusFromId(textId) ?? statusFromId(existingId) ?? currentStatus ?? 0);
 
 	message.errorId = id;

package/src/error/format.ts

@@ -5,6 +5,12 @@ import {
 	rewriteCopilotError,
 } from "../utils/http-inspector";
 import { formatErrorMessageWithRetryAfter } from "../utils/retry-after";
+import { LLAMA_CPP_TOOL_CALL_PARSE_PATTERN } from "./flags";
+
+function rewriteOllamaToolCallJsonError(message: string): string {
+	if (!LLAMA_CPP_TOOL_CALL_PARSE_PATTERN.test(message)) return message;
+	return `Local Ollama model emitted malformed tool-call JSON and llama.cpp rejected it (HTTP 500). This is usually a deterministic model-output failure after context degradation, not a transient server outage; reload the model or reduce context, then retry.\n${message}`;
+}
 
 /** Inputs that steer {@link formatMessage}'s formatter selection. */
 export interface FormatMessageOptions {
@@ -12,7 +18,7 @@ export interface FormatMessageOptions {
 	rawRequestDump?: RawHttpRequestDump;
 	/** Captured non-2xx response body, appended to the message when available. */
 	capturedErrorResponse?: CapturedHttpErrorResponse;
-	/** Provider id; `"github-copilot"` triggers the copilot message rewrite. */
+	/** Provider id; gates provider-specific user-facing rewrites. */
 	provider?: string;
 }
 
@@ -32,5 +38,8 @@ export async function formatMessage(error: unknown, opts: FormatMessageOptions =
 	if (opts.provider === "github-copilot") {
 		message = rewriteCopilotError(message, error, opts.provider);
 	}
+	if (opts.provider === "ollama") {
+		message = rewriteOllamaToolCallJsonError(message);
+	}
 	return message;
 }

package/src/providers/ollama.ts

@@ -323,6 +323,10 @@ function createChatBody(model: Model<"ollama-chat">, context: Context, options:
 	};
 }
 
+function shouldRetryOllamaResponse(response: Response, bodyText: string): boolean {
+	return response.status < 500 || !AIError.LLAMA_CPP_TOOL_CALL_PARSE_PATTERN.test(bodyText);
+}
+
 async function captureHttpErrorResponse(response: Response): Promise<CapturedHttpErrorResponse> {
 	let bodyText: string | undefined;
 	let bodyJson: unknown;
@@ -598,6 +602,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 					body: JSON.stringify(body),
 					signal: watchdog.signal,
 					defaultDelayMs: OLLAMA_RETRY_DELAYS_MS,
+					shouldRetryResponse: shouldRetryOllamaResponse,
 					fetch: options.fetch,
 					timeout: false,
 				});
@@ -747,6 +752,7 @@ export const streamOllama: StreamFunction<"ollama-chat"> = (
 			}
 			const result = await AIError.finalize(error, {
 				api: model.api,
+				provider: model.provider,
 				signal: options.signal,
 				rawRequestDump,
 				capturedErrorResponse,

package/src/registry/oauth/callback-server.ts

@@ -26,6 +26,20 @@ export interface OAuthCallbackFlowOptions {
 	callbackHostname?: string;
 	/** Exact redirect URI advertised to the provider; disables port fallback. */
 	redirectUri?: string;
+	/**
+	 * Whether the flow may bind to a random port when {@link preferredPort} is
+	 * unavailable. Defaults to `true` so historical AI-provider flows (which
+	 * pick uncommon ports and tolerate any loopback callback) keep working.
+	 *
+	 * Set to `false` for providers that validate the redirect URI against a
+	 * registered callback — silently advertising a random-port URI would be
+	 * rejected by the authorization server, leaving the browser on an opaque
+	 * 500 page and the local callback waiting until the 5-minute timeout fires.
+	 * With fallback disabled, {@link OAuthCallbackFlow.login} throws a
+	 * {@link AIError.ConfigurationError} immediately so the caller can surface
+	 * an actionable message before opening the browser.
+	 */
+	allowPortFallback?: boolean;
 }
 
 /**
@@ -37,6 +51,7 @@ export abstract class OAuthCallbackFlow {
 	callbackPath: string;
 	callbackHostname: string;
 	redirectUri?: string;
+	allowPortFallback: boolean;
 	#callbackResolve?: (result: CallbackResult) => void;
 	#callbackReject?: (error: string) => void;
 
@@ -50,6 +65,7 @@ export abstract class OAuthCallbackFlow {
 			this.preferredPort = preferredPortOrOptions;
 			this.callbackPath = callbackPath;
 			this.callbackHostname = DEFAULT_HOSTNAME;
+			this.allowPortFallback = true;
 			return;
 		}
 
@@ -57,6 +73,7 @@ export abstract class OAuthCallbackFlow {
 		this.callbackPath = preferredPortOrOptions.callbackPath ?? CALLBACK_PATH;
 		this.callbackHostname = preferredPortOrOptions.callbackHostname ?? DEFAULT_HOSTNAME;
 		this.redirectUri = preferredPortOrOptions.redirectUri;
+		this.allowPortFallback = preferredPortOrOptions.allowPortFallback ?? true;
 	}
 
 	/**
@@ -87,18 +104,29 @@ export abstract class OAuthCallbackFlow {
 			.join("");
 	}
 
+	#loginCancelledError(): AIError.LoginCancelledError {
+		return new AIError.LoginCancelledError(`OAuth callback cancelled: ${this.ctrl.signal?.reason}`);
+	}
+
+	#throwIfCancelled(): void {
+		if (this.ctrl.signal?.aborted) throw this.#loginCancelledError();
+	}
+
 	/**
 	 * Execute the OAuth login flow.
 	 */
 	async login(): Promise<OAuthCredentials> {
 		const state = this.generateState();
+		this.#throwIfCancelled();
 
 		// Start callback server first to get actual redirect URI
 		const { server, redirectUri } = await this.#startCallbackServer(state);
 
 		try {
+			this.#throwIfCancelled();
 			// Generate auth URL with the ACTUAL redirect URI (may differ from expected if port was busy)
 			const { url: authUrl, instructions } = await this.generateAuthUrl(state, redirectUri);
+			this.#throwIfCancelled();
 
 			// Notify controller that auth is ready
 			this.ctrl.onAuth?.({ url: authUrl, instructions });
@@ -106,6 +134,7 @@ export abstract class OAuthCallbackFlow {
 
 			// Wait for callback or manual input
 			const { code } = await this.#waitForCallback(state);
+			this.#throwIfCancelled();
 
 			this.ctrl.onProgress?.("Exchanging authorization code for tokens...");
 
@@ -126,10 +155,17 @@ export abstract class OAuthCallbackFlow {
 			}
 			const redirectUri = `http://${this.callbackHostname}:${this.preferredPort}${this.callbackPath}`;
 			return { server, redirectUri };
-		} catch {
+		} catch (cause) {
 			if (this.redirectUri) {
 				throw new AIError.ConfigurationError(
-					`OAuth callback port ${this.preferredPort} unavailable; cannot fall back to a random port when oauth.redirectUri is set`,
+					`OAuth callback port ${this.preferredPort} is in use, but oauth.redirectUri (${this.redirectUri}) requires this exact port. Free port ${this.preferredPort} (e.g. stop the process bound to it) and retry, or change oauth.redirectUri to point at an available port.`,
+					{ cause },
+				);
+			}
+			if (!this.allowPortFallback) {
+				throw new AIError.ConfigurationError(
+					`OAuth callback port ${this.preferredPort} is in use. The OAuth provider validates redirect URIs against its registered callback, so falling back to a random port would be rejected. Free port ${this.preferredPort} (e.g. stop the process bound to it) and retry, or set oauth.callbackPort/oauth.redirectUri to a port the provider has registered.`,
+					{ cause },
 				);
 			}
 			const server = this.#createServer(0, expectedState);
@@ -208,17 +244,18 @@ export abstract class OAuthCallbackFlow {
 	#waitForCallback(expectedState: string): Promise<CallbackResult> {
 		const timeoutSignal = AbortSignal.timeout(DEFAULT_TIMEOUT);
 		const signal = this.ctrl.signal ? AbortSignal.any([this.ctrl.signal, timeoutSignal]) : timeoutSignal;
+		if (signal.aborted) return Promise.reject(this.#loginCancelledError());
 
-		const callbackPromise = new Promise<CallbackResult>((resolve, reject) => {
-			this.#callbackResolve = resolve;
-			this.#callbackReject = reject;
+		const callback = Promise.withResolvers<CallbackResult>();
+		this.#callbackResolve = callback.resolve;
+		this.#callbackReject = callback.reject;
 
-			signal.addEventListener("abort", () => {
-				this.#callbackResolve = undefined;
-				this.#callbackReject = undefined;
-				reject(new AIError.LoginCancelledError(`OAuth callback cancelled: ${signal.reason}`));
-			});
+		signal.addEventListener("abort", () => {
+			this.#callbackResolve = undefined;
+			this.#callbackReject = undefined;
+			callback.reject(new AIError.LoginCancelledError(`OAuth callback cancelled: ${signal.reason}`));
 		});
+		const callbackPromise = callback.promise;
 
 		// Manual input race (if supported)
 		if (this.ctrl.onManualCodeInput) {