@remodex/rmx 1.0.2

package/src/lib/eventstream-decoder.ts

@@ -0,0 +1,253 @@
+/**
+ * `application/vnd.amazon.eventstream` decoder.
+ *
+ * Ported from jawcode `packages/ai/src/providers/aws-eventstream.ts` (verbatim logic).
+ * Foundational dependency for AWS-eventstream providers: kiro (CodeWhisperer
+ * GenerateAssistantResponse) and amazon-bedrock (Converse). Self-contained — only
+ * uses Buffer / DataView / TextDecoder (Bun + Node compatible).
+ *
+ * Wire format (all integers big-endian):
+ *
+ *   [total length     u32]
+ *   [headers length   u32]
+ *   [prelude CRC32    u32]   <- CRC over the first 8 bytes
+ *   [headers          headers_length]
+ *   [payload          total_length - headers_length - 16]
+ *   [message CRC32    u32]   <- CRC over the entire message minus the trailing 4 bytes
+ *
+ * Headers: a sequence of `[name_len u8][name utf8][value_type u8][value …]`.
+ */
+
+const PRELUDE_LEN = 8;
+const PRELUDE_CRC_LEN = 4;
+const MESSAGE_CRC_LEN = 4;
+const HEADER_BLOCK_OFFSET = PRELUDE_LEN + PRELUDE_CRC_LEN;
+const MIN_MESSAGE_LEN = HEADER_BLOCK_OFFSET + MESSAGE_CRC_LEN;
+const MAX_MESSAGE_LEN = 16 * 1024 * 1024;
+const MAX_HEADERS_LEN = 128 * 1024;
+
+export interface EventStreamMessage {
+	/** Header casing is preserved verbatim (e.g. `:event-type`, `:message-type`). */
+	headers: Record<string, string>;
+	payload: Uint8Array;
+}
+
+/** CRC32 (IEEE / zlib polynomial 0xEDB88320), matches `@aws-crypto/crc32`. */
+const CRC_TABLE = (() => {
+	const t = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let c = i;
+		for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+		t[i] = c >>> 0;
+	}
+	return t;
+})();
+
+export function crc32(bytes: Uint8Array, seed = 0): number {
+	let c = (seed ^ 0xffffffff) >>> 0;
+	for (let i = 0; i < bytes.length; i++) c = (CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8)) >>> 0;
+	return (c ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * Decode a single, fully buffered eventstream message. Throws if the framing is
+ * malformed or either CRC mismatches.
+ */
+export function decodeMessage(frame: Uint8Array): EventStreamMessage {
+	if (frame.length < MIN_MESSAGE_LEN) throw new Error("eventstream: frame too short");
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const total = view.getUint32(0, false);
+	if (total !== frame.length) throw new Error(`eventstream: framed length ${total} != buffer ${frame.length}`);
+	if (total > MAX_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} exceeds maximum`);
+	const headersLen = view.getUint32(4, false);
+	const preludeCrc = view.getUint32(8, false);
+	const computedPreludeCrc = crc32(frame.subarray(0, PRELUDE_LEN));
+	if (computedPreludeCrc !== preludeCrc) throw new Error("eventstream: prelude CRC mismatch");
+	if (headersLen > MAX_HEADERS_LEN) throw new Error(`eventstream: headers length ${headersLen} exceeds maximum`);
+	if (headersLen > total - MIN_MESSAGE_LEN) throw new Error("eventstream: headers length exceeds frame payload");
+	const msgCrc = view.getUint32(total - MESSAGE_CRC_LEN, false);
+	const computedMsgCrc = crc32(frame.subarray(0, total - MESSAGE_CRC_LEN));
+	if (computedMsgCrc !== msgCrc) throw new Error("eventstream: message CRC mismatch");
+
+	const headersBytes = frame.subarray(HEADER_BLOCK_OFFSET, HEADER_BLOCK_OFFSET + headersLen);
+	const payload = frame.subarray(HEADER_BLOCK_OFFSET + headersLen, total - MESSAGE_CRC_LEN);
+	return { headers: parseHeaders(headersBytes), payload };
+}
+
+function parseHeaders(buf: Uint8Array): Record<string, string> {
+	const out: Record<string, string> = {};
+	const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+	const decoder = new TextDecoder();
+	let p = 0;
+	const need = (n: number, label: string) => {
+		if (p + n > buf.length) throw new Error(`eventstream: truncated header ${label}`);
+	};
+	while (p < buf.length) {
+		need(1, "name length");
+		const nameLen = view.getUint8(p);
+		p += 1;
+		need(nameLen, "name");
+		const name = decoder.decode(buf.subarray(p, p + nameLen));
+		p += nameLen;
+		need(1, "type");
+		const type = view.getUint8(p);
+		p += 1;
+		switch (type) {
+			case 0: // bool true
+				out[name] = "true";
+				break;
+			case 1: // bool false
+				out[name] = "false";
+				break;
+			case 2: // byte
+				need(1, "byte value");
+				out[name] = String(view.getInt8(p));
+				p += 1;
+				break;
+			case 3: // short
+				need(2, "short value");
+				out[name] = String(view.getInt16(p, false));
+				p += 2;
+				break;
+			case 4: // integer
+				need(4, "integer value");
+				out[name] = String(view.getInt32(p, false));
+				p += 4;
+				break;
+			case 5: // long — decimal string to avoid precision loss
+				need(8, "long value");
+				out[name] = bigIntFromBytes(buf.subarray(p, p + 8)).toString();
+				p += 8;
+				break;
+			case 6: {
+				// byte array — base64 for safe transport
+				need(2, "byte-array length");
+				const len = view.getUint16(p, false);
+				p += 2;
+				need(len, "byte-array value");
+				out[name] = Buffer.from(buf.buffer, buf.byteOffset + p, len).toString("base64");
+				p += len;
+				break;
+			}
+			case 7: {
+				// string
+				need(2, "string length");
+				const len = view.getUint16(p, false);
+				p += 2;
+				need(len, "string value");
+				out[name] = decoder.decode(buf.subarray(p, p + len));
+				p += len;
+				break;
+			}
+			case 8: // timestamp (ms since epoch as i64)
+				need(8, "timestamp value");
+				out[name] = new Date(Number(bigIntFromBytes(buf.subarray(p, p + 8)))).toISOString();
+				p += 8;
+				break;
+			case 9: {
+				// uuid
+				need(16, "uuid value");
+				const u = buf.subarray(p, p + 16);
+				const hex: string[] = [];
+				for (let i = 0; i < 16; i++) hex.push(u[i].toString(16).padStart(2, "0"));
+				out[name] =
+					`${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+				p += 16;
+				break;
+			}
+			default:
+				throw new Error(`eventstream: unknown header value type ${type}`);
+		}
+	}
+	return out;
+}
+
+function bigIntFromBytes(b: Uint8Array): bigint {
+	let v = 0n;
+	for (let i = 0; i < b.length; i++) v = (v << 8n) | BigInt(b[i]);
+	// sign-extend (two's complement)
+	if (b.length === 8 && b[0] & 0x80) v -= 1n << 64n;
+	return v;
+}
+
+/**
+ * Async generator that consumes a `ReadableStream<Uint8Array>` (a fetch response
+ * body) and yields fully-framed messages, handling arbitrary chunk boundaries.
+ */
+export async function* decodeEventStream(source: ReadableStream<Uint8Array>): AsyncGenerator<EventStreamMessage> {
+	const reader = source.getReader();
+	let buf: Uint8Array = new Uint8Array(0);
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (value && value.length > 0) buf = buf.length === 0 ? value : Buffer.concat([buf, value]);
+			let offset = 0;
+			while (buf.length - offset >= 4) {
+				const dv = new DataView(buf.buffer, buf.byteOffset + offset, buf.length - offset);
+				const total = dv.getUint32(0, false);
+				if (total < MIN_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} below minimum`);
+				if (total > MAX_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} exceeds maximum`);
+				if (buf.length - offset >= HEADER_BLOCK_OFFSET) {
+					const headersLen = dv.getUint32(4, false);
+					const preludeCrc = dv.getUint32(8, false);
+					const computedPreludeCrc = crc32(buf.subarray(offset, offset + PRELUDE_LEN));
+					if (computedPreludeCrc !== preludeCrc) throw new Error("eventstream: prelude CRC mismatch");
+					if (headersLen > MAX_HEADERS_LEN) throw new Error(`eventstream: headers length ${headersLen} exceeds maximum`);
+				}
+				if (buf.length - offset < total) break;
+				const frame = buf.subarray(offset, offset + total);
+				yield decodeMessage(frame);
+				offset += total;
+			}
+			if (offset > 0) buf = buf.slice(offset);
+			if (buf.length > MAX_MESSAGE_LEN) throw new Error(`eventstream: buffered frame exceeds maximum ${MAX_MESSAGE_LEN}`);
+			if (done) break;
+		}
+		if (buf.length > 0) throw new Error("eventstream: truncated message at end of stream");
+	} finally {
+		// Early termination (consumer break/return, turn abort, or an HTTP/2 mid-body reset) can leave
+		// an in-flight `reader.read()` pending when this generator's `finally` runs. Releasing the lock
+		// does NOT settle that orphaned read — Bun then surfaces it as an off-path
+		// `unhandledRejection: TypeError: null is not an object` that no caller try/catch can intercept.
+		// Cancel first (settles the pending read + closes the body), then release. On a clean `done`
+		// finish the read is already settled, so cancel() is a harmless no-op.
+		try {
+			await reader.cancel();
+		} catch {
+			/* body already errored/closed — nothing to cancel */
+		}
+		try {
+			reader.releaseLock();
+		} catch {
+			/* lock already released by cancel() on some runtimes */
+		}
+	}
+}
+
+/** Build a single eventstream frame (string headers only) — used by tests and fixtures. */
+export function encodeMessage(headers: Record<string, string>, payload: Uint8Array): Uint8Array {
+	const enc = new TextEncoder();
+	const headerParts: Uint8Array[] = [];
+	for (const [name, value] of Object.entries(headers)) {
+		const nameBytes = enc.encode(name);
+		const valueBytes = enc.encode(value);
+		const head = new Uint8Array(1 + nameBytes.length + 1 + 2);
+		const hv = new DataView(head.buffer);
+		hv.setUint8(0, nameBytes.length);
+		head.set(nameBytes, 1);
+		hv.setUint8(1 + nameBytes.length, 7); // string type
+		hv.setUint16(1 + nameBytes.length + 1, valueBytes.length, false);
+		headerParts.push(head, valueBytes);
+	}
+	const headersBytes = Buffer.concat(headerParts.map(p => Buffer.from(p)));
+	const total = HEADER_BLOCK_OFFSET + headersBytes.length + payload.length + MESSAGE_CRC_LEN;
+	const frame = new Uint8Array(total);
+	const dv = new DataView(frame.buffer);
+	dv.setUint32(0, total, false);
+	dv.setUint32(4, headersBytes.length, false);
+	dv.setUint32(8, crc32(frame.subarray(0, PRELUDE_LEN)), false);
+	frame.set(headersBytes, HEADER_BLOCK_OFFSET);
+	frame.set(payload, HEADER_BLOCK_OFFSET + headersBytes.length);
+	dv.setUint32(total - MESSAGE_CRC_LEN, crc32(frame.subarray(0, total - MESSAGE_CRC_LEN)), false);
+	return frame;
+}

