@oh-my-pi/pi-ai 15.3.1 → 15.3.2

package/CHANGELOG.md

@@ -2,12 +2,32 @@
 
 ## [Unreleased]
 
+## [15.3.2] - 2026-05-25
+### Added
+
+- Added `GET /v1/snapshot/stream` for live auth-broker snapshot updates via SSE with `snapshot`, `entry`, and `removed` event frames
+- Added `AuthBrokerClient.openSnapshotStream()` for consuming SSE snapshot streams from `/v1/snapshot/stream`
+- Added `streamSnapshots` option to `RemoteAuthCredentialStore` (default `true`) to enable or disable SSE-based snapshot synchronization
+- Added `streamKeepaliveMs` to `startAuthBroker()` to tune heartbeat frequency for the SSE stream
+- Added `AuthStorage.checkCredentials({ signal?, timeoutMs?, baseUrlResolver? })` that returns a per-credential `CredentialHealthResult` with tri-state `ok` (`true` / `false` / `null`-unverifiable), the credential's identity (provider, type, email/accountId, broker-refresh flag), and the upstream error string when the probe fails. Iterates sequentially over `listAuthCredentials()`, exercises OAuth refresh on expiry, then calls the per-provider `UsageProvider.fetchUsage` without swallowing errors — so callers can identify which row in a multi-account broker is producing 401s instead of getting a silently-deduplicated `fetchUsageReports` list.
+- Added `GET /v1/credentials/check` to `startAuthGateway()` that forwards to `AuthStorage.checkCredentials` and returns `{ generatedAt, credentials }`. Gated by the same bearer as the rest of the gateway.
+
+### Changed
+
+- Changed `RemoteAuthCredentialStore` to prefer SSE snapshot streaming and automatically fall back to long-polling when a broker returns 404 for `/v1/snapshot/stream`
+- Changed snapshot write-refresh flow so `RemoteAuthCredentialStore` skips immediate `/v1/snapshot` refreshes when SSE streaming is active
+- Changed broker SSE stream behavior to keep connections open with periodic keepalives and an increased server idle timeout
+
 ## [15.3.0] - 2026-05-25
 
 ### Added
 
 - Added DeepSeek to the built-in API-key login provider catalog so `omp login deepseek` stores a reusable `DEEPSEEK_API_KEY` credential for the bundled DeepSeek models.
 
