@linxiraos/pi-ai 1.0.0

package/src/utils/block-symbols.ts

@@ -0,0 +1,78 @@
+/** Stores streamed tool-call argument JSON for live renderers and parser recovery. */
+export const kStreamingPartialJson = Symbol("provider.block.partialJson");
+
+/** Carries streamed tool-call argument JSON without exposing a string-keyed property. */
+export type StreamingPartialJsonCarrier = object & { [kStreamingPartialJson]?: string };
+
+/** Reads streamed tool-call argument JSON from a block or event snapshot. */
+export function getStreamingPartialJson(block: StreamingPartialJsonCarrier | null | undefined): string | undefined {
+	return block?.[kStreamingPartialJson];
+}
+
+/** Writes streamed tool-call argument JSON to a block or clears it with `undefined`. */
+export function setStreamingPartialJson(block: StreamingPartialJsonCarrier, value: string | undefined): void {
+	block[kStreamingPartialJson] = value;
+}
+
+/** Clears streamed tool-call argument JSON without deleting or changing object shape. */
+export function clearStreamingPartialJson(block: StreamingPartialJsonCarrier): void {
+	if (Object.hasOwn(block, kStreamingPartialJson)) block[kStreamingPartialJson] = undefined;
+}
+
+/** Stores a provider-local stream block index without exposing a string-keyed property. */
+export const kStreamingBlockIndex = Symbol("provider.block.index");
+
+/** Stores the last parsed argument prefix length for throttled streaming JSON parsing. */
+export const kStreamingLastParseLen = Symbol("provider.block.lastParseLen");
+
+/**
+ * The Cursor interaction envelope's `call_id` for a streamed tool-call block.
+ *
+ * Tracked separately from the block's own `id` because they are NOT the same
+ * key: MCP and Pi blocks are filed under the id inside the call's `args`, which
+ * is what the exec channel pairs its result under, while every streamed
+ * `ToolCall*Update` correlates on the envelope's `call_id`. Matching
+ * completions against the block id would mis-route every call whose args carry
+ * their own id.
+ */
+export const kStreamingEnvelopeId = Symbol("provider.block.envelopeId");
+
+/** Marks streamed tool-call arguments that already received an authoritative done payload. */
+export const kStreamingArgumentsDone = Symbol("provider.block.argumentsDone");
+
+/** Classifies Cursor's in-flight tool-call kind without leaking provider-private state. */
+export const kStreamingBlockKind = Symbol("provider.block.kind");
+
+/**
+ * Marks a `toolCall` content block that Cursor's exec channel already
+ * executed server-side (via the coding-agent bridge) and whose result is
+ * buffered separately for emission via the assistant-loop stream.
+ *
+ * `agent-loop.ts` MUST skip execution of blocks carrying this marker —
+ * treating them as a fresh runnable tool call would run the same
+ * side-effecting tool (bash, write, delete, …) a second time. Symbol-keyed
+ * so it never persists across the JSONL round-trip, where rebuild instead
+ * pairs the block with its already-persisted `toolResult` message by id.
+ */
+export const kCursorExecResolved = Symbol("provider.block.cursorExecResolved");
+
+/** Carries the resolved marker without exposing a string-keyed property. */
+export type CursorExecResolvedCarrier = object & { [kCursorExecResolved]?: true };
+
+/**
+ * Marks a text block synthesized by cross-model thinking demotion in
+ * `transformMessages`. Converters that flatten adjacent text blocks into one
+ * string (openai-completions) insert a paragraph separator after marked
+ * blocks; unmarked adjacent blocks keep their original byte sequence.
+ * Symbol-keyed so the marker never persists across the JSONL round-trip and
+ * never reaches the wire.
+ */
+export const kDemotedThinking = Symbol("provider.block.demotedThinking");
+
+/** Carries the demoted-thinking marker without exposing a string-keyed property. */
+export type DemotedThinkingCarrier = object & { [kDemotedThinking]?: boolean };
+
+/** True for text blocks synthesized by cross-model thinking demotion. */
+export function isDemotedThinking(block: DemotedThinkingCarrier | null | undefined): boolean {
+	return block?.[kDemotedThinking] === true;
+}

package/src/utils/deterministic-id.ts

