@gajae-code/ai 0.1.1

package/src/providers/transform-messages.ts

@@ -0,0 +1,309 @@
+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
+ */
+export function transformMessages<TApi extends Api>(
+	messages: Message[],
+	model: Model<TApi>,
+	normalizeToolCallId?: (id: string, model: Model<TApi>, source: AssistantMessage) => string,
+): 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 have partially-streamed thinking signatures.
+			// A partial signature is invalid and will be rejected by the API, so we must
+			// strip signatures from thinking blocks in these messages.
+			const hasInvalidSignatures = assistantMsg.stopReason === "aborted" || assistantMsg.stopReason === "error";
+
+			const transformedContent = assistantMsg.content.flatMap(block => {
+				if (block.type === "thinking") {
+					// Strip signature from aborted/errored messages — it's likely incomplete
+					const sanitized =
+						hasInvalidSignatures && block.thinkingSignature ? { ...block, thinkingSignature: undefined } : block;
+					if (mustPreserveLatestAnthropicThinking) return sanitized;
+					// For same model: keep thinking blocks with signatures (needed for replay)
+					// even if the thinking text is empty (OpenAI encrypted reasoning)
+					if (isSameModel && sanitized.thinkingSignature) 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 (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;
+			});
+
+			return {
+				...assistantMsg,
+				content: transformedContent,
+			};
+		}
+		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.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.ts

@@ -0,0 +1,84 @@
+/**
+ * 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; // ±15s
+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("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")) {
+		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). */
+const USAGE_LIMIT_PATTERN =
+	/usage.?limit|usage_limit_reached|usage_not_included|limit_reached|quota.?exceeded|resource.?exhausted/i;
+
+export function isUsageLimitError(errorMessage: string): boolean {
+	return USAGE_LIMIT_PATTERN.test(errorMessage);
+}