+### Fixed
+
+- Fixed `openai-responses` requests intermittently 400ing with `No tool call found for function call output with call_id …` after an aborted turn or a locally-rejected tool call (e.g. argument-validation failure). `convertConversationMessages` now folds orphan `function_call_output` / `custom_tool_call_output` items — those whose matching `function_call` was wiped by an earlier `dt: false` snapshot splice or never landed in any persisted provider payload — into assistant text notes, preserving the payload while keeping the request grammatically valid ([#1351](https://github.com/can1357/oh-my-pi/issues/1351)).
+
 ## [15.2.4] - 2026-05-22
 
 ### Fixed

package/dist/types/auth-broker/client.d.ts

@@ -1,5 +1,5 @@
 import type { AuthCredential } from "../auth-storage";
-import type { CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, UsageResponse } from "./types";
+import type { CredentialDisableResponse, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types";
 export interface AuthBrokerClientOptions {
     /** Base URL (e.g. `https://broker.tailnet:8765`). Trailing slashes are trimmed. */
     url: string;
@@ -21,6 +21,14 @@ export declare class AuthBrokerError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Thrown when a broker responds 404 to `GET /v1/snapshot/stream` — old
+ * brokers that predate the SSE endpoint. Callers (`RemoteAuthCredentialStore`)
+ * detect this sentinel to fall back to long-polling permanently.
+ */
+export declare class AuthBrokerStreamUnsupportedError extends AuthBrokerError {
+    constructor(message?: string);
+}
 export interface FetchSnapshotOptions {
     ifGenerationGt?: number;
     waitMs?: number;
@@ -39,6 +47,18 @@ export declare class AuthBrokerClient {
     constructor(opts: AuthBrokerClientOptions);
     healthz(signal?: AbortSignal): Promise<HealthzResponse>;
     fetchSnapshot(opts?: FetchSnapshotOptions): Promise<FetchSnapshotResult>;
+    /**
+     * Subscribe to the broker's SSE snapshot stream. The first frame is always
+     * a full `snapshot`; subsequent frames are `entry` upserts / refreshes or
+     * `removed` deletes. Caller controls lifecycle via `opts.signal`.
+     *
+     * Throws {@link AuthBrokerStreamUnsupportedError} when the broker responds
+     * 404 — older brokers predate this endpoint and the caller should fall back
+     * to long-polling for the remainder of its lifetime.
+     */
+    openSnapshotStream(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SnapshotStreamEvent>;
     fetchUsage(signal?: AbortSignal): Promise<UsageResponse>;
     refreshCredential(id: number, signal?: AbortSignal): Promise<CredentialRefreshResponse>;
     disableCredential(id: number, cause: string, signal?: AbortSignal): Promise<CredentialDisableResponse>;

package/dist/types/auth-broker/remote-store.d.ts

@@ -2,7 +2,7 @@ import { type AuthCredential, type AuthCredentialStore, type OAuthCredential, ty
 import type { Provider } from "../types";
 import type { UsageReport } from "../usage";
 import type { OAuthCredentials } from "../utils/oauth/types";
-import type { AuthBrokerClient } from "./client";
+import { type AuthBrokerClient } from "./client";
 import type { SnapshotResponse } from "./types";
 export interface RemoteAuthCredentialStoreOptions {
     client: AuthBrokerClient;
@@ -11,6 +11,11 @@ export interface RemoteAuthCredentialStoreOptions {
      * {@link RemoteAuthCredentialStore.refreshSnapshot} before the first read.
      */
     initialSnapshot?: SnapshotResponse;
+    /**
+     * Subscribe to the broker's SSE snapshot stream when available. Falls back
+     * to long-poll permanently when the broker returns 404. Default `true`.
+     */
+    streamSnapshots?: boolean;
 }
 export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     #private;

package/dist/types/auth-broker/server.d.ts

@@ -14,6 +14,12 @@ export interface AuthBrokerServerOptions {
     refreshIntervalMs?: number;
     /** Disable the background refresher (e.g. for tests). */
     disableRefresher?: boolean;
+    /**
+     * Override SSE keepalive cadence in milliseconds for `/v1/snapshot/stream`.
+     * Internal-only — tests use a short interval so they can assert heartbeats
+     * without long sleeps. Default {@link DEFAULT_STREAM_KEEPALIVE_MS}.
+     */
+    streamKeepaliveMs?: number;
 }
 export interface AuthBrokerServerHandle {
     /** Bound URL (`http://host:port`). */

package/dist/types/auth-broker/types.d.ts

@@ -56,6 +56,35 @@ export interface CredentialUploadRequest {
 export interface CredentialUploadResponse {
     entries: AuthCredentialSnapshotEntry[];
 }
+/**
+ * SSE event kinds emitted on `GET /v1/snapshot/stream`. The same value is set
+ * as the SSE `event:` name (load-bearing for clients) **and** embedded as a
+ * `kind` field inside the JSON body so a Zod discriminated union can validate
+ * the payload without consulting the line metadata.
+ */
+export type SnapshotStreamEventKind = "snapshot" | "entry" | "removed";
+/** Initial frame emitted on connect — the full {@link SnapshotResponse}. */
+export interface SnapshotStreamSnapshotEvent extends SnapshotResponse {
+    kind: "snapshot";
+}
+/** Single credential added/changed (upsert or refresh). */
+export interface SnapshotStreamEntryEvent {
+    kind: "entry";
+    generation: number;
+    serverNowMs: number;
+    refresher: RefresherSchedule;
+    entry: SnapshotEntry;
+}
+/** Single credential disabled/deleted. */
+export interface SnapshotStreamRemovedEvent {
+    kind: "removed";
+    generation: number;
+    serverNowMs: number;
+    refresher: RefresherSchedule;
+    id: number;
+}
+/** Discriminated union of every event the snapshot stream emits. */
+export type SnapshotStreamEvent = SnapshotStreamSnapshotEvent | SnapshotStreamEntryEvent | SnapshotStreamRemovedEvent;
 /**
  * Default bearer-protected route prefix. The broker exposes `/v1/healthz`
  * unauthenticated for liveness probes; everything else requires a bearer.
@@ -67,3 +96,10 @@ export declare const DEFAULT_AUTH_BROKER_BIND = "127.0.0.1:8765";
 export declare const DEFAULT_REFRESH_SKEW_MS: number;
 /** Default broker refresh-loop cadence. */
 export declare const DEFAULT_REFRESH_INTERVAL_MS = 60000;
+/** Keepalive cadence for `GET /v1/snapshot/stream` SSE comments. */
+export declare const DEFAULT_STREAM_KEEPALIVE_MS = 20000;
+/**
+ * Bun.serve `idleTimeout` (seconds) used by the broker. Default Bun idle
+ * timeout (10s) would close long-lived SSE connections between keepalives.
+ */
+export declare const DEFAULT_SERVER_IDLE_TIMEOUT_S = 255;

package/dist/types/auth-broker/wire-schemas.d.ts

@@ -138,6 +138,154 @@ export declare const snapshotResponseSchema: z.ZodObject<{
         rotatesInMs: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** First frame on connect — full snapshot embedded inline with a `kind` tag. */
+export declare const snapshotStreamSnapshotEventSchema: z.ZodObject<{
+    generation: z.ZodNumber;
+    generatedAt: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    credentials: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+        rotatesInMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    kind: z.ZodLiteral<"snapshot">;
+}, z.core.$strict>;
+/** Per-credential upsert/refresh delta. */
+export declare const snapshotStreamEntryEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"entry">;
+    generation: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    entry: z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+        rotatesInMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Per-credential delete delta. */
+export declare const snapshotStreamRemovedEventSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"removed">;
+    generation: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    id: z.ZodNumber;
+}, z.core.$strict>;
+/** Discriminated union over every event frame the snapshot stream emits. */
+export declare const snapshotStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    generation: z.ZodNumber;
+    generatedAt: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    credentials: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+        rotatesInMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    kind: z.ZodLiteral<"snapshot">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"entry">;
+    generation: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    entry: z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        credential: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            access: z.ZodString;
+            expires: z.ZodNumber;
+            enterpriseUrl: z.ZodOptional<z.ZodString>;
+            projectId: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            accountId: z.ZodOptional<z.ZodString>;
+            refresh: z.ZodLiteral<"__remote__">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"api_key">;
+            key: z.ZodString;
+        }, z.core.$strict>], "type">;
+        identityKey: z.ZodNullable<z.ZodString>;
+        rotatesInMs: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"removed">;
+    generation: z.ZodNumber;
+    serverNowMs: z.ZodNumber;
+    refresher: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        intervalMs: z.ZodNumber;
+        skewMs: z.ZodNumber;
+        nextSweepInMs: z.ZodNumber;
+    }, z.core.$strict>;
+    id: z.ZodNumber;
+}, z.core.$strict>], "kind">;
 export declare const healthzResponseSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     version: z.ZodOptional<z.ZodString>;

package/dist/types/auth-storage.d.ts

@@ -44,6 +44,45 @@ export interface StoredAuthCredential {
     credential: AuthCredential;
     disabledCause: string | null;
 }
+/**
+ * Per-credential health record returned by {@link AuthStorage.checkCredentials}.
+ *
+ * Use this to identify which credential in a multi-account pool is causing
+ * auth errors. `ok` is tri-state:
+ *
+ * - `true` — credential authenticated against the provider's auth-verifying
+ *   probe (today: the usage endpoint). For OAuth this also exercises refresh
+ *   when the access token was expired.
+ * - `false` — the probe rejected the credential (401/403/refresh failure/etc).
+ *   `reason` carries the upstream error string.
+ * - `null` — no probe is configured for this provider (or the configured
+ *   probe doesn't support this credential type). The credential's auth
+ *   status is unverifiable from here.
+ */
+export interface CredentialHealthResult {
+    /** Database row id (matches {@link StoredAuthCredential.id}). */
+    id: number;
+    provider: string;
+    type: AuthCredential["type"];
+    /** OAuth email if known on the stored credential or surfaced by the probe. */
+    email?: string;
+    /** OAuth account id / org id if known. */
+    accountId?: string;
+    /** `true` when the refresh token lives on a remote broker (sentinel was present). */
+    remoteRefresh?: true;
+    ok: boolean | null;
+    /** Failure / unverifiable reason; absent when `ok === true`. */
+    reason?: string;
+    /** Probe usage report (raw payload stripped) when `ok === true`. */
+    report?: Omit<UsageReport, "raw">;
+}
+export interface CheckCredentialsOptions {
+    signal?: AbortSignal;
+    /** Per-credential probe timeout (ms). Defaults to the configured usage request timeout. */
+    timeoutMs?: number;
+    /** Provider → base URL override, same shape as {@link AuthStorage.fetchUsageReports}. */
+    baseUrlResolver?: (provider: Provider) => string | undefined;
+}
 /**
  * Sentinel value placed in OAuth `refresh` fields when a credential is shared
  * via {@link AuthStorage.exportSnapshot}. Refresh tokens never leave the broker;
@@ -252,6 +291,10 @@ type AuthApiKeyOptions = {
      */
     signal?: AbortSignal;
 };
+export interface InvalidateCredentialMatchingOptions {
+    signal?: AbortSignal;
+    sessionId?: string;
+}
 /**
  * Credential storage backed by an AuthCredentialStore.
  * Reads from storage on reload(), manages round-robin credential selection,
@@ -401,6 +444,27 @@ export declare class AuthStorage {
         /** Caller's cancel signal; only rejects this caller, never the shared upstream fetch. */
         signal?: AbortSignal;
     }): Promise<UsageReport[] | null>;
+    /**
+     * Probe each stored credential against its provider's auth-verifying usage
+     * endpoint and report per-credential auth health.
+     *
+     * Surfaces the identity of failing credentials so callers running a
+     * multi-account pool (e.g. a broker-backed auth-gateway) can tell which
+     * row is producing 401s. The probe mirrors the per-credential fan-out
+     * inside {@link AuthStorage.fetchUsageReports} (OAuth refresh-on-expiry,
+     * then `UsageProvider.fetchUsage`) but does NOT swallow errors — every
+     * credential gets either `ok: true`, `ok: false` with `reason`, or
+     * `ok: null` when no probe is configured for the provider.
+     *
+     * Iterates sequentially to avoid synchronized N-account fan-out that
+     * upstream `/usage` rate limiters (per source IP) treat as a burst.
+     *
+     * Only inspects active rows from {@link AuthCredentialStore.listAuthCredentials};
+     * soft-disabled rows are already known-bad and don't need a network probe.
+     * Environment-variable API keys are not enumerated — the caller's intent
+     * here is "which of my stored credentials is broken".
+     */
+    checkCredentials(options?: CheckCredentialsOptions): Promise<CredentialHealthResult[]>;
     /**
      * Marks the current session's credential as temporarily blocked due to usage limits.
      * Uses usage reports to determine accurate reset time when available.
@@ -429,6 +493,7 @@ export declare class AuthStorage {
      * 6. Fallback resolver (models.yml custom providers, last-resort)
      */
     getApiKey(provider: string, sessionId?: string, options?: AuthApiKeyOptions): Promise<string | undefined>;
+    invalidateCredentialMatching(provider: string, apiKey: string, options?: InvalidateCredentialMatchingOptions): Promise<boolean>;
     invalidateCredentialMatching(provider: string, apiKey: string, signal?: AbortSignal): Promise<boolean>;
     /**
      * Build a redacted snapshot of all loaded credentials for the auth-broker

package/dist/types/providers/openai-responses-shared.d.ts

@@ -12,6 +12,30 @@ export declare function normalizeResponsesToolCallIdForTransform(id: string, mod
 export declare function collectKnownCallIds(messages: ResponseInput): Set<string>;
 /** Scan replay items for call_ids that were originally custom tool calls. */
 export declare function collectCustomCallIds(messages: ResponseInput): Set<string>;
+/**
+ * Convert orphan `function_call_output` / `custom_tool_call_output` items —
+ * those whose `call_id` has no matching preceding `function_call` /
+ * `custom_tool_call` in the same input — into assistant text notes.
+ *
+ * The Responses API rejects unpaired outputs with
+ * `400 No tool call found for function call output with call_id …`. Orphans
+ * sneak in through two paths today:
+ *
+ * - A previous turn's `providerPayload` snapshot replaces the input array via
+ *   the `dt: false` splice (see {@link convertConversationMessages}), wiping
+ *   the matching `function_call` while leaving the matching
+ *   `function_call_output` queued in a later `toolResult`.
+ * - A locally-rejected tool call (argument-validation failure, hook reject,
+ *   aborted turn before the call streamed) produces a tool result without a
+ *   `function_call` ever landing in any persisted provider payload.
+ *
+ * Dropping the result loses information the model needs to recover; sending
+ * it as-is 400s the request. Folding it into an assistant `message` preserves
+ * the payload (call_id + truncated output) while staying within the Responses
+ * input grammar. Matches the behavior of {@link transformRequestBody} in the
+ * codex provider — issue #1351 / regression of #472.
+ */
+export declare function repairOrphanResponsesToolOutputs(input: ResponseInput): ResponseInput;
 export declare function convertResponsesInputContent(content: string | Array<TextContent | ImageContent>, supportsImages: boolean): ResponseInputContent[] | undefined;
 export declare function convertResponsesAssistantMessage<TApi extends Api>(assistantMsg: AssistantMessage, model: Model<TApi>, msgIndex: number, knownCallIds: Set<string>, includeThinkingSignatures?: boolean, customCallIds?: Set<string>): ResponseInput;
 export declare function appendResponsesToolResultMessages<TApi extends Api>(messages: ResponseInput, toolResult: ToolResultMessage, model: Model<TApi>, strictResponsesPairing: boolean, knownCallIds: ReadonlySet<string>, customCallIds?: ReadonlySet<string>): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-ai",
-	"version": "15.3.1",
+	"version": "15.3.2",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@oh-my-pi/pi-utils": "15.3.1",
+		"@oh-my-pi/pi-utils": "15.3.2",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/auth-broker/client.ts

@@ -5,6 +5,7 @@
  * `omp auth-broker status` (liveness checks). All endpoints except
  * `/v1/healthz` require a bearer token.
  */
+import { readSseEvents } from "@oh-my-pi/pi-utils";
 import type { ZodType, infer as zInfer } from "zod/v4";
 import type { AuthCredential } from "../auth-storage";
 import type {
@@ -15,6 +16,7 @@ import type {
 	CredentialUploadResponse,
 	HealthzResponse,
 	SnapshotResponse,
+	SnapshotStreamEvent,
 	UsageResponse,
 } from "./types";
 import {
@@ -23,6 +25,7 @@ import {
 	credentialUploadResponseSchema,
 	healthzResponseSchema,
 	snapshotResponseSchema,
+	snapshotStreamEventSchema,
 	usageResponseSchema,
 } from "./wire-schemas";
 
@@ -50,6 +53,18 @@ export class AuthBrokerError extends Error {
 	}
 }
 
+/**
+ * Thrown when a broker responds 404 to `GET /v1/snapshot/stream` — old
+ * brokers that predate the SSE endpoint. Callers (`RemoteAuthCredentialStore`)
+ * detect this sentinel to fall back to long-polling permanently.
+ */
+export class AuthBrokerStreamUnsupportedError extends AuthBrokerError {
+	constructor(message = "Auth broker does not support /v1/snapshot/stream") {
+		super(message, { status: 404 });
+		this.name = "AuthBrokerStreamUnsupportedError";
+	}
+}
+
 export interface FetchSnapshotOptions {
 	ifGenerationGt?: number;
 	waitMs?: number;
@@ -128,6 +143,88 @@ export class AuthBrokerClient {
 		return { status: 200, snapshot, generation: etagGeneration ?? snapshot.generation };
 	}
 
+	/**
+	 * Subscribe to the broker's SSE snapshot stream. The first frame is always
+	 * a full `snapshot`; subsequent frames are `entry` upserts / refreshes or
+	 * `removed` deletes. Caller controls lifecycle via `opts.signal`.
+	 *
+	 * Throws {@link AuthBrokerStreamUnsupportedError} when the broker responds
+	 * 404 — older brokers predate this endpoint and the caller should fall back
+	 * to long-polling for the remainder of its lifetime.
+	 */
+	async *openSnapshotStream(opts: { signal?: AbortSignal } = {}): AsyncGenerator<SnapshotStreamEvent> {
+		const url = `${this.#baseUrl}/v1/snapshot/stream`;
+		const headers: Record<string, string> = {
+			Accept: "text/event-stream",
+			Authorization: `Bearer ${this.#token}`,
+		};
+		if (opts.signal?.aborted) {
+			throw new AuthBrokerError("Auth broker request aborted", { cause: opts.signal.reason });
+		}
+		// No timeout: this connection is intentionally long-lived. Caller's signal
+		// is the only cancel path.
+		const response = await this.#fetch(url, { method: "GET", headers, signal: opts.signal });
+		if (response.status === 404) {
+			// Drain the body so the socket can be reused; tiny payload.
+			await response.text().catch(() => {});
+			throw new AuthBrokerStreamUnsupportedError();
+		}
+		if (!response.ok) {
+			const text = await response.text().catch(() => "");
+			throw new AuthBrokerError(`Auth broker stream failed: ${response.status} ${response.statusText}`, {
+				status: response.status,
+				body: text,
+			});
+		}
+		if (!response.body) {
+			throw new AuthBrokerError("Auth broker stream response had no body", { status: response.status });
+		}
+		const contentType = response.headers.get("content-type")?.toLowerCase();
+		if (contentType?.split(";", 1)[0].trim() !== "text/event-stream") {
+			await response.body.cancel().catch(() => {});
+			throw new AuthBrokerError("Auth broker stream returned non-SSE response", {
+				status: response.status,
+				body: contentType ?? "",
+			});
+		}
+
+		let sawFirstEvent = false;
+		for await (const sse of readSseEvents(response.body, opts.signal)) {
+			if (sse.event === null && sse.data === "") continue; // keepalive comment frames
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(sse.data);
+			} catch (err) {
+				throw new AuthBrokerError("Auth broker stream returned malformed JSON", {
+					body: sse.data,
+					cause: err,
+				});
+			}
+			const validated = snapshotStreamEventSchema.safeParse(parsed);
+			if (!validated.success) {
+				throw new AuthBrokerError("Auth broker stream event failed schema validation", {
+					body: validated.error.message,
+				});
+			}
+			const event = validated.data;
+			if (!sawFirstEvent) {
+				sawFirstEvent = true;
+				if (event.kind !== "snapshot") {
+					throw new AuthBrokerError("Auth broker stream did not start with snapshot", { body: sse.data });
+				}
+			}
+			yield event;
+		}
+		if (!opts.signal?.aborted) {
+			throw new AuthBrokerError(
+				sawFirstEvent
+					? "Auth broker stream ended unexpectedly"
+					: "Auth broker stream ended before initial snapshot",
+				{ status: response.status },
+			);
+		}
+	}
+
 	fetchUsage(signal?: AbortSignal): Promise<UsageResponse> {
 		// Validates the envelope (`generatedAt`, `reports[].provider`, `limits`,
 		// `metadata`) but leaves provider-specific extension fields permissive so