@@ -0,0 +1,20 @@
+/**
+ * A UUID-shaped string: five hex groups in the canonical 8-4-4-4-12 layout.
+ *
+ * NOT a spec-compliant RFC 4122 UUID — the version/variant nibbles are left as
+ * raw hash output — but the shape passes everywhere a UUID string is expected.
+ */
+export type DeterministicUuid = `${string}-${string}-${string}-${string}-${string}`;
+
+/**
+ * Format the leading 128 bits of `seed`'s SHA-256 digest as a v4-shape UUID
+ * (8-4-4-4-12 hex groups).
+ *
+ * Deterministic: identical seeds always map to the same id, so callers get
+ * stable ids across requests / conversation turns (reusing message-blob ids,
+ * keying prompt caches) without persisting a seed→id mapping.
+ */
+export function deterministicUuid(seed: string): DeterministicUuid {
+	const hex = new Bun.CryptoHasher("sha256").update(seed).digest("hex");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/src/utils/empty-completion-retry.ts

@@ -0,0 +1,161 @@
+/**
+ * Bounded retries for an empty assistant completion.
+ *
+ * Some providers — and especially flaky OpenAI-/Anthropic-compatible gateways —
+ * intermittently return a benign terminal stop carrying no content and no usage
+ * (e.g. a single OpenAI `delta: {}` + `finish_reason: "stop"` chunk). Delivered
+ * as-is the agent loop has nothing to act on and silently halts mid-task, so the
+ * request must be retried instead of surfaced.
+ *
+ * This wraps a single-attempt provider stream and re-invokes it (a fresh request
+ * with its own message state) when an attempt produces no meaningful content.
+ * Only a stream that streamed nothing meaningful is retried: the moment any
+ * text/thinking/tool delta is forwarded the attempt is committed, so live
+ * streaming (including thinking) is never delayed, retried, or duplicated.
+ *
+ * Mirrors the Gemini empty-response policy in `google-shared` (which keeps its
+ * own integrated loop) and is shared by the OpenAI-completions and
+ * Anthropic-messages providers.
+ */
+import { scheduler } from "node:timers/promises";
+import type { AssistantMessage, AssistantMessageEvent, Context } from "../types";
+import { AssistantMessageEventStream } from "./event-stream";
+
+export const MAX_EMPTY_COMPLETION_RETRIES = 2;
+export const EMPTY_COMPLETION_BASE_DELAY_MS = 500;
+
+const NON_WHITESPACE_RE = /\S/;
+
+/**
+ * Whether a completed assistant message carries content worth delivering: an
+ * image, tool call, or any non-whitespace text. An empty/whitespace-only message
+ * — or one that only ever produced thinking — is the "empty response" failure.
+ */
+export function hasVisibleAssistantContent(message: AssistantMessage): boolean {
+	for (const block of message.content) {
+		if (block.type === "image") return true;
+		if (block.type === "toolCall") return true;
+		if (block.type === "text" && NON_WHITESPACE_RE.test(block.text)) return true;
+	}
+	return false;
+}
+
+/** A streamed event that delivers content worth committing the attempt for. */
+function isMeaningfulCompletionEvent(event: AssistantMessageEvent): boolean {
+	switch (event.type) {
+		case "text_delta":
+		case "thinking_delta":
+		case "toolcall_delta":
+			return event.delta.length > 0;
+		case "text_end":
+		case "thinking_end":
+			return event.content.length > 0;
+		case "image_end":
+			return true;
+		case "toolcall_start":
+		case "toolcall_end":
+			return true;
+		default:
+			return false;
+	}
+}
+
+interface EmptyCompletionRetryOptions {
+	signal?: AbortSignal;
+	providerRetryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+}
+
+/**
+ * Wrap a single-attempt provider stream with bounded empty-completion retries.
+ * `attempt` MUST create a fresh request (and its own output message) on each
+ * call so a retry never inherits stale metadata from an empty attempt.
+ */
+export function withEmptyCompletionRetry<M, O extends EmptyCompletionRetryOptions>(
+	model: M,
+	context: Context,
+	options: O | undefined,
+	attempt: (model: M, context: Context, options?: O) => AssistantMessageEventStream,
+): AssistantMessageEventStream {
+	const outer = new AssistantMessageEventStream();
+	const signal = options?.signal;
+	void (async () => {
+		for (let emptyAttempt = 0; ; emptyAttempt++) {
+			const inner = attempt(model, context, options);
+			const buffered: AssistantMessageEvent[] = [];
+			let committed = false;
+			let terminal: AssistantMessageEvent | undefined;
+			const flush = (): void => {
+				for (const event of buffered) outer.push(event);
+				buffered.length = 0;
+			};
+			try {
+				for await (const event of inner) {
+					if (event.type === "done" || event.type === "error") {
+						terminal = event;
+						break;
+					}
+					// Buffer pre-content events (start/*_start) so an empty attempt can
+					// be discarded; commit the moment real content streams.
+					if (!committed && !isMeaningfulCompletionEvent(event)) {
+						buffered.push(event);
+						continue;
+					}
+					committed = true;
+					flush();
+					outer.push(event);
+					if (outer.done) return;
+				}
+			} catch (error) {
+				flush();
+				outer.fail(error);
+				return;
+			}
+
+			// Retry only a genuinely degenerate completion: a normal stop that
+			// produced no visible content and reported no generated content tokens.
+			// Some providers count the terminal EOS as one output token, so a
+			// one-token invisible stop is still the same empty-completion failure.
+			const message = terminal?.type === "done" ? terminal.message : undefined;
+			const isRetryableEmpty =
+				!committed &&
+				message !== undefined &&
+				message.stopReason === "stop" &&
+				!message.errorMessage &&
+				(message.usage?.output ?? 0) <= 1 &&
+				!hasVisibleAssistantContent(message);
+
+			if (isRetryableEmpty && emptyAttempt < MAX_EMPTY_COMPLETION_RETRIES && !signal?.aborted) {
+				const delayMs = EMPTY_COMPLETION_BASE_DELAY_MS * 2 ** emptyAttempt;
+				try {
+					if (options?.providerRetryWait) await options.providerRetryWait(delayMs, signal);
+					else await scheduler.wait(delayMs, { signal });
+				} catch (waitError) {
+					// Aborted during backoff: deliver the empty result rather than hang.
+					// Any other wait failure is a real error and must surface.
+					flush();
+					if (signal?.aborted) {
+						if (terminal) outer.push(terminal);
+					} else {
+						outer.fail(waitError);
+					}
+					return;
+				}
+				// Discard the buffered `start` from this empty attempt and retry.
+				continue;
+			}
+
+			flush();
+			if (terminal) {
+				outer.push(terminal);
+			} else if (!outer.done) {
+				try {
+					outer.end(await inner.result());
+				} catch (error) {
+					outer.fail(error);
+				}
+			}
+			return;
+		}
+	})();
+	return outer;
+}

package/src/utils/event-stream.ts

@@ -0,0 +1,202 @@
+import * as AIError from "../error";
+import type { AssistantMessage, AssistantMessageEvent } from "../types";
+
+// Generic event stream class for async iteration
+export class EventStream<T, R = T> implements AsyncIterable<T> {
+	queue: T[] = [];
+	waiting: Array<{ resolve: (value: IteratorResult<T>) => void; reject: (err: unknown) => void }> = [];
+	done = false;
+	/** True once finalResultPromise has been resolved or rejected. */
+	resultSettled = false;
+	#failed = false;
+	#error: unknown = undefined;
+	/**
+	 * Consumer-side local operations currently in flight for this stream — a
+	 * provider transport waiting on a server-requested local tool bridge
+	 * (e.g. the Cursor exec channel) before it can send the result upstream.
+	 * While non-zero, event silence is attributable to our own pending work,
+	 * not a provider stall; idle watchdogs consult {@link hasPendingLocalWork}.
+	 */
+	#pendingLocalWork = 0;
+	finalResultPromise: Promise<R>;
+	resolveFinalResult!: (result: R) => void;
+	rejectFinalResult!: (err: unknown) => void;
+	isComplete: (event: T) => boolean;
+	extractResult: (event: T) => R;
+
+	constructor(isComplete: (event: T) => boolean, extractResult: (event: T) => R) {
+		const { promise, resolve, reject } = Promise.withResolvers<R>();
+		// Prevent an unhandled rejection when fail() is called but nobody awaits result().
+		// Callers who do await result() still receive the rejection normally.
+		promise.catch(() => {});
+		this.finalResultPromise = promise;
+		this.resolveFinalResult = resolve;
+		this.rejectFinalResult = reject;
+		this.isComplete = isComplete;
+		this.extractResult = extractResult;
+	}
+
+	push(event: T): void {
+		if (this.done) return;
+
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resultSettled = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		// Deliver to waiting consumer or queue it
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	deliver(event: T): void {
+		const waiter = this.waiting.shift();
+		if (waiter) {
+			waiter.resolve({ value: event, done: false });
+		} else {
+			this.queue.push(event);
+		}
+	}
+
+	end(result?: R): void {
+		this.done = true;
+		if (result !== undefined) {
+			this.resultSettled = true;
+			this.resolveFinalResult(result);
+		} else if (!this.resultSettled) {
+			// end() without a terminal value must still settle result() —
+			// otherwise complete()/result() awaits hang forever.
+			this.resultSettled = true;
+			this.rejectFinalResult(
+				new AIError.ProviderResponseError("Stream ended without a final result", { kind: "envelope" }),
+			);
+		}
+		// Notify all waiting consumers that we're done
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.resolve({ value: undefined as any, done: true });
+		}
+	}
+
+	endWaiting(): void {
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.resolve({ value: undefined as any, done: true });
+		}
+	}
+
+	fail(err: unknown): void {
+		if (this.done) return;
+		this.done = true;
+		this.#failed = true;
+		this.#error = err;
+		this.resultSettled = true;
+		this.rejectFinalResult(err);
+		while (this.waiting.length > 0) {
+			const waiter = this.waiting.shift()!;
+			waiter.reject(err);
+		}
+	}
+
+	async *[Symbol.asyncIterator](): AsyncIterator<T> {
+		while (true) {
+			if (this.queue.length > 0) {
+				yield this.queue.shift()!;
+			} else if (this.#failed) {
+				throw this.#error;
+			} else if (this.done) {
+				return;
+			} else {
+				const result = await new Promise<IteratorResult<T>>((resolve, reject) =>
+					this.waiting.push({ resolve, reject }),
+				);
+				if (result.done) return;
+				yield result.value;
+			}
+		}
+	}
+
+	result(): Promise<R> {
+		return this.finalResultPromise;
+	}
+
+	/** True while local work tracked via {@link trackLocalWork} is pending. */
+	get hasPendingLocalWork(): boolean {
+		return this.#pendingLocalWork > 0;
+	}
+
+	/**
+	 * Track a local-work promise so idle watchdogs on this stream do not treat
+	 * the event silence while it is pending as a provider stall.
+	 */
+	async trackLocalWork<TWork>(work: Promise<TWork>): Promise<TWork> {
+		this.#pendingLocalWork++;
+		try {
+			return await work;
+		} finally {
+			this.#pendingLocalWork--;
+		}
+	}
+}
+
+export class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+	constructor() {
+		super(
+			event => event.type === "done" || event.type === "error",
+			event => {
+				if (event.type === "done") {
+					return event.message;
+				} else if (event.type === "error") {
+					return event.error;
+				}
+				throw new AIError.ProviderResponseError("Unexpected event type for final result", { kind: "envelope" });
+			},
+		);
+	}
+
+	override push(event: AssistantMessageEvent): void {
+		if (this.done) return;
+
+		if (event.type === "error" && event.error.stopReason === "error") {
+			AIError.classifyMessage(event.error);
+		}
+
+		// Completion resolves the final result and still emits the terminal event.
+		if (this.isComplete(event)) {
+			this.done = true;
+			this.resultSettled = true;
+			this.resolveFinalResult(this.extractResult(event));
+		}
+
+		this.deliver(event);
+	}
+
+	override end(result?: AssistantMessage): void {
+		this.done = true;
+		if (result !== undefined) {
+			if (result.stopReason === "error") {
+				AIError.classifyMessage(result);
+			}
+			this.resultSettled = true;
+			this.resolveFinalResult(result);
+		} else if (!this.resultSettled) {
+			// Mirror the base class: a result-less end() must not leave
+			// result() pending forever.
+			this.resultSettled = true;
+			this.rejectFinalResult(
+				new AIError.ProviderResponseError("Stream ended without a final result", { kind: "envelope" }),
+			);
+		}
+		this.endWaiting();
+	}
+}
+
+/** Create an assistant-message event stream for legacy extension providers. */
+export function createAssistantMessageEventStream(): AssistantMessageEventStream {
+	return new AssistantMessageEventStream();
+}

