@oh-my-pi/pi-ai 15.11.0 → 15.11.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [15.11.1] - 2026-06-11
+
+### Changed
+
+- Exported `resolveAnthropicMetadataUserId` so non-streaming Anthropic Messages consumers (e.g. the coding-agent web search provider) can produce the same Claude-Code-shaped `metadata.user_id` as the main streaming path.
+
+### Fixed
+
+- Preserved Anthropic `stop_details` on assistant messages so refusal and sensitive classifier stops remain structurally visible to callers. ([#2290](https://github.com/can1357/oh-my-pi/issues/2290))
+- Fixed OpenAI Responses, Azure OpenAI Responses, and OpenAI Completions streams hanging until the 120s idle watchdog errored the turn when a provider delivers the terminal frame but never sends `[DONE]` nor closes the connection. `processResponsesStream` now breaks out of the event loop on `response.completed`/`response.incomplete` (mirroring the Codex websocket/SSE terminal break), and the completions consumer breaks once `finish_reason` plus a usage payload arrived — or, for hosts that never send usage, ends the stream cleanly via a short post-finish grace window (`iterateWithTerminalGrace`) that aborts the transport to release the socket.
+
 ## [15.11.0] - 2026-06-10
 
 ### Added

package/dist/types/providers/anthropic.d.ts

@@ -54,6 +54,18 @@ export declare function wrapFetchForCch(base: FetchImpl): FetchImpl;
 export declare function isClaudeCloakingUserId(userId: string): boolean;
 export declare function generateClaudeCloakingUserId(): string;
 export declare function deriveClaudeDeviceId(installId: string, accountId?: string): string;
+/**
+ * Resolve the `metadata.user_id` field for an Anthropic Messages request.
+ *
+ * For API-key tokens, an explicit caller-supplied `userId` is forwarded
+ * verbatim and `undefined` yields no metadata. For OAuth tokens the value
+ * must match the Claude Code attribution shape (`isClaudeCloakingUserId` or
+ * the `{session_id, account_uuid?, device_id?}` JSON envelope) — anything
+ * else is dropped and a fresh Claude-Code-style JSON id is generated from
+ * `sessionId`/`accountId` so attribution stays consistent across the main
+ * streaming path and provider-specific request builders (e.g. web search).
+ */
+export declare function resolveAnthropicMetadataUserId(userId: unknown, isOAuthToken: boolean, sessionId?: string, accountId?: string): string | undefined;
 export declare const applyClaudeToolPrefix: (name: string) => string;
 export declare const stripClaudeToolPrefix: (name: string) => string;
 export type AnthropicEffort = "low" | "medium" | "high" | "xhigh" | "max";

package/dist/types/providers/mock.d.ts

@@ -41,7 +41,7 @@
  *   // Inspect calls afterwards.
  *   expect(mock.calls).toHaveLength(2);
  */
-import type { Api, Context, Model, SimpleStreamOptions, StopReason, Usage } from "../types";
+import type { Api, Context, Model, SimpleStreamOptions, StopDetails, StopReason, Usage } from "../types";
 import { AssistantMessageEventStream } from "../utils/event-stream";
 /** The API string this provider serves. */
 export declare const MOCK_API: "mock";
@@ -67,6 +67,10 @@ export interface MockResponse {
     content?: ReadonlyArray<MockContent>;
     /** Stop reason. Defaults to `"toolUse"` when content has tool calls, else `"stop"`. */
     stopReason?: StopReason;
+    /** Structured terminal stop classification, e.g. Anthropic refusal metadata. */
+    stopDetails?: StopDetails | null;
+    /** Error text paired with an explicit `"error"` stop reason. */
+    errorMessage?: string;
     /** Usage stats. Missing fields default to 0; missing `cost.total` is recomputed from components. */
     usage?: Partial<Omit<Usage, "cost">> & {
         cost?: Partial<Usage["cost"]>;

package/dist/types/types.d.ts

@@ -7,6 +7,7 @@ import type { ZodType, z } from "zod/v4";
 import type { ApiKey } from "./auth-retry";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
+import type { StopDetails } from "./providers/anthropic-wire";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
 import type { CursorOptions } from "./providers/cursor";
 import type { GoogleOptions } from "./providers/google";
@@ -17,6 +18,7 @@ import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-respo
 import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 import type { OpenAIResponsesOptions } from "./providers/openai-responses";
 import type { AssistantMessageEventStream } from "./utils/event-stream";
+export type { StopDetails } from "./providers/anthropic-wire";
 export type { AssistantMessageEventStream } from "./utils/event-stream";
 /**
  * Ceiling on the output-token count omp requests from any OpenAI-family endpoint
@@ -398,6 +400,7 @@ export interface AssistantMessage {
     upstreamProvider?: string;
     usage: Usage;
     stopReason: StopReason;
+    stopDetails?: StopDetails | null;
     errorMessage?: string;
     /** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
     errorStatus?: number;

package/dist/types/utils/idle-iterator.d.ts

@@ -76,3 +76,38 @@ export interface IdleTimeoutIteratorOptions {
  * before any user-visible content has streamed.
  */
 export declare function iterateWithIdleTimeout<T>(iterable: AsyncIterable<T>, options: IdleTimeoutIteratorOptions): AsyncGenerator<T>;
+export interface TerminalGraceIteratorOptions {
+    /**
+     * Epoch-ms timestamp at which the consumer observed a logically terminal
+     * item (e.g. a chat-completions chunk carrying `finish_reason`), or
+     * `undefined` while the stream is still mid-response. Read before every
+     * pull, so the consumer can flip it between yields.
+     */
+    finishedAtMs: () => number | undefined;
+    /**
+     * Post-terminal budget: how long after `finishedAtMs()` to keep draining
+     * trailing items (e.g. a usage-only chunk or the `[DONE]` sentinel) before
+     * ending the iteration cleanly. The deadline is fixed at
+     * `finishedAtMs() + graceMs`; trailing items do not extend it, so
+     * keepalive-only servers cannot hold the stream open.
+     */
+    graceMs: number;
+    /**
+     * Invoked when the grace window closes with the source still open. Use it
+     * to abort the underlying request: the source generator is typically parked
+     * mid-`next()` (not at a yield), so a queued `.return()` alone cannot reach
+     * the transport until that pending read settles.
+     */
+    onGraceEnd?: () => void;
+}
+/**
+ * Yields items from an async iterable until the consumer marks the stream
+ * logically finished AND the source stays silent past a short grace window.
+ *
+ * Misbehaving OpenAI-compatible servers deliver the terminal chunk but never
+ * send `[DONE]` nor close the connection; without this guard the consumer
+ * hangs on `iterator.next()` until the idle watchdog converts an
+ * already-successful turn into a timeout error. Grace expiry is a clean end
+ * of iteration, never an error.
+ */
+export declare function iterateWithTerminalGrace<T>(iterable: AsyncIterable<T>, options: TerminalGraceIteratorOptions): AsyncGenerator<T>;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.11.0",
+	"version": "15.11.1",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -38,8 +38,8 @@
 	},
 	"dependencies": {
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-catalog": "15.11.0",
-		"@oh-my-pi/pi-utils": "15.11.0",
+		"@oh-my-pi/pi-catalog": "15.11.1",
+		"@oh-my-pi/pi-utils": "15.11.1",
 		"openai": "^6.39.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/providers/anthropic.ts

@@ -677,7 +677,18 @@ function generateClaudeJsonUserId(sessionId?: string, accountId?: string): strin
 	return JSON.stringify(userId);
 }
 
-function resolveAnthropicMetadataUserId(
+/**
+ * Resolve the `metadata.user_id` field for an Anthropic Messages request.
+ *
+ * For API-key tokens, an explicit caller-supplied `userId` is forwarded
+ * verbatim and `undefined` yields no metadata. For OAuth tokens the value
+ * must match the Claude Code attribution shape (`isClaudeCloakingUserId` or
+ * the `{session_id, account_uuid?, device_id?}` JSON envelope) — anything
+ * else is dropped and a fresh Claude-Code-style JSON id is generated from
+ * `sessionId`/`accountId` so attribution stays consistent across the main
+ * streaming path and provider-specific request builders (e.g. web search).
+ */
+export function resolveAnthropicMetadataUserId(
 	userId: unknown,
 	isOAuthToken: boolean,
 	sessionId?: string,
@@ -1992,6 +2003,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 							}
 							if (output.stopReason === "error") {
 								const stopDetails = delta?.stop_details;
+								output.stopDetails = stopDetails ?? (rawStopReason ? { type: rawStopReason } : null);
 								if (stopDetails?.type === "refusal") {
 									const explanation = stopDetails.explanation?.trim();
 									const category = stopDetails.category;
@@ -2151,6 +2163,7 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 					output.content.length = 0;
 					output.responseId = undefined;
 					output.errorMessage = undefined;
+					output.stopDetails = undefined;
 					output.providerPayload = undefined;
 					output.usage = createEmptyUsage(copilotDynamicHeaders?.premiumRequests);
 					output.stopReason = "stop";

package/src/providers/mock.ts

@@ -49,6 +49,7 @@ import type {
 	Context,
 	Model,
 	SimpleStreamOptions,
+	StopDetails,
 	StopReason,
 	TextContent,
 	ThinkingContent,
@@ -81,6 +82,10 @@ export interface MockResponse {
 	content?: ReadonlyArray<MockContent>;
 	/** Stop reason. Defaults to `"toolUse"` when content has tool calls, else `"stop"`. */
 	stopReason?: StopReason;
+	/** Structured terminal stop classification, e.g. Anthropic refusal metadata. */
+	stopDetails?: StopDetails | null;
+	/** Error text paired with an explicit `"error"` stop reason. */
+	errorMessage?: string;
 	/** Usage stats. Missing fields default to 0; missing `cost.total` is recomputed from components. */
 	usage?: Partial<Omit<Usage, "cost">> & { cost?: Partial<Usage["cost"]> };
 	/** Pre-set responseId. */
@@ -389,6 +394,8 @@ async function runMock(
 	const reason: StopReason = response.stopReason ?? (hasToolCall ? ("toolUse" as StopReason) : ("stop" as StopReason));
 
 	partial.stopReason = reason;
+	partial.stopDetails = response.stopDetails;
+	partial.errorMessage = response.errorMessage;
 	partial.usage = mergeUsage(response.usage);
 	partial.duration = Date.now() - startedAt;
 

package/src/providers/openai-completions.ts

@@ -56,6 +56,7 @@ import {
 	getOpenAIStreamFirstEventTimeoutMs,
 	getOpenAIStreamIdleTimeoutMs,
 	iterateWithIdleTimeout,
+	iterateWithTerminalGrace,
 } from "../utils/idle-iterator";
 import { parseStreamingJson, parseStreamingJsonThrottled } from "../utils/json-parse";
 import { notifyProviderResponse } from "../utils/provider-response";
@@ -392,6 +393,13 @@ function getTrailingPartialDeepseekToken(text: string): string {
 }
 const OPENAI_COMPLETIONS_FIRST_EVENT_TIMEOUT_MESSAGE =
 	"OpenAI completions stream timed out while waiting for the first event";
+// How long to keep draining the stream after a `finish_reason` chunk arrived.
+// Compliant hosts follow it (almost) immediately with an optional usage-only
+// chunk and the `[DONE]` sentinel, so the window only ever elapses on hosts
+// that hold the connection open after the response logically completed —
+// without it the turn parks on `iterator.next()` until the idle watchdog
+// converts the already-successful response into a timeout error.
+const OPENAI_COMPLETIONS_POST_FINISH_GRACE_MS = 2_500;
 
 async function* observeDecodedOpenAICompletionChunks(
 	chunks: AsyncIterable<ChatCompletionChunk>,
@@ -748,6 +756,11 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				for (const call of calls) emitHealedToolCall(call);
 			};
 
+			// Terminal-chunk bookkeeping for the post-finish grace window below.
+			// `streamFinishedAt` flips when a chunk carries `finish_reason`;
+			// `sawUsagePayload` flips when any usage payload was parsed.
+			let streamFinishedAt: number | undefined;
+			let sawUsagePayload = false;
 			const timedOpenaiStream = iterateWithIdleTimeout(openaiStream, {
 				idleTimeoutMs,
 				firstItemTimeoutMs: firstEventTimeoutMs,
@@ -761,7 +774,16 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 			const observedOpenaiStream = rawSseObserver
 				? observeDecodedOpenAICompletionChunks(timedOpenaiStream, rawSseObserver)
 				: timedOpenaiStream;
-			for await (const chunk of observedOpenaiStream) {
+			const terminalAwareStream = iterateWithTerminalGrace(observedOpenaiStream, {
+				finishedAtMs: () => streamFinishedAt,
+				graceMs: OPENAI_COMPLETIONS_POST_FINISH_GRACE_MS,
+				// The inner idle-timeout generator is parked mid-`next()` when the
+				// grace window closes, so abort the transport to settle that read
+				// and release the socket immediately (a queued `.return()` alone
+				// would wait on the never-arriving next chunk).
+				onGraceEnd: () => requestAbortController.abort(),
+			});
+			for await (const chunk of terminalAwareStream) {
 				if (!chunk || typeof chunk !== "object") continue;
 
 				// OpenAI documents ChatCompletionChunk.id as the unique chat completion identifier,
@@ -776,15 +798,23 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 
 				if (chunk.usage) {
 					output.usage = parseChunkUsage(chunk.usage, model, premiumRequestsTotal);
+					sawUsagePayload = true;
 				}
 
 				const choice = Array.isArray(chunk.choices) ? chunk.choices[0] : undefined;
-				if (!choice) continue;
+				if (!choice) {
+					// Trailing usage-only chunk (`stream_options.include_usage`) after
+					// `finish_reason`: the response is complete — stop pulling instead
+					// of waiting for `[DONE]`/close from hosts that never send either.
+					if (streamFinishedAt !== undefined && sawUsagePayload) break;
+					continue;
+				}
 
 				if (!chunk.usage) {
 					const choiceUsage = getChoiceUsage(choice);
 					if (choiceUsage) {
 						output.usage = parseChunkUsage(choiceUsage, model, premiumRequestsTotal);
+						sawUsagePayload = true;
 					}
 				}
 
@@ -794,6 +824,7 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 					if (finishReasonResult.errorMessage) {
 						output.errorMessage = finishReasonResult.errorMessage;
 					}
+					streamFinishedAt ??= Date.now();
 				}
 
 				if (choice.delta) {
@@ -967,6 +998,12 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 						}
 					}
 				}
+
+				// `finish_reason` + usage both observed: the chat-completions
+				// contract has nothing left to deliver. Break instead of waiting
+				// for `[DONE]`/connection close so hosts that hold the socket open
+				// can't park the turn until the idle watchdog errors it out.
+				if (streamFinishedAt !== undefined && sawUsagePayload) break;
 			}
 
 			if (streamMarkupHealing) {

package/src/providers/openai-responses-shared.ts

@@ -914,6 +914,14 @@ export async function processResponsesStream<TApi extends Api>(
 				output.stopReason = "toolUse";
 			}
 			options?.onCompleted?.();
+			// `response.completed`/`response.incomplete` is the last event of a
+			// Responses stream. Stop pulling instead of waiting for the server to
+			// close the connection: misbehaving providers keep the socket open
+			// after the terminal event, which would park this loop until the idle
+			// watchdog converts an already-successful turn into a timeout error.
+			// Breaking unwinds the iterator chain (the consumer's `.return()`
+			// reaches the SDK stream), actively releasing the connection.
+			break;
 		} else if (event.type === "error") {
 			throw new Error(`Error Code ${event.code}: ${event.message}`);
 		} else if (event.type === "response.failed") {

package/src/types.ts

@@ -24,6 +24,7 @@ import type { ZodType, z } from "zod/v4";
 import type { ApiKey } from "./auth-retry";
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
+import type { StopDetails } from "./providers/anthropic-wire";
 import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses";
 import type { CursorOptions } from "./providers/cursor";
 import type { GoogleOptions } from "./providers/google";
@@ -35,6 +36,7 @@ import type { OpenAICompletionsOptions } from "./providers/openai-completions";
 import type { OpenAIResponsesOptions } from "./providers/openai-responses";
 import type { AssistantMessageEventStream } from "./utils/event-stream";
 
+export type { StopDetails } from "./providers/anthropic-wire";
 export type { AssistantMessageEventStream } from "./utils/event-stream";
 
 /**
@@ -486,6 +488,7 @@ export interface AssistantMessage {
 	upstreamProvider?: string;
 	usage: Usage;
 	stopReason: StopReason;
+	stopDetails?: StopDetails | null;
 	errorMessage?: string;
 	/** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
 	errorStatus?: number;

package/src/utils/idle-iterator.ts

@@ -347,6 +347,89 @@ export async function* iterateWithIdleTimeout<T>(
 	}
 }
 
+export interface TerminalGraceIteratorOptions {
+	/**
+	 * Epoch-ms timestamp at which the consumer observed a logically terminal
+	 * item (e.g. a chat-completions chunk carrying `finish_reason`), or
+	 * `undefined` while the stream is still mid-response. Read before every
+	 * pull, so the consumer can flip it between yields.
+	 */
+	finishedAtMs: () => number | undefined;
+	/**
+	 * Post-terminal budget: how long after `finishedAtMs()` to keep draining
+	 * trailing items (e.g. a usage-only chunk or the `[DONE]` sentinel) before
+	 * ending the iteration cleanly. The deadline is fixed at
+	 * `finishedAtMs() + graceMs`; trailing items do not extend it, so
+	 * keepalive-only servers cannot hold the stream open.
+	 */
+	graceMs: number;
+	/**
+	 * Invoked when the grace window closes with the source still open. Use it
+	 * to abort the underlying request: the source generator is typically parked
+	 * mid-`next()` (not at a yield), so a queued `.return()` alone cannot reach
+	 * the transport until that pending read settles.
+	 */
+	onGraceEnd?: () => void;
+}
+
+/**
+ * Yields items from an async iterable until the consumer marks the stream
+ * logically finished AND the source stays silent past a short grace window.
+ *
+ * Misbehaving OpenAI-compatible servers deliver the terminal chunk but never
+ * send `[DONE]` nor close the connection; without this guard the consumer
+ * hangs on `iterator.next()` until the idle watchdog converts an
+ * already-successful turn into a timeout error. Grace expiry is a clean end
+ * of iteration, never an error.
+ */
+export async function* iterateWithTerminalGrace<T>(
+	iterable: AsyncIterable<T>,
+	options: TerminalGraceIteratorOptions,
+): AsyncGenerator<T> {
+	const iterator = iterable[Symbol.asyncIterator]();
+	try {
+		while (true) {
+			const finishedAtMs = options.finishedAtMs();
+			if (finishedAtMs === undefined) {
+				const result = await iterator.next();
+				if (result.done) return;
+				yield result.value;
+				continue;
+			}
+			const remainingMs = finishedAtMs + options.graceMs - Date.now();
+			if (remainingMs <= 0) {
+				options.onGraceEnd?.();
+				return;
+			}
+			const nextPromise = iterator.next();
+			let timer: NodeJS.Timeout | undefined;
+			const timeoutPromise = new Promise<"timeout">(resolve => {
+				timer = setTimeout(() => resolve("timeout"), remainingMs);
+			});
+			try {
+				const outcome = await Promise.race([nextPromise, timeoutPromise]);
+				if (outcome === "timeout") {
+					// The abandoned read settles (likely rejects) once onGraceEnd
+					// aborts the transport — mark it handled so it cannot surface
+					// as an unhandled rejection.
+					nextPromise.catch(() => {});
+					options.onGraceEnd?.();
+					return;
+				}
+				if (outcome.done) return;
+				yield outcome.value;
+			} finally {
+				if (timer !== undefined) clearTimeout(timer);
+			}
+		}
+	} finally {
+		const returnPromise = iterator.return?.();
+		if (returnPromise) {
+			void Promise.resolve(returnPromise).catch(() => {});
+		}
+	}
+}
+
 function abortReason(signal: AbortSignal): Error {
 	const reason = signal.reason;
 	if (reason instanceof Error) return reason;