@vib-rato/ai 0.16.0

package/src/providers/transform-messages.ts

@@ -0,0 +1,408 @@
+import turnAbortedGuidance from "../prompts/turn-aborted-guidance.md" with { type: "text" };
+import type {
+	Api,
+	AssistantMessage,
+	DeveloperMessage,
+	Message,
+	Model,
+	ToolCall,
+	ToolResultMessage,
+	UserMessage,
+} from "../types";
+
+const enum ToolCallStatus {
+	/** Tool call has received a result (real or synthetic for orphan) */
+	Resolved = 1,
+	/** Tool call was from an aborted message; synthetic result injected, skip real results */
+	Aborted = 2,
+}
+
+/**
+ * Normalize tool call ID for cross-provider compatibility.
+ * OpenAI Responses API generates IDs that are 450+ chars with special characters like `|`.
+ * Anthropic APIs require IDs matching ^[a-zA-Z0-9_-]+$ (max 64 chars).
+ *
+ * For aborted/errored turns, this function:
+ * - Preserves tool call structure (unlike converting to text summaries)
+ * - Injects synthetic "aborted" tool results
+ * - Adds a <turn-aborted> guidance marker for the model
+ */
+/**
+ * Detect directly adjacent private thinking blocks inside one assistant message's
+ * content. `thinking` and `redacted_thinking` are one adjacency class: the
+ * Anthropic wire contract rejects a replayed assistant turn where two such blocks
+ * sit next to each other with no intervening `tool_use`/`text` block (#4416).
+ *
+ * This is a pure, allocation-free predicate used by defense-in-depth diagnostics
+ * (issue #4443): the write-time transcript assertion (coding-agent persistence)
+ * and the stream-assembler SSE diagnostic (anthropic stream completion). It never
+ * inspects block payloads — only the block-type sequence — so it cannot leak
+ * thinking text, signatures, or credentials.
+ *
+ * Blocks separated by any non-private block (`tool_use`, `text`, …) are ordinary
+ * interleaved-thinking shape and return `false`.
+ */
+export function hasAdjacentPrivateThinkingBlocks(content: { type: string }[]): boolean {
+	let previousWasPrivate = false;
+	for (const block of content) {
+		const isPrivate = block.type === "thinking" || block.type === "redactedThinking";
+		if (isPrivate && previousWasPrivate) return true;
+		previousWasPrivate = isPrivate;
+	}
+	return false;
+}
+
+/**
+ * Collapse a run of directly adjacent `thinking` blocks inside one assistant message down
+ * to its first block.
+ *
+ * Anthropic accepts a replayed assistant turn carrying a single thinking block, and accepts
+ * thinking blocks separated by a `tool_use` (ordinary interleaved-thinking shape), but
+ * rejects two directly adjacent `thinking` blocks with
+ * `messages.N.content.M: thinking or redacted_thinking blocks in the latest assistant
+ * message cannot be modified`, citing the *second* block of the pair. Because the offending
+ * message keeps its index as history grows, a single such turn makes every later request in
+ * that session fail, and the mutation repair - scoped to the latest assistant message -
+ * can never reach it (#4416).
+ *
+ * `redactedThinking` is not folded in this phase, but the final send-boundary
+ * collapse in `convertAnthropicMessages` (#4425) treats `thinking` and
+ * `redacted_thinking` as one adjacency class per the API contract.
+ */
+function collapseAdjacentThinking<T extends { type: string }>(content: T[]): T[] {
+	let previousWasThinking = false;
+	let dropped = false;
+	const collapsed: T[] = [];
+	for (const block of content) {
+		const thinking = block.type === "thinking";
+		if (thinking && previousWasThinking) {
+			dropped = true;
+			continue;
+		}
+		previousWasThinking = thinking;
+		collapsed.push(block);
+	}
+	return dropped ? collapsed : content;
+}
+
+export function transformMessages<TApi extends Api>(
+	messages: Message[],
+	model: Model<TApi>,
+	normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string,
+	options?: { repairLatestAssistantThinking?: boolean; repairAllAssistantThinking?: boolean },
+): Message[] {
+	// Build a map of original tool call IDs to normalized IDs
+	const toolCallIdMap = new Map<string, string>();
+
+	const latestAssistantIndex = messages.findLastIndex(msg => msg.role === "assistant");
+	// First pass: transform messages (thinking blocks, tool call ID normalization)
+	const transformed = messages.map((msg, index) => {
+		// User and developer messages pass through unchanged
+		if (msg.role === "user" || msg.role === "developer") {
+			return msg;
+		}
+
+		// Handle toolResult messages - normalize toolCallId if we have a mapping
+		if (msg.role === "toolResult") {
+			const normalizedId = toolCallIdMap.get(msg.toolCallId);
+			if (normalizedId && normalizedId !== msg.toolCallId) {
+				return { ...msg, toolCallId: normalizedId };
+			}
+			return msg;
+		}
+
+		// Assistant messages need transformation check
+		if (msg.role === "assistant") {
+			const assistantMsg = msg as AssistantMessage;
+			const isSameModel =
+				assistantMsg.provider === model.provider &&
+				assistantMsg.api === model.api &&
+				assistantMsg.model === model.id;
+
+			const mustPreserveLatestAnthropicThinking =
+				index === latestAssistantIndex &&
+				model.api === "anthropic-messages" &&
+				assistantMsg.api === "anthropic-messages";
+			// Aborted/errored messages may contain partially-streamed thinking blocks.
+			// Anthropic requires thinking/redacted_thinking bytes in replayed assistant
+			// messages to match the original response exactly; stripping a signature,
+			// well-forming text, or keeping a partial redacted block would emit a
+			// modified thinking sequence. Drop those private blocks instead. Tool calls
+			// are kept so the second pass can either preserve real results or synthesize
+			// an explicit aborted result without leaving dangling tool_use blocks.
+			const hasPartialThinking = assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error";
+			// One-shot Anthropic replay repair. `repairLatestAssistantThinking` targets the
+			// "latest assistant message ... cannot be modified" 400; `repairAllAssistantThinking`
+			// targets the "Invalid `signature` in `thinking` block" 400, which can cite a block
+			// anywhere in the replayed history (e.g. after compaction/pruning rewrote an earlier
+			// turn), so the drop must apply to every assistant message. Within each
+			// message only blocks that would replay as native thinking/redacted_thinking
+			// are dropped; cross-model reasoning degrades to text and is preserved.
+			const dropAssistantThinkingForRepair =
+				(options?.repairAllAssistantThinking === true ||
+					(options?.repairLatestAssistantThinking === true && index === latestAssistantIndex)) &&
+				model.api === "anthropic-messages" &&
+				assistantMsg.api === "anthropic-messages";
+
+			const transformedContent = assistantMsg.content.flatMap(block => {
+				if (block.type === "thinking") {
+					if (hasPartialThinking) return [];
+					const sanitized = block;
+					// Repair must only drop blocks that would otherwise replay as native
+					// thinking. Cross-model/provider reasoning degrades to unsigned text
+					// below and was never replayed as a signed block, so it cannot be the
+					// signature failure — dropping it would silently lose valid context.
+					const replaysAsNativeThinking = mustPreserveLatestAnthropicThinking || isSameModel;
+					if (dropAssistantThinkingForRepair && replaysAsNativeThinking) return [];
+					if (mustPreserveLatestAnthropicThinking) return sanitized;
+					// For same model: keep thinking blocks with signatures (needed for replay)
+					// even if the thinking text is empty — but only for non-Anthropic APIs where
+					// the signature represents OpenAI encrypted reasoning. For anthropic-messages,
+					// a signed block with empty text means clear_thinking_20251015 stripped the
+					// content server-side while the stale signature remained; replaying it
+					// produces `thinking ... cannot be modified` 400s on every turn (#4247).
+					if (isSameModel && sanitized.thinkingSignature) {
+						if (sanitized.thinking.trim() === "" && model.api === "anthropic-messages") return [];
+						return sanitized;
+					}
+					// Skip empty thinking blocks, convert others to plain text
+					if (!sanitized.thinking || sanitized.thinking.trim() === "") return [];
+					if (isSameModel) return sanitized;
+					return {
+						type: "text" as const,
+						text: sanitized.thinking,
+					};
+				}
+
+				if (block.type === "redactedThinking") {
+					if (hasPartialThinking) return [];
+					// Same restriction as thinking blocks: cross-model/provider redacted
+					// blocks already drop below, so repair only needs to cover blocks that
+					// would replay as native redacted_thinking.
+					if (dropAssistantThinkingForRepair && (mustPreserveLatestAnthropicThinking || isSameModel)) {
+						return [];
+					}
+					if (mustPreserveLatestAnthropicThinking) return block;
+					if (isSameModel) return block;
+					return [];
+				}
+
+				if (block.type === "text") {
+					if (isSameModel) return block;
+					return {
+						type: "text" as const,
+						text: block.text,
+					};
+				}
+
+				if (block.type === "toolCall") {
+					const toolCall = block as ToolCall;
+					let normalizedToolCall: ToolCall = toolCall;
+
+					if (!isSameModel && toolCall.thoughtSignature) {
+						normalizedToolCall = { ...toolCall };
+						delete (normalizedToolCall as { thoughtSignature?: string }).thoughtSignature;
+					}
+
+					if (!isSameModel && normalizeToolCallId) {
+						const normalizedId = normalizeToolCallId(toolCall.id, model, assistantMsg);
+						if (normalizedId !== toolCall.id) {
+							toolCallIdMap.set(toolCall.id, normalizedId);
+							normalizedToolCall = { ...normalizedToolCall, id: normalizedId };
+						}
+					}
+
+					return normalizedToolCall;
+				}
+
+				return block;
+			});
+
+			// Only the Anthropic wire shape rejects adjacent private blocks; other targets
+			// either degrade reasoning to text above or carry their own encoding rules.
+			const replayableContent =
+				model.api === "anthropic-messages" ? collapseAdjacentThinking(transformedContent) : transformedContent;
+
+			return {
+				...assistantMsg,
+				content: replayableContent,
+			};
+		}
+		return msg;
+	});
+	const realToolResultIds = new Set(
+		transformed.filter((msg): msg is ToolResultMessage => msg.role === "toolResult").map(msg => msg.toolCallId),
+	);
+
+	// Anthropic rejects `tool_result` blocks whose `tool_use_id` does not appear in a prior
+	// `tool_use` block. After handoff/compaction folds an assistant turn into a summary
+	// string, the user-side `toolResult` for that turn can survive while the originating
+	// `tool_use` disappears — leaving an orphan that triggers HTTP 400. Track the set of
+	// `tool_use` ids that survive transformation so the second pass can drop orphans cleanly.
+	const validToolUseIds = new Set<string>();
+	for (const msg of transformed) {
+		if (msg.role !== "assistant") continue;
+		for (const block of msg.content) {
+			if (block.type === "toolCall") validToolUseIds.add(block.id);
+		}
+	}
+
+	// Second pass: insert synthetic empty tool results for orphaned tool calls
+	// and preserve aborted/errored tool results when they were already persisted.
+	const result: Message[] = [];
+	let pendingToolCalls: ToolCall[] = [];
+	let pendingAbortedToolCalls = new Map<string, ToolCall>();
+	let pendingAbortedTimestamp: number | undefined;
+	// Track tool call status: whether resolved (has result) or aborted (synthetic result injected, skip later real results)
+	const toolCallStatus = new Map<string, ToolCallStatus>();
+
+	const flushPendingToolCalls = (timestamp: number): void => {
+		if (pendingToolCalls.length === 0) return;
+		for (const tc of pendingToolCalls) {
+			if (!toolCallStatus.has(tc.id) && !realToolResultIds.has(tc.id)) {
+				result.push({
+					role: "toolResult",
+					toolCallId: tc.id,
+					toolName: tc.name,
+					content: [{ type: "text", text: "No result provided" }],
+					isError: true,
+					timestamp,
+				} as ToolResultMessage);
+				toolCallStatus.set(tc.id, ToolCallStatus.Resolved);
+			}
+		}
+		pendingToolCalls = [];
+	};
+
+	const flushPendingAbortedToolCalls = (): void => {
+		if (pendingAbortedTimestamp === undefined) return;
+		for (const tc of pendingAbortedToolCalls.values()) {
+			if (!toolCallStatus.has(tc.id)) {
+				result.push({
+					role: "toolResult",
+					toolCallId: tc.id,
+					toolName: tc.name,
+					content: [{ type: "text", text: "aborted" }],
+					isError: true,
+					timestamp: pendingAbortedTimestamp,
+				} as ToolResultMessage);
+				toolCallStatus.set(tc.id, ToolCallStatus.Aborted);
+			}
+		}
+		result.push({
+			role: "developer",
+			content: turnAbortedGuidance,
+			timestamp: pendingAbortedTimestamp + 1,
+		} as DeveloperMessage);
+		pendingAbortedToolCalls = new Map();
+		pendingAbortedTimestamp = undefined;
+	};
+
+	for (let i = 0; i < transformed.length; i++) {
+		const msg = transformed[i];
+		const messageTimestamp = "timestamp" in msg && typeof msg.timestamp === "number" ? msg.timestamp : Date.now();
+
+		if (msg.role === "assistant") {
+			flushPendingToolCalls(messageTimestamp);
+			flushPendingAbortedToolCalls();
+
+			const assistantMsg = msg as AssistantMessage;
+			const toolCalls = assistantMsg.content.filter(b => b.type === "toolCall") as ToolCall[];
+
+			if (assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") {
+				// Keep the assistant message with tool calls intact. If real tool results follow, preserve them;
+				// otherwise synthesize aborted results before the next turn boundary.
+				result.push(msg);
+				pendingAbortedToolCalls = new Map(toolCalls.map(toolCall => [toolCall.id, toolCall] as const));
+				pendingAbortedTimestamp = assistantMsg.timestamp;
+				continue;
+			}
+
+			if (toolCalls.length > 0) {
+				pendingToolCalls = toolCalls;
+			}
+
+			result.push(msg);
+		} else if (msg.role === "toolResult") {
+			if (pendingAbortedToolCalls.has(msg.toolCallId)) {
+				pendingAbortedToolCalls.delete(msg.toolCallId);
+				toolCallStatus.set(msg.toolCallId, ToolCallStatus.Resolved);
+				result.push(msg);
+				continue;
+			}
+
+			if (toolCallStatus.get(msg.toolCallId) === ToolCallStatus.Aborted) continue;
+
+			if (!validToolUseIds.has(msg.toolCallId)) {
+				// Orphan `tool_result`: the originating `tool_use` is not present in the
+				// transformed history (typically because handoff/compaction folded the
+				// assistant message into a summary string while the user-side result
+				// survived). Sending the block as-is would 400 the request, so it must
+				// be dropped.
+				//
+				// If a pending tool-call window is still open (either normal or
+				// aborted), the orphan cannot be replaced with a developer note here:
+				//
+				// * Anthropic requires the next message after an assistant `tool_use`
+				//   to be the matching `tool_result`. Inserting a developer message
+				//   would break that contiguity.
+				// * `flushPendingAbortedToolCalls` synthesizes "aborted" results
+				//   without checking whether a real result lands later in history
+				//   (unlike `flushPendingToolCalls`, which is gated by
+				//   `realToolResultIds`). Calling it here would convert a legitimate
+				//   later `tool_result` into a synthetic "aborted" one via the
+				//   `ToolCallStatus.Aborted` skip-guard.
+				//
+				// Drop the orphan silently in that case; the upcoming real
+				// `tool_result` will land normally on the next iteration.
+				if (pendingToolCalls.length > 0 || pendingAbortedToolCalls.size > 0) {
+					continue;
+				}
+				// No pending tool-call window: safe to preserve the text payload so the
+				// model still sees what the tool returned.
+				//
+				// The note is emitted with `role: "user"` rather than `role: "developer"`
+				// because the developer role is elevated by some providers:
+				//
+				// * Ollama maps `developer` -> `system` (highest instruction priority).
+				// * OpenAI chat-completions reasoning models forward `developer` as
+				//   `developer` (above-user instruction priority).
+				//
+				// Stale, model-untrusted tool output must not gain instruction priority
+				// above user/developer messages it lived alongside before compaction.
+				// `user` role is mapped to plain user content by every provider, so the
+				// content survives without ever being treated as an instruction the
+				// model should obey.
+				const textParts: string[] = [];
+				for (const part of msg.content) {
+					if (part.type === "text" && part.text.trim() !== "") textParts.push(part.text);
+				}
+				if (textParts.length > 0) {
+					const errorAttr = msg.isError ? ' is-error="true"' : "";
+					result.push({
+						role: "user",
+						content: `<stale-tool-result tool="${msg.toolName}" id="${msg.toolCallId}"${errorAttr}>\n${textParts.join("\n")}\n</stale-tool-result>`,
+						timestamp: messageTimestamp,
+					} as UserMessage);
+				}
+				continue;
+			}
+
+			toolCallStatus.set(msg.toolCallId, ToolCallStatus.Resolved);
+			result.push(msg);
+		} else if (msg.role === "user" || msg.role === "developer") {
+			flushPendingToolCalls(messageTimestamp);
+			flushPendingAbortedToolCalls();
+			result.push(msg);
+		} else {
+			flushPendingToolCalls(messageTimestamp);
+			flushPendingAbortedToolCalls();
+			result.push(msg);
+		}
+	}
+
+	flushPendingToolCalls(Date.now());
+	flushPendingAbortedToolCalls();
+
+	return result;
+}