package/src/utils/foundry.ts

@@ -0,0 +1,8 @@
+import { $env } from "@linxiraos/pi-utils";
+
+export function isFoundryEnabled(): boolean {
+	const value = $env.CLAUDE_CODE_USE_FOUNDRY;
+	if (!value) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}

package/src/utils/google-validation.ts

@@ -0,0 +1,25 @@
+export function extractGoogleValidationUrl(errorBody: string): string | undefined {
+	if (!errorBody.includes("VALIDATION_REQUIRED")) return undefined;
+	const start = errorBody.indexOf("{");
+	if (start === -1) return undefined;
+	try {
+		const parsed = JSON.parse(errorBody.slice(start)) as {
+			error?: { details?: Array<{ reason?: string; metadata?: { validation_url?: string } }> };
+		};
+		const detail = parsed.error?.details?.find(
+			d => d.reason === "VALIDATION_REQUIRED" && typeof d.metadata?.validation_url === "string",
+		);
+		return detail?.metadata?.validation_url;
+	} catch {
+		return undefined;
+	}
+}
+
+export function formatGoogleValidationRequiredMessage(
+	validationUrl: string,
+	nextAction: string,
+	email?: string,
+): string {
+	const account = email ? ` for ${email}` : "";
+	return `Account verification required${account}. Visit ${validationUrl} to continue, then ${nextAction}.`;
+}