@gajae-code/ai 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -2,8 +2,69 @@
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-08-17
+- Cursor native tool calls (shell/read/write/… oneof variants) now convert their protobuf payloads into plain JSON-safe data before attaching them as toolCall `arguments`: `$typeName` markers are stripped, safe-range bigints become numbers (decimal strings beyond `Number.MAX_SAFE_INTEGER`), byte arrays become base64 strings, and cycles/functions collapse to null. Raw protobuf-es payloads carry `bigint` fields (`fileSize`, `durationMs`, `fileOutputThresholdBytes`, …) that defeat `JSON.stringify`, which broke managed snapshot staging, JSONL transcript persistence, and provider replay — the issue #4578 local-snapshot producer defect class fixed at its producer boundary.
+- Generic OpenAI-compatible `/v1/models` discovery now reads served context-window and output-limit metadata instead of defaulting every dynamically listed model to the unknown-window sentinel. `max_model_len` (vLLM/SGLang/oMLX), `context_length`, `context_window`, `max_context_length` (LM Studio), and `max_position_embeddings` populate `contextWindow` in that precedence order, while `max_tokens`/`max_output_tokens` populate `maxTokens`; total-window fields never leak into the output-token ceiling. Malformed values (non-finite, zero, negative, non-numeric) are rejected per-field with fallback to the next candidate, so a `1e400`-style catalog entry can no longer poison compaction thresholds or compact-input budgets.
+- Codex websocket requests now abort and close their transport when the downstream event-stream consumer returns early (including managed provisional-buffer rejection), so the next turn opens a clean connection instead of inheriting `websocket request already in progress` (#4534).
+- Refreshed the bundled ZAI catalog with GLM-5.3 and made it the provider's default model.
+- Added the typed `local_snapshot_failure` and `local_buffer_overflow` assistant error kinds so downstream retry policy can distinguish local event-snapshot and staging-buffer failures from provider failures.
+- Anthropic first-event timeouts now report safe elapsed time, serialized request bytes, canonical-vs-custom endpoint class, and the `PI_STREAM_FIRST_EVENT_TIMEOUT_MS` override without exposing URL credentials, query tokens, or body content. Large requests through custom endpoints receive one bounded two-minute observation grace so a slightly later proxy 529 can surface without extending explicit-zero, small-request, or canonical deadlines; full-window multi-megabyte requests are never automatically re-uploaded and small requests get at most one session replay. Credit: @probepark (#4464).
+- A ceiling-bound Anthropic upload that fails before stream iteration begins (for example an immediate 529 surfacing from response setup) now carries the one-attempt upload ceiling to the outer provider retry loop as well. Previously only the SDK's internal retries were suppressed for these requests, so the multi-megabyte body could still be re-uploaded up to the default `streamMaxRetries` budget. The delayed-setup grace test was also rescaled from a 1ms window/5ms setup pair — which made the grace-boundary outcome a coin flip on runner scheduling latency — to a regime where the contract is decidable, with a new complementary test proving an in-window 529 after delayed setup keeps its ordinary retry budget. Credit: @probepark (#4464).
+- Unknown Anthropic stream rejections are normalized to a mutable `Error` before retry facts are stamped. An injected custom client rejecting `withResponse()` with a primitive string previously had its facts assigned onto a temporary boxed value — silently discarding them — so a ceiling-bound multi-megabyte upload slipped past the one-attempt ceiling and a string-matched corrective branch (CPA tool-alias restore) re-uploaded the body. Credit: @probepark (#4464).
+- Defense-in-depth: a completed Anthropic stream whose assembled assistant content carries directly adjacent `thinking`/`redacted_thinking` blocks now emits a bounded diagnostic per stream invocation naming only the envelope shape (block count, adjacency presence, model, provider), never raw thinking text, signatures, or redacted payloads. The send-boundary collapse remains the wire source of truth; this is a read-only observation that helps surface upstream producers of the rejected shape (#4443).
+
+- The adjacent-thinking-block collapse now treats `thinking` and `redacted_thinking` as one adjacency class at the final Anthropic send boundary, matching the maintainer-approved send-time invariant (#4425). The earlier replay-phase collapse (#4418) and its test asserted that a `redacted_thinking` block following a `thinking` block survived; the final send-boundary pass (#4425) correctly collapses that pair, and the replay-phase test and doc comment are reconciled to that authoritative behavior (#4382).
+- Assistant turns that carry two directly adjacent `thinking` blocks are now collapsed to the first block before replay on `anthropic-messages`. Anthropic rejects that shape 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, and because the offending message keeps its index as the transcript grows, one such turn made every later request in the session fail - observed on two live sessions stuck for 9+ hours, each turn spending two rejected ~1.5 MB uploads, with the cited index frozen (`messages.5.content.118`) while the history grew from 103 to 430 messages. Verified against the captured transcript: the unmodified 430-message replay returns 400 and the collapsed replay returns 200. Thinking blocks separated by a `tool_use` are ordinary interleaved-thinking shape and are preserved, and a `redacted_thinking` blob following a thinking block is untouched (#4416).
+- Dev CI now runs each AI test file in a fresh process instead of sharing one Bun test runtime across the package. This prevents leaked fetch spies, fake timers, environment overrides, auth-broker state, and module caches from contaminating later files while using the same bounded, root-preloaded harness as coding-agent shards (#4378).
+- The deterministic Anthropic cache-eval fixture moved from the untracked root `artifacts/` directory to `packages/ai/test/fixtures/issue-3670-anthropic-cache-eval.json` where test fixtures belong. The integration test import path is updated accordingly (#4420).
+- Anthropic thinking-replay repair now fingerprints the exact serialized outbound body before any application-level resend. A no-op latest-assistant transform is skipped in favor of a safe all-assistant transform, and if neither changes the body the turn fails without uploading the same large request again. The rejected request, transform disposition, hashes, sizes, and cited `messages.N.content.M` mismatch are recorded through the existing redacted HTTP-400 capture and warn path; thinking mode and the `context-management-2025-06-27` beta remain unchanged (#4382).
+- Anthropic 400 errors that name a `clear_thinking_*` context-management strategy now explain when GJC's captured outgoing body contains neither `thinking` nor `context_management`: an intermediary at the redacted configured base URL likely injected the strategy. The diagnostic recommends explicitly enabling thinking or fixing/replacing the intermediary, never silently enables thinking or retries, and annotates the sanitized raw-request capture without changing its body. Credit: @probepark (#4380).
+- Anthropic streams now repair the CPA Claude-OAuth "cannot restore tool alias" 500 instead of blindly resending the unchanged request: the exact SSE signature is classified, the base tool name is extracted, and the request is corrected exactly once with steering that names the unique callable tool (or directs tool discovery when no unique match exists). Recurrence surfaces an actionable terminal error with no transport facts, so neither the provider generic 5xx retry nor the managed fallback controller re-sends; managed attempts record the steering against the same turn and the next attempt applies it (#4338).
+- Tool calls whose raw argument JSON spells a printable non-ASCII character as a `\uXXXX` escape instead of literal UTF-8 are now flagged with `ToolCall.escapedNonAsciiArguments`. Such a payload parses cleanly but is unverifiable — one mistyped hex digit decodes to a different, equally valid character — so the agent loop rejects it instead of executing silently corrupted text. Required control escapes and lone surrogates never trip the flag, and `\\uXXXX` (the source syntax of code being written) is not an escape and is ignored. New `findUnnecessaryUnicodeEscape` helper in `utils/json-parse`. The Kimi tool-call healer samples the signal from the raw leaked payload before its normalizing JSON round-trip, which would otherwise decode the escapes and erase the evidence.
+- Persist learned tool-choice incapabilities in a bounded, expiring, digest-keyed cache so fresh processes avoid repeating known-invalid forced-choice probes while retaining automatic revalidation and existing first-discovery fallback behavior. Credit: @probepark (#4319).
+
+### Added
+- Added first-class support for oMLX (Apple Silicon MLX local inference server), including automatic discovery at `http://127.0.0.1:8080/v1`, `OMLX_BASE_URL`, and `OMLX_API_KEY`.
+
+- Added first-class direct xAI `grok-4.6` catalog support over the existing xAI OAuth/subscription transport. Grok 4.5 now exposes exactly `low` through `high` reasoning effort, Grok 4.6 exposes exactly `low` through `xhigh`, and both serialize the selected level through `reasoning_effort`.
+- `AuthStorage.switchSessionCredential(provider, sessionId, selector)` forces a running session's OAuth credential for a provider to a specific stored row, independent of quota/rate-limit state — backing the coding-agent `/credential` slash command for a manual mid-session account switch (as opposed to the existing automatic quota-triggered fallback). Mutates only the session-scoped sticky pointer keyed by `sessionId` (never a provider-wide runtime override), so it cannot bleed into other sessions with a different credential identity; subagents/team workers inherit the parent's credential identity by design and switch with it. Fails closed when a stronger override already re-decides the provider's credential every call (`--credential` hard pin, `--api-key` runtime override, or a config-sourced `models.yml` `apiKey`), and deliberately leaves credential-blocked state untouched so a switch to a still-backoff-blocked row safely falls back to a usable account instead of drawing another 429/quota error.
+
+- Added the authoritative OpenRouter `meta/muse-spark-1.2` catalog fallback with a 1,048,576-token context window and `minimal` through `xhigh` reasoning effort, so stale or credential-limited catalog generation still closes the Muse Spark preset alias deterministically.
+- `AuthStorage` supports a soft, per-provider preferred OAuth credential (`setRuntimePreferredCredentialSelector` / `hasRuntimePreferredCredentialSelector` / `removeRuntimePreferredCredentialSelector`, plus `AuthApiKeyOptions.preferredCredentialSelector`) that backs the coding-agent `--prefer-credential` CLI flag. A usable preferred row is placed ahead of the provider's normal balanced/earliest-reset ranking; a content-free quota or rate-limit failure marks it blocked and rotates to another active credential immediately, same as the existing session-stickiness fallback. It is mutually exclusive with the existing hard `setRuntimeCredentialSelector` pin (`--credential`) for the same provider, and `resolveRuntimePreferredCredentialSelectorProvider` resolves an unqualified selector to its single matching active OAuth provider or fails closed on ambiguity.
+
+### Changed
+
+- Documented multi-account auth behavior: credential ranking (`balanced` or `earliest-reset`) runs at session start or after a blocked preferred account, explicit OAuth checks run sequentially, and API-key sources remain visible/checkable without entering OAuth pooling, pinning, or removal.
+
+- Model discovery now retains the authoritative dynamic provider model IDs separately from the merged static/cache catalog. Consumers can distinguish a fresh provider omission from bundled offline availability through `ModelResolutionResult.dynamicModelIds`; cache schema v5 persists those IDs through fresh-cache reuse and static transport re-merges, scoped to the credential-and-endpoint provenance that produced them.
+
+### Fixed
+
+- Grok Build `/usage` now uses the weekly credits quota when the monthly billing endpoint reports a zero limit, avoiding misleading `100% free` and `used/0` output.
+- A deterministic Anthropic thinking-replay rejection now converges under a managed fallback attempt instead of repeating forever (#4262). Every coding-agent turn prompts with `fallbackManaged: true`, and the whole in-provider thinking-replay repair sits behind `!options?.fallbackManaged` because the fallback controller owns retries — the shipping CLI therefore never repaired anything: each turn rebuilt the same replay from the same history, drew the same 400, and the session burned one rejected request per turn without ever self-healing (reported as ~1 rejected 1.3 MB request every 12s, ~300/h, never converging). The provider still does not retry inside a managed attempt — it records the full-history repair escalation on the provider session state instead, so the next managed attempt builds a repaired replay at the cost of zero extra round trips. Only the two deterministic rejections (`blocks ... cannot be modified`, ``Invalid `signature` in `thinking` block``) qualify; the proxy-masked generic `api_error` names no cause and may be a transient blip, so it still never costs the session its native replay.
+- A long-lived process now recovers when the OAuth row it holds in memory is soft-disabled or replaced in the shared store by a peer (`invalid_grant` disable, credential removal, or a re-login that inserts a new row). The refresh lease answers `missing` for a row that is no longer active, which surfaced as `OAuth refresh credential disappeared` — an error the failure classifier reads as transient, so the vanished row was temp-blocked and retried for the life of the process while a valid re-login row sat unused in the store. Resumed sessions therefore failed every request with the misleading `No credentials found for <provider>` until the CLI was restarted, even though `gjc` had just been logged back in (observed as a per-request refresh-failure flood against `anthropic`). `#tryOAuthCredential` now detects that the attempted row is gone from the store, reloads the snapshot, and re-resolves within the existing reload budget, alongside the peer-rotation recovery it already performed.
+- OpenAI Responses streams now preserve canonical terminal function-call arguments when compatible relays such as llama.cpp emit an empty placeholder in `response.output_item.added`. Tool-call correlation also accepts llama.cpp’s `call_id`-only event shape, while conflicting streamed/terminal arguments, malformed terminal JSON, and terminal payloads that decode to something other than a JSON object fail closed instead of reaching execution. Argument source precedence is terminal item, then streamed deltas, then the `output_item.added` snapshot, so a relay that only ever populates the added snapshot keeps its real payload.
+
+- Added bundled Gemini 3.7 Flash next to every existing Gemini 3.6 Flash catalog selector (`google`, `google-gemini-cli`, `github-copilot`, `google-antigravity` effort variants, `opencode-zen`, `openrouter`, `vercel-ai-gateway`, `cursor`, `kilo`, `venice`). Gemini 3.7 Flash accepts only `low`, `medium`, and `high` thinking levels; `minimal` is rejected because the official API returns an error, so the Cursor `-minimal` suffix is not cloned.
+
+## [0.13.3] - 2026-08-15
+
+### Added
+
+- Added first-class direct xAI `grok-4.6` catalog support over the existing xAI OAuth/subscription transport. Grok 4.5 exposes `low` through `high` reasoning effort and Grok 4.6 exposes `low` through `xhigh`.
+- Added a native TypeScript Kiro (Amazon Q Developer / CodeWhisperer) provider: AWS SSO OIDC device-code login, bearer-token transport to the CodeWhisperer streaming endpoint over `application/vnd.amazon.eventstream`, and a `kiro` model-manager descriptor for Claude 3.7 Sonnet (#4304).
+- Added the authoritative OpenRouter `meta/muse-spark-1.2` catalog fallback with a 1,048,576-token context window and `minimal` through `xhigh` reasoning effort, so stale or credential-limited catalog generation still closes the Muse Spark preset alias deterministically.
+
+### Fixed
+- Validate Synthetic API key via models endpoint, not retired Kimi probe (#4385).
+- Tool-call arguments that spell printable non-ASCII text as `\uXXXX` escapes are now flagged on the raw wire (`escapedNonAsciiArguments`) by the Anthropic, OpenAI Responses, and OpenAI Completions streams — after JSON decode the defect is unobservable, and a mistyped hex nibble silently becomes a different character (#4515).
+
 ## [0.13.2] - 2026-08-13
 
+### Fixed
+
+- `clear_thinking`-emptied Anthropic thinking blocks now drop stale signatures before replay, preventing the next request from failing with `Invalid signature in thinking block` after a provider-side reasoning clear (#4247, reported by @probepark).
+
 ## [0.13.1] - 2026-08-11
 
 ### Fixed
@@ -64,7 +125,6 @@
 
 ### Fixed
 
-
 - `todo_write` raw argument rejections now carry bounded, authority-controlled correction codes for each rejected shape: unknown root keys, unknown operation-entry keys, done/drop entries missing a task or phase target, and unknown init list-entry keys. Each code maps to a fixed correction message naming the accepted shape (never echoing the offending input), so invalid calls surface specific guidance while valid payloads keep the existing passthrough/coercion path (#3916).
 - Anthropic Sonnet 5 now exposes Anthropic's real `xhigh` and `max` thinking efforts on the Messages API (`minimal`/`low`/`medium`/`high`/`xhigh`/`max`), matching official support. The previous generic `kind === opus` gate excluded it from the full preset range; the capability predicate is now an explicit version-scoped list (Opus 4.7+, Sonnet 5+), so older Sonnet generations and Bedrock Converse routes stay fail-closed at their previously advertised levels (issue #3913).
 - Alibaba Token Plan now exposes Qwen 3.8 Max under the provider-supported `qwen3.8-max` wire id instead of the rejected `qwen-3.8-max` spelling; catalog regeneration canonicalizes a legacy discovered alias rather than retaining a broken duplicate (#3909).
@@ -129,7 +189,6 @@
 
 - Reproducible Alibaba Token Plan header-parity A/B latency benchmark (`packages/ai/scripts/alibaba-token-plan-latency-ab.ts`): a fixed-seed interleaved A/B comparison of legacy vs Qwen-identical headers against a deterministic local HTTP server, reporting n/success/error/timeout and TTFT/total latency median/p90/p95/mean/stddev. No live credentials are required; a public-safe blocked-live-data receipt is included (`packages/ai/test/fixtures/alibaba-token-plan-latency-blocked-receipt.md`) (#3557).
 
-
 ## [0.12.4] - 2026-07-30
 
 ### Fixed

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

@@ -1,5 +1,5 @@
 import type { AuthCredential } from "../auth-storage";
-import type { CredentialDisableResponse, CredentialIfAbsentUploadResponse, CredentialRefreshRequest, CredentialRefreshResponse, CredentialUploadResponse, HealthzResponse, SnapshotResponse, SnapshotStreamEvent, UsageResponse } from "./types";
+import type { CredentialDisableResponse, CredentialIfAbsentUploadResponse, CredentialMetadataResponse, CredentialRefreshRequest, 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;
@@ -29,6 +29,10 @@ export declare class AuthBrokerError extends Error {
 export declare class AuthBrokerStreamUnsupportedError extends AuthBrokerError {
     constructor(message?: string);
 }
+/** Thrown when a broker responds 404 to `GET /v1/credentials/metadata`. */
+export declare class AuthBrokerCredentialMetadataUnsupportedError extends AuthBrokerError {
+    constructor(message?: string);
+}
 export interface FetchSnapshotOptions {
     ifGenerationGt?: number;
     waitMs?: number;
@@ -45,8 +49,12 @@ export type FetchSnapshotResult = {
 export declare class AuthBrokerClient {
     #private;
     constructor(opts: AuthBrokerClientOptions);
+    /** Normalized broker origin used for non-secret local presentation partitioning. */
+    get baseUrl(): string;
     healthz(signal?: AbortSignal): Promise<HealthzResponse>;
     fetchSnapshot(opts?: FetchSnapshotOptions): Promise<FetchSnapshotResult>;
+    /** Fetches the generation-aware, secret-free credential inventory projection. */
+    fetchCredentialMetadata(signal?: AbortSignal): Promise<CredentialMetadataResponse>;
     /**
      * Subscribe to the broker's SSE snapshot stream. The first frame is always
      * a full `snapshot`; subsequent frames are `entry` upserts / refreshes or

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

@@ -0,0 +1,7 @@
+/**
+ * Keep provider and upstream failure text safe for less-trusted surfaces.
+ *
+ * This intentionally mirrors the bounded reason scrubber used by the account
+ * management CLI without taking a dependency on coding-agent.
+ */
+export declare function cleanReason(value: unknown): string | undefined;

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

@@ -1,9 +1,30 @@
-import { type AuthCredential, type AuthCredentialIfAbsentResult, type AuthCredentialStore, type MCPOAuthRefreshClient, type OAuthCredential, type StoredAuthCredential } from "../auth-storage";
+/**
+ * Client-side {@link AuthCredentialStore} that mirrors a remote broker's
+ * snapshot. Refresh tokens never leave the broker; mutating methods (`replace*`,
+ * `upsert*`, `delete*ForProvider`) throw because login flows are server-side.
+ *
+ * Cache (`getCache`/`setCache`/`cleanExpiredCache`) is in-memory and ephemeral —
+ * usage reports cache TTL is 5 minutes per credential, so durability across
+ * runs isn't required.
+ */
+import { type AuthCredential, type AuthCredentialIfAbsentResult, type AuthCredentialStore, type CachedCredentialHealth, type CachedUsagePresentation, type CredentialInventoryRecord, type MCPOAuthRefreshClient, type OAuthCredential, type SafeUsageReport, type StoredAuthCredential } from "../auth-storage";
 import type { Provider } from "../types";
 import type { UsageReport } from "../usage";
 import type { OAuthCredentials } from "../utils/oauth/types";
 import { type AuthBrokerClient } from "./client";
 import type { SnapshotResponse } from "./types";
+export type CredentialInventoryMetadataCapability = "pending" | "supported" | "unsupported" | "mismatch" | "failed";
+export interface CachedInventoryNotice {
+    status: Exclude<CredentialInventoryMetadataCapability, "supported">;
+    reason: string;
+    generation?: number;
+}
+export interface CredentialInventoryMetadataState {
+    capability: CredentialInventoryMetadataCapability;
+    generation: number;
+    records: readonly CredentialInventoryRecord[];
+    notice?: CachedInventoryNotice;
+}
 export interface RemoteAuthCredentialStoreOptions {
     client: AuthBrokerClient;
     /**
@@ -16,12 +37,26 @@ export interface RemoteAuthCredentialStoreOptions {
      * to long-poll permanently when the broker returns 404. Default `true`.
      */
     streamSnapshots?: boolean;
+    /** Override the local redacted presentation sidecar path (primarily for tests). */
+    presentationPath?: string;
 }
 export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     #private;
     constructor(opts: RemoteAuthCredentialStoreOptions);
     get client(): AuthBrokerClient;
+    /** Wait for redacted presentation hydration and initial inventory metadata. */
+    waitForReady(): Promise<void>;
+    /** Await pending atomic sidecar writes (useful to bounded shutdown callers). */
+    flushPresentationPersistence(): Promise<void>;
     get snapshot(): SnapshotResponse;
+    getInventoryMetadataState(): Readonly<CredentialInventoryMetadataState>;
+    syncInventoryMetadata(): Promise<Readonly<CredentialInventoryMetadataState>>;
+    /**
+     * Payload-free inventory view. This method never performs network I/O; metadata
+     * rows appear only after an explicit or background metadata synchronization for
+     * the current snapshot generation.
+     */
+    listCredentialInventory(provider?: string): CredentialInventoryRecord[];
     /** Re-hydrate the in-memory snapshot from the broker. */
     refreshSnapshot(): Promise<SnapshotResponse>;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
@@ -31,8 +66,8 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * authoritative row, so we just mirror it.
      */
     updateAuthCredential(id: number, credential: AuthCredential): void;
-    deleteAuthCredential(id: number, disabledCause: string): void;
-    tryDisableAuthCredentialIfMatches(id: number, _expectedData: string, disabledCause: string): boolean;
+    deleteAuthCredential(_id: number, _disabledCause: string): void;
+    tryDisableAuthCredentialIfMatches(_id: number, _expectedData: string, _disabledCause: string): boolean;
     waitForFreshSnapshot(maxWaitMs: number, opts?: {
         signal?: AbortSignal;
     }): Promise<boolean>;
@@ -46,6 +81,8 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
     upsertAuthCredentialForProvider(_provider: string, _credential: AuthCredential): StoredAuthCredential[];
     upsertAuthCredentialForProviderIfAbsent(_provider: string, _credential: AuthCredential): AuthCredentialIfAbsentResult;
     deleteAuthCredentialsForProvider(_provider: string, _disabledCause: string): void;
+    /** Logout authority remains on the broker; the client only mirrors its result. */
+    deleteAuthCredentialsRemote(provider: string, disabledCause: string): Promise<void>;
     /**
      * Upsert a single credential through the broker. The broker server is the
      * canonical writer — see `POST /v1/credential`. The redacted snapshot
@@ -61,12 +98,6 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * key clobbers any previously stored key for the same provider.
      */
     replaceAuthCredentialsRemote(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
-    /**
-     * Logout: disable every active credential for the provider on the broker,
-     * then drop them from the local snapshot. Refresh fetches the authoritative
-     * post-state in the background.
-     */
-    deleteAuthCredentialsRemote(provider: string, disabledCause: string): Promise<void>;
     getCache(key: string): string | null;
     setCache(key: string, value: string, expiresAtSec: number): void;
     cleanExpiredCache(): void;
@@ -86,6 +117,16 @@ export declare class RemoteAuthCredentialStore implements AuthCredentialStore {
      * residential laptop is, so all credentials surface every cycle.
      */
     fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /** Synchronous, zero-network usage presentation read. */
+    peekCachedUsagePresentation(provider: Provider, credentialId: number): CachedUsagePresentation | undefined;
+    /** Synchronous, zero-network health presentation read backed by the redacted sidecar. */
+    peekCachedCredentialHealth(provider: Provider, credentialId: number): CachedCredentialHealth | undefined;
+    /** Persist a safe health result without credential or bearer-token material. */
+    recordCredentialHealth(provider: Provider, credentialId: number, health: CachedCredentialHealth): void;
+    /** Record a safe usage observation after an explicit broker usage/check call. */
+    recordUsagePresentation(observation: CachedUsagePresentation): void;
+    /** Persist an explicit usage/check report for the current credential identity. */
+    recordCredentialUsage(provider: Provider, credentialId: number, report: SafeUsageReport): void;
     /**
      * Per-credential usage hook consumed by `AuthStorage.#getUsageReport`. Pulls
      * the aggregate broker `/v1/usage` once and serves all callers from the

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

@@ -7,6 +7,20 @@
  */
 import type { AuthCredential, AuthCredentialIfAbsentReason, AuthCredentialSnapshot, AuthCredentialSnapshotEntry, MCPOAuthRefreshClient } from "../auth-storage";
 import type { UsageReport } from "../usage";
+/** A single credential metadata projection; secret-bearing fields are intentionally absent. */
+export interface CredentialMetadataRecord {
+    id: number;
+    provider: string;
+    type: "oauth" | "api_key";
+    identity: string | null;
+    disabledCause: string | null;
+}
+/** GET /v1/credentials/metadata response body. */
+export interface CredentialMetadataResponse {
+    generation: number;
+    generatedAt: number;
+    credentials: CredentialMetadataRecord[];
+}
 /** GET /v1/healthz response body. */
 export interface HealthzResponse {
     ok: boolean;

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

@@ -170,6 +170,31 @@ export declare const snapshotResponseSchema: z.ZodObject<{
         rotatesInMs: z.ZodNullable<z.ZodNumber>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** Closed redacted projection: no token, key, identity object, or extension fields. */
+export declare const credentialMetadataRecordSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    provider: z.ZodString;
+    type: z.ZodEnum<{
+        api_key: "api_key";
+        oauth: "oauth";
+    }>;
+    identity: z.ZodNullable<z.ZodString>;
+    disabledCause: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const credentialMetadataResponseSchema: z.ZodObject<{
+    generation: z.ZodNumber;
+    generatedAt: z.ZodNumber;
+    credentials: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        provider: z.ZodString;
+        type: z.ZodEnum<{
+            api_key: "api_key";
+            oauth: "oauth";
+        }>;
+        identity: z.ZodNullable<z.ZodString>;
+        disabledCause: z.ZodNullable<z.ZodString>;
+    }, 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;

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

@@ -59,6 +59,86 @@ export interface StoredAuthCredential {
     provider: string;
     credential: AuthCredential;
     disabledCause: string | null;
+    /** Monotonic local row revision used by optimistic hard-removal actions. */
+    revision?: number;
+}
+/**
+ * Payload-free inventory projection used by account-management and presentation
+ * surfaces. This deliberately has no credential/token fields; `listAuthCredentials`
+ * remains the active full-fidelity selection contract.
+ */
+export interface CredentialInventoryRecord {
+    id: number;
+    provider: string;
+    credentialKind: "oauth" | "api_key";
+    identityLabel: string | null;
+    accountId?: string;
+    email?: string;
+    projectId?: string;
+    disabled: boolean;
+    disabledCause: string | null;
+}
+/** Safe usage observation supplied by a remote store's presentation cache. */
+export interface CachedUsagePresentation {
+    credentialId: number;
+    provider: string;
+    inventoryGeneration: number;
+    identityDigest: string;
+    usage: SafeUsageReport;
+    fetchedAt: number;
+    freshUntil: number;
+    retainUntil: number;
+}
+/** Opaque local action target for an all-or-nothing OAuth hard removal. */
+export interface CredentialRemovalTarget {
+    id: number;
+    provider: string;
+    expectedRevision: number;
+}
+export type AuthCredentialHardRemovalResult = {
+    kind: "removed";
+    ids: readonly number[];
+} | {
+    kind: "conflict";
+    currentIds: readonly number[];
+};
+/** Usage report projection safe to cross a presentation boundary. */
+export type SafeUsageReport = Omit<UsageReport, "raw">;
+export type CachedUsageFreshness = "fresh" | "stale-last-good";
+export interface CachedUsageReport {
+    report: SafeUsageReport;
+    fetchedAt: number;
+    freshUntil: number;
+    retainUntil: number;
+    freshness: CachedUsageFreshness;
+}
+export type CachedCredentialHealthStatus = "ok" | "failed" | "unverifiable" | "unknown";
+export interface CachedCredentialHealth {
+    status: CachedCredentialHealthStatus;
+    reason: string | null;
+    checkedAt?: number;
+    retainUntil?: number;
+}
+/** Safe result from an explicit API-key probe whose key bytes are invocation-only. */
+export interface ApiKeyCredentialCheckResult {
+    provider: string;
+    type: "api_key";
+    ok: boolean | null;
+    reason?: string;
+    report?: SafeUsageReport;
+}
+/** Typed failure raised when an OAuth-only selector cannot be applied. */
+export type OAuthCredentialSelectorFailureReason = "api-key-row" | "api-key-provider" | "override-active" | "not-found" | "disabled" | "ambiguous" | "gateway-managed";
+export declare class OAuthCredentialSelectorError extends Error {
+    readonly reason: OAuthCredentialSelectorFailureReason;
+    readonly provider: string;
+    readonly selector: AuthCredentialSelector;
+    readonly candidateIds: readonly number[];
+    constructor(reason: OAuthCredentialSelectorFailureReason, provider: string, selector: AuthCredentialSelector, message: string, candidateIds?: readonly number[]);
+}
+export interface OAuthPinTarget {
+    credentialId: number;
+    canonicalSelector: AuthCredentialSelector;
 }
 /**
  * Per-credential health record returned by {@link AuthStorage.checkCredentials}.
@@ -89,16 +169,22 @@ export interface CredentialHealthResult {
     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">;
+    report?: SafeUsageReport;
 }
 export interface CheckCredentialsOptions {
     signal?: AbortSignal;
+    provider?: string;
     /** 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;
 }
+/** Options for the explicit, invocation-only API-key probe. */
+export interface ApiKeyCredentialCheckOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    baseUrl?: string;
+}
 /**
  * Sentinel value placed in OAuth `refresh` fields when a credential is shared
  * via {@link AuthStorage.exportSnapshot}. Refresh tokens never leave the broker;
@@ -170,6 +256,12 @@ export type OAuthRefreshLeaseClaim = {
 export interface AuthCredentialStore {
     close(): void;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
+    /** Payload-free account inventory; active and soft-disabled rows are included. */
+    listCredentialInventory?(provider?: string): CredentialInventoryRecord[];
+    /** Local opaque removal targets; remote stores may omit this capability. */
+    listCredentialRemovalTargets?(provider?: string): CredentialRemovalTarget[];
+    /** Transactional local hard removal; remote stores must reject this capability. */
+    removeAuthCredentialsHard?(provider: string, targets: readonly CredentialRemovalTarget[]): AuthCredentialHardRemovalResult;
     updateAuthCredential(id: number, credential: AuthCredential): void;
     deleteAuthCredential(id: number, disabledCause: string): void;
     tryDisableAuthCredentialIfMatches(id: number, expectedData: string, disabledCause: string): boolean;
@@ -228,6 +320,21 @@ export interface AuthCredentialStore {
      * `signal` propagates the agent's cancel down to the broker fetch.
      */
     fetchUsageReports?(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /** Synchronous, zero-network usage presentation peek. */
+    peekCachedUsagePresentation?(provider: Provider, credentialId: number): CachedUsagePresentation | undefined;
+    /** Record a safe usage observation after an explicit fetch/check. */
+    recordUsagePresentation?(observation: CachedUsagePresentation): void;
+    /** Read a safe, durable health observation for one credential row. */
+    peekCachedCredentialHealth?(provider: Provider, credentialId: number): CachedCredentialHealth | undefined;
+    /** Persist a safe health observation for one credential row. */
+    recordCredentialHealth?(provider: Provider, credentialId: number, health: CachedCredentialHealth): void;
+    /** Persist a safe usage observation without exposing credential payloads. */
+    recordCredentialUsage?(provider: Provider, credentialId: number, report: SafeUsageReport): void;
+    /**
+     * Optional readiness hook for stores that must hydrate payload-free metadata
+     * before one-shot inventory consumers read their first snapshot.
+     */
+    waitForReady?(): Promise<void>;
     /**
      * Optional store-supplied per-credential usage report lookup. When present,
      * `AuthStorage` consults this before its own per-credential upstream fetch
@@ -273,8 +380,8 @@ export interface AuthCredentialStore {
     replaceAuthCredentialsRemote?(provider: string, credentials: AuthCredential[]): Promise<StoredAuthCredential[]>;
     /**
      * Optional async write hook for clearing every credential for a provider
-     * (logout). When present, `AuthStorage.remove` routes through this instead
-     * of the sync `deleteAuthCredentialsForProvider`.
+     * (logout or a provider-wide invalidation). Remote stores must perform this
+     * through their authoritative broker rather than mutating the client cache.
      */
     deleteAuthCredentialsRemote?(provider: string, disabledCause: string): Promise<void>;
 }
@@ -373,6 +480,8 @@ type AuthApiKeyOptions = {
     signal?: AbortSignal;
     /** Pin selection to one stored credential instead of using round-robin/ranking. */
     credentialSelector?: AuthCredentialSelector;
+    /** Prefer one stored OAuth credential while preserving quota-triggered fallback. */
+    preferredCredentialSelector?: AuthCredentialSelector;
 };
 export type AuthCredentialSelectorKind = "id" | "email" | "account" | "project";
 export interface AuthCredentialSelector {
@@ -453,10 +562,52 @@ export declare class AuthStorage {
      * Used for CLI --credential.
      */
     setRuntimeCredentialSelector(provider: string, selector: AuthCredentialSelector): void;
+    /** Acquire a reference-counted credential scope for a session or shared subagent scope. */
+    acquireCredentialScope(scopeId: string): void;
+    /** Whether a credential scope already has at least one live owner. */
+    hasCredentialScopeLease(scopeId: string): boolean;
+    /** Release one credential-scope lease; final release clears only that scope's derived state. */
+    releaseCredentialScope(scopeId: string): void;
+    /** Set the selector derived from a durable session pin or a session seed. */
+    setSessionCredentialSelector(scopeId: string, provider: string, selector: AuthCredentialSelector): void;
+    /** Explicitly mask persistent/process-global selection and return the provider to AUTO for one scope. */
+    setSessionCredentialAuto(provider: string, scopeId: string): void;
+    /** Clear a scope's explicit selector and AUTO mask, restoring normal precedence. */
+    clearSessionCredentialSelector(provider: string, scopeId: string): void;
+    /** Whether the effective selection for a scope is explicitly pinned (AUTO masks are not pins). */
+    hasSessionCredentialSelector(provider: string, scopeId?: string): boolean;
+    /** Whether this scope explicitly masks provider pins and uses AUTO ranking. */
+    hasSessionCredentialAuto(provider: string, scopeId?: string): boolean;
+    /** Resolve the effective selector precedence for a provider/scope. */
+    resolveEffectiveCredentialSelector(provider: string, scopeId?: string, explicitSelector?: AuthCredentialSelector): AuthCredentialSelector | undefined;
+    /** Validate and canonicalize an OAuth-only selector for account pinning. */
+    resolveOAuthPinTarget(provider: string, selector: AuthCredentialSelector): OAuthPinTarget;
+    /** Return all local inventory rows, including soft-disabled metadata, without payloads. */
+    listCredentialInventory(provider?: string): CredentialInventoryRecord[];
+    /** Return local OAuth hard-removal action targets, including disabled rows. */
+    listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[];
+    /** Remove selected local OAuth rows atomically; conflict leaves all rows intact. */
+    removeAuthCredentialsHard(provider: string, targets: readonly CredentialRemovalTarget[]): AuthCredentialHardRemovalResult;
     /**
      * Remove a runtime credential selector.
      */
     removeRuntimeCredentialSelector(provider: string): void;
+    /** Whether a provider currently has a soft runtime credential preference. */
+    hasRuntimePreferredCredentialSelector(provider: string): boolean;
+    /** Resolve an unqualified preferred selector to the single active OAuth provider it matches. */
+    resolveRuntimePreferredCredentialSelectorProvider(selector: AuthCredentialSelector): string;
+    /**
+     * Prefer one stored OAuth credential for a provider while retaining quota
+     * fallback to the rest of the pool (not persisted to disk). Used for CLI
+     * `--prefer-credential`. Unlike {@link setRuntimeCredentialSelector}, a
+     * quota/rate-limit failure on the preferred row still rotates to another
+     * active credential instead of failing the session.
+     */
+    setRuntimePreferredCredentialSelector(provider: string, selector: AuthCredentialSelector): void;
+    /**
+     * Remove a runtime preferred credential selector.
+     */
+    removeRuntimePreferredCredentialSelector(provider: string): void;
     /**
      * Remove a runtime API key override.
      */
@@ -475,6 +626,8 @@ export declare class AuthStorage {
      * credential have to consult BOTH.
      */
     hasRuntimeCredentialSelector(provider: string): boolean;
+    /** Whether the effective selector for a session scope is pinned. */
+    hasEffectiveCredentialSelector(provider: string, sessionId?: string): boolean;
     /**
      * Opaque stored row id of the credential this session is currently using.
      *
@@ -488,6 +641,36 @@ export declare class AuthStorage {
      * resolver rather than a stored row.
      */
     getSessionCredentialRowId(provider: string, sessionId?: string): number | undefined;
+    /**
+     * Force a running session's OAuth credential for a provider to a specific
+     * stored row, independent of quota/rate-limit state. Used for a mid-session
+     * `/credential <selector>` switch that has nothing to do with exhaustion —
+     * the user just wants a different account for the rest of the session.
+     *
+     * This mutates ONLY the session-scoped sticky pointer
+     * ({@link AuthStorage.#recordSessionCredential}), never a provider-wide
+     * runtime override, so it cannot bleed into other sessions in the same
+     * process whose credential identity differs. The sticky pointer is keyed by
+     * `sessionId`, and subagents/team workers inherit their parent's
+     * `credentialSessionId` by design so they keep using the same account as
+     * the parent — a switch therefore applies to the whole session family
+     * sharing that identity, not to unrelated sessions.
+     *
+     * Fails closed rather than silently no-op when a stronger override already
+     * decides this provider's credential every call: a hard pin
+     * ({@link AuthStorage.setRuntimeCredentialSelector}, `--credential`), a
+     * runtime API-key override (`--api-key`), or a config-sourced API key
+     * (`models.yml` `apiKey`) would each re-decide the credential on the very
+     * next {@link AuthStorage.getApiKey} call and make this switch appear to
+     * silently do nothing.
+     *
+     * Deliberately does not touch credential-blocked state: if the target row
+     * is still backoff-blocked from a prior quota failure, the existing
+     * `#resolveOAuthSelection` ranking safely ignores this sticky pointer and
+     * falls back to a usable account instead of re-issuing a request that would
+     * just draw another 429/quota error.
+     */
+    switchSessionCredential(provider: string, sessionId: string, selector: AuthCredentialSelector): void;
     /**
      * Register a per-provider API key sourced from user configuration
      * (e.g. `models.yml` `providers.<name>.apiKey`). Higher priority than
@@ -540,7 +723,7 @@ export declare class AuthStorage {
      * Check if credentials exist for a provider in storage.
      */
     has(provider: string): boolean;
-    hasAuth(provider: string): boolean;
+    hasAuth(provider: string, sessionId?: string): boolean;
     /**
      * Credential type that a provider/session will dispatch first without performing I/O.
      * Mirrors getApiKey selector validation, overrides, session OAuth stickiness,
@@ -558,7 +741,7 @@ export declare class AuthStorage {
     /**
      * Get OAuth credentials for a provider.
      */
-    getOAuthCredential(provider: string): OAuthCredential | undefined;
+    getOAuthCredential(provider: string, sessionId?: string): OAuthCredential | undefined;
     /**
      * Get the OAuth `accountId` for a provider, preferring the credential that is
      * session-sticky for `sessionId` when multiple OAuth credentials are configured.
@@ -617,6 +800,14 @@ export declare class AuthStorage {
      * Environment-variable API keys are not enumerated — the caller's intent
      * here is "which of my stored credentials is broken".
      */
+    /** Return a safe cache-only usage observation. */
+    getCachedUsageReport(provider: Provider, credentialId: number, baseUrl?: string): CachedUsageReport | undefined;
+    /** Cache-only health observation; unknown means no retained explicit check. */
+    getCachedCredentialHealth(credentialId: number): CachedCredentialHealth;
+    peekCachedCredentialHealthForSource(provider: string, source: "env" | "config" | "runtime"): CachedCredentialHealth;
+    recordCredentialHealthForSource(provider: string, source: "env" | "config" | "runtime", health: CachedCredentialHealth): void;
+    /** Explicit API-key probe; key bytes are not retained in the returned result. */
+    checkApiKeyCredential(provider: Provider, apiKey: string, options?: ApiKeyCredentialCheckOptions): Promise<ApiKeyCredentialCheckResult>;
     checkCredentials(options?: CheckCredentialsOptions): Promise<CredentialHealthResult[]>;
     /**
      * Marks the current session's credential as temporarily blocked due to usage limits.
@@ -736,6 +927,9 @@ export declare class SqliteAuthCredentialStore implements AuthCredentialStore {
     constructor(db: Database);
     static open(dbPath?: string): Promise<SqliteAuthCredentialStore>;
     listAuthCredentials(provider?: string): StoredAuthCredential[];
+    listCredentialInventory(provider?: string): CredentialInventoryRecord[];
+    listCredentialRemovalTargets(provider?: string): CredentialRemovalTarget[];
+    removeAuthCredentialsHard(provider: string, targets: readonly CredentialRemovalTarget[]): AuthCredentialHardRemovalResult;
     claimOAuthRefreshLease(credentialId: number, expectedRefresh: string, force: boolean, owner: string, nowMs: number, leaseMs: number): OAuthRefreshLeaseClaim;
     completeOAuthRefreshLease(lease: OAuthRefreshLease, credential: OAuthCredential): boolean;
     releaseOAuthRefreshLease(lease: OAuthRefreshLease): void;

package/dist/types/core.d.ts

@@ -19,6 +19,7 @@ export * from "./model-thinking";
 export * from "./models";
 export * from "./provider-models";
 export { getProviderRuntimeDescriptor, PROVIDER_RUNTIME_DESCRIPTORS, type ProviderRuntimeDescriptor, } from "./providers/register-builtins";
+export { hasAdjacentPrivateThinkingBlocks } from "./providers/transform-messages";
 export * from "./rate-limit-utils";
 export * from "./stream";
 export * from "./types";

package/dist/types/model-cache.d.ts

@@ -11,9 +11,12 @@ interface CacheEntry<TApi extends Api = Api> {
      * match — the cache already incorporates the same static state.
      */
     staticFingerprint: string;
+    /** IDs returned by the authoritative dynamic provider catalog, when retained. */
+    dynamicModelIds: string[] | undefined;
+    dynamicModelProvenance: string | undefined;
 }
 /** Close the shared cache only when it owns the exact requested database path. */
 export declare function closeModelCache(dbPath?: string): boolean;
 export declare function readModelCache<TApi extends Api>(providerId: string, ttlMs: number, now: () => number, dbPath?: string): CacheEntry<TApi> | null;
-export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string): void;
+export declare function writeModelCache<TApi extends Api>(providerId: string, updatedAt: number, models: Model<TApi>[], authoritative: boolean, staticFingerprint: string, dbPath?: string, dynamicModelIds?: readonly string[], dynamicModelProvenance?: string): void;
 export {};