changes.md

## 2026-10-24 - Provider requests carry the session working directory (senpi#2848)

### What changed

- `packages/ai/src/types.ts`: provider request options accept the originating session's `cwd` for subprocess-backed providers.

### Why

- `packages/ai/src/types.ts`: a shared engine process can serve projects outside its process working directory; subprocess adapters need the session directory rather than the host directory.

### Why an extension could not handle it

- `packages/ai/src/types.ts`: this option crosses the shared provider request contract before an adapter is selected.

### Expected merge conflict zones

- `packages/ai/src/types.ts`: the optional fields at the start of `ProviderRequestOptions`.

## 2026-10-12 - Remove the /llama llama.cpp integration (senpi#3202)

### What changed

- `packages/ai/src/types.ts`: `KnownClassifierApi` drops the `"llama-cpp-classify"` member.

### Why

- `packages/ai/src/types.ts`: Q ordered removal of the `/llama` feature, including its dedicated classifier API.

### Why an extension could not handle it

- `packages/ai/src/types.ts`: an extension cannot narrow the shared `KnownClassifierApi` type union.

### Expected merge conflict zones

- `packages/ai/src/types.ts`: the `KnownClassifierApi` union.

## 2026-10-21 - ModelCost.unknown and Usage.costUnknown (senpi#3844)

### What changed

- `packages/ai/src/types.ts`: `ModelCost` gains optional `unknown: true`; `Usage` gains optional `costUnknown: true`.
- `packages/ai/src/models.ts`: `calculateCost` on a model whose cost is `unknown` zeroes the cost fields and sets `usage.costUnknown` instead of multiplying placeholder rates.

### Why

- Lets a model with no known price report its turns as cost-unknown, so consumers show no amount instead of a reported $0 (senpi#3844).

### Why an extension could not handle it

- Cost calculation and the `Usage` contract live in the ai package.

### Expected merge conflict zones

- LOW: the `ModelCost` and `Usage` interfaces in `types.ts`; the head of `calculateCost` in `models.ts`.

## 2026-10-21 - Kimi keeps its blank-key, region-only login (senpi#3869)

### What changed

- `packages/ai/src/providers/kimi-coding-auth.ts`: the Kimi API-key auth declares `keyOptional: true`.

### Why

- senpi#3869 review: before senpi#3867 a user with `KIMI_API_KEY` in the environment could leave the key prompt blank to store only the region (`resolve` falls back from an empty stored key to `KIMI_API_KEY` and still routes to the stored region). Refusing that login would be a user-facing regression. Regression: the Kimi case in `test/login-empty-api-key.test.ts`.

### Why an extension could not handle it

- This is the in-tree Kimi provider declaring its own auth metadata.

### Expected merge conflict zones

- LOW: the object returned by `kimiCodeApiKeyAuth`.

## 2026-10-21 - Logins refuse a blank API key unless the provider declares it optional (senpi#3867)

### What changed

- `packages/ai/src/auth/types.ts`: `ApiKeyAuth` gains optional `keyOptional`, which a provider sets when it works without a key (a local server such as llama.cpp).
- `packages/ai/src/models.ts`: `Models.login` passes the provider's login result through `withoutBlankKey` when `keyOptional` is set, so a blank or `undefined` key is dropped and the URL/env-only credential is saved. Then `assertLoginKeyPresent` (fork-only `src/auth/pool/slots.ts`) throws `EmptyApiKeyError` for any remaining blank, whitespace or `undefined` key, before the store is touched. `appendLoginSlot` in the same file runs the same check, so `AuthStorage.set` and RPC `login_api_key` stay strict. Env-only logins that carry no `key` field (Bedrock profile or credential chain, Vertex ADC) still save.

### Why

- senpi#3867: an empty key was appended as a keyless `login-2` account that nothing could use. Regression: `test/login-empty-api-key.test.ts`.

### Why an extension could not handle it

- `Models.login` owns the write; an extension cannot veto a credential before the store mutation.

### Expected merge conflict zones

- LOW: the import block and the line after `raceWithAbortSignal(loginOperation, signal)` in `Models.login`.

## 2026-10-22 - AssistantMessage.promptCacheBreakpoint (senpi#3242)

### What changed

- `packages/ai/src/types.ts`: `AssistantMessage` gains optional `promptCacheBreakpoint?: true`, a request-only hint that the history up to and including the message is a stable prefix. Context reduction sets it on copies; it is never persisted.

### Why

- `packages/ai/src/types.ts`: context reduction must tell the provider adapter where the prefix it leaves unchanged ends, so the adapter can keep a cache checkpoint there instead of re-writing the cached conversation at every frontier step.

### Why an extension could not handle it

- `packages/ai/src/types.ts`: the hint has to travel on the message the adapter converts, which is a core message contract.

### Expected merge conflict zones

- `packages/ai/src/types.ts`: the end of `AssistantMessage`.

## 2026-10-21 - AssistantMessage.timing (senpi#3879)

### What changed

- `packages/ai/src/types.ts`: new `AssistantMessageTiming` (`requestedAt`, optional `firstTokenAt`/`lastTokenAt`, `endedAt`, optional `generationMs`, all milliseconds) and an optional `AssistantMessage.timing`.

### Why

- A reply's time to first token and generation rate were measured only live by the TPS notice and discarded; RPC clients (the desktop turn stats line, desktop #3729) and reloaded sessions had no record of them.

### Why an extension could not handle it

- The message type is the public `pi-ai` contract; an extension cannot add a persisted field to it.

### Expected merge conflict zones

- LOW: `AssistantMessage` in `packages/ai/src/types.ts`, next to `endTurn`/`timestamp`.

## 2026-10-21 - Request context is distinct from cumulative billing (omo#10792)

### What changed

- `packages/ai/src/types.ts`: optional `Usage.contextUsage` records the latest request's input (including cache reads/writes) and output separately. `null` means the provider reports cumulative billing but no request measurement; absent preserves the legacy single-request contract. Existing billing fields retain their semantics. The two-part snapshot preserves both prompt-only overflow/anchor calculations and occupied-context totals without subtracting cumulative output.

### Why

- `packages/ai/src/types.ts`: an SDK query can bill multiple requests whose input contexts overlap. Their sum cannot describe the current context window.

### Why an extension could not handle it

- `packages/ai/src/types.ts`: the public usage contract must carry the distinction through persistence, provider middleware, and every context consumer without changing billing.

### Expected merge conflict zones

- LOW: `packages/ai/src/types.ts`, the optional fields in `Usage`. Keep this additive field if upstream still uses one usage object.

## 2026-10-21 - AssistantMessage.failureSource (senpi#3866)

### What changed

- `packages/ai/src/types.ts`: `AssistantMessage` gains optional `failureSource?: "local"`.

### Why

- A run can fail in local code (the session's pending-input journal, a local file) with no provider request involved. The agent marks that failure so a session never retries the model or walks the fallback chain on it (omo#10781).

### Why an extension could not handle it

- `AssistantMessage` is the public message contract in `pi-ai`.

### Expected merge conflict zones

- LOW: after `abortSource` in `AssistantMessage` in `packages/ai/src/types.ts`.

## 2026-10-18 - AnthropicMessagesCompat.supportsGzipRequestBody (senpi#3643)

### What changed

- `packages/ai/src/types.ts`: `AnthropicMessagesCompat` gains optional `supportsGzipRequestBody`.

### Why

- Lets a model or provider opt in or out of gzip request bodies (senpi#3643).

### Why an extension could not handle it

- The compat type is part of the public model contract in `pi-ai`.

### Expected merge conflict zones

- LOW: the end of `AnthropicMessagesCompat` in `packages/ai/src/types.ts`.

## 2026-10-17 - Export the provider credential env names (senpi#3531)

### What changed

- `packages/ai/src/env-api-keys.ts`: the provider-to-variable map is the module-level `API_KEY_ENV_VARS`, read by `getApiKeyEnvVars` exactly as before. New exports:
  - `apiKeyEnvProviders()`: every provider id `getApiKeyEnvVars` maps.
  - `providerCredentialEnvNames()`: every name `getEnvApiKey` can read, meaning those variables plus the Vertex ADC and Bedrock names.

### Why

senpi#3531: the RPC host daemon's environment allowlist was a separate hand-written list. It dropped credential names the lookup reads (`COPILOT_GITHUB_TOKEN`, `HF_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, every numbered slot), so a host never saw credentials a direct process used. The daemon now derives its list from these exports.

### Why an extension could not handle it

The map is private to `pi-ai`; a consumer can only enumerate it through an export.

### Expected merge conflict zones

- `packages/ai/src/env-api-keys.ts`: the map moved out of `getApiKeyEnvVars`, and the two exports sit above it.


## 2026-10-18 - Cursor families published after the 2026-08-18 capture (senpi#3620)

### What changed

- `src/cursor/capability-table.ts` (split out of `src/cursor/model-capabilities.ts`, which keeps the types, parser
  and alias lookups): capability entries for `claude-opus-5-5`, `claude-fable-5-1`, `claude-sonnet-5-5`,
  `claude-haiku-5-5`, `muse-wonder-1.0`, `muse-spark-1.3`, `grok-4.7`, `gemini-4-argon`, `gemini-3.8-flash` and
  `default`. Each window is the ceiling the server reported on the first checkpoint on 2026-10-18 for the suffix
  variant senpi sends; `maxWindow` is the largest context option AvailableModels offers. `reasoning_effort` joins
  `CursorParameterId` (Sonnet 5.5, Haiku 5.5, Muse Wonder, Grok 4.7 and the Gemini 4/3.8 rows name the axis so).
- `src/cursor/display-name.ts` (moved out of `catalog-grouping.ts`): names drop zero-width characters and doubled
  spaces, the Haiku 5.5 plain group drops Cursor's "No Thinking" whole, and a thinking group whose label never said
  so gains "Thinking".
- `src/cursor/model-input.ts` (moved out of `api/cursor-agent.ts`): image input follows AvailableModels'
  `supportsImages`, adding Kimi K3, Muse and Grok 4.5/4.6.
- `src/cursor/model-capabilities.ts` + `src/cursor/display-name.ts` + `src/cursor/catalog-grouping.ts` (review LOW-1 fix):
  the ten families' entries carry the new `served-checkpoint` evidence kind, and a display name drops its `1M` size
  token when the measured window is smaller — Opus 5.5, Fable 5.1 and Muse Spark 1.3 serve 300k for the default option
  senpi sends; Cursor's `1M` label names the extended-context tier (`maxWindow`). `available-models` entries keep
  Cursor's label untouched (their mismatch is senpi#3621's scope).

### Why

- The ten families answered live requests through the #2038 derived grouping but advertised the 200k placeholder
  window, two carried broken names, and image-capable families were offered as text-only.
- A picker name promising 1M while the served window is 300k misleads (review LOW-1); the name now follows the window
  the server was measured serving, sourced from the committed 2026-10-18 checkpoint fixture and Cursor's published
  "up to 1M with extended context" tier.

### Why an extension couldn't do it

- Catalog normalization and discovery run inside the provider before any extension sees a model.

### Expected merge-conflict zones

- `src/cursor/model-capabilities.ts`, `src/cursor/capability-table.ts`, `src/cursor/catalog-grouping.ts`, the
  discovery block of `api/cursor-agent.ts`.
## 2026-10-16 - Image generation results carry the provider diagnostic (omo#10285)

### What changed

- `packages/ai/src/types.ts`: `AssistantImages` gains optional `providerDiagnostic`, the same bounded classification `AssistantMessage` already carries.
- `packages/ai/src/api/openai-images.ts`: the SDK images call runs inside `awaitProviderTransport` with `openAICompatibleProviderDiagnosticFromError`, as the chat adapters' calls do, and a failed request sets `providerDiagnostic` from `readProviderDiagnostic(error)`.

### Why

The coding agent's `generate_image` tool needs the HTTP status of a rejected images request (404/405 means the provider has no images endpoint) to move past such a gateway. Reading it from the formatted `errorMessage` would be guessing from prose.

### Why an extension could not handle it

`AssistantImages` is the `pi-ai` result type; only the adapter that made the request sees the SDK error.

### Expected merge conflict zones

- `packages/ai/src/types.ts`: the `AssistantImages` field list, beside `errorMessage`.
- `packages/ai/src/api/openai-images.ts`: the request callback and the `catch` block of `generateImages`.

## 2026-10-15 - ProviderDiagnostic gains the network category and structured_transport evidence (senpi#3228)

### What changed

- `packages/ai/src/provider-diagnostic.ts`: `ProviderDiagnosticCategory` adds `network`; `ProviderDiagnosticEvidence` adds `structured_transport`; `sanitizeProviderDiagnostic` accepts a transport diagnostic only with no status and a code from the allowlist.

### Why

See `utils/changes.md` (senpi#3228): connection failures need a category clients can act on.

### Why an extension could not handle it

The diagnostic type and its boundary validation are part of the `pi-ai` contract.

### Expected merge conflict zones

- `packages/ai/src/provider-diagnostic.ts`: the category and evidence unions and `sanitizeProviderDiagnostic`.

## 2026-10-15 - Bill usage with the cost card in force (senpi#3378)

### What changed

- `packages/ai/src/types.ts`: `ModelCostCard` (the rates plus `tiers`) and `ModelCostEffectiveRate` (`effectiveFrom` plus a card); `ModelCost` gains optional `effectiveRates`.
- `packages/ai/src/models.ts`: `calculateCost(model, usage, atMs = Date.now())` bills with `costCardAt(model.cost, atMs)` and takes the tiers from that card.
- `packages/ai/src/index.ts`: re-exports the new fork file `model-cost.ts` (`costCardAt`).

### Why

- senpi#3378: the provider moves the 2026-10-13 Argon model from $2/$10 to $4/$20 per 1M tokens on 2026-12-01 08:00Z. A single static card under-reports every request after that instant by 2x until a catalog refresh, and a session loaded before the refresh keeps the old card even after it.

### Why an extension could not handle it

- `calculateCost` is the single billing function every wire adapter calls; an extension cannot change how a builtin adapter bills.

### Expected merge conflict zones

- LOW: the first lines of `calculateCost`, the `ModelCost` interface block in `types.ts`, and the export list in `index.ts`.

## 2026-10-14 - Map-less generation-4 rows offer only the levels the provider accepts (senpi#3292 review)

### What changed

- `packages/ai/src/models.ts`: new `inferThinkingLevelMap` returns the row's own map, else the OpenAI inference, else `inferGoogleThinkingLevelMap` from the fork-only `packages/ai/src/google-thinking-generation.ts`. `getSupportedThinkingLevels` reads it, so a generation-4-or-later Google row without a `thinkingLevelMap` offers only `low`, `medium` and `high`, and `clampThinkingLevel` raises `off` and `minimal` to `low`.

### Why

Custom `models.json` and discovered rows usually carry no map. Before this, such a row still offered `off` (sent as a zero budget) and `minimal`, both rejected with HTTP 400; the review of #3293 found the fix only worked for rows that shipped a map.

### Why an extension could not handle it

Supported levels and clamping are computed in the core model runtime before any adapter or extension sees the request.

### Expected merge conflict zones

- LOW: the import block of `packages/ai/src/models.ts` and the line in `getSupportedThinkingLevels` that reads the inferred map.

## 2026-10-11 - Usage-limit advice retains structured cause (senpi#3131 review)

### What changed

- `packages/ai/src/types.ts`: assistant messages have an optional redaction-safe `errorCause` identifying account- or model-scoped usage exhaustion independently of presentation text.

### Why

Recovery advice includes `/model`, so parsing the rewritten sentence loses the original account scope.

### Why an extension could not handle it

The shared assistant message is the transport contract consumed by session events and RPC history.

### Expected merge conflict zones

- `packages/ai/src/types.ts`: optional assistant failure metadata.

## 2026-10-11 - Evidence-gated server search opt-in (senpi#3122 review)

### What changed

- `model.ts`: Google generation and Vertex models accept typed `compat.supportsWebSearch`.
- `providers/xai.ts`: retains the documented `webSearchToolType` without setting `supportsWebSearchPreview: true`; the unverified route now requires explicit opt-in.

### Why

- Documented tool support and an accepted request are not proof of executed search and replay. The held xAI probe failed authentication.

### Why an extension could not handle it

- Model compatibility types and provider catalog defaults belong to pi-ai.

### Expected merge conflict zones

- `model.ts` compatibility conditional and the xAI catalog mapping.

## 2026-10-11 - Explicit in-turn search capabilities (senpi#3122)

### What changed

- `providers/xai.ts` marks the built-in Responses catalogue with `supportsWebSearchPreview: true`; the coding-agent injector uses xAI's documented `web_search` type, not OpenAI's legacy preview type.
- `api/openai-responses.ts` gates the current `web_search` name alongside the two legacy preview names, preventing unsupported custom endpoints from receiving hook-injected native search.
- `types.ts` adds optional `OpenAICompletionsCompat.supportsWebSearch` for endpoint-specific completion server search, and the compatibility resolver keeps this declaration optional rather than synthesizing support for a coding-plan endpoint.
- Focused xAI, custom-Responses and existing Anthropic encrypted-replay tests cover the boundary.

### Why

- Server search must be the first choice on a supported main-request API. Search capability belongs to the exact provider/API route, not to a guessed proxy hostname or an auxiliary search model.

### Why an extension could not handle it

- Provider catalogue capabilities, shared model types and the final wire sanitizer are owned by pi-ai.

### Expected merge conflict zones

- The xAI catalogue mapping, optional completion compatibility fields, and the Responses native-tool predicate.

## 2026-10-10 - allowed_tools only on native OpenAI API hosts (senpi#3080)

### What changed

- `packages/ai/src/types.ts`: the `Context.activeToolNames` doc names the predicate that now gates it, `supportsAllowedToolChoice`, which requires the compat flag and a native OpenAI API host.

### Why

A flagged model behind a Responses-compatible gateway was sent `tool_choice: allowed_tools`, which the gateway rejects on every turn.

### Why an extension could not handle it

The doc describes the core request contract between the session and the provider adapters.

### Expected merge conflict zones

- The `activeToolNames` doc comment on `Context`.

## 2026-10-07 - Claude Agent SDK 0.3.292 (senpi#2545)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `claudeCodeVersion` 2.1.289 -> 2.1.292, the Claude Code version the bundled SDK 0.3.292 declares.
- `packages/ai/test/anthropic-oauth-claude-code-version.test.ts`: the two `claude_code_version_too_old` retry tests name one patch above the version a request advertises by default instead of a literal `2.1.290`, which the bundled version had passed.

### Why

The nightly Releasability gate (senpi#2545) fails its SDK currency check while a newer SDK is published; 0.3.292 bundles Claude Code 2.1.292.

### Why an extension could not handle it

The SDK pin and the advertised Claude Code version are fixed at build time in the package manifest and the provider module.

### Expected merge conflict zones

The SDK pin line and the lockfiles at the next upstream dependency sync.

## 2026-10-07 - A tool-change system param never lands directly before a user turn (senpi#2864)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `convertMessages` flushes the pending mid-conversation system messages when an assistant param is actually pushed, after the `blocks.length === 0` skip, instead of at the start of every assistant message.

### Why

A reply that converts to no blocks (for example a same-model reply that ended with nothing replayable) was skipped after the flush, leaving the tool-change `system` param directly before the next `user` turn. Anthropic rejects that (`role 'system' must precede an 'assistant' message`), and since the transcript keeps the layout, every later request in the session failed. The same class was fixed upstream in oh-my-pi v18.8.0.

### Why an extension could not handle it

The placement of system params is decided inside the provider's message conversion.

### Expected merge conflict zones

- The assistant branch of `convertMessages` in `packages/ai/src/api/anthropic-messages.ts`, around the `blocks.length === 0` skip.

## 2026-10-06 - A forced tool_choice refused inside a 200 stream is retried (senpi#2801)

### What changed

- `packages/ai/src/utils/tool-choice-fallback.ts`: `primeStreamUntilContent` reads a forced request's stream until its first content (text, reasoning, a tool call or a finish), replaying what it read. An error the stream raises before that is marked as a request refusal, and `isForcedToolChoiceUnsupportedError` / `refusalNamesForcedTool` treat it like a 400. The existing rules apply unchanged: the known wordings, the forced-tool naming rule, one retry, and no memory for thinking-blamed refusals.
- `packages/ai/src/api/openai-completions.ts`: the forced request's `send` primes its stream through `primeStreamUntilContent` (`chatChunkHasContent`). An unforced request's stream is untouched.
- `packages/ai/test/openai-completions-tool-choice.test.ts`: the fake gateway can now answer 200 and raise in-band. Five new cases, three of which fail on main: an in-band refusal is retried once and the turn completes; a thinking-blamed one is not remembered; a second refusal surfaces once. Two guards: a refusal after content streamed is not retried (nothing is sent twice), and an unforced request is not retried.

### Why

A keepalive gateway serving Kimi K3 with thinking on answered the first-turn forced `todo` request with 200 and then `tool_choice 'specified' is incompatible with thinking enabled` in-band. The retry only wrapped the HTTP response, so the first turn ended in an error until the user typed `continue`.

### Why an extension could not handle it

The refusal has to be caught where the provider request is sent and its stream is opened, which is inside the AI package's provider implementation.

### Expected merge conflict zones

- `packages/ai/src/api/openai-completions.ts`: the `createRequest` call to `sendWithForcedToolChoiceFallback` and the helpers next to `isForcedOpenAICompletionsToolChoice`.
- `packages/ai/src/utils/tool-choice-fallback.ts`: the status gate at the top of `isForcedToolChoiceUnsupportedError` and `refusalNamesForcedTool`.

## 2026-10-04 - Claude Agent SDK 0.3.289

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `claudeCodeVersion` 2.1.288 -> 2.1.289, the Claude Code version the bundled SDK 0.3.289 declares.

### Why

The Releasability gate's SDK currency check fails while a newer SDK is published; 0.3.289 bundles Claude Code 2.1.289.

### Why an extension could not handle it

The SDK pin and the advertised Claude Code version are fixed at build time in the package manifest and the provider module.

### Expected merge conflict zones

The SDK pin line and the lockfiles at the next upstream dependency sync.

## 2026-10-03 - Cursor resource_exhausted signatures are Cursor-only; "reset in N minutes" is a retry hint (senpi#2660)

### What changed

- `packages/ai/src/utils/overflow.ts`: `isCursorPayloadResourceExhausted`, `isCursorQuotaResourceExhausted` and `isCursorZeroTokenResourceExhausted` return false unless the message's provider is `cursor` or `cursor-cli-oauth` (or unset, as in provider-agnostic callers).
- `packages/ai/src/utils/retry-hint.ts`: `fromBodyProse` reads "reset(s) in N <unit>" when the body is already rate-limited.

### Why

- `packages/ai/src/utils/overflow.ts`: Devin rejects a turn over its free-model limit with a trailer-only `resource_exhausted`, so the message bills zero tokens and matched Cursor's zero-token signature. The session then compacted and re-minted on the refused model instead of reaching the fallback chain.
- `packages/ai/src/utils/retry-hint.ts`: the same message says "Your limit will reset in 9 minutes", which the prose parser ignored, so the wait fell back to the 60 s cap.

### Why an extension could not handle it

- Both functions are the classification the session's retry loop calls before any extension sees the failure.

### Expected merge conflict zones

- LOW: the three Cursor functions in `overflow.ts` and the prose branch of `fromBodyProse`.

## 2026-10-03 - Model `supportsAssistantPrefill` (senpi#1930)

### What changed

- `packages/ai/src/model.ts`: `Model.supportsAssistantPrefill?: boolean` (absent = no) and `modelSupportsAssistantPrefill(model, { thinkingEnabled })`, false unless the model is marked and, on the Anthropic Messages API, extended thinking is off.
- `packages/ai/src/index.ts`: exports `modelSupportsAssistantPrefill`.

### Why

- `packages/ai/src/model.ts`, `packages/ai/src/index.ts`: #1930. Whether a request may end with an assistant message is a property of the model and of the request settings. No default model supports it today, and it is set per model only after a live probe.

### Why an extension could not handle it

- `packages/ai/src/model.ts`, `packages/ai/src/index.ts`: model metadata is defined in packages/ai, below the extension runtime.

### Expected merge conflict zones

- LOW: the field beside `recoverTextToolCalls` in `Model`, and the export line beside `./models.ts`.

## 2026-10-03 - Claude Code fingerprint floor 2.1.288 (senpi#2545)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: the `claudeCodeVersion` floor declaration is 2.1.288, the Claude Code version `@anthropic-ai/claude-agent-sdk` 0.3.288 ships. The declaration keeps its literal `const claudeCodeVersion = "X.Y.Z";` form.

### Why

- Regression #2033 keeps the floor equal to the pinned SDK's `claudeCodeVersion`; the pin moved (`packages/coding-agent/changes.md`).

### Why an extension could not handle it

- The OAuth fingerprint is built inside the Anthropic API module before any extension hook.

### Expected merge conflict zones

- LOW: the `claudeCodeVersion` declaration line.

## 2026-10-02 - Retry a rejected tool_reference replay as text (senpi #2568)

### What changed

- `packages/ai/src/api/anthropic-tool-references.ts`: new `demoteToolReferenceReplay` turns every replayed `tool_reference` into text: a native search pair (`server_tool_use` plus its `tool_search_tool_result`) becomes `Tool search found: <names>`, and `tool_reference` items inside a client `tool_result` become one `Tools loaded: <names>` text item. Tool definitions in `tools` are untouched.
- `packages/ai/src/api/anthropic-messages.ts`: when a request that replays a `tool_reference` fails with `400 Tool reference '<name>' not found in available tools`, `stream` retries it once with `demoteToolReferenceReplay` applied and remembers the fallback per (session, base URL, model) in `toolReferenceReplayFallbacks`, next to the unsigned-thinking fallback and cleared by the same session-resource cleanup. A request that replays no reference is never retried.
- `packages/ai/test/anthropic-tool-reference-replay-fallback.test.ts`: a local endpoint that rejects any replayed reference proves the retry, the session-level memory, and that a reference-free request is not retried.

### Why

- Live 2026-10-02 (omo 5.1.10, claude-sonnet-5 through an Anthropic-compatible relay): a native BM25 search returned `generate_image`, `thread_set_model`, `task`, `thread_set_reasoning`, `workpool`; the next request replayed that result and failed with `Tool reference 'generate_image' not found in available tools` although `tools` defined every name. Bisecting the captured payload against the relay showed it rejects any replayed `tool_reference` (in a search result or a `tool_result`) once the request carries six or more tools, while it accepts the same history with five. History only grows, so every later turn in the session failed the same way (`'task' not found` on the next one).

### Why an extension could not handle it

- The rejection is decided by the wire payload assembled from history inside the provider; an extension's `before_provider_request` hook cannot see the HTTP error to retry, and stripping references unconditionally would lose deferred-tool loading on endpoints that accept them.

### Expected merge conflict zones

- LOW: the retry branch sits in the fork-only `createRequest` retry block beside the unsigned-thinking fallback; `anthropic-tool-references.ts` is fork-only.
- The demoted replay keeps the found tools callable: a deferred tool is loaded only by a replayed `tool_reference`, so `demoteToolReferenceReplay` also sends every tool a demoted reference named without `defer_loading` (other deferred tools keep it). Without this the model would have to search again before calling a tool an earlier turn found. Test: the found tools lose `defer_loading` and an unrelated deferred tool keeps it.

## 2026-10-02 - Compat faux registrations survive an API registry reset (senpi#2542)

### What changed

- `packages/ai/src/api-registry.ts`: `registerApiProvider` accepts `{ survivesClear: true }`. `clearApiProviders()` (and so `resetApiProviders()`) keeps such entries in the registry it clears, the global one or the active scope's overlay; `unregisterApiProviders(sourceId)` still removes them. Removing an entry from the global registry puts the builtin for that API back, so unregistering an override that outlived a reset leaves the builtin usable (a scope overlay already falls back to the builtin).
- `packages/ai/src/compat.ts`: `registerFauxProvider` registers with `survivesClear`, so a reset leaves the caller's faux provider in place, in or out of a provider scope.

### Why

- `packages/ai/src/api-registry.ts`, `packages/ai/src/compat.ts`: `AgentSession.reload()` runs `resetApiProviders()`, which cleared the only copy of a compat faux registration, so every request after a reload failed with "No API provider registered". Reload holds prompts until the rebuilt runtime is bound, so a prompt sent during teardown always hit that gap. When the random faux API id happened to contain a transient-looking token, the error entered auto-retry backoff and the config-reload admission test timed out in CI.

### Why an extension could not handle it

- `packages/ai/src/api-registry.ts`, `packages/ai/src/compat.ts`: the registration and the reset live in pi-ai's provider registry, below the extension API.

### Expected merge conflict zones

- `packages/ai/src/api-registry.ts`: `RegisteredApiProvider`, `createRegisteredProvider`, `registerApiProvider`, `unregisterApiProviders`, `clearApiProviders`.
- `packages/ai/src/compat.ts`: the `registerFauxProvider` body.

## 2026-10-01 - Claude Code fingerprint floor 2.1.286 (senpi#2481)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: the `claudeCodeVersion` floor declaration is 2.1.286, the Claude Code version `@anthropic-ai/claude-agent-sdk` 0.3.286 ships. The declaration keeps its literal `const claudeCodeVersion = "X.Y.Z";` form.

### Why

- Regression #2033 keeps the floor equal to the pinned SDK's `claudeCodeVersion`; the pin moved (`packages/coding-agent/changes.md`).

### Why an extension could not handle it

- The OAuth fingerprint is built inside the Anthropic API module before any extension hook.

### Expected merge conflict zones

- LOW: the `claudeCodeVersion` declaration line.

## 2026-09-30 - ChatGPT Subscription requests carry codex's routing hint (senpi#2410)

### What changed

- `packages/ai/src/api/openai-codex-responses.ts`: every Responses request on the ChatGPT Subscription lane, over SSE and on the WebSocket handshake, sends `x-codex-routing-hint: model=<id>`, plus `;tier=<tier>` when the body names a service tier (for example `model=gpt-6-astra;tier=ultrafast`). The value is built from the final request body, after `onPayload`; a cached WebSocket is rebuilt when that hint changes so a model or tier switch cannot reuse a stale handshake.

### Why

- `packages/ai/src/api/openai-codex-responses.ts`: codex (`build_routing_hint_header`) and oh-my-pi (`codexRoutingHint`) send this header on every ChatGPT-backend request, and it is how they tell the backend which tier a request is meant for. senpi sent no routing hint at all.

### Why an extension could not handle it

- `packages/ai/src/api/openai-codex-responses.ts`: the header must match the request body the adapter builds, and it has to be on the WebSocket handshake, which extensions cannot reach.

### Expected merge conflict zones

- `packages/ai/src/api/openai-codex-responses.ts`: the `sseHeaders` / `websocketHeaders` construction in `streamOpenAICodexResponses`, and the `buildBaseCodexHeaders` / `buildSSEHeaders` / `buildWebSocketHeaders` signatures.

## 2026-09-29 - Explicit Astra Ultrafast request tier (senpi#2399)

### What changed

- `packages/ai/src/types.ts`, `packages/ai/src/model.ts`: accept `ultrafast` in shared request and model service-tier types.
- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`, `packages/ai/src/api/openai-responses-shared.ts`: forward Ultrafast through simple and full Responses options and apply Astra's 6x Standard pricing; retain the Codex default-echo fallback.

### Why

- `packages/ai/src/types.ts`, `packages/ai/src/model.ts`: the typed public API must accept the tier before callers can select it.
- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`, `packages/ai/src/api/openai-responses-shared.ts`: Astra Ultrafast needs the native request path and correct costs at every effort and context size.

### Why an extension could not handle it

- `packages/ai/src/types.ts`, `packages/ai/src/model.ts`: extensions cannot widen the exported request/model contracts.
- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`, `packages/ai/src/api/openai-responses-shared.ts`: the adapters own request composition, shared response typing, and token accounting.

### Expected merge conflict zones

- `packages/ai/src/types.ts`, `packages/ai/src/model.ts`: service-tier type unions.
- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`, `packages/ai/src/api/openai-responses-shared.ts`: request/response service-tier types and pricing switches.

## 2026-09-30 - Claude Code fingerprint floor 2.1.285 (senpi#752)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: the `claudeCodeVersion` floor declaration is 2.1.285, the Claude Code version `@anthropic-ai/claude-agent-sdk` 0.3.285 ships. The declaration keeps its literal `const claudeCodeVersion = "X.Y.Z";` form.

### Why

- Regression #2033 keeps the floor equal to the pinned SDK's `claudeCodeVersion`; the pin moved (`packages/coding-agent/changes.md`).

### Why an extension could not handle it

- The OAuth fingerprint is built inside the Anthropic API module before any extension hook.

### Expected merge conflict zones

- LOW: the `claudeCodeVersion` declaration line.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): retired and renamed AI source paths

### What changed

- `packages/ai/src/auth/oauth/openai-codex.ts` -> `packages/ai/src/auth/oauth/chatgpt-subscription.ts` and `packages/ai/src/providers/openai-codex.models.ts` -> `packages/ai/src/providers/chatgpt-subscription.models.ts` under fork rename commit `3c816ead49` (D-4).
- `packages/ai/src/images-models.ts` and `packages/ai/src/providers/openrouter-images.ts` stay deleted by upstream image/classifier unification commit `a328aa89ad`; their live behavior is on `image-models.ts`, `models.ts`, `providers/openrouter.ts`, and `providers/images/register-builtins.ts`.

### Why

The fork uses the user-facing `chatgpt-subscription` provider identity, while upstream v0.99.1 replaced the legacy image collections and provider wrapper with the unified schema-v6 model surface. Keeping the old paths would create duplicate provider and image-model stacks.

### Why an extension could not handle it

OAuth loading, generated model shards, and image provider registration are package-core wiring below the extension API.

### Expected merge conflict zones

- HIGH: upstream continues to edit `openai-codex` paths; port applicable deltas into the `chatgpt-subscription` counterparts.
- MEDIUM: upstream changes to the unified image surface; keep the legacy `images-models.ts` and `providers/openrouter-images.ts` paths deleted.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): kimi-coding vision rows carry the default image resize profile

### What changed

- `packages/ai/src/providers/kimi-coding.models.ts`: the four image-input rows (`k3`, `k3-256k`, `kimi-for-coding`, `kimi-for-coding-highspeed`) declare `inputLimits.images.resize` with the generator's default profile (2000 x 2000 px, 4.5 MiB, JPEG quality 80).

### Why

Upstream v6 stamps that resize profile on every generated vision model, and the read tool and the session read it from `model.inputLimits`; the hand-owned kimi-coding shard bypasses the generator, so its vision rows had no resize profile.

### Why an extension could not handle it

The shard is part of the builtin catalog, loaded before any extension exists.

### Expected merge conflict zones

- LOW: none from upstream (the shard is fork-owned); a change to the generator's `DEFAULT_IMAGE_RESIZE` must be mirrored here.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): paths divergent from the new pin

### What changed

- `packages/ai/src/image-models.ts`: same code as the pinned upstream file; the `BuiltinImageModel` conditional type is laid out the way the fork's formatter prints it.

### Why

The fork runs biome with its own formatter over every package (`npm run check` fails on warnings). No behavior differs from upstream; the fork image stack consumes this module through `@earendil-works/pi-ai/compat` (sync decision D-3).

### Why an extension could not handle it

Source formatting of package files is enforced by the repository check, not by any runtime surface.

### Expected merge conflict zones

- LOW: an upstream edit to `BuiltinImageModel`; take upstream's content and re-format.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): shared type roots (contract wave)

### What changed

- `packages/ai/src/types.ts`: What changed: adopted upstream v0.99.1 transcript contracts (SystemMessage, ToolReference, branded TranscriptContext, JSON-only ToolCall.arguments/ToolResultMessage details, nestedCalls, AssistantMessage.thinkingLevel, onProviderStreamEvent, classifier + image model types, BaseModel/ModelTypeMap/AnyModel, input limits, promptCache, mid-conversation system-message compat flags, MistralConversationsCompat). Kept fork: Model home in model.ts, OpenAIResponsesCompat home in openai-responses-compat.ts (+ supportsMidConvoSystemMessages), ConfigurationUpdateMessage, ProviderNativeContent, ToolCall incomplete/errorMessage, ToolResultMessage.addedToolNames, TranscriptContext.activeToolNames, KnownImageApi "openai-images", ImagesModelCost.imageInput, fork aliases KnownImagesApi/ImagesApi/ImagesModel, literal KnownImagesProvider/ImagesProviderId, deferredToolsMode "kimi", Anthropic supportsToolReferences/supportsWebSearch/unsignedThinkingReplay/string fallback models, BaseModel.input "video". Why: one type root for upstream transcript normalization while fork providers (OpenAI images, allowed-tools, native deferred tool loading, video input) keep compiling and behaving as before. Why an extension could not handle it: these are the core message/model contracts every provider adapter and the agent loop import; extensions cannot widen them. Expected merge conflict zones: KnownImageApi/KnownImagesProvider block, ToolCall and ToolResultMessage, Message union, Model/BaseModel/ImageModel block, OpenAIResponsesCompat, AnthropicMessagesCompat tail, OpenAICompletionsCompat deferred-tool fields.

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; the four shared type roots (plan D-24 contract wave, D-2, D-3, D-16).

### Why an extension could not handle it

They are the public type contracts every provider, the agent loop, extensions and RPC compile against; an extension consumes these types and cannot change them.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): ai core and TranscriptContext migration

### What changed

- `packages/ai/src/api/simple-options.ts`: `api/simple-options.ts` `buildBaseOptions` forwards `onProviderStreamEvent`. `api/simple-options.ts` keeps `applyExtraBody`, the reserved-key sets, `clampMaxForOpenAI`, the no-thinking guard in `adjustMaxTokensForThinking`, `abortServerSideFallback`/`extraBody`/model `cacheRetention` forwarding, and the model + request `samplingParams` merge.
- `packages/ai/src/api/transform-messages.ts`: `api/transform-messages.ts` keeps the fork two-pass tool-result pairing (dropped errored/aborted calls, results pulled next to their call, reused-id windows); system messages keep their position.
- `packages/ai/src/compat.ts`: Transcript contract: `utils/transcript.ts` (normalizeContext, getCurrentTools/SystemPrompt/SystemMessage, collapseSystemMessages, resolveTranscript, tool-state helpers) and its barrel export; `ApiStreamFunction`/`ApiStreamSimpleFunction` (fork home `api-registry.ts`) and `clampMaxTokensToContext` (fork home `api/context-room.ts`) take `TranscriptContext`; `compat.ts` `stream`/`streamSimple` normalize the public `Context` once and dispatch the transcript. `compat.ts`: fork api-registry module (provider scopes, builtin registry, faux lookup) kept; text-protocol tool-call middleware kept, now reading tools from the transcript.
- `packages/ai/src/index.ts`: resolved by L2a against upstream v0.99.1 (6a4af07d6): upstream constructs adopted, fork behavior kept.
- `packages/ai/src/models.ts`: Model types: `models.ts` `ProviderModel` catalogs (chat/image/classifier), `hasKnownModelType` filtering of fetched overlays, `getModelType`/`isModelType` re-export, `login(..., options)` forwarded to the provider method, `modelsAreEqual` compares type; `model.ts` `Model<TApi> extends BaseModel<TApi>` with `type?: "chat"`, `promptCache`, inherited `inputLimits`, and the `mistral-conversations` -> `MistralConversationsCompat` compat branch (C-AI-11). `models.ts`: `restoreModels` hook (chat subset), empty-refresh guard (a fetched overlay with no known model types never replaces the catalog), `PROVIDER_NOT_CONFIGURED_PREFIX`/`providerNotConfiguredMessage` exports, `onAccountCommitted` kept out of the provider login interaction, `supportsXhigh`/`supportsMax`/`supportsConfigurationUpdate` and the fork id tables, `retryPolicy`.
- `packages/ai/src/providers/all.ts`: `providers/all.ts`: upstream typed getters `getBuiltinImageModel(s)`, `getBuiltinClassifierModel(s)`, `getAllBuiltinModels`, `typesafe` provider; the separate images-provider collection (`builtinImagesProviders`, `builtinImagesModels`) is gone with upstream's image unification (D-3 ADOPT). `providers/all.ts`: fork-owned `kimi-coding` catalog (`BUILTIN_CATALOGS`), `normalizeBuiltinModel` (MiMo v2.5 Pro compat, Opus 4.8 `max`), `venice`, `alibaba-token-plan`; image/classifier getters tolerate providers without a generated shard.
- `packages/ai/src/providers/faux.ts`: Fork-only adapters read the prompt and tools from transcript system messages: `api/cursor-agent.ts` (`toCursorRequestView`: replayed prompt, non-system turns, current tools), `api/devin-agent/request.ts` (prompt/tools replayed; system messages removed before the index-seeded history ids), `api/devin-agent.ts` signatures; `providers/faux.ts` call log; `utils/estimate.ts`. `providers/faux.ts` `getCallLog()` keeps the pre-transcript `Context` shape (prompt/tools replayed, system messages dropped from `messages`). `api/cloudflare.ts` (REST base URL added), `api/pi-messages.ts` (TranscriptContext + provider stream events; fork tool-result sanitizing kept), `env-api-keys.ts` (typesafe, meta keys), `providers/faux.ts` (edited: call log + imports), `utils/estimate.ts` (edited: lazily-activated tools), tests `abort`, `context-estimate`, `cross-provider-handoff`, `empty`, `models-runtime`, `overflow`, `stream`, `tokens`, `tool-call-without-result`, `total-tokens`, `unicode-surrogate` (read; no edit needed).
- `packages/ai/src/utils/estimate.ts`: Fork-only adapters read the prompt and tools from transcript system messages: `api/cursor-agent.ts` (`toCursorRequestView`: replayed prompt, non-system turns, current tools), `api/devin-agent/request.ts` (prompt/tools replayed; system messages removed before the index-seeded history ids), `api/devin-agent.ts` signatures; `providers/faux.ts` call log; `utils/estimate.ts`. `utils/estimate.ts` keeps counting tools activated by a later `toolResult.addedToolNames` after the last billed usage. `api/cloudflare.ts` (REST base URL added), `api/pi-messages.ts` (TranscriptContext + provider stream events; fork tool-result sanitizing kept), `env-api-keys.ts` (typesafe, meta keys), `providers/faux.ts` (edited: call log + imports), `utils/estimate.ts` (edited: lazily-activated tools), tests `abort`, `context-estimate`, `cross-provider-handoff`, `empty`, `models-runtime`, `overflow`, `stream`, `tokens`, `tool-call-without-result`, `total-tokens`, `unicode-surrogate` (read; no edit needed).
- `packages/ai/src/utils/overflow.ts`: `utils/overflow.ts`: `prompt (?:is )?too long` (z.ai), Cerebras bodyless 400/413 overflow scoped to the `cerebras` provider. `utils/overflow.ts`: pre-flight guard, cold-seed budget, gateway 413 and kiro-lb patterns kept.
- `packages/ai/src/utils/retry.ts`: `utils/retry.ts`: ChatGPT subscription `subscription_sharing_usage_limit_exceeded` (terminal), `subscription_sharing_usage_unavailable`/`_user_unavailable` (retryable), HTTP 520 retryable; upstream tests added to `retry.test.ts` (Azure peak load, subscription limits). `utils/retry.ts`: credits_required, usage-limit exhaustion, request-shape rejections, 522, forbidden "Request not allowed" (senpi#2376) and Claude SDK lock contention kept.
- `packages/ai/src/utils/text.ts`: `utils/text.ts` `getSystemMessageText`/`renderSystemMessageUpdate` (now exported from the barrel); `SystemMessage` handling in estimate, faux serialization and the transform-messages first pass.
- `packages/ai/src/utils/transcript.ts`: Transcript contract: `utils/transcript.ts` (normalizeContext, getCurrentTools/SystemPrompt/SystemMessage, collapseSystemMessages, resolveTranscript, tool-state helpers) and its barrel export; `ApiStreamFunction`/`ApiStreamSimpleFunction` (fork home `api-registry.ts`) and `clampMaxTokensToContext` (fork home `api/context-room.ts`) take `TranscriptContext`; `compat.ts` `stream`/`streamSimple` normalize the public `Context` once and dispatch the transcript. `utils/transcript.ts` `normalizeContext` carries `Context.activeToolNames` (C-AI-1) and `collapseSystemMessages` keeps it.
- `packages/ai/src/api/cloudflare.ts`: `api/cloudflare.ts` (REST base URL added), `api/pi-messages.ts` (TranscriptContext + provider stream events; fork tool-result sanitizing kept), `env-api-keys.ts` (typesafe, meta keys), `providers/faux.ts` (edited: call log + imports), `utils/estimate.ts` (edited: lazily-activated tools), tests `abort`, `context-estimate`, `cross-provider-handoff`, `empty`, `models-runtime`, `overflow`, `stream`, `tokens`, `tool-call-without-result`, `total-tokens`, `unicode-surrogate` (read; no edit needed).
- `packages/ai/src/api/pi-messages.ts`: `api/cloudflare.ts` (REST base URL added), `api/pi-messages.ts` (TranscriptContext + provider stream events; fork tool-result sanitizing kept), `env-api-keys.ts` (typesafe, meta keys), `providers/faux.ts` (edited: call log + imports), `utils/estimate.ts` (edited: lazily-activated tools), tests `abort`, `context-estimate`, `cross-provider-handoff`, `empty`, `models-runtime`, `overflow`, `stream`, `tokens`, `tool-call-without-result`, `total-tokens`, `unicode-surrogate` (read; no edit needed).
- `packages/ai/src/env-api-keys.ts`: `api/cloudflare.ts` (REST base URL added), `api/pi-messages.ts` (TranscriptContext + provider stream events; fork tool-result sanitizing kept), `env-api-keys.ts` (typesafe, meta keys), `providers/faux.ts` (edited: call log + imports), `utils/estimate.ts` (edited: lazily-activated tools), tests `abort`, `context-estimate`, `cross-provider-handoff`, `empty`, `models-runtime`, `overflow`, `stream`, `tokens`, `tool-call-without-result`, `total-tokens`, `unicode-surrogate` (read; no edit needed).

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; the ai core adopts the upstream TranscriptContext/system-message model while keeping fork adapters, deferral and sampling behavior (plan D-16, D-3).

### Why an extension could not handle it

Provider-neutral message transforms, model registry and stream helpers sit below the extension layer and are shared by every provider.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): ai model catalog and generator

### What changed

- `packages/ai/src/providers/kimi-coding.models.ts`: `kimi-coding.models.ts` stays hand-owned with the fork's inline values, re-keyed `chat:<id>` with `type: "chat"` and exported through `flattenChatModelCatalog` (+ empty image/classifier catalogs).

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; the model catalog and generator take the upstream v6 schema while fork rows (GPT-6 family, chatgpt-subscription, fork-owned shards) win on overlap (plan D-9, D-3).

### Why an extension could not handle it

The generated catalog and its generator are build-time data the runtime loads before any extension exists.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): ai Anthropic and Bedrock adapters, Anthropic OAuth

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: Transcript pattern adopted: `stream`/`streamSimple` take `TranscriptContext`; `stream` resolves it once with `resolveTranscript(context, compat.supportsMidConvoSystemMessages)` and reads tools with `getCurrentTools` (Copilot vision headers, fine-grained-tool-streaming beta, Claude Code tool-name mapping, `buildParams`). `buildParams` takes the prompt from `getInitialSystemMessage` + `getSystemMessageText` (OAuth identity block + prompt, API-key prompt) and drops the leading system message from the converted turns. Upstream mid-conversation system messages adopted: later system messages (only kept when `compat.supportsMidConvoSystemMessages`) are held and emitted before the next assistant turn or at the end; a trailing system update carries the history cache checkpoint; the managed-effort checkpoint re-run stops at such an update. Upstream native tool changes adopted (`compat.supportsMidConvoSystemMessages && supportsMidConvoToolChanges`, an initial tool set, no redefinitions): initial tools active, `DEFERRED_TOOL_PLACEHOLDER` + later tools with `defer_loading`, `tool_addition`/`tool_removal` blocks, `mid-conversation-tool-changes-2026-07-01` beta. Fork kept: transcript-loaded deferral via `splitDeferredTools` + `tool_reference` results (`addedToolNames`, `supportsToolReferences`) now applies to the current transcript tool list and runs only when native tool changes are off; server-side fallback boundary pruning, discarded pre-fallback tool results, provider-native replay pairing, web-search replay gate, unsigned-thinking replay learning (`unsignedThinkingReplay`, per-session fallback set), Claude Code version recovery/too-old retry, forced tool-choice fallback, sticky/mid-output fallback receipts and abort, tool-loop cache checkpoints, effort markers, refusal fallbacks, extraBody, video blocks, `sanitizeAnthropicToolPairs`/`demoteUnavailableToolReferences` pre-submit passes. Claude Code version line: fork `2.1.284` (with the installer-rewrite comment) kept; upstream's bump to 2.1.280 is older than the fork value. `compat.allowedFallbackModels` kept on the fork's mixed `AnthropicAllowedFallbackModel | string` shape; fallback pricing matches object entries by provider+model and string entries by id. Renamed-model signed-thinking replay (upstream #9188) adopted: `message_start` keeps the requested id on `output.model` and records a different reported id in `output.responseModel`, so relabelling relays keep signed thinking replayable. Fork deviation: a served model that is one of the request's allowed fallbacks becomes `output.model` (genuine server-side fallback, same as the mid-output marker path). Adopted: `onProviderStreamEvent` for every raw SSE event; Vercel AI Gateway 1-hour cache writes read from `message_delta` (`cacheWrite1h`). `buildAnthropicWarmPromptCacheParams` keeps its public `Context` input (warmPromptCache, cache-keepalive) and normalizes with `normalizeContext` + `resolveTranscript`, so the warmed prefix equals the turn's. Thinking-drop notices (upstream #9391) live in interactive-mode (L6a); the adapter already captures `input_transformations`, nothing changes here.
- `packages/ai/src/api/bedrock-converse-stream.ts`: Upstream adopted: `TranscriptContext`, `collapseSystemMessages` (Bedrock has no mid-conversation system messages), prompt from the leading system message, tools from `getCurrentTools`, `withoutInitialSystemMessage` before `transformMessages`, `onProviderStreamEvent`, Bedrock one-hour cache-write pricing (`cacheWrite1h` from `cacheDetails`), `JsonObject`/`JsonValue` diagnostics typing. Fork kept: typed `ConverseStreamCommandInput` command input, `preserveThinking` + env conversion options, `appendMessage` user-turn merging, `normalizeToolParametersForBedrock`, `options.cacheRetention ?? model.cacheRetention`.
- `packages/ai/src/auth/oauth/anthropic.ts`: Fork body kept: `anthropic-callback-listener.ts` (prefers 53692, falls back to an ephemeral port, foreign-state 400 page, manual-only mode, #1503), 10-minute idle timeout, auth URL notified before the waits with the bound redirect URI (#2037), `authorization-input.ts`, `error-details.ts`, test node-API injection. Upstream `callback-server.ts` is not used by Anthropic: it has no bind-failure injection, no ephemeral-port fallback and only a generic state-mismatch page, which would drop #1503 and break the fork's OAuth tests. requires L2a (fork-only file outside L2d rows): `auth/oauth/anthropic-callback-listener.ts` still imports `./oauth-page.ts`, which upstream moved to `../../utils/oauth-page.ts`; the same move breaks `devin-callback.ts`. Recommended in the same edit: finish the login with the provider's `error_description` on an authorization-error redirect instead of waiting (upstream fix "browser sign-in waiting indefinitely after an authorization error").

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; the Anthropic and Bedrock adapters keep the fork refusal, unsigned-thinking, cache and callback-listener machinery and adopt the upstream transcript pattern (plan D-16).

### Why an extension could not handle it

Wire adapters and OAuth flows are provider internals below the extension API.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): ai OpenAI family and chatgpt-subscription

### What changed

- `packages/ai/src/api/azure-openai-responses.ts`: What changed: fork reasoning-effort mapping kept, upstream transcript tool placement adopted. Why / extension / zones: adapter internals; `buildParams` preamble.
- `packages/ai/src/api/openai-codex-responses.ts`: What changed: upstream transcript request body (`instructions` from the leading system message) and `onProviderStreamEvent` forwarded through every `mapCodexEvents` call, including the fork's cached-WebSocket stale-continuation retry loop; tool placement through `resolveResponsesToolPlacement`. Fork 429/usage-limit classification, wire identity, and retry-hint markers unchanged. Why: same as above; the codex adapter shares the Responses converter. Why an extension could not handle it: provider wire adapter internals. Expected merge conflict zones: import block, `buildRequestBody` tool placement, WebSocket retry loop.
- `packages/ai/src/api/openai-completions.ts`: What changed: adopted upstream transcript conversion (`resolveTranscript`, system messages, `supportsMidConvoToolAdditions` Kimi tools system messages), provider stream events, samplingParams merge, and the upstream regression tests. Restored the Kimi `deferredToolsMode: "kimi"` path upstream deleted: tools named by `addedToolNames` leave `tools` and load in a Kimi tools system message after the result, sharing one loaded-tools ledger with system-message additions. Fork compat resolution stays in `utils/prompt-cache-ttl.ts`. Why: keep fork lazy activation working on Kimi while adopting upstream's transcript mechanism. Why an extension could not handle it: completions message conversion is adapter-internal. Expected merge conflict zones: imports, `buildParams` tool placement, `convertMessages` preamble and tool-result branch.
- `packages/ai/src/api/openai-responses-shared.ts`: What changed: adopts upstream transcript conversion (`resolveTranscript`, leading system message as the instruction item, later system messages via `renderSystemMessageUpdate`, `toolsAdded` loaded in place as `additional_tools` or a client `tool_search_call`/`tool_search_output` pair, `onProviderStreamEvent`, unfinished-tool-call rejection #9974). Keeps the fork's `addedToolNames` deferral: new exported `resolveResponsesToolPlacement(messages, supportsToolAdditions)` returns upstream `requestTools` minus tools first named by a tool result's `addedToolNames` before any call to them, plus that `deferred` map (the rule is `splitDeferredTools` from `utils/deferred-tools.ts`, restored by L2a, applied to the transcript's current tools); `resolveResponsesDeferredToolsMode(compat)` picks `additional-tools` over `tool-search`. System-message additions and `addedToolNames` loads share one loaded-tools ledger so a tool loads once. Keeps fork `configurationUpdate`, `systemPromptCacheBreakpoint` (applied to the leading system message), context provenance sealing, freeform custom tool calls (looked up in `getDeclaredTools`), `withResponsesCompletionGrace`, `serviceTier: "fast"`, and namespace replay for same-model OR transcript-deferred tools. `ConvertResponsesToolsOptions.deferLoading` is now upstream's `toolSearchResult`. Why: upstream moved deferred tool loading into transcript system messages and deleted `utils/deferred-tools.ts`; fork lazy activation (`extensions/wrapper.ts`) and tool-search native loading still mark activations with `addedToolNames` (kept by the A2 contract). Why an extension could not handle it: request-item placement happens inside the Responses message converter; no hook sees the provider payload before items are ordered. Expected merge conflict zones: `convertResponsesMessages` preamble and system/tool-result branches, `convertResponsesTools` `defer_loading` spread, `processResponsesStream` loop head.
- `packages/ai/src/api/openai-responses.ts`: What changed: fork body kept (WebSocket transport, Copilot limits and diagnostics, allowed-tools #2095/#2234, prompt-cache comparison and prewarm #2096, Cloudflare base URL, forced tool-choice fallback, extraBody). Adopted: `TranscriptContext` input with `resolveTranscript`, `getDeclaredTools` for grammar tools, `onProviderStreamEvent`, provider-named error prefix #9298 plus the ChatGPT usage-limit note (vendored), Fast service-tier pricing, `model.samplingParams` merged under `options.samplingParams`. `applyAllowedToolsChoice` takes the transcript plus `context.activeToolNames` and references tools missing from the request placement. `warmOpenAIResponsesPromptCache` keeps its `Context` input and normalizes it. NOT adopted: `isChatGPTSignIn` request-field omission (the sign-in path is not exposed on `openai`). Why: upstream v0.99.1 adapter contract (transcript contexts) with the fork's larger adapter as the base (D-16). Why an extension could not handle it: provider wire adapter internals. Expected merge conflict zones: imports, stream() client/params construction, error formatting, `buildParams` placement/prompt-cache fields, samplingParams tail. openai 6.26.0 hold (lead 2026-09-29): `packages/ai/src/api/openai-responses.ts` `getPromptCacheOptions` returned upstream's openai 7.x-only `ResponseCreateParamsStreaming["prompt_cache_options"]`; it now returns the fork-local `OpenAIPromptCacheOptionsPayload | undefined` (same `{ mode: "explicit" }` / `{ ttl: "30m" }` payload as OURS), so the adapter typechecks against the pinned openai@6.26.0 with the wire payload unchanged.
- `packages/ai/src/providers/openai-codex.ts` (deleted): What changed: stays deleted (fork rename to `providers/chatgpt-subscription.ts`); upstream's only delta was the "(legacy)" display rename, which is not adopted. Expected merge conflict zones: modify/delete on every sync while upstream keeps the file.
- `packages/ai/src/providers/openai.ts`: What changed: upstream's `oauth: lazyOAuth({ name: "OpenAI (ChatGPT subscription)", loginLabel: "Sign in with ChatGPT", load: loadOpenAIChatGPTOAuth })` block and its import are stripped; the provider stays API-key only. `auth/oauth/openai-chatgpt.ts` stays vendored and unregistered. Why: ChatGPT sign-in is the `chatgpt-subscription` provider; a second login path would split the credential pool (D-4, Q2). Why an extension could not handle it: built-in provider registration. Expected merge conflict zones: the `auth` object and imports on every sync.

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; the OpenAI family keeps the fork chatgpt-subscription provider and deferral while adopting upstream transcript additions; the second ChatGPT login on `openai` is not exposed (plan D-4, D-10, D-16).

### Why an extension could not handle it

Wire adapters, provider registration and OAuth are provider internals below the extension API.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): ai Google, Mistral, auth and OAuth loading

### What changed

- `packages/ai/src/api/google-generative-ai.ts`: `packages/ai/src/api/google-generative-ai.ts`, `google-vertex.ts`: provider-native parts plus grounding / URL-context metadata blocks, `providerHeadersToRecord` header normalization, `applyExtraBody(... GOOGLE_RESERVED_BODY_KEYS)`, runtime `"off"` early disable (typed ThinkingLevel can still carry "off"), post-clamp `"off"` disable for non-reasoning models, `preserveThinking` tied to `options.thinking.enabled`.
- `packages/ai/src/api/google-shared.ts`: `packages/ai/src/api/google-shared.ts`: `appendContent` same-role turn folding (#2114, Cloud Code Assist single function-response turn), `convertMessages(model, context, { preserveThinking })` option, shared `normalizeToolCallId` from `utils/tool-call-id.ts`, `toProviderNativeContent` (executableCode / codeExecutionResult / dominant-part fallback), array-recursive `sanitizeForOpenApi`, position-aware `stripOptional`, `FinishReason.TOO_MANY_TOOL_CALLS` -> error.
- `packages/ai/src/api/google-vertex.ts`: `packages/ai/src/api/google-generative-ai.ts`, `google-vertex.ts`: provider-native parts plus grounding / URL-context metadata blocks, `providerHeadersToRecord` header normalization, `applyExtraBody(... GOOGLE_RESERVED_BODY_KEYS)`, runtime `"off"` early disable (typed ThinkingLevel can still carry "off"), post-clamp `"off"` disable for non-reasoning models, `preserveThinking` tied to `options.thinking.enabled`.
- `packages/ai/src/api/mistral-conversations.ts`: `packages/ai/src/api/mistral-conversations.ts`: `preserveThinking` replay control, `applyExtraBody(... MISTRAL_RESERVED_BODY_KEYS)`, `configurationUpdate` messages skipped, non-toolCall assistant blocks skipped when building tool calls, optional-chaining block checks.
- `packages/ai/src/auth/helpers.ts`: `packages/ai/src/auth/types.ts` / `helpers.ts`: `isSubscription`, `rejectedTokenStatuses` (GitHub Copilot server-side token revocation re-exchange) carried through `lazyOAuth`.
- `packages/ai/src/auth/oauth/load.ts`: `packages/ai/src/auth/oauth/load.ts` / `bun-oauth.ts`: `chatgptSubscription` loader and `loadChatGptSubscriptionOAuth` (no `openaiCodex` loader; fork deleted `openai-codex.ts`). `auth/oauth/load.ts` `loadOpenAIChatGPTOAuth` + `openaiChatGPT` loader, `bun-oauth.ts` bundles `openaiChatGPTOAuth` and `metaOAuth` (D-8) - the ChatGPT one is vendored inert: it is not registered on the `openai` provider by this lane (L2e strips `providers/openai.ts`).
- `packages/ai/src/auth/resolve.ts`: `packages/ai/src/auth/resolve.ts`: `PROVIDER_NOT_CONFIGURED_PREFIX` / `providerNotConfiguredMessage()`, OAuth refresh module (`OAuthRefreshExchangeError`, `OAuthRefreshStoreError`, `projectOAuthSlot`, `refreshOAuthCredential`) and pool `projectSlot` imports. `ModelsError` / `ModelsErrorCode` now live in upstream `utils/models-error.ts` (identical class and union) and are re-exported from `auth/resolve.ts`.
- `packages/ai/src/auth/types.ts`: `packages/ai/src/auth/types.ts` / `helpers.ts`: `isSubscription`, `rejectedTokenStatuses` (GitHub Copilot server-side token revocation re-exchange) carried through `lazyOAuth`.
- `packages/ai/src/bun-oauth.ts`: `packages/ai/src/auth/oauth/load.ts` / `bun-oauth.ts`: `chatgptSubscription` loader and `loadChatGptSubscriptionOAuth` (no `openaiCodex` loader; fork deleted `openai-codex.ts`). `auth/oauth/load.ts` `loadOpenAIChatGPTOAuth` + `openaiChatGPT` loader, `bun-oauth.ts` bundles `openaiChatGPTOAuth` and `metaOAuth` (D-8) - the ChatGPT one is vendored inert: it is not registered on the `openai` provider by this lane (L2e strips `providers/openai.ts`).

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; google/mistral/auth adopt the upstream shared thinking helpers and callback server while fork auth precedence stays (plan D-4).

### Why an extension could not handle it

Wire adapters and auth resolution are provider internals below the extension API.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Sync with upstream v0.99.1 (6a4af07d6): ai images and classifiers on the v6 model surface

### What changed

- `packages/ai/src/images-api-registry.ts`: Type renames per A2 C-AI-8/C-AI-9: `ImagesModel`/`ImagesApi` -> `ImageModel`/`ImageApi` in every L2c file; `ImagesFunction<TOptions>` one-parameter form (`api/openai-images.ts`, `providers/images/register-builtins.ts`, `images-api-registry.ts`). `images-api-registry.ts`: fork provider-scope accessor and strict mode (`installImagesProviderScopeAccessor`, `setImagesProviderScopeStrictMode`, scope overlay -> immutable builtin set lookup), exported `ImagesApiProviderInternal`, `registerBuiltinImagesApiProvider`, `resetImagesApiProviders`.
- `packages/ai/src/images.ts`: `images.ts`: fork re-export of the OpenAI image option types and parsers (`parseOpenAIImageOutputOptions`, `parseOpenAIImageSize`).
- `packages/ai/src/providers/images/register-builtins.ts`: Type renames per A2 C-AI-8/C-AI-9: `ImagesModel`/`ImagesApi` -> `ImageModel`/`ImageApi` in every L2c file; `ImagesFunction<TOptions>` one-parameter form (`api/openai-images.ts`, `providers/images/register-builtins.ts`, `images-api-registry.ts`). `providers/images/register-builtins.ts`: upstream OpenRouter lazy branch plus the fork OpenAI lazy branch (`generateImagesOpenAI`), both registered through the fork `registerBuiltinImagesApiProvider`; import failures still return an error `AssistantImages`.
- `packages/ai/src/providers/openrouter.ts`: `providers/openai.ts` gains `images: { "openai-images": openaiImagesApi() }` and lists `OPENAI_IMAGE_MODELS` next to `OPENAI_MODELS` (pattern of upstream `providers/openrouter.ts`). The fork OpenAI image rows (gpt-image-2.5-sunburst, gpt-image-2.5-flare, gpt-image-2, gpt-image-1.5, hand-declared costs incl. `imageInput`) come from L2b's static `OPENAI_IMAGE_MODELS` generator section; costs unchanged. `providers/openrouter.ts`: upstream typed `createProvider<"anthropic-messages" | "openai-completions">` with its `images`/`classifiers` maps (the fork comment about native Claude routing kept).
- `packages/ai/src/api/openrouter-images.ts`: `api/openrouter-images.ts` (silent): auto-merge accepted - upstream `ImageModel<ImageApi>`/one-parameter `ImagesFunction` plus the fork `cache_creation_tokens` cache-write fallback both present.

### Why

Upstream v0.99.1 (6a4af07d6) changed these paths while the fork carries its own behavior; images/classifiers migrate to the upstream unified v6 model surface with the fork OpenAI image rows and scoped registry kept (plan D-3, ADOPT).

### Why an extension could not handle it

Image model types and the images API registry are ai-package core consumed by the imagegen extension, not provided by it.

### Expected merge conflict zones

Every path listed above conflicts again where upstream edits the hunks named in its line; the fork-kept constructs named there are the anchors to preserve.

## 2026-09-30 - Derive custom-provider max effort from discovery and the built-in catalog (senpi#2456)

### What changed

- `packages/ai/src/models.ts` now resolves max effort in four steps: valid endpoint-discovery efforts first (their authoritative `thinkingLevelMap`, including an explicit no-max result), then any model-owned map, then any built-in catalog entry with the exact same model id that advertises max, then the unchanged `OPENAI_MAX_MODEL_IDS` / `MAX_MODEL_IDS` floors.
- `packages/ai/src/model-catalog.ts` records max-capable exact ids while the regenerated chat catalogs are flattened through `flattenChatModelCatalog`. This reuses the shipped catalog loader; provider-qualified ids remain qualified, exactly as `getBuiltinModel()` lookup treats them.
- `packages/ai/test/fixture-model-catalog.ts` injects stable max and no-max chat rows through `flattenChatModelCatalog`, so catalog regeneration cannot invalidate the regressions. `packages/ai/test/supports-xhigh.test.ts` covers a map-less custom model, an unknown map-less id, and the unchanged GPT/Claude floors; `packages/coding-agent/test/suite/models-discover.test.ts` covers an authoritative discovered low/high ladder for the injected max-capable id.

### Why

A custom OpenAI-compatible `kimi-k3` row without a `thinkingLevelMap` fell through to hand-kept id lists that did not include Kimi, so configured max and xhigh were clamped to high even though multiple built-in catalog entries advertise native max. Adding another hand-kept id would leave capability metadata split across two sources and repeat the bug for the next catalog model.

### Why an extension could not handle it

Reasoning-level availability is resolved in the core model capability path before extensions can safely repair every UI, clamp, and wire-adapter caller.

### Expected merge conflict zones

- LOW: `packages/ai/src/models.ts` max-tier capability detection and `packages/ai/src/model-catalog.ts` chat-catalog flattening.
- LOW: `packages/ai/test/supports-xhigh.test.ts` and `packages/coding-agent/test/suite/models-discover.test.ts` capability regressions.

## 2026-09-30 - GPT-6.1 Sol id inference: xhigh/max on, off vetoed for map-less rows (senpi#2390)

### What changed

- `packages/ai/src/models.ts`: `XHIGH_MODEL_IDS` and `OPENAI_MAX_MODEL_IDS` gain `gpt-6.1-sol`, so a custom provider that ships the id without a `thinkingLevelMap` still surfaces `xhigh` and `max` on the OpenAI-compatible APIs. `inferOpenAIThinkingLevelMap` applies the Astra-shaped map (`off: null`, `minimal: null`, low..max) to any id in the new `GPT_6_NO_NONE_EFFORT_MODEL_IDS` list (`gpt-6-astra`, `gpt-6.1-sol`) instead of to Astra alone, because GPT-6.1 Sol documents no `none` effort either.
- Catalog rows and generator changes for the same release are tracked in `packages/ai/changes.md`.

### Why

A `models.json` or gateway row for `gpt-6.1-sol` without a map would otherwise lose the two top efforts and keep `off` selectable, and selecting it would put `reasoning.effort: none` on the wire, which the model rejects (`test/gpt-6-family-catalog.test.ts`, map-less block).

### Why an extension could not handle it

Effort inference runs inside the model registry before any extension hook sees the model.

### Expected merge conflict zones

- `packages/ai/src/models.ts`: `inferOpenAIThinkingLevelMap` and the `XHIGH_MODEL_IDS` / `OPENAI_MAX_MODEL_IDS` constant block.

## 2026-09-29 - A reason-less forbidden rejection is retried, not treated as terminal (senpi#2376)

### What changed

- `packages/ai/src/utils/retry.ts`: `RETRYABLE_PROVIDER_ERROR_PATTERN` matches the Anthropic `forbidden` error whose message is only `Request not allowed` (either field order, optional status prefix), so `classifyErrorMessage` answers `retryable` instead of `unknown`.

### Why

- A Claude subscription path answered some requests with `{"type":"error","error":{"type":"forbidden","message":"Request not allowed"}}` while the same credential served neighbouring requests with 200, and the burst ended by itself. As "unknown" the session hopped down the fallback ladder at once, onto a provider that could not serve; a bounded same-model retry recovers. `permission_error` and `forbidden` rejections that name a reason stay terminal.

### Why an extension could not handle it

- Retry classification is the shared provider-error classifier every session and summarizer consults before any extension hook runs.

### Expected merge conflict zones

- LOW: the tail of `RETRYABLE_PROVIDER_ERROR_PATTERN` in `packages/ai/src/utils/retry.ts` (two added patterns).

## 2026-09-29 - A provider module removed by a reinstall ends the turn once (#2358)

### What changed

- `packages/ai/src/api/lazy.ts`: a setup failure whose error is a missing shipped `.js` module (`Cannot find module '<path>'`, or Bun's `ENOENT reading "<path>"`) becomes the message from `describeReplacedInstall()`, new in `utils/provider-failure-description.ts` beside the marker it stamps: `senpi:no-turn-retry:` plus "The installed package changed while this session was running, so <file> can no longer be loaded. Restart and resume this session to continue." Other setup failures keep their own text.

### Why

- After a package manager rewrote the install under a running session, the missing provider chunk failed the turn, then the same-model retries and every fallback model failed on the same missing module (#2358). The no-turn-retry marker stops both, and the text says what to do. A bare package name or a `.ts` source path is left alone, so a genuinely missing dependency still reads as itself.

### Why an extension could not handle it

- `lazyStream` builds the error message before any session or extension sees the failure.

### Expected merge conflict zones

- LOW: `createSetupErrorMessage` in `api/lazy.ts`; the end of `utils/provider-failure-description.ts`.

## 2026-09-29 - Cursor exec calls run once in the release bundle; bundle copies share module state (senpi#2334)

### What changed

- `packages/ai/src/utils/block-symbols.ts`: every block marker (`kStreamingPartialJson`, `kStreamingBlockIndex`, `kStreamingLastParseLen`, `kStreamingEnvelopeId`, `kStreamingBlockKind`, `kCursorExecResolved`) is a registry symbol (`Symbol.for("provider.block.<name>")`), so a block stamped by one copy of the module is recognized by another.
- `packages/ai/src/utils/process-singleton.ts` (new, browser-safe): `processSingleton(key, create)` keeps one value per process under `Symbol.for(key)` on `globalThis`.
- `packages/ai/src/session-resources.ts`: the cleanup registry is `processSingleton("@earendil-works/pi-ai:session-resource-cleanups")`.
- `packages/ai/src/cursor/context-limit-store.ts`: the observed limits, installed port and hydration flag live in `processSingleton("@earendil-works/pi-ai:cursor-context-limits")`.
- `packages/ai/src/utils/cursor-context-limit.ts`: the file persistence port, with its `savingEnabled` flag, is `processSingleton("@earendil-works/pi-ai:cursor-context-limit-file")`, so every copy installs the same port.
- `packages/ai/test/bundle-module-copies.test.ts` (new): loads two copies of each module (`vi.resetModules`) and checks the marker, the cleanup registry and the context-limit store are shared.

### Why

- The release bundle emits `chunks/cursor-agent.js` as a self-contained file (`splitting: false`), so it carries its own copy of every module it imports while the agent loop and the coding agent use the main graph's copy. With module-private `Symbol()` markers the loop never saw `kCursorExecResolved` on a block Cursor's exec channel had already executed and ran every exec-bridged tool call a second time under the same id, which replayed stale writes. The same split kept the Cursor conversation-cache cleanup out of the registry `AgentSession.dispose` runs, and kept an observed Cursor context ceiling from reaching the running session until a restart.

### Why an extension could not handle it

- The markers, the cleanup registry and the context-limit store are module state inside `pi-ai`; which copy a caller gets is decided by the release bundle, not by anything an extension controls.

### Expected merge conflict zones

- LOW: the `sessionResourceCleanups` declaration in `session-resources.ts` if upstream touches the registry.

## 2026-09-29 - The anthropic-subscription cold-seed refusal is a context overflow (senpi#2329)

### What changed

- `packages/ai/src/utils/overflow.ts`: `OVERFLOW_PATTERNS` gains `/^The conversation is too long to resend \(about \d+ tokens, limit \d+\)/` and the provider list comment names it, so `isContextOverflow` classifies the refusal the `anthropic-subscription` lane raises before re-sending a conversation that cannot fit ("The conversation is too long to resend (about N tokens, limit M). Compacting it and retrying.").

### Why

- The refusal must reach the same overflow recovery an API rejection does: senpi compacts its own history once and retries (oh-my-openagent#7975). Its wording is plain for the user, so it no longer matches the provider patterns.

### Why an extension could not handle it

- `isContextOverflow` is the shared classifier that core overflow recovery consults before any extension hook runs; only a core pattern can make the provider's own refusal count as an overflow.

### Expected merge conflict zones

- LOW: the head of `OVERFLOW_PATTERNS` in `packages/ai/src/utils/overflow.ts` and its provider list comment.

## 2026-09-29 - Claude Code fingerprint follows the latest release; Sonnet 5.5 request shaping (senpi#2321)

### What changed

- `packages/ai/src/utils/claude-code-version.ts` (new, browser-safe): `createClaudeCodeVersionResolver` (higher of the floor, a host-installed `ClaudeCodeVersionStore` cache and the latest published Claude Code from Anthropic's `latest` release channel and the npm dist-tag; one background refresh per six hours, never blocks, `offline` serves the cache only), `raise()` for a version a rejection names, `getClaudeCodeVersion(floor, env)` honoring `PI_CLAUDE_CODE_VERSION`, `isClaudeCodeVersionTooOldError`, `requiredClaudeCodeVersionFromError`, `recoverClaudeCodeVersion`, `claudeCodeVersionTooOldHint`.
- `packages/ai/src/utils/claude-code-version-cache.ts` (new, Node): `installClaudeCodeVersionFileStore()` installs the file cache at `<agent dir>/claude-code-version.json` (same agent-dir resolution as the cursor stores, atomic tmp+rename, one failed write disables saving) and passes `PI_OFFLINE` through as `offline`.
- `packages/ai/src/api/anthropic-messages.ts`: the `claudeCodeVersion` constant stays (2.1.284) as the bundled floor and the byte-for-byte declaration a downstream installer rewrites (`scripts/node-bundle-smoke.test.ts`); `createClient` reads `getClaudeCodeVersion(claudeCodeVersion, env)` per request for the OAuth `user-agent` and returns the advertised version. `stream` keeps an `openClient` closure; a `claude_code_version_too_old` 400 raises the version (the one the error names, else a refresh) and reopens the client for one retry; a second rejection, or a pinned version, appends the hint naming the advertised version and the pin variable. `DISABLED_THINKING_REJECTING_MODEL_MARKERS` adds `sonnet-5-5` / `sonnet-5.5`.
- `packages/ai/src/api/bedrock-converse-stream.ts`: `rejectsDisabledThinking` adds the same markers.
- `packages/ai/src/utils/prompt-cache-ttl.ts`: `FORCED_TOOL_CHOICE_REJECTING_MODEL_ID` covers `claude-sonnet-5[.-]5`.
- `packages/ai/test/claude-code-version.test.ts` (new): resolver, fetch, error parsing. `packages/ai/test/anthropic-oauth-claude-code-version.test.ts`: floor 2.1.284, exact pin, retry once with the named version, hint on the second failure, no retry when pinned. `packages/ai/test/anthropic-sonnet-5-5.test.ts` (new): catalog row and request shape.

### Why

- The fingerprint had gone stale twice (2.1.75 -> 2.1.251 -> 2.1.280), each time a 400 for OAuth users of a new model until a release. Claude Sonnet 5.5 (2026-09-28) requires Claude Code 2.1.284: the 2.1.283 binary does not contain the model id, 2.1.284 does. The Models API and live requests show Sonnet 5.5 rejects `thinking.type=disabled` and forced `tool_choice` exactly like Opus 5.5.

### Why an extension could not handle it

- The user-agent is set inside `createClient` and the rejection is caught inside the request retry loop; neither is reachable from an extension.

### Expected merge conflict zones

- MEDIUM: `createClient`'s OAuth branch and the `stream` request setup in `api/anthropic-messages.ts`; upstream still carries a constant there. LOW: the marker lists.

## 2026-09-29 - Auth resolution marks shared cloud credential chains as ambient (senpi#2327)

### What changed

- `packages/ai/src/auth/types.ts`: `AuthResult` and `AuthCheck` gain optional `ambient?: true`, set when auth came only from a shared cloud credential chain (AWS profile/keys/roles, Google ADC) rather than a credential configured for that provider.
- `packages/ai/src/providers/amazon-bedrock.ts`: `resolve` marks the environment `AWS_PROFILE`, `AWS_ACCESS_KEY_ID`+`AWS_SECRET_ACCESS_KEY`, ECS task role and web-identity branches `ambient: true`. A stored credential (key or chosen profile) and `AWS_BEARER_TOKEN_BEDROCK` (Bedrock-only) stay unmarked.
- `packages/ai/src/providers/google-vertex.ts`: `resolve` marks Application Default Credentials without a stored credential `ambient: true`; an API key or a stored credential stays unmarked.
- `packages/ai/src/models.ts`: `checkProviderAuth` carries `ambient` from the resolution into the `AuthCheck` it returns.

### Why

- AWS keys and ADC exist for many tools. With them in the environment, Bedrock was indistinguishable from a provider the user logged in to, and the coding agent made it the startup model over the user's own login (senpi#2327).

### Why an extension could not handle it

- The provenance is known only inside each provider's `resolve` and must travel through `Models.checkAuth`; no extension sees either.

### Expected merge conflict zones

- LOW: the `AuthResult`/`AuthCheck` interfaces in `auth/types.ts`; the ambient branches of the Bedrock and Vertex `resolve`; the api-key fallback line of `checkProviderAuth` in `models.ts`.

## 2026-09-28 - Copilot requests use the account's own API host (senpi#2309)

### What changed

- `packages/ai/src/api/github-copilot-endpoint.ts` (new): `resolveGitHubCopilotBaseUrl` picks the host from the token response's `endpoints.api` stored for that exact token (`copilotApiEndpoint: { tid, url }`, matched by the token's `tid`), then the token's `proxy-ep`, then the GHE domain, then `GITHUB_COPILOT_INDIVIDUAL_BASE_URL`. `parseGitHubCopilotApiEndpoint` accepts only https URLs without credentials.
- `packages/ai/src/auth/oauth/github-copilot.ts`: the token exchange stores `copilotApiEndpoint`; `/models`, model-policy updates and `toAuth` resolve through the new helper; the Individual picker fallback compares against the shared constant.
- `packages/ai/src/providers/github-copilot.ts`: the api-key lane (`COPILOT_GITHUB_TOKEN`, explicit keys) returns the token's `proxy-ep` host as `auth.baseUrl`.
- `packages/ai/src/api/github-copilot-errors.ts`: a Copilot 421 gets a note naming the wrong-host cause, the fix, and the GitHub request id.

### Why

- Business and Enterprise accounts are served from their own host; a request on the individual host is refused with `421 Misdirected Request` (omo#8662). The token response's `endpoints.api` was discarded, a token without `proxy-ep` fell back to the individual host even at refresh, and a token passed as a key never derived a host at all.

### Why an extension could not handle it

- The host is decided inside the bundled OAuth flow and the provider's auth resolution before any extension sees the request.

### Expected merge conflict zones

- LOW: `refreshGitHubCopilotAccessToken`'s return, the `getGitHubCopilotBaseUrl` call sites and `toAuth` in `auth/oauth/github-copilot.ts`; the `apiKey` line in `providers/github-copilot.ts`; the 421 branch in `api/github-copilot-errors.ts`.

## 2026-09-28 - Copilot account model limits drive compaction and output budgets (senpi#2299)

### What changed

- `packages/ai/src/auth/oauth/github-copilot.ts` persists the account catalog's normalized per-model limits on credentials returned by both login and refresh.
- `packages/ai/src/auth/oauth/github-copilot-model-catalog.ts`: the extracted Copilot catalog parser keeps positive `capabilities.limits.max_context_window_tokens`, `max_prompt_tokens`, and `max_output_tokens` beside the existing availability and policy results.
- `packages/ai/src/providers/github-copilot.ts` applies credential-scoped limits after filtering the generated catalog to the authenticated account.
- `packages/ai/src/providers/github-copilot-limits.ts`: the account prompt cap (falling back to the reported context window) overrides `Model.contextWindow`, the reported output cap overrides `Model.maxTokens`, malformed persisted values are ignored, and the generated model remains the fallback.
- `packages/ai/src/utils/overflow.ts` recognizes Copilot's `model_max_prompt_tokens_exceeded` code explicitly in addition to its existing prompt-count prose.

### Why

- Copilot's authenticated `GET /models` can advertise smaller prompt, context, and output limits than the native models.dev rows senpi generates. The previous parser discarded those fields. The public oh-my-pi Copilot discovery fix records `gpt-5.4` with a 272,000-token Copilot prompt cap versus its larger native total window, while senpi's generated Copilot row currently carries 1,000,000; without the credential overlay, pre-flight compaction starts after the account prompt cap. Source: https://github.com/can1357/oh-my-pi/pull/631
- Microsoft VS Code records the rejection as HTTP 400 with code `model_max_prompt_tokens_exceeded` and message `prompt token count of 13613 exceeds the limit of 12288`. Treating either preserved part of that response as context overflow routes the turn into the existing bounded compact-and-retry recovery.

### Why an extension could not handle it

- The account catalog is parsed and attached to the credential inside the bundled OAuth flow, before extensions can observe model availability. `Models.getAvailable()` applies the provider's credential-aware shaping before a model is selected, and the shared overflow classifier runs inside the harness recovery path before extension hooks can repair a terminal assistant error.

### Expected merge conflict zones

- LOW: `parseGitHubCopilotModelCatalog` was extracted from `auth/oauth/github-copilot.ts`; the OAuth orchestration stays unchanged apart from carrying `modelLimits` through the existing login and refresh return objects.
- LOW: `filterModels` in `providers/github-copilot.ts` and the GitHub Copilot regex row in `utils/overflow.ts`.

## 2026-09-28 - A Copilot token GitHub refuses is re-exchanged once; Copilot refusals are explained (senpi#2297)

### What changed

- `packages/ai/src/auth/types.ts`: `OAuthAuth` gains optional `rejectedTokenStatuses`, the HTTP statuses with which a provider refuses a stored access token before its own expiry says so.
- `packages/ai/src/auth/helpers.ts`: `lazyOAuth` forwards `rejectedTokenStatuses` so the flag is readable without loading the flow module.
- `packages/ai/src/auth/resolve.ts`: `AuthResolutionOverrides.rejectedAccess` names a token the provider just refused; `resolveStoredOAuth` treats a stored credential (or slot) still carrying it as stale and runs the normal compare-and-swap refresh, so a token another request already rotated is adopted instead of re-exchanged.
- `packages/ai/src/auth/oauth/github-copilot.ts`, `packages/ai/src/providers/github-copilot.ts`: GitHub Copilot declares `rejectedTokenStatuses` 401/403 (constant `GITHUB_COPILOT_REJECTED_TOKEN_STATUSES` in `packages/ai/src/api/github-copilot-headers.ts`).
- `packages/ai/src/api/openai-completions.ts`, `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/anthropic-messages.ts`: a `github-copilot` failure message is followed by the note from the new `api/github-copilot-errors.ts` (`withGitHubCopilotFailureNote`): quota exhaustion (402, 429 `quota_exceeded`, VS Code's quota codes) versus refusal (403, empty body called out), plus the `x-github-request-id`. `openai-responses.ts` now also sets `providerDiagnostic` on a failed `github-copilot` request (the other two adapters already set it for every provider) so the HTTP status reaches the runtime.
- `packages/ai/src/utils/retry.ts`: `classifyErrorMessage` and `isQuotaExhaustionMessage` drop request-id segments (new exported `stripProviderRequestIds` / `formatProviderRequestId` in the same file) before matching, because a hex id can contain `429` or `500`.

### Why

- GitHub revoked short-lived Copilot tokens server-side on 2026-09-28 while they still claimed ~22h of validity (Copilot tokens now live 24h). Every request on such a token got HTTP 403 with an empty body on every model; a fresh exchange for the same account succeeded. Refresh was expiry-only, so a session kept the dead token for up to a day, and `/login` appended a new slot while the session stayed on the old one. VS Code Copilot Chat drops its Copilot token on 401/403 and fetches a new one. The bare `403 status code (no body)` gave the user nothing to act on.

### Why an extension could not handle it

- Token staleness is decided inside `resolveStoredOAuth` under the credential-store compare-and-swap, and the refusal status only exists inside the adapters' catch blocks; an extension sees neither.

### Expected merge conflict zones

- LOW: `AuthResolutionOverrides` and the `resolveStoredOAuth` signature/staleness lines in `auth/resolve.ts`; the `OAuthAuth` interface in `auth/types.ts`; `lazyOAuth` in `auth/helpers.ts`; the error-assembly line in each adapter's catch block; `classifyErrorMessage` in `utils/retry.ts`.

## 2026-09-28 - A same-name re-login refresh survives the provider-pool merge (senpi#2222)

### What changed

- `packages/ai/src/auth/pool/slots.ts`: `mergeProvidedPool` still keeps `current` for every existing name, EXCEPT a same-name provided slot whose `expires` is strictly newer than the stored slot's (or the stored slot has none). That slot replaces the stored copy, dropping the stale token and any block fields it carried. `current` is still returned by identity when nothing was added or replaced. The comparison lives in the new `hasNewerMaterial` helper below it.
- `packages/ai/test/credential-pool-mutations.test.ts`: a same-name re-login with newer material replaces the stored slot and lifts its block while a sibling and the pin stay untouched; a sibling rotated during the browser round trip is still not rewound while the re-logged slot refreshes; an echo with equal material keeps `current`.
- `packages/coding-agent/test/suite/regressions/7084-anthropic-subscription-login-refresh.test.ts`: the provider's refreshed pool is pushed through `appendLoginSlot`, the persistence path `Models.login` uses, instead of being asserted only as the provider's return value.

### Why

- The anthropic-subscription recovery path (omo#7084) refreshes an auth-blocked slot in place: the provider returns its pool with that slot's fresh tokens under the SAME name. The 2026-09-10 merge treated every known name as stored-wins, so `Models.login` persisted `current` unchanged. The exchanged tokens were discarded, `blockReason: "auth_error"` stayed on disk, the account stayed "blocked until re-login", and the UI still reported a successful login (senpi#2222, oh-my-openagent#8673). A pre-login snapshot of a sibling is never newer than what concurrent writers stored, so the 2026-09-10 guarantee (no rewinding a rotated or blocked sibling) still holds.

### Why an extension could not handle it

- The merge runs inside the shared credential-store mutation that `Models.login` performs after the provider returns; an extension cannot change what the runtime writes under the credential lock.

### Expected merge conflict zones

- LOW: `mergeProvidedPool`, its JSDoc, and the new `hasNewerMaterial` helper directly below it in `auth/pool/slots.ts`.

## 2026-09-28 - A refused forced tool_choice is retried once and remembered per model; compat can declare it (senpi#2218)

### What changed

- `packages/ai/src/utils/tool-choice-fallback.ts`: `sendWithForcedToolChoiceFallback` owns the forced-choice retry for every adapter. It drops a forced `tool_choice` up front when the model declares `supportsForcedToolChoice: false` or refused one earlier in the process; otherwise it retries a classified 400 once without `tool_choice` and, when that retry is accepted and the refusal did not blame thinking, remembers the model (`api`, `provider`, `baseUrl`, `id`) in a process-level set read by `hasRefusedForcedToolChoice` and reset by `clearForcedToolChoiceRefusals`. The auto-only wording pattern now also matches Kiro's `Kiro supports only automatic tool choice or tool_choice:none`.
- `packages/ai/src/api/openai-completions.ts`, `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/anthropic-messages.ts`: `createRequest` sends through `sendWithForcedToolChoiceFallback` instead of an inline try/retry. `openai-responses.ts` calls `client.responses.create(...).withResponse()` directly again (the senpi#2224 transport-diagnostic wrapping is not part of this fix) and `getCompat` defaults `supportsForcedToolChoice` to `true`.
- `packages/ai/src/types.ts` (`OpenAICompletionsCompat`), `packages/ai/src/openai-responses-compat.ts` (`OpenAIResponsesCompat`): optional `supportsForcedToolChoice`.
- `packages/ai/src/utils/prompt-cache-ttl.ts`: `ResolvedOpenAICompletionsCompat` carries the optional flag and `getOpenAICompletionsCompat` passes the model's value through.

### Why

- The coding-agent first-turn plan opener forces `tool_choice` to `todo`. Kiro behind an OpenAI-compatible proxy refuses any forced choice with a wording the classifier did not match, so the first turn of every session failed (senpi#2218). Even with a matching wording, every new session paid the refused request again, and a provider known to be auto-only had no way to say so.
- A refusal that names thinking (`Thinking may not be enabled when tool_choice forces tool use.`) depends on the request's thinking setting, so remembering it would stop forcing the same model with thinking off.

### Why an extension could not handle it

- The refusal is only observable inside the adapter's `createRequest`; an extension sees the payload before it is sent (`before_provider_request`) and cannot retry the rejection or learn from it. The coding-agent todotools read the remembered refusal through the `./utils/*` export.

### Expected merge conflict zones

- LOW: the `createRequest` blocks in `api/openai-completions.ts`, `api/openai-responses.ts`, and `api/anthropic-messages.ts` if upstream restructures request sending.
- LOW: `OpenAICompletionsCompat` / `OpenAIResponsesCompat` field lists and `getOpenAICompletionsCompat` when upstream adds compat flags.

## 2026-09-27 - openai-responses falls back without tool_choice when a provider refuses the forced choice (senpi#2224)

### What changed

- `packages/ai/src/api/openai-responses.ts`: the SSE request path wraps `client.responses.create` in `createRequest`, which retries once without `tool_choice` when `isForcedToolChoiceUnsupportedError` matches and the sent `tool_choice` was forced (anything but `auto`/`none`), mirroring `openai-completions.ts`. (senpi#2218 moved this retry into the shared `sendWithForcedToolChoiceFallback`.)
- `packages/ai/src/utils/tool-choice-fallback.ts` `isForcedToolChoiceUnsupportedError`: the wording patterns accept `not currently compatible`/`not currently supported`, and a new pattern matches the auto-only refusal `only \`"auto"\` is supported for \`tool_choice\`` (observed on OmniRoute for `opencode-go/muse-spark-1.3-contributor`, 2026-09-27).
- `packages/ai/test/openai-responses-tool-choice.test.ts`: retry-without-tool_choice cases for the shared "not supported" wording and the #2224 auto-only wording, plus a no-retry case when `tool_choice` was not forced.

### Why

- The coding-agent first-turn todo forcing sends a named `tool_choice` on the session's first provider request. On `openai-responses` models that only accept `tool_choice: "auto"`, the request failed with a hard 400 and no retry, killing the session's first turn, while `openai-completions` and `anthropic-messages` already degraded to an unforced request for the same class of refusal (senpi#2224).

### Why an extension could not handle it

- The retry decision runs inside the adapter's `createRequest` after the provider rejects the request; an extension only sees the payload before it is sent (`before_provider_request`) and cannot observe or retry the rejection.

### Expected merge conflict zones

- LOW: the `requestOptions`/`retryProviderRequest` block in `api/openai-responses.ts` if upstream restructures the SSE request path or adds its own transport wrapping.
- LOW: the regex list in `utils/tool-choice-fallback.ts` (same zone as the senpi#2121 entry).

## 2026-09-28 - allowed_tools no longer names a tool a payload hook removed (senpi#2234)

### What changed

- `packages/ai/src/api/openai-responses.ts`: `applyAllowedToolsChoice` references a declared, active tool that is missing from `tools` only when `splitDeferredTools` deferred it to a transcript item. A function tool that a `before_provider_request` hook removed (the builtin `openai-web-search` extension swaps the `web_search` function for hosted `web_search_preview`) is no longer added back to `tool_choice: allowed_tools`. The new `resolveDeferredToolsMode` gives `buildParams` and `applyAllowedToolsChoice` the same deferred-mode decision.

### Why

- On a model that accepts `allowed_tools`, any inactive declared tool makes the adapter send `allowed_tools`, and the list named the hook-removed `web_search` function, which is not in `tools`. The Responses API rejects such a request with `400 Tool choice 'web_search' not found in 'tools' parameter.`, so native OpenAI sessions with default settings failed every turn.

### Why an extension could not handle it

- The adapter builds `tool_choice` after `onPayload` returns, so a `before_provider_request` hook never sees the `allowed_tools` list it would have to correct.

### Expected merge conflict zones

- LOW: the reference loop in `applyAllowedToolsChoice` and the deferred-mode lines at the top of `buildParams` in `openai-responses.ts`.

## 2026-09-27 - Show nested OpenAI Responses WebSocket errors (senpi#2235)

### What changed

- `packages/ai/src/api/openai-responses-shared.ts`: read nested WebSocket error details and HTTP status when a Responses error event has no top-level code or message, while retaining top-level SSE errors.

### Why

- Rejected WebSocket requests surfaced as `Error Code undefined: undefined` instead of the provider's actionable 400 error message.

### Why an extension could not handle it

- The shared Responses stream parser formats and throws the error before extensions receive a provider error.

### Expected merge conflict zones

- LOW: the `error` event branch in `processResponsesStream`.

## 2026-09-26 - Fold adjacent user messages for non-OpenAI Chat Completions (#2120)

### What changed

- `packages/ai/src/api/openai-completions.ts`: adjacent user messages are emitted as one user message with their content parts kept in order for non-`api.openai.com` hosts; direct OpenAI requests retain their existing message boundaries.
- `packages/ai/test/openai-completions-message-order.test.ts`: covers folding on a compatible host and preserving the direct OpenAI wire shape.

### Why

- OpenAI-compatible servers with alternation-enforcing chat templates reject a prompt followed by an extension or next-turn user message as consecutive user roles.

### Why an extension could not handle it

- The adapter builds the provider-specific message list after extension hooks run; only the converter can preserve content ordering while changing the wire role sequence.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/openai-completions.ts` near `convertMessages`; the new focused test is isolated from shared fixtures.

## 2026-09-27 - Terminal provider errors keep the provider Retry-After; quota exhaustion wording is shared (senpi#2198)

### What changed

- `packages/ai/src/utils/error-body.ts`: `normalizeProviderError` reads `retry-after-ms` / `retry-after` (delta-seconds or HTTP-date) / `x-ratelimit-reset*` from the SDK error's response headers for 429 and 503 statuses into `retryAfterMs`, and `formatProviderError` appends the canonical `(retry-after-ms: N)` marker when the message does not already carry one. Every adapter formatting its terminal error through `formatProviderError` (OpenAI completions/responses/codex, Azure, Google, OpenRouter images) now keeps the provider-requested wait.
- `packages/ai/src/utils/retry.ts`: the account quota/budget/credit/billing exhaustion patterns move into `QUOTA_EXHAUSTION_PATTERNS` (spread unchanged into `NON_RETRYABLE_PROVIDER_ERROR_PATTERN`) and are exposed through `isQuotaExhaustionMessage()`.

### Why

- With provider retries disabled (or exhausted), the SDK error's headers were dropped when the terminal message was formatted, so a provider `Retry-After` never reached the coding-agent fallback circuit breaker. The breaker also needs the terminal classifier's own quota wording to open circuits for `quota exceeded` / `out of budget` failures (senpi#2198, review of senpi#2201).

### Why an extension could not handle it

- The headers exist only on the SDK error object inside each adapter's catch block; nothing downstream of the formatted `errorMessage` can recover them.

### Expected merge conflict zones

- LOW: `NormalizedProviderError` and `formatProviderError` in `utils/error-body.ts`.
- LOW: the head of `NON_RETRYABLE_PROVIDER_ERROR_PATTERN` in `utils/retry.ts`.

## 2026-09-27 - Endpoint-advertised reasoning efforts (senpi#2196)

### What changed

- `packages/ai/src/index.ts`: re-exports the fork-only `endpoint-reasoning-efforts.ts` (`parseEndpointReasoningEfforts`, `EndpointReasoningEfforts`), which maps the `reasoning_efforts` an OpenAI-compatible `/models` entry advertises onto senpi's thinking levels. The fork-only `model.ts` gains an optional `defaultThinkingLevel`.
- `packages/ai/src/api/openai-completions.ts`: `streamSimple` keeps the `gpt-6-astra` off -> low fallback only when the model's thinking map has no string `off` value; an explicitly mapped off value (such as an endpoint-advertised `none`) is sent when reasoning is off.

### Why

- OpenAI-compatible endpoints advertise which effort values each model accepts and which one is the default; the coding-agent's `senpi models discover` turns that into a model's `thinkingLevelMap` and `defaultThinkingLevel` (prior art: gajae-code #5979).
- The Astra fallback turned an advertised `none` into `low`, enabling reasoning the endpoint was asked to disable.

### Why an extension could not handle it

- The mapper is a pure function of the package's own `ThinkingLevelMap` contract and belongs beside it so every consumer maps the same way; the barrel is the package's public entry. The off normalization happens inside the adapter while it builds the request, after any extension hook could influence the level.

### Expected merge conflict zones

- `packages/ai/src/index.ts`: the alphabetical `export *` block before `./env-api-keys.ts`.
- `packages/ai/src/api/openai-completions.ts`: the `normalizedReasoning` computation in `streamSimple`.

## 2026-09-28 - Bound GitHub Copilot requests to 128 tools (senpi#2298)

### What changed

- `packages/ai/src/api/openai-completions.ts`: after payload hooks and schema normalization, GitHub Copilot requests keep 128 serialized tools, preserving an explicitly forced tool even when it was declared later; they record how many definitions were omitted and replace a generic HTTP 400 `Bad Request` with a tool-limit explanation when that limit was applied.
- `packages/ai/src/api/openai-responses.ts`: after payload hooks, native-tool sanitizing, and allowed-tool selection, GitHub Copilot streaming requests apply the same forced-tool-preserving bound and diagnostic; prompt-cache prewarm requests apply the bound too. The transport now attaches the same structured HTTP diagnostic as Chat Completions, so a generic 400 can be identified safely.
- `packages/ai/src/api/anthropic-messages.ts`: after payload hooks and the final Anthropic tool-pair sanitizers, GitHub Copilot requests apply the same forced-tool-preserving bound, diagnostic, and generic-400 explanation.
- Fork-owned `packages/ai/src/utils/github-copilot-tool-limit.ts` owns the shared 128-tool bound, non-mutating selection, wire-shape-aware forced-tool lookup, diagnostic, and generic-400 explanation. Adapters only replace `params.tools` when the bound actually omitted definitions, preserving the payload object a hook returned for every other request.

### Why

- GitHub Copilot returned HTTP 400 with a plain-text `Bad Request` body when senpi sent 130 function tools to Chat Completions, while the same request without tools succeeded. VS Code Copilot independently enforces a 128-tool hard limit on endpoints without tool search. Current Copilot catalog rows advertise no native deferred-tool capability, so all three senpi adapters previously serialized every available tool. A blind first-128 slice could remove the tool selected by `tool_choice`, so the selected tool is retained in preference to the 128th unforced definition.

### Why an extension could not handle it

- Extensions can add or rewrite provider payloads through `onPayload`, so the bound must run after that hook at each adapter's final wire-shaping boundary. A higher-level extension cannot guarantee that every Copilot API route sends at most 128 tools or attach the provider diagnostic to the resulting assistant message.

### Expected merge conflict zones

- `packages/ai/src/api/openai-completions.ts`: the post-`normalizeRequestToolSchemas` request setup and the terminal error formatter.
- `packages/ai/src/api/openai-responses.ts`: the post-sanitizer request setup and prompt-cache prewarm body construction.
- `packages/ai/src/api/anthropic-messages.ts`: the final request sanitizing block after `extractPayloadRequestMetadata`.

## 2026-09-24 - Forced tool_choice refused under thinking falls back instead of failing (senpi#2121)

### What changed

- `utils/tool-choice-fallback.ts` `isForcedToolChoiceUnsupportedError` recognizes two more 400 wordings: Anthropic Messages `Thinking may not be enabled when tool_choice forces tool use.` and the OpenAI-compatible gateway `... so tool_choice cannot force tool use. Use tool_choice 'auto' or 'none'.` (observed on a gateway serving `claude-fable-5-1` over `openai-completions`). Both adapters already retry once without `tool_choice` when this classifier matches; nothing else changed.
- `test/anthropic-tool-choice-compat.test.ts` and `test/openai-completions-tool-choice.test.ts`: one retry case each, shown failing with the previous classifier.

### Why

- The coding-agent first-turn plan opener (senpi#2121) forces `tool_choice` to the todo tool where a provider accepts a named choice. A real-surface run through a gateway that serves an always-thinking Claude model on `openai-completions` returned this 400; the classifier did not match it, so the whole first turn failed instead of degrading to an unforced request. The Anthropic Messages wording had the same gap for thinking-enabled requests.

### Why an extension could not handle it

- The retry decision runs inside each adapter's `createRequest` after the provider rejects the request; an extension only sees the payload before it is sent (`before_provider_request`) and cannot observe or retry the rejection.

### Expected merge conflict zones

- `utils/tool-choice-fallback.ts` regex list if upstream widens it; the two test files' retry sections.

## 2026-09-24 - Build replayed reasoning_details from the input schema (senpi#2125)

### What changed

- `packages/ai/src/api/openai-completions.ts`: `stripStreamingIndex` is replaced by `toReplayableReasoningDetail` / `toReplayableReasoningDetails`, which CONSTRUCT each replayed entry instead of copying the stored one. An entry carries `type`, `id` and `format` when present, and exactly the payload its type defines: `reasoning.text` -> `text` plus optional `signature`, `reasoning.summary` -> `summary`, `reasoning.encrypted` -> `data`. `null` is preserved where the schema allows it (`id`, `signature`) because the provider sent it. The switch is exhaustive over the same union `isOpenAIReasoningDetail` validates, so a new detail type or payload field fails to compile until both sides agree. The call site at `assistantMsg.reasoning_details` is the only consumer, so both replay sources — the signed array parsed from a thinking block's `thinkingSignature` and the legacy encrypted detail parsed from a tool call's `thoughtSignature` — are projected. Stream assembly, `fillMissingCommonReasoningDetailFields`, and the persisted `thinkingSignature` are unchanged.

### Why

- A parsed detail is an open record (`OpenAIReasoningDetailBase` extends `Record<string, JsonValue>`) and `isOpenAIReasoningDetail` only type-checks the fields it knows, so every other key survived into the request. senpi#2122 removed one such key, `index`, by name; any other output-only key reproduces the same permanently-wedged conversation, because a gateway that validates its input reasoning schema rejects the request and the offending key lives in stored history. Constructing the entry makes every unknown key absent by construction rather than by name, which is how `assistantMsg.tool_calls` in the same function has always been built (`{ id, type, function: { name, arguments } }`) — the reasoning replay was the one path that echoed a stored object.

### Why an extension could not handle it

- The projection runs inside `convertMessages` while the adapter builds the Chat Completions request; `onPayload` sees the finished body and would have to re-derive the reasoning-detail conversion to repair it.

### Expected merge conflict zones

- LOW: the helper beside `appendOpenAIReasoningDetail` and the single `assistantMsg.reasoning_details` assignment in `convertMessages` (`openai-completions.ts`).

## 2026-09-24 - Replay reasoning_details without the streaming index (senpi#2122)

### What changed

- `packages/ai/src/api/openai-completions.ts`: new `stripStreamingIndex` maps the preserved reasoning details through a copy without `index` at the single assignment site (`assistantMsg.reasoning_details`), so both sources — a signed array parsed from `thinkingSignature` and the legacy encrypted detail parsed from a tool call's `thoughtSignature` — are sanitized. Stream assembly is untouched: `appendOpenAIReasoningDetail` still merges by adjacency and `fillMissingCommonReasoningDetailFields` still carries `index`, and the stored `thinkingSignature` keeps it, so nothing on disk changes. The same file also gained `OPENAI_COMPLETIONS_REASONING_FIELDS` / `isOpenAICompletionsReasoningField`, and the thinking-signature replay branch now assigns a property only when the signature is one of those known reasoning field names.
- `packages/ai/src/utils/retry.ts`: `RETRYABLE_PROVIDER_ERROR_PATTERN` gained `"must not contain streaming index"`, next to the Anthropic server-tool pairing entry and for the same reason.

### Why

- A gateway validates that an input reasoning entry must not carry the streaming-assembly `index` and answers `the reasoning_details at position 1271 entry 0 must not contain streaming index`. The merged array is persisted verbatim in the assistant block and replayed on every later request, so one such turn rejected every following request in that conversation. The message matched neither classification pattern, so `classifySenpiAssistantFailure` fell through to a structured status that an in-stream gateway error does not carry and returned `terminal`: the turn ended with no retry and no fallback. `index` orders deltas while a response streams, is absent from non-streamed responses, and carries nothing on the input side where array order already is the sequence — so it is consumed, never echoed. Classifying the rejection retryable is sound for the same reason the pairing class is: the builder repairs the replayed history deterministically before the retried request is built, and the retry stays bounded by the policy's attempt budget.
- The signature slot is overloaded — it names the reasoning field to replay for llama.cpp server + gpt-oss, but it holds serialized `reasoning_details` for OpenRouter-style providers. Passing the latter to `Object.assign` created a property whose name was the entire serialized array, duplicating the reasoning into every later request; restricting the branch to the three known field names leaves the llama.cpp/gpt-oss and OpenCode Go paths (`reasoning` remapped to `reasoning_content`) untouched.

### Why an extension could not handle it

- Both the sanitized array and the offending property are produced inside `convertMessages` while the adapter builds the Chat Completions request; `onPayload` sees the finished body and would have to re-derive the reasoning-detail conversion to repair it. The retry classification runs in the shared provider-error path before any hook.

### Expected merge conflict zones

- LOW: the `preservedReasoningDetails` assignment and the thinking-signature replay branch in `convertMessages` (`openai-completions.ts`), plus the new helpers beside `appendOpenAIReasoningDetail`; one added entry in `RETRYABLE_PROVIDER_ERROR_PATTERN` (`utils/retry.ts`).

## 2026-09-24 - Fold adjacent same-role messages for Bedrock Converse and Gemini (senpi#2114)

### What changed

- `packages/ai/src/api/bedrock-converse-stream.ts`: `convertMessages` pushes every Converse message through the new `appendMessage`, which appends the content blocks of a message whose role matches the previous wire message to that message instead of opening a new one. Adjacent user messages (text and image blocks) and a user prompt that follows the merged tool-result user message become one user message, blocks in order. The cache point is still appended after the loop, so it lands at the end of the merged last user message.
- `packages/ai/src/api/google-shared.ts`: `convertMessages` pushes every `Content` through the new `appendContent` with the same rule. It replaces the Cloud Code Assist special case that merged only a function response into a previous function-response turn, and the Gemini < 3 "Tool result image:" parts now join the tool-result user turn instead of opening an adjacent one (which had also split the function responses of one model turn across two user turns). `google-generative-ai.ts` and `google-vertex.ts` use this converter and are unchanged.

### Why

- Since senpi#2106 the coding agent sends a hidden environment-context user message right before the prompt, so a first turn carries two adjacent user messages. Bedrock Converse rejects a conversation whose roles do not alternate ("A conversation must alternate between user and assistant roles"), and Gemini expects `contents` to alternate between user and model (the `@google/genai` Chat history contract; generateContent answers 400 "Please ensure that multiturn requests alternate between user and model").
- Audited and left unchanged because their providers accept adjacent same-role messages: `mistral-conversations.ts` (mistral-common `_validate_message_order` allows user after user and user after tool), `anthropic-messages.ts` (the Messages API combines consecutive same-role turns), and the OpenAI Chat Completions / Responses adapters.

### Why an extension could not handle it

- The Converse and Gemini wire messages are built inside the adapters' `convertMessages`; `onPayload` sees the finished request, and rewriting role sequences there would duplicate each adapter's block conversion and cache-point placement.

### Expected merge conflict zones

- MEDIUM: `convertMessages` in `bedrock-converse-stream.ts` (the three `result.push` sites for user, assistant, and tool-result messages) and in `google-shared.ts` (the user, model, and function-response push sites plus the removed Cloud Code Assist merge block).

## 2026-09-24 - Shared lenient tool-name matcher (senpi#2111)

### What changed

- `packages/ai/src/utils/tool-name-match.ts` (new, fork-only): `resolveToolNameMatch(requested, available)`, `toolNameForms`, and `foldToolName`. Names compare with case and `-`/`_` folded away. An `mcp_`/`mcp__` prefix in any case is stripped on both the requested and the registered side. It is cut only at its delimiter: `__` for `mcp__<id>__<name>` (the id may contain `_`), and the first `_` for `mcp_<server>_<tool>`. It is never cut inside the tool's own name, so `mcp__sandbox__run_bash` cannot resolve to a local `bash`. Each form is tried most specific first (exact, fold, then a registered tool whose unprefixed name folds the same) before a shorter form, so `mcp__gh__pull_request_read` picks `mcp_github_pull_request_read` over `read`. A step resolves only on a unique match.
- `packages/ai/src/api/anthropic-tool-references.ts`: the native tool-search reference repair resolves names through `resolveToolNameMatch` instead of its own `GATEWAY_TOOL_NAMESPACE` regex and fold map.

### Why

- The inbound tool-call resolver in `packages/agent` and this repair each carried a copy of the rule, and the copies drifted (senpi#2104). One matcher keeps the two paths accepting the same shapes.

### Why an extension could not handle it

- The tool-reference pass runs inside the Anthropic adapter while it builds the request, and the agent loop resolves tool-call names before any hook runs.

### Expected merge conflict zones

- LOW: `collectAvailableToolNames` and the `resolve` binding in `anthropic-tool-references.ts` (fork-only); `utils/tool-name-match.ts` is new.

## 2026-09-24 - Strip a gateway tool-reference namespace whatever the casing of its prefix (senpi#2104)

### What changed

- `packages/ai/src/api/anthropic-tool-references.ts`: `GATEWAY_TOOL_NAMESPACE` matches the `mcp__<id>__` prefix case-insensitively, so a replayed native tool-search reference such as `Mcp__a4e6__Memory` folds onto the request's `memory` tool instead of being dropped. The unique-match rule is unchanged.

### Why

- The inbound tool-call resolver (senpi#2104) had the same lowercase-only regex. Both copies of the rule now accept any casing of the prefix, so the two paths agree.

### Why an extension could not handle it

- The tool-reference pass runs inside the Anthropic adapter while it builds the request, before any extension sees the payload.

### Expected merge conflict zones

- LOW: the `GATEWAY_TOOL_NAMESPACE` line in `anthropic-tool-references.ts` (fork-only).

## 2026-09-24 - Prewarm the GPT-5.6+ prefix and record prompt_cache_diagnostics (senpi#2096)

### What changed

- `packages/ai/src/api/openai-responses.ts`: `buildParams` adds `prompt_cache_options.comparison_response_id` (the most recent completed same-model assistant `responseId` in `context.messages`) for native `api.openai.com` models with `compat.supportsExplicitPromptCacheMode`, unless `cacheRetention` is `none`. The existing `mode`/`ttl` fields are unchanged. `streamSimple`'s option mapping moved into `resolveSimpleOptions`, which the new `warmOpenAIResponsesPromptCache` also uses: it builds the next turn's payload with an empty conversation (system prompt + tools only), runs `onPayload` and native-tool sanitizing, sends it non-streaming with `prompt_cache_options.prewarm: true` and a 30 s default timeout, and returns priced usage.
- `packages/ai/src/api/openai-responses.ts` (same function): when `compat.supportsExplicitPromptCacheMode` is set and `cacheRetention` is not `none`, `buildParams` asks `convertResponsesMessages` for `systemPromptCacheBreakpoint`, so every turn and the prewarm send the system prompt as `[{ type: "input_text", text, prompt_cache_breakpoint: { mode: "explicit" } }]`. `cacheRetention` is now resolved before the input conversion.
- `packages/ai/src/api/openai-responses-shared.ts`: `finalizeResponse` stores the terminal response's `prompt_cache_diagnostics` on `output.promptCacheDiagnostics`. `ConvertResponsesMessagesOptions.systemPromptCacheBreakpoint` emits the system/developer item as one `input_text` block with `prompt_cache_breakpoint: { mode: "explicit" }` instead of a plain string.
- `packages/ai/src/types.ts`: new `PromptCacheDiagnostics` and the optional `AssistantMessage.promptCacheDiagnostics` field.
- `packages/ai/src/index.ts`: exports `isOpenAIResponsesPromptCacheModel`.
- `packages/ai/src/api/openai-responses.lazy.ts`: registers the OpenAI Responses prompt-cache warmer (a lazy `import()` of `openai-responses.ts`) in the new `prompt-cache-warmers.ts` table, next to `openAIResponsesApi`.
- Fork-owned: `packages/ai/src/api/openai-responses-prompt-cache.ts` (new, SDK-free eligibility, comparison-id lookup, diagnostics parser), `packages/ai/src/api/prompt-cache-warmers.ts` (new, api-keyed warmer table), and `packages/ai/src/api/warm-prompt-cache.ts` (`warmPromptCache` dispatches eligible OpenAI Responses models to the registered warmer, returns `{ supported: false }` for `cacheRetention: "none"` or when no warmer is registered, and accepts the next turn's `reasoning`, `thinkingSelection`, `thinkingBudgets`, `serviceTier`, and `extraBody` so the warm request carries the same fields). The table keeps the browser-safe root barrel from reaching the OpenAI SDK: a direct `import()` from `warm-prompt-cache.ts` put `openai` into the Anthropic-only selective-provider bundle (`scripts/check-browser-smoke.mjs`).

### Why

Live platform probes (gpt-6-luna, `store: false`) showed `prompt_cache_options.prewarm` writes the instructions + tools prefix with no output and the next request reads it (but with the hosted `web_search_preview` tool present the next request read 0 of a prewarmed prefix until the system block carried an explicit `prompt_cache_breakpoint`; with it, 9,508 of 9,583 tokens were read), and `comparison_response_id` returns `cache_hit` / `cache_miss` with a reason (`reasoning_effort_changed`, `service_tier_changed`, ...). senpi had neither: the first turn always paid a cold prefix and misses were unexplained.

### Why an extension could not handle it

`prompt_cache_options` is written inside the Responses request builder and `prompt_cache_diagnostics` is only visible on the raw terminal event inside the stream parser, before any extension observes the payload or the assistant message.

### Expected merge conflict zones

- `packages/ai/src/api/openai-responses.ts`: imports, the `MutableResponsesPayload` type, `streamSimple` (now delegating to `resolveSimpleOptions`), the new `warmOpenAIResponsesPromptCache` after it, and the `prompt_cache_key` / `prompt_cache_options` fields in `buildParams`.
- `packages/ai/src/api/openai-responses-shared.ts`: the import block, the `responseId` assignment in `finalizeResponse`, `ConvertResponsesMessagesOptions`, and the system-prompt push at the top of `convertResponsesMessages`.
- `packages/ai/src/api/openai-responses.ts`: the `cacheRetention` line moved above the `convertResponsesMessages` call in `buildParams`.
- `packages/ai/src/types.ts`: the new interface before `StopReason` and the `AssistantMessage` field after `diagnostics`.
- `packages/ai/src/index.ts`: the export line before `convertResponsesMessages`.
- `packages/ai/src/api/openai-responses.lazy.ts`: the import block and the registration call after `openAIResponsesApi`.

## 2026-09-24 - Restrict callable tools with allowed_tools instead of rewriting tools (senpi#2095)

### What changed

- `packages/ai/src/openai-responses-compat.ts`: new `supportsAllowedTools` compat flag and the `supportsAllowedToolChoice(model)` predicate.
- `packages/ai/src/types.ts`: `Context.activeToolNames`, the subset of `tools` the model may call on this request.
- `packages/ai/src/api/openai-responses.ts`: `getCompat` resolves `supportsAllowedTools` (default false). After the payload hook and native-tool sanitizing, `applyAllowedToolsChoice` keeps `tools` untouched and, when some declared tool is inactive, sends `tool_choice: { type: "allowed_tools", mode: "auto", tools }` listing the active function/custom tools, every hosted tool in the payload, and active deferred tools by name; an empty list sends `tool_choice: "none"`. An explicit `toolChoice`, a model without the flag, or an absent `activeToolNames` leaves the request unchanged.
- `packages/ai/src/index.ts`: exports `supportsAllowedToolChoice`.

### Why

Removing one function tool between turns rewrites the `tools` prefix and drops the prompt cache to 0 cached tokens. A live gpt-6-luna probe kept the full ~5k-token prefix cached (`cache_hit`) when the same tools were sent and the callable subset moved to `allowed_tools` (developers.openai.com/api/docs/guides/prompt-caching#manage-tools-with-append-only-updates).

### Why an extension could not handle it

`tool_choice` and `tools` are built inside the Responses adapter from the context the agent loop passes; the compat flag and the context field are part of the AI package contract.

### Expected merge conflict zones

- `packages/ai/src/api/openai-responses.ts`: the responses type import, `getCompat`, the new function above `formatOpenAIResponsesError`, and the line after `sanitizeUnsupportedNativeTools` in `stream`.
- `packages/ai/src/types.ts`: the `Context` interface. `packages/ai/src/index.ts`: one export line. `packages/ai/src/openai-responses-compat.ts`: the compat interface tail.

## 2026-09-24 - Parse gateway cache_creation_tokens as prompt-cache writes (senpi#2091)

### What changed

- `packages/ai/src/api/openai-responses-shared.ts`: terminal Responses usage mapping reads `input_tokens_details.cache_write_tokens` when present and otherwise `cache_creation_tokens` as `usage.cacheWrite`, still subtracting both cache read and cache write from `input_tokens`.
- `packages/ai/src/api/openai-completions.ts`: `parseChunkUsage` does the same for `prompt_tokens_details` (`cache_write_tokens` wins, else `cache_creation_tokens`). DeepSeek `prompt_cache_hit_tokens`, Kimi top-level `cached_tokens`, and OpenRouter `cache_write_tokens` mapping are unchanged.
- `packages/ai/src/api/openrouter-images.ts`: `parseUsage` uses the same write-field preference; OpenRouter's existing subtract-writes-from-`cached_tokens` behavior is unchanged.

### Why

OpenAI-compatible gateways report prompt-cache writes as `cache_creation_tokens` while the OpenAI platform uses `cache_write_tokens`. Ignoring the gateway field billed those writes as uncached input (`cacheWrite` stayed 0).

### Why an extension could not handle it

Usage is parsed inside the OpenAI Completions, Responses, and OpenRouter images adapters before any extension observes the assistant message.

### Expected merge conflict zones

- `packages/ai/src/api/openai-responses-shared.ts`: the `response.usage` mapping in `finalizeResponse`.
- `packages/ai/src/api/openai-completions.ts`: `parseChunkUsage` and its `prompt_tokens_details` type.
- `packages/ai/src/api/openrouter-images.ts`: `parseUsage` and its `prompt_tokens_details` type.

## 2026-09-24 - Omit session prompt_cache_key on GPT-5.6+ OpenAI API (senpi#2097)

### What changed

- `packages/ai/src/api/openai-responses.ts`: `buildParams` omits `prompt_cache_key` for native `api.openai.com` GPT-5.6+ models (`compat.supportsExplicitPromptCacheMode` or `cost.cacheWrite > 0`). Pre-5.6 models still send the clamped session id. `cacheRetention: "none"` still omits it.
- `packages/ai/src/api/openai-completions.ts`: the same omit on `api.openai.com` when `cost.cacheWrite > 0`. Other send conditions (long retention, `supportsPromptCacheKey`) are unchanged.

### Why

On GPT-5.6 and later, OpenAI treats `prompt_cache_key` as cache-accounting only. A per-session value returns `prompt_cache_key_changed` and a full miss even when the prefix is identical, so forks and task children cannot reuse the parent's cached prefix. Live probes on gpt-6-luna showed key-less requests share the prefix across sessions.

### Why an extension could not handle it

The key is written inside the provider request builders (`packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-completions.ts`) before any extension observes the payload.

### Expected merge conflict zones

- `packages/ai/src/api/openai-responses.ts`: the `prompt_cache_key` field in `buildParams`.
- `packages/ai/src/api/openai-completions.ts`: the `prompt_cache_key` ternary in `buildParams`.

## 2026-09-24 - configuration_update follows a catalog capability flag (senpi#2094)

### What changed

- `packages/ai/src/openai-responses-compat.ts`: `OpenAIResponsesCompat.supportsConfigurationUpdate` (boolean, default false) marks models that accept Responses `configuration_update` input items.
- `packages/ai/src/models.ts`: new `supportsConfigurationUpdate(model)`, true only for a Responses-family api (`openai-responses`, `openai-codex-responses`, `azure-openai-responses`) whose `compat.supportsConfigurationUpdate` is true.
- `packages/ai/src/api/openai-responses-shared.ts`: the `configurationUpdate` branch of `convertResponsesMessages` gates on `supportsConfigurationUpdate(model)` instead of `model.id === "gpt-6-astra"` on `openai` / `chatgpt-subscription`; adjacent updates still coalesce into one item.
- `packages/ai/src/api/openai-responses.ts`: `getCompat` resolves `supportsConfigurationUpdate` (default false) with the other `Required<OpenAIResponsesCompat>` fields.
- `packages/ai/src/providers/data/openai.json`, `packages/ai/src/providers/data/chatgpt-subscription.json`, `packages/ai/src/providers/data/.manifest.json`: the flag lands on the 12 `openai` GPT-5.6/GPT-6 rows (base and `-fast`) and on `chatgpt-subscription` `gpt-6-astra` / `gpt-6-astra-fast`; no other field changed.
- `packages/ai/test/openai-config-update.test.ts`: flagged and unflagged catalog rows, the api guard, and the exact flagged set per provider.

### Why

A top-level `reasoning.effort` change rewrites the hidden instructions and discards the cached prefix (live probe 2026-09-24: cached 0, diagnostics `reasoning_effort_changed` on gpt-6-luna and gpt-5.6-luna), while an appended `configuration_update` keeps it (4882 / 4879 cached tokens) and still changes effort. The literal `gpt-6-astra` gate threw that cache away on every other model that accepts the item.

### Why an extension could not handle it

The Responses input list is built inside `convertResponsesMessages` before the request leaves the package; an extension sees neither the item list nor the model's wire capabilities.

### Expected merge conflict zones

- `packages/ai/src/api/openai-responses-shared.ts`: the `configurationUpdate` branch at the top of the message loop and the `../models.ts` import.
- `packages/ai/src/models.ts`: the block after `supportsMax` and the `./types.ts` type import.
- `packages/ai/src/openai-responses-compat.ts`: the field after `supportsExplicitPromptCacheMode`.
- `packages/ai/src/api/openai-responses.ts`: the `getCompat` return object.
- `packages/ai/src/providers/data/*.json` + `.manifest.json`: regenerate rather than merge.

## 2026-09-23 - Cursor variant grouping derived from the live catalog (senpi#2038)

### What changed

- `packages/ai/src/cursor/catalog-grouping.ts`: adds the pure `deriveCursorVariantAliases(ids)` export. For raw ids `cursor-variant-aliases.json` does not list, it derives family aliases (base id, with the `-thinking` infix as a separate identity, requiring `>= 2` distinct observed levels in the same batch; `-fast`, single-level, and level-less ids stay flat). `normalizeCursorCatalog` resolves `static alias ?? derived alias`, so static-table output stays byte-identical. Derivation rejects targets that are a static identity, a static alias key (a derived `gpt-5.5-high` would shadow the static `gpt-5.5-high` alias of `gpt-5.5`), or a raw batch id; duplicate normalized levels choose the exact normalized suffix deterministically and leave other ids flat. Derived capability lookup uses the original member's base id, even when the target ends in a level token; derived groups get `capabilityId`/`window` (capability row or `FALLBACK_WINDOW`), a total `thinkingLevelMap` (observed levels map to their raw suffix and every unobserved level is `null`, because the shared model contract treats an absent ordinary level as supported and would offer and silently substitute levels the server never listed), `representativeVariantId`, `legacyAliases`, and the new `variantIds` map (normalized level -> exact server-listed variant id). Declares `CursorCatalogEntry.variantIds`.
- `packages/ai/src/model.ts`: declares `CursorAgentCompat.cursorReasoning.variantIds` (`Readonly<Partial<Record<ModelThinkingLevel, string>>>`), present only on derived identities.
- `packages/ai/src/cursor/selection-descriptor.ts`: `resolveCursorSelectionDescriptor` resolves explicit selections through `cursorReasoning.variantIds` before any capability lookup (a level missing from `variantIds` falls back to the representative instead of silently downgrading), and legacy-variant selections accept ids that are static aliases or `variantIds` values.
- `packages/ai/src/cursor/store-migration.ts`: `regroupStoredCursorModels` treats stored flat entries whose ids derivation groups as legacy and regroups them over the stored batch, idempotently and in stable order; it coalesces flats and an existing derived identity at their first position, preserving existing metadata on conflicting levels. Conflicting raw levels remain flat and wire-selectable (only ids represented by the retained `variantIds` map are consumed); coalescing duplicate stored identities also runs when no new level was added, keeping the first position and its metadata. An existing grouped identity, static or derived, wins over flat rows aliasing it regardless of input order: a static group absorbs its flat alias rows, filling only levels it lacks (`absorbStaticLevels`) while its representative and compat stay unchanged. `entryToModel` copies `variantIds` into `cursorReasoning`.
- `packages/ai/src/providers/cursor.ts`: `fetchCursorModels` copies `entry.variantIds` into `compat.cursorReasoning.variantIds`.
- `packages/ai/test/cursor-derived-variant-grouping.test.ts` (`// senpi#2038`): coverage over the 2026-09-23 unlisted-ids fixture, target collisions, duplicate levels, parser base ids, and mixed-store migration in both orders; `cursor-derived-supported-levels.test.ts` pins supported levels, clamping, and wire ids for every derived family; `cursor-store-migration-mixed-groups.test.ts` pins static groups mixed with flat aliases, including the provider restore path.

### Why

Cursor shipped suffix families after the 2026-08-18 alias snapshot (`grok-4.7`, `claude-opus-5-5`, `claude-fable-5-1` plus its thinking variants, `gemini-3.8-flash`, `muse-spark-1.3`); ids absent from the static table became singleton flat models (reasoning false, 200k fallback window), and `resolveCursorSelectionDescriptor` returned the representative (medium) whenever the capability row was missing, so `senpi --model cursor/grok-4.7:low` and `:xhigh` both ran `grok-4.7-xhigh-fast` with thinking off. Deriving the grouping from the observed `GetUsableModels` batch fixes selection for new families without touching the static snapshot or its byte-identical output.

### Why an extension could not handle it

The grouping runs inside `normalizeCursorCatalog` / `regroupStoredCursorModels` during catalog normalization and store restore, before any extension observes model identities; selection resolution happens inside the Cursor transports' descriptor resolution, which extensions cannot intercept.

### Expected merge conflict zones

- `packages/ai/src/cursor/catalog-grouping.ts`: the `CursorCatalogEntry` interface tail, static target collision guard, duplicate-level selection in derivation, and derived capability lookup in `normalizeCursorCatalog`.
- `packages/ai/src/cursor/selection-descriptor.ts`: the selection blocks of `resolveCursorSelectionDescriptor`.
- `packages/ai/src/cursor/store-migration.ts`: `absorbStaticLevels`, the existing-group reservation, the legacy classification, mixed-store conflict filtering and unconditional identity coalescing loop, and the `entryToModel` compat spread.
- `packages/ai/src/model.ts`: the `cursorReasoning` block of `CursorAgentCompat`.
- `packages/ai/src/providers/cursor.ts`: the `cursorReasoning` spread in `fetchCursorModels`.

## 2026-09-23 - claudeCodeVersion follows the pinned claude-agent-sdk (senpi#2033)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `claudeCodeVersion` goes from `2.1.251` to `2.1.280`, so the OAuth client's `user-agent` header is `claude-cli/2.1.280`, the Claude Code version `@anthropic-ai/claude-agent-sdk` 0.3.280 ships.
- `packages/ai/test/anthropic-oauth-claude-code-version.test.ts`: the floor moves to 2.1.280. `packages/coding-agent/test/suite/regressions/2033-claude-code-version-currency.test.ts` fails whenever this constant and the installed SDK's `claudeCodeVersion` differ.

### Why

Claude Opus 5.5 rejects OAuth requests that advertise Claude Code below 2.1.280 (`claude_code_version_too_old`). oh-my-openagent raised the constant with an install-time byte rewrite, and that rewrite never runs under `ignore-scripts=true` or Bun's blocked-postinstall default, so those installs kept sending 2.1.251.

### Why an extension could not handle it

The header is built inside the Anthropic client before any extension hook runs.

### Expected merge conflict zones

- LOW: the single `claudeCodeVersion` constant near the top of `api/anthropic-messages.ts`.

## 2026-09-23 - GPT-6 Sol / Luna id inference for map-less rows

### What changed

- `packages/ai/src/models.ts`: `XHIGH_MODEL_IDS` and `OPENAI_MAX_MODEL_IDS` gain `gpt-6-sol` and `gpt-6-luna`, so a custom provider that ships either id without a `thinkingLevelMap` still surfaces `xhigh` and `max` on the OpenAI-compatible APIs. `inferOpenAIThinkingLevelMap` stays Astra-only: Sol and Luna document `none`, so their `off` level remains selectable.
- Catalog rows and generator changes for the same release are tracked in `packages/ai/changes.md`.

### Why

The generated catalogs carry explicit maps, but `models.json` entries and gateway rows for the new tiers carry none; without the id families the two top efforts disappeared on those routes (`test/gpt-6-family-catalog.test.ts`, map-less block).

### Why an extension could not handle it

Effort inference runs inside the model registry before any extension hook sees the model.

### Expected merge conflict zones

- `packages/ai/src/models.ts`: the `XHIGH_MODEL_IDS` / `OPENAI_MAX_MODEL_IDS` constant block.

## 2026-09-22 - Claude Opus 5.5 request compat: no disabled thinking, no forced tool_choice

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `DISABLED_THINKING_REJECTING_MODEL_MARKERS` gains `opus-5-5` / `opus-5.5`, so rows with no generated compat (a `models.json` entry, a gateway row) never send `thinking.type: "disabled"` and pin effort `low` for a thinking-off turn instead.
- `packages/ai/src/api/bedrock-converse-stream.ts`: `rejectsDisabledThinking` matches the same two markers for Bedrock application inference profiles that carry no catalog metadata.
- `packages/ai/src/utils/prompt-cache-ttl.ts`: `getAnthropicCompat` defaults `supportsForcedToolChoice` to `false` for `claude-opus-5-5` / `claude-opus-5.5` ids alongside Fable and Mythos, so `tool_choice: any` / `{type: "tool"}` is omitted from the request rather than round-tripping a 400.
- Catalog rows and generator changes for the same release are tracked in `packages/ai/changes.md`.

### Why

Claude Opus 5.5 (2026-09-22) returns 400 for `thinking.type` `disabled` and `enabled` alike and for `tool_choice` `any` / `tool`; on Opus 5 both were accepted. Verified against the live Models API (`thinking.types.enabled.supported: false`). The generated catalog encodes the facts as compat, but `models.json` entries and third-party gateway rows carry no generated compat, so the family fact has to live in the providers as well.

### Why an extension could not handle it

The request shape is built inside the Messages and Bedrock providers before any extension hook runs.

### Expected merge conflict zones

- `packages/ai/src/api/anthropic-messages.ts`: the family-marker constant block near the top of the file.
- `packages/ai/src/api/bedrock-converse-stream.ts`: `rejectsDisabledThinking`.
- `packages/ai/src/utils/prompt-cache-ttl.ts`: the forced-tool-choice family regex.

## 2026-09-22 - rename the subscription-provider symbols and modules (senpi#1989)

### What changed

- `packages/ai/src/providers/openai-codex.ts` -> `packages/ai/src/providers/chatgpt-subscription.ts` and `packages/ai/src/providers/openai-codex.models.ts` -> `packages/ai/src/providers/chatgpt-subscription.models.ts`; `packages/ai/src/auth/oauth/openai-codex.ts` -> `packages/ai/src/auth/oauth/chatgpt-subscription.ts`; the catalog shard `packages/ai/src/providers/data/.manifest.json` regenerated for the renamed shard.
- `packages/ai/src/index.ts` and `packages/ai/src/bun-oauth.ts`: exports follow the renamed modules and symbols.
- `packages/ai/src/providers/all.ts`: imports and the provider factory name follow the rename.
- `packages/ai/src/auth/oauth/load.ts`: the lazy OAuth module id and its dynamic import follow the renamed file.
- `packages/ai/src/api/openai-codex-responses.ts`: only the debug-stats SYMBOL renamed (`OpenAICodexWebSocketDebugStats` -> `ChatGptSubscriptionWebSocketDebugStats`). The module path, the `openai-codex-responses` api id and `OpenAICodexResponsesOptions` are FROZEN and unchanged.

### Why

The provider ids were renamed in earlier commits; the symbols, module names and the catalog shard still spelled the old ids, so the tree read as though two different providers existed. This commit is behaviour-free: every persisted VALUE is byte-identical, including the seven frozen tokens and the `LEGACY_PROVIDER_IDS` map keys. Symbols that HOLD a frozen value were renamed while their string contents were not, and symbols that NAME the wire api were left alone entirely.

### Why an extension could not handle it

These are the ai package's own provider factories, OAuth module registry and export surface, all resolved before any extension loads.

### Expected merge conflict zones

- `packages/ai/src/providers/all.ts` and `packages/ai/src/index.ts` export lists, against any other provider addition.
- `packages/ai/src/auth/oauth/load.ts` module map, against any other OAuth provider.

## 2026-09-22 - Normalize Bedrock root tool schemas (#1947)

### What changed

- `packages/ai/src/api/bedrock-converse-stream.ts` normalizes root parameters before strict sampling. `packages/ai/src/utils/tool-schema-compat.ts` supplies the Bedrock-specific object-composition normalization.

### Why

- `packages/ai/src/api/bedrock-converse-stream.ts` sent missing object types and forbidden root combiners. `packages/ai/src/utils/tool-schema-compat.ts` now preserves alternative properties, intersection constraints and required names without changing other providers' allOf boundary.

### Why an extension could not handle it

- `packages/ai/src/api/bedrock-converse-stream.ts` owns the SDK request; the shared conversion in `packages/ai/src/utils/tool-schema-compat.ts` must also cover direct SDK consumers.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/bedrock-converse-stream.ts` tool conversion and `packages/ai/src/utils/tool-schema-compat.ts` root-object merge.

## 2026-09-22 - legacy provider id read helpers (senpi#1989)

### What changed

- `packages/ai/src/legacy-provider-ids.ts`: adds `legacyProviderIdsFor` (canonical id -> its legacy spellings) and `readByProviderId`, which reads a provider-keyed record by trying the canonical key first and then every legacy spelling that normalizes to it. Never throws and never rewrites.

### Why

Todo 8 normalizes the legacy provider id at every READ boundary. Each boundary needs the same "try canonical, then legacy" lookup, and a second copy of that map in each caller would drift. Providers that were never renamed (`anthropic`, `openai`) return no legacy spelling, so they resolve exactly and the subscription lane can never inherit the metered lane's state.

### Why an extension could not handle it

These helpers are consumed by core credential, settings, session and model-config code that runs before extensions load.

### Expected merge conflict zones

- `packages/ai/src/legacy-provider-ids.ts`, against any other addition to the legacy-id surface.

## 2026-09-22 - typed legacy provider id rejection (senpi#1989)

### What changed

- `packages/ai/src/legacy-provider-ids.ts`: adds `legacyProviderIdRejection`, which returns the error text for a TYPED legacy provider id (or one of the legacy DISPLAY NAMES `OpenAI Codex` / `Claude SDK OAuth`), naming the id it was renamed to. Case- and whitespace-insensitive, the way a typed argument is.

### Why

A user who types a legacy id must be told the id MOVED, not shown a generic "Unknown provider" or an empty filtered selector. This is the deliberate counterpart to todo 8: ids READ FROM DISK are normalized and never rejected, while ids the user TYPES are rejected by name. Keeping both behaviours driven by the same legacy map stops them drifting apart.

### Why an extension could not handle it

The rejection must fire inside CLI argument parsing and the interactive login command, both of which run before extensions can observe the input.

### Expected merge conflict zones

- `packages/ai/src/legacy-provider-ids.ts`, against any other addition to the legacy-id surface.

## 2026-09-22 - claude-sdk-oauth renamed to anthropic-subscription: the pooled-credential sentinel matcher stays legacy-aware (senpi#1989)

### What changed

- `packages/ai/src/auth/pool/slots.ts`: new `managedSentinelMaterials(providerId)` returns the canonical `<providerId>-managed` plus the legacy material of any renamed ancestor id (derived from `packages/ai/src/legacy-provider-ids.ts`), and `isManagedSentinelSlot` accepts EITHER material as long as both OAuth fields carry the same one. The sentinel VALUE stored inside credentials is NOT rewritten: credentials written before the rename keep `claude-sdk-oauth-managed` verbatim, and a matcher keyed only on the new id would stop recognizing those slots, resurrecting the poisoned-slot "Provider is not configured" deaths that `repairManagedSentinelSlots` exists to prune.
- Guarded by `packages/ai/test/anthropic-subscription-rename.test.ts` (both materials match under `anthropic-subscription`; unrelated providers do not widen; the wire api id stays frozen on the prompt-cache ttl table).

### Why

The provider id `claude-sdk-oauth` moves to `anthropic-subscription` (display name "Claude SDK OAuth" -> "Anthropic Subscription") while every persisted token derived from the old id stays byte-identical. The managed-sentinel material is derived data written into stored credentials, so it is exactly the frozen half of the rename; the matcher is the moving half.

### Why an extension could not handle it

Slot repair runs inside `packages/ai`'s pooled-credential mutations (`repairManagedSentinelSlots`), which extensions never see; the sentinel material is compared before any extension hook fires.

### Expected merge conflict zones

- `packages/ai/src/auth/pool/slots.ts` sentinel block, against any other pooled-credential change.
- `packages/ai/src/legacy-provider-ids.ts`, whenever another provider id is renamed.

## 2026-09-22 - openai-codex renamed to chatgpt-subscription (senpi#1989)

### What changed

- `packages/ai/src/providers/chatgpt-subscription.ts`: provider `id` -> `chatgpt-subscription`, `name` -> `ChatGPT Subscription`, OAuth label -> `ChatGPT Subscription (Plus/Pro)`. The function still returns `Provider<"openai-codex-responses">`.
- `packages/ai/src/providers/chatgpt-subscription.models.ts`: the catalog aggregator flattens under the new provider id.
- `packages/ai/src/types.ts`: `"chatgpt-subscription"` added to `KnownProvider`; `"openai-codex"` is RETAINED as a documented legacy member so configuration written by an older build still type-checks.
- `packages/ai/src/auth/oauth/chatgpt-subscription.ts`: every user-visible label and error string now reads "ChatGPT Subscription", including the login select prompt.
- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`, `packages/ai/src/api/azure-openai-responses.ts` and `packages/ai/src/api/openai-responses-shared.ts`: the provider comparisons that gate tool-call handling match `model.provider`, so each moved to the new id.
- `packages/ai/src/live-api-gates.ts`: the env-switch map is keyed by PROVIDER ID, so its key moved with the provider.
- Catalog data (`packages/ai/src/providers/data/chatgpt-subscription.json`, its manifest) carries the new provider id; `packages/ai/src/models.generated.ts` is regenerated output.

### Why

The id named a CLI rather than the thing a user signs in with, and the display name followed it. The wire api id `openai-codex-responses` is deliberately NOT renamed: it names the dialect (`https://chatgpt.com/backend-api`, `codex/responses/compact`), not the provider, and about ten runtime branches switch on it. `packages/ai/src/live-api-gates.ts` mattered more than it looks - renaming the provider without moving that key leaves a lookup that silently never matches, and it is invisible in CI because everything it gates is skipped by default (886 skips in this package).

### Why an extension could not handle it

The provider id is resolved inside this package before any extension loads: the catalog is keyed by it, `getModel` resolves through it, and the tool-call provider Sets compare `model.provider` during request construction. An extension cannot rename an id that the package has already used to build its own catalog.

### Expected merge conflict zones

- `packages/ai/src/types.ts` `KnownProvider`, against any other provider addition.
- `packages/ai/src/providers/data/*.json` and `packages/ai/src/models.generated.ts`, against any catalog regeneration.

## 2026-09-22 - Canonical map for renamed provider ids (senpi#1989)

### What changed

- `packages/ai/src/legacy-provider-ids.ts` (new): frozen `LEGACY_PROVIDER_IDS` maps `openai-codex` -> `chatgpt-subscription` and `claude-sdk-oauth` -> `anthropic-subscription`. `normalizeProviderId` is an O(1) own-property hit that returns the input unchanged when the id is already canonical. `normalizeModelRef` splits on the first `/` only so a model id that itself contains `/` survives. `isLegacyProviderId` is `Object.hasOwn` on that map. Re-exported from `packages/ai/src/index.ts` and `packages/ai/src/compat.ts`. Nothing calls these functions yet.
- Guarded by `packages/ai/test/legacy-provider-ids.test.ts`.

### Why

- Two provider ids are being renamed. Existing users have the old ids written into auth.json, settings.json, models.json, and session files, so every later read path will need to normalize. This module is the single canonical map both packages import so no second copy drifts. It lives in `packages/ai` because `packages/coding-agent` cannot be imported from here without a cycle.

### Why an extension could not handle it

- Auth, settings, models, and session files are read inside the package before any extension runs. A second map in an extension would drift from the rewrite every later task imports.

### Expected merge conflict zones

- `packages/ai/src/legacy-provider-ids.ts`: the frozen map, whenever another provider id is renamed.
- `packages/ai/src/index.ts` and `packages/ai/src/compat.ts`: the re-export lines.

## 2026-09-22 - Hard account-quota exhaustion is terminal on the first failure (senpi#1969)

### What changed

- `packages/ai/src/utils/retry.ts`: new exported `USAGE_LIMIT_EXHAUSTION` constant holds the OpenAI hard-quota family — the structured codes `usage_limit_reached` and `usage_not_included` plus the exhaustion sentence "usage limit has been reached" — and `NON_RETRYABLE_PROVIDER_ERROR_PATTERN` includes its markers, so the 429 body `{"type":"usage_limit_reached","message":"The usage limit has been reached"}` classifies as non-retryable instead of matching the retryable `429`.
- `packages/ai/src/utils/retry-profile/classifiers.ts`: `SENPI_STRUCTURED_TERMINAL_PROVIDER_CODES` consumes `USAGE_LIMIT_EXHAUSTION.codes`, so a failure carrying either provider code is terminal even when the message regexes are silent. The family is declared once in `utils/retry.ts` so the two lists cannot drift.

### Why

- A dead account cannot serve another request until its quota resets, so every same-account retry is guaranteed to fail; the turn stage burned `SENPI_DEFAULT_RETRY_PROFILE.turn.maxRetries` (5 extra attempts over ~60 s) before surfacing the terminal state.

### Why an extension could not handle it

- Retry classification runs inside `packages/ai`'s classifiers before any extension hook sees the failure; the pattern lists are compiled there.

### Expected merge conflict zones

- `packages/ai/src/utils/retry.ts`: the `NON_RETRYABLE_PROVIDER_ERROR_PATTERN` array, whenever upstream adds quota wording.
- `packages/ai/src/utils/retry-profile/classifiers.ts`: `SENPI_STRUCTURED_TERMINAL_PROVIDER_CODES`.

## 2026-09-21 - WebSocket transport faults name their close code and read as plain language (senpi#1628)

### What changed

- `packages/ai/src/api/websocket-transport-failure.ts` (new): `createWebSocketTransportFailure` reports a message-bearing `error` event at once, defers a message-less one to the `close` frame that follows, and falls back to the generic `WebSocket error` after `WEBSOCKET_ERROR_CLOSE_GRACE_MS` (250 ms) so a runtime that never sends `close` still fails. `WebSocketCloseError`, `extractWebSocketCloseError` (with the 1009 "message too big" wording) and `extractWebSocketErrorMessage` live here.
- `packages/ai/src/api/openai-codex-responses.ts`, `packages/ai/src/api/openai-responses.ts`: the connect and the streaming `error`/`close` listeners go through that helper; each adapter's private extractor pair and the Codex-only close-error class are removed. `parseWebSocket` disposes the pending grace on completion, abort and idle.
- `packages/ai/src/utils/provider-failure-description.ts` (new): `TURN_RETRY_SUPPRESSION_PREFIX` (moved here from `auth/pool/failover.ts`, which now re-exports it), `stripTurnRetrySuppressionPrefix`, and `describeProviderFailureForUser`, which strips the marker, delegates stall watchdogs to `describeProviderStallForUser`, and words WebSocket closures, bare WebSocket errors and connect timeouts for a person with the same attempts/recovery options as the stall helper.
- `packages/ai/src/utils/retry.ts`: `formatStallDuration` is exported for the new helper. `packages/ai/src/index.ts` exports the new module.

### Why

- Bun (and Node's undici client) fire an `error` event with no message for an unclean disconnect; only the `close` that follows carries `1006 Connection ended`. Failing on the first event threw the diagnosis away, and the raw text - prefixed with the session-internal `senpi:no-turn-retry:` marker - was what the user read as the outcome of the turn.
- The marker constant moved into `utils/` because the `./utils/*` entry graph is budgeted at three files; importing it from `auth/pool` pulled the pool engine into every consumer of the description helper.

### Why an extension could not handle it

- The event pair is consumed inside the adapters' socket listeners before any message reaches the stream; an extension only sees the finished assistant message.

### Expected merge conflict zones

- `packages/ai/src/api/openai-codex-responses.ts` and `packages/ai/src/api/openai-responses.ts`: `connectWebSocket` listeners and the `parseWebSocket` `onError`/`onClose` pair, whenever upstream touches the WebSocket transport.
- `packages/ai/src/auth/pool/failover.ts`: the re-exported marker constant at the top of the file.

## 2026-09-21 - Regional Kimi Code login (#1890)

### What changed

- `packages/ai/src/auth/oauth/kimi-region.ts` (new): the region table (`mainland-cn` -> `auth.kimi.com` + `api.kimi.com/coding`, `global` -> `auth.kimi.ai` + `api.kimi.ai/coding`, ids and hosts taken from the official Kimi Code CLI's `packages/oauth/src/region.ts`), the select prompt, `resolveKimiCodeEndpoints` (stored host > stored region > env host > env region > default), and `chooseKimiCodeLoginEndpoints` (env answers the prompt when it names a host or region).
- `packages/ai/src/auth/oauth/kimi-coding.ts`: `login` asks the region unless the env answers it, and stores the choice as credential `env` (`KIMI_CODE_REGION`, or `KIMI_CODE_OAUTH_HOST` for a custom host). `refresh` exchanges at the credential's own host and carries the env forward, because a flat credential is replaced wholesale by `mergeRefreshed`. `toAuth` returns `baseUrl` only for the international region so a `models.json` `baseUrl` override keeps winning for the default one.
- `packages/ai/src/providers/kimi-coding-auth.ts` (new) replaces `envApiKeyAuth` in `packages/ai/src/providers/kimi-coding.ts`: the API-key login asks the region before the key; `resolve` merges credential env over ambient env (the Cloudflare pattern) and routes by it. The path stays identity-header-free (#1504).
- `packages/ai/src/auth/pool/slots.ts`: `CredentialSlot.env` carries provider-scoped values per account. `slotFromFlatCredentialNamed` copies a login's env into its slot, `projectSlot` overlays the slot's env on the flat projection, and `projectFlatFields` re-projects it when the mirrored slot is removed, so sibling accounts in different regions never share one.

### Why

- Both hosts serve separate accounts, and the flow only knew `auth.kimi.com` through an env override that nothing persisted: an international subscription could log in with `KIMI_CODE_OAUTH_HOST` set, then refresh at the wrong host and send every request to `api.kimi.com/coding`.

### Why an extension could not handle it

- The flow is a bundled `OAuthAuth` and the api-key auth is a provider field; an extension can register a second provider but cannot add a prompt to the shipped `kimi-coding` login or attach metadata to its stored credential.

### Expected merge conflict zones

- `packages/ai/src/auth/oauth/kimi-coding.ts`: imports, `loginKimiCoding`, and the `refresh` / `toAuth` members of `kimiCodingOAuth`; the device and refresh request bodies are unchanged.
- `packages/ai/src/auth/pool/slots.ts`: `CredentialSlot`, `slotFromFlatCredential*`, `projectFlatFields`, `projectSlot`.
- `packages/ai/src/providers/kimi-coding.ts`: the `auth.apiKey` line.

## 2026-09-19 - A fork-owned provider survives a catalog regeneration

### What changed

- `packages/ai/src/providers/kimi-coding.models.ts` is hand-written with inline values, the way
  `devin.models.ts` is, instead of importing a `data/kimi-coding.json` that a generation run no
  longer writes; the data file and its manifest entry are gone.
- `packages/ai/src/providers/all.ts` reads a `FORK_OWNED_CATALOGS` map alongside the generated
  `MODELS`, so `getBuiltinModel`, `getBuiltinModels` and `getBuiltinProviders` keep serving a
  provider that can never appear in the generated aggregate.
- `packages/ai/scripts/model-shards.ts` lists the shard as fork-owned.
- `packages/ai/test/fork-owned-catalogs.test.ts` requires the provider to be absent from `MODELS`
  and still readable through the catalog API.

### Why

- models.dev stopped describing `kimi-coding`, so a regeneration emits neither its shard nor its
  data file and the provider silently left the generated catalog - fifteen type errors that only the
  release job ever saw. Keeping the shard (the prune guard) and tolerating it (the aggregator gate)
  were the first two layers; a provider the fork ships also has to stay readable.

### Why an extension could not handle it

- The generated aggregate and the catalog API are fork source; an extension cannot add a provider to
  a union the generator writes, nor change what `getBuiltinModel` reads.

### Expected merge conflict zones

- `packages/ai/src/providers/all.ts` around the catalog imports and `BuiltinProvider`, whenever
  upstream reshapes the generated catalog read.
- `packages/ai/src/providers/kimi-coding.models.ts`, if upstream ever describes the provider again
  and the generator wants to own the shard back.

## 2026-09-21 - Track the widened Anthropic input-transformation union (senpi#1895)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: the streaming path holds `BetaInputTransformation[]` instead of `BetaThinkingDroppedInputTransformation[]`, and imports that union type.

### Why

- @anthropic-ai/sdk 0.127.0 widened a message's `input_transformations` into a union that also carries `thinking_mismatch_allowed` entries, so both assignments from `message_start` and `message_delta` stopped type-checking. The runtime already forwarded whatever the server sent, so the narrower annotation was describing less than the code did; the interactive transcript filters on `thinking_dropped`, so a mismatch-allowed entry reaches the assistant diagnostic without being announced as a dropped block.

### Why an extension could not handle it

- The stream reader is provider-API plumbing inside this package; no extension hook sees the raw Anthropic event before it is mapped.

### Expected merge conflict zones

- LOW: the type import block at the top of the file and the `inputTransformations` declaration.

## 2026-09-18 — Drop the OpenRouter Mistral overflow case that the catalog no longer carries

### What changed

- `test/context-overflow.test.ts`: removed the `mistralai/mistral-large-2512` OpenRouter case.

### Why

- The generated catalog has no `mistralai/*` ids under `openrouter` any more, so the hardcoded id stopped satisfying `ModelId` and `npm run check` failed with TS2345. Push CI does not typecheck tests, so it only surfaced inside `scripts/release.mjs` and blocked the release of senpi run 35334224253. The other backends in that block each pin one live id; Mistral simply has no OpenRouter id left to pin.

### Why an extension could not handle it

- Test source against a generated catalog.

### Expected merge conflict zones

- LOW: the OpenRouter block in `test/context-overflow.test.ts`.

## Native B.AI provider with credential-scoped catalog and schema compatibility (2026-09-18)

### What changed

- `packages/ai/src/providers/bai.ts`: adds the built-in `bai` provider, API-key auth, credential-scoped
  `/v1/models` discovery, generated-metadata filtering, cached catalog remapping, and mixed Responses /
  Messages / Chat Completions dispatch. Discovery indexes the catalog under both the dot-version and
  hyphenated spelling of every model ID, and a `success: false` model list fails the refresh instead of
  publishing an empty catalog.
- `packages/ai/src/providers/bai-stream.ts`: merges a union-root function schema into a single object schema
  on the B.AI Responses payload, without mutating caller-owned payloads.
- `packages/ai/src/providers/all.ts`: registers B.AI among built-in providers.
- `packages/ai/src/env-api-keys.ts`: maps `bai` to `BAI_API_KEY`.
- `packages/ai/src/types.ts`: adds `bai` to `KnownProvider`.

### Why

- B.AI exposes one API key and a credential-scoped `/v1/models` list across multiple compatible wire APIs.
  IDs alone do not contain the capabilities, limits, reasoning levels, or pricing Senpi needs for selection
  and accounting.
- B.AI rejects union-root function schemas such as `workpool` unless the root explicitly declares
  `type: "object"`, while the same schemas are accepted by less strict Responses backends. Only the OpenAI
  Responses path needs the repair: `api/openai-completions.ts` re-normalizes `tool.function.parameters` after
  `onPayload`, and `api/anthropic-messages.ts` resolves the root before building `input_schema`, so both
  already send an object root. Restoring only the `type` keyword would satisfy B.AI's validator and still
  leave the root without `properties`/`required`, which advertises the tool to the model as taking no
  arguments, so the union is merged through `utils/tool-schema-compat.ts` instead.

### Why an extension could not handle it

- A user extension can prove the transport, but cannot add B.AI to the shipped built-in provider registry,
  generated catalog, canonical environment-key map, or every consumer of `KnownProvider`.

### Expected merge conflict zones

- LOW: provider import/order additions in `packages/ai/src/providers/all.ts`.
- LOW: one member in `KnownProvider` and one environment-key mapping.
- NONE: `bai.ts` and `bai-stream.ts` are new fork-owned files.

## 2026-09-17 - Follow the z.ai catalog to the glm-5.3 family

### What changed

- Regenerated `src/providers/data/` (`zai-coding-cn`, `openrouter`, `cloudflare-ai-gateway`, `.manifest.json`).
- `test/gpt-6-astra-context-window.test.ts` adds `cloudflare-ai-gateway.json` to the covered-catalog list, which now ships Astra models.
- `test/zai-coding-plan-models.test.ts` and `test/openai-completions-tool-choice.test.ts` assert `glm-5.3`, `glm-5.3-flash` and `glm-5.3-highspeed` instead of the retired `glm-5.1`/`glm-5.2`/`glm-5v-turbo` ids, and expect the 5.3 reasoning map.

### Why

- `zai-coding-cn` no longer publishes the 5.1/5.2 ids. The release script regenerates the catalog before it type-checks, so the stale assertions failed `tsc` during publish and blocked the release rather than failing in a normal CI run.

## Slow-stream classification withdrawn (2026-09-16)

### What changed

- `packages/ai/src/utils/retry.ts`: the retryable alternation and the anchored predicate that recognised the agent loop's rate verdict are removed. The silence-stall classifiers and `describeProviderStallForUser` are untouched.

### Why

- The agent loop no longer produces that verdict (senpi#1759): the rate guard that raised it failed healthy turns and was withdrawn, so a classifier for a message that can no longer occur is dead weight.

### Why an extension could not handle it

- Retry and fallback admission is decided from this classifier inside `AgentSession`; an extension observes the turn only after that decision.

### Expected merge conflict zones

- LOW: the retryable list and the stall-classifier block in `packages/ai/src/utils/retry.ts` are back to carrying silence classes only.

## Plain-language provider-stall copy (2026-09-16)

### What changed

- `packages/ai/src/utils/retry.ts`: adds `describeProviderStallForUser(errorMessage, options)` and the `ProviderStallDescriptionOptions` type next to `PROVIDER_STREAM_STALL_ERROR_PATTERN`. It turns any of the four stall watchdog wordings (stream-start, idle, WebSocket liveness, Responses completion) into one user-facing sentence naming the model, what the provider failed to do, and the bound it blew; with `attempts` it adds the same-model retry count, and with `recovery` it adds the next step (`/fallback`, resend, or the matching `retry.provider.*` setting). Anything that is not a stall returns `undefined` so callers keep their verbatim error. The classifier patterns and every existing export are untouched.

### Why

- senpi#1740: the watchdog's own `Error.message` is a classifier token (`isProviderStreamStallError`, the turn-retry gate) that also leaked to users as the answer to a stalled turn (`Provider stream start timed out after 180000ms`). The wording therefore cannot change, and the replacement has to live next to the patterns it mirrors so the two never drift - the coding-agent session, the interactive transcript and print mode all read this one definition.

### Why an extension could not handle it

- The stall wording is produced inside the agent loop and consumed by the retry classifier in this package; an extension sees the assistant message only after the host has already decided what to print.

### Expected merge conflict zones

- LOW: one appended block at the end of the stall-classifier section in `packages/ai/src/utils/retry.ts`; no existing line changes.

## Shared empty-response error texts, forwarded empty stops admitted to the turn retry (2026-09-16)

### What changed

- `packages/ai/src/utils/empty-response-errors.ts` (new): `EMPTY_RESPONSE_ERROR`, `EMPTY_TOOL_USE_ERROR`, `FORWARDED_EMPTY_RESPONSE_ERROR`, `FORWARDED_EMPTY_TOOL_USE_ERROR` - the terminal texts the pi-agent-core empty-assistant recovery wrapper produces, so the producer and the retry classifier read one definition.
- `packages/ai/src/index.ts`: re-exports that module from the package root.
- `packages/ai/src/utils/retry.ts`: `RETRYABLE_PROVIDER_ERROR_PATTERN` accepts the two "after streaming thinking" texts (escaped literally via a local `escapeRegExp`), so `isRetryableErrorMessage` / `isRetryableAssistantError` admit them to the session turn retry. The "twice" texts are deliberately absent and stay non-retryable.
- Tests: `packages/ai/test/retry.test.ts` (forwarded texts retryable, "twice" texts non-retryable).

### Why

- senpi#1733: the recovery wrapper now forwards a reasoning model's thinking live. An attempt that already forwarded reasoning and then stopped empty cannot be replayed inside the stream (a second `start` duplicates the partial; stitching attempt-one thinking onto attempt-two content breaks replay of signed thinking blocks), so the wrapper ends it as an error and the session's turn retry - which removes the errored message from agent state before re-requesting - owns the recovery. The classifier is where the session decides that, and it matches on wording.

### Why an extension could not handle it

- Retry admission is decided inside `AgentSession` from the classifier verdict; an extension observes the turn only after that decision.

### Expected merge conflict zones

- LOW: one import, one helper, and two alternations in `packages/ai/src/utils/retry.ts`; one export line in `packages/ai/src/index.ts`.

## Responses completion-phase watchdog: a dropped terminal event is a stall, not a five-minute wait (2026-09-13)

### What changed

- `packages/ai/src/api/responses-completion-grace.ts` (new): `withResponsesCompletionGrace(stream, graceMs = RESPONSES_COMPLETION_GRACE_MS)` wraps a Responses event stream. It counts `response.output_item.added` / `response.output_item.done`; once at least one item is done and none is open, waiting for the next event is bounded by the grace (60 s). On expiry it throws `ResponsesCompletionStallError` (`Provider stream stalled after the last output item: response.completed timed out after <n>ms`) and releases the source iterator without awaiting it. While an item is open, or before the first item is done, it imposes no deadline.
- `packages/ai/src/api/openai-responses-shared.ts`: `processResponsesStream` iterates `withResponsesCompletionGrace(openaiStream)`, so every Responses transport (SSE and WebSocket; OpenAI, Codex, Azure, gateways) gets the watchdog.
- `packages/ai/src/utils/retry.ts`: `PROVIDER_STREAM_STALL_ERROR_PATTERN` accepts the wording; "timed out" also satisfies the turn retry gate.
- Tests: `packages/ai/test/responses-completion-grace.test.ts` (stall after grace; no deadline while an item is open or before the first done; continues when a new item is added; end to end through the Codex SSE stream the assistant message ends as a stall that both classifiers accept).

### Why

- The second stall class behind senpi#1648: about a quarter of the local `Idle timeout waiting for provider stream after 300000ms` incidents had a complete tool call or message in the message and then silence — the server had finished generating but `response.completed` never arrived. A healthy server sends the terminal event within milliseconds of the last `output_item.done`, so silence in that phase is a dropped event or a dead path, not the model thinking; it deserves a short grace, not the full idle budget. The WebSocket liveness heartbeat only covers Bun WebSocket transports; this covers SSE and Node as well.

### Why an extension could not handle it

- The phase (which items are open) is only visible inside the shared stream processor; an extension sees the assistant message after the idle watchdog has already spent five minutes.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/responses-completion-grace.ts` has no upstream counterpart.
- LOW: one import plus the `for await` head in `packages/ai/src/api/openai-responses-shared.ts` `processResponsesStream`; one alternation in `packages/ai/src/utils/retry.ts`.

## Codex WebSocket liveness: no more five-minute stalls on dead connections (2026-09-13)

### What changed

- `packages/ai/src/api/websocket-liveness.ts` (new): a ping/pong heartbeat for one WebSocket request. After `WEBSOCKET_LIVENESS_PING_INTERVAL_MS` (30 s) without any inbound frame it sends a ping; when `WEBSOCKET_LIVENESS_MAX_UNANSWERED_PINGS` (2) consecutive pings each go `WEBSOCKET_LIVENESS_PONG_TIMEOUT_MS` (20 s) without a pong, ping, or message, it reports `WebSocketLivenessError` (`WebSocket liveness timeout after <n>ms (<k> pings unanswered)`). Runtimes whose WebSocket has no `ping()` - Node's WHATWG client - get an inert monitor. Bun's client exposes `ping()` and dispatches `ping`/`pong` events, so the omo native binary gets the heartbeat.
- `packages/ai/src/api/openai-codex-responses.ts`: `parseWebSocket` runs the heartbeat for the life of the request and fails the stream with the liveness error (socket closed `liveness_timeout`). `WebSocketLike` gains optional `readyState` and `ping`; the Bun proxy-aware wrapper forwards both, so `isWebSocketReusable` sees the inner socket's state on Bun. Parked connections are now watched: `parkSessionWebSocket` attaches `close`/`error` listeners that evict the cache entry immediately (`parked_close`), `unparkSessionWebSocket` detaches them on reuse, and the idle TTL goes through the same `evictSessionWebSocket`.
- `packages/ai/src/api/openai-responses.ts`: `parseWebSocket` runs the same heartbeat; this transport had no idle bound of its own at all.
- `packages/ai/src/utils/retry.ts`: `PROVIDER_STREAM_STALL_ERROR_PATTERN` accepts the liveness wording, so the failure takes the bounded same-model stall retry like the agent-loop idle timeout does.
- Tests: `packages/ai/test/chatgpt-subscription-websocket-liveness.test.ts` (dead after two unanswered pings well inside the idle budget; pongs alone keep a silent stream alive; no ping API leaves the idle timeout in charge; a parked socket that closes is evicted even without `readyState`), `packages/ai/test/chatgpt-subscription-websocket-bun-wrapper.test.ts` (the Bun wrapper never reuses a closed or non-open parked socket), and two classifier rows in `retry.test.ts`.

### Why

- A user report: gpt-5.6-sol turns froze for five minutes at a time. Both provider watchdogs are 300 s (idle, and stream-start since #1276), and nothing else could tell a dead transport from a slow model, so every stall cost the whole budget before the retry that fixes it (senpi#1648). Local session logs held 60 such `Idle timeout waiting for provider stream after 300000ms` incidents on sol/astra streams, each recovered by the next retry within 10-35 s.
- On Bun the failure was deterministic: `WebSocketWithProxy` hid `readyState`, so `isWebSocketReusable` returned true for a parked socket the server had already closed, and a WHATWG `send()` on a closed socket discards the frame silently (measured on Bun 1.4.2), leaving the request to wait out the stream-start watchdog. Nothing observed a close on a parked socket; only the 5-minute TTL evicted it. Codex CLI gets a write error from tungstenite in the same situation and reconnects at once.

### Why an extension could not handle it

- The WebSocket cache, the reuse check, and the frame reader are internals of the provider stream implementation; an extension sees only the assistant-message error five minutes later.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/websocket-liveness.ts` has no upstream counterpart.
- MEDIUM: `packages/ai/src/api/openai-codex-responses.ts` `WebSocketLike`/`CachedWebSocketConnection` types, the Bun wrapper class, `parkSessionWebSocket`/`unparkSessionWebSocket`/`evictSessionWebSocket` (replacing `scheduleSessionWebSocketExpiry`), the two `release` closures in `acquireWebSocket`, and the `liveness` lines in `parseWebSocket`.
- LOW: `packages/ai/src/api/openai-responses.ts` `WebSocketLike` and the `liveness` lines in `parseWebSocket`; `packages/ai/src/utils/retry.ts` one alternation in `PROVIDER_STREAM_STALL_ERROR_PATTERN`.

## Cursor context ceilings come from the server, not the capability table (2026-09-12)

### What changed

- `packages/ai/src/cursor/context-limit-store.ts` (new): browser-safe in-memory store of the context ceiling Cursor reported per model id, with `recordCursorContextLimit`, `getCursorContextLimit`, `resolveCursorContextWindow` (observed, else catalog) and a persistence port. It is browser-safe on purpose: the catalog builders that read it are bundled for the browser by `scripts/check-browser-smoke.mjs`.
- `packages/ai/src/utils/cursor-context-limit.ts` (new): the Node entry point. It owns the JSON file (`<agentDir>/cursor-context-limits.json`, same resolution as `packages/ai/src/api/cursor-conversation-rotation.ts`, override `CURSOR_CONTEXT_LIMIT_STORE`), loads it lazily once, writes atomically (tmp + rename), treats a missing or corrupt file as empty, and installs itself as the persistence port on first use rather than as an import side effect. It lives under `utils/` because `./utils/*` is the only subpath pattern `packages/ai` exports that a Node-only module reachable from the coding agent can use.
- `packages/ai/src/api/cursor-agent.ts`: `onConversationCheckpoint` records `checkpoint.tokenDetails?.maxTokens` for the streaming model. The first checkpoint of a conversation reports 0 and is ignored. Also re-exports `measureCursorModelInputSerializedBytes`.
- `packages/ai/src/api/cursor-agent/measure.ts`: `measureCursorModelInputSerializedBytes` sums only the `rootPromptMessagesJson` blobs - what Cursor replays to the model - where `measureCursorHistorySerializedBytes` also counts the `turns[]` display copies and reports roughly twice that. First proposed in #1614 by DevNewbie1826.
- `packages/ai/src/index.ts`: exports the new measurement.
- `packages/ai/src/cursor/store-migration.ts` and `packages/ai/src/providers/cursor.ts`: a catalog entry materializes its `contextWindow` through `resolveCursorContextWindow(entry.id, entry.window)`, so an observed ceiling wins over the capability table. With an empty store both are unchanged.
- Tests: `packages/ai/test/cursor-context-limit-store.test.ts` (new) and a checkpoint case in `packages/ai/test/cursor-conversation-rotation-stream.test.ts`.

### Why

- `GetUsableModels` carries no window, so `CURSOR_MODEL_CAPABILITIES` is a committed guess. When the guess is larger than the account's real ceiling, every sizing decision downstream - context usage, compaction thresholds, request admission - is made against a window the server will not honour, and the turn fails as a 0-token `resource_exhausted` instead of compacting in time (senpi#1603).
- The aggregate admission budget in the coding agent needs a measurement of what the model actually ingests; sizing against root plus display copies double-counted the same conversation.

### Why an extension could not handle it

- The checkpoint callback lives inside the builtin `cursor-agent` stream implementation, and the catalog builders are `packages/ai` internals; an extension can neither observe `tokenDetails` nor change how a Cursor `Model` is materialized.

### Expected merge conflict zones

- LOW: the new `packages/ai/src/cursor/context-limit-store.ts` and `packages/ai/src/utils/cursor-context-limit.ts` have no upstream counterpart.
- MEDIUM: `packages/ai/src/api/cursor-agent.ts` around `onConversationCheckpoint` and the measure re-export block.
- LOW: the single `contextWindow` line in `packages/ai/src/cursor/store-migration.ts` and `packages/ai/src/providers/cursor.ts`.

## Devin Cascade transport parity with the released CLI (2026-09-12)

### What changed

- `packages/ai/src/auth/oauth/devin.ts`: `toAuth` returns only the session token. It used to return `baseUrl: https://api.devin.ai`, and `Models.applyAuth` overlays `auth.baseUrl` onto the model, so every `GetChatMessage` was posted to the REST login host and answered `404 {"detail":"Not Found"}` (#1615). `api.devin.ai` is the login/token host only; chat stays on the Cascade host seeded on the model.
- `packages/ai/proto/devin/cascade.proto` + `gen/cascade_pb.ts`: `Metadata.user_jwt` moves to its upstream field 21 (it was declared on 22, which is `force_team_id`, so a minted JWT would have been sent as a team override); adds `supported_model_displays`, `device_fingerprint`, `DisplayOption` (incl. the native 6-8 slots), `ModelDimensionKind`, `ModelFeatures`/`ModelInfo`/`ModelDimension`/`ModelFamilyMetadata` subsets on `ClientModelConfig`, `CompletionConfiguration.fim_eot_prob_threshold`, `ChatMessagePrompt.thinking_redacted`/`signature_type`, `GetChatMessageRequest.model_assignment_jwt`, and the `GetUserJwt`/`AssignModel` request-response pairs with `ModelAssignment`. Regenerated with the documented buf + transform workflow.
- `packages/ai/src/api/devin-agent/metadata.ts`: two identities, as the released CLI presents them - `devin-cli`/`chisel`/`3000.6.2` on `GetUserJwt`, `AssignModel` and `GetChatMessage`, and the dev-channel `chisel`/`0.0.0-dev` identity with `supportedModelDisplays [3,4,6,7,8]` on `GetCliModelConfigs`. The previous `chisel`/`cli`/`0.0.0-dev` chat identity is not one the CLI sends.
- `packages/ai/src/api/devin-agent/unary.ts` (new): unary Connect RPC helper - bare `application/proto` body both ways, raw-or-gzip decode, `DevinUnaryError` with status. `paths.ts` gains `DEVIN_USER_JWT_PATH`, `DEVIN_ASSIGN_MODEL_PATH`, `DEVIN_CHAT_HEADERS` (the released CLI header set: gzip Connect frame, `accept-encoding: identity`, `user-agent: connect-go/1.18.1 (go1.26.3)`, no `authorization` header - auth rides in `Metadata.api_key`) and `DEVIN_UNARY_HEADERS`.
- `packages/ai/src/api/devin-agent.ts`: a turn is now `GetUserJwt` -> (`AssignModel` for `compat.modelRouter` models) -> `GetChatMessage`. The user JWT rides in `Metadata.user_jwt`; `custom_api_server_url` from `GetUserJwt` replaces the chat host when present (ordinary accounts are provisioned on a different host than the seed). An empty JWT, a non-2xx auth answer, or an assignment without uid+JWT fails the turn before any chat request. The end-of-stream trailer is parsed (`trailer.ts`, new) and an `{error:{code,message,details}}` trailer terminates the turn as an error naming the code - previously the trailer was ignored and a rejected turn surfaced as an empty successful `done`. `cascadeId` defaults to a fresh UUID instead of `""`.
- `packages/ai/src/api/devin-agent/request.ts`: message ids are deterministic UUID-shaped (`deterministicUuid` of cascade id + index + role), assistant turns use `bot-<uuid>` or the server's `responseId` when the turn is native, tool-result ids include the tool call id, and empty assistant turns are skipped; `executionId` is a fresh UUID; `chatModelUid` is `assignment.modelUid ?? model.upstreamModelId ?? model.id`; `chatModelName` is no longer sent; `disableParallelToolCalls` follows `compat.supportsParallelToolCalls`; tools carry `strict: false`; user prompts and tool results carry inline `images`; the completion configuration is the released CLI's (`numCompletions 1`, `maxNewlines 200`, `temperature 0.4` default with `firstTemperature` mirrored, `topK 50`, `topP 1`, `fimEotProbThreshold 1`, stop patterns + caller stop sequences), and a caller temperature of exactly 0 is clamped to `0.0001` because Cascade answers a zero temperature with an opaque `invalid_argument`. `buildDevinRouterPrompt` builds the `AssignModel` prompt from the latest user turn with an empty message id.
- `packages/ai/src/api/devin-agent/stream-state.ts`: tool-call chunks after the first arrive with an empty id; they now attach to the active call, arguments accumulate across chunks (a chunk either repeats the accumulated JSON or carries only the new bytes), `toolcall_delta` carries only the new bytes, and the block's arguments are re-parsed from the accumulated text with `parseStreamingJson`.
- `packages/ai/src/api/devin-agent/discovery.ts`: `GetCliModelConfigs` goes through `postDevinUnary` (bare proto body - the Connect frame it used to send was answered HTTP 415), with the discovery identity and no bearer header; normalization drops disabled and internal-display configs, flags routers (`compat.modelRouter`), reads `contextWindow` from `ClientModelConfig.max_tokens` (the account's window, not the output cap) and `maxTokens` from `ModelInfo.max_output_tokens`, per-million cost from the cost dimensions, image support from model features minus the image-blind SWE-1.6 lanes, and sorts by id.
- `packages/ai/src/model.ts`: `DevinAgentCompat { modelRouter?, supportsParallelToolCalls? }` bound to `Model<"devin-agent">.compat`.
- `packages/ai/src/providers/devin.models.ts`: the seed is the plan-available SWE-2 effort lanes (`swe-2-high` first, then `swe-2-max`, `swe-2-low`, `swe-2-high-lite`) plus `swe-1-6`/`swe-1-6-fast`, 262k/200k context windows, 64k output. The bare `swe-2` uid is removed: Cascade rejects it with `permission_denied`.
- Tests: `devin-agent-wire`, `devin-agent-request` (new), `devin-agent-stream`, `devin-agent-stream-deltas` (new), `devin-agent-stream-harness` (shared stub edge: GetUserJwt + AssignModel unary, then the chat stream), `devin-provider`, `devin-oauth`.

### Why

- Every Devin chat in the shipped 2026.9.11 engine failed. Login succeeded and minted a valid token, but the transport could not spend it: the login host overlay produced a 404 on every turn, and the layers behind it (missing user JWT, wrong identity, JWT on the wrong field, non-UUID ids, zero temperature) each produced `invalid_argument` once the host was right. Community reproduction on omo `5.0.0-0.beta.55` isolated the first two; the remaining gaps were found by diffing the transport against the released CLI's behaviour as mirrored by oh-my-pi's `devin.ts`.
- Tool calls streamed by Cascade were split into a nameless second call on every argument continuation, so no tool ever executed even when text streamed.

### Why an extension could not handle it

- The api implementation, its auth adapter and the model compat type live inside `packages/ai`; an extension cannot change how `Models.applyAuth` consumes `toAuth`, cannot alter the builtin `devin-agent` stream function, and cannot extend the `Model<"devin-agent">.compat` type.

### Expected merge conflict zones

- `packages/ai/src/model.ts`: the `compat` conditional type chain gains a `devin-agent` arm.
- Everything under `packages/ai/src/api/devin-agent/`, `packages/ai/src/api/devin-agent.ts`, `packages/ai/proto/devin/cascade.proto` and `packages/ai/src/providers/devin*` are fork-owned files with no upstream counterpart.

## Devin static module override (2026-09-13)

### What changed

- `packages/ai/src/api/devin-agent.lazy.ts` accepts a typed module override before its existing variable-specifier fallback, including for wrappers created before registration.
- `packages/ai/src/devin-provider.ts` exposes the concrete streaming functions as a static module shape for standalone bundles.

### Why

- A relocated Bun binary cannot resolve a variable-specifier import whose implementation is not embedded.

### Why an extension could not handle it

- The lazy loader and its module state belong to the AI package, while static bundle membership is determined before extensions run.

### Expected merge conflict zones

- `packages/ai/src/api/devin-agent.lazy.ts` loader and override setter; both files are fork-only.

## Devin Cascade model transport (2026-09-12)

### What changed

- `packages/ai/proto/devin/cascade.proto` plus `packages/ai/src/api/devin-agent/gen/cascade_pb.ts`: a vendored SUBSET of Codeium/Windsurf's Cascade schema, generated with protoc-gen-es v2.13.0 and run through `scripts/transform-cursor-agent-proto.mjs` like the Cursor schema. Only the messages the transport reads or writes are declared; every field number matches upstream, so unknown upstream fields round-trip as unknown fields.
- `packages/ai/src/api/devin-agent.ts`: the `devin-agent` API. One server-streaming `GetChatMessage` Connect call per turn, request sent as a single gzipped frame, response frames mapped onto senpi's assistant event protocol, terminal `done`/`error` with abort handling.
- `packages/ai/src/api/devin-agent/frames.ts`: Connect framing - 5-byte prefix, gzip flag 0x01, end-of-stream trailer flag 0x02, and a 64 MiB payload cap so a corrupted length prefix cannot become a 4 GiB allocation.
- `packages/ai/src/api/devin-agent/request.ts`: request building. Cascade has no system role, so the system prompt travels in the top-level `prompt` field and history becomes flat `ChatMessagePrompt` entries whose `source` carries the role; message ids are derived from the conversation id and index so a retried turn does not fork the server-side transcript.
- `packages/ai/src/api/devin-agent/stream-state.ts`: delta bookkeeping. Cascade blocks are implicit and one frame may carry thinking, text and a tool call at once, so this module opens and closes senpi's blocks and maps Cascade stop reasons onto senpi's vocabulary.
- `packages/ai/src/api/devin-agent/metadata.ts` and `paths.ts`: the CLI identity envelope, the `devin-session-token$` scheme prefix, and the RPC paths.
- `packages/ai/src/api/devin-agent/discovery.ts`: credential-scoped `GetCliModelConfigs` discovery that returns undefined on failure or an empty roster.
- `packages/ai/src/api/devin-agent.lazy.ts`, `packages/ai/src/compat.ts`, `packages/ai/src/types.ts`: the Node-only lazy boundary, the builtin api-registry entry, and the `devin-agent` api id with its options type.
- `packages/ai/src/providers/devin.ts` and `packages/ai/src/providers/devin.models.ts`: the provider bound to the merged Devin OAuth flow, its public SWE seed, and a `refreshModels` that publishes the account's real lanes but never an empty catalog.
- `packages/ai/src/providers/all.ts`: registers the provider among the builtins.

- `packages/ai/src/api/devin-agent.ts` only upgrades the default `stop` to `toolUse` when a tool call block is present: a server-reported `length` means the turn was truncated, and a truncated tool call must not be advertised as a complete one.

- `packages/ai/src/api/devin-agent.ts` terminates a Cascade `ERROR` or `CONTENT_FILTER` stop as an `error` event rather than a `done` event: senpi's protocol has no "done because it failed", and a done event carrying a failed turn would be consumed as a successful assistant message.

- `packages/ai/src/api/devin-agent/discovery.ts` authenticates with the same `Bearer devin-session-token$…` header as the chat call, not only the protobuf `Metadata.api_key`: Cascade rejects an unauthenticated discovery request, which would have silently degraded every account to the static seed.

### Why

- The merged Devin OAuth flow could mint a credential that nothing could spend: senpi had no Cascade transport, so a signed-in user still had no Devin model to select.
- Cascade deviates from every OpenAI-shaped adapter senpi already had (Connect framing, gzip per frame, protobuf payloads, no system role, implicit blocks, credential-scoped catalog), so the deviations are pinned in code next to the reasons.

### Why an extension could not handle it

- An api id must exist in `KnownApi`, in the per-api options map and in the builtin api-registry inside `packages/ai`; an extension cannot add one, cannot participate in the Bun binary's static bundle, and cannot return a `ProviderStreams` implementation that the model runtime treats as first-class.

### Expected merge conflict zones

- `packages/ai/src/types.ts`: the `KnownApi` union and the api options map - upstream adding an api touches both.
- `packages/ai/src/compat.ts`: the lazy re-export block and the builtin api registration list.
- `packages/ai/src/providers/all.ts`: the provider import list and the builtin provider array.
- Everything under `packages/ai/src/api/devin-agent/` and the two `providers/devin*` files are additions with no upstream counterpart.

## Devin CLI OAuth login flow (2026-09-11)

### What changed

- `packages/ai/src/auth/oauth/devin.ts`: new Devin (Cognition) OAuth flow. Generates a PKCE S256 challenge plus a uuid state, sends the user to `https://app.devin.ai/auth/cli/continue` with `response_type=code`, the loopback `redirect_uri` and `prompt=select_account`, and races the loopback callback against the manual paste prompt for headless sessions. Exports `devinOAuth` whose `refresh` is a no-op (Devin has no refresh grant) and whose `toAuth` returns the stored token plus the `https://api.devin.ai` base URL.
- `packages/ai/src/auth/oauth/devin-callback.ts`: one-shot loopback callback server pinned to `127.0.0.1:59653/callback`, the single redirect URI Devin registers for the CLI. Validates the issued state before the authorization code is spent, renders the shared OAuth result pages, and reports exchange failures through both the page and the login promise.
- `packages/ai/src/auth/oauth/devin-token.ts`: the non-standard CLI token exchange. Posts JSON carrying only `code` and `code_verifier` (no client_id, no grant_type) with `Accept: application/json`, then builds the credential from the single `token` field used as both access and refresh, with expiry decoded from the JWT `exp` and a 31536000000 ms fallback.
- `packages/ai/src/auth/oauth/load.ts`: adds `devin` to `OAuthFlowLoaders` and exports `loadDevinOAuth`, so the flow resolves through the same lazy-import boundary as every other provider and stays out of browser-reachable static imports.
- `packages/ai/src/bun-oauth.ts`: registers `devin: () => devinOAuth` in the statically bundled flow set so the standalone Bun binary can run the login without dynamic import.

### Why

- senpi had no Devin authentication at all: no flow module, no loader entry, no bundled registration, so Devin could not be signed into from senpi even though its CLI grant is a plain public-client authorization-code flow.
- Devin's grant deviates from the OAuth defaults the existing helpers assume (fixed redirect port, no client_id, no grant_type, one token serving as access and refresh, expiry only inside the JWT), so the deviations are pinned in code next to the reasons rather than rediscovered per incident.

### Why an extension could not handle it

- OAuth flows are resolved inside `packages/ai` through `registerBundledOAuthFlowLoaders` and the `OAuthFlowLoaders` type; an extension cannot add a member to that registry, cannot participate in the standalone Bun binary's static bundle, and cannot return an `OAuthAuth` that the credential store and auth resolution treat as first-class.

### Expected merge conflict zones

- `packages/ai/src/auth/oauth/load.ts`: the `OAuthFlowLoaders` member list and the block of `load*OAuth` exports — upstream adding a provider touches the same two spots.
- `packages/ai/src/bun-oauth.ts`: the import list and the `registerBundledOAuthFlowLoaders` object literal.
- The three `packages/ai/src/auth/oauth/devin*.ts` files are additions with no upstream counterpart and should not conflict.

## PR #1304 review fixes: shared auth-miss prefix, login merge, sentinel repair (2026-09-10)

### What changed

- `packages/ai/src/auth/resolve.ts`: `PROVIDER_NOT_CONFIGURED_PREFIX` / `providerNotConfiguredMessage()` export the exact auth-miss wording every resolution site throws; `packages/ai/src/models.ts` re-exports both and throws through the helper. Consumers keying recovery decisions off that message (the coding-agent session layer and the credential-pool classifier) can never drift from the throw sites.
- `packages/ai/src/auth/pool/slots.ts`: `appendLoginSlot` MERGES a provider-owned pool onto the value read under the credential lock - stored slots and their block state win for names that already exist, only genuinely new names are appended - instead of whole-writing a snapshot the provider built before the interactive browser round trip. `managedSentinelMaterial` / `isManagedSentinelSlot` / `repairManagedSentinelSlots` recognize and drop pool slots whose `access` and `refresh` both equal the provider's `<providerId>-managed` marker (clearing a pin that pointed at one), reporting whether a repair happened so callers rewrite storage only when bytes change.
- `packages/ai/test/credential-pool-mutations.test.ts`: a pre-login snapshot never rewinds a sibling that rotated or earned a block; a provider-owned pool onto a flat current keeps the whole-write shape; sentinel slots are recognized, dropped, un-pinned, and a clean pool is a no-op.

### Why

- The provider builds its returned pool from a snapshot read BEFORE the browser flow, tens of seconds before the commit under the lock: writing it verbatim rolled a sibling's rotated refresh token back to the consumed value (a forced re-login, since Anthropic rotates refresh tokens on use) and erased its rate-limit block. Separately, a shipped build stored the provider pool's flat sentinel as a generated `login-N` slot; such a slot can never authenticate and dead-ends every request whose affinity picks it, so the coding-agent store now heals those entries on load.

### Why an extension could not handle it

- Both the merge and the repair algebra run inside the shared credential-pool read/write path the runtime owns; providers cannot intercept what the runtime stores after login returns or what every reader parses from auth.json.

### Expected merge conflict zones

- LOW: `appendLoginSlot` and the sentinel helpers in `auth/pool/slots.ts`; the prefix helpers in `auth/resolve.ts` and their re-export in `models.ts`.

## Classify Claude SDK session lock contention as retryable (2026-09-02)

### What changed

- `packages/ai/src/utils/retry.ts`: `RETRYABLE_PROVIDER_ERROR_PATTERN` matches `Lock file is already being held`.
- `packages/ai/test/retry.test.ts`: pins that wording as a retryable assistant error.

### Why

- Claude Agent SDK session resume/stream hits proper-lockfile while a previous subprocess still holds `session.json`. The failure is local and transient; treating it as unknown/terminal made the coding-agent hard-error fallback hop providers.

### Why an extension could not handle it

- Retry classification lives in the shared `pi-ai` regexes used by every caller of `isRetryableAssistantError`.

### Expected merge conflict zones

- LOW: `RETRYABLE_PROVIDER_ERROR_PATTERN` in `retry.ts`.

## Preserve provider-owned credential pools during login (2026-09-02)
## 2026-09-10 - Kimi Code client identity headers on the subscription path (#1504)

### What changed

- `packages/ai/src/auth/oauth/kimi-identity.ts` (new): `kimiCodeIdentityHeaders()` returns `User-Agent: KimiCLI/<version>` plus `X-Msh-Platform`, `X-Msh-Version`, `X-Msh-Device-Name`, `X-Msh-Device-Model`, `X-Msh-Os-Version`, and `X-Msh-Device-Id`. Every value is printable-ASCII sanitized. The device id is read from (or minted into) `<agent dir>/kimi-device-id` (`SENPI_CODING_AGENT_DIR` / `CODING_AGENT_DIR`, else `~/.senpi/agent`), memoized per process, and degrades to an ephemeral id when that directory cannot be written; `resetKimiDeviceIdForTests()` clears the memo.
- `packages/ai/src/auth/oauth/kimi-coding.ts`: sends that header set on device authorization, device-code token polling, and token refresh, and returns it from `toAuth` so `resolveProviderAuth` merges it into every chat request the model runtime issues for the provider. The api-key auth path is untouched and stays header-free.

### Why

- `api.kimi.com/coding` recognizes its clients by a product `User-Agent` plus the six-header `X-Msh-*` device set; the official Kimi Code client attaches it to every OAuth and managed-API call. `X-Msh` existed nowhere in this package, so a Kimi For Coding subscription session presented itself as an anonymous Anthropic-protocol client holding a Kimi bearer token (#1504).
- It is the only divergence from the reference clients that fits the timeline: the kimi-coding request shape had not changed when the endpoint began rejecting fresh sessions, so a server-side tightening around client identification explains it where a payload regression does not.
- ASCII sanitization and best-effort device-id persistence are ported deliberately: raw non-ASCII header bytes draw a CDN 520 on this host, and an `ENOENT` on a fresh install must not break header construction for every request.

### Why an extension could not handle it

- The headers must ride the provider's own OAuth requests (device authorization, polling, refresh) inside `kimi-coding.ts` and the credential-derived request auth that `resolveProviderAuth` produces from `toAuth`. Both run below any extension hook, and an extension cannot see the device-code exchange at all.

### Expected merge conflict zones

- LOW: new file `packages/ai/src/auth/oauth/kimi-identity.ts`.
- LOW: the three `fetch` call sites and `toAuth` in `packages/ai/src/auth/oauth/kimi-coding.ts`.

## 2026-09-10 - Map ask_user_question to Claude Code's AskUserQuestion wire name

## 2026-09-08 - Immutable account IDs with optional display metadata (senpi#1495)

## 2026-09-10 - Immutable account IDs with column-bounded, render-unique display metadata (senpi#1495)



### What changed

- `packages/ai/src/auth/pool/slots.ts`: adds optional `displayName`, safe single-line labels, and pure rename/clear validation. A label is stored NFC-normalized with internal whitespace runs collapsed, must contain at least one visibly advancing character, may not begin with a combining mark, and is bounded at 32 terminal columns measured per grapheme cluster (`displayNameColumns`) rather than in UTF-16 code units. Provider-local uniqueness compares a fold of case, Unicode compatibility forms (NFKC), invisible code points and Cyrillic lookalikes, so two labels that render identically cannot coexist. Slot IDs and credential material remain unchanged. Login allocation reports the allocated ID together with its origin (`generated` for an ID Senpi chose, `provider` for one a provider envelope carried); provider-owned envelopes still require exactly one new ID compared with the locked current pool, never token matching or array ordering.
- `packages/ai/src/auth/types.ts`: adds secret-free `AccountLoginReceipt` with `providerId`, `name` and `origin`, plus optional `AuthInteraction.onAccountCommitted`; the callback is excluded from provider interactions.
- `packages/ai/src/models.ts`: captures the allocated ID and its origin inside the serialized login write and emits the receipt only after persistence succeeds. Ambiguous provider envelopes do not produce a receipt. Existing credential return values remain compatible.

### Why

- `packages/ai/src/auth/pool/slots.ts`: account labels must not remap pins, refresh, health, failover, or HRW affinity, and a documented "unique per provider" / bounded-length guarantee must hold for real Unicode input: `trim`/`toLowerCase`/`String.length` accepted double-spaced, NFC/NFD and homoglyph duplicates and let a 170-column label through while rejecting 41 emoji.
- `packages/ai/src/auth/types.ts`: callers need a supported, secret-free committed-slot identity, including whether the ID was machine-generated, to avoid prompting for a name a provider flow already asked for.
- `packages/ai/src/models.ts`: only the login write knows which ID was actually committed and who chose it; callers must not infer it from credentials or list order.

### Why an extension could not handle it

- `packages/ai/src/auth/pool/slots.ts`, `packages/ai/src/auth/types.ts` and `packages/ai/src/models.ts` own shared credential metadata and the locked login boundary below the extension API. The user-facing commands remain extensions.

### Expected merge conflict zones

- LOW: `packages/ai/src/auth/pool/slots.ts` slot type, display-name validation block and append function; `packages/ai/src/auth/types.ts` interaction types; `packages/ai/src/models.ts` login mutation and return boundary.

## 2026-09-10 - Map ask_user_question to Claude Code's AskUserQuestion wire name

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: map the registered `ask_user_question` tool to `AskUserQuestion` for Anthropic Claude Code wire requests, and map it back only when the registered tools include the alias.

### Why

- Claude Code's Anthropic wire contract uses `AskUserQuestion`; without the explicit alias, the built-in tool name cannot round-trip through streamed `tool_use` blocks.

### Why an extension could not handle it

- Tool-name conversion happens inside the Anthropic provider adapter while constructing and decoding provider messages, before an extension can repair the wire name.

### Expected merge conflict zones

- LOW: the Claude Code tool lookup and conversion helpers in `packages/ai/src/api/anthropic-messages.ts`.

## 2026-09-10 - OAuth refresh runs outside the credential lock and the catalog lane joins it (#1542)

### What changed

- `packages/ai/src/auth/oauth-refresh.ts` (new): `refreshOAuthCredential({ credentials, providerId, oauth, stale, slotName, isStale, signal, owning })` re-reads the stored credential, runs `oauth.refresh` OUTSIDE `CredentialStore.modify` under `AbortSignal.any([exchange, timeout 15s])`, then re-enters `modify` and compare-and-swaps: the rotated token is written only when the slot's refresh token still equals the one the exchange consumed; on mismatch the newer stored value is adopted and no write happens. Concurrent refreshes of the same `(store, provider, slot, refresh token)` join one in-flight exchange; owning waiters (per-request resolution) cancel the exchange once none is left waiting and a result arriving after that is not persisted; a non-owning waiter (the catalog lane) only stops waiting. The write itself is not cancellable because the exchange already consumed the refresh token. Exports `OAuthRefreshExchangeError` / `OAuthRefreshStoreError` for code mapping and `projectOAuthSlot`.
- `packages/ai/src/auth/resolve.ts`: `resolveStoredOAuth` no longer runs the refresh inside `credentials.modify`; it calls `refreshOAuthCredential` as an owning waiter and maps failures through the new exported `oauthRefreshModelsError` (`oauth` for the exchange, `auth` for the store) so `ModelsError` codes and messages are unchanged. `DEFAULT_OAUTH_REFRESH_TIMEOUT_MS` moved to `oauth-refresh.ts`.
- `packages/ai/src/auth/refresh-credential.ts` (new, extracted from `models.ts` for the LOC ceiling): `resolveRefreshCredential(provider, credentials, authContext, stored, signal)` is the catalog lane's effective-credential step; the expired-OAuth branch joins `refreshOAuthCredential` with `owning: false`.
- `packages/ai/src/models.ts`: `ModelsImpl.refresh` calls the extracted `resolveRefreshCredential`. The per-provider catalog-refresh controller (`supersedeProviderRefresh` on `setProvider`/`deleteProvider`/`refresh`) therefore no longer reaches the token exchange: a superseded catalog refresh stops waiting while the exchange completes and persists.

### Why

- Issue #1542: with several `openai-codex` OAuth slots, one slot's refresh held the single `auth.json` lock for the whole up-to-15s HTTP exchange while every other slot, provider and login gave up after `FILE_STORAGE_LOCK_RETRY_BUDGET_MS` (5.5s) with `CredentialStoreBusyError`; and any login/logout/`setRuntimeApiKey` for the shared provider id aborted an in-flight token refresh through the catalog-refresh controller.

### Why an extension could not handle it

- The lock scope is inside `resolveStoredOAuth` -> `CredentialStore.modify`, below every extension hook, and the catalog-refresh controller is private to `ModelsImpl`.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/auth/resolve.ts` `resolveStoredOAuth` (the refresh block is now a call into `oauth-refresh.ts`).
- MEDIUM: `packages/ai/src/models.ts` `refresh()` credential step and the removed private `resolveRefreshCredential`.
- LOW: new files `auth/oauth-refresh.ts`, `auth/refresh-credential.ts`.

## 2026-09-10 - Venice AI provider registration and venice_parameters

### What changed

- `packages/ai/src/types.ts` adds `"venice"` to `KnownProvider` and a `veniceParameters` field to `OpenAICompletionsCompat`, carrying Venice's only non-OpenAI request object (`{ include_venice_system_prompt?: boolean }`).
- `packages/ai/src/api/openai-completions.ts` emits that object as the top-level `venice_parameters` request field, alongside the existing OpenRouter and Vercel gateway routing hooks, and declares it on `OpenAICompletionsRequestParams`. `packages/ai/src/utils/prompt-cache-ttl.ts` keeps it optional in `ResolvedOpenAICompletionsCompat` so auto-detection never has to synthesize one.
- `packages/ai/src/env-api-keys.ts` maps `venice` to `VENICE_API_KEY`; `packages/ai/src/providers/all.ts` registers the fork-only `veniceProvider()` factory.

### Why

- Venice's `ChatCompletionRequest` schema is `additionalProperties: false` (`components.schemas.ChatCompletionRequest` in https://api.venice.ai/api/v1/swagger.yaml), so a Venice-only field cannot be smuggled in as an ad-hoc key and every other field senpi sends had to be checked against Venice's accepted list. It already accepts `store`, `developer` role, `reasoning_effort`, `stream_options.include_usage`, `max_completion_tokens`, `prompt_cache_key`, `prompt_cache_retention`, and `strict` tools, so the auto-detected compat defaults were left untouched.
- Without `include_venice_system_prompt: false`, Venice prepends its own default system prompt ahead of the agent's.

### Why an extension could not handle it

- Provider registration, credential detection, and the outbound request body are all inside the AI adapter boundary, below the point where extension code can rewrite a provider request.

### Expected merge conflict zones

- LOW: the `KnownProvider` union tail and the `builtinProviders()` array in `providers/all.ts` when upstream adds providers.
- LOW: the compat field list in `types.ts` / `prompt-cache-ttl.ts` and the request-field block in `openai-completions.ts` when upstream adds provider-specific request options.

## 2026-09-10 - OpenAI images output options, masks, and image-token pricing

### What changed

- `packages/ai/src/api/openai-images-params.ts`: `OpenAIImagesOptions` gains `background`, `outputFormat`, `outputCompression`, `moderation`, and `mask`; `buildParams` forwards them and `parseOpenAIImageOutputOptions` (exported through compat) rejects transparent+jpeg, compression on png, non-integer or out-of-range compression, and a mask without an input image before any request.
- `packages/ai/src/api/openai-images-edit.ts`: uploads the mask as `mask.<ext>` next to the reference images.
- `packages/ai/src/images.ts`: re-exports `parseOpenAIImageOutputOptions`, `OpenAIImageBackground`, `OpenAIImageOutputFormat`, `OpenAIImageModeration`, and `OpenAIImageOutputOptions` through the compat surface.
- `packages/ai/src/api/openai-images-result.ts` (moved out of `openai-images.ts` for the LOC ceiling): b64 payloads are labeled by their magic bytes, falling back to the requested container; URL hydration is unchanged.
- `packages/ai/src/api/openai-images.ts`: echoes the response `background`, and `parseUsage` prices `input_tokens_details.image_tokens` with `cost.imageInput ?? cost.input`.
- `packages/ai/src/types.ts`: `ImagesModelCost.imageInput`, `AssistantImages.background`, and `KnownImagesProvider` now includes `openai` so `getImageModel("openai", id)` type-checks.
- `packages/ai/scripts/generate-image-models.ts` + regenerated `image-models.generated.ts`: `imageInput: 8` on gpt-image-2 and both 2.5 entries.

### Why

- GPT Image 2.5 supports transparent backgrounds, jpeg/webp containers, compression, moderation, and inpainting masks that the adapter could not request; image input tokens are billed at $8/M, not the $5/M text rate; and a gateway that ignores `output_format` returned png bytes labeled `image/webp`.

### Why an extension could not handle it

- The wire payload, response decoding, and usage pricing live inside the provider adapter behind the compat surface.

### Expected merge conflict zones

- MEDIUM: `openai-images.ts` (helper extraction) and `openai-images-params.ts`.
- LOW: `types.ts` additions, generator array, tests.
## 2026-09-09 - GPT Image 2.5 generation and reference-image editing

### What changed

- `packages/ai/scripts/generate-image-models.ts` and `packages/ai/src/image-models.generated.ts`: add GPT Image 2.5 Sunburst and Flare ahead of the existing OpenAI models with $5 input / $30 output / $1.25 cached-input rates per million tokens. Both new entries and GPT Image 2 advertise text and image inputs; the OpenRouter catalog is unchanged.
- `packages/ai/src/api/openai-images-params.ts`: own the quality/size options, prompt construction, and exported `parseOpenAIImageSize` validator. Accept `xhigh`/`max` quality and arbitrary integer dimensions that satisfy the divisibility, edge, aspect-ratio, and pixel-count limits.
- `packages/ai/src/api/openai-images-edit.ts` and `packages/ai/src/api/openai-images.ts`: upload up to 16 base64 reference images via `/images/edits`, without `input_fidelity`, using the generation path's payload/response hooks, retry, usage, and error handling. Keep the OpenAI SDK pinned at 6.26.0 with one localized request-type assertion.
- `packages/ai/src/images.ts`: expose the parser, quality/size types, and `OpenAIImagesOptions` through the existing compat re-export without eagerly loading the SDK.

### Why

- The GPT Image 2.5 models released on 2026-09-08 add quality tiers and support high-resolution generation and reference-image edits. The adapter previously advertised only text inputs, rejected references, and typed only the preset dimensions.

### Why an extension could not handle it

- The built-in catalog, public option types, request validation, and SDK endpoint selection belong to the AI provider layer; callers should not need to rewrite payloads or implement uploads themselves.

### Expected merge conflict zones

- LOW: the OpenAI portion of the generated image catalog, its static generator entries, and the images export surface; MEDIUM: the request-construction block in `packages/ai/src/api/openai-images.ts`. The parameter and edit builders are new files.

## 2026-09-08 - Recased gateway-namespaced tool references fold onto the request's tool names

### What changed

- `packages/ai/src/api/anthropic-tool-references.ts` (new): the Anthropic tool-reference integrity pass (`demoteUnavailableToolReferences` and its helpers) moved out of `packages/ai/src/api/anthropic-messages.ts` into its own module, mirroring `anthropic-tool-pairs.ts`. `packages/ai/src/api/anthropic-messages.ts` only imports the pass now (and keeps `httpStatusOfError`, which #1487 added beside it).
- `resolveAvailableToolName` compares names with case and `_`/`-` separators folded away (`foldToolNameKey`) after the literal and namespace-stripped literal lookups fail. `collectAvailableToolNames` builds the folded index from the request's `tools` array once per request and drops any folded key that two request tools share, so the fold never guesses between candidates; such a reference stays unresolved and is dropped like before.
- `packages/ai/test/anthropic-tool-reference-integrity.test.ts`: three cases pin the fold (recased native search references `mcp__a4e6__Memory` / `LspSymbols` / `XSearch` plus a hyphenated literal fold onto `memory` / `lsp_symbols` / `x_search` / the literal; a recased namespaced history `tool_use` is renamed; an ambiguous fold is dropped).

### Why

- Live 2026-09-08 (omo 5.0.0-0.beta.48 / senpi 2026.9.7-2, session 01a08016, claude-fable-5-1 through ccapi): a native tool search returned its references as `mcp__a4e6__Memory`, `mcp__a4e6__LspSymbols`, `mcp__a4e6__XSearch`, `mcp__a4e6__Eval` — namespaced AND recased. Every later Anthropic request failed with `Tool reference 'mcp__a4e6__Memory' not found in available tools` and the session fell back to another model each turn. The shipped engine predates #1480, so it replayed the block verbatim; on main, #1480's exact-suffix fold would have turned `Memory` into a dropped reference (no 400, but the discovery was lost and the search pair demoted) because `Memory !== memory`.

### Why an extension could not handle it

- Same seam as #1480: the repair runs against the final `tools` array right before the SDK call, on provider-native blocks the provider assembles from history.

### Expected merge conflict zones

- LOW: `anthropic-messages.ts` loses a fork-only block (the pass was fork-only since `5ecb30463`), so future upstream merges touch it less; the new module is fork-only.


## 2026-09-08 - Deliver provider HTTP status on rejected Anthropic requests (senpi #1481)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: when the complete `retryProviderRequest` operation finally rejects, a numeric HTTP status carried by the SDK error (`APIError.status`) is delivered once through `options.onResponse` (`httpStatusOfError`) before the error is rethrown. Success-path delivery is unchanged; errors without a status (network, aborts) report nothing rather than a fabricated code.
- `packages/ai/test/anthropic-on-response-error.test.ts`: a rejecting fake client proves status 400 and 500 reach `onResponse` exactly once and that a status-less error produces no callback.

### Why

- The SDK turns HTTP failures into rejections instead of a Response, so the success-only `onResponse` never fired for them. The native tool-search adapter's permanent 400 fallback (`noteResponseStatus`, senpi #1481) was unreachable on the live error path, and any other `after_provider_response` extension was blind to error statuses.

### Why an extension could not handle it

- The status exists only inside the provider's own request error object; an extension observing the payload hook or the assistant error message cannot recover the HTTP code.

### Expected merge conflict zones

- MEDIUM: the request construction block in `packages/ai/src/api/anthropic-messages.ts` (upstream has no error-path callback); LOW: the new test file (fork-only).
## 2026-09-08 - Anthropic tool references resolve against the request's own tools (senpi native tool-search 400)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `demoteUnavailableToolReferences` now decides availability from the final `tools` array alone and repairs every reference site. A `tool_reference` whose `tool_name` carries a gateway namespace (`mcp__<id>__<tool>`) is folded back to the request's own tool name when that tool is defined (`resolveAvailableToolName`); a reference that still does not resolve is dropped. Replayed native `tool_search_tool_result` blocks are repaired the same way (`rewriteToolReferenceItems`), and a search pair whose every reference stopped resolving is demoted to text together with its `server_tool_use`. A history `tool_use` under a gateway namespace is renamed to the request's tool name; a `tool_use` whose only justification was a dangling discovery is demoted like any other unavailable call. `collectToolReferenceNames` is gone: discovered names no longer stand in for missing definitions.
- `packages/ai/test/anthropic-tool-reference-integrity.test.ts`: five cases pin the invariant (namespaced native reference folded to `memory`; mixed list keeps the resolvable names; emptied search pair demoted; namespaced history `tool_use` renamed; dangling discovery no longer keeps its `tool_use`).

### Why

- Live 2026-09-08 (senpi 4adba7afb, omo desktop, claude-fable-5-1): a native tool search returned `tool_reference` names as `mcp__925c__memory`, `mcp__925c__todo`, ... — a namespace neither senpi nor the request defined — and the block replayed verbatim on the next request, which Anthropic rejected with `Tool reference 'mcp__925c__memory' not found in available tools`. The turn hard-errored and fell back to a weaker model. The repair pass saw the names as dangling but only rewrote `tool_result` content, so native results fell through untouched, and a dangling discovery still exempted a later `tool_use` from demotion.

### Why an extension could not handle it

- The reference repair runs after every `before_provider_request` hook, immediately before the SDK call, against the final tools array; an extension cannot see that array or the replayed provider-native blocks the provider itself assembles from history.

### Expected merge conflict zones

- MEDIUM: the `demoteUnavailableToolReferences` block and its helpers in `packages/ai/src/api/anthropic-messages.ts` (upstream has no gateway-namespace handling); LOW: the integrity test file (fork-only).

## 2026-09-08 - Simple stream options carry the requested service tier (code-yeongyu/oh-my-openagent#6795)

### What changed

- `packages/ai/src/types.ts`: `SimpleStreamOptions.serviceTier` (`ServiceTierPreference`: `"auto" | "flex" | "priority"`) names the processing tier a caller requests.
- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`: `streamSimple` forwards that option into the provider options, so it reaches `service_tier` on the wire and the tier-aware usage pricing, exactly like a full `stream()` call. Azure is unchanged (it does not sell Priority processing).

### Why

- The simple path dropped `serviceTier` in `buildBaseOptions`, so the only way to send the field was to mutate the request payload from an extension hook. A session that loads no extensions (SDK embedders, oh-my-openagent's in-process delegated children) could therefore never run at the priority tier even when its model was a `-fast` catalog variant.

### Why this lives in the fork

- `streamSimple` is the provider-neutral entry every host goes through; the field has to be threaded there.

### Expected merge conflict zones

- LOW: `SimpleStreamOptions` in `types.ts`; the `streamSimple` option literals in both Responses adapters.

## 2026-09-07 - Classify OpenAI context-window overflow and token rate limits (code-yeongyu/oh-my-openagent#7921)

### What changed

- `packages/ai/src/utils/overflow.ts`: widen the OpenAI overflow pattern so "exceeds the model's context window" and "exceeds this model's context window" match, and add NON_OVERFLOW exclusions for tokens-per-window quota wording, TPM/RPM, quota exceeded, retry-after, HTTP 429 prefixes, and overloaded providers so those stay on the rate-limit path (code-yeongyu/oh-my-openagent#7921).

### Why

- OpenAI's current overflow text does not contain "exceeds the context window" as a contiguous phrase, so compaction recovery missed real overflows. Generic overflow fallbacks also matched token-quota 429s ("too many tokens per minute", "exceeds the limit of N tokens per minute"), so the agent showed a context-overflow error instead of the provider rate-limit error.

### Why an extension could not handle it

- `isContextOverflow` is the shared pi-ai classifier that compaction and overflow recovery consult before any extension hook runs; only a core pattern change can correct both the miss and the false positive.

### Expected merge conflict zones

- LOW: `packages/ai/src/utils/overflow.ts` OVERFLOW_PATTERNS OpenAI entry and NON_OVERFLOW_PATTERNS.

## 2026-09-05 - Project Astra configuration updates at the Responses wire

### What changed

- packages/ai/src/api/mistral-conversations.ts: ignore the Astra-only configuration-update role on Mistral.
- packages/ai/src/api/openai-responses-shared.ts: emit the configuration-update item at its original position for Astra Responses requests.
- packages/ai/src/providers/faux.ts: ignore the Astra-only configuration-update role in faux providers.
- packages/ai/src/types.ts: define the configuration-update message shape.
- packages/ai/src/utils/estimate.ts: account for the non-token-bearing configuration-update role.

### Why

- The Responses API requires a positional configuration-update item for cache-preserving reasoning changes, while other providers must ignore it.

### Why this lives in the fork

- Message conversion and token estimation happen inside the AI provider boundary before extensions can alter the request.

### Expected merge conflict zones

- Responses message conversion and provider-specific message handling.

## 2026-09-05 - Infer map-less GPT-6 Astra reasoning controls

### What changed

- `packages/ai/src/models.ts` infers the canonical GPT-6 Astra OpenAI-family thinking ladder when model metadata omits a map; `packages/ai/src/api/openai-completions.ts` and `packages/ai/src/api/openai-responses.ts` use that inference for wire effort mapping.

### Why

- Custom map-less Astra models must clamp unsupported `minimal` and `off` selections to `low` instead of sending unsupported `minimal` or `none` values, while preserving xhigh/max and GPT-5.6 Sol behavior.

### Why an extension could not handle it

- Model capability inference and request effort serialization run inside the core model and provider adapter paths before extensions can modify the request.

### Expected merge conflict zones

- LOW: `packages/ai/src/models.ts` model capability helpers; `packages/ai/src/api/openai-completions.ts` and `packages/ai/src/api/openai-responses.ts` reasoning mapping.

## 2026-09-05 - Account for Fast-mode responses in OpenAI adapters

### What changed

- `packages/ai/src/api/openai-responses.ts`, `packages/ai/src/api/openai-codex-responses.ts`, and `packages/ai/src/api/openai-responses-shared.ts` widen local service-tier handling with `fast`, apply the priority cost multiplier, and resolve Codex request/response tiers correctly.

### Why

- GPT-6 Astra echoes `fast` for Fast mode, and the pinned SDK union does not yet include that documented value; without this, usage was billed at the default rate.

### Why an extension could not handle it

- Response parsing, service-tier resolution, and usage accounting are implemented within the provider adapters before extension code can observe the completed usage.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/openai-responses.ts` and `packages/ai/src/api/openai-codex-responses.ts` multiplier/resolution helpers; `packages/ai/src/api/openai-responses-shared.ts` stream option contracts.

## 2026-09-04 - Credential-store lock contention stays on the transient retry path

### What changed

- `packages/ai/src/utils/retry.ts`: `RETRYABLE_PROVIDER_ERROR_PATTERN` recognises the coding-agent's `Credential store is busy: lock ...` message (`CredentialStoreBusyError`), so an exhausted local credential/auth/settings lock wait is classified as retryable infrastructure contention.

### Why

- Without the pattern the message fell through as an unknown provider error, which the fallback machinery treated as a model failure and hopped providers (oh-my-openagent#7748: claude-sdk-oauth -> opengateway 401). Lock contention between omo processes sharing `~/.omo` is transient and local; the same provider should simply be retried.

### Why an extension could not handle it

- Retry classification runs inside pi-ai's provider retry loop before any extension observes the assistant error.

### Expected merge conflict zones

- LOW: the retryable pattern list in `retry.ts`.

## 2026-09-04 - Adopt the Mistral indexed-chunk and Responses max_output_tokens fixes

### What changed

- `packages/ai/src/api/mistral-conversations.ts`: streamed tool-call chunks are keyed by the provider chunk index when present, falling back to the derived call id, instead of the old callId-plus-index-or-zero key (upstream 6c87d9a02, #8387).
- `packages/ai/src/api/openai-responses.ts`: a new `supportsMaxOutputTokens` compat flag (default true) gates sending `max_output_tokens`, so Responses-compatible gateways that reject the parameter can opt out (upstream b8b873b98, #8941).

### Why

- Mistral streams indexed argument chunks with missing or duplicated ids; the old key collapsed index 0 and an absent index into the same slot and mis-assembled tool calls. Some OpenAI Responses-compatible gateways (for example Codex-protocol proxies) reject `max_output_tokens` with a 400, and the API always sent it when `maxTokens` was set with no way to opt out.

### Why an extension could not handle it

- Stream chunk assembly and request body construction happen inside the provider API clients, below the extension boundary.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/mistral-conversations.ts` tool-call block keying in `consumeChatStream` and `packages/ai/src/api/openai-responses.ts` in `getCompat` and `buildParams`.

## 2026-09-04 - Failed assistant turns are dropped from converted LLM context

### What changed

- `packages/ai/src/utils/drop-failed-assistant-turns.ts` (new): `dropFailedAssistantTurns(messages)` removes every assistant message whose `stopReason` is `error` or `aborted`, plus every `toolResult` whose `toolCallId` was declared only by those dropped assistants; a call id re-declared by any kept assistant keeps its result, mirroring the `droppedCallIds` pairing in `api/transform-messages.ts`. Order and all other messages are preserved.
- `packages/ai/src/index.ts`: the helper is exported from the package barrel.
- `packages/ai/test/drop-failed-assistant-turns.test.ts` (new): pins the drop of error/aborted turns and their orphaned results, the re-declared-id keep, and the stop/length/toolUse pass-through.

### Why

- Two lanes build LLM requests straight from `convertToLlm` output with no `stopReason` filter (the claude-sdk-oauth prompt bridge and cursor turn building), so after a provider error or abort every subsequent request replayed the failed turn's partial text and unexecuted tool calls; token estimation counted them too. The provider transform layer already dropped them, but only for pi-ai API requests.

### Why an extension could not handle it

- The drop must happen inside `convertToLlm`, which both lanes consume before any extension seam runs; extensions observe the already-built context and cannot remove a failed assistant turn from every downstream request shape deterministically.

### Expected merge conflict zones

- LOW: `packages/ai/src/index.ts` (one barrel line beside the other utils exports).

## GPT-6 Astra joins the xhigh and max effort families (2026-09-04)

### What changed

- `packages/ai/src/models.ts`: `XHIGH_MODEL_IDS` gains `gpt-6-astra`, and the sol-only native `max` family check becomes `OPENAI_MAX_MODEL_IDS` (`gpt-5.6-sol`, `gpt-6-astra`), so map-less custom providers that ship the Astra id still surface both tiers.

### Why

- OpenAI documents `reasoning.effort` low/medium/high/xhigh/max for `gpt-6-astra`; the generated catalogs carry the map, and the id-based inference must agree for models registered without one.

### Why an extension could not handle it

- Effort-tier inference lives in this runtime module.

### Expected merge conflict zones

- `packages/ai/src/models.ts` (id lists), trivially adjacent to upstream additions.

## 2026-09-03 - Align Anthropic beta-client fallback and thinking semantics

### What changed

- Anthropic managed effort requests retain the stable top-level `output_config.effort: "high"` while selected per-turn effort remains in the marker; thinking-off managed models now emit `thinking.type: "disabled"` when supported.
- The Anthropic beta request path continues to preserve the pre-output fallback receipt behavior and the unsupported mid-output fallback error.

### Why

- The upstream SDK contract uses `client.beta.messages.create`; managed model semantics require per-turn effort markers and a real disabled-thinking request when the user turns reasoning off.

### Why this cannot be expressed externally

- Request construction, SSE fallback handling, and thinking normalization are owned by the Anthropic adapter below extension hooks.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` request construction and SSE event loop during future upstream syncs.

## 2026-09-03 - Restore Anthropic mid-output fallback failure path after upstream sync

### What changed

- Restored the Anthropic SSE guard that fails immediately when a `fallback` content block arrives after output has begun, preserving the explicit `unsupported mid-output model fallback` error instead of allowing an incomplete stream to report only a missing `message_stop`.
- Restored the managed-provider argument to Anthropic message conversion so persisted per-turn effort levels reconstruct their exact historical marker prefix; managed requests retain the stable top-level `output_config: { effort: "high" }` while per-turn markers carry the selected effort.

### Why

- The upstream re-integration retained beta-client and effort-marker machinery but lost two fork-side merge behaviors. Without the SSE guard, Anthropic could replace a partially emitted response without a safe error. Without provider-scoped conversion, historical effort metadata was not associated with assistant messages and the marker prefix was omitted.

### Why this cannot be expressed externally

- Both behaviors are owned by the Anthropic adapter: the fallback decision occurs inside the SSE event loop, and effort markers are constructed while converting persisted conversation history into Anthropic wire messages before extension hooks can repair the payload.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` SSE `content_block_start` handling and `buildParams()` / `convertMessages()` effort-marker plumbing during future upstream syncs.

## OpenRouter native Anthropic routing declared ahead of the catalog (2026-09-03)

### What changed

- `providers/openrouter.ts`: the provider is now built with an explicit
  `createProvider<"anthropic-messages" | "openai-completions">` type argument so the upstream
  `anthropic-messages` entry in its `api` map type-checks. The committed catalog
  (`providers/data/openrouter.json`) still declares every `anthropic/*` model as `openai-completions`,
  because the generator rule that flips them (`scripts/generate-models.ts`, `useAnthropicMessages`)
  only takes effect on a live regeneration, which this merge deliberately did not run.
- `openai-responses-compat.ts`: added `supportsMaxOutputTokens`, which upstream reads in
  `api/openai-responses.ts` but which the fork's extracted Responses compat interface was missing.
- `utils/prompt-cache-ttl.ts`: resolver defaults for the new compat flags -
  `supportsMaxOutputTokens` defaults to `true`, `vllmPriority` stays unset (off by default) and is
  therefore excluded from `ResolvedOpenAICompletionsCompat`'s `Required<>` core, and
  `supportsMidConvoEffort` is excluded from the Anthropic resolver because every consumer reads it
  straight off `model.compat`.

### Why

- Adopting upstream's per-turn effort and OpenRouter Claude routing requires the compat surface and
  provider typing to exist even before the model catalog is regenerated; without these the tree does
  not compile.

### Why an extension could not handle it

- Provider construction, the compat type surface, and catalog resolution are core `packages/ai`
  wiring that runs before any extension is loaded.

### Expected merge conflict zones

- MEDIUM: `providers/openrouter.ts` and the compat resolvers will conflict on the next sync if
  upstream keeps extending Responses/Completions compat flags. Regenerating the model catalog will
  flip the `anthropic/*` entries and make the explicit type argument redundant.

## Upstream AI provider compatibility merge (2026-09-03)

### What changed

- Merged Anthropic Messages beta request types and per-turn effort persistence, including provider-scoped mid-conversation effort markers while retaining Senpi's refusal fallback, signature replay, tool-pairing, and cache checkpoint behavior.
- Added OpenAI Completions vLLM priority and upstream model routing/catalog compatibility while retaining Senpi request retry and reasoning-detail handling. Pinned `@anthropic-ai/sdk` to `0.123.0` for the beta stop-reason and dropped-input transformation types.

### Why

- The upstream provider behavior is required for Claude 5 effort changes, OpenRouter native Anthropic routing, Fireworks GLM completions, and vLLM scheduling without regressing Senpi's provider-specific safeguards.

### Why an extension could not handle this

- These changes are shared wire-format construction, generated model metadata, and SDK type contracts executed below the extension/provider composition boundary.

### Expected merge conflict zones

- LOW: future upstream syncs in `api/anthropic-messages.ts`, `api/openai-completions.ts`, `types.ts`, `scripts/generate-models.ts`, and provider-composition model defaults.

## Provider requests are refused, not shrunk to one token, once the context window is exhausted (2026-09-03)

### What changed

- `packages/ai/src/api/context-room.ts` (new): owns `clampMaxTokensToContext`, `CONTEXT_SAFETY_TOKENS`,
  `MIN_ANSWER_TOKENS`, and the new `ContextWindowExhaustedError`. The clamp still fits the requested output budget into
  `contextWindow - estimateContextTokens(context).tokens - CONTEXT_SAFETY_TOKENS`, but when that room drops below
  `MIN_ANSWER_TOKENS` (1024) it throws `ContextWindowExhaustedError` instead of flooring `max_tokens` at 1. Windows
  smaller than `CONTEXT_GUARD_MIN_WINDOW` (5120 = safety margin + one answer) cannot satisfy that geometry at all and
  keep the previous one-token floor, so tiny-window fixtures and models behave exactly as before. The error
  message names the estimate and the window ("Context window exhausted: the conversation is estimated at X of Y tokens,
  leaving fewer than 1024 tokens for a response. Compact the conversation, enable auto-compaction, or start a new session
  before retrying.") and carries `estimatedTokens` / `contextWindow` as typed fields.
- `packages/ai/src/api/simple-options.ts`: `clampMaxTokensToContext` and `MIN_ANSWER_TOKENS` moved to
  `context-room.ts`; `simple-options.ts` re-exports them (plus `CONTEXT_SAFETY_TOKENS` and
  `ContextWindowExhaustedError`) so `buildBaseOptions`, `anthropic-messages.ts`, `bedrock-converse-stream.ts`, and tests
  keep their import sites. `buildBaseOptions` therefore throws before any provider request is built once the window is
  exhausted; the lazy API boundary (`lazyStream`) turns that throw into an assistant `stopReason: "error"` message with
  the text above, and the harness `ModelRuntime` / provider-composer `lazyStream` wrappers do the same for extension
  providers.
- `packages/ai/src/utils/overflow.ts`: `OVERFLOW_PATTERNS` gains `/^Context window exhausted: /` so
  `isContextOverflow` classifies the guard's error as a context overflow; the retry classifier leaves it `unknown`
  (never retried).

### Why

- Observed on 2026-09-03 (session `01a06520`, anthropic `claude-fable-5-1`, 1M window, auto-compaction disabled): at
  an estimated 995,154 tokens the clamp produced `max_tokens: 750`; the model's tool call was cut mid-arguments and the
  agent loop reported "Tool call stream ended before completion. Re-issue the tool call with complete arguments."; the
  re-issued request got `max_tokens: 1`, stopped after one token, and the TUI rendered "Model stopped because it reached
  the maximum output token limit". Both messages hid the real cause and each doomed request billed ~1M cached tokens.
- A request that cannot produce a minimal answer is never worth sending. Refusing it with a typed, overflow-classified
  error lets the existing overflow route compact and retry when auto-compaction is enabled, and gives the user an
  actionable message (compact / enable auto-compaction / new session) when it is not.

### Why an extension could not handle it

- The clamp runs inside `buildBaseOptions`, in every provider adapter, after the harness has emitted its last
  `before_provider_request` hook; no extension seam sits between the token estimate and the request body. Extensions also
  cannot see the `max_tokens` the adapter is about to send, so they cannot tell a doomed request from a normal one.

### Expected merge conflict zones

- LOW: the `clampMaxTokensToContext` / `MIN_ANSWER_TOKENS` region of `packages/ai/src/api/simple-options.ts` (upstream
  keeps both definitions inline; the fork re-exports them from `context-room.ts`).
- LOW: the head of `OVERFLOW_PATTERNS` in `packages/ai/src/utils/overflow.ts` and its provider list comment.

## A legacy flat credential is promoted, not overwritten, by a second login (2026-09-03)

### What changed

- `packages/ai/src/auth/pool/slots.ts`: `appendLoginSlot` whole-writes the login result only when there is no stored
  credential at all (`if (!current)`), instead of also whole-writing whenever the stored credential is flat. A flat
  `current` now takes the `upsertSlot` path, so `listSlots` synthesizes its `default` slot from the flat fields and the
  fresh login is appended as the next generated `login-N`. The provider-owned pool guard added for senpi#1279 keeps its
  place ahead of both branches and is unchanged, as is the pooled-`current` append.
- `packages/ai/src/auth/pool/slots.ts`: `removeSlot` re-projects the flat top-level fields from the first surviving slot
  when the removed slot was the one those fields mirrored (matched by `access`/`refresh` for OAuth, by `key` for an API
  key). Removing a slot whose material the flat fields never carried still leaves them byte-identical, the last-slot
  removal still returns `undefined`, and a pin naming the removed slot is still cleared. `accounts` is preserved in every
  surviving case, so a one-slot pool stays a pool rather than collapsing to a bare flat credential; only its projection
  moves to the survivor.

### Why

- `openai-codex` OAuth `login` returns a plain flat `OAuthCredential` with no `accounts` array, so the #1279 guard never
  fires for it and the old flat-current disjunct did. A second `/login openai-codex` (or the coding-agent `AuthStorage.set`
  RPC path) therefore replaced the first account's tokens outright: the user lost the credential they were already using
  and the pool they were trying to build never came into existence (senpi LAB-109). Promotion is the same transition
  `setSlot` already performs, and `upsertSlot` keeps the pre-existing flat fields as the top-level projection, so a build
  that ignores `accounts` still authenticates with exactly the bytes it authenticated with before.
- Promotion alone made removal unsafe. After promotion the flat fields are the legacy `default`'s material, so removing
  `default` used to leave the pool listing only `login-2` while the flat projection still held the deleted account's
  tokens. That is not cosmetic: `mightHoldCredentialPool` in the coding-agent model runtime only routes through
  credential rotation when `accounts.length > 1`, so a pool with one slot left resolves through `resolveProviderAuth`'s
  flat branch and kept authenticating as exactly the account the user had just removed, with no way to pin around it.
  Re-projecting from the survivor makes the remaining account the effective credential the moment the removal lands.
- This supersedes the sentence in the 2026-09-03 senpi#1279 entry below that says a flat `current` still stores the flat
  credential as-is; that branch is what this pass changes. Every other branch it describes is still accurate.

### Why an extension could not handle it

- `appendLoginSlot` is the shared write step inside `ModelsImpl.login` and the coding-agent auth storage `set`, running
  after the provider's `login` resolves and before the credential is persisted. No provider or extension seam exists
  between producing the credential and the write that was discarding the previous account.
- `removeSlot` is the shared slot algebra behind `ModelsImpl.logout({ slotId })`, `AuthStorage.removeSlot` and
  `removeCredentialAccount`. Every removal caller reaches the flat projection only through it, so nothing above it can
  keep the projection and the surviving slot in agreement.

### Expected merge conflict zones

- LOW: the second condition of `appendLoginSlot` and its JSDoc in `auth/pool/slots.ts`, immediately below the senpi#1279
  guard that the open PRs #1304 and #1196 also touch.
- LOW: the `removeSlot` body and the two projection helpers added directly above it in `auth/pool/slots.ts`.

## OAuth prompt types carry the provider's cancellation signal (2026-09-03)

### What changed

- `src/compat/extension-oauth-types.ts`: `OAuthPrompt` and `OAuthSelectPrompt` gained an optional `signal?: AbortSignal`. Purely additive; every existing field and callback signature is untouched.

### Why

- `AuthStorage.handleLegacyPrompt` already hands the richer `AuthPrompt` (which carries `signal`) to `onPrompt` and `onSelect`, but the public callback types didn't say so. Extension and RPC callbacks that park a prompt on a dialog need that signal to notice when the provider gives up on the prompt (`loginAnthropic` aborts its `manual_code` prompt once the browser callback wins the race) and to release the dialog instead of leaving it dangling. The RPC login-prompt bridge for senpi#1316 is the first consumer.

### Why an extension could not handle it

- It's a type on the shared callback contract; an extension can only read what the type declares.

### Expected merge conflict zones

- LOW: the two interface bodies in `compat/extension-oauth-types.ts`.

## Login keeps a provider-owned credential pool intact (2026-09-03)

### What changed

- `packages/ai/src/auth/pool/slots.ts`: `appendLoginSlot` returns the login result untouched when that result already carries a populated `accounts` array. Every other branch is unchanged: an absent or flat `current` still stores the flat credential as-is, and an unnamed flat credential against a pooled `current` still becomes the next generated `login-N` slot with its own material.

### Why

- A provider whose own `login` returns the complete pooled credential (claude-sdk-oauth builds it with `addAccount`) was double-pooled: the shared login path read that result's top-level fields as if they were a flat credential and appended them as a second slot. For claude-sdk-oauth those top-level fields are the managed sentinel, so a second account produced a `login-2` slot holding `claude-sdk-oauth-managed` instead of the newly issued tokens, and selecting that slot failed authentication (senpi#1279).

### Why an extension could not handle it

- `appendLoginSlot` is the shared write step inside `ModelsImpl.login` and the coding-agent auth storage `set`; it runs after the provider's `login` returns and before the credential is persisted, so no provider or extension seam exists between producing the pool and mangling it.

### Expected merge conflict zones

- LOW: the guard at the top of `appendLoginSlot` and its JSDoc in `auth/pool/slots.ts`. The same hunk appears in the open PRs #1304 and #1196.

## Anthropic OAuth advertises Claude Code 2.1.251 (2026-09-02)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `claudeCodeVersion` goes from `2.1.75` to `2.1.251`, so the OAuth client's `user-agent` header is `claude-cli/2.1.251`. Same value as upstream pi commit `96317e50`; the OAuth beta list, `x-app`, and tool naming are untouched.

### Why

- Anthropic now rejects OAuth requests for Claude Fable 5.1 and Opus 5 whose advertised Claude Code version is below 2.1.251 (`error_code: claude_code_version_too_old`), regardless of the Claude Code actually installed on the machine. Tracked as oh-my-openagent#7650. `test/anthropic-oauth-claude-code-version.test.ts` pins the advertised version at or above that minimum.

### Why an extension could not handle it

- The header is assembled inside `createClient()` before `onPayload` hooks run and is not part of the model or request options an extension can override; the SDK client is constructed with it as a default header.

### Expected merge conflict zones

- LOW: the single `claudeCodeVersion` constant near the top of `api/anthropic-messages.ts`; upstream already carries the identical value, so the next pin sync should resolve cleanly.

## senpi-default retry profile is more patient with slow providers (2026-09-02)

### What changed

- `utils/retry-profile/profiles.ts`: `SENPI_DEFAULT_RETRY_PROFILE.turn.maxRetries` goes from 3 to 5. Backoff shapes, the server-hint policies, `providerRequest.maxRetries` (still 0, so no hidden second budget), and `KIMI_CODE_RETRY_PROFILE` are untouched.

### Why

- Opus/Fable-class models with xhigh thinking make transient provider failures more likely per turn, and the previous turn budget was the least tolerant of the harnesses we compared: opencode retries a session 5 times, codex defaults to `stream_max_retries` 5, and oh-my-pi allows up to 10 agent retries. The `providerRequest` server-hint ceiling was deliberately left alone: `planRetryDelay` has no production caller today, so changing that constant would have been an inert edit dressed up as a fix.

### Why an extension could not handle it

- Shipped profile constants are read by the provider-request and turn retry planners before any extension seam exists; an extension can only override them per provider through settings, not change what every session inherits.

### Expected merge conflict zones

- LOW: the two constant lines inside `SENPI_DEFAULT_RETRY_PROFILE` in `utils/retry-profile/profiles.ts`.

## Actionable provider stream-start timeout guidance (2026-09-02)

### What changed

- `isProviderTimeoutError` accepts the actionable guidance suffix now appended to stream-start timeout messages while preserving strict matching of unrelated timeout text.

### Why

- Adding the setting name to a provider timeout must not disable retry classification.

### Why an extension could not handle it

- Timeout classification is centralized in the AI package and runs before coding-agent retry policy.

### Expected merge conflict zones

- LOW: `utils/retry.ts` provider timeout pattern.

## 2026-09-09 - Keep Anthropic thinking parameters stable across tool continuations

### What changed

- `api/anthropic-messages.ts` `buildParams()`: the "final assistant turn starts with tool_use" guard now degrades thinking only for a budget-thinking request (`thinking.type: "enabled"`) whose final assistant turn came from a different wire API (`finalAssistantTurnIsForeign`, the Kimi/OpenAI replay shape the guard was written for). Adaptive requests, and native turns under budget thinking, keep the caller's `thinking` and `output_config.effort`.

### Why

- With adaptive thinking the model routinely answers a trivial tool call with `tool_use` and no thinking block. The old guard then sent the tool continuation with `thinking: {type: "disabled"}` (and no `output_config`), and Anthropic keys the prompt cache on the thinking parameters: the continuation missed the whole cached prefix and re-wrote it (2026-09-09 capture, claude-opus-5 through a logging proxy: turn 2 first call `cache_read 28114`, its tool continuation `cache_read 0 / cache_creation 28239`, next turn `cache_read 28181` from the adaptive line). That is the "cache misses every second prompt / burns the 5h limit" report; every tool-using turn paid a full cache write.
- The premise no longer holds for the models that matter: replaying that exact continuation with `thinking` left adaptive returned HTTP 200 on claude-opus-5, claude-opus-4-6 and claude-fable-5 (and 200 on claude-sonnet-4-5 under `enabled` thinking). The remaining risk is the original incident shape only - foreign history under budget thinking - so that is the only case that still degrades.

### Why an extension could not handle it

- The degrade happens inside the provider request builder after every extension hook has run; no extension sees or can veto the `thinking` rewrite.

### Expected merge conflict zones

- LOW: `src/api/anthropic-messages.ts` thinking degrade guard in `buildParams()` and the `finalAssistantTurnIsForeign` helper next to `finalAssistantTurnStartsWithToolUse`.
- LOW: `test/anthropic-cross-model-history.test.ts` (the Fable expectation flipped from `effort: low` to adaptive/high; two native-turn cases added).

## 2026-09-09 - Anthropic OAuth callback listener: ephemeral port fallback and idle timeout

### What changed

- `auth/oauth/anthropic.ts`: the login now binds its callback listener through `auth/oauth/anthropic-callback-listener.ts` (new, fork-only). The listener still prefers `127.0.0.1:53692`, but when that port is already held (EADDRINUSE, EACCES, EPERM) it binds an ephemeral loopback port instead of dropping into manual mode; the auth URL `redirect_uri`, the manual-prompt placeholder, and the token-exchange `redirect_uri` all carry the port that was actually bound. Manual-only mode (registered `http://localhost:53692/callback` redirect, paste the redirect URL) is now reached only when neither the preferred nor an ephemeral port can be bound.
- `auth/oauth/anthropic.ts`: a login that receives neither a browser callback nor a pasted redirect URL for 10 minutes rejects with a timeout error and closes its listener, instead of holding the port and the manual prompt open indefinitely.
- `auth/oauth/anthropic-callback-listener.ts`: a callback whose `state` belongs to another login answers HTTP 400 with a page that says the login belongs to a different session or an earlier attempt and tells the user to paste the address-bar URL into the session that is waiting (or to restart the login), instead of the bare "State mismatch." page.
- `auth/oauth/authorization-input.ts` and `auth/oauth/error-details.ts` (new, fork-only): `parseAuthorizationInput` and `formatErrorDetails` moved out of `anthropic.ts` unchanged.

### Why

- Two senpi/omo processes on one machine (a second TUI session, an RPC host whose login prompt was never answered, an abandoned `/login`) could not both log in: the second login hit EADDRINUSE, fell back to manual mode while still advertising `localhost:53692`, and the browser redirect landed on the first process's stale listener, which rendered "State mismatch." on every retry (omo Discord report, 2026-09-09). The OAuth client is registered for any localhost port on `/callback` - the Claude Code CLI itself binds a random port - so a fixed port was never required.
- A pending login had no deadline, so one abandoned attempt kept the port for the life of the process.

### Why an extension could not handle it

- The callback listener, the redirect URI it advertises, and the token exchange are created and owned inside the provider OAuth implementation before any auth interaction event reaches an extension; an extension can neither pick the port nor change the redirect URI the exchange must match.

### Expected merge conflict zones

- MEDIUM: `src/auth/oauth/anthropic.ts` callback listener startup, auth URL construction, manual prompt, cleanup (listener code moved out of the file).
- LOW: `test/anthropic-oauth.test.ts` callback listener coverage.

## 2026-09-02 - Anthropic OAuth callback bind fallback

### What changed

- The login abort handler now aborts the manual `manual_code` prompt as well as the callback wait, so cancelling a manual-only login (callback port unavailable) settles instead of leaving `loginAnthropic` pending.
- `auth/oauth/anthropic.ts`: Anthropic OAuth now falls back to manual redirect URL entry when local callback port 53692 cannot bind with EACCES, EADDRINUSE, or EPERM, while preserving the registered localhost redirect URI.

### Why

- Fixed or restricted callback ports can be unavailable on Windows, sandboxed hosts, or when another senpi/Claude process is already listening, so login must not fail before presenting its existing manual-code path.

### Why an extension could not handle it

- The callback listener is created and owned inside the Anthropic provider OAuth implementation before auth interaction events are emitted; an extension cannot intercept its bind failure or preserve the provider's registered redirect URI.

### Expected merge conflict zones

- MEDIUM: `src/auth/oauth/anthropic.ts` callback listener startup, auth URL instructions, and cleanup.
- LOW: `test/anthropic-oauth.test.ts` OAuth interaction coverage.

## Cursor conversation cache eviction cannot break a live request (2026-08-31)

### What changed

- `api/cursor-agent.ts`: `ConversationBlobStore` is now a true LRU (reads promote recency, not only writes) and pins every blob the in-flight request stores or the server reads back, for the lifetime of that request's stream. The byte cap evicts unpinned blobs only; if the pinned working set alone exceeds the cap the store stays temporarily over budget and logs once, and trims back when the stream settles.
- `api/cursor-agent.ts`: the conversation count cap is enforced per owning session (the `conversationId -> sessionId` map added in this pass) instead of over the process-global maps, and never evicts a conversation with a request in flight.
- `api/cursor-agent.ts`: a process-global blob ceiling (`PI_CURSOR_CONVERSATION_TOTAL_BLOB_LIMIT_BYTES`, default 1 GiB) bounds every cached conversation together, shedding cold conversations before live ones and never dropping a pinned blob.

### Why

- Cursor resolves history blobs by id mid-turn (`getBlobArgs`); the client answers a miss with an unset `blobData`. Immediate byte-cap eviction could drop a blob the request being built or streamed still references, so a long history silently lost context or failed the turn.
- The count cap iterated the process-global maps, so session B's 65th conversation could forget session A's live conversation key; A's retry/resume then re-entered through the same global map and fell back to fresh empty state.
- Per-conversation caps multiply (count cap x byte cap per session), so the only number that actually bounds the process is a shared ceiling.

### Why an extension could not handle it

- The conversation state cache, blob stores and their eviction are module-local to the Cursor adapter; no extension seam can observe a blob id the wire protocol resolves mid-stream.

### Expected merge conflict zones

- MEDIUM: `ConversationBlobStore` and the cache-limit helpers in `api/cursor-agent.ts`.
- LOW: the per-attempt live/pin retain-release pair in the `stream` retry loop.

## Session-scoped provider state hygiene (2026-08-31)

### What changed

- `api/anthropic-messages.ts`: the learned unsigned-thinking text-replay fallback set is cleared for a session when its session resources are cleaned up (registered on the shared session-resource cleanup seam).
- `api/openai-responses.ts`: the session-websocket idle expiry re-arms itself when it fires while the socket is busy, and drops a busy entry whose socket already died, so a lost release can no longer pin a cached websocket forever.

### Why

- Both collections previously lived for process lifetime once touched: long-lived multi-session hosts accumulated one fallback key per (session, base URL, model) that ever hit the invalid-signature retry, and a cached websocket whose release path never ran stayed pinned forever. Part of the #1024 memory-hygiene pass.

### Why an extension could not handle it

- The fallback set and the websocket session cache are module-local state inside the provider adapters; no extension seam can reach or dispose them.

### Expected merge conflict zones

- LOW: the fallback set declaration and its cleanup registration in `api/anthropic-messages.ts`.
- LOW: the `scheduleSessionWebSocketExpiry` timer body in `api/openai-responses.ts`.

## Stop replaying the Anthropic server-side fallback marker (2026-08-30)

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: `REPLAYABLE_ANTHROPIC_PROVIDER_NATIVE_TYPES` no longer contains `fallback`. The stored marker (`providerNative` subtype `fallback`) remains session audit metadata and still drives declined-attempt pruning (`lastAnthropicFallbackBoundary`, `collectDiscardedFallbackToolCallIds`), but it is never serialized into request params.
- `packages/ai/test/anthropic-provider-native-replay.test.ts`: new regression test `never replays the fallback marker itself into request content`; the three existing fallback replay expectations updated to the marker-absent contract.

### Why

- Production 400 loop (omo session 01a050f8, 2026-08-30): after a client retry-fallback switched the session to the model that had served a server-side fallback (`claude-opus-4-8`), `isSameAnthropicModel` became true and the raw `{type:"fallback"}` marker replayed verbatim as `messages.253.content.0`. The Messages API rejected every subsequent request with `Input tag 'fallback' found using 'type' does not match any of the expected tags`, wedging the session permanently.
- Live wire probes (2026-08-30, ccapi): a marker-bearing assistant input 400s with exactly that error on routes without the `server-side-fallback` beta and is merely tolerated on beta routes, while the marker-stripped shape is accepted on both. Replaying the marker buys nothing and breaks every cross-route/model-switch replay, so the marker is stored-only now.

### Why an extension could not handle it

- The replay set is provider serialization internals in `convertMessages`; no extension hook exists between stored assistant content and the Anthropic payload.

### Expected merge conflict zones

- LOW: the `REPLAYABLE_ANTHROPIC_PROVIDER_NATIVE_TYPES` literal and its comment block.
- LOW: expectation arrays in `anthropic-provider-native-replay.test.ts`.

## Measure Cursor history at the wire representation (2026-08-29)

### What changed

- `packages/ai/src/api/cursor-agent.ts` exposes the shared serialized-history measurement used by Cursor admission.
- `packages/ai/src/index.ts` exports the measurement helper for the coding-agent package.

### Why

- Cursor history admission must measure the complete serialized request representation rather than a fixed envelope estimate.

### Why an extension could not handle it

- The measurement is part of the provider serialization boundary in the AI package.

### Expected merge conflict zones

- LOW: Cursor history measurement exports.

## 2026-08-28 - Restore Bedrock global GPT-5.6 strict tool sampling

### What changed

- `packages/ai/src/providers/data/amazon-bedrock.json`: `global.openai.gpt-5.6-luna`, `global.openai.gpt-5.6-sol`, and `global.openai.gpt-5.6-terra` carry `compat.supportsStrictMode: true` again (plus the matching `.manifest.json` hash). A catalog regeneration had dropped the field, so `bedrock-converse-stream.ts` read `model.compat?.supportsStrictMode ?? false` and rejected `constrainedSampling.strict: "require"` as unsupported while silently downgrading `"prefer"` to an unconstrained schema.
- `packages/ai/scripts/generate-models.ts`: `applyStrictToolCompatMetadata()` now re-stamps `supportsStrictMode` on those three Bedrock global inference profiles, so the capability survives future regenerations instead of depending on models.dev reporting `structured_output` (it reports it only for the regional `openai.gpt-5.6-*` IDs).
- `packages/ai/test/bedrock-strict-tool-compat.test.ts`: asserts the shipped catalog data and re-runs the generator offline against an upstream payload with no `structured_output` to prove the override survives regeneration.

### Why

- Strict JSON-schema tool sampling is a wire-visible provider capability. Losing it turned working `strict: "require"` requests into unsupported-capability failures on the global Bedrock GPT-5.6 profiles.

### Why an extension could not handle it

- The capability is read from the generated model catalog inside the Bedrock adapter; there is no extension-visible hook between the catalog and `convertToolConfig()`.

### Expected merge conflict zones

- LOW: three generated entries in `amazon-bedrock.json` plus its manifest hash line during catalog regeneration syncs.
- LOW: one `else if` branch in `applyStrictToolCompatMetadata()`.

## 2026-08-27 - Default retry policy phase-2 close-out (docs)

### What changed

- `packages/ai/src/utils/retry-profile/profiles.ts`: the senpi-default turn stage ships an 8s `perAttemptCapMs` and +0..25% additive jitter on locally computed exponential backoffs (provider-derived `Retry-After` hints stay exact). `classifyErrorMessage` remains tri-state (non-retryable / retryable / unknown) with non-retryable outranking retryable.
- The default same-model turn retry budget stays at 3 retries. This is an intentional non-change: the budget was reviewed during phase-2 close and kept at its existing value for all providers that don't declare their own profile.
- No new kimi-code observability or telemetry surface was adopted. The `provider_retry_failure` diagnostic added in phase 1 is the only retry-specific emission, and no additional counters, traces, or structured events were introduced.
- Regression coverage: `packages/coding-agent/test/suite/regressions/retry-default-no-kimi-leak.test.ts` guards senpi-default against kimi semantics leaking in (no-hint 429 first-failure fallback, 1258000ms hint tier routing, billing 429 pinned fallback, abort during backoff single `auto_retry_end`).
- Tracked in `packages/ai/src/changes.md` and `packages/coding-agent/src/core/changes.md`.

### Why

- Phase-2 close needs an explicit record that the 3-retry budget and the absence of new telemetry were deliberate decisions, not oversights. The profile defaults recap documents the shipped values in one place for reviewers who don't read `profiles.ts`.

### Why an extension could not handle it

- The profile constants and classifier live inside this package's retry-profile tree, below any extension-visible hook.

### Expected merge conflict zones

- NONE: doc-only section append; no code files touched.

## 2026-08-27 - Storage docs describe pooled entries

### What changed

- `packages/ai/src/auth/types.ts`, `packages/ai/src/auth/credential-store.ts`: the "one credential per provider" doc comments now say one ENTRY per provider, where an entry may pool sibling slots under `accounts` while its flat fields remain a valid credential (matching `auth/AGENTS.md`).

### Why

- The old sentence contradicted the shipped pooled-entry contract; stale invariants misdirect future changes into destroying sibling slots.

### Why an extension could not handle it

- Doc comments live in the module source.

### Expected merge conflict zones

- LOW: comment-only hunks.

## 2026-08-27 - Export the canonical provider API-key env-var mapping

### What changed

- `packages/ai/src/env-api-keys.ts`: `getApiKeyEnvVars` is now exported (previously module-private and reachable only through `findEnvKeys`/`getEnvApiKey`).

### Why

- Numbered environment credential slots (`OPENAI_API_KEY_2`, ...) must generalize over the same provider-id-to-env-var mapping the resolver already uses. Re-deriving that table in `packages/coding-agent` would let the two drift, and a drifted table silently discovers the wrong variable for a provider.

### Why an extension could not handle it

- The mapping is data owned by this module and reachable only from inside it; an extension can neither read it nor keep a copy in step with upstream catalog changes.

### Expected merge conflict zones

- LOW: one `export` keyword on an existing function declaration.

## 2026-08-27 - Credential pool engine: HRW selection, failure taxonomy, slot failover, slot-scoped resolution

### What changed

- `packages/ai/src/auth/pool/select.ts` (new): browser-safe HRW slot selection over an injected `SlotHasher` - `rendezvousOrder` hashes `key\0slot.name` exactly like the claude-sdk-oauth affinity oracle, `selectSlot` honors a pinned slot, skips blocked slots (auth blocks persist, elapsed rate blocks clear), and throws `AllSlotsBlockedError` with the soonest unblock time.
- `packages/ai/src/auth/pool/classify.ts` (new): three-way in-lane failure taxonomy (`rotate`/`retry`/`fail`) with `retryAfterMs` extraction; unknown errors default-deny to `fail` so the model fallback chain keeps owning them.
- `packages/ai/src/auth/pool/failover.ts` (new): `runSlotFailover` runs at most one attempt per slot, blocks failed slots (exponential rate-limit windows capped at 48h, expiry-free auth blocks), and reuses the `senpi:no-turn-retry:` suppression marker; `isCommittedOutput` is default-DENY, so absent an explicit bookkeeping filter any yielded event makes rotation non-transparent.
- `packages/ai/src/auth/pool/slots.ts`: added `projectSlot` (named-slot flat projection with pool fields stripped) and `mergeRefreshedSlot` (named-slot refresh merge that rotates the flat downgrade projection only when it mirrored that slot).
- `packages/ai/src/auth/resolve.ts`: `AuthResolutionOverrides.slotName` resolves one named slot of a pooled credential; a missing entry or slot resolves to undefined instead of falling back to another account or ambient env, and the locked OAuth refresh path refreshes exactly the named slot via `mergeRefreshedSlot`.

### Why

- Generic multi-credential rotation needs a provider-neutral engine: session-affine slot choice that provably never remaps existing claude-sdk-oauth sessions (golden-oracle test), failover that can rotate accounts mid-lane without replaying committed output, and an auth resolution path that can address a specific slot without disturbing siblings or the flat projection older binaries read.

### Why an extension could not handle it

- Slot-scoped resolution must run inside `resolveProviderAuth`'s locked OAuth refresh path, which is the cross-provider choke point in `packages/ai`; extensions cannot enter that lock or the credential-store modify transaction.

### Expected merge conflict zones

- LOW: `resolve.ts` stored-credential branch and the refresh modify callback; new pool files have no upstream counterpart.

## 2026-08-27 - Duplicate cursor exec tool-call ids no longer brick Anthropic resumes

### What changed

- `packages/ai/src/api/cursor-agent.ts` uniquifies exec-frame tool-call ids before synthesizing blocks (`ensureUniqueCursorExecToolCallId`): Cursor reuses one parent id across the exec sub-frames of a compound tool (observed: `StrReplace` → `read` + `write` both carrying `StrReplace_0_<hash>-<n>`), so the persisted assistant message carried duplicate `toolCall` ids.
- `packages/ai/src/api/anthropic-tool-pairs.ts` now also repairs duplicate `tool_use` ids payload-wide at the final pre-submit pass: later duplicates are renamed (`<id>__dedup<n>`) and the following user message's `tool_result` blocks are remapped in call order, so transcripts already corrupted by the cursor bug (or any other source) resume instead of failing every request with `tool_use ids must be unique` (invalid_request_error), which permanently bricked sessions.

### Why

- Field incident 2026-08-27: two omo-desktop threads could never resume — every turn errored with `messages.1.content.27: tool_use ids must be unique`. Forensics showed cursor/kimi StrReplace frames sharing one id for their read+write pair; 2 of 59 session transcripts on the host carried such duplicates (6 pairs total). The sanitizer heals existing transcripts; the cursor-agent guard stops new corruption at the source.

## 2026-08-25 - Preserve same-model redacted thinking during message transforms

### What changed

- `packages/ai/src/api/transform-messages.ts` preserves opaque redacted thinking blocks whenever the source and target model are the same, independent of `preserveProviderState`.

### Why

- Bedrock redacted reasoning is provider replay state that must survive same-model transformation; gating it on `preserveProviderState` dropped the block and changed the replayed request.

### Why an extension could not handle it

- Message transformation and provider-state preservation run inside the AI adapter boundary before extension code receives the outbound request.

### Expected merge conflict zones

- LOW: redacted-thinking handling in `transformMessages()` when upstream changes message replay policy.

## Provider wire layer re-diverges from upstream dcd4619 (2026-08-25)

### What changed

- `packages/ai/src/providers/cloudflare-ai-gateway.ts` keeps the fork's Cloudflare AI Gateway provider registration and Workers AI model mapping.
- `packages/ai/src/index.ts` keeps the fork barrel export for `estimateContextTokens`.
- `packages/ai/src/api/anthropic-messages.ts` keeps refusal fallback, provider-native content,
  prompt-cache TTL compat, 429 retry-after hints, and combined abort signals.
- `packages/ai/src/api/azure-openai-responses.ts` keeps `supportsMax`-aware effort mapping and
  `thinkingLevelMap` resolution.
- `packages/ai/src/api/bedrock-converse-stream.ts` keeps prompt-cache TTL gating, tool-call id
  normalization, `applyExtraBody` with reserved keys, and the trimmed smithy type imports.
- `packages/ai/src/api/google-generative-ai.ts` and `packages/ai/src/api/google-vertex.ts` keep the
  thinking-level maps, `applyExtraBody` with `GOOGLE_RESERVED_BODY_KEYS`, provider-header records,
  and grounding/url-context metadata emission.
- `packages/ai/src/api/mistral-conversations.ts` keeps `preserveThinking` message transformation and
  `MISTRAL_RESERVED_BODY_KEYS` extra-body support.
- `packages/ai/src/api/transform-messages.ts` keeps same-model redacted-thinking replay: opaque
  redacted blocks are preserved for the same model regardless of `preserveProviderState` (upstream
  additionally gates on it), so Bedrock redacted reasoning replays instead of being dropped.
- `packages/ai/src/api/openai-completions.ts` keeps moonshot/compat tool-schema normalization,
  forced-tool-choice fallback, stream-aware retries, and `supportsMax`/`supportsXhigh` effort.
- `packages/ai/src/api/openai-responses.ts` keeps the responses-websockets beta header, Cloudflare
  base-url routing, client-auth resolution, reserved body keys, and `clampMaxForOpenAI`.
- `packages/ai/src/index.ts` keeps fork re-exports (cursor pi-args helpers,
  `sanitizeAnthropicToolPairs`, cursor exec types).
- `packages/ai/src/types.ts` keeps the `cursor-agent` API id, the extended `OpenAIResponsesCompat`
  (`supportsAdditionalTools`), session-affinity formats, and `Model` re-exports.

### Why

These are fork-owned product surfaces (senpi branding, provider wire behavior, fork runtime features) that upstream does not carry; the sync must re-assert them on top of upstream's tree.

### Why this lives in the fork

The divergence lives in core wiring, package identity, or build plumbing that executes before any extension loads, so no extension hook can express it.

### Expected merge conflict zones

- Import blocks and option-mapping functions of every listed `packages/ai/src/api/*.ts` file, and the
  export list of `packages/ai/src/index.ts` — upstream touches these on nearly every provider change.

## 2026-08-26 - Detect Kiro payload-limit/context-limit rejections as context overflow

### What changed

- `packages/ai/src/utils/overflow.ts`: kiro-lb local byte/token payload-guard rejections (`Request payload is <n> bytes/tokens, over the <n> byte/token limit Kiro accepts.`) and kiro-lb's enhanced upstream context-limit response classify as context overflow.

### Why

- The local `KIRO_MAX_PAYLOAD_BYTES` guard is a gateway limit distinct from Kiro's upstream `CONTENT_LENGTH_EXCEEDS_THRESHOLD` token rejection. Both are client-visible HTTP 400 overflow paths, with route-specific wrappers (Anthropic `invalid_request_error`, OpenAI `detail`, and upstream `kiro_api_error`), so matching the emitted message lets input-shrinking recovery handle each instead of terminating the session.

### Why an extension could not handle it

- Overflow classification is a provider-neutral AI utility below extension-visible session behavior; retry policy reads the verdict before any extension sees the error.

### Expected merge conflict zones

- LOW: the tail of `OVERFLOW_PATTERNS` and the provider inventory comment in `packages/ai/src/utils/overflow.ts`.

## 2026-08-25 - Distinguish Cursor usage-pool exhaustion from context overflow

### What changed

- `packages/ai/src/utils/overflow.ts`: token-bearing Cursor `resource_exhausted` errors are context overflow only at or above half the supplied context window; added `isCursorQuotaResourceExhausted` for below-half usage-pool failures while preserving zero-token and no-window behavior.

### Why

- Cursor uses the same bare `resource_exhausted` status for quota exhaustion and context overflow. Proximity to the model window is the verified discriminator.

### Why an extension could not handle it

- Overflow classification is a provider-neutral AI utility below extension-visible session behavior.

### Expected merge conflict zones

- LOW: Cursor `resource_exhausted` handling in `packages/ai/src/utils/overflow.ts`.

## Unreleased

## 2026-08-29 - Cover GLM-5.3 generator negative variants

### What changed

- `packages/ai/src/api/openai-completions.ts`: narrowed the Z.AI always-enabled matcher to the exact `glm-5.3`, `glm-5.3-flash`, and `glm-5.3-highspeed` variants so unsupported variants are not forced into thinking.
- `scripts/generate-models.ts`: generated Z.AI records for unsupported GLM-5.3 variants omit `thinkingLevelMap` and `compat.supportsReasoningEffort`.
- `test/generate-models-strict.test.ts`: added an offline generator fixture covering `glm-5.3-turbo`, `glm-5.3-xl`, and `glm-5.3-anything-else`.

### Why

- Unsupported GLM-5.3 variants must not receive reasoning metadata or be forced into enabled thinking; only the validated base, Flash, and Highspeed variants should use the always-enabled Z.AI thinking path.

### Why an extension could not handle it

- Generated model capability metadata and OpenAI Completions request serialization are implemented inside the AI package.

### Expected merge conflict zones

- LOW: `api/openai-completions.ts` and the GLM-5.3 generator regression coverage.

## 2026-08-26 - Coalesce adjacent Anthropic user turns

### What changed

- `api/anthropic-messages.ts` now appends adjacent user content and trailing tool-result blocks to the existing Anthropic user message instead of emitting consecutive `user` roles.

### Why

- Interrupted tool turns and consecutively dispatched user messages could produce adjacent Anthropic user messages, which the API rejects because message roles must alternate.

### Why an extension could not handle it

- Anthropic wire-message serialization occurs inside the provider adapter after extension-visible message handling, so an extension cannot repair the final role sequence safely.

### Expected merge conflict zones

- LOW: `api/anthropic-messages.ts` around `convertMessages()` user and tool-result serialization.

## 2026-08-25 - Harden bounded retry jitter and provider abort metadata

### What changed

- `packages/ai/src/providers/faux.ts`: preserves `abortSource` in faux assistant messages.
- `packages/ai/src/types.ts`: adds optional provider abort provenance to assistant messages.
- `packages/ai/src/utils/retry.ts`: adds injectable Codex-style +/-10% jitter to bounded retry delays; provider hints remain lower bounds.

### Why

- Retry watchdog ownership and deterministic jitter must survive shared AI message and retry utility boundaries. Jitter prevents synchronized retries without shortening provider-directed waits.

### Why an extension could not handle it

- These browser-safe shared types and utilities execute below extension-visible provider/session boundaries.

### Expected merge conflict zones

- LOW: `packages/ai/src/providers/faux.ts`, `packages/ai/src/types.ts`, and `packages/ai/src/utils/retry.ts`.
- Pin a Cursor Composer operating prefix as its own leading system blob so Composer models arrive with this client's native tool vocabulary and completion rules instead of the Cursor-harness habits they were trained on.
- Match the official Cursor CLI's stream recovery: every inbound frame, including heartbeats and checkpoints, refreshes the 30s health timer; pre-`turnEnded` stalls and transport deaths retry with bounded backoff, and checkpointed attempts resume with the original pinned model request.
- Treat Cursor `turnEnded` as definitive completion after a bounded exec-dispatch drain.
- Skip ANTML invoke recovery when `model.api === "cursor-agent"` so native Cursor tool starts are not rejected as invalid event order.
- Keep usable Cursor task tool arguments when the complete frame parses as empty.
- Remint a Cursor conversation wire id after the 3-rotation skip instead of blocking the whole session.
- Persist Cursor conversation-id rotation under the agent dir (`CODING_AGENT_DIR` / `~/.senpi/agent`), not `$HOME/cursor-conversation-ids.json`.
- Surface the first 0-token `resource_exhausted` of a `stream()` call so session-layer compaction runs before rotation.

## 2026-08-23 - Provider-declared retry policy profiles

### What changed

- `packages/ai/src/utils/retry-profile/` (new tree): pure retry-profile value types (`types.ts`), backoff calculator (`backoff.ts`), failure normalizer (`failure.ts`), classifiers (`classifiers.ts`), delay planner (`planner.ts`), and shipped profile constants (`profiles.ts`). Two stages per profile (`providerRequest`, `turn`), each carrying enabled/maxRetries/backoff(exponential with factor, per-attempt cap, jitter mode)/serverHint(override with ceiling or tiered)/classify.
- `packages/ai/src/models.ts`: added optional `retryPolicy?: RetryPolicyProfile` to `Provider` and `CreateProviderOptions`, forwarded through `createProvider`. Omitting it means the shipped senpi-default profile applies.
- `packages/ai/src/providers/kimi-coding.ts`: declares `KIMI_CODE_RETRY_PROFILE` (10 total attempts, 500ms base, x2 factor, 32s per-attempt cap, +0-25% additive jitter, uncapped server Retry-After, status-whitelist classifier) because kimi-code's managed base (api.kimi.com/coding/v1) and wire protocol (anthropic) match this provider's target exactly.
- `packages/ai/src/api/anthropic-messages.ts`: the catch boundary emits exactly one `provider_retry_failure` diagnostic via `normalizeAnthropicRetryFailure` before the raw error is reduced to a string, carrying a whitelist of facts (kind, statusCode, providerCodes, retryAfterMs, shouldRetry). `output.errorMessage` remains character-identical including the existing `(retry-after-ms: N)` marker.
- `packages/ai/src/utils/diagnostics.ts`: the `provider_retry_failure` diagnostic type sits alongside existing diagnostics, never retaining a `Headers` object or authorization value.
- `packages/ai/src/utils/retry.ts`: `isRetryableErrorMessage` delegates to the new tri-state `classifyErrorMessage` (non-retryable / retryable / unknown). Verdicts are unchanged for every message the regexes match; "unknown" lets profile classifiers consult structured status facts only when the regexes say nothing, with non-retryable still outranking retryable.
- `packages/ai/src/utils/retry-profile/profiles.ts` (phase 2 defaults): the senpi-default turn backoff gained an 8s per-attempt cap and +0..25% additive jitter for locally computed exponentials; provider-derived hints stay exact. The kimi-code profile keeps its documented +0..25% additive jitter on both stages.

### Why

- senpi's `kimi-coding` provider talks to the same upstream service as the kimi-code CLI, so its own retry policy (10 attempts, shorter first waits, uncapped server hints) applies verbatim. Every other provider keeps senpi's existing default behavior byte-identical because the senpi-default profile delegates to the same functions that already drive it.

### Why an extension could not handle it

- The retry decision lives inside this package's streaming adapters and the failure-catch boundary, before any extension hook observes the error. The profile must be resolved at the provider level to affect classification, delay, and fallback routing together.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/models.ts` Provider/CreateProviderOptions field lists and the `createProvider` forwarding block.
- MEDIUM: `packages/ai/src/api/anthropic-messages.ts` catch boundary (diagnostic emission before errorMessage assignment).
- LOW: `packages/ai/src/utils/diagnostics.ts` diagnostic union (append-only).
- LOW: `packages/ai/src/utils/retry-profile/` (new tree, no upstream owner).

## 2026-08-23 - Browser-safe credential pool slot algebra

### What changed

- `packages/ai/src/auth/pool/slots.ts` (new): pure slot algebra over the stored `Credential` - `listSlots`, `findSlot`, `upsertSlot`, `removeSlot`, `pinSlot`, `assertValidSlotName`, plus `CredentialSlot` / `PooledCredential` types. A credential with no `accounts` array is read as a one-slot pool named `default` derived from its flat fields without any write-back; `upsertSlot` replaces or appends one slot while every sibling, the pin, and the flat top-level credential survive untouched. Exported as the new subpath `@earendil-works/pi-ai/auth/pool/slots`.
- `packages/ai/package.json`: added the `./auth/pool/slots` export mapping.
- `packages/ai/src/models.ts`: `login()` now appends the fresh credential to a pool as a generated `login-N` slot instead of replacing the provider entry (flat/absent entries keep today's whole-write shape); `logout()` accepts `slotId` to remove exactly one slot (no-slot keeps remove-everything); `resolveRefreshCredential()` merges the rotated token back via `mergeRefreshed` so sibling slots and the pin survive a refresh.
- `packages/ai/src/auth/resolve.ts`: the request-path OAuth refresh applies the same `mergeRefreshed` before persisting.

### Why

- Multi-account credential pools need one shared, provider-neutral definition of slot shape and slot-preserving mutation. The module is pure data transformation with zero I/O so the auth root stays browser-safe, and consumers (coding-agent storage, later affinity/failover) import it rather than redefining it.

### Why an extension could not handle it

- The slot shape extends the stored `Credential` contract defined in this package's `src/auth/types.ts`; extensions cannot author new credential-envelope types or their canonical mutation semantics.

### Expected merge conflict zones

- LOW: new file with no upstream counterpart; the `package.json` export insertion sits beside `./oauth`.

## 2026-08-20 - Google FinishReason exhaustiveness after the @google/genai 2.18.0 bump

### What changed

- `packages/ai/src/api/google-shared.ts`: `mapStopReason` handles the new `FinishReason.TOO_MANY_TOOL_CALLS` member alongside `UNEXPECTED_TOOL_CALL`, mapping it to the `"error"` stop reason.

### Why

- `@google/genai` 2.18.0 adds that enum member, and the switch closes with a `const _exhaustive: never = reason` guard, so `tsc --noEmit` failed until the new case was handled. Grouping it with the other tool-calling aborts keeps the existing semantics: a run that was stopped by the provider rather than completing is surfaced as an error.

### Why an extension could not handle it

- The mapping runs inside this package's Google streaming adapter, on the provider response path that produces the stop reason an extension would only observe after the fact.

### Expected merge conflict zones

- LOW: the `mapStopReason` case list, which grows only when the upstream SDK adds finish reasons.

## 2026-08-20 - Cursor 0-token RE overflow without estimate gate

### What changed

- `packages/ai/src/utils/overflow.ts`: 0-token Cursor `resource_exhausted` is overflow even when the local estimate is 0; same-model remint helpers skip provider fallback; Cursor overflow compaction settings force `keepRecentTokens: 0` and disable restoration.

### Why

- The 50k estimate gate missed sessions whose last billed usage was zeroed after an earlier compact, so Cursor still rejected the payload while senpi treated it as a 429 and jumped providers.

### Why an extension could not handle it

- Overflow classification and retry fallback run in core before extension hooks.

### Expected merge conflict zones

- `packages/ai/src/utils/overflow.ts` after `getOverflowPatterns()`.

# AI Source Changes

## 2026-08-22 - Cursor heartbeat liveness and checkpoint resume retries

### What changed

- `packages/ai/src/api/cursor-agent.ts`: uses one 30s deadline since the last inbound frame of any kind, waits for local exec dispatches before retrying pre-completion stalls or transport termination, and rebuilds checkpointed attempts as `resumeAction` requests without re-resolving the selected model.
- `packages/ai/src/api/cursor-agent/stream-retry.ts` (new): contains the retry classification, 10-retry default policy, and official-style exponential backoff capped at 60s plus 0-20% jitter. Deterministic delay and budget options support transport harness tests.

### Why

- Cursor heartbeats and conversation checkpoints prove the server stream is alive, especially while a local exec handler is running. Killing heartbeat-only streams after 90s interrupted valid long-running tools. The official CLI instead retries a stream only after 30s with no inbound frame at all, resuming from the latest checkpoint when available.

### Why an extension could not handle it

- HTTP/2 termination, checkpoint caching, request action selection, and exec-dispatch draining all happen inside the native provider below extension-visible events.

### Expected merge conflict zones

- HIGH: `packages/ai/src/api/cursor-agent.ts` `stream()` HTTP/2 lifecycle and retry loop.
- LOW: `packages/ai/src/api/cursor-agent/types.ts` test-tuning options.

## 2026-08-21 - Cursor turn completion and stream health bounds

### What changed

- `packages/ai/src/api/cursor-agent.ts`: treats a decoded `turnEnded` frame as definitive application completion, drains tracked exec dispatches for at most `CURSOR_TURN_END_DRAIN_TIMEOUT_MS` (5000ms), then closes the client HTTP/2 stream instead of waiting for the server. Before `turnEnded`, `CURSOR_STREAM_HEALTH_FAIL_THRESHOLD_MS` (30000ms) bounds complete inbound silence and `CURSOR_STREAM_HEALTH_HEARTBEAT_ONLY_THRESHOLD_MS` (90000ms) bounds streams carrying only heartbeats or conversation checkpoints.

### Why

- Cursor can leave the HTTP/2 response open after all assistant content, exec results, usage, and `turnEnded` have arrived. The adapter previously waited exclusively for transport end, leaving the user-facing turn frozen until the generic 300000ms agent idle timeout. A server that stalls before `turnEnded` had the same five-minute escape path despite the official Cursor CLI bounding transport silence much sooner.

### Why an extension could not handle it

- Frame decoding, HTTP/2 stream ownership, exec-dispatch tracking, and the conversation-rotation retry loop all live inside the Cursor provider adapter below extension-visible events. Only this transport layer can distinguish heartbeat/checkpoint liveness from meaningful frames and close the active request after the authoritative completion signal.

### Expected merge conflict zones

- HIGH: `packages/ai/src/api/cursor-agent.ts` `stream()` HTTP/2 lifecycle, frame decode loop, and final exec drain; upstream and fork Cursor protocol changes commonly touch the same block.

## 2026-08-20 - Cursor conversation rotation composes with compact-before-rotate

### What changed

- `packages/ai/src/api/cursor-conversation-rotation.ts` (new): persists the base-id to wire-id mapping under the agent dir (`CODING_AGENT_DIR` / `~/.senpi/agent`, overridable with `CURSOR_CONVERSATION_ID_STORE`), caps rotation at `MAX_CURSOR_CONVERSATION_ROTATIONS` (3), and remints a fresh wire id after the skip so a session is never permanently blocked.
- `packages/ai/src/api/cursor-agent.ts` `stream()`: the FIRST 0-token `resource_exhausted` of a `stream()` call surfaces as an error with no rotation, so the session layer gets first refusal and can compact. Rotation, cache/blob migration, and same-stream retry apply only to attempts after the first within one `stream()` call. Once the base conversation has burned its 3 rotations, `shouldSkip()` surfaces `CURSOR_CONVERSATION_POISONED_MESSAGE` instead of rotating again.

### Why

- Rotating on the first failure swallowed the error inside `stream()`, so the compact-before-rotate policy added by #1015 (which fires in `agent-session` on a SURFACED 0-token RE via `isCursorPayloadResourceExhausted`) never ran. A large-payload rejection then burned all three rotations replaying the same oversized payload and still failed. Surfacing attempt 1 lets compaction shrink the payload first; rotation remains the fallback for a genuinely poisoned conversation id, which compaction cannot fix.

### Why an extension could not handle it

- The rotation map, the persisted wire id, and the h2 retry loop live inside `cursor-agent` `stream()`, below every extension hook; the retry must reuse the same in-flight event stream so `start` is emitted once.

### Expected merge conflict zones

- `packages/ai/src/api/cursor-agent.ts` `stream()` retry loop and its `catch` block.
- `packages/ai/src/api/cursor-conversation-rotation.ts` (whole file).

## 2026-08-20 - Cursor explicit levels prefer catalog suffix variant ids

### What changed

- `packages/ai/src/cursor/selection-descriptor.ts`: `resolveCursorSelectionDescriptor` now resolves an
  explicit thinking level to the catalog-guaranteed legacy suffix alias (`kimi-k3-high`,
  `claude-fable-5-thinking-low`, `gpt-5.3-codex-xhigh`) whenever one exists, via a new
  `suffixAliasId` that tries the level's wire value then the level token, with thinking-infixed
  candidates for thinking Claude identities. Bare base id + ordered parameters remains only as the
  fallback for levels without any alias; `legacySuffixId` is subsumed.

### Why

- Cursor's Run RPC now rejects bare capability ids with Connect `not_found` for every family
  (issue #1008; live probes 2026-08-20 in
  `local-ignore/qa-evidence/20260820-cursor-bare-id-notfound/`: bare `kimi-k3`+parameters and bare
  `claude-fable-5`+parameters both `not_found`, while `kimi-k3-high` and
  `claude-fable-5-thinking-low` complete), so every explicit level rendered as base+parameters died
  at turn start.

### Why an extension could not handle it

- The selection descriptor is core provider data consumed by both Cursor transports (protobuf
  `RequestedModel` and the CLI model string); no extension hook sits between them.

### Expected merge conflict zones

- `selection-descriptor.ts` resolver body and helper block (fork-only file; upstream has no cursor
  provider).

## 2026-08-19 - Ignore Cursor billed cacheRead that dwarfs usedTokens

### What changed

- `applyCheckpointTokenDetails` records `UsageState.liveUsedTokens`.
- `applyBilledTurnEndedUsage` ignores `cache_read_tokens` when it is more than 3× that live window and keeps `totalTokens` at `usedTokens`.

### Why

- Session 01a01879 jumped 148k → 4.09M because field 3 was dashboard-cumulative cache read, not conversation size. `max(usage, estimate)` then forced a useless compact and a 0-token `resource_exhausted`.

### Conflict zone

- `packages/ai/src/api/cursor-agent.ts` `applyBilledTurnEndedUsage` / `UsageState`.

## 2026-08-19 - OpenAI-family adapters re-diverge from the 59a71b23 pin

### What changed

- `packages/ai/src/api/openai-responses.ts`: keeps the fork's Responses request surface on top of the new
  pin — `serviceTier` forwarded as `service_tier` with `-fast`/Priority-tier cost correction
  (`getServiceTierCostMultiplier` / `applyServiceTierPricing`, flex 0.5x, priority 2x and 2.5x for
  `gpt-5.5`), the `max` ladder resolved through `supportsMax` / `supportsXhigh` / `clampMaxForOpenAI`
  instead of a flat clamp, the `web_search_preview` compat guard that strips the unsupported
  `web_search_call.action.sources` include, per-session WebSocket connection reuse with idle expiry, the
  three-way `sessionAffinityFormat` split (`openai` / `openai-nosession` / `openrouter`),
  `extraBody` merging, and null-aware `thinkingLevelMap` resolution where a mapped `null` means
  "reasoning unavailable" rather than "reasoning off".
- `packages/ai/src/api/openai-completions.ts`: compat resolution now lives in the shared browser-safe
  `utils/prompt-cache-ttl.ts` (`getOpenAICompletionsCompat`) and is re-exported from here, replacing the
  pin's file-local `detectCompat`/`getCompat` pair; the params type is a real
  `OpenAICompletionsRequestParams` (fork fields `tool_stream`, `chat_template_kwargs`,
  `reasoning_effort` typed instead of `as any` casts); Kimi K3 detection supplies
  `KIMI_K3_THINKING_LEVEL_MAP`; usage parsing reads cache-read tokens from
  `prompt_tokens_details.cached_tokens`, then DeepSeek's `prompt_cache_hit_tokens`, then Kimi's
  documented **top-level** `usage.cached_tokens` on the final usage chunk, and never subtracts writes;
  per-choice usage is typed via `ChatCompletionChoiceWithUsage`; `applyExtraBody` merges caller fields
  under `OPENAI_COMPLETIONS_RESERVED_BODY_KEYS`. The `thinkingTokenBudgetField` /
  `supportsThinkingTokenBudget` budget field upstream generalized is retained through the shared
  resolver rather than the pin's inline compat table.
- `packages/ai/src/api/openai-codex-responses.ts`: the fork splits WebSocket fallback/debug state into
  `openai-codex-responses/fallback-state.ts` and re-exports `ChatGptSubscriptionWebSocketDebugStats` from there;
  ChatGPT account identity resolves through `extractChatGptSubscriptionAccountId` with an `accountId ?? apiKey`
  affinity fallback, cache-affinity headers come from `applyChatGptSubscriptionCacheAffinityHeaders`, the same
  `supportsMax`/`supportsXhigh`/`clampMaxForOpenAI` ladder applies, and `extraBody` merges under
  `OPENAI_RESPONSES_RESERVED_BODY_KEYS`.
- `packages/ai/src/api/azure-openai-responses.ts`: accepts upstream's `tool_choice` forwarding while
  keeping the fork's additions — the `supportsMax` effort ladder in `streamSimple`, `prompt_cache_key`
  suppressed when the effective `cacheRetention` (option or `model.cacheRetention`) is `"none"`, the
  null-aware `thinkingLevelMap` resolution with `reasoningRequested` / `reasoningUnavailable`, and
  `reasoningSummary: null` omitting the summary field entirely.
- `packages/ai/src/api/simple-options.ts`: fork-owned shared option layer — `applyExtraBody` plus the
  six per-provider reserved-key sets (OpenAI Completions/Responses, Google, Anthropic, Mistral,
  Bedrock), `clampMaxForOpenAI`, `cacheRetention` defaulting to `model.cacheRetention`,
  `abortServerSideFallback` and `extraBody` carried onto base options, integer/finite clamping in
  `clampMaxTokensToContext`, and `adjustMaxTokensForThinking` treating an unresolvable level as
  "no thinking" (budget 0) instead of producing a NaN budget.

### Why

- These are the fork's paid-tier accounting, provider-affinity, and wire-compat contracts. Upstream
  `59a71b235d` has no service-tier pricing, no `-fast` Priority variants, no Kimi top-level cached-token
  form, no `extraBody` seam, and no shared compat resolver, so each re-diverges on merge. The Kimi read
  in particular is a correctness fix: Kimi reports cache reads only at `usage.cached_tokens`, so without
  the top-level branch every Kimi turn bills cache reads as fresh input.

### Why an extension could not handle it

- Request-body construction, usage/cost parsing, WebSocket session reuse, and affinity headers all run
  inside the provider adapters, below every extension-visible surface. An extension cannot rewrite a
  streamed usage chunk into corrected cost, nor inject a header on a socket it never sees.

### Expected merge conflict zones

- HIGH: `openai-responses.ts` `buildParams` / request construction and the usage-and-cost block;
  `openai-completions.ts` compat import and params typing (upstream owns the same `detectCompat` hunk —
  keep the shared resolver when resolving).
- MEDIUM: `openai-codex-responses.ts` fallback-state extraction and affinity header application;
  `azure-openai-responses.ts` `buildParams` reasoning block.
- LOW: `simple-options.ts` reserved-key sets and clamp helpers.

## 2026-08-19 - Google, Anthropic, Bedrock, and Mistral adapters re-diverge from the 59a71b23 pin

### What changed

- `packages/ai/src/api/google-shared.ts`: tool-call ids normalize through the shared collision-safe
  `utils/tool-call-id.ts` instead of the pin's local `replace(...).slice(0, 64)` truncation;
  `convertMessages` takes `preserveThinking` so a non-reasoning turn drops thinking state;
  `sanitizeForOpenApi` recurses into arrays; the position-aware `stripOptional` removes the non-standard
  `optional` keyword from schema-keyword position only, preserving it as a property name under
  `properties`/`patternProperties`/`$defs`/`definitions` and never traversing the value keywords
  `const`/`default`/`examples`/`enum`; `toProviderNativeContent` maps unrecognized Gemini parts
  (`executableCode`, `codeExecutionResult`, or the dominant part key) onto the fork's
  `providerNative` content block.
- `packages/ai/src/api/google-generative-ai.ts` and `packages/ai/src/api/google-vertex.ts`: both take
  upstream's thinking-level direction but keep the fork's thinking-off routing — a runtime `"off"`
  handed through the `ThinkingLevel`-typed `reasoning` option, and a post-clamp `"off"`, both take the
  disabled wire form rather than an enabled one, which a post-clamp check alone cannot see because
  Gemini 3 maps `off` to `null`. Both also emit `providerNative` blocks for unhandled parts and for
  once-per-response `groundingMetadata` / `urlContextMetadata`, merge `extraBody` into the inner
  `config` under `GOOGLE_RESERVED_BODY_KEYS`, and pass `preserveThinking` into `convertMessages`.
  `google-generative-ai.ts` additionally replaces the pin's `as any` thinking-level casts with a typed
  `THINKING_LEVEL_MAP` onto the SDK's `ThinkingLevel` enum; `google-vertex.ts` drops the
  `Model<"google-generative-ai">` casts in favor of `Pick<Model<Api>, "id">` predicates and takes plain
  header records so `providerHeadersToRecord` is applied once at the client boundary.
- `packages/ai/src/api/anthropic-messages.ts`: keeps the fork's adaptive-thinking surface — the
  `ADAPTIVE_THINKING_MODEL_MARKERS` and `NATIVE_XHIGH_EFFORT_MODEL_MARKERS` families, the
  `forceAdaptiveThinking` compat override, `sanitizeAdaptiveThinkingPayload` /
  `sanitizeAdaptiveThinkingHeaders` (which rewrite `thinking` to `{type: "adaptive"}` with an
  `output_config.effort`, and strip the interleaved-thinking beta an adaptive family rejects), the
  computer-use beta stripper for families that reject it, effort pinned low on a degraded/disabled turn,
  the shared `getAnthropicCompat` / `isAnthropicApiBaseUrl` prompt-cache-TTL resolver behind the `1h`
  retention decision, and server-side-fallback receipt handling.
- `packages/ai/src/api/bedrock-converse-stream.ts`: keeps `cacheRetention` falling back to
  `model.cacheRetention`, `preserveThinking` on message conversion, shared `normalizeToolCallId`,
  `applyExtraBody` with `BEDROCK_RESERVED_BODY_KEYS`, the Mythos 5 adaptive-family marker, and the
  custom-header build-step middleware — now guarded so no middleware is registered for an empty header
  map and narrowed through a `hasHeaders` type guard rather than an inline cast. Upstream's response
  smithy-header deserialize middleware is accepted in the same inline-registration form.
- `packages/ai/src/api/mistral-conversations.ts`: keeps `preserveThinking` (derived from
  `promptMode === "reasoning"` or an explicit `reasoningEffort`) on message transformation and
  `applyExtraBody` with `MISTRAL_RESERVED_BODY_KEYS`, plus the block-type narrowing in `toChatMessages`
  that skips non-`toolCall` blocks instead of coercing them.

### Why

- Every item here is a wire contract the fork resolved against live provider behavior: truncating tool
  ids can collapse two distinct calls into one id, replaying thinking state into a non-reasoning turn is
  rejected, an adaptive Anthropic family 400s on `thinking: {type: "disabled"}` and on the interleaved
  beta, Gemini 3 cannot express thinking-off through a budget, and `optional` is not a JSON Schema
  keyword Gemini accepts. Upstream's new thinking-level maps do not encode any of these, so the fork's
  routing must survive the merge.

### Why an extension could not handle it

- Message conversion, tool-schema emission, beta-header negotiation, and Smithy middleware registration
  happen inside the adapters while constructing the outbound request; there is no hook between the
  adapter and the provider SDK where an extension could observe or repair them.

### Expected merge conflict zones

- HIGH: `anthropic-messages.ts` `buildParams` and the beta-header/payload sanitizers.
- MEDIUM: `google-shared.ts` `convertMessages` and `convertTools`; the `streamSimple` thinking branches
  in `google-generative-ai.ts` and `google-vertex.ts`; `bedrock-converse-stream.ts` middleware
  registration and command-input construction.
- LOW: `mistral-conversations.ts` payload build and stream-block narrowing.

## 2026-08-19 - Public type and export surface re-diverges from the 59a71b23 pin

### What changed

- `packages/ai/src/types.ts`: carries the fork's request and content contracts — the compaction
  affinity/request-identity split (`affinitySessionId`, the stable originating-session identity that
  survives auxiliary calls which replace `sessionId`, plus `streamKind: "main" | "auxiliary"` where an
  absent value must be read as auxiliary), `abortServerSideFallback`, `extraBody`, the three-argument
  `onPayload` with `ProviderRequestMetadata` (effective model plus fully transformed headers),
  `ThinkingSelection` provenance, `thinkingBudgets.max`, thinking-block `startedAt`/`endedAt`, the
  `incomplete`/`errorMessage` tool-call carriers used by text tool-call recovery, `isVideoMimeType` and
  video payloads riding `ImageContent`, the `providerNative` block, the local `OpenAIResponsesCompat`
  extension adding `supportsAdditionalTools`, and the fork-only `cursor-agent` API plus
  `alibaba-token-plan` / `cursor` / `ollama` / `opengateway` provider ids and the `openai-images` images
  API.
- `packages/ai/src/index.ts`: publishes the fork's core export surface that upstream has no counterpart
  for — the cursor capability/grouping/selection API and cursor pi-args helpers, `getApiProvider`,
  `convertResponsesMessages`, `warmPromptCache`, `sanitizeAnthropicToolPairs`, the tool-call middleware
  entry points (`wrapStreamWithToolCallMiddleware`, `shouldRecoverTextToolCalls`,
  `hasKimiTextToolCallRecovery`, the XTML recovery stream parser), context provenance,
  `env-api-keys`, `auth/headers`, prompt-cache TTL constants, server-fallback receipts, stop details,
  tool-pair repair, visible text, block symbols (`kCursorExecResolved`), wire identity
  (`getWireIdentity` / `setWireIdentity`, the senpi branding seam), and `extractChatGptSubscriptionAccountId`.

### Why

- These two files are the seam through which `packages/agent` and `packages/coding-agent` reach every
  fork behavior recorded elsewhere in this tracker. If the merge took the pin's version, the affinity
  split, provenance-bearing thinking selection, provider-native blocks, and the entire cursor and
  tool-call-middleware surface would stop being reachable and the dependent packages would not compile.

### Why an extension could not handle it

- An extension consumes these types and exports; it cannot add a field to a core request interface or
  publish a package entry point that other workspace packages import.

### Expected merge conflict zones

- HIGH: `index.ts` export ordering — upstream appends to the same alphabetized lists, so nearly every
  sync conflicts here; resolve by keeping both sides' exports.
- MEDIUM: `types.ts` `ProviderRequestOptions` / `StreamOptions` / `SimpleStreamOptions` members and the
  `KnownProvider` / `KnownApi` unions.

## 2026-08-18 - Cursor context windows tracked to the models.dev first-party SSOT

### What changed

- `packages/ai/src/cursor/model-capabilities.ts`: window values now derive from the models.dev
  first-party catalog capped by the `context` options Cursor actually offers each family, and the
  capability gains `requestContext` — the context token matching the advertised window.
- `packages/ai/src/cursor/selection-descriptor.ts`: the wire mapper emits
  `requestContext ?? defaultContext`, so a family advertising 1M also asks Cursor for `context=1m`.

### Why

- Claude families were encoded at 300000, copied from the cursor-agent CLI listing's stale
  "(300K context)" display labels; models.dev, Cursor's `1m` context option, and the models' own "1M"
  display names all agree they are 1000000. Advertising a window larger than the context the request
  asks for would let compaction overrun what Cursor was told to allocate, so the two values are one
  contract and are now verified together.

### Why an extension could not handle it

- The capability table and the protobuf/CLI wire mapper are core provider data consumed by both
  Cursor transports; no extension hook sits between them.

### Expected merge conflict zones

- `model-capabilities.ts` family table and helper signatures, `selection-descriptor.ts` parameter switch.

## 2026-08-18 - Sanitize JSON-Schema composition keywords from advertised Cursor tool schemas

### What changed

- `packages/ai/src/api/cursor-agent.ts`: new exported `sanitizeCursorToolSchema` helper plus
  `CURSOR_UNSUPPORTED_SCHEMA_KEYS`; `buildMcpToolDefinitions` now recursively strips `oneOf`,
  `anyOf`, and `allOf` from every advertised tool's inputSchema before proto encoding. `not` and
  all other keywords pass through untouched. Returns new structures (input never mutated).

### Why

- An advertised tool whose inputSchema carries a composition keyword makes Cursor's gateway
  reject the ENTIRE request upstream with a wrapped provider 400 (`ERROR_PROVIDER_ERROR`, zero
  tokens, `resource_exhausted` end-stream) — proven by live A/B on 2026-08-18 with a minimal
  single-tool `oneOf`/`anyOf`/`allOf` repro against `claude-fable-5-thinking-xhigh`. External MCP
  servers ship such schemas routinely (ast-grep's `scan` uses a top-level `oneOf`), so every
  session registering one failed on the cursor provider from turn 1.

### Why an extension could not handle it

- `buildMcpToolDefinitions` runs inside the cursor-agent Run-request construction path; the
  advertised schema bytes are serialized before any extension-visible surface exists.

### Expected merge-conflict zones

- `packages/ai/src/api/cursor-agent.ts` (`buildMcpToolDefinitions` / schema helpers) — same zone
  as the reasoning-levels entry; test file
  `packages/ai/test/cursor-tool-schema-sanitize.test.ts` is new.

## 2026-08-18 - Cursor reasoning levels end to end

### What changed

- `src/cursor/model-capabilities.ts`, `src/cursor/cursor-variant-aliases.json`: committed static capability table
  (windows, parameter orders, exact level encodings incl. GPT 5.5/Codex 5.3 `extra-high` and off=`none` families)
  plus the 204-id alias index, both derived from the live aiserver.v1 AvailableModels capture of 2026-08-18.
- `src/cursor/catalog-grouping.ts`: lossless variant parser + grouping (Claude `base`/`base-thinking` boolean axis,
  fast variants retained raw) with total seven-key thinkingLevelMaps; golden 204->113/32 pinned by fixture test.
- `src/cursor/selection-descriptor.ts`: transport-neutral selection resolver (parameters vs suffix-id encodings)
  shared by the native protobuf lane and the `cursor-cli-oauth` extension.
- `src/cursor/store-migration.ts`: idempotent stored-catalog regrouping.
- `providers/cursor.ts`: discovery now publishes grouped identities with `compat.cursorReasoning` and correct
  windows; `api/cursor-agent.ts` renders `options.thinkingSelection` into `RequestedModel.parameters`; absent
  selections keep the representative-variant request shape byte-exactly.
- `packages/ai/src/index.ts`: re-exports the shared cursor capability, grouping, and selection API.
- `packages/ai/src/models.ts`: new `restoreModels` provider hook (try/catch — stored catalog survives a throwing transform).
- `packages/ai/src/types.ts` / `packages/ai/src/model.ts`: `ThinkingSelection` type + `CursorAgentCompat.cursorReasoning` capability gate.

### Why

- The Cursor catalog exposed 204 expanded variant ids with reasoning disabled, so senpi thinking
  levels could not reach the wire and context windows came from stale name heuristics.

### Why an extension couldn't do it

- Provider discovery normalization, protobuf Run-request construction, agent-loop option propagation, and the
  models-store restore path are core runtime seams an extension cannot reach.

### Expected merge-conflict zones

- `api/cursor-agent.ts` (Run-request builder + streamSimple), `providers/cursor.ts`, `models.ts` restore path,
  `types.ts` SimpleStreamOptions, `packages/agent/src/agent-loop.ts` prepareNextTurn merge.

## 2026-08-17 - Cursor exec result closure + per-exec heartbeats

### What changed and why

- `api/cursor-agent.ts`: recognised exec frames now run inside one lifecycle boundary. While a handler is pending,
  the client emits `ExecClientControlMessage.heartbeat` with the numeric `ExecServerMessage.id` after 3 seconds and
  schedules each later heartbeat only after the prior HTTP/2 write completes. When a normal typed result sequence
  finishes — including typed rejection/error results and streamed shell results — the client clears the heartbeat
  and emits exactly one `ExecClientControlMessage.streamClose` for the same numeric id.
- Unknown/unset frame fallback remains `ExecClientThrow` followed by `streamClose`; `ExecClientThrow` itself is now
  a throw-only primitive so the recognised lifecycle and unknown fallback each own exactly one close.
- Direct capture of `cursor-agent` `2026.08.11-e8db854` established the contract: a normal `readResult` is followed
  by `streamClose`, and the bundled dispatcher uses write-completion-chained 3-second exec heartbeats. Senpi's prior
  port inherited oh-my-pi's result-only behaviour for most exec families, leaving the server-side exec pending until
  the Run stream could end before `turnEnded`.
- `test/cursor-agent.test.ts` registers focused lifecycle cases split between a small behavior module and reusable
  h2 harness. They pin typed success/rejection closure, pending-handler heartbeat write serialization and cleanup,
  unexpected-dispatch throw-close recovery, unknown fallback, and exactly-once shell-stream closure.

### Why this cannot be expressed as an extension

- Heartbeats and close controls must be written on the same provider-owned HTTP/2 Connect stream while the server is
  blocked on a local tool result. Extensions can observe the outer agent turn but cannot own provider-internal exec
  control frames or their write-completion timing.

### Expected merge conflict zones

- MEDIUM: `api/cursor-agent.ts` around `handleExecServerMessage`, the exec heartbeat scheduler, and exec control
  writers. Reapply the single lifecycle owner if upstream changes individual result branches.
- LOW: `test/cursor-agent-exec-lifecycle-{cases,harness}.ts` and the permanent senpi-qa scenario are fork-only
  coverage registered by `test/cursor-agent.test.ts`.

> Audit backfill (2026-08-17): the entries between this note and the pre-existing `2026-08-16` Cursor
> entries were recorded during the repository-wide changes.md audit of divergences from the upstream pin
> (v0.84.2, `914cf1472e`); each is dated by its underlying work and gives its audited production paths a
> canonical four-section record.

## Upstream v0.84.2 sync on the pinned OpenAI SDK (PR #892) (2026-08-16)

### What changed

- `packages/ai/src/api/openai-responses-shared.ts`: the PR #892 upstream merge brought deferred-tools
  support that constructs an `additional_tools` input item. That member exists only in openai@6.40.0's
  `ResponseInputItem` union while the fork deliberately pins openai@6.26.0, so the merged source did not
  typecheck; the local `AdditionalToolsInputItem` type extends the pinned union instead of bumping the
  dependency, leaving the wire payload unchanged.
- `packages/ai/src/api/openai-responses.ts`: the merge kept the fork's Responses additions (service-tier
  pricing for `-fast` variants, native image-generation item reconciliation, the `web_search_preview`
  compat guard, `supportsMax`-aware effort handling) while accepting upstream's deferred-tools plumbing.
- Accepted upstream v0.84.2 transports that arrived with the same sync: Kimi Coding requests send the
  shared `pi (<platform>)` User-Agent (`utils/pi-user-agent.ts`, unchanged from the pin), Google length
  stops are preserved when tool calls are present (`packages/ai/src/api/google-generative-ai.ts`,
  `packages/ai/src/api/google-shared.ts`, `packages/ai/src/api/google-vertex.ts`), the Mistral
  Conversations HTTP transport rework landed in `packages/ai/src/api/mistral-conversations.ts`, and
  delayed GitHub Copilot device-code polling was accepted in the OAuth flow.
- `packages/ai/src/api/constrained-sampling.ts`: `constrainedSampling: false` is honored as an explicit
  opt-out, distinct from an absent value, in both the strict-JSON and grammar resolvers.
- The Google files' remaining pin divergence is the fork's own work recorded in the 2026-07-25/07-26
  entries (thinking-off routing, shared collision-safe tool-call-id normalization); Mistral keeps the
  fork's `preserveThinking` and `applyExtraBody` additions.

### Why

- The fork tracks upstream provider transports to stay mergeable but cannot take upstream's floating
  `openai` SDK pin: the pinned SDK is a deliberate dependency decision, so upstream type-level work must
  be repaired locally rather than pulled in through a version bump.

### Why an extension could not handle it

- Wire item types, transport construction, and stop-reason normalization live inside the provider
  adapters, below every extension-visible surface; an extension cannot widen SDK request unions or repair
  streaming transports.

### Expected merge conflict zones

- HIGH: `packages/ai/src/api/openai-responses-shared.ts` message conversion (upstream owns the same
  hunk; keep the local union extension when resolving).
- MEDIUM: `packages/ai/src/api/openai-responses.ts` request construction and the Google adapters' stop
  handling.
- LOW: `packages/ai/src/api/mistral-conversations.ts` and `packages/ai/src/api/constrained-sampling.ts`.

## Bedrock Converse adapter divergence (2026-08-16)

### What changed

- `packages/ai/src/api/bedrock-converse-stream.ts`: the prompt-cache predicates (`supportsPromptCaching`
  and the Bedrock Claude 4.5 one-hour-TTL allowlist) moved into the browser-safe
  `utils/prompt-cache-ttl.ts` and are re-exported here, so the wire request and the TTL estimate share one
  definition; `cacheRetention` falls back to `model.cacheRetention`; message conversion takes
  `preserveThinking` so non-reasoning turns drop thinking state.
- Tool-call ids normalize through the shared collision-safe `normalizeToolCallId`
  (`utils/tool-call-id.ts`), replacing the adapter's local 64-character truncation that could collapse two
  distinct over-long ids into duplicate tool ids.
- `extraBody` pass-through applies `applyExtraBody` with `BEDROCK_RESERVED_BODY_KEYS`; custom headers are
  injected through a typed inline Smithy build-step middleware (reserved `x-amz-*`/`authorization`/`host`
  headers ignored to preserve SigV4 signing, no middleware added when the header map is empty); the
  command input is typed as `ConverseStreamCommandInput`.
- Mythos 5 joins the adaptive-family markers so a thinking-off turn cannot fall through to a budget-based
  request.

### Why

- Bedrock cache points, SigV4-signed headers, and tool-id pairing are wire contracts resolved inside the
  adapter; divergent copies between the adapter, the TTL resolver, and the other Anthropic-compatible
  adapters previously produced wrong TTL estimates and duplicate tool ids.

### Why an extension could not handle it

- AWS SDK request assembly and the Smithy middleware stack are constructed inside `packages/ai` before
  any extension hook can observe or rewrite the signed request.

### Expected merge conflict zones

- MEDIUM: cache-point construction, header middleware, and message conversion in
  `packages/ai/src/api/bedrock-converse-stream.ts`.

## OAuth loader registry, compatibility surface, and auth resolution (2026-08-16)

### What changed

- `packages/ai/src/auth/oauth/load.ts` and `packages/ai/src/bun-oauth.ts`: the `cursor` OAuth flow joined
  the lazy loader registry and the standalone-Bun static bundle (details in the Cursor OAuth entry
  below).
- `packages/ai/src/oauth.ts`: the extension compatibility entry point re-exports `loadAnthropicOAuth`
  and `registerBundledOAuthFlowLoaders` so extension providers can reuse the Anthropic PKCE machinery;
  previously the entry was type-only.
- `packages/ai/src/compat/extension-oauth-types.ts`: legacy extension OAuth declarations gained the
  `OAuthProviderId` alias, an optional `OAuthSelectOption.description`, and readonly select options.
- `packages/ai/src/auth/resolve.ts` and `packages/ai/src/auth/types.ts`: stored OAuth credentials refresh
  before the optional side-effect-free `check` runs, sentinel envelopes with zero usable accounts no
  longer bypass availability, request environment merges transiently for `check()`/`toAuth()` and
  auxiliary replay without persisting request secrets, explicit empty request values mask host values,
  and `ApiKeyAuth.ambientOnly` marks compatibility adapters fallback-only.

### Why

- Availability must not report a provider configured from dead or empty credentials, and auxiliary
  streams (compaction) must keep the same account affinity. The legacy extension OAuth types must keep
  compiling for coding-agent extensions while the real loader registry grows.

### Why an extension could not handle it

- The loader registry, Bun bundle registration, and the stored-credential short-circuit inside
  `resolveProviderAuth` are package-internal seams that run before extension request hooks exist.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/auth/resolve.ts` precedence and derivation branches.
- LOW: loader lists in `packages/ai/src/auth/oauth/load.ts` and `packages/ai/src/bun-oauth.ts`; additive
  fields in `packages/ai/src/auth/types.ts` and
  `packages/ai/src/compat/extension-oauth-types.ts`; the export block in `packages/ai/src/oauth.ts`.

## Shared retry, overflow, and event-stream utilities (2026-08-16)

### What changed

- `packages/ai/src/utils/retry.ts`: the bounded retry loop gained the throw-based `retryTransientCall`
  sibling and the exported string classifier `isRetryableErrorMessage`, stream-stall and timeout
  classifiers, and pattern updates — the gateway "model request was rejected" wording is retryable while
  malformed tool-schema rejections and Anthropic `credits_required` exhaustion are terminal; Cloudflare
  522 and Codex `upstream_unavailable` join the transient set.
- `packages/ai/src/utils/provider-retry.ts`: 429 retry-after hints propagate as structured
  `ProviderRetryDelayError` (canonical markers from `utils/retry-hint.ts`), and the first stream chunk is
  prefetched inside the bounded policy so pre-output failures retry without replaying started streams.
- `packages/ai/src/utils/overflow.ts`: gateway HTTP 413 byte-size rejections ("Request body too large",
  "Request Entity Too Large", `body_too_large`, "Payload Too Large") classify as context overflow so
  shrink-retry recovery runs instead of dead-ending the session.
- `packages/ai/src/utils/event-stream.ts`: the event queue uses a ring-buffer head with compaction, the
  final-result promise rejects on stream failure (with an unhandled-rejection guard), and
  `trackLocalWork`/`hasPendingLocalWork` attribute mid-stream silence to local tool work for idle
  watchdogs.

### Why

- Transient-vs-terminal classification, overflow recovery, and stream lifecycle are the provider-neutral
  boundary every caller keys off; duplicated per-consumer copies diverge and wedge sessions.

### Why an extension could not handle it

- These utilities run below the extension-visible assistant message; extensions consume their verdicts
  through the retry loop and cannot add error classes or repair stream lifecycles from outside.

### Expected merge conflict zones

- MEDIUM: pattern lists and classifier functions in `packages/ai/src/utils/retry.ts`; hint propagation in
  `packages/ai/src/utils/provider-retry.ts`.
- LOW: `packages/ai/src/utils/overflow.ts` pattern list; `packages/ai/src/utils/event-stream.ts` queue
  internals.

## Adapter option normalization: extraBody, reasoning ladders, affinity (2026-08-16)

### What changed

- `packages/ai/src/api/simple-options.ts`: `applyExtraBody()` merges user pass-through fields into
  provider payloads while skipping per-provider reserved-key sets
  (`OPENAI_COMPLETIONS_RESERVED_BODY_KEYS` and the Mistral, Bedrock, and Google inner-`config` sets) so
  users cannot stomp library-managed fields.
- `packages/ai/src/api/openai-completions.ts`: map-less thinking-level ladders for Kimi K3, DeepSeek,
  MiMo, GLM 5.x, and Ollama; Kimi's flat `usage.cached_tokens` parsed after the nested forms;
  OpenRouter-style session affinity (`x-session-id` plus body `session_id`); replayed tool-call ids
  sanitized to the strict OpenAI-compatible shape; Moonshot/final-boundary tool-schema normalization;
  and header-only credential clients without a synthetic bearer key.
- `packages/ai/src/api/azure-openai-responses.ts`: `max` maps through `supportsMax` (clamped to `high`
  otherwise), `thinkingLevelMap` wins for adapter options, and `cacheRetention: "none"` omits
  `prompt_cache_key`.
- `packages/ai/src/api/openai-prompt-cache.ts`: `applyChatGptSubscriptionCacheAffinityHeaders()` applies the
  complete Codex affinity tuple (`session-id`, `thread-id`, `x-client-request-id`) beside the clamped
  `prompt_cache_key`.

### Why

- Option derivation, capability ladders, and affinity headers are decided while each adapter builds its
  wire payload; one shared reserved-key and ladder policy prevents the per-adapter drift that produced
  rejected requests and silently lost capability levels.

### Why an extension could not handle it

- The final request object is assembled inside the adapter after `onPayload`; extensions cannot reserve
  provider-managed fields, remap reasoning levels, or attach transport headers reliably.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/api/simple-options.ts` reserved sets and
  `packages/ai/src/api/openai-completions.ts` request construction.
- LOW: `packages/ai/src/api/azure-openai-responses.ts` payload construction and the header helper in
  `packages/ai/src/api/openai-prompt-cache.ts`.

## Canonical record for images builtin registration (2026-08-11)

### What changed

- `packages/ai/src/providers/images/register-builtins.ts`: registers the `openai-images` ImagesApi as a
  lazy builtin beside `openrouter-images`, generalizes `createLazyLoadErrorImages` over `ImagesApi`, and
  normalizes module-load failures into `AssistantImages` error envelopes. Semantics and coverage live in
  the two OpenAI-images entries below; this entry supplies the canonical four-section record for the
  audited path.

### Why

- Same as the entries below: builtin registration runs at module load inside `packages/ai` and must keep
  the images SDK out of the initial bundle.

### Why an extension could not handle it

- External providers register through the public images registry but cannot supply the lazy
  module-promise boundary that builtin registration owns.

### Expected merge conflict zones

- LOW: additive registration entries in `packages/ai/src/providers/images/register-builtins.ts`.

## Dynamic product wire identity (2026-08-10)

### What changed

- `packages/ai/src/index.ts` exports `getWireIdentity`/`setWireIdentity` from the browser-safe
  `wire-identity.ts` module (default token `senpi`).
- `packages/ai/src/api/openai-codex-responses.ts` builds the Codex `originator` and `User-Agent` from
  the dynamic identity instead of the previously hardcoded `senpi` strings.
- `packages/ai/src/auth/oauth/chatgpt-subscription.ts` derives the OAuth flow's default `originator` from the
  same identity.

### Why

- A distribution repackaging this stack sets its product token once at startup; a standalone install
  keeps the default. One source of truth replaces per-site hardcoded strings that had already diverged
  once (upstream `pi` versus fork `senpi`).

### Why an extension could not handle it

- Header construction and the OAuth originator default happen inside `packages/ai` request builders and
  auth flows, below extension hooks.

### Expected merge conflict zones

- LOW: additive root exports in `packages/ai/src/index.ts`.
- MEDIUM: `packages/ai/src/api/openai-codex-responses.ts` header builders and the originator default in
  `packages/ai/src/auth/oauth/chatgpt-subscription.ts`, where upstream hardcodes `pi`.

## Request-option and content contract: metadata hooks, affinity, native blocks (2026-08-07)

### What changed

- `packages/ai/src/types.ts`: `onPayload` gained the optional `ProviderRequestMetadata` third argument
  (effective model plus fully transformed headers); `ProviderRequestOptions` gained `affinitySessionId`
  (stable session identity preserved across auxiliary calls such as compaction, consumed by the
  claude-sdk-oauth lane for account affinity) and `streamKind` (`main` or `auxiliary`, absent treated as
  auxiliary as the fail-safe); `ProviderNativeContent` surfaces provider-native blocks verbatim on
  assistant content; `OpenAICompletionsCompat.supportsAdditionalTools` gates the deferred
  additional-tools path; and video payloads ride `ImageContent` with `isVideoMimeType()` for models
  declaring the `video` input modality.
- `packages/ai/src/utils/text.ts`: `contentText()` accepts `ProviderNativeContent` blocks and extracts
  their embedded text.

### Why

- Payload hooks needed the post-transform header set to make informed decisions; auxiliary streams were
  re-rolling account affinity; providers emit native blocks (web-search results, grounding metadata)
  that lossy normalization dropped; and the modality and compat facts must be typed once for every
  consumer.

### Why an extension could not handle it

- These are the exported contracts extensions compile against and the content shapes produced inside
  provider streams; standalone `pi-ai` consumers need them before any coding-agent extension runs.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/types.ts` option and content unions (upstream owns adjacent members).
- LOW: `packages/ai/src/utils/text.ts` content union.

## Cross-provider message transform contract (2026-07-20)

### What changed

- `packages/ai/src/api/transform-messages.ts`: tool results pair by source position (the earliest
  still-unconsumed matching result after the declaring assistant, or exactly one synthetic error result),
  video-mime blocks downgrade to placeholders for models without the `video` modality, and
  `TransformMessagesOptions.preserveThinking` (default true) lets non-reasoning turns drop provider
  thinking state.

### Why

- Delayed or duplicated results mis-attached across user turns; unsupported video blocks crossed model
  handoffs to rejecting providers; preserved thinking on thinking-off turns produced invalid requests.

### Why an extension could not handle it

- History normalization runs during provider request serialization, below extension-visible payloads.

### Expected merge conflict zones

- MEDIUM: the second-pass pairing loop and media-downgrade pass in
  `packages/ai/src/api/transform-messages.ts`.

## Lazy stream iterator cancellation (2026-07-20)

### What changed

- `packages/ai/src/api/lazy.ts`: `LazyAssistantMessageEventStream` overrides `[Symbol.asyncIterator]` so
  a consumer's `return()` (early break, abort) invokes a cancellation handler that awaits the deferred
  provider iterator's `return` exactly once; `forwardStream` iterates the inner iterator manually instead
  of `for await`.

### Why

- Breaking out of a lazy stream previously never reached the not-yet-consumed inner iterator, leaving
  the in-flight provider request running (billing and resources) when consumers terminate early.

### Why an extension could not handle it

- The lazy wrapper is the package's sanctioned dynamic-import seam; cancellation semantics are part of
  the stream contract it owns.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/lazy.ts` stream wrapper.

## Token estimation and UUIDv7 generator maintenance (2026-07-14)

### What changed

- `packages/ai/src/utils/estimate.ts`: `estimateMessageTokens` counts `providerNative` blocks (subtype
  plus raw JSON length) instead of misreading them as tool calls.
- `packages/ai/src/utils/uuid.ts`: typed-array generics (`Uint8Array<ArrayBuffer>`), a hoisted `crypto`
  local, and the extracted `formatUuid()` helper keep the time-ordered UUIDv7 generator compiling under
  the repo's TypeScript pin.

### Why

- Overflow prediction under-counted turns carrying native blocks; the generator must stay typecheck-clean
  under the pinned compiler without behavior change.

### Why an extension could not handle it

- Both are shared utilities consumed inside `packages/ai` before extension code runs.

### Expected merge conflict zones

- LOW: both files are small leaf utilities.

## Builtin provider set and model capability runtime (2026-06-23)

### What changed

- `packages/ai/src/providers/all.ts`: `normalizeBuiltinModel()` projects builtin catalog entries (applied
  to the Xiaomi MiMo provider set among others) and the builtin list exports `ollamaProvider` (Ollama
  Cloud, added 2026-07-30).
- `packages/ai/src/providers/anthropic.ts`, `packages/ai/src/providers/google.ts`, and
  `packages/ai/src/providers/google-vertex.ts`: re-export `stream`/`streamSimple` functions from the lazy
  API instances for direct consumers.
- `packages/ai/src/env-api-keys.ts`: the browser-safe env map detects `ALIBABA_TOKEN_PLAN_API_KEY`,
  `OLLAMA_API_KEY`, and `OPENGATEWAY_API_KEY`.
- `packages/ai/src/models.ts`: shared `supportsXhigh`/`supportsMax` capability detection (boundary-aware
  family matcher, explicit-map precedence, `null` veto) with `getSupportedThinkingLevels` delegating to
  it, and `checkProviderAuth` consulting the optional `OAuthAuth.check` hook for stored and ambient
  credentials.

### Why

- Provider availability, env detection, and capability inference run before the extension runtime loads
  and must be one implementation; per-adapter copies of the xhigh/max rules had already drifted once.

### Why an extension could not handle it

- `KnownProvider` typing, the builtin registration list, and the `Models` capability APIs are compile-time
  and package-internal surfaces.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/models.ts` capability predicates and auth precedence branches.
- LOW: additive provider/env entries in `packages/ai/src/providers/all.ts` and
  `packages/ai/src/env-api-keys.ts`; stream re-exports in the three provider modules.

## Registry seams: compat dispatch and scoped images registry (2026-06-23)

### What changed

- `packages/ai/src/compat.ts`: the mutable API-provider registry moved to the fork-owned
  `api-registry.ts` (compat re-exports registration and lookup), `stream`/`streamSimple` wrap calls in
  the text tool-call middleware when the model declares a `ToolCallFormat`, and the `cursor-agent` lazy
  API registers through `BUILTIN_APIS`.
- `packages/ai/src/images-api-registry.ts`: the images registry became scope-aware — an immutable
  builtin registry plus per-scope overlays, `installImagesProviderScopeAccessor` for the node-only
  subpath, strict-mode errors when multi-session lookup happens with no active scope, and closed-scope
  throws on lookup or mutation.

### Why

- Multi-session RPC hosts need session-scoped provider resolution that never falls back to a mutable
  process-global, while the root stays browser-safe (no `node:async_hooks` reachable from root).

### Why an extension could not handle it

- Registry dispatch and scope installation are package-internal seams; extensions register through the
  public surface but cannot re-home the registry or install the scope accessor.

### Expected merge conflict zones

- MEDIUM: `packages/ai/src/compat.ts` dispatch and re-export block (upstream owns the legacy registry
  inline).
- LOW: additive scope functions in `packages/ai/src/images-api-registry.ts`.

## Faux provider test surface (2026-06-23)

### What changed

- `packages/ai/src/providers/faux.ts`: `FauxContentBlock` includes `ProviderNativeContent` so faux turns
  exercise native blocks; `FauxCallLogEntry` records cloned contexts and stream options per call;
  `schedulerHook` paces chunk emission deterministically; and
  `registerFauxProvider`/`getRegisteredFauxProvider` (plus `fauxOverflowError`) expose registration and
  overflow fixtures for the test harness.

### Why

- Faux is the default token-free test provider: suites must capture what was sent, drive pacing
  deterministically, and cover native-block handling without live credentials.

### Why an extension could not handle it

- Faux is the in-package test double reached through the registry's fast path, below the extension
  runtime.

### Expected merge conflict zones

- MEDIUM: upstream also evolves faux; the registration and logging additions sit beside upstream's core.

## Cloudflare base-URL routing (2026-06-23)

### What changed

- `packages/ai/src/api/cloudflare.ts`: `isCloudflareProvider()` and `resolveCloudflareBaseUrl()`
  substitute provider-scoped `CLOUDFLARE_ACCOUNT_ID`/`CLOUDFLARE_GATEWAY_ID` values into the
  brace-placeholder gateway base URLs at request time.
- `packages/ai/src/api/anthropic-messages.ts` and `packages/ai/src/api/openai-responses.ts` resolve their
  base URL through that helper. `packages/ai/src/api/anthropic-messages.ts` is also this tracker's
  canonical cover for its accumulated adapter divergences (final tool-pair sanitization,
  unavailable-tool demotion, adaptive-thinking effort ladders, the warm-cache request builder, and the
  unsigned-thinking replay retry) recorded in the dated entries below.

### Why

- The committed catalog stores placeholder URLs; without request-time substitution the literal braces go
  to the wire and every Cloudflare route fails.

### Why an extension could not handle it

- Base-URL resolution happens inside adapter client construction before any extension hook or payload
  transform runs.

### Expected merge conflict zones

- LOW: `packages/ai/src/api/cloudflare.ts` helpers.
- MEDIUM: client construction sites in `packages/ai/src/api/anthropic-messages.ts` and
  `packages/ai/src/api/openai-responses.ts`.

## 2026-08-16 - Cursor agent protocol: full chat + tool calling (`cursor-agent` API)

### What changed and why

- `api/cursor-agent.ts` (new) + `api/cursor-agent.lazy.ts` (new): full port of the Cursor agent protocol from
  upstream oh-my-pi, adapted to this fork's API architecture. One HTTP/2 Connect stream per assistant turn
  (`POST /agent.v1.AgentService/Run`, `application/connect+proto`, 5-byte envelope framing, 5s client
  heartbeats, gRPC-trailer + Connect end-stream error decoding, abort via stream close). Interaction updates
  map onto assistant events (text/thinking deltas, streamed MCP tool calls with cumulative `args_text_delta`
  buffering + throttled partial-JSON parsing, `turnEnded`, `tokenDelta` usage). The exec channel is answered
  in band: the server blocks mid-turn on tool results, so exec frames dispatch onto injected
  `CursorExecHandlers` (legacy read/ls/grep/write/shell(+stream)/delete frames, modern `pi_*` frames, MCP
  calls incl. approval-only probes, kv blob get/set, `requestContext` tool advertising, `mcpState` regrouping,
  neutral hook replies) and every remaining frame gets a typed refusal or `ExecClientThrow` — an unanswered
  frame strands the turn. Each bridged call is synthesized into the assistant message as an already-resolved
  `toolCall` block (`kCursorExecResolved`) and paired with a `ToolResultMessage` via `onToolResult`.
- `api/cursor-agent/gen/agent_pb.ts` (new, vendored): protobuf-es v2.13 codegen of
  `packages/ai/proto/cursor/agent.proto`, with TS enums rewritten to erasable const objects by
  `scripts/transform-cursor-agent-proto.mjs` (repo compiles with `erasableSyntaxOnly`; runtime decode uses the
  embedded descriptor, not the TS enums). Excluded from Biome via `biome.json`.
- `api/cursor-agent/{types,exec-modern,pi-args,deterministic-id}.ts` (new): browser-safe handler contracts,
  wire result builders for the Pi frames, and arg translations shared by the API's synthesized display blocks
  and the coding-agent bridge (senpi's tools take plain kwargs, so `pi_read` maps to `offset`/`limit` instead
  of upstream's path selectors; `pi_edit` maps 1:1 onto `edits[{oldText,newText}]`; `workingDirectory`
  composes onto `bash` commands as a quoted `cd` prefix because senpi's bash has no cwd kwarg).
- Conversation continuity: history is rebuilt per request from `context.messages` into
  `rootPromptMessagesJson` blobs (system prompt + Vercel-AI-SDK-shaped user/assistant/tool JSON) and
  `turns[]` display structures over a per-conversation SHA-256 blob store; checkpoints are cached per
  conversation id; a bare `resource_exhausted` with zero tokens rotates the wire conversation id once.
- Model discovery: `fetchCursorUsableModels` (unary `GetUsableModels` over HTTP/2) normalizes usable models
  (1M-context signals, max-mode flag → `Model.compat.cursorMaxMode`); `providers/cursor.ts` now wires
  `api: cursorAgentApi()` + `fetchModels`, so the catalog appears after `/login cursor` (refresh runs
  automatically after login).
- Registration: `KnownApi`/`ApiOptionsMap` gain `"cursor-agent"`; `compat.ts` `BUILTIN_APIS` registers the
  lazy API; `model.ts` gains `CursorAgentCompat`; `utils/block-symbols.ts` (new) carries the streaming and
  `kCursorExecResolved` markers; `utils/event-stream.ts` gains `trackLocalWork`/`hasPendingLocalWork` so idle
  watchdogs can attribute mid-stream tool-run silence to local work.
- Deliberately not ported from upstream: computer use, subagents, background shells, canvas, smart-mode
  classifier, conversation search, native todo mirroring (summary-only pairing is kept), Kimi-K3 thinking
  replay, request-debug capture, and proxy tunneling — each answered with the protocol's typed refusal.

### Why this cannot be expressed as an extension

- The exec channel must be answered on the SAME HTTP/2 stream mid-turn, which requires provider-internal
  transport access; `KnownApi` registration, `Model.compat` typing, and the event-stream local-work contract
  are all package-internal seams.

### Expected merge conflict zones

- LOW: `types.ts` (`KnownApi`, `ApiOptionsMap`), `compat.ts` lists, `model.ts` compat conditional,
  `index.ts` export blocks — additive lines.
- NONE expected under `api/cursor-agent/`: fork-only files; upstream's implementation lives in a different
  architecture (`src/providers/cursor.ts`).

## 2026-08-16 - Cursor OAuth authentication and builtin provider

### What changed and why

- `auth/oauth/cursor.ts` (new): Cursor's browser deep-link + poll OAuth flow. `login` generates a PKCE S256
  pair, notifies `auth_url` for `https://cursor.com/loginDeepControl?challenge&uuid&mode=login&redirectTarget=cli`,
  and polls `https://api2.cursor.sh/auth/poll?uuid&verifier` with capped geometric backoff (1s ×1.2 up to 10s,
  150 attempts). 404 means "not approved yet"; 400/401/403/410 fail fast as definitive rejections; 429 keeps
  polling without burning the transient budget; network errors and 5xx tolerate 3 consecutive failures. The
  poll sleep is abort-aware, so cancelling the login interaction aborts immediately. `refresh` POSTs the stored
  refresh token as a bearer to `auth/exchange_user_api_key` and keeps the previous refresh token when the
  server does not rotate it. Expiry comes from the access-token JWT `exp` claim minus a 5-minute skew, with a
  1-hour fallback for unreadable tokens. Error messages carry HTTP status plus short server `error` strings,
  never raw bodies or token material.
- Compared to the upstream oh-my-pi flow this fixes a self-swallowed error bug (upstream throws its polling
  `OAuthError` inside its own `try`, so a definitive 401 was retried as if it were a network hiccup), adds
  abort-signal support, and validates response shapes strictly.
- `auth/oauth/load.ts` + `bun-oauth.ts`: `cursor` loader added to the lazy registry and the Bun static bundle.
- `providers/cursor.ts` (new) + `providers/all.ts` + `types.ts`: builtin `cursor` provider (OAuth-only,
  `isSubscription`), registered with an empty model catalog and an empty API map because Cursor chat runs on a
  protobuf Connect-RPC agent protocol (`agent.v1.AgentService`) that is not ported. Nothing becomes selectable
  in model pickers, and `Models.getAuth("cursor")` resolves the stored access token for integrations that speak
  the Cursor protocol.

### Why this cannot be expressed as an extension

- Builtin OAuth flows are lazy-loaded through the bundler-opaque loader registry in `auth/oauth/load.ts` and
  statically registered for standalone Bun binaries in `bun-oauth.ts`; both are package-internal seams an
  extension cannot reach, and `KnownProvider` typing is compile-time.

### Expected merge conflict zones

- LOW: `auth/oauth/load.ts` and `bun-oauth.ts` loader lists when upstream adds flows.
- LOW: `providers/all.ts` builtin list and `types.ts` `KnownProvider` union (additive lines).
- NONE expected in `auth/oauth/cursor.ts` / `providers/cursor.ts`: fork-only files; upstream's Cursor
  implementation lives in a different architecture (`src/registry/oauth/`).

## 2026-08-16 - GLM 5.3 reasoning effort + zai always-enabled thinking + catalog entries

### What changed and why

- `openai-completions.ts`: generalized the `isGlm52` thinking-level-map matcher to `isGlm5x` (regex `glm-5\.[23]`), so GLM 5.3 inherits the same host-specific thinkingLevelMap branches 5.2 uses (zai → DEEPSEEK map, openrouter → `{xhigh}`, default → `{max}`). Without this, 5.3 returned `undefined` from `getThinkingLevelMap` and reasoning effort was sent raw instead of mapped.
- `openai-completions.ts`: the zai `thinkingFormat` handler now forces `{type: "enabled"}` for GLM 5.3 ids even when no `reasoningEffort` is set. GLM 5.3 cannot disable thinking (Z.AI wire contract: `thinking.type` must always be `"enabled"`). GLM 5.2 keeps the existing `{type: "disabled"}` behavior when no effort is set.
- Provider data files (`packages/ai/src/providers/data/`): cloned glm-5.2 model entries to glm-5.3 across
  17 provider files (alibaba-token-plan, baseten, cloudflare-ai-gateway, cloudflare-workers-ai, fireworks,
  huggingface, nvidia, opencode-go, opencode, opengateway, openrouter, qwen-token-plan-cn, qwen-token-plan,
  together, vercel-ai-gateway, zai-coding-cn, zai). Each 5.3 entry inherits the 5.2 entry's baseUrl,
  compat, cost, contextWindow, maxTokens, and thinkingLevelMap with only the id/name version bumped. A
  qwen-token-plan-individual entry shipped initially and was reverted the same day (see the generator
  bullet).
- `scripts/generate-models.ts`: generalized the four 5.2-specific generator sites to also cover 5.3 (zai
  `isGlm52`→`isGlm5x`, openrouter, fireworks `glm-5p2`→`glm-5p3`, opencode-go). `glm-5.3` was also added
  to the qwen-token-plan-individual allowlist and then removed again on 2026-08-16: models.dev does not
  yet publish GLM 5.3 for that provider, so the strict allowlist validation (exact model-ID match plus the
  strict-generation error assertion) failed. Regeneration preserves the 5.3 entries and their
  thinkingLevelMaps everywhere else.
- `.manifest.json`: regenerated (structureHash + per-file sha256) to match the changed data files.
- `test/glm-5.3-thinking.test.ts`: pins both wire contracts through the stream (vi.mock openai + onPayload capture): low/medium effort maps through the zai thinking-level map (not raw), and no-reasoning still enables thinking.

### Expected merge conflict zones

- `openai-completions.ts`: the `isGlm52`→`isGlm5x` rename and the zai handler `isGlm53` guard sit in fork-modified sections; re-apply if upstream touches the same lines.
- Provider data files: fork-only; upstream has no counterpart.

## 2026-08-16 - Classify gateway 413 body-size rejections as overflow

### What changed and why

- `isContextOverflow` now recognizes gateway HTTP 413 byte-size rejections — "Request body too
  large", "Request Entity Too Large", `body_too_large`, and "Payload Too Large" — as the same
  recovery class as Anthropic's native `request_too_large`. Both wordings were captured from a
  live session whose compaction summarization request exceeded a gateway body limit on every
  fallback model ([#884](https://github.com/code-yeongyu/senpi/issues/884)).
- Without the classification, a byte-size rejection never reached input-shrinking recovery: it
  surfaced as a terminal error and wedged sessions above the compaction threshold.

### Why this cannot be expressed externally

- Overflow classification is the provider-neutral boundary every caller (compaction shrink-retry,
  agent-session overflow admission) keys off; an extension can only observe the final error.

### Expected merge conflict zones

- LOW: `utils/overflow.ts` pattern list and its header documentation; LOW in
  `test/overflow.test.ts` where the new cases sit beside existing provider patterns.

## 2026-08-14 - Harden stored OAuth request derivation

### What changed and why

- `resolveProviderAuth()` refreshes expired OAuth credentials before invoking the provider's optional side-effect-free `check`.
- Sentinel envelopes that represent zero usable accounts can no longer bypass the same availability predicate used by provider catalog checks.
- Stored OAuth derivation transiently merges request environment before both `check()` and `toAuth()`, then returns it for auxiliary replay without persisting request secrets.
- Explicit empty request environment values mask host values instead of falling back through truthiness.
- `ApiKeyAuth.ambientOnly` lets compatibility adapters remain fallback-only without changing explicit-key precedence for real dual-auth providers.
- Ambient-only adapters receive the raw request environment alongside their overlaid context, allowing provider-owned token namespaces to replace sibling host slots instead of importing them during replay.

### Why this cannot be expressed externally

- Stored OAuth credentials short-circuit inside the provider-neutral resolver before coding-agent provider composition or extension request hooks can intervene.

### Expected merge conflict zones

- MEDIUM: `auth/resolve.ts` at explicit-key precedence, environment overlay, and stored-OAuth refresh/check/derivation.
- LOW: `auth/types.ts` at the additive `ApiKeyAuth.ambientOnly` metadata.

## 2026-08-13 - Preserve explicit request compatibility fields

### What changed and why

- OpenAI-completions compatibility resolution now preserves explicit Baseten `chatTemplateArgs` and vLLM
  `supportsThinkingTokenBudget` settings when it combines detected defaults with model overrides.
- Focused Baseten and thinking-budget tests prove those fields reach the final request payload.

### Why this cannot be expressed externally

- The compatibility resolver is the provider-neutral normalization boundary used before any request transform or
  coding-agent extension can observe the payload.

### Expected merge conflict zones

- MEDIUM: `utils/prompt-cache-ttl.ts` at the explicit compatibility override return object.

## 2026-08-13 - Upstream option and live-test cleanup

### What changed and why

- Removed an obsolete reasoning-budget local and a Baseten live-test key lookup no test consumes after the
  upstream option/catalog merge.
- Runtime behavior and live-test gating are unchanged; this keeps warnings fatal without weakening the checks.

### Why this cannot be expressed externally

- Both warnings arise in the provider-neutral option compiler and AI test module before coding-agent extensions
  exist.

### Expected merge conflict zones

- LOW: `api/simple-options.ts` reasoning-budget setup and `test/context-overflow.test.ts` live-key declarations.

## 2026-08-12 - Throw-based sibling for the bounded assistant retry loop

### What changed and why

- `utils/retry.ts` adds `retryTransientCall(produce, isRetryable, policy, signal, callbacks)`. It reuses the exact
  sleep, exponential backoff (`baseDelayMs * 2^(attempt-1)`), abort, and `RetryCallbacks` contract that
  `retryAssistantCall` already implements, for producers that report failure by THROWING rather than by resolving an
  `AssistantMessage` with `stopReason: "error"`.
- The classifier is an explicit `isRetryable(error)` parameter, so each caller keeps ownership of what counts as
  transient instead of inheriting assistant-message semantics that do not apply to it.
- `retryAssistantCall` is untouched and stays value-based; its full existing suite passes unchanged. The two loops
  share the private `sleep`/`RetrySleepAbortError` primitives so backoff and cancellation have one implementation.
- First consumer is senpi's builtin compaction extension, whose summarization request throws and therefore could not
  reuse the bounded retry without first reshaping failures into assistant messages.

### Why this cannot be expressed externally

- The delay, abort-during-backoff normalization, and retry callback ordering are private to this module. A caller
  reimplementing them outside `utils/retry.ts` is exactly the duplicated policy this addition removes.

### Expected merge conflict zones

- MEDIUM: `utils/retry.ts` between `RetryCallbacks`/`sleep` and `retryAssistantCall`, where the new function is
  inserted.
- LOW: `test/retry-transient-call.test.ts` is a new focused file for the added surface.

## 2026-08-12 - OpenGateway built-in provider

### What changed and why

- Added `opengateway` as a built-in provider for the OpenGateway data plane (`https://apis.opengateway.ai`),
  an OpenAI-compatible multi-provider gateway serving `owner/model` ids (OpenAI, Anthropic, Google, xAI,
  Moonshot, DeepSeek, ZAI, MiniMax, Qwen) through a single `OPENGATEWAY_API_KEY` Bearer credential.
- The generated catalog is hydrated from the gateway's live `/v1/models` at generation time by
  `scripts/generate-models-opengateway.ts`: chat-completions-capable, non-retired models are kept and
  enriched with pricing/context/reasoning metadata from models.dev, preferring the owning provider's
  catalog over the OpenRouter id space. Six models models.dev cannot enrich carry explicit overrides.
- Env detection maps `OPENGATEWAY_API_KEY`; the provider factory uses the shared `openai-completions`
  API with standard OpenAI compat auto-detection.

### Why this cannot be expressed externally

- A user-level `models.json` custom provider can point at the gateway, but it cannot ship a generated,
  validated catalog in `src/providers/data/`, participate in `KnownProvider` typing, or register the
  built-in display name that makes the provider a first-class `/login` target.

### Expected merge conflict zones

- MEDIUM: `scripts/generate-models.ts` main fetch/assembly flow (new source call + spread).
- LOW: `src/types.ts` `KnownProvider` union, `src/env-api-keys.ts` env map, `src/providers/all.ts`
  registration list.
- LOW: generated artifacts (`models.generated.ts`, `providers/data/`) — resolve by regenerating.
## 2026-08-12 - Default direct Anthropic prompt caching to five minutes

### What changed and why

- Native `anthropic-messages` requests now use Anthropic's default five-minute prompt-cache retention when neither
  `cacheRetention` nor `PI_CACHE_RETENTION=long` explicitly selects long retention. The adapter emits bare
  `{ type: "ephemeral" }` cache-control markers instead of adding `ttl: "1h"`.
- The browser-safe `resolvePromptCacheTtlSeconds()` mirror now reports 300 seconds for the same omitted-retention
  path, keeping cache-aware tool waits and goal-monitor timing aligned with the wire request.
- Explicit `cacheRetention: "long"`, model-level long retention, and `PI_CACHE_RETENTION=long` still request and
  report one hour on supported canonical Anthropic endpoints. Anthropic-compatible proxies remain five minutes.

### Why this cannot be expressed externally

- Prompt-cache retention is selected while the Anthropic provider serializes system, tool, and conversation cache
  breakpoints. Extensions only observe higher-level requests and cannot safely rewrite every provider-owned
  `cache_control` block or the browser-safe TTL estimate consumed by cache-aware runtime scheduling.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` around `resolveCacheRetention()` and the cache-session-id setup.
- MEDIUM: `utils/prompt-cache-ttl.ts` in the native Anthropic branch of `resolvePromptCacheTtlSeconds()`.
- LOW: focused cache-retention and TTL tests that pin provider-default precedence.

## 2026-08-11 - Native Responses image-generation item reconciliation

### What changed and why

- The shared OpenAI Responses stream loop now structurally recognizes `image_generation_call` output items across
  SSE, WebSocket, Azure, and Codex adapters. Added and done frames reconcile into one provider-native slot, while a
  terminal response backfills the final item when providers omit `response.output_item.done`.
- Completed items retain only validated base64 plus an optional nonempty `revised_prompt`. Missing, empty, or invalid
  results become short malformed status blocks; failed and provider-specific statuses remain message-local metadata
  instead of escalating into transport errors. Partial-image events remain intentionally ignored.
- Native image results have a 24 MiB aggregate base64-character cap. Exceeding it scrubs already collected image bytes
  before the adapter returns a normalized provider error, so oversized data cannot enter the final assistant content.
- `OpenAIResponsesCompat.supportsImageGeneration` exposes an explicit native-tool compatibility override, with direct
  OpenAI Responses endpoints as the default-compatible route.

### Why this cannot be expressed externally

- Output-item slot reconciliation and terminal-response backfill happen inside the shared provider event loop before
  extensions receive a completed assistant message. External hooks cannot reliably deduplicate frames or prevent
  oversized native payloads from entering normalized content across all three adapters.

### Expected merge conflict zones

- MEDIUM: `api/openai-responses-shared.ts` output-slot lifecycle and terminal response finalization.
- LOW: `openai-responses-compat.ts` additive compatibility flag.
- LOW: `api/openai-responses.ts` resolved compatibility defaults.

## 2026-08-11 - OpenAI images provider with generated gpt-image models

### What changed and why

- `scripts/generate-image-models.ts` now also emits `IMAGE_MODELS.openai` with static, hand-authored entries for
  `gpt-image-2` and `gpt-image-1.5` (api `openai-images`, provider `openai`, baseUrl `https://api.openai.com/v1`,
  input `["text"]` only - the v1 generations endpoint is text-only). Costs quote models.dev as of 2026-08-11
  (gpt-image-2: $5 input / $30 output / $1.25 cache-read per 1M tokens; gpt-image-1.5 has no models.dev cost entry
  as of that date and is zero-filled until pricing is published). The OpenRouter live fetch is unchanged.
- `providers/openai-images.ts` adds `openaiImagesProvider()` mirroring the OpenRouter images provider, authing via
  `OPENAI_API_KEY` and serving `Object.values(IMAGE_MODELS.openai)` through the lazy `openaiImagesApi()` accessor.
- `providers/all.ts` appends the provider to `builtinImagesProviders()`, so `builtinImagesModels()` exposes the
  `openai` provider and its catalog.

### Why this cannot be expressed externally

- The built-in image model catalog is generated inside `packages/ai`; external providers can register through the
  images registry but cannot extend the generated `IMAGE_MODELS` catalog or the builtin provider list.

### Expected merge conflict zones

- LOW: additive static model table and provider grouping in `scripts/generate-image-models.ts`.
- LOW: one-line append in `builtinImagesProviders()` and the import block in `providers/all.ts`.

## 2026-08-11 - Lazy builtin registration for openai-images provider

### What changed and why

- `providers/images/register-builtins.ts` registers the `openai-images` ImagesApi as a lazy builtin alongside the
  existing `openrouter-images` registration. The lazy wrapper defers the dynamic import of `api/openai-images.ts`
  until first invocation, and catches any module-load failure into a normalized `AssistantImages` error envelope
  (stopReason "error", never a thrown rejection).
- The shared `createLazyLoadErrorImages` helper is generalized over `ImagesApi` so both providers reuse the same
  error-envelope construction.

### Why this cannot be expressed externally

- Builtin provider registration runs at module load time inside `packages/ai`; external extensions register through
  the public registry surface but cannot supply the lazy module-promise boundary that keeps the openai-images SDK
  out of the initial bundle.

### Expected merge conflict zones

- LOW: additive registration entry inside `registerBuiltInImagesApiProviders()` and the new lazy wrapper export in
  `providers/images/register-builtins.ts`.
- LOW: additive test file `test/images-registry-builtins.test.ts`.

## 2026-08-11 - OpenAI Images API adapter

### What changed and why

- `api/openai-images.ts` adds the text-only OpenAI Images generations adapter with canonical `/v1` endpoint
  normalization, shared credential-header auth, provider-owned retries, usage/cost mapping, and normalized error envelopes.
- Image results accept provider base64, data URLs, or unauthenticated signed HTTP URLs. Hydration validates image MIME or
  magic bytes, enforces a 24 MiB cap, and keeps generated bytes in memory so packages/ai remains browser-safe.
- `api/openai-images.lazy.ts` adds the sanctioned dynamic-import boundary, and `types.ts` recognizes `openai-images` as
  a known images API.

### Why this cannot be expressed externally

- Correct request fields, SDK retry ownership, credential-header suppression, and response hydration are provider wire
  concerns that must run before the normalized `AssistantImages` result reaches callers.

### Expected merge conflict zones

- LOW: additive API and test modules plus the `KnownImagesApi` union line.
- LOW: additive entry at the top of `src/changes.md`.
## 2026-08-11 - Normalize replayed tool IDs for strict OpenAI-compatible gateways

### What changed and why

- `api/openai-completions.ts` now sanitizes every replayed non-Responses tool-call ID to the OpenAI-compatible
  alphanumeric/underscore/dash shape, preserves already-valid bounded IDs, and uses a deterministic hash suffix when
  sanitization or the 40-character bound changes the ID.
- `api/transform-messages.ts` lets strict target adapters opt into applying their supplied tool-call ID normalizer to
  same-model history as well as cross-model history. OpenAI completions enables that opt-in and remaps the paired
  tool result through the existing ID map; Responses retains its provider-native IDs.
- A persisted `apitopia/kimi-k3-unlocked` session stored tool-call IDs such as `eval:18`. After switching to
  `opengateway/anthropic/claude-fable-5`, the gateway rejected the request before generation with
  `messages.36.content.1.tool_use.id: String should match pattern '^[a-zA-Z0-9_-]+$'`.
- This cannot be extension-local: tool-call IDs and their paired results are transformed inside provider request
  serialization before an extension can safely rewrite the complete outbound history. Rewriting persisted session
  files would also leave other histories and future provider handoffs exposed.

### Expected merge conflict zones

- MEDIUM: `api/openai-completions.ts` near the local `normalizeToolCallId` function in `convertMessages`.
- LOW: `api/transform-messages.ts` in the assistant `toolCall` transformation branch.
- LOW: `../test/model-switch-replay-characterization.test.ts` near the non-Responses replay cases.

## 2026-08-11 - Retry gateway model-request rejections

### What changed and why

- `utils/retry.ts` classifies `"model request was rejected"` as retryable so a gateway/proxy-side "The model
  request was rejected. Check the request and try again." response is absorbed by the bounded same-model retry
  policy (`settings.retry`) instead of failing the turn or immediately burning the fallback chain. Observed in a
  live session on 2026-08-11. The classifier couples the rejection sentence to its explicit "Check the request and
  try again." instruction so permission denials, content refusals, and request-shape errors remain terminal, and
  the non-retryable list still wins on overlap.

### Why this cannot be expressed externally

- The transient-vs-terminal message classifier is package-internal; callers and extensions consume its verdict
  through `retryAssistantCall`/`isRetryableAssistantError` and cannot add a message class without forking the
  retry loop.

### Expected merge conflict zones

- LOW: additive pattern in `utils/retry.ts`, additive cases in `test/retry.test.ts`, additive mock-loop scenario
  and optional scripted-error `type` under `.agents/skills/senpi-qa/scripts/`.

## 2026-08-11 - Optional availability `check` on `OAuthAuth`

### What changed and why

Added an optional `check?(input)` to `OAuthAuth` (`auth/types.ts`) and taught `checkProviderAuth` (`models.ts`) to consult it in the stored-OAuth-credential branch. Previously that branch was a pure structural short-circuit — `provider.auth.oauth ? {configured} : undefined` — so any stored OAuth credential, including an empty sentinel envelope with zero accounts, reported the provider as configured. The fallback engine reads configured-ness through `hasConfiguredAuth`, so such a provider was never skipped as `unauthenticated`. `ApiKeyAuth` already exposes an equivalent `check`; this makes the OAuth path symmetric. When `check` is absent, behavior is byte-identical to before, so every existing OAuth provider is unaffected. This cannot be extension-local: the short-circuit lives in `ModelsImpl.checkProviderAuth`, which no extension hook reaches, and `OAuthAuth` had no `check` to supply.

### Expected merge-conflict zones

LOW in `auth/types.ts` (additive optional field on `OAuthAuth`); LOW in `models.ts` `checkProviderAuth` (one stored-OAuth branch expanded, existing behavior preserved when `check` is undefined).

## 2026-08-11 - OAuth availability `check` for ambient and no-credential providers

### What changed and why

- Follow-up to the optional `OAuthAuth.check` hook: `Models.checkAuth()` now also invokes the hook for ambient
  no-credential providers, not only for stored OAuth credentials. Providers without a hook retain the previous
  behavior where any matching stored OAuth credential is configured.
- This lets providers confirm usable ambient OAuth without refreshing, resolving, or exposing token material. Hook
  failures are wrapped in `ModelsError` on both the stored-credential and ambient paths.

### Why this cannot be expressed externally

- Provider availability and model filtering happen inside `Models` before host registries and fallback controllers see
  the provider, so an extension-only post-filter would leave `checkAuth()` and `getAvailable()` inconsistent.

### Expected merge conflict zones

- MEDIUM: the auth precedence branches in `models.ts`.

## 2026-08-09 - Native Anthropic prompt-cache warming primitive

### What changed and why

- `api/warm-prompt-cache.ts` adds the non-streaming `warmPromptCache()` request primitive for direct Anthropic
  Messages models. It sends the normal converted system, tools, and conversation cache breakpoints with
  `max_tokens: 0`, strips streaming, thinking, and forced tool choice, disables SDK retries, and returns normalized
  input/output/cache-read/cache-write usage alongside the raw provider usage.
- `api/anthropic-messages.ts` exposes a focused warm-request builder so pre-warming and the normal stream share the
  same message, tool, cache-control, and tool-pair conversion instead of maintaining a second wire transform.
- The root package exports the primitive and its exact supported/unsupported result contract. Non-Anthropic APIs and
  Anthropic-compatible gateways return unsupported before authentication or network work begins.

### Why this cannot be expressed externally

- Correct cache breakpoints depend on adapter-internal Anthropic message and tool conversion. Reconstructing the
  request outside the package would drift from the normal provider path and could mutate history or send incompatible
  streaming/thinking options.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` near request construction and cache-control conversion.
- LOW: additive `api/warm-prompt-cache.ts` and root `index.ts` export.

## 2026-08-09 - Prompt-cache correctness across OpenAI-compatible and Bedrock lanes

### What changed and why

- `api/openai-completions.ts` `parseChunkUsage()` now reads Kimi's flat `usage.cached_tokens` only after the
  existing nested OpenAI and `prompt_cache_hit_tokens` forms, preserving precedence while reporting cache reads and
  uncached input correctly.
- `types.ts` adds `OpenAICompletionsCompat.supportsPromptCacheKey`; `utils/prompt-cache-ttl.ts`
  `detectOpenAICompletionsCompat()` enables it for Moonshot and direct OpenAI endpoints, and
  `getOpenAICompletionsCompat()` preserves explicit overrides. `buildParams()` uses the resolved flag to emit a
  clamped stable key without adding provider URL checks at the request boundary.
- OpenRouter compatibility detection now defaults session affinity on, and `buildParams()` sends the same session ID
  in both `x-session-id` and the body `session_id` from the first cache-enabled request.
- Runtime and `scripts/generate-models.ts` detection share the literal `anthropic/`, `qwen/`, `google/` cache-control
  prefix allowlist and strip one optional leading `~`. Hydrated Moonshot and OpenRouter catalogs bake the resolved
  compatibility metadata.
- `utils/prompt-cache-ttl.ts` `supportsOneHourCacheTtl()` is the single Bedrock Claude 4.5 allowlist used by both
  `api/bedrock-converse-stream.ts` cache-point sites and `resolvePromptCacheTtlSeconds()`, preventing a one-hour
  resolver estimate when the wire request can only use five minutes.
- `resolvePromptCacheTtlSeconds()` reports 300 seconds for the actual `claude-sdk-oauth` model shape because the SDK
  owns that lane's default ephemeral prompt caching.

### Why this cannot be expressed externally

- Usage parsing, provider request fields, cache-point TTLs, and cache lifetime estimates are adapter-internal wire
  contracts resolved before an extension can observe a normalized assistant message or safely rewrite every request
  path. Generated compatibility metadata must also stay aligned with runtime detection.

### Expected merge conflict zones

- HIGH: `utils/prompt-cache-ttl.ts` OpenAI-compatible detection/merge and cache TTL resolver switches.
- HIGH: `api/openai-completions.ts` request construction and streamed usage parsing.
- MEDIUM: `api/bedrock-converse-stream.ts` system and conversation cache-point construction.
- MEDIUM: `scripts/generate-models.ts` compatibility detection and generated Moonshot/OpenRouter data.

## 2026-08-09 - Shared visible assistant-content classification

### What changed and why

- `utils/visible-text.ts` defines the shared visibility boundary for assistant text: Unicode format characters
  (`\p{Cf}`) are removed before whitespace trimming, so zero-width spaces, joiners, word joiners, byte-order marks,
  and directional formatting marks cannot make an otherwise empty response appear user-visible.
- `hasVisibleAssistantContent` treats a tool call or text containing a visible scalar as assistant output. Emoji ZWJ
  sequences remain visible because removing the joiner leaves visible emoji scalars.
- The browser-safe root exports both predicates so agent-core and other consumers use one classification instead of
  duplicating JavaScript `trim()` checks that miss U+200B.

### Why this cannot be expressed externally

- Assistant response visibility is a shared message-level contract consumed before coding-agent extensions receive a
  committed turn; external hooks cannot reliably repair divergent classifiers in each core consumer.

### Expected merge conflict zones

- LOW: additive `utils/visible-text.ts` module and root export in `index.ts`.

## 2026-08-05 - Root-object tool schemas and request-shape error classification

### What changed and why

- `utils/tool-schema-compat.ts` no longer hoists a ROOT schema's `type` into its combiner branches.
  OpenAI-compatible gateways reject a covered object-shaped root when normalization removes its required
  `type: "object"`, which is exactly how an Apitopia/Kimi turn died on 2026-08-04. `normalizeNode` now takes an
  `isRoot` flag so branch-level hoisting (still correct below the root) is unchanged. Plain and object-shaped roots
  receive or retain object typing, while scalar and mixed root unions remain unchanged instead of being mislabeled.
  Root `allOf` is protected from root type hoisting but is not flattened into a synthetic object.
- `mergeRootObjectUnion` merges object-shaped root `anyOf`/`oneOf` schemas without replacing the root's own
  `properties`/`required`. It previously returned `{"properties":{},"type":"object"}` for a root union that declared
  its properties at the root — silently sending a tool with zero parameters. Untyped constraint-only branches
  (`{ required: [...] }` over root properties) are accepted, and `required` keeps root entries plus only the names
  every branch shares.
- `normalizeToolParametersForMoonshot` now reuses the same object-root normalization before annotation stripping,
  rather than maintaining a second, divergent root-merge path.
- `api/anthropic-messages.ts` resolves object-shaped root `anyOf`/`oneOf` parameters through the shared
  `resolveRootObjectSchema` before building `input_schema`. `convertTools` reads top-level `properties`/`required`
  only, so covered root unions previously arrived as `{"properties":{},"required":[]}`. The conversion now merges
  their properties and required names while leaving ordinary object schemas unchanged; non-object unions and root
  `allOf` remain outside this resolver's flattening boundary.
- `utils/retry.ts` classifies five recognized malformed tool/function schema message forms as NON-retryable, and
  `NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN` is renamed `NON_RETRYABLE_PROVIDER_ERROR_PATTERN` because it no
  longer covers only limits. Gateways can wrap these deterministic rejections in retryable-looking 5xx envelopes,
  so generic status matching replayed an equivalent invalid request on the same model. Four matchers target
  `tools.`/`functions.` request paths; `invalid tool schema` is intentionally broader. Eligible configured
  fallbacks rebuild their own provider-specific request rather than inheriting guaranteed identical bytes.

### Why this cannot be expressed externally

- Wire-payload schema normalization runs inside the provider adapter, after extension payload
  hooks, so no extension can repair the emitted tool schema. Retry classification is consumed by
  the agent session's hard-error routing, which lives below any extension seam.

### Expected merge conflict zones

- MEDIUM: `utils/tool-schema-compat.ts` around root handling and `mergeRootObjectUnion`.
- MEDIUM: `utils/retry.ts` in the non-retryable pattern list and its renamed constant.
- LOW: `test/openai-completions-tool-schema-compat.test.ts`, `test/retry.test.ts`.


## 2026-08-03 - Hint-aware 429 retry-after propagation

### What changed and why

- `utils/retry-hint.ts` (new) owns the strict 429 retry-hint extractor: `extract429RetryAfterMs` plus
  canonical marker helpers. It parses `retry-after` / `retry-after-ms` headers, `x-ratelimit-reset*` epoch
  headers, recursive JSON `retryDelay` fields (Google RPC style), body prose ("try again in N s", "resets at
  <ISO8601>"), and SSE `event: error` payloads, normalizing every shape to a millisecond delay or a sentinel for
  absent hint. Explicit-zero (retry immediately) is distinct from absent-hint (no guidance), so callers never
  conflate “server said now” with “server said nothing.”
- `utils/provider-retry.ts` propagates the extracted hint as a structured `ProviderRetryDelayError` carrying
  the canonical marker, instead of leaving the delay embedded in an opaque error string. Non-429 retry-loop
  behavior (forced-eligibility, backoff) is intentionally preserved — the hint path only augments 429-class
  errors.
- `api/anthropic-messages.ts` and `api/openai-codex-responses.ts` emit the canonical markers at both the
  HTTP-status boundary and the SSE in-stream `event: error` boundary, so hints survive regardless of whether
  the 429 arrives as a status response or a mid-stream error event.

### Expected merge conflict zones

- MEDIUM: `utils/provider-retry.ts` around the 429 hint propagation and `ProviderRetryDelayError`.
- MEDIUM: `api/anthropic-messages.ts` and `api/openai-codex-responses.ts` at the status/SSE error
  boundaries.
- LOW: `utils/retry-hint.ts` (new file) and `package.json` `./utils/*` export.

## 2026-08-01 - Final Anthropic tool-pair normalization

### What changed and why

- `api/anthropic-tool-pairs.ts` owns the browser-safe wire sanitizer for Anthropic client `tool_use` /
  `tool_result` adjacency, deduplication, orphan removal, and interrupted-result synthesis.
- `api/anthropic-messages.ts` applies that sanitizer after `onPayload` and every built-in Anthropic request
  rewrite, immediately before request metadata extraction and SDK submission.
- The final boundary no longer depends on extension-runner liveness or hook registration order. A reload,
  extension, or late payload transform can remove one result from a parallel tool-call turn without sending an
  invalid request to Anthropic.
- `test/anthropic-final-tool-pair-guard.test.ts` deterministically removes one result in the last payload hook
  and asserts that the SDK receives both immediate result blocks, including a synthetic error result.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` around the final request-sanitization pipeline.
- LOW: `api/anthropic-tool-pairs.ts` if upstream adds equivalent Anthropic wire normalization.

## 2026-07-31 - Recover Codex WebSocket fallback sessions

### What changed and why

- A transient pre-start Codex WebSocket failure no longer pins the session to
  SSE for the rest of the process lifetime. The fallback circuit now keeps
  immediate requests on SSE for 60 seconds, then lets the next fresh request
  probe WebSocket again.
- Recovery changes only a future request. The existing guard still propagates
  transport failures after the response stream starts, so no already-started
  or potentially billed response is retried through SSE.
- Production session cleanup now removes both live WebSocket resources and
  the session's fallback/debug state. Long-lived app-server processes no
  longer retain degraded routing after a session is closed.
- Fallback and debug-state ownership moved into
  `api/openai-codex-responses/fallback-state.ts`, reducing the oversized
  adapter while keeping the public debug API stable.

### Coverage

- `../test/chatgpt-subscription-fallback-recovery.test.ts` proves the immediate SSE
  cooldown boundary, post-cooldown WebSocket recovery, and immediate recovery
  after production cleanup.
- Existing Codex stream tests retain the post-start no-fallback guard,
  continuation recovery, connection-limit handling, and one-shot
  `cacheRetention: "none"` behavior.

### Expected merge conflict zones

- MEDIUM: Codex WebSocket debug/fallback state and session cleanup.

## 2026-07-31 - Align Codex prompt-cache affinity headers

### What changed and why

- Issue #589's donated 25-hour session contained an 8.5-minute HTTP/SSE
  fallback burst where 18 requests reused only 22,016 cached tokens and resent
  roughly 175k-180k uncached tokens, interleaved with 10 normal roughly
  196k-199k cache hits. No model, thinking-level, compaction, or custom-message
  transition occurred inside the burst.
- The session had previously recorded Codex WebSocket transport failures and
  fallen back to SSE. Senpi's Codex adapter sent the stable session ID as
  `prompt_cache_key`, `session-id`, and `x-client-request-id`, but omitted the
  official Codex `thread-id` affinity header on both SSE and WebSocket.
- `api/openai-prompt-cache.ts` now applies the complete stable affinity tuple,
  and both transports use it. Senpi has one durable conversation identifier at
  this layer, so `session-id`, `thread-id`, and `x-client-request-id` all carry
  the clamped Senpi session ID while `prompt_cache_key` remains unchanged.
- `cacheRetention: "none"` keeps its existing no-affinity SSE behavior.
- This fixes the client-controlled protocol divergence. Open upstream Codex
  reports show that the provider cache can still miss intermittently with
  byte-identical bodies and stable keys, so the change does not claim that a
  best-effort upstream cache becomes deterministic.

### Coverage

- `../test/chatgpt-subscription-cache-affinity.test.ts` drives the real SSE and
  WebSocket request builders, pins the complete header/body mapping, and
  preserves the disabled-cache boundary.

### Expected merge conflict zones

- LOW: additive prompt-cache header helper and the two Codex header builders.

## 2026-07-31 - Reshape unavailable Anthropic tool transcript records

### What changed and why

- Unavailable Anthropic `tool_use` history is still demoted to satisfy Anthropic's same-request tool-reference validation, but the assistant-role text now uses explicit `<unavailable-tool-call>` transcript records instead of an imitable `[Called tool ... with input: ...]` pseudo-action.
- The first record for each missing tool name in a request explains that the call is historical and lists a capped, request-derived set of tools actually available now; later records for that name are terse self-closing elements. Tracking is request-local, so concurrent requests cannot interfere.
- Historical call inputs are omitted entirely, removing large replayed patch bodies. Tool-result text remains available in `<unavailable-tool-result>` records; only literal closing-tag openers are narrowly neutralized so attacker-influenced output cannot escape the envelope.
- XML attribute values are escaped for exotic tool names. The text builders live in the non-public `utils/` surface rather than growing the already-large Anthropic adapter.
- Coverage drives the real fake-client request path for first/later behavior, request-derived list capping, input omission, exotic-name escaping, result preservation, and closing-tag neutralization. The existing tool-reference integrity test remains unchanged.

### Expected merge conflict zones

- LOW: unavailable-tool rewriting inside `api/anthropic-messages.ts` and its internal text helper import.

## 2026-07-30 - Map-less GPT-5.6 Sol preserves max reasoning

### What changed and why

- OpenAI-compatible map-less `gpt-5.6-sol` models now expose `xhigh` and `max` without requiring a generated
  `thinkingLevelMap`.
- Explicit maps remain authoritative: a missing level on an existing map stays unavailable, and `null` vetoes the
  heuristic. `supportsXhigh` and `supportsMax` share that precedence.
- `supportsMax` is exported from `models.ts` so OpenAI Responses, Azure Responses, Codex Responses, and
  Completions send `max` on the wire instead of clamping a UI-selected map-less Sol level to `high`.
- Coverage pins capability, negative non-Sol boundaries, and captured request payloads without live tokens.

## 2026-07-30 - Recover Kimi XTML response channels from thinking

### What changed and why

- Kimi-family streams now sanitize structural `think` / `response` / `message` XTML markers from final thinking
  content and promote text only when an explicit response-open boundary makes the split unambiguous.
- Recovery uses the existing code mask, so XTML-looking examples inside inline or fenced code remain literal.
  Closing-marker-only payloads are sanitized but never exposed as visible chain-of-thought.
- Model recovery composition now applies Kimi response-channel recovery even when no tools are registered, while
  leaked text-tool-call reconstruction remains conditional on available tools.
- Coverage: coding-agent runtime-boundary tests pin no-tools recovery, split markers, conservative malformed
  handling, code literals, ordinary Kimi thinking, non-Kimi isolation, and existing tool-call recovery.

## 2026-07-30 - Add the official Ollama Cloud dynamic provider

### What changed and why

- New `providers/ollama.ts` registers `ollama` as an OpenAI-compatible builtin using `OLLAMA_API_KEY` and
  `https://ollama.com/v1`.
- The provider discovers the current Cloud catalog from `/api/tags`, enriches each entry through `/api/show`,
  exposes only tool-capable models, and derives thinking, vision, and architecture-specific context metadata.
- Per-model inspection uses bounded concurrency and retains a last-known tool model when that tag's inspection
  fails beside usable results; complete inspection failure and aborts fail the refresh without replacing the cache.
  A successful discovery with no usable tool models also preserves the last-known catalog instead of publishing or
  persisting an empty replacement.
- Catalog reads use the shared auth-aware `ModelsStore` refresh lifecycle, so only a non-empty successful result is
  persisted and failed or empty refreshes cannot replace the last-known list. Subscription usage has no stable
  per-token dollar rate, so discovered models report zero cost instead of fabricating prices.
- Ollama's OpenAI-compatible endpoint does not accept OpenAI-only storage/developer/strict-tool fields; the model
  compatibility projection uses `max_tokens`, and Senpi's `max` reasoning level clamps to Ollama's supported
  `high` wire value.

### Expected merge conflict zones

- LOW: additive provider factory, provider registration, `KnownProvider`, environment-key map entries, and the
  existing Ollama reasoning-level map in `api/openai-completions.ts`.
- LOW: additive provider documentation and deterministic catalog fixtures.

## 2026-07-29 - Preserve invoke-recovery protocol provenance

### What changed and why

- `wrapStreamWithInvokeRecovery()` accepts typed recovery options carrying both the parser factory and the protocol
  identity. The previous parser-only argument selected Kimi XTML correctly but lost that provenance in shared
  diagnostics and recovered tool-call IDs.
- Successful Kimi recovery now reports `protocol: "kimi-xtml"` and allocates `recovered-kimi-xtml-*` IDs. Invalid
  content/native event order and collision failures use the same protocol identity instead of always claiming
  `antml`.
- The default and legacy parser-function call forms remain ANTML-compatible, preserving existing Claude/default
  recovery diagnostics and IDs.
- Coverage: the shared wrapper pins Kimi failure diagnostics, and the coding-agent runtime boundary pins successful
  Kimi diagnostics plus recovered IDs.

### Expected merge conflict zones

- MEDIUM: invoke-recovery wrapper, diagnostic, failure, and native projection constructor signatures.

## 2026-07-29 - Serialize OpenAI completion content block events

### What changed and why

- `api/openai-completions.ts` now closes the active thinking, text, or native tool-call block before starting the
  next block. The adapter previously accumulated every block and emitted all `*_end` events only after the wire
  stream finished, producing overlapping canonical lifecycles such as `thinking_start -> text_start` and
  `text_start -> toolcall_start`.
- Providers that put text, reasoning, and parallel tool-call deltas in the same chunk keep their established
  single-block aggregation. The adapter defers that mixed chunk's content events and replays text, thinking, and
  each tool call as complete sequential lifecycles, avoiding duplicate text/thinking starts without restoring
  overlapping events.
- The invoke-recovery wrapper correctly rejects overlapping canonical content lifecycles. Kimi K3 exposed the
  adapter bug when a normal response streamed reasoning, visible text, and native tool calls in sequence, causing
  the user-facing terminal error `Invalid assistant content event order`.
- Coverage: `test/openai-completions-stream-lifecycle.test.ts` drives a real local SSE endpoint through reasoning,
  text, and a native tool call and pins the sequential start/delta/end event order.
  `test/openai-completions-tool-choice.test.ts` pins mixed text/reasoning/parallel-tool aggregation and sequential
  event replay.

### Expected merge conflict zones

- LOW: the block lifecycle helpers inside `api/openai-completions.ts`.

## 2026-07-29 - Support static credential headers without a synthetic API key

### What changed and why

- `auth/headers.ts` defines the narrow, case-insensitive credential-header contract shared by auth discovery and
  request adapters. Standard authorization, API-key, API-token, auth-token, access-token, and client-secret header
  names count only when their effective value contains credential material; metadata such as `User-Agent`,
  request ids, and trace tokens does not.
- `api/openai-client-auth.ts` lets OpenAI-compatible adapters initialize from credential-bearing headers when
  `ModelAuth.apiKey` is absent. Header-only clients suppress the SDK's default `Authorization: Bearer ...` header
  unless an explicit Authorization or the existing Cloudflare AI Gateway authorization path owns that behavior.
- `api/openai-completions.ts` and `api/openai-responses.ts` use the shared client-auth resolver for HTTP and
  Responses WebSocket requests, so `x-api-key` and equivalent static credentials work without an invented bearer
  token.

### Coverage

- `test/auth-headers.test.ts` covers recognized names, metadata rejection, case-insensitive overrides, and empty
  authorization schemes.
- `test/openai-header-auth.test.ts` exercises real OpenAI-compatible request construction for Completions and
  Responses and proves metadata-only headers fail before any request is issued.

### Expected merge conflict zones

- LOW: additive auth/header helpers and root export.
- MEDIUM: the duplicated OpenAI client-auth setup removed from `api/openai-completions.ts` and
  `api/openai-responses.ts`.

## 2026-07-29 - Classify Anthropic credits_required as non-retryable billing exhaustion

### What changed and why

- `utils/retry.ts`: `NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN` gains `credits_required` and
  `credits are required`, the Anthropic Console credit-exhaustion wording (a 429 `rate_limit_error` whose
  details carry `error_code: credits_required`). The account stays dead until the user buys credits or raises
  the spend limit, so same-model retries can never recover it. Callers now route the shape through the
  hard-error fallback branch, where coding-agent pins the billing fallback, instead of burning the same-model
  retry budget (1 + maxRetries dead requests) on every turn.
- Coverage: `test/retry.test.ts` pins the verbatim incident message as non-retryable.

### Expected merge conflict zones

- LOW: two strings appended to the non-retryable pattern list in `utils/retry.ts`.

## 2026-07-29 - Classify zero-event provider stream stalls

### What changed and why

- `utils/retry.ts` exports `isProviderStreamStallError()`: matches the agent-loop stream-watchdog failures
  ("Idle timeout waiting for provider stream after <n>ms" and "Provider stream start timed out after <n>ms")
  on `stopReason: "error"` messages. The class stays
  retryable (unchanged), but callers can now distinguish "the provider accepted the request and sent zero events
  for the whole idle budget" from fast transient failures. agent-session uses it to escalate a second consecutive
  stall to the fallback chain instead of replaying the identical payload for the rest of the same-model budget
  (evidence: donated session 019fa8da-43ad-70b7-b01b-8f34f4d907f2, records 1906/1919, where a hung gateway made
  every replay burn the full 300s idle budget).
- Coverage: `test/retry.test.ts` pins the stall class against the idle-timeout message, `Request timed out.`,
  and aborted stop reasons.

## 2026-07-29 - Classify provider stream and transport timeouts precisely

### What changed and why

- `utils/retry.ts` exports `isProviderStreamStallError()` for the two anchored agent-loop watchdog
  messages and `isProviderTimeoutError()` for those stalls plus the exact `Request timed out` transport
  shape. The shared classifier accepts transport timeouts reported as `aborted` while rejecting incidental
  timeout text from commands, MCP servers, and extensions.
- `../test/retry.test.ts` pins the observed positive shapes, negative lookalikes, and stop-reason policy.

### Expected merge conflict zones

- LOW: additive classifiers beside `isRetryableAssistantError()` in `utils/retry.ts`; keep
  `isProviderStreamStallError()` aligned with PR #453 when the branches meet.

## 2026-07-29 - kimi-xtml text tool-call protocol + ToolCallFormat union

### What changed and why

- `ToolCallFormat` gains `"kimi-xtml"` (Kimi K3 native XTML channel syntax); `getToolCallFormat()` whitelist, protocol registry, compat docs, and middleware TESTING.md updated accordingly. Protocol implementation lives in `tool-call-middleware/protocols/kimi-xtml/` (markers, parse, format, stream); details in `tool-call-middleware/changes.md`.

## 2026-07-28 - Demote unavailable Anthropic tool references instead of failing the request

### What changed and why

- `api/anthropic-messages.ts` gains a final payload pass, `demoteUnavailableToolReferences()`, applied after
  `sanitizeUnsupportedNativeTools()` on every request. Anthropic rejects a request whose message history references
  a tool that is neither defined in `tools` nor discovered through a `tool_reference` block in the same request
  (`400 invalid_request_error: Tool reference '<name>' not found in available tools`). Sessions outlive their
  tools: an MCP server can be absent after a `senpi --session` resume, an extension can stop registering a tool,
  or an `onPayload` hook can strip a definition while the history still carries the call.
- The pass collects defined tool names and names discovered via `tool_reference` blocks (including replayed
  server-side tool-search results), then demotes offending `tool_use` blocks to plain text, demotes their
  `tool_result` blocks in lockstep (preserving the original result text), and strips `tool_reference` entries
  whose definition vanished — so neither the original 400 nor an orphan-pairing 400 can occur.
- `../test/anthropic-tool-reference-integrity.test.ts` drives the full request path offline through a fake
  Anthropic client: single and mixed-turn demotion, still-available tools kept intact, deferred
  `tool_reference` discovery kept intact, and dangling-reference stripping after a payload hook removes a
  definition.

### Expected merge conflict zones

- LOW: the request-finalization chain inside `createRequest()` in `api/anthropic-messages.ts`.
- LOW: new unexported helpers near the other payload sanitizers in `api/anthropic-messages.ts`.

## 2026-07-28 - Retry OpenAI-compatible stream failures before the first chunk

### What changed and why

- `utils/provider-retry.ts` now prefetches the first SDK stream result inside the existing bounded, abortable provider
  retry policy. A retry creates a fresh request only when stream consumption fails before any wire chunk can reach
  the public event stream.
- `api/openai-completions.ts` uses that prefetch wrapper for OpenAI-compatible providers. Once the first chunk exists,
  the stream is replayed exactly once and any later failure remains terminal, preventing duplicated text or tool
  effects.
- The exact property-less gateway error `Upstream error from DigitalOcean: stream failed` is recognized as transient;
  arbitrary property-less errors remain non-retryable.
- `../test/openai-completions-retry.test.ts` covers recovery, retry exhaustion, non-retryable failures, and the
  post-first-chunk no-retry boundary. The isolated mock-loop driver
  `.agents/skills/senpi-qa/scripts/mock-loop-stream-retry.mjs` proves the same behavior through the real source CLI.

### Expected merge conflict zones

- LOW: the request creation/retry block in `api/openai-completions.ts`.
- LOW: shared provider retry classification and stream-prefetch helper in `utils/provider-retry.ts`.


## 2026-07-28 - OpenAI catalog gains `-fast` Priority-processing variants

### What changed and why

- `scripts/generate-models.ts`: new `OPENAI_PRIORITY_TIER_MODEL_IDS` (the OpenAI pricing page's
  Priority table: gpt-5.6-sol/terra/luna, gpt-5.5, gpt-5.4(+mini), gpt-5.2, gpt-5.1, gpt-5(+mini),
  gpt-4.1 family, gpt-4o family, o3, o4-mini) plus an emission pass that clones each eligible
  `openai` provider model into `<id>-fast` with `upstreamModelId` set to the base id and
  `serviceTier: "priority"`. Emission runs after metadata application so variants clone fully
  processed base models, and is scoped to the direct OpenAI provider (Azure clones and
  `openai-codex` are intentionally excluded).
- `src/model.ts`: `Model` gains optional `upstreamModelId` and `serviceTier` so catalog entries
  can carry the alias/tier defaults that previously only models.json or extension model
  definitions could express. This removes the need to hand-maintain `-fast` pseudo-models in
  models.json for stock OpenAI models.
- Variant `cost` rates intentionally equal the base model's: `api/openai-responses.ts`
  `applyServiceTierPricing()` multiplies usage cost by the service-tier multiplier (2x, 2.5x for
  gpt-5.5) at request time, so raised catalog rates would double-count. The request path rewrites
  the wire id to `upstreamModelId`, preserving the multiplier's `model.id === "gpt-5.5"` branch.
- Regenerated catalog: 18 `openai` `-fast` variants added; other provider shards carry routine
  upstream models.dev/OpenRouter drift (e.g. nvidia +14/-2, fireworks +/-2) from regeneration.
- `../test/openai-fast-models.test.ts`: pins variant presence/eligibility, cloned fields, base
  cost rates, non-recursion, and Azure/Codex exclusion.

### Expected merge conflict zones

- LOW: additive set + emission block in `scripts/generate-models.ts`; additive optional fields on
  `Model` in `src/model.ts`; regenerated `src/providers/data/*` shards (regenerate on conflict).


## 2026-07-27 - Codex reasoning summary null omits the field instead of sending "off"

### What changed and why

- `api/openai-codex-responses.ts` `buildRequestBody()` and the internal
  `api/openai-codex-responses/reasoning.ts` normalizer: `reasoningSummary: null` now omits the `summary`
  field from `body.reasoning` instead of sending the literal string `"off"`. The Codex backend's
  `ReasoningSummaryParam` accepts only `concise`, `detailed`, and `auto`, so every request carrying
  `reasoningSummary: null` failed with a 400 `invalid_enum_value`. The coding-agent builtin compaction
  (`summarizationReasoningOptions()`) passes exactly that value to keep summarization turns cheap, which
  made compaction unusable on Codex models. The adapter now also preserves the shipped legacy union while
  normalizing `"off"` to omission and `"on"` to `"auto"`. These semantics match the sibling adapters and
  the official OpenAI Codex CLI reference client, whose `ReasoningSummary::None` is encoded as an absent
  `summary` field for both ordinary and compaction requests. Current upstream pi-mono instead maps null to
  `"auto"`, so this fork intentionally follows the official Codex wire contract rather than claiming
  upstream parity.
- An extension cannot fix this: the invalid value is produced inside the wire adapter's request builder,
  below every extension hook.
- `../test/openai-responses-thinking-matrix.test.ts`: pins both `buildRequestBody()` branches — explicit
  `reasoningEffort` and the thinking-off fallback — across null, legacy `"off"` / `"on"`, and `"auto"`.

### Expected merge conflict zones

- LOW: `api/openai-codex-responses.ts` `buildRequestBody()` reasoning block and the internal
  `api/openai-codex-responses/reasoning.ts` normalizer. Upstream writes
  `summary: options.reasoningSummary ?? "auto"` without the null branch; a clean upstream touch of these
  two object literals should resolve by keeping the null-omit spread.

## 2026-07-27 - Retry Cloudflare 522 connection timeouts

### What changed and why

- `utils/retry.ts` adds `"522"` to the retryable provider-error patterns. Cloudflare surfaces an
  origin that stopped responding as `Error: error code: 522` (Connection timed out); the message
  matched no retryable pattern, so a transient gateway timeout dead-ended the turn instead of going
  through the existing bounded retry policy like the other 5xx statuses (500/502/503/504/524).

### Expected merge conflict zones

- LOW: `utils/retry.ts` retryable provider-error status patterns.

## 2026-07-27 - OAuth loader export for extension providers

- `oauth.ts` now also exports `loadAnthropicOAuth` and `registerBundledOAuthFlowLoaders` from
  `auth/oauth/load.ts` (bundler-safe variable-specifier dynamic import preserved), so coding-agent
  extension providers can reuse the Anthropic PKCE machinery without reaching into package internals.

## 2026-07-27 - Typed Responses remote-compaction capability

- Extracted `OpenAIResponsesCompat` and `SessionAffinityFormat` from the oversized `types.ts` into
  `openai-responses-compat.ts` while preserving their public exports.
- Added `supportsRemoteCompactionV2` so verified OpenAI Responses proxies can explicitly advertise the native
  `compaction_trigger` request contract. Unknown custom proxies remain disabled by default.

## 2026-07-27 - Honor disabled Azure Responses prompt caching

### What changed and why

- `api/azure-openai-responses.ts`: requests with `cacheRetention: "none"` now omit `prompt_cache_key`,
  matching the OpenAI Responses adapter instead of silently enabling Azure prompt-cache affinity from the
  session id.
- `../test/azure-openai-base-url.test.ts`: pins both the existing 64-character cache-key clamp and the
  disabled-cache omission path.

### Expected merge conflict zones

- LOW: `api/azure-openai-responses.ts` request payload construction.

## 2026-07-27 - Treat Anthropic policy blocks as classifier refusals

### What changed and why

- `utils/stop-details.ts`: `isClassifierRefusal()` now accepts typed refusal/sensitive details on mixed
  `toolUse` stops, matching Anthropic streams that finish with a policy block after emitting a tool call.
- The same helper recognizes Anthropic's legacy policy-block error text when a gateway omits typed
  `stopDetails`, while requiring the provider's full restrictions-and-Usage-Policy signature so ordinary
  policy documentation errors remain non-refusals.
- This routes both shapes through the existing immediate pinned model-fallback path instead of executing the
  partial tool call or continuing on the refusing model.

## 2026-07-26 - Cross-model replay hardening (foreign signatures, id collisions, thinking turn shape)

### What changed and why

- `api/openai-responses-shared.ts`: `convertResponsesMessages()` and `backfillReasoningSignatures()` now parse
  persisted reasoning signatures through a guarded `parseReasoningSignature()` that requires a JSON payload with
  `type === "reasoning"`. Foreign providers store non-JSON markers (Kimi's `"reasoning_content"`) or opaque
  payloads (Anthropic thinking signatures) in the same `thinkingSignature` field; when such a block reaches the
  converter with same-model provenance (aliased/custom providers, corrupted session state), the previous
  unguarded `JSON.parse` threw a client-side `SyntaxError` or leaked an invalid item to the API. Unparseable or
  non-reasoning signatures now demote to plain assistant text (empty text is dropped), mirroring the cross-model
  policy in `transformMessages`.
- `utils/tool-call-id.ts`, `api/anthropic-messages.ts`, `api/bedrock-converse-stream.ts`, and
  `api/google-shared.ts`: the Anthropic-compatible adapters now share one collision-safe id normalizer. Over-long
  ids keep a readable prefix plus a `shortHash` of the full id instead of blind 64-char prefix truncation. OpenAI
  Responses tool ids run 450+ chars, and two distinct ids sharing a 64-char prefix previously collapsed into
  duplicate tool ids in Bedrock/Google even after the Anthropic Messages fix, corrupting tool-result pairing.
- `api/anthropic-messages.ts` `buildParams()`: when a thinking-enabled request's final assistant turn contains
  `tool_use` but no leading thinking block — the normal outcome of replaying Kimi/OpenAI history, whose thinking
  demotes to text or drops — thinking is disabled for that request instead of failing with Anthropic's "final
  assistant message must start with a thinking block" 400 on every turn. Adaptive families that reject
  `thinking.type: "disabled"` use the existing valid fallback (`thinking` omitted plus
  `output_config.effort: "low"`).
- `../test/openai-responses-foreign-signature.test.ts`, `../test/anthropic-cross-model-history.test.ts`,
  `../test/bedrock-convert-messages.test.ts`, and `../test/google-shared-tool-call-id.test.ts`: cover foreign
  signature demotion, genuine reasoning-item replay, cross-adapter collision freedom, and both legal
  thinking-degradation wire forms.

### Expected merge conflict zones

- MEDIUM: `api/openai-responses-shared.ts` thinking/text branches of `convertResponsesMessages()` (text emission
  is now a shared `pushAssistantText` closure) and `backfillReasoningSignatures()`.
- LOW: `utils/tool-call-id.ts`, the three adapter imports/call sites, and the thinking-config block of
  `api/anthropic-messages.ts` `buildParams()`.

## 2026-07-27 - Export string-based transient-error classifier

### What changed and why

- `utils/retry.ts` now exports `isRetryableErrorMessage(errorMessage: string)` and `isRetryableAssistantError`
  delegates to it. Callers that hold a thrown `Error` instead of an `AssistantMessage` (the compaction
  extension's blocking summarization path) need the same transient-vs-terminal classification to decide
  between degrading gracefully and surfacing loudly. No pattern changes; classification behavior is identical.

### Expected merge conflict zones

- LOW: `utils/retry.ts` around `isRetryableAssistantError`.

## 2026-07-26 - Retry transient Codex upstream websocket failures

### What changed and why

- `utils/retry.ts` classifies `upstream_unavailable` provider errors as transient so the existing bounded retry policy
  retries Codex websocket proxy disconnects such as `ConnectionClosedOK`.
- The retry classifier and coding-agent event-contract tests pin the exact reported error through the existing retry
  lifecycle rather than introducing provider-specific retry behavior.

### Expected merge conflict zones

- LOW: `utils/retry.ts` transient transport error patterns.

## 2026-07-26 - Repair unpaired Anthropic server-tool blocks and let the pairing 400 retry

### What changed and why

A session died permanently with a 400 `invalid_request_error` reading "`web_search` tool use with id
`srvtoolu_...` was found without a corresponding `web_search_tool_result` block". The assistant turn had persisted two
`server_tool_use` (`web_search`) provider-native blocks and no result blocks - the stream ended
between the search call and its result - and every later request replayed the unpairable halves, so
the session could never recover on its own.

Anthropic validates that each `server_tool_use` is followed, inside the same assistant message, by
its matching `*_tool_result`, and rejects the mirror case too (a result whose `server_tool_use` is
missing).

- `api/anthropic-messages.ts`: assistant conversion now repairs the pairing across the whole
  conversation, not only inside the server-side-fallback boundary. `collectProviderNativeToolPairing`
  walks the conversation in order, tracking which server-tool uses are still resumable: a use answered
  by a result in its own or the next assistant message replays (the deferred-continuation shape the API
  documents); a pending use survives only tool results, because user text, a tool result that registers
  deferred tool names (whose references serialize sibling text after the results), or another
  assistant turn all close the turn; and a blank user message closes nothing because it serializes to
  nothing. Only the unpairable halves are dropped — a closed use and a result whose use is nowhere.
  The predicate covers the `mcp_tool_use` shape for when those blocks become replayable. Paired blocks,
  `fallback`, and `container_upload` replay byte-for-byte as before, so `encrypted_content` fidelity is
  untouched.
- `utils/retry.ts`: the pairing-error wording ("was found without a corresponding", anchored on the
  opening backtick of the result block name) joins the retryable provider-error patterns.
  The repaired history means the retried request is valid, so the session self-heals through the
  existing retry path; if it keeps failing, the error now also reaches the model-fallback chain
  instead of dead-ending the turn.
- `test/anthropic-web-search-replay-encryption.test.ts`: the byte-fidelity fixture gained the
  `server_tool_use` its result belongs to. The assertion is unchanged - the fixture was simply not a
  shape Anthropic can accept.

## 2026-07-26 - Preserve persisted freeform identity when replaying OpenAI Responses calls (#256)

### What changed and why

- `api/openai-responses-shared.ts`: custom Responses calls with no server item id now persist the shared
  `CUSTOM_TOOL_CALL_ITEM_ID_SENTINEL` (`"custom"`) and recover their `custom_tool_call` /
  `custom_tool_call_output` wire types from that evidence. The recovery uses the existing freeform input
  serializer, preserving raw `apply_patch` text during no-tool compaction and model/API replay. It never sends
  the sentinel as an item `id`.
- Active grammar metadata remains the higher-fidelity source when it is available: it continues to choose its
  named input property and retain real custom-call ids, while a sentinel still removes the invalid synthetic id.
- Focused AI and compaction wiremock tests pin raw-input round trips, matching custom result types, model-switch
  preservation, grammar precedence, and the no-invalid-id guard.

This deliberately diverges from upstream's #271 crash-only repair. That patch omitted the invalid sentinel id
but downgraded a historical freeform call to JSON `function_call` when the current request had no tool definitions.
Senpi's compaction path intentionally omits those definitions, so preserving the persisted freeform type is required
for type fidelity and byte-identical patch replay.

### Why extension system couldn't handle this

The persisted tool-call identity is decoded while constructing the provider request in `packages/ai`; extensions only
see the already-normalized context and cannot restore the Responses wire item type.

### Expected merge conflict zones

- HIGH: upstream owns `api/openai-responses-shared.ts`'s `convertResponsesMessages()` tool-call and tool-result
  branches and rewrote the same hunk in #271. Future upstream syncs will collide here; retain sentinel recovery,
  raw-input serialization, and the no-`custom`-id invariant when resolving.

## 2026-07-25 - Thinking-off actually disables reasoning; wire-exact effort ladders across adapters

### What changed and why

Turning thinking **off** silently kept paid reasoning on for several model families, and several
effort ladders degraded a requested level to a weaker wire value. Both are fixed adapter-side; the
generated catalog only gained one compat fact.

Wire truth was established by probing the live Anthropic Messages endpoint before any edit
(7 families x `thinking:{type:"disabled"}`, plus pin/display controls, `max_tokens: 16`):

| probe | result |
|---|---|
| `thinking:{type:"disabled"}` on opus-4-6 / 4-7 / 4-8 / 5, sonnet-4-6 / 5 | **200** - true disable works, kept as-is |
| `thinking:{type:"disabled"}` on `claude-fable-5` | **400** `"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified` |
| no `thinking` + `output_config:{effort:"low"}` on fable-5 / opus-5 | **200** (with and without an effort beta header) |
| `thinking:{type:"adaptive",display:"summarized"}` on opus-4-6 | **200** |

- `api/anthropic-messages.ts`: the thinking-off branch no longer silently omits the thinking field
  for adaptive families that reject `disabled`. Families that accept `disabled` keep sending it;
  families that cannot (encoded as `compat.supportsDisabledThinking: false`) now send **no** thinking
  block plus `output_config:{effort:"low"}`, because the API defaults to adaptive thinking when the
  field is absent - previously "off" billed full reasoning.
- `api/anthropic-messages.ts`: `ADAPTIVE_THINKING_MODEL_MARKERS` gained `opus-4-8`, `opus-5`,
  `sonnet-5`, `fable-5`, so models without the `forceAdaptiveThinking` compat pin (custom
  `models.json` entries, third-party gateways) get adaptive effort control instead of a
  budget-token request. `mapThinkingLevelToEffort` now floors the extended levels at the adaptive
  ladder's top tier via `NATIVE_XHIGH_EFFORT_MODEL_MARKERS`: `xhigh` -> native `xhigh` where the
  family has it, otherwise `max`; `max` -> `max` always. It previously returned `high` for
  everything except Opus 4.6/4.7, so a map-less Sonnet 4.6/5, Opus 4.8/5 or Fable 5 silently
  under-thought at `high`.
- `api/bedrock-converse-stream.ts`: `buildAdditionalModelRequestFields` returned `undefined` for a
  thinking-off turn, which let every adaptive Claude family on Bedrock fall back to the adaptive
  default. It now sends `thinking:{type:"disabled"}`, or `output_config:{effort:"low"}` for families
  that reject `disabled`; budget-based Claude still sends nothing (extended thinking is opt-in
  there). Its effort ladder got the same `xhigh`/`max` floor fix.
- `api/anthropic-messages.ts`: the "cannot disable thinking" fact is owned by code as well as the
  catalog (`DISABLED_THINKING_REJECTING_MODEL_MARKERS` + `cannotDisableThinking()`). `models.json`
  entries and third-party gateway rows carry no generated compat, so a custom Fable/Mythos model
  would otherwise take the `disabled` branch and get the probe-confirmed 400.
- `api/bedrock-converse-stream.ts`: `supportsAdaptiveThinking` and `supportsNativeXhighEffort` now
  include `opus-5`. Bedrock Opus 5 was classified as budget-based, so it sent
  `thinking:{type:"enabled",budget_tokens}` instead of adaptive + `output_config.effort`, and a
  thinking-off turn sent nothing at all and fell back to adaptive. It also gained the same
  family-marker check so application inference profiles and custom Fable rows never receive
  `disabled`.
- `models.ts` `supportsXhigh`: recognizes `gpt-5.6`, `opus-5`, `sonnet-5` and `fable-5`.
- `api/openai-completions.ts`: added the missing no-map fallback ladders (Kimi K3 `low/high/max`,
  DeepSeek and GLM 5.2 `high/max`, OpenRouter DeepSeek `high`-only, MiMo `minimal->low` /
  `xhigh->high`, Ollama `low/medium/high/max`) and made an explicit catalog `null` suppress the wire
  effort instead of forwarding the raw requested value. Applied consistently to `streamSimple`, every
  value-bearing `thinkingFormat` branch, and chat-template effort kwargs.
- `api/openai-responses.ts`, `api/azure-openai-responses.ts`, `api/openai-codex-responses.ts`:
  explicit `max: "max"` is preserved for GPT-5.6 instead of being clamped, an explicit
  `thinkingLevelMap` `null` wins for direct adapter options (including summary-default resolution),
  and Codex sends its catalog-directed off sentinel when agent-level off arrives as omitted reasoning.
- `api/google-generative-ai.ts`, `api/google-vertex.ts`: a runtime thinking-off request fell through
  to an *enabled* reasoning form (worst case `thinkingBudget: 24576` with `includeThoughts: true` on
  Gemini 2.5 Flash). Both `streamSimple` paths now route off to the adapter's disabled form.
  `api/mistral-conversations.ts` was audited and needed no change: off provably cannot reach the
  `?? "high"` fallback.
- `scripts/generate-models.ts`: Fable 5 on `anthropic-messages` is now encoded as
  `compat.supportsDisabledThinking: false` instead of `thinkingLevelMap.off: null`. Both express
  "never send `thinking.type: disabled`", but the compat form keeps `off` a **selectable** level, so
  the UI can offer off and the provider pins the cheapest effort. Bedrock/Converse Fable rows keep
  `off: null` unchanged. Regenerated data therefore differs only in those fable-5 rows (plus one
  incidental OpenRouter price refresh).

### Known limitation (deliberate)

For Fable 5 the API exposes **no** true off switch: `thinking.type: "disabled"` is rejected and an
absent thinking field means adaptive. `off` therefore maps to the cheapest adaptive effort rather
than zero reasoning. That is strictly better than the alternatives - before this change `off` was
hidden and the level clamped to the lowest selectable tier, which produced the *same* wire effort
while labelling it `minimal`. The level stays labelled `off` because it is the cheapest reasoning the
model can be asked for, and no other senpi surface can promise more.

### Why extension system couldn't handle this

The thinking-off wire shape, the effort ladder floors and the beta/compat gating all live inside the
provider request builders in `packages/ai`, below any extension-visible surface.

## 2026-07-23 - Session-scoped provider resolution via node-only AsyncLocalStorage subpath

### What changed and why

- New node-only subpath module `packages/ai/src/node/provider-scope.ts`, exported as
  `@earendil-works/pi-ai/node/provider-scope`. It owns an `AsyncLocalStorage<ProviderScope>` plus
  `runWithProviderScope` and `bindToProviderScope(fn)` (explicit callback binding for EventEmitter/
  watcher callbacks, because EventEmitter does not propagate ALS from registration time).
  `ProviderScope` carries `active|closed` state and a per-scope overlay `Map`.
- `api-registry.ts` stays browser-neutral: a synchronous scope-accessor install hook (default: none)
  lets the RPC host install a strict accessor. With no accessor installed, every classic path is
  byte-identical (browser smoke pins this). The faux fast path (`getRegisteredFauxProvider` short-circuit
  at `api-registry.ts:78-82`) consults the active scope first or is scope-keyed.
- Scope-aware behavior for ALL registry operations: `getApiProvider`, `getApiProviders`,
  `registerApiProvider`, `unregisterApiProviders`, `clearApiProviders`, `resetApiProviders`
  (`compat.ts:143-147`). In an active scope, resolution = `session overlay → immutable builtin set` —
  NEVER the mutable legacy global. After `close_session` the scope is closed and any lookup/mutation
  through it throws (no silent fallback). Reaching provider lookup in multi-session mode with NO
  active scope throws a diagnostic error (fail-loud, not fall-through).
- The image-provider registry is scoped identically to the API-provider registry (same overlay →
  immutable-builtins-only resolution, same closed-scope throws semantics).
- Builtin identity semantics preserved: `getBuiltinProviderForModel` (`compat.ts:127-140,173`)
  keeps reference-identity routing in `getBuiltinProviderForModel` / `builtinApiProviderInstances`
  while a scope holds unrelated overlay entries.
- Browser-safety approach: the synchronous scope-accessor install hook keeps `packages/ai` root and
  compat exports browser-neutral; the only `node:async_hooks` import lives behind the node-only
  subpath. Root/compat stay browser-safe; `npm run check:browser-smoke` stays green.

### What future refactors must NOT break

- Overlay → immutable-builtins-only resolution in an active scope; NEVER fall back to the mutable legacy
  global in multi-session mode.
- A closed scope must throw on any lookup/mutation (no silent fallback).
- Builtin identity semantics (`builtinApiProviderInstances` reference-identity routing in
  `getBuiltinProviderForModel`) must keep working while a scope holds unrelated overlay entries.
- Root/compat exports must stay browser-safe: no `node:async_hooks` (or any node-only) import reachable
  from root or compat; the scope accessor ships only from the node-only subpath.
- No new dependencies (`node:async_hooks` is built-in).

### Expected merge conflict zones

- MEDIUM: `api-registry.ts` scope-accessor install hook + the faux fast-path short-circuit.
- LOW: `compat.ts` builtin identity routing (additive guard only).

## 2026-07-22 - Drop tool results of errored/aborted assistants in transformMessages

### What changed and why

- `api/transform-messages.ts`: the pairing pass now records the toolCall ids of every assistant it skips
  because `stopReason === "error" | "aborted"` into `droppedCallIds` (mirroring the existing skip condition),
  and the emit loop no longer emits a toolResult whose `toolCallId` is in that set — unless the id is also
  declared by a kept assistant (`nextToolCallIndexById`), which still pairs through the normal windows.
  Previously the errored assistant was dropped while its result (a real one, or a placeholder synthesized by
  the compaction pipeline's `repairOrphanedToolResults`) survived, so the request carried a `role:"tool"`
  message whose `tool_call_id` no assistant declared; strict providers (apitopia/kimi openai-completions)
  reject it with `400 tool_call_id ... is not found`, permanently bricking compaction for the session.
  True orphans (id declared nowhere) and results of kept assistants are unchanged, and kept assistants'
  unanswered calls still get the synthetic "No result provided" result.
- `utils/tool-pair-repair.ts`: `repairOrphanedToolResults` no longer synthesizes placeholder results for
  toolCalls declared by errored/aborted assistants (defense in depth; those assistants are dropped by
  `transformMessages` anyway). The coding-agent compaction copy received the identical guard; the two
  files remain verbatim copies.
- `../test/transform-messages-errored-tool-results.test.ts`: drop cases (errored + real result, aborted +
  synthesized placeholder), preservation cases (kept pair, "No result provided" synthesis, true orphan
  passthrough), and an id re-declared by a later kept assistant. `../test/tool-pair-repair.test.ts`: no
  synthesis for errored/aborted assistants, synthesis kept for a kept re-declaration.

### Expected merge conflict zones

- LOW: `api/transform-messages.ts` second-pass pairing loop and toolResult emit branch;
  `utils/tool-pair-repair.ts` dangling-call synthesis loop.

## 2026-07-21 - OpenAI Responses provider-native completion reconciliation

### What changed and why

- `api/openai-responses-shared.ts`: opaque output items now occupy the existing output-index slot map, so
  `response.output_item.done` replaces the partial `added` payload with the final provider item. OpenAI web-search
  actions commonly arrive only on the done frame; retaining the added placeholder lost the final query/action before
  session persistence and app-server projection.
- `../test/openai-responses.provider-native.test.ts`: covers an action-less added web-search item followed by the
  completed done item.

### Expected merge conflict zones

- LOW: `api/openai-responses-shared.ts` output-slot creation and `response.output_item.done` finalization.

## 2026-07-22 - Omit non-"fc" item ids when replaying tool calls as function_call

- `api/openai-responses-shared.ts` `convertResponsesMessages()`: a `function_call` input
  item's `id` is now emitted only when it begins with "fc" — the Responses API rejects
  anything else (`Invalid 'input[N].id': 'custom'. Expected an ID that begins with 'fc'.`).
  Custom tool calls are stored with the `<call_id>|custom` sentinel (a `custom_tool_call`
  output carries no server-issued item id), so replaying them without their freeform tool
  registered — compaction summarization strips `freeform` from its tool list — previously
  sent `id: "custom"` and hard-failed the whole request, tripping the compaction circuit
  breaker. Omitting mirrors the existing different-model pairing-validation skip;
  server-issued `fc_…` ids still replay unchanged.
- `../test/openai-responses-custom-tools.test.ts`: sentinel omission plus a pin that
  genuine `fc` ids survive same-model replay.

### Expected merge conflict zones

- LOW: `convertResponsesMessages` function_call emission branch.

## 2026-07-20 - Typed classifier stop details

- Added optional typed refusal/sensitive stop details to assistant messages, preserving Anthropic classifier outcomes through streaming and faux provider errors.
- Exported `isClassifierRefusal` and excluded classifier outcomes from generic same-model retry classification.


## 2026-07-20 - Live tool-result pairing by source position + Retry unsigned Anthropic thinking replay as text

### What changed and why

#### Live tool-result pairing by source position

- `api/transform-messages.ts`: live history normalization now indexes tool results and replayable tool calls by
  source position. Each tool call consumes the earliest still-unconsumed matching result after its declaring
  assistant, emits that result adjacent to the assistant turn, or emits exactly one synthetic error result.
  A repeated ID establishes a new pairing window, so a delayed result cannot attach to an earlier call or be
  replayed twice across an intervening user turn. Aborted and errored assistant turns remain excluded.
- `../test/transform-messages-copilot-openai-to-anthropic.test.ts`: covers delayed normalized results across a
  user turn, partial multi-call results, reused IDs with prior orphaned results, trailing unresolved calls, and
  Anthropic-required tool-result adjacency.

#### Retry unsigned Anthropic thinking replay as text

- `AnthropicMessagesCompat.unsignedThinkingReplay` now explicitly controls replay of thinking blocks without a usable signature. The safe default is text replay for first-party/signing endpoints; the legacy `allowEmptySignature` flag remains an alias for Kimi-compatible empty-signature replay.
- When an endpoint rejects an empty replay signature with a pre-stream HTTP 400 containing `Invalid signature in thinking block`, the Anthropic adapter rebuilds the request with unsigned thinking demoted to text and retries exactly once. That learned fallback is scoped to the session, base URL, and model ID, without mutating shared `Model` metadata.
- Signed and redacted thinking replay remains byte-for-byte/native-state preserving. Non-signature 400s and errors after SSE content begins do not retry.

### Files modified

- `api/transform-messages.ts`
- `../test/transform-messages-copilot-openai-to-anthropic.test.ts`
- `types.ts`
- `api/anthropic-messages.ts`
- `../test/anthropic-unsigned-thinking-replay.test.ts`

### Expected merge conflict zones

- LOW: `api/transform-messages.ts` second-pass tool-result normalization.
- LOW: `AnthropicMessagesCompat` replay options and Anthropic request creation.
## 2026-07-17 - Video input modality for Kimi K3 (kimi-coding)

### What changed and why

- `types.ts`: `Model.input` union gains `"video"`. No new message content type: video payloads ride the
  existing `ImageContent` block with a `video/*` mimeType (helper `isVideoMimeType()` exported) to keep the
  message contract and the upstream merge surface unchanged.
- `api/transform-messages.ts`: `downgradeUnsupportedImages` now first replaces video-mime blocks with a
  placeholder for models without the `"video"` modality (user and toolResult content), then applies the
  existing image downgrade. Prevents cross-model replay from sending video blocks to providers that reject
  them.
- `api/anthropic-messages.ts`: `convertContentBlocks` and the user-message block mapping serialize
  video-mime blocks as `{type:"video", source:{type:"base64", media_type, data}}` — the wire shape the
  Kimi Anthropic-compatible endpoint accepts (verified against MoonshotAI/kimi-code kosong anthropic
  provider). The block is not in the official SDK union, so it is cast like the existing `tool_reference`
  escape hatch.
- `scripts/generate-models.ts` + regenerated `providers/kimi-coding.models.ts`: kimi-coding `k3` declares
  `input: ["text", "image", "video"]`.

### Files modified

- `types.ts`
- `api/transform-messages.ts`
- `api/anthropic-messages.ts`
- `../scripts/generate-models.ts`
- `providers/kimi-coding.models.ts` (generated)
- `../test/transform-messages-video.test.ts`

### Expected merge conflict zones

- LOW: `types.ts` `Model.input` union and `ImageContent` comment.
- MEDIUM: `api/anthropic-messages.ts` `convertContentBlocks` / `convertToolResult` if upstream reworks
  content serialization.
- LOW: `api/transform-messages.ts` `downgradeUnsupportedImages`.

## 2026-07-19 - Name-preserving apply_patch replay characterization and policy coverage

### What changed and why

- Added characterization + policy-table coverage for replaying mixed edit/apply_patch
  history across every KnownApi: Responses targets serialize a historical apply_patch call
  as `custom_tool_call` when a freeform apply_patch is declared and as `function_call`
  (name preserved, JSON `{input}` args) otherwise; Completions/Anthropic/Google/Bedrock/
  Mistral/pi-messages keep the stored name with native JSON-typed call entries.
- No production change was required: existing converters already implement the
  name-preserving truth table. Tests pin both branches plus per-API shape assertions so a
  future regression cannot silently rename or drop historical patch calls.

## 2026-07-17 - Truncation-recovery contract for ToolCall and toolcall_end

### What changed and why

- Truncated text-protocol tool calls were silently dropped, leaked as raw markup, or executed from a
  stale argument snapshot, with no public signal distinguishing a finalized (executable) call from
  one the parser could only partially recover. Consumers had no contract for "this tool call is
  incomplete; do not execute it; ask the model to retry."
- `ToolCall` gains optional `incomplete?: true` and `errorMessage?: string`, set by the text tool-call
  middleware when a truncated call could not be recovered. Carriers of `incomplete` MUST NOT be
  executed; they are surfaced as a failed tool result so the model re-issues the call next turn.
- The `toolcall_end` member of `AssistantMessageEvent` is redefined from an implicit "complete" to
  "finalized": a `toolcall_end` is executable iff `incomplete !== true`. Flagged ends still terminate
  the call (so the wrapper never holds a dangling partial) but are not executable. This is the
  release-note surface for the redefinition.
- `ToolCallFormat` gains `"morph-xml"` as the canonical id; `"xml"` is retained as a deprecated alias
  resolving to the same protocol, so existing `models.json` configs and compiled consumers of
  `getProtocol("xml")` keep working without a runtime normalization that rewrites stored config
  values.
- Flagged dangling-call diagnostics always append `Re-issue the tool call with complete arguments.` to parser-provided error messages without duplicating a final period.
- `compat.ts` now publicly re-exports `getToolCallFormat`, `getProtocol`, `transformContext`, and `wrapStreamWithToolCallMiddleware` for composed providers that need the text tool-call middleware.

### Files modified

- `types.ts` (`ToolCall`, `AssistantMessageEvent.toolcall_end`, `OpenAICompletionsCompat.toolCallFormat` doc)
- `tool-call-middleware/types.ts`, `tool-call-middleware/index.ts`, `tool-call-middleware/context-transformer.ts`
- `../test/tool-call-middleware/context-transformer.test.ts`, `../test/tool-call-middleware/stream-integration.test.ts`

### Why the higher-level extension system couldn't handle this alone

- The canonical `ToolCall` shape, the `toolcall_end` event contract, and the `ToolCallFormat` union
  are all exported from `pi-ai` and consumed by standalone `pi-ai` clients before any coding-agent
  extension runs.

### Expected merge conflict zones

- LOW: `types.ts` around the `ToolCall` and `AssistantMessageEvent` declarations.
- LOW: `tool-call-middleware/types.ts` `ToolCallFormat` union and `toolcall_end` variant.

## 2026-07-17 - Moonshot root object-union compatibility

### What changed and why

- `utils/tool-schema-compat.ts`: Moonshot normalization now flattens a root `anyOf`/`oneOf` of object parameter
  shapes into one `type: "object"` schema. Properties are merged and only branch-common required fields remain.
  Kimi rejects a root combiner without `type`, but also rejects a sibling root `type` beside that combiner, so the
  union must be represented as a permissive object at the function-parameter boundary.
- `../test/openai-completions-tool-schema-compat.test.ts`: covers the real `click`-style coordinate/index union and
  the final post-hook request payload.

### Why the higher-level extension system couldn't handle this alone

- The provider adapter owns the final wire schema after payload hooks and is the only layer shared by direct
  Moonshot requests and custom Moonshot-compatible gateways.

### Expected merge conflict zones

- LOW: `utils/tool-schema-compat.ts` if upstream expands its provider-specific schema normalizers.

## 2026-07-17 - Final-boundary Moonshot tool schema normalization

### What changed and why

- `api/openai-completions.ts`: re-normalizes function tool parameter schemas after `onPayload` and immediately before
  the OpenAI SDK request. Payload hooks can replace or inject tools after the ordinary `convertTools` pass; those tools
  previously bypassed the Moonshot/MFJS compatibility transform and could retain a parent `type` beside `anyOf`, which
  Moonshot rejects with HTTP 400.
- `../test/openai-completions-tool-schema-compat.test.ts`: captures the real HTTP request and locks the post-hook wire
  shape.

### Why the higher-level extension system couldn't handle this alone

- `before_provider_request` is exposed through `onPayload`, so the provider adapter is the only layer that can validate
  the complete tool list after every hook has run.

### Expected merge conflict zones

- LOW: `api/openai-completions.ts` around the `onPayload` callback and final request submission.

## 2026-07-16 - Anthropic native web_search endpoint guard and server_tool_use input streaming

### What changed and why

- `types.ts`: added `AnthropicMessagesCompat.supportsWebSearch`. Default (resolved in
  `getAnthropicCompat`): true only for the first-party `api.anthropic.com` endpoint; compatible providers and
  provider overrides can
  opt in per model via `compat`.
- `api/anthropic-messages.ts`: `sanitizeUnsupportedNativeTools` now also strips hook-injected native `web_search_*`
  tools when the resolved compat does not support them, mirroring the existing native computer tool guard and the
  OpenAI Responses `web_search_preview` compat guard (2026-05-15). Anthropic-compatible endpoints such as kimi-coding
  execute the server-side search but reject the replayed `server_tool_use` / `web_search_tool_result` blocks on the
  next request (kimi-coding 400s with `tool_call_id is not found`), wedging the session. Named `tool_choice` is
  preserved when a same-name function fallback remains and removed only when the retained tool list no longer
  contains that choice.
- `api/anthropic-messages.ts`: same-model provider-native replay also drops web-search server-tool blocks
  (`server_tool_use` named `web_search` and `web_search_tool_result`) when the endpoint lacks `supportsWebSearch`.
  Sessions that already recorded such blocks against an incompatible endpoint were permanently wedged — every
  request replayed the rejected blocks; dropping the pair loses the searched context but unwedges the session.
- `api/anthropic-messages.ts`: streaming now accumulates `input_json_delta` for Anthropic's confirmed
  provider-native tool-use blocks (`server_tool_use` and beta `mcp_tool_use`) and merges the parsed input into the stored raw block at
  `content_block_stop` (or in the abort/error finalizer for interrupted streams). Previously the block kept the
  `content_block_start` snapshot (`input: {}`), so every same-model replay sent the server tool call with an empty
  input. Unknown and result-shaped blocks are never touched; their raw provider payload must remain verbatim.

### Files modified

- `types.ts`
- `api/anthropic-messages.ts`
- `../test/anthropic-native-web-search-compat.test.ts`
- `../test/anthropic-provider-native-replay.test.ts`
- `../test/anthropic-web-search-replay-encryption.test.ts`
- `../test/anthropic.provider-native.test.ts`
- (see also `../../coding-agent/src/core/changes.md` for the models.json compat schema entry)

### Why the higher-level extension system couldn't handle this alone

- Extensions can inject native `web_search_*` tools via `before_provider_request`; the final payload is only known
  after all hooks run, so the provider is the last reliable guard before SDK submission (same rationale as the
  OpenAI Responses guard). Provider-native block capture during streaming happens inside `pi-ai` before any
  extension sees the message.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` around `getAnthropicCompat`, `sanitizeUnsupportedNativeTools`, and the
  `content_block_delta` / `content_block_stop` streaming handlers.
- LOW: `types.ts` `AnthropicMessagesCompat` if upstream adds more compat flags.

## 2026-07-14 - Anthropic web search replay encrypted content correction

### What changed and why

- `api/anthropic-messages.ts`: same-model provider-native replay now preserves each nested `web_search_result` item's
  `encrypted_content` byte-for-byte before sending prior server-side web search results back in the next Anthropic
  request. The existing same-provider/api/model boundary, fallback pruning, and cross-model dropping behavior remain
  unchanged.
- Anthropic's current web-search contract requires `encrypted_content` to be passed back unmodified for multi-turn use.
  The July 8 stripping workaround was wrong under that contract: it discarded opaque provider-owned replay state after
  one observed 400, even though the raw session stored all seven encrypted fields and Senpi removed them during
  conversion.

### Files modified

- `api/anthropic-messages.ts`
- `../test/anthropic-provider-native-replay.test.ts`
- `../test/anthropic-web-search-replay-encryption.test.ts`

### Expected merge conflict zones

- LOW: `api/anthropic-messages.ts` around `sanitizeReplayableAnthropicProviderNativeBlock` and the provider-native
  replay path.

## 2026-07-06 - Anthropic server-side fallback replay contract

### What changed and why

- The server-side fallback beta (`server-side-fallback-2026-06-01`) emits a `fallback` content block mid-response when
  the serving model falls back (e.g. a `claude-fable-5` refusal replaced by the fallback model). Three fixes
  (2026-07-02 → 2026-07-06) make replaying such turns conform to the beta's contract:
  - `fallback` was added to `REPLAYABLE_ANTHROPIC_PROVIDER_NATIVE_TYPES`; dropping it on same-model replay mutated the
    latest assistant message's block sequence and the API rejected the next request of the turn with a 400
    `thinking … cannot be modified` error, wedging the session.
  - Blocks emitted before the final `fallback` marker belong to the discarded attempt and are now omitted on replay;
    replaying them verbatim left pre-boundary `tool_use` blocks without matching `tool_result`s, rejected with 400
    `tool_use ids were found without tool_result blocks`.
  - An unpaired pre-boundary `server_tool_use` (fallback interrupted the declined attempt before the server tool's
    result arrived) is also dropped; paired server-tool blocks and text still replay verbatim.

### Files modified

- `api/anthropic-messages.ts`
- `test/anthropic-provider-native-replay.test.ts`

### Why the higher-level extension system couldn't handle this alone

- Provider-native block replay filtering happens inside the Anthropic message transformer before any coding-agent
  extension can rewrite provider payloads.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` around `REPLAYABLE_ANTHROPIC_PROVIDER_NATIVE_TYPES` and the assistant-turn
  replay/filter path.
- LOW: `test/anthropic-provider-native-replay.test.ts` fixtures if upstream restructures replay tests.

## 2026-07-02 - Upstream provider metadata and Codex SSE transport sync

### What changed and why

- `api/openai-codex-responses.ts`: accepted upstream zstd request-body compression for Codex Responses SSE while
  preserving the fork's senpi-branded Codex headers, stale response handling, service-tier support, and thinking support.
- `utils/oauth/device-code.ts` and `utils/oauth/github-copilot.ts`: accepted delayed GitHub Copilot device-code polling
  and related OAuth cleanup.
- Provider model catalogs were refreshed for Copilot, Fireworks, OpenCode, Cloudflare AI Gateway, Bedrock, and related
  providers while retaining fork-specific model capability metadata such as `supportsXhigh`.

### Files modified

- `api/openai-codex-responses.ts`
- `providers/amazon-bedrock.models.ts`
- `providers/cloudflare-ai-gateway.models.ts`
- `providers/fireworks.models.ts`
- `providers/github-copilot.models.ts`
- `providers/opencode-go.models.ts`
- `providers/opencode.models.ts`
- `utils/oauth/device-code.ts`
- `utils/oauth/github-copilot.ts`

### Why the higher-level extension system couldn't handle this alone

- Codex SSE request compression, OAuth polling, and generated provider metadata all live inside `pi-ai` before
  coding-agent extensions can intercept a request or model catalog entry.

### Expected merge conflict zones

- MEDIUM: `api/openai-codex-responses.ts` around request body creation, zstd encoding, headers, and stream response
  handling.
- LOW: `utils/oauth/device-code.ts` around polling cadence and error handling.
- LOW: provider `*.models.ts` catalogs when upstream regenerates model metadata.

## 2026-05-19 - Cloudflare Anthropic computer tool guard

### What changed and why
- `providers/anthropic.ts`: Cloudflare Anthropic routes now strip hook-injected native `computer_*` tools after `onPayload`, while preserving supported native tools such as `bash_20250124` and `text_editor_20250124`.
- Computer-use beta request headers are removed only for routes/models that reject the native computer tool.
- Added a regression matching the CF runtime error where `computer_20250124` is not one of the accepted tool tags.

### Files modified
- `providers/anthropic.ts`
- `../test/anthropic-on-payload-headers.test.ts`

### Why the higher-level extension system couldn't handle this alone
- The failing payload can be introduced by `before_provider_request`; the provider adapter is the final point that sees the complete Anthropic request before SDK submission.

### Expected merge conflict zones
- LOW: native-tool sanitization helpers near request metadata extraction.

## 2026-05-18 - Anthropic protected thinking replay

### What changed and why
- `providers/anthropic.ts`: signed Anthropic `thinking` replay now forwards the stored text exactly as-is instead of running it through local surrogate sanitization. Anthropic treats signed and redacted thinking blocks as protected replay state; rewriting them can make the next tool-result request fail with `thinking` / `redacted_thinking` modification errors.
- `providers/transform-messages.ts`: same-model preserved provider-state blocks are now copied rather than shared, and redacted thinking remains same-model only. Cross-model transforms still drop opaque redacted thinking state.
- Added regressions for signed thinking replay, redacted thinking replay, immutable same-model transforms, cross-model redacted thinking dropping, and retry context behavior after a failed assistant turn.

### Files modified
- `providers/anthropic.ts`
- `providers/transform-messages.ts`
- `../test/anthropic-thinking-disable.test.ts`
- `../test/transform-messages-copilot-openai-to-anthropic.test.ts`
- `../../coding-agent/test/suite/regressions/0000-anthropic-partial-thinking-replay.test.ts`

### Why the higher-level extension system couldn't handle this alone
- Anthropic protected thinking is serialized inside `pi-ai`'s provider adapter after history transformation. Extensions and coding-agent retry logic cannot safely repair a signed block once the provider has normalized or shared it.

### Expected merge conflict zones
- LOW: `convertMessages()` signed/redacted thinking block serialization in `providers/anthropic.ts`.
- LOW: same-model `preserveProviderState` branches in `providers/transform-messages.ts`.

## 2026-05-15 - OpenAI Responses `web_search_preview` compat guard

### What changed and why
- `providers/openai-responses.ts`: after `onPayload` hooks run, custom OpenAI Responses endpoints now strip native `web_search_preview` / `web_search_preview_2025_03_11` tools, the matching `tool_choice`, and `web_search_call.action.sources` includes unless `compat.supportsWebSearchPreview` explicitly opts in. Official `api.openai.com` endpoints keep the existing default support.
- `types.ts`: added `OpenAIResponsesCompat.supportsWebSearchPreview` so custom providers can declare support when they really pass OpenAI-native Responses tools through.
- Added regression coverage for hook-injected native web search on a custom Responses endpoint and the explicit opt-in path.

### Files modified
- `providers/openai-responses.ts`
- `types.ts`
- `../test/openai-responses-web-search-compat.test.ts`

### Why the higher-level extension system couldn't handle this alone
- External or user extensions can add provider-native tools through `before_provider_request`; the final OpenAI Responses payload is only known after all hooks have run. The provider is the last reliable guard before SDK submission.

### Expected merge conflict zones
- LOW: `streamOpenAIResponses()` request construction immediately after the `onPayload` callback.
- LOW: `OpenAIResponsesCompat` if upstream adds more Responses compatibility flags.

## 2026-05-15 - Opus 4.6/4.7 unsupported native computer tool guard

### What changed and why
- `providers/anthropic.ts`: after `onPayload` hooks run, Opus 4.6 and 4.7 requests now strip Anthropic's legacy native `computer_20250124` tool and remove `computer-use-2025-01-24` from hook-added `anthropic-beta` request headers.
- Added a regression to cover extension-style payload mutation where a native computer tool is injected alongside another supported native tool. The supported tool and remaining beta header survive; the Opus-rejected computer tool does not reach the SDK request body.

### Files modified
- `providers/anthropic.ts`
- `../test/anthropic-on-payload-headers.test.ts`

### Why the higher-level extension system couldn't handle this alone
- External or user extensions can add provider-native tools through `before_provider_request`; the final provider payload is only known after all hooks have run. The Anthropic provider is the last reliable guard before SDK submission.

### Expected merge conflict zones
- LOW: `streamAnthropic()` request construction immediately after the `onPayload` callback.
- LOW: native-tool sanitization helpers near request metadata extraction.

## 2026-05-15 - Anthropic `onPayload` request headers

### What changed and why
- `providers/anthropic.ts`: when an `onPayload` hook returns request metadata fields (`headers` / `extra_body`), the provider now forwards string-valued `headers` through the Anthropic SDK request options and strips both metadata keys from the JSON request body.
- Added a regression test for native computer-use extensions that inject `computer_20250124` plus `anthropic-beta: computer-use-2025-01-24` from `before_provider_request`. Previously the tool reached Anthropic but the beta header did not, producing a 400 where `computer_20250124` was not among the accepted tool tags.

### Files modified
- `providers/anthropic.ts`
- `../test/anthropic-on-payload-headers.test.ts`

### Why the higher-level extension system couldn't handle this alone
- Extensions can mutate the provider payload via `before_provider_request`, but Anthropic SDK request headers are assembled inside `pi-ai`. The provider must explicitly lift hook-added header metadata into SDK request options after `onPayload` runs.

### Expected merge conflict zones
- LOW: `streamAnthropic()` request construction around the `onPayload` callback and SDK `messages.create()` options.

## 2026-05-11 - Senpi-branded Codex originator and User-Agent

### What changed and why
- `providers/chatgpt-subscription-responses.ts` `buildBaseCodexHeaders()`: changed the hardcoded `originator: "pi"` and the `User-Agent: "pi (…)"` string to `"senpi"`. Upstream chose `"pi"` as the Codex CLI identity; this fork's identity is `senpi`.
- `auth/oauth/chatgpt-subscription.ts` `createAuthorizationFlow()`: changed the default `originator` parameter from `"pi"` to `"senpi"` and updated the JSDoc on `loginChatGptSubscription` accordingly. Callers can still pass their own originator.

### Files modified
- `providers/chatgpt-subscription-responses.ts`
- `auth/oauth/chatgpt-subscription.ts`

### Why the higher-level extension system couldn't handle this alone
- The originator + User-Agent headers are built inside `pi-ai`'s Codex header constructor before the request leaves the library. Coding-agent extensions cannot intercept the header construction step.

### Expected merge conflict zones
- LOW: `buildBaseCodexHeaders()` body (3 lines) and the `originator` default parameter / JSDoc in `createAuthorizationFlow`.

## 2026-05-07 - Shared tool pair repair utility for compaction-safe histories

### What changed and why
- Added `utils/tool-pair-repair.ts` to centralize bidirectional `tool_use`/`tool_result` pairing repair in `pi-ai`.
- This supports both coding-agent builtin extensions and external `pi-ai` consumers that do not load coding-agent extensions.

### Files modified
- `utils/tool-pair-repair.ts`

### Why the higher-level extension system couldn't handle this alone
- Extension code alone is not available to standalone `pi-ai` consumers, so this shared history repair logic must live in `pi-ai`.

### Expected merge conflict zones
- None expected; this is a new additive utility file.

## 2026-04-13 - OpenAI Responses custom tool support for apply_patch

### What changed and why
- Added optional freeform grammar metadata to tool types.
- Updated OpenAI Responses request/history conversion to emit and preserve `custom` / `custom_tool_call` / `custom_tool_call_output` items for freeform tools. This was required to match Codex GPT `apply_patch` behavior instead of falling back to JSON function tools.

### Files modified
- `types.ts`
- `providers/openai-responses-shared.ts`

### Why the higher-level extension system couldn't handle this alone
- `pi-ai` only serialized tools as JSON function definitions for OpenAI Responses, so a builtin extension could not produce Codex-compatible freeform tools without core provider changes.

### Expected merge conflict zones
- `types.ts` tool model
- `providers/openai-responses-shared.ts` request/stream conversion paths

## 2026-04-17 - Claude Opus 4.7, `max` effort alignment, and extra-body pass-through

### What changed and why
- Added `claude-opus-4-7` to the Anthropic provider and its Bedrock cross-region profiles (`anthropic.*`, `us.*`, `eu.*`, `global.*`) so Opus 4.7 is available in the catalog and survives re-runs of `generate-models.ts`.
- Expanded `supportsXhigh()` to include `opus-4-7` / `opus-4.7` so the coding agent exposes `xhigh` for Opus 4.7 users.
- Expanded Anthropic adaptive thinking support (`supportsAdaptiveThinking`) and effort mapping (`mapThinkingLevelToEffort`) for Opus 4.7:
  - `xhigh` now maps to the native `"xhigh"` effort on Opus 4.7 (Anthropic's newest tier).
  - `xhigh` still maps to `"max"` on Opus 4.6 (Opus 4.6 doesn't support native `xhigh`).
  - Added explicit `"max"` to the effort type union for future use.
  - Cast through `{ output_config?: { effort: AnthropicEffort } }` while the @anthropic-ai/sdk upstream types still reject `"xhigh"`.
- Added `StreamOptions.extraBody` for pass-through custom body fields (matches opencode's provider `options`). Wired it through every builtin provider's payload builder (`anthropic`, `openai-responses`, `openai-completions`, `azure-openai-responses`, `openai-codex-responses`, `mistral`, `google`, `google-vertex`, `google-gemini-cli`, `amazon-bedrock`). A shared `applyExtraBody` helper and per-provider reserved-key sets live in `providers/simple-options.ts` to prevent users from overriding provider-managed fields (model id, messages, stream flag, etc.).

### Files modified
- `types.ts`
- `models.ts`
- `models.generated.ts`
- `providers/simple-options.ts`
- `providers/anthropic.ts`
- `providers/openai-responses.ts`
- `providers/openai-completions.ts`
- `providers/azure-openai-responses.ts`
- `providers/chatgpt-subscription-responses.ts`
- `providers/mistral.ts`
- `providers/google.ts`
- `providers/google-vertex.ts`
- `providers/google-gemini-cli.ts`
- `providers/amazon-bedrock.ts`
- `scripts/generate-models.ts`

### Why the higher-level extension system couldn't handle this alone
- Extra-body pass-through has to be read inside each provider's payload builder (pre-`onPayload` hook), which is core `pi-ai` territory; a coding-agent extension cannot reach into `pi-ai` provider payload construction.
- Opus 4.7 model metadata, xhigh capability detection, and adaptive thinking effort mapping all live in `pi-ai`. `supportsXhigh`, `supportsAdaptiveThinking`, and `mapThinkingLevelToEffort` are internal to the provider.
- Running `generate-models.ts` regenerates `models.generated.ts` from models.dev; the Opus 4.7 override block ensures the upstream regeneration keeps our entry.

### Expected merge conflict zones
- `scripts/generate-models.ts` Opus override block (lines around the 4.6 additions).
- `src/providers/anthropic.ts` `supportsAdaptiveThinking` / `mapThinkingLevelToEffort` / `AnthropicEffort`.
- `src/providers/simple-options.ts` (new exports).
- `src/models.ts` `supportsXhigh`.
- `src/types.ts` `StreamOptions.extraBody`.

## 2026-04-17 (follow-up) - "max" ThinkingLevel + tightened extraBody guards + Google `config` merge

### What changed and why
- Exposed Anthropic's native `"max"` effort through the unified `ThinkingLevel` surface: `StreamOptions.reasoning: "max"` maps to `max` on Opus 4.6/4.7, clamps to `high` on other adaptive models, and falls back to the `high` budget on budget-based Anthropic models. OpenAI-style providers clamp `max` to `xhigh` on xhigh-capable models (GPT-5.2/5.3/5.4) and to `high` otherwise via a new `clampMaxForOpenAI` helper.
- Extended the per-provider reserved-key sets so `extraBody` cannot stomp library-managed fields. New reservations include `metadata`, `temperature`, `store`, `stream_options`, `provider`, `providerOptions`, `tool_stream`, `prompt_cache_key`, `prompt_cache_retention`, `service_tier`, `promptMode`, `requestMetadata`. The Google reserved set now targets the inner `config` object (which the @google/genai SDK serializes as the HTTP request body) with `systemInstruction` / `tools` / `toolConfig` / `generationConfig` / `thinkingConfig` / `responseMimeType` / `responseSchema` / `cachedContent` / `abortSignal` / `httpOptions` reserved.
- Merged Google and Google Vertex `extraBody` into `params.config` instead of the top-level `GenerateContentParameters` so user-supplied fields actually reach the Gemini wire (the SDK does not serialize root-level unknown fields).
- Updated `adjustMaxTokensForThinking` / `clampReasoning` to accept the new `"max"` level without crashing on missing budget entries.

### Files modified (follow-up)
- `src/types.ts` (ThinkingLevel adds `"max"`)
- `src/providers/simple-options.ts` (added `clampMaxForOpenAI`, tightened reserved sets, Google reservations target `config`)
- `src/providers/anthropic.ts` (`mapThinkingLevelToEffort` native `max` case, JSDoc refresh, reserved keys `metadata` + `temperature`)
- `src/providers/openai-responses.ts`, `openai-completions.ts`, `openai-codex-responses.ts`, `azure-openai-responses.ts` (use `clampMaxForOpenAI` on xhigh-capable models)
- `src/providers/amazon-bedrock.ts` (budget table adds `max`, clamp `max` on budget-based path)
- `src/providers/google.ts`, `google-vertex.ts` (merge extraBody into `config`)

### Why the higher-level extension system couldn't handle this alone
- The `ThinkingLevel` union, provider effort mapping, and reserved-key sets all live inside `pi-ai`. Exposing `"max"` to the coding agent requires widening the shared union and updating every provider's payload builder and option-derivation logic.

### Expected merge conflict zones (follow-up)
- `src/types.ts` `ThinkingLevel` union.
- Each provider's `streamSimple<Provider>` reasoning mapping block.
- `src/providers/simple-options.ts` exported reserved-key sets.

## 2026-07-22 - Thinking content stream timing metadata

### What changed and why

- `ThinkingContent` now exposes optional `startedAt` and `endedAt` epoch-millisecond fields. The agent loop stamps these at provider stream-event receipt on a best-effort basis, allowing consumers to measure individual reasoning-block duration without changing provider event contracts.

### Expected merge conflict zones

- LOW: `src/types.ts` `ThinkingContent` interface.

## Client abort on Anthropic server-side fallback receipts (2026-07-25)

### What changed

- `utils/server-fallback-receipt.ts`: new module parsing Anthropic's `fallback` content block and the `fallback_message` entry in `usage.iterations`, plus the refusal-shaped rewrite applied to an aborted turn.
- `types.ts`: `StreamOptions.abortServerSideFallback` (opt-in), inherited by `SimpleStreamOptions` and `AnthropicOptions`; `api/simple-options.ts` forwards it through `buildBaseOptions`.
- `api/anthropic-messages.ts`: a provider-local `AbortController`, merged with the caller signal through `combineAbortSignals`, is passed to the request and the SSE iterator. A receipt block or a `fallback_message` usage entry aborts it and finalizes the turn as `{stopReason:"error", stopDetails:{type:"refusal"}}` with empty content plus `server_fallback_aborted` and `billing_incomplete_after_client_abort` diagnostics. A caller abort is checked first and always wins.

### Why the extension system couldn't handle this

Detection has to happen inside the Anthropic SSE loop while the stream is still open; nothing outside the provider can stop reading a response mid-flight.

### Expected merge conflict zones

- MEDIUM: `api/anthropic-messages.ts` streaming event loop and request-option construction.
- LOW: `types.ts` `StreamOptions`, `api/simple-options.ts` `buildBaseOptions` field list, `index.ts` export list.

## 2026-08-25 - Preserve upstream provider adapter behavior

### What changed

- `packages/ai/src/api/openai-completions.ts` and `packages/ai/src/providers/cloudflare-ai-gateway.ts` retain fork provider behavior while adopting upstream reasoning and typing fixes.

### Why

- Provider wire behavior is a runtime contract.

### Why this lives in the fork

- Adapter serialization and provider registration run below extension hooks.

### Expected merge conflict zones

- OpenAI Completions reasoning conversion and Cloudflare provider generic declarations.

## 2026-08-22 - Stable Anthropic cache checkpoints across tool loops

### What changed
- `api/anthropic-messages.ts` now marks the newest and immediately preceding cacheable user-message boundaries, retaining a stable Anthropic prompt-cache checkpoint while tool loops append new results. OAuth requests with a context system prompt keep the checkpoint budget available for message history.

### Why
- Replacing the sole tail marker on every tool turn invalidated the previous cache boundary and caused repeated prefix reprocessing instead of preserving a reusable checkpoint across adjacent loops.

### Why an extension could not handle it
- Cache markers are attached while the Anthropic wire payload is built inside `pi-ai`; extensions cannot safely rewrite Anthropic-native message blocks after conversion.

### Expected merge conflict zones
- MEDIUM: `api/anthropic-messages.ts` cache-control placement in `buildParams()` and the final checkpoint pass in `convertMessages()`.

## 2026-09-08 - Handle Anthropic mid-output server fallback

### What changed

- `packages/ai/src/api/anthropic-messages.ts` handles Anthropic `fallback` content blocks through the existing receipt path regardless of whether they arrive before or after output starts.
- When client-side abort is disabled, `packages/ai/src/api/anthropic-messages.ts` preserves the fallback boundary, records the serving model, and continues accumulating its output.

### Why

- Anthropic documents mid-output fallback blocks as a supported streaming response. The early error in `packages/ai/src/api/anthropic-messages.ts` prevented configured refusal fallback routing.

### Why an extension could not handle it

- `packages/ai/src/api/anthropic-messages.ts` owns the SSE boundary, stream cancellation, and serving-model attribution before extension hooks receive the completed message.

### Expected merge conflict zones

- `packages/ai/src/api/anthropic-messages.ts`: the `content_block_start` fallback receipt branch.

## 2026-09-12 - Upstream sync (upstream/main@71dca871) integration repairs

### What changed

- `packages/ai/src/api/anthropic-messages.ts`: fork adapter body (adaptive/xhigh/disabled-thinking model markers, mid-conversation output config and thinking-binding betas, unsigned-thinking fallback, tool-pair sanitizing and unavailable-tool demotion, Cloudflare base URL, retry-after hints, session resource cleanup, video input filtering) with upstream's `sessionAffinityFormat` folded into the fork's `getAnthropicCompat` (`openrouter` -> `x-session-id`, otherwise `x-session-affinity`).
- `packages/ai/src/api/mistral-conversations.ts`: fork prompt-mode/thinking-replay handling (`preserveThinking`, `applyExtraBody` with `MISTRAL_RESERVED_BODY_KEYS`, `configurationUpdate` skipped) unioned with upstream's `reasoning_effort` for `mistral-medium-*` and GLM-5.2.
- `packages/ai/src/api/openai-codex-responses.ts`: fork Codex adapter (WebSocket fallback state and debug stats, stale previous-response recovery, account-id extraction, wire identity, retry hints, `buildCodexReasoning` helper in `openai-codex-responses/reasoning.ts`) extended so a reasoning model whose `thinkingLevelMap.off !== null` sends `{ effort: off ?? "none" }` when no effort is requested (upstream Codex Off behavior).
- `packages/ai/src/api/openai-responses-shared.ts`: fork `configurationUpdate` positioning, context provenance stamping, freeform/custom tool deltas (`CUSTOM_TOOL_CALL_ITEM_ID_SENTINEL`), reasoning-signature parsing and native image-generation reconciliation, plus upstream's delete-undefined `errorMessage` on terminal messages.
- `packages/ai/src/api/openai-responses.ts`: fork Responses adapter (session WebSocket cache with TTL, `responses_websockets` beta, web-search sources include, Cloudflare/native endpoint detection, client auth resolution, unsupported native tool sanitizing, `clampMaxForOpenAI`, seven-level thinking map inference) over upstream's base.
- `packages/ai/src/index.ts`: keeps the fork barrel additions (Cursor agent helpers and types, `warmPromptCache`, auth headers, context provenance, Cursor catalog/capabilities/selection, env API keys, tool-call middleware and recovery parsers, `dropFailedAssistantTurns`, `estimateContextTokens`, prompt-cache TTL helpers, server-fallback receipts, stop details, tool-pair repair, visible text, wire identity).
- `packages/ai/src/models.ts`: fork credential pool (`appendLoginSlot`/`removeSlot`, `resolveRefreshCredential` module, `logout` with `slotId`), `PROVIDER_NOT_CONFIGURED_PREFIX`/`providerNotConfiguredMessage`, per-model `retryPolicy` profile, `ThinkingLevelMap` re-export; upstream's `streamDeferred` split was adopted.
- `packages/ai/src/providers/cloudflare-ai-gateway.ts`: the gateway catalog also mirrors `CLOUDFLARE_WORKERS_AI_MODELS` under `workers-ai/<id>` on the compat base URL.
- `packages/ai/src/providers/faux.ts`: fork faux provider extras (`ProviderNativeContent` blocks, `abortSource`/`stopDetails` on synthesized messages, `schedulerHook`, `getCallLog` with cloned context/options, `configurationUpdate` skipped).
- `packages/ai/src/types.ts`: fork type surface (`cursor-agent`/`devin-agent` APIs, `openai-images`, extra known providers incl. `venice`/`opengateway`/`cursor`/`ollama`, `ThinkingSelection`, `max` thinking level, `ProviderRequestMetadata` third argument to `onPayload`, `abortServerSideFallback`, `affinitySessionId`, `streamKind`, `supportsAdditionalTools` compat) plus upstream's `sessionAffinityFormat` on `AnthropicMessagesCompat`.
- `packages/ai/src/utils/event-stream.ts`: fork `EventStream` (`fail()` rejecting waiters and the final promise, array-backed queue with compaction, `queue` snapshot getter, `trackLocalWork`/`hasPendingLocalWork`) over upstream's FIFO queue.
- `packages/ai/src/utils/retry.ts`: fork classifiers (credit exhaustion and request-shape rejections non-retryable; credential-store lock contention, Cloudflare 522, model-request-rejected wording, Anthropic pairing errors and Claude SDK lock contention retryable) and `retryDelayMs` with `+/-10%` jitter through the injectable `random` before the safe-integer guard and the `maxAgentDelayMs` cap (D-M).
- `packages/ai/src/utils/uuid.ts`: `fillRandomBytes` falls back to `Math.random` when `globalThis.crypto` is unavailable; `formatUuid` split out; upstream timestamp support retained.

### Why

- These files carry the fork's provider behavior (Astra thinking ladder, Codex WebSocket fallbacks, Cursor/Devin agents, credential pools, prompt-cache provenance, retry classification with jitter) that upstream does not ship; the sync keeps them and folds upstream's affinity, Codex Off and `errorMessage` fixes into the fork shapes.

### Why an extension could not handle it

- Request payload construction, stream event queues, retry classification, the public type union and the package barrel are inside the AI library; extensions consume them and cannot rewrite them.

### Expected merge conflict zones

- HIGH: `packages/ai/src/api/anthropic-messages.ts` (`getAnthropicCompat`, beta header list, `buildParams`), `packages/ai/src/api/openai-responses.ts` and `openai-codex-responses.ts` request builders, `packages/ai/src/types.ts` option interfaces, `packages/ai/src/index.ts` export list.
- MEDIUM: `retryDelayMs`/`NON_RETRYABLE_PROVIDER_ERROR_PATTERN` in `utils/retry.ts`; `EventStream` iterator in `utils/event-stream.ts`; `usesReasoningEffort` in `mistral-conversations.ts`; `models.ts` auth resolution.
- LOW: `providers/faux.ts` option types; `providers/cloudflare-ai-gateway.ts` model list; `utils/uuid.ts` byte source.


## 2026-09-23 — Add model-only text audience without changing provider payloads

### What changed

`packages/ai/src/types.ts`, `packages/ai/src/api/pi-messages.ts`: Add the optional model-only audience contract and project protocol text fields without UI metadata. Adapter tests compare serialized marked and unmarked requests, including image-bearing results and Cursor/Devin protobuf messages.

### Why

Tool notices must remain model context without being presented as user-facing output.

### Why an extension could not handle it

The shared content type and provider serialization belong to the AI package, before extension rendering hooks.

### Expected merge conflict zones

TextContent and pi-messages request construction.

- Covered production paths: `packages/ai/src/types.ts`, `packages/ai/src/api/pi-messages.ts`.

## 2026-09-24 — Classify prompt-cache lifetimes per provider contract (#2090, #831)

### What changed

- `packages/ai/src/utils/prompt-cache-ttl.ts` adds `resolvePromptCacheLifetime()` and the `PromptCacheLifetime` union: `ttl` (explicit expiry contract with seconds), `best-effort` (automatic caching with no expiry contract), and `none` (disabled or unknown). `resolvePromptCacheTtlSeconds()` keeps its signature and returns the `ttl` seconds, otherwise `undefined`.
- The `openai-responses`, `azure-openai-responses` and `openai-codex-responses` branch resolves GPT-5.6 and later (`gpt-5.6*`, `gpt-6*`, or `compat.supportsExplicitPromptCacheMode`) to `PROMPT_CACHE_TTL_OPENAI_EXTENDED_SECONDS` (1800). On `openai-responses` this applies only to provider `openai` or the `api.openai.com` host; gateways that proxy the same ids keep 300. Earlier OpenAI models keep 300.
- The `openai-completions` branch classifies direct DeepSeek (provider `deepseek` or the parsed, case-insensitive `api.deepseek.com` host) as `best-effort`. `cacheRetention: "none"` still wins first.
- `packages/ai/src/index.ts` exports `resolvePromptCacheLifetime`, `PromptCacheLifetime` and `PROMPT_CACHE_TTL_OPENAI_EXTENDED_SECONDS`.

### Why

- OpenAI documents that GPT-5.6+ prompt caches stay eligible at least 30 minutes after the latest write or reuse, yet every Responses model resolved 300 s, so cache-aware budgets were about 6.7x tighter than the provider requires. DeepSeek's disk cache is automatic and best-effort, with entries cleared after hours to days, so reporting it as a fixed 5-minute TTL produced false TTL copy and 270 s goal wakes.

### Why an extension could not handle it

- Provider cache semantics are resolved in the shared AI provider matrix that every coding-agent consumer reads; an extension cannot change what the resolver reports to core budgets and builtins.

### Expected merge conflict zones

- MEDIUM: `utils/prompt-cache-ttl.ts` `resolvePromptCacheLifetime()` switch (formerly the body of `resolvePromptCacheTtlSeconds()`) and the new constants near the top of the file.
- LOW: the prompt-cache export block in `index.ts`.

- Covered production paths: `packages/ai/src/utils/prompt-cache-ttl.ts`, `packages/ai/src/index.ts`.

## 2026-09-27 — Structured providerDiagnostic on failed provider turns (#2197)

### What changed

- `packages/ai/src/types.ts`: `AssistantMessage` gains the optional `providerDiagnostic?: ProviderDiagnostic` field.
- `packages/ai/src/api/anthropic-messages.ts`: the two `client.beta.messages.create(...).asResponse()` awaits run through `awaitProviderTransport(..., anthropicProviderDiagnosticFromError)`, the `event: error` SSE throw attaches `anthropicProviderDiagnosticFromSseData(sse.data)` to the same `Error(errorText)`, and the catch copies `readProviderDiagnostic(error)` onto `output.providerDiagnostic` for `stopReason: "error"` only. `errorMessage` and the `provider_retry_failure` diagnostic are byte-identical.
- `packages/ai/src/api/openai-completions.ts`: `createStream` awaits the SDK call through `awaitProviderTransport` and wraps the SDK stream in `iterateProviderTransport` (both with `openAICompatibleProviderDiagnosticFromError`), so HTTP rejections and in-stream error chunks carry a diagnostic; the catch copies it like the Anthropic adapter. `errorMessage` formatting is unchanged.
- `packages/ai/src/index.ts`: re-exports `./provider-diagnostic.ts` (`ProviderDiagnostic` types, `PROVIDER_DIAGNOSTIC_MAX_BYTES`, `sanitizeProviderDiagnostic`, `readProviderDiagnostic`).
- Fork-only modules: `src/provider-diagnostic.ts`, `src/utils/provider-diagnostic-vocabulary.ts` (closed token allowlist, status compatibility, 512-byte builder), `src/utils/provider-diagnostic-carrier.ts` (WeakMap side channel on thrown errors), `src/utils/provider-diagnostic-sources.ts` (per-adapter readers and the transport seam wrappers).

### Why

- SDK/RPC consumers could only tell an auth failure from a rate limit, quota exhaustion, a context overflow or an outage by regex over `errorMessage`. The diagnostic is minted where the structured evidence still exists (the SDK error its own transport call raised, the SSE envelope before it becomes an Error message), never from message text, headers or request ids, and never from errors raised by caller callbacks such as `onPayload`. Prior art: gajae-code #6017.

### Why an extension could not handle it

- The structured status and error code are gone once the adapter reduces the failure to `errorMessage`; only the adapter's own transport seam can observe them, and extensions see the already-collapsed message.

### Expected merge conflict zones

- MEDIUM: `createRequest` in `anthropic-messages.ts` (the `send` wrapper around `client.beta.messages.create`) and the stream catch block; `createStream` and the catch block in `openai-completions.ts`.
- LOW: the `event: error` branch of `iterateAnthropicEvents`; the `AssistantMessage` interface in `types.ts`; the export block in `index.ts`.

- Covered production paths: `packages/ai/src/types.ts`, `packages/ai/src/api/anthropic-messages.ts`, `packages/ai/src/api/openai-completions.ts`, `packages/ai/src/index.ts`.

### Review round 2: retry-delay boundary

- `packages/ai/src/utils/provider-retry.ts`: `validateServerRetryDelayMs` receives the provider error itself instead of only its message and re-attaches the diagnostic already minted on it (`peekProviderDiagnostic` → `attachProviderDiagnostic`) to the `ProviderRetryDelayError` it throws when the server's requested delay exceeds `maxRetryDelayMs`. Without this the replacement error dropped the diagnostic on both adapters. The message text, `retryAfterMs`, the delay limit and the retry decision are unchanged; nothing is classified from the text or the headers.
- Expected merge conflict zones: LOW, the `validateServerRetryDelayMs` signature and its single call site in `getRetryDelayMs`.

- Covered production paths: `packages/ai/src/utils/provider-retry.ts`.

## 2026-10-02 - Adopted upstream provider and auth fixes (upstream v1.0.0 sync)

### What changed

- `packages/ai/package.json`
- `packages/ai/src/api/anthropic-messages.ts`
- `packages/ai/src/api/constrained-sampling.ts`
- `packages/ai/src/api/openai-responses-shared.ts`
- `packages/ai/src/auth/oauth/anthropic.ts`
- `packages/ai/src/env-api-keys.ts`
- `packages/ai/src/providers/anthropic.ts`
- `packages/ai/src/utils/overflow.ts`

The upstream v1.0.0 (and absorbed main) changes are kept: Anthropic workload identity federation, the Anthropic copy-code login, non-strict tools when a schema uses rejected keywords (through the fork's constrained-sampling policy), Z.AI CN overflow detection, grammar tool-call replay id dropping, and the lightweight `./models` entry with its export block.

### Why

These are additive upstream fixes and features the fork adopted (D-12) on top of its kept provider/auth behaviour; every recorded pin stays.

### Why an extension could not handle it

Provider authentication and API behaviour live in this package, below any extension hook.

### Expected merge conflict zones

Upstream provider/auth changes in these files at the next sync.
## 2026-10-11 - Explain account-wide usage limits (senpi#3131)

### What changed

- `packages/ai/src/utils/provider-failure-description.ts`: accepts the caller's classified usage-limit scope and describes an account limit with provider identity, a reset hint, and model-switch/fallback recovery.

### Why

Raw provider JSON does not explain that another model on the same account will also fail.

### Why an extension could not handle it

The shared provider-error formatter owns presentation across session, print, and interactive consumers.

### Expected merge conflict zones

The options type and account-limit branch in `describeProviderFailureForUser`.