package/src/providers/vision-guard.d.ts

@@ -0,0 +1,8 @@
+import type { ImageContent, TextContent } from "../types";
+export declare const NON_VISION_IMAGE_PLACEHOLDER = "[image omitted: model does not support vision]";
+export declare function partitionVisionContent(content: ReadonlyArray<TextContent | ImageContent>, supportsImages: boolean): {
+    textBlocks: TextContent[];
+    imageBlocks: ImageContent[];
+    omittedImages: boolean;
+};
+export declare function joinTextWithImagePlaceholder(text: string, omittedImages: boolean): string;

package/src/providers/vision-guard.ts

@@ -0,0 +1,31 @@
+import type { ImageContent, TextContent } from "../types";
+
+export const NON_VISION_IMAGE_PLACEHOLDER = "[image omitted: model does not support vision]";
+
+export function partitionVisionContent(
+	content: ReadonlyArray<TextContent | ImageContent>,
+	supportsImages: boolean,
+): {
+	textBlocks: TextContent[];
+	imageBlocks: ImageContent[];
+	omittedImages: boolean;
+} {
+	const textBlocks = content.filter((block): block is TextContent => block.type === "text");
+	const imageBlocks = content.filter((block): block is ImageContent => block.type === "image");
+	return {
+		textBlocks,
+		imageBlocks: supportsImages ? imageBlocks : [],
+		omittedImages: !supportsImages && imageBlocks.length > 0,
+	};
+}
+
+export function joinTextWithImagePlaceholder(text: string, omittedImages: boolean): string {
+	const parts: string[] = [];
+	if (text.length > 0) {
+		parts.push(text);
+	}
+	if (omittedImages) {
+		parts.push(NON_VISION_IMAGE_PLACEHOLDER);
+	}
+	return parts.join("\n");
+}