package/src/lib/gcp-adc.ts

@@ -0,0 +1,341 @@
+/**
+ * Application Default Credentials (ADC) resolution for Vertex AI.
+ *
+ * Direct WebCrypto + REST implementation (no `google-auth-library`). Sources, in priority order:
+ *   1. `GOOGLE_APPLICATION_CREDENTIALS` env → file with `type: "service_account"` (RS256 JWT
+ *      exchange) or `type: "authorized_user"` (refresh-token exchange).
+ *   2. gcloud user ADC (`CLOUDSDK_CONFIG`, else `%APPDATA%\gcloud` on Windows, else
+ *      `~/.config/gcloud`) `application_default_credentials.json` (authorized_user flow).
+ *   3. GCE / Cloud Run metadata server.
+ *
+ * Tokens are cached per source key and refreshed `GOOGLE_VERTEX_REFRESH_SKEW_MS` (default 60s)
+ * before expiry. Concurrent callers waiting on a refresh share one in-flight promise.
+ *
+ * Security: never logs the access token, private key, or refresh token.
+ */
+
+import { Buffer } from "node:buffer";
+import * as os from "node:os";
+import * as path from "node:path";
+import { readFileSync, existsSync, statSync } from "node:fs";
+import {
+  captureConfigGeneration,
+  sweepExpiredOnWrite,
+  type GenerationContext,
+} from "./state-store-sweeper";
+
+/** Injectable fetch (tests pass a mock); defaults to the global fetch. */
+export type FetchImpl = typeof fetch;
+
+const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const METADATA_TOKEN_URL = "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token";
+const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const JWT_BEARER_GRANT = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+
+const TOKEN_TIMEOUT_MS = 15_000;
+const TOKEN_ATTEMPTS = 3;
+const TOKEN_RETRY_BASE_MS = 300;
+
+interface CachedToken {
+  token: string;
+  expiresAtMs: number;
+}
+
+interface ServiceAccountCredentials {
+  type: "service_account";
+  client_email: string;
+  private_key: string;
+  private_key_id?: string;
+}
+
+interface AuthorizedUserCredentials {
+  type: "authorized_user";
+  client_id: string;
+  client_secret: string;
+  refresh_token: string;
+}
+
+type AdcFileCredentials = ServiceAccountCredentials | AuthorizedUserCredentials;
+
+interface TokenResponse {
+  access_token: string;
+  expires_in: number;
+  token_type?: string;
+}
+
+const tokenCache = new Map<string, CachedToken>();
+const inflight = new Map<string, Promise<string>>();
+let lastReconciledGeneration = 0;
+let liveSources = new Set<string>();
+
+export function sweepExpiredGcpAdcTokens(now = Date.now()): number {
+  const skew = getRefreshSkewMs();
+  let removed = 0;
+  for (const [source, cached] of tokenCache) {
+    if (cached.expiresAtMs - skew > now) continue;
+    tokenCache.delete(source);
+    removed += 1;
+  }
+  return removed;
+}
+
+export function reconcileGcpAdcTokens(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  const currentSource = currentAdcSourceKey();
+  let removed = 0;
+  for (const source of tokenCache.keys()) {
+    if (source === currentSource) continue;
+    tokenCache.delete(source);
+    removed += 1;
+  }
+  liveSources = new Set([currentSource]);
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+function getRefreshSkewMs(): number {
+  const raw = Number(process.env.GOOGLE_VERTEX_REFRESH_SKEW_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 60_000;
+}
+
+/** gcloud config dir, matching the SDK's own resolution order. */
+function gcloudConfigDir(): string {
+  const explicit = process.env.CLOUDSDK_CONFIG?.trim();
+  if (explicit) return explicit;
+  if (process.platform === "win32" && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, "gcloud");
+  }
+  return path.join(os.homedir(), ".config", "gcloud");
+}
+
+function userAdcPath(): string {
+  return path.join(gcloudConfigDir(), "application_default_credentials.json");
+}
+
+/**
+ * A content-freshness fingerprint for a credential file, so an in-place rewrite (e.g.
+ * `gcloud auth application-default login`, or a rotated service-account key at the same path)
+ * changes the cache key and invalidates the stale token. Falls back to the bare path when stat fails.
+ */
+function fileSourceTag(prefix: string, filePath: string): string {
+  try {
+    const st = statSync(filePath);
+    return `${prefix}:${filePath}:${st.size}:${Math.floor(st.mtimeMs)}`;
+  } catch {
+    return `${prefix}:${filePath}`;
+  }
+}
+
+function readJsonFile<T>(filePath: string): T | undefined {
+  if (!existsSync(filePath)) return undefined;
+  return JSON.parse(readFileSync(filePath, "utf8")) as T;
+}
+
+function loadAdcCredentials(): { source: string; creds: AdcFileCredentials } | undefined {
+  const gacPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  if (gacPath) {
+    const creds = readJsonFile<AdcFileCredentials>(gacPath);
+    if (!creds) throw new Error(`GOOGLE_APPLICATION_CREDENTIALS points to a missing file: ${gacPath}`);
+    return { source: fileSourceTag("gac", gacPath), creds };
+  }
+  const userPath = userAdcPath();
+  const creds = readJsonFile<AdcFileCredentials>(userPath);
+  if (creds) return { source: fileSourceTag("user", userPath), creds };
+  return undefined;
+}
+
+/**
+ * The cache key for the source the NEXT resolve would use, computed cheaply (no network). Lets the
+ * cache return a token only when it still matches the active credential source, so an in-process
+ * change to GOOGLE_APPLICATION_CREDENTIALS (or the user ADC file) does not keep serving a stale
+ * token from a different source. Falls back to "metadata" when no file/env ADC is present.
+ */
+function currentAdcSourceKey(): string {
+  const gacPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  if (gacPath) return fileSourceTag("gac", gacPath);
+  const userPath = userAdcPath();
+  if (existsSync(userPath)) return fileSourceTag("user", userPath);
+  return "metadata";
+}
+
+function base64UrlEncode(bytes: Uint8Array | string): string {
+  const buf = typeof bytes === "string" ? Buffer.from(bytes, "utf8") : Buffer.from(bytes);
+  return buf.toString("base64url");
+}
+
+function pemToPkcs8(pem: string): ArrayBuffer {
+  const body = pem
+    .replace(/-----BEGIN [^-]+-----/g, "")
+    .replace(/-----END [^-]+-----/g, "")
+    .replace(/\s+/g, "");
+  if (!body) throw new Error("Invalid PEM: empty body");
+  const buf = Buffer.from(body, "base64");
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
+}
+
+async function signJwtRs256(claims: Record<string, unknown>, privateKeyPem: string, keyId?: string): Promise<string> {
+  const header: Record<string, unknown> = { alg: "RS256", typ: "JWT" };
+  if (keyId) header.kid = keyId;
+  const payload = `${base64UrlEncode(JSON.stringify(header))}.${base64UrlEncode(JSON.stringify(claims))}`;
+  const key = await globalThis.crypto.subtle.importKey(
+    "pkcs8",
+    pemToPkcs8(privateKeyPem),
+    { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = new Uint8Array(
+    await globalThis.crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(payload)),
+  );
+  return `${payload}.${base64UrlEncode(signature)}`;
+}
+
+function tokenRetryDelayMs(attempt: number): number {
+  const exp = TOKEN_RETRY_BASE_MS * 2 ** attempt;
+  return Math.floor(exp * (0.8 + Math.random() * 0.4));
+}
+
+function isRetryableTokenStatus(status: number): boolean {
+  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+
+function tokenTimeoutSignal(parent: AbortSignal | undefined): AbortSignal {
+  const timeout = AbortSignal.timeout(TOKEN_TIMEOUT_MS);
+  return parent ? AbortSignal.any([parent, timeout]) : timeout;
+}
+
+/**
+ * Exchange a grant for a Google access token, hardened with a per-attempt timeout + bounded retry
+ * on transient failures (network errors and 429/5xx). Non-retryable statuses (e.g. 400/401 from a
+ * bad grant) fail fast. The error message carries only the status code, never the response body
+ * (which can leak grant/account details) or the token/key.
+ */
+async function postForToken(body: URLSearchParams, signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<TokenResponse> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < TOKEN_ATTEMPTS; attempt++) {
+    if (signal?.aborted) throw signal.reason ?? new Error("Google OAuth token exchange aborted");
+    let response: Response;
+    try {
+      response = await fetchImpl(OAUTH_TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+        signal: tokenTimeoutSignal(signal),
+      });
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      lastError = err;
+      if (attempt === TOKEN_ATTEMPTS - 1) break;
+      await new Promise(resolve => setTimeout(resolve, tokenRetryDelayMs(attempt)));
+      continue;
+    }
+    if (response.ok) return (await response.json()) as TokenResponse;
+    if (!isRetryableTokenStatus(response.status) || attempt === TOKEN_ATTEMPTS - 1) {
+      throw new Error(`Google OAuth token exchange failed (${response.status})`);
+    }
+    lastError = new Error(`Google OAuth token exchange failed (${response.status})`);
+    await response.body?.cancel().catch(() => {});
+    await new Promise(resolve => setTimeout(resolve, tokenRetryDelayMs(attempt)));
+  }
+  throw lastError instanceof Error ? lastError : new Error("Google OAuth token exchange failed");
+}
+
+async function exchangeJwtForToken(creds: ServiceAccountCredentials, signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<TokenResponse> {
+  const now = Math.floor(Date.now() / 1000);
+  const assertion = await signJwtRs256(
+    { iss: creds.client_email, scope: CLOUD_PLATFORM_SCOPE, aud: OAUTH_TOKEN_URL, exp: now + 3600, iat: now },
+    creds.private_key,
+    creds.private_key_id,
+  );
+  return postForToken(new URLSearchParams({ grant_type: JWT_BEARER_GRANT, assertion }), signal, fetchImpl);
+}
+
+async function exchangeRefreshToken(creds: AuthorizedUserCredentials, signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<TokenResponse> {
+  return postForToken(
+    new URLSearchParams({
+      client_id: creds.client_id,
+      client_secret: creds.client_secret,
+      refresh_token: creds.refresh_token,
+      grant_type: "refresh_token",
+    }),
+    signal,
+    fetchImpl,
+  );
+}
+
+async function fetchMetadataToken(signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<TokenResponse | undefined> {
+  const timeout = AbortSignal.timeout(2000);
+  const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+  try {
+    const response = await fetchImpl(METADATA_TOKEN_URL, {
+      method: "GET",
+      headers: { "Metadata-Flavor": "Google" },
+      signal: combined,
+    });
+    if (!response.ok) return undefined;
+    return (await response.json()) as TokenResponse;
+  } catch {
+    return undefined;
+  }
+}
+
+async function resolveAccessTokenUncached(signal: AbortSignal | undefined, fetchImpl: FetchImpl): Promise<{ source: string; token: TokenResponse }> {
+  const adc = loadAdcCredentials();
+  if (adc) {
+    const token = adc.creds.type === "service_account"
+      ? await exchangeJwtForToken(adc.creds, signal, fetchImpl)
+      : await exchangeRefreshToken(adc.creds, signal, fetchImpl);
+    return { source: adc.source, token };
+  }
+  const metadata = await fetchMetadataToken(signal, fetchImpl);
+  if (metadata) return { source: "metadata", token: metadata };
+  throw new Error(
+    "Vertex AI requires Application Default Credentials. Set GOOGLE_APPLICATION_CREDENTIALS, run `gcloud auth application-default login`, or run on a GCE/Cloud Run instance with a service account.",
+  );
+}
+
+/** Returns a Bearer access token for the `Authorization` header on Vertex AI calls (cached + refreshed). */
+export async function getVertexAccessToken(options?: { signal?: AbortSignal; fetch?: FetchImpl }): Promise<string> {
+  const fetchImpl = options?.fetch ?? globalThis.fetch.bind(globalThis);
+  const skew = getRefreshSkewMs();
+  const now = Date.now();
+
+  // Only serve a cached token that matches the source the next resolve would actually use; prune
+  // expired or now-stale (different-source) entries so a credential-source change is honored.
+  const expectedSource = currentAdcSourceKey();
+  const writerGeneration = captureConfigGeneration();
+  for (const [source, cached] of tokenCache) {
+    if (source === expectedSource && cached.expiresAtMs - skew > now) return cached.token;
+    if (cached.expiresAtMs - skew <= now) tokenCache.delete(source);
+  }
+
+  // Dedup in-flight fetches PER source, not globally: if the credential source changes while a
+  // fetch is in flight, a new caller must not reuse the old source's promise (cross-source bleed).
+  const cacheKey = expectedSource;
+  const existing = inflight.get(cacheKey);
+  if (existing) return existing;
+
+  const promise = (async () => {
+    try {
+      const { source, token } = await resolveAccessTokenUncached(options?.signal, fetchImpl);
+      const expiresAtMs = Date.now() + Math.max(0, token.expires_in * 1000);
+      if (writerGeneration >= lastReconciledGeneration || liveSources.has(source)) {
+        tokenCache.set(source, { token: token.access_token, expiresAtMs });
+        sweepExpiredOnWrite(Date.now());
+      }
+      return token.access_token;
+    } finally {
+      inflight.delete(cacheKey);
+    }
+  })();
+  inflight.set(cacheKey, promise);
+  return promise;
+}
+
+/** Test seam: restores complete process-local token and reconciliation state. */
+export function __resetVertexTokenCache(): void {
+  tokenCache.clear();
+  inflight.clear();
+  lastReconciledGeneration = 0;
+  liveSources = new Set();
+}

package/src/lib/injection-debug-log.ts

@@ -0,0 +1,58 @@
+/** In-memory ring buffer of multi-agent guidance-injection / effort-cap log lines.
+ *
+ * Injection debug lines were previously console-only, so the GUI had an "Injection log"
+ * toggle with nothing to display. This buffer mirrors the provider debug buffer so the
+ * management API and GUI can tail injection lines the same way. Callers keep their own
+ * `isInjectionDebugEnabled()` guard; this module only stores what it is given. */
+
+import type { DebugLogEntry } from "./debug-log-buffer";
+import { retainedUtf8Bytes, truncateRetainedUtf8 } from "./admission";
+import { enforceAppOwnedMemoryBudget } from "./app-owned-memory";
+
+const MAX_LINES = 2_000;
+const MAX_DEBUG_LINE_BYTES = 16 * 1024;
+const buffer: DebugLogEntry[] = [];
+let nextSeq = 1;
+let bufferBytes = 0;
+
+function removeOldestEntry(): number {
+  const entry = buffer.shift();
+  if (!entry) return 0;
+  const bytes = retainedUtf8Bytes(entry.line);
+  bufferBytes -= bytes;
+  return bytes;
+}
+
+/** Append a line to the injection buffer and echo it to the server console. */
+export function injectionDebugLog(line: string): void {
+  const retainedLine = truncateRetainedUtf8(line, MAX_DEBUG_LINE_BYTES);
+  const entry: DebugLogEntry = { seq: nextSeq++, at: Date.now(), line: retainedLine };
+  buffer.push(entry);
+  bufferBytes += retainedUtf8Bytes(retainedLine);
+  while (buffer.length > MAX_LINES) removeOldestEntry();
+  enforceAppOwnedMemoryBudget();
+  console.log(line);
+}
+
+export function getInjectionDebugLogEntries(options?: { after?: number; limit?: number }): DebugLogEntry[] {
+  const after = options?.after ?? 0;
+  const limit = options?.limit ?? 500;
+  const filtered = after > 0 ? buffer.filter(entry => entry.seq > after) : buffer;
+  if (filtered.length <= limit) return filtered;
+  return filtered.slice(-limit);
+}
+
+export function injectionBufferMetrics(): { entries: number; bytes: number; oldestAt: number | null } {
+  return { entries: buffer.length, bytes: bufferBytes, oldestAt: buffer[0]?.at ?? null };
+}
+
+export function evictOldestInjectionEntryForBudget(): number {
+  return removeOldestEntry();
+}
+
+/** Test isolation. */
+export function resetInjectionDebugLogBufferForTests(): void {
+  buffer.length = 0;
+  bufferBytes = 0;
+  nextSeq = 1;
+}