package/src/rate-limit-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Rate limit reason classification and backoff calculation utilities.
+ * Ported from opencode-antigravity-auth plugin for consistency.
+ */
+export type RateLimitReason = "QUOTA_EXHAUSTED" | "RATE_LIMIT_EXCEEDED" | "MODEL_CAPACITY_EXHAUSTED" | "SERVER_ERROR" | "UNKNOWN";
+/**
+ * Classify a rate-limit error message into a reason category.
+ * Priority order: MODEL_CAPACITY > RATE_LIMIT > QUOTA > SERVER_ERROR > UNKNOWN.
+ *
+ * "resource exhausted" maps to MODEL_CAPACITY (transient, short wait)
+ * "quota exceeded" maps to QUOTA_EXHAUSTED (long wait, switch account)
+ */
+export declare function parseRateLimitReason(errorMessage: string): RateLimitReason;
+/**
+ * Calculate backoff delay in ms for a given rate limit reason.
+ * MODEL_CAPACITY gets jitter to prevent thundering herd.
+ */
+export declare function calculateRateLimitBackoffMs(reason: RateLimitReason): number;
+export declare function isUsageLimitError(errorMessage: string): boolean;

package/src/rate-limit-utils.ts

@@ -0,0 +1,102 @@
+/**
+ * Rate limit reason classification and backoff calculation utilities.
+ * Ported from opencode-antigravity-auth plugin for consistency.
+ */
+
+export type RateLimitReason =
+	| "QUOTA_EXHAUSTED"
+	| "RATE_LIMIT_EXCEEDED"
+	| "MODEL_CAPACITY_EXHAUSTED"
+	| "SERVER_ERROR"
+	| "UNKNOWN";
+
+const QUOTA_EXHAUSTED_BACKOFF_MS = 30 * 60 * 1000; // 30 min
+const RATE_LIMIT_EXCEEDED_BACKOFF_MS = 30 * 1000; // 30s
+const MODEL_CAPACITY_BASE_MS = 45 * 1000; // 45s base
+const MODEL_CAPACITY_JITTER_MS = 30 * 1000; // uniform +0–30s above base → 45–75s total
+const SERVER_ERROR_BACKOFF_MS = 20 * 1000; // 20s
+
+/**
+ * Classify a rate-limit error message into a reason category.
+ * Priority order: MODEL_CAPACITY > RATE_LIMIT > QUOTA > SERVER_ERROR > UNKNOWN.
+ *
+ * "resource exhausted" maps to MODEL_CAPACITY (transient, short wait)
+ * "quota exceeded" maps to QUOTA_EXHAUSTED (long wait, switch account)
+ */
+export function parseRateLimitReason(errorMessage: string): RateLimitReason {
+	const lower = errorMessage.toLowerCase();
+
+	if (
+		lower.includes("capacity") ||
+		lower.includes("overloaded") ||
+		lower.includes("529") ||
+		lower.includes("503") ||
+		lower.includes("resource exhausted")
+	) {
+		return "MODEL_CAPACITY_EXHAUSTED";
+	}
+
+	if (
+		lower.includes("out_of_credits") ||
+		lower.includes("request would exceed your account's rate limit") ||
+		lower.includes("request would exceed your accounts rate limit")
+	) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (
+		lower.includes("per minute") ||
+		lower.includes("rate limit") ||
+		lower.includes("too many requests") ||
+		lower.includes("presque")
+	) {
+		return "RATE_LIMIT_EXCEEDED";
+	}
+
+	if (
+		lower.includes("exhausted") ||
+		lower.includes("quota") ||
+		lower.includes("usage limit") ||
+		lower.includes("model limit") ||
+		lower.includes("model_limit") ||
+		lower.includes("message limit") ||
+		lower.includes("message_limit") ||
+		lower.includes("limit for this model")
+	) {
+		return "QUOTA_EXHAUSTED";
+	}
+
+	if (lower.includes("500") || lower.includes("internal error") || lower.includes("internal server error")) {
+		return "SERVER_ERROR";
+	}
+
+	return "UNKNOWN";
+}
+
+/**
+ * Calculate backoff delay in ms for a given rate limit reason.
+ * MODEL_CAPACITY gets jitter to prevent thundering herd.
+ */
+export function calculateRateLimitBackoffMs(reason: RateLimitReason): number {
+	switch (reason) {
+		case "QUOTA_EXHAUSTED":
+			return QUOTA_EXHAUSTED_BACKOFF_MS;
+		case "RATE_LIMIT_EXCEEDED":
+			return RATE_LIMIT_EXCEEDED_BACKOFF_MS;
+		case "MODEL_CAPACITY_EXHAUSTED":
+			return MODEL_CAPACITY_BASE_MS + Math.random() * MODEL_CAPACITY_JITTER_MS;
+		case "SERVER_ERROR":
+			return SERVER_ERROR_BACKOFF_MS;
+		default:
+			return QUOTA_EXHAUSTED_BACKOFF_MS; // conservative default
+	}
+}
+
+/** Detect usage/quota limit errors in error messages (persistent, requires credential switch). */
+// ZAI reports durable token exhaustion as "[1310][Weekly/Monthly Limit Exhausted...]".
+// Keep this explicit so generic "rate limit exhausted, retry..." throttles remain retryable.
+const USAGE_LIMIT_PATTERN =
+	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|model.?limit|model_limit_reached|message.?limit|message_limit_reached|limit for this model|weekly\/monthly\s+limit\s+exhausted|quota.?exceeded|out_of_credits|request would exceed your account.?s rate limit|resource has been exhausted[^\n]*(?:quota|limit)/i;
+export function isUsageLimitError(errorMessage: string): boolean {
+	return USAGE_LIMIT_PATTERN.test(errorMessage);
+}

package/src/stream.d.ts

@@ -0,0 +1,45 @@
+import type { Effort } from "./model-thinking";
+import type { AnthropicOptions } from "./providers/anthropic";
+import type { Api, AssistantMessage, Context, Model, OptionsForApi, SimpleStreamOptions, ToolChoice } from "./types";
+import { AssistantMessageEventStream } from "./utils/event-stream";
+/**
+ * Get API key for provider from known environment variables, e.g. OPENAI_API_KEY.
+ *
+ * Provider authentication intentionally excludes cwd/.env values. Project dotenv files are
+ * loaded into $env for app/tool execution, but must not silently fund Vibrato model requests.
+ */
+export declare function getEnvApiKey(provider: string): string | undefined;
+/**
+ * Enumerate every provider that has an env-var fallback for `getEnvApiKey`.
+ * Used by `vib auth-broker migrate --include-env` to discover env-sourced keys
+ * that should be uploaded to the broker.
+ */
+export declare function listProvidersWithEnvKey(): string[];
+/**
+ * Provider-specific credential guidance appended to "no credential" errors.
+ *
+ * Headless Vibrato has no interactive `/login` TUI, so a bare "No API key" /
+ * "No credentials" error left users — OpenCode Go subscribers especially
+ * (#755) — unsure what signal Vibrato actually reads. OpenCode subscriptions are
+ * themselves API keys, so this names the env var Vibrato reads for the provider,
+ * warns that a project `.env` is intentionally ignored for provider
+ * credentials, and points OpenCode users at one-time interactive CLI credential capture.
+ *
+ * Returns an empty string when the provider has no env-var key and no special
+ * handling, so callers can append it unconditionally.
+ */
+export declare function formatProviderCredentialHint(provider: string): string;
+export declare function streamFromLazyImport(createInner: () => Promise<AssistantMessageEventStream>, signal?: AbortSignal, onStreamCreated?: () => void): AssistantMessageEventStream;
+/**
+ * Build an actionable "missing API key" error for a provider, used by the
+ * low-level `stream`/`complete` entry points (#755).
+ */
+export declare function formatMissingApiKeyError(provider: string): string;
+export declare function stream<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>, onStreamCreated?: () => void): AssistantMessageEventStream;
+export declare function complete<TApi extends Api>(model: Model<TApi>, context: Context, options?: OptionsForApi<TApi>): Promise<AssistantMessage>;
+export declare function streamSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): AssistantMessageEventStream;
+export declare function completeSimple<TApi extends Api>(model: Model<TApi>, context: Context, options?: SimpleStreamOptions): Promise<AssistantMessage>;
+export declare const OUTPUT_FALLBACK_BUFFER = 4000;
+export declare const ANTHROPIC_THINKING: Record<Effort, number>;
+export declare function mapAnthropicToolChoice(choice?: ToolChoice): AnthropicOptions["toolChoice"];
+export declare function resolveDefaultRequestMaxTokens<TApi extends Api>(model: Model<TApi>, requested?: number): number;