npm - @fgv/ts-extras - Versions diffs - 5.1.0-56 → 5.1.0-57 - Mend

@fgv/ts-extras 5.1.0-56 → 5.1.0-57

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (98) hide show

package/CAPABILITIES.md CHANGED Viewed

@@ -20,7 +20,7 @@
 | [`hash`](https://github.com/ErikFortune/fgv/tree/release/libraries/ts-extras/src/packlets/hash) | `Md5Normalizer` (Node + browser variants). |
 | [`zip-file-tree`](https://github.com/ErikFortune/fgv/tree/release/libraries/ts-extras/src/packlets/zip-file-tree) | `FileTree` accessors backed by a ZIP archive. Read-only, and ZIP entries are byte-native, so `ZipFileTreeAccessors`/`ZipFileItem` support the read half of the optional binary capability (`getFileBytes`/`getRawBytes`) alongside the usual text read. `createZipFromFiles({ path, contents: string \| Uint8Array }[])` (sibling to `createZipFromTextFiles`) writes archive entries whose contents are raw bytes — string entries are UTF-8 encoded, `Uint8Array` entries are stored verbatim. Byte-native custody also means both types support the optional **strict-text** capability (`getFileTextStrict`/`getTextStrict`) — a `ZipFileItem` constructed directly from already-decoded text is the one case that refuses, since its bytes are a re-encode. |
 | [`conversion`](https://github.com/ErikFortune/fgv/tree/release/libraries/ts-extras/src/packlets/conversion) | Extra converters beyond ts-utils. |
-| [`ai-assist`](https://github.com/ErikFortune/fgv/tree/release/libraries/ts-extras/src/packlets/ai-assist) | LLM provider client + JSON-tolerant response handling. `callProviderCompletion`/`callProviderCompletionStream` (OpenAI, xAI, Anthropic, Gemini), provider/model registry, `AiPrompt`. **Model aliases (`@<provider>:<role>`).** A model string that begins with the `@` sigil (`MODEL_ALIAS_SIGIL`) is an fgv-owned alias resolved through the owning descriptor's `aliases` map (`IModelAliasMap`) to the current concrete provider id; **any string without a leading `@` is a raw provider id and passes through verbatim** (back-compat is structural — Ollama `model:tag` ids, dated snapshots, and every existing `modelOverride` are unaffected). Resolution is `Result`-returning and registry-gated: an unregistered `@alias` fails loudly (typo/unknown) rather than hitting the wire. `resolveModelAlias(descriptor, model)` resolves one string (following one `@fgv-alias → provider-native-alias` hop, cycle-guarded); `resolveProviderModel(descriptor, modelOverride, context?)` is the call-time chokepoint (ModelSpecKey walk THEN alias resolution) used by completion / streaming / image / embedding / client-tool paths. `resolveImageCapability`/`resolveEmbeddingCapability` (look up a model's `IAiImageModelCapability`/`IAiEmbeddingModelCapability` by id) also resolve the alias first — pass either an `@alias` or a concrete provider id and both prefix-match against the correct capability entry; before this, an unresolved alias silently fell through to the provider's catch-all `modelPrefix: ''` rule and returned a confidently wrong capability rather than failing or returning `undefined`. **Quality-tier axis (`base`/`advanced`/`frontier`).** On top of the alias layer, one cross-provider quality axis selects the *completion* model: `ModelSpecKey = 'base' \| 'advanced' \| 'frontier' \| 'image' \| 'embedding'`, and a completion/streaming call takes an optional `tier?: 'advanced' \| 'frontier'` request param (omit → `base`). The three tier keys are the **only** completion-model selectors; `image`/`embedding` select the non-completion modalities. **Cascade:** a tier request walks an ordered fallback list and takes the first key present — `frontier → advanced → base`, `advanced → base`, `base` — so a provider only declares the tiers it differentiates (OpenAI wires all three — `frontier` → `gpt-5.6-sol`, which works on Chat Completions; Anthropic, Gemini, and xAI omit `frontier` and cascade to their `advanced` model; the previous frontier target `gpt-5.5-pro` is Responses-API-only and stays `modelOverride`-only). `base` is the required floor and universal fallback; `image`/`embedding` keep flat `modality → base` behavior. **Composition, not competition:** thinking (reasoning effort) and tools (server-side tools) are orthogonal request/capability params — they ride on top of whatever model the tier picked and **never select a model** (`ModelSpecKey` carries no `thinking`/`tools` keys — they were removed when the tier axis landed). `tier: 'base'` + a thinking config resolves the cheap base model and sends the thinking param to it; every base model is thinking-capable, so thinking composes with any tier with zero capability checks. A `frontier + thinking` request is just a frontier-tier completion with the thinking param set. **Per-provider tier maps:** OpenAI `base @openai:mini → gpt-5.6-luna`, `advanced @openai:flagship → gpt-5.6-terra`, `frontier @openai:pro → gpt-5.6-sol` (the 5.6 family works on chat completions; the previous frontier target `gpt-5.5-pro` remains Responses-API-only and `modelOverride`-only, routed via `responsesOnlyModelPrefixes`); Anthropic `base @anthropic:sonnet → claude-sonnet-5`, `advanced @anthropic:opus → claude-opus-5` (frontier unset → cascades to opus); Gemini `base @google-gemini:flash → gemini-3.5-flash`, `advanced @google-gemini:pro → gemini-3.1-pro-preview` (frontier unset → cascades to pro), `image @google-gemini:flash-image → gemini-3.1-flash-image`, `embedding @google-gemini:embedding → gemini-embedding-001`; xAI `base @xai-grok:standard → grok-4.3`, `advanced @xai-grok:flagship → grok-4.5` (frontier unset → cascades to flagship), `image @xai-grok:imagine → grok-imagine-image-quality` (the cheaper `@google-gemini:flash-lite → gemini-3.1-flash-lite` and the non-tier `@openai:nano`/`@anthropic:haiku`/`@anthropic:fable` aliases are `modelOverride`-only). **Maintenance loop = one edit + a testbed run:** on a provider line rotation edit the single alias value in that descriptor's `aliases` map (a tier re-slot edits the one `defaultModel` slot → alias mapping, no alias rename so no `modelOverride` ripple), then run the per-provider testbed scenario against the live API to confirm the new id answers — consumers and `defaultModel` reference the stable alias/tier slot and never change. The alias layer covers **selection/default churn only** — capability-detection `idPattern` rules and the typed `*ModelNames` unions remain manual axes (see TECH_DEBT). **Every turn entry point takes the unified `{ system?, messages: IChatMessage[] }` request shape (`IChatRequest`)** — `messages` is the ordered conversation, the last entry is the current user turn and the preceding entries are history; history is always linearized before the current turn (no head/tail asymmetry). `AiPrompt.toRequest()` lowers a system+user prompt to this shape. The proxy wire body serializes `{ system?, messages }`. **For JSON-shaped completions use `generateJsonCompletion<T>({ converter, ... })`** — it appends a smart "raw JSON only" prompt hint and runs the response through `fencedStringifiedJson`, which strips Markdown fences, leading preamble, and trailing prose before validating with the caller's `Converter<T>` or `Validator<T>`. The bare `extractJsonText` helper is exported for callers that just need wrapper-stripping; `fencedStringifiedJson({ extractor, inner })` is the extension point for custom extractors. **Don't reimplement fence-stripping in consumers.** **Native structured output (`structuredOutput` on every **non-streaming** completion request; the streaming paths deliberately do not support it).** Rather than only *asking* for JSON in the prompt, a caller can **tell the provider** — `structuredOutput: { mode: 'schema', schema }` (a `JsonSchema.ISchemaValidator`, **the same object you validate the reply with**, so the wire schema and the check cannot drift — the cloud sibling of `@fgv/ts-extras-ollama`'s `chatStructured`) or `{ mode: 'json-object' }` (syntactic validity only, arbitrary shape). Four wire formats behind it, declared per model family on `IAiProviderDescriptor.structuredOutput: IAiStructuredOutputCapability[]` and longest-prefix matched **after** alias resolution (`resolveStructuredOutputCapability`): `openai-json-schema` (`response_format`), `openai-responses-format` (`text.format`), `gemini-response-schema` (`generationConfig.responseMimeType` + `responseSchema`, run through the same draft-07 sanitizer the Gemini tool path uses), and `anthropic-tool-forced` — Anthropic has **no** response-format field, so its mechanism is a forced synthetic tool, which is why `'tool-forced'` is a distinct enforcement value and not a spelling of `'schema'`. **`IAiCompletionResponse.structuredOutput: StructuredOutputEnforcement` is REQUIRED, not optional** (`'none'` | `'json-mode'` | `'schema'` | `'tool-forced'`): an optional field would make absence three-ways ambiguous — no capability / not requested / a build predating the feature — and disambiguating exactly that is what it is for. It reports what was **sent**, never whether *this* response conforms; that is your converter's answer and re-deriving it here would be a second source of truth. **An optional property is unsendable to the OpenAI strict formats** (every property must be in `required`), and that is refused rather than silently repaired — *unless* the property's node **already admits `null`**, in which case **`adaptOptionalToNullable: true`** hoists it into `required` instead of refusing the schema. The opt-in is not the caller asserting its validator tolerates `null`; the condition is read off the schema, so it cannot be asserted falsely. `optional(string({ nullable: true }))` accepts absent-or-null-or-value, so listing the key in `required` only removes the model's option to omit it and every permitted reply still satisfies the supplied schema — whereas a plain `optional(string())` rejects `null`, is not hoisted, and still refuses. Verification is `hasOptionalProperties` re-run on the rewritten schema, so a partly-hoistable schema degrades **whole** rather than going out half-adapted; the hoist is also gated on the format, so it is inert on Gemini and Anthropic, which have no such rule. **Prefer `optional(x({ nullable: true })) + adaptOptionalToNullable` to authoring a bare `nullable`** when absence is genuinely meaningful to you: the schema then states what your validator does rather than what one provider demands, and the provider accommodation stays in `resolveStructuredOutput` where it can be kept correct as providers change. **`onUnsupported` defaults to `'degrade'`, and that is only safe because the report is required** — degrade-and-tell-me is safe, degrade-silently is the failure this exists to remove, so the two are one decision. Pass `'fail'` for output that is persisted or put on a wire, where an unconstrained generation that happens to parse is worse than an error; leave it at `'degrade'` on paths *designed* to degrade. Structured output **conflicts with server-side tools on Anthropic and Gemini, for different reasons** — Anthropic's mechanism *is* `tools` + `tool_choice` (a wire-level clash), Gemini's lives in `generationConfig` and the exclusion is API-enforced — and that conflict **fails rather than degrading** (`onUnsupported` speaks to capability, not to a caller asking for two incompatible things). Under `'tool-forced'` the reply arrives in a `tool_use` block and is **re-serialized** into `content`, so `content` stays a JSON string on every provider and a converter never branches on which enforcement it got. **`generateJsonCompletion` adopts this for free**: `ISchemaValidator<T> extends Validator<T>`, so if you already author `converter` as `JsonSchema.object({...})` the library now sends it — **no new parameter** (which would reintroduce the converter/schema drift `JsonSchema` exists to remove), and a plain `Converter` carries no schema so existing callers are byte-for-byte unchanged and report `'none'`. Self-hosted providers (`ollama`, `openai-compat`) and `groq` declare **no** capability on purpose — any model can sit behind them, and a wrong capability claim is worse than none; they report `'none'` and the report makes that visible. **To find out *why* a JSON-shaped response failed to parse** (not just that it did), use `classifyJsonParseFailure(text)` → `JsonParseFailureReason` — a structural classifier (walks the JSON grammar; never regex-matches the engine's `JSON.parse` error string, so verdicts don't drift across Node/V8 versions) that names four property-name-position faults with `token` + `offset` (0-based into the original `text`, not the extracted substring): `unquoted-property-name`, `single-quoted-property-name`, `unterminated-property-name`, `elided-member`; everything else — including truncation, missing colons, and bad number literals — falls to the conservative `'unknown'` rather than guessing. **Total**: non-string input returns `'unknown'` instead of throwing, matching `extractJsonText`'s guard. **For image generation use `callProviderImageGeneration`/`callProxiedImageGeneration`** — supports OpenAI DALL-E 3 / gpt-image-1 (`openai-images`), xAI grok-imagine generations (`xai-images`) and edits (`xai-images-edits`), and Gemini image-output via generateContent (`gemini-image-out`). The layered options system provides top-level keys (`size`, `quality`, `seed`, `count`) alongside per-provider `models` blocks for provider-specific params (e.g. `{ provider: 'openai', family: 'gpt-image', config: { outputFormat, background, moderation, outputCompression } }`). Provider capability is declared on `IAiProviderDescriptor.imageGeneration: IAiImageModelCapability[]`; `imageOptionsResolver` translates the layered options into a wire-ready `IResolvedImageOptions`. **For harness-side client tools (tools the caller implements, not the provider) use `executeClientToolTurn`** — the single-turn helper for tool-use conversations. Supply `clientTools: IAiClientTool[]` alongside any `tools: IAiServerToolConfig[]`; the helper returns `{ events: AsyncIterable<IAiStreamEvent>, nextTurn: Promise<Result<IAiClientToolTurnResult>> }` where `events` streams intermediate tool events and `nextTurn` awaits the complete round-trip result (including `continuation.messages` — the provider-format wire messages to re-supply on the next turn). `IAiClientTool` carries `config: IAiClientToolConfig` (name, description, `parametersSchema: ISchemaValidator<TParams>` — use `JsonSchema.object(...)` from `@fgv/ts-json-base`) and `execute: (args: unknown) => Promise<Result<unknown>>`. Type the tool as `IAiClientTool` (unparameterized, default `unknown`) and validate args inside `execute` via `parametersSchema.validate(args)` — the `execute` callback is contravariant in `TParams` so a typed `IAiClientTool<{key:string}>` is not assignable to `IAiClientTool<unknown>`. For multi-turn conversations pass `continuationMessages: continuation.messages` (type `ReadonlyArray<JsonObject>`) — `continuation.messages` is **cumulative** (replace each round, do not manually concatenate; the library prepends the inbound tail automatically so the array always covers all rounds so far) — these are provider-format wire objects appended after the current user turn. The exact wire-shape handling is per-provider: **Anthropic** projects each entry to `{ role, content }` (extra fields dropped; invalid entries skipped); **Gemini** projects to `{ role, parts }` (same shape guard); **OpenAI Responses / xAI** pass entries through verbatim with a `JsonObject` guard (since OpenAI Responses items are a `type`-keyed discriminated union whose fields differ per item). Consumers should not assume arbitrary fields round-trip on every provider — the high-fidelity round-trip is on the OpenAI/xAI path; Anthropic and Gemini preserve only the projected fields. Cross-provider continuation works on **all four providers**. **Do not put continuation wire objects in `messages`** (the unified `IChatRequest` conversation turns) — `continuationMessages` is a distinct post-current-turn axis whose provider-native fields the normalized `messages` path would strip. `IResolvedThinkingConfig` is exported from the packlet for callers that pre-resolve thinking options (e.g. `{ anthropicEffort: 'low' }`) and pass them directly to `executeClientToolTurn`. **Tool parameters authored as `JsonSchema.object(...)` work transparently on Gemini** — the adapter sanitizes draft-07-only keywords (`additionalProperties`, `$schema`) recursively before submission, so strict-by-default schemas don't need consumer pre-processing. **Gemini API constraint:** Gemini's `generateContent` forbids combining built-in grounding (`web_search`) with function calling in the same request — pick one. The library **pre-empts this with a named `Result.fail` before any wire call**, so you get a legible refusal rather than the provider's `INVALID_ARGUMENT` HTTP 400. **Completion diagnostic:** `IAiStreamDone.incompleteReason?: string` (`@public`) carries the OpenAI/xAI Responses `incomplete_details.reason` (`'max_output_tokens'`, `'content_filter'`, …) when `truncated === true`; absent when the stream completed normally. **Provider-drift instrumentation:** Anthropic and OpenAI Responses adapters maintain a `RECOGNIZED_*_EVENTS` allowlist and log a one-time `logger.warn` per stream per unrecognized SSE event name. Warning starts with the stable `ai-assist:unrecognized-event` tag (filter on this prefix to alert on provider-API evolution); includes a **default-safe structural payload preview** (top-level JSON keys + length — never field values) for triage; names the allowlist constant so a developer can find the right list to update. Production deployments wire the `ILogger` via the streaming-call params (`IProviderCompletionStreamParams.logger` / `IExecuteClientToolTurnParams.logger` — NOT via the per-adapter `IStreamApiConfig`, which carries only `{ baseUrl, apiKey, model }`); deployments that don't (default `NoOpLogger`) get a silent no-op. Ops triaging an active drift signal can opt in to the **raw payload preview** by setting `AI_ASSIST_UNRECOGNIZED_EVENT_FULL_PAYLOAD=1` in the environment — keep this off in production by default since SSE payloads can carry tool args / user-conversation text / other sensitive content. Gemini-side drift instrumentation is queued (JSON-chunk wire shape doesn't fit the SSE-event-name allowlist concept). **For embeddings (`text → vector`) use `callProviderEmbedding`/`callProxiedEmbedding`** — the cross-provider embedding primitive (third modality alongside completion and image generation). Batch in (`input: string \\| string[]`), `number[][]` out, `Result`-wrapped. Two wire formats behind one dispatcher: `openai-embeddings` (`POST /embeddings`) serves **OpenAI** (`text-embedding-3-*`), **Ollama** (point `endpoint` at `http://localhost:11434/v1`), **openai-compat** self-hosted servers, and **Mistral** (`mistral-embed`); `gemini-embeddings` (`POST /models/{model}:batchEmbedContents`) serves **Google Gemini** (`gemini-embedding-001`) with its `taskType` retrieval-asymmetry knob. Capability is declared on `IAiProviderDescriptor.embedding: IAiEmbeddingModelCapability[]` (model-prefix matched, longest wins) and selects the model via the `embedding` `ModelSpecKey`. Knob handling (`dimensions`, `taskType`) is **no-op-where-unsupported, not a failure** — a caller passes `taskType: 'retrieval-query'` once and it maps to Gemini's wire `RETRIEVAL_QUERY` while being a logged no-op on the (symmetric) OpenAI-format providers, so the cross-provider call site never branches. Empty input short-circuits to an empty result with no wire call; a batch over the capability's `maxBatchSize` fails fast (no auto-chunking). xAI and Anthropic declare no embedding capability (no first-party endpoint) and reject up front. Vectors are `number[]` (not `Float32Array`) for JSON-wire fidelity — call `Float32Array.from(vector)` at the vector-store boundary; the library does not L2-normalize (Gemini MRL-truncated vectors may need it). **Prompt-cache token accounting (`IAiCompletionResponse.usage?: IAiCompletionUsage`, also on `IAiStreamDone`).** Sibling to `IAiEmbeddingResult.usage` — present when the provider reports it, absent otherwise, never guessed. `AiCacheReportingLevel` (`'reads' \| 'reads-and-writes'` — no `'none'` member; "nothing reported" is `usage` itself being absent) is **required, not optional** on `IAiCompletionUsage`, for the same reason `structuredOutput` is required: an absent `cacheWriteTokens` is three-ways ambiguous (no write happened / this API cannot report writes / a build predating the field) and `reports` disambiguates it by construction. Normalized per wire shape: Anthropic Messages and OpenAI Responses report `'reads-and-writes'`; OpenAI/xAI Chat Completions and Gemini `generateContent` report `'reads'` only — Chat Completions has no `cache_write_tokens` field at all (never defaulted to `0`), and Gemini has no write concept in a `generateContent` call (writes are the out-of-band `cachedContents` resource, out of scope). The OpenAI/xAI Responses route is shared code with diverging behavior: `reports` is derived from **field presence** (`input_tokens_details.cache_write_tokens` present, even `0` → `'reads-and-writes'`; absent entirely → `'reads'`), not from provider identity — but only once a descriptor has cleared `AiAssist.supportsCacheUsageReporting`, the gate applied at all four call sites (Chat Completions and Responses, streaming and non-streaming) before any normalization runs, since all four are shared by every `apiFormat: 'openai'` descriptor (Groq, Mistral, Ollama, self-hosted `openai-compat`), not just OpenAI and xAI Grok; an unconfirmed descriptor — including a future one — gets `usage: undefined` rather than a guess derived from whatever ordinary usage shape its wire happens to send. Gemini's footgun: `cachedContentTokenCount` sits **inside** `promptTokenCount`, unlike OpenAI where it sits in a sibling `…_details` object next to a separate total — `uncachedInputTokens` subtracts to correct for it, but only when the cached figure is itself known (never assumed zero from a merely-absent field). Streaming is covered from the same commit, not a follow-on: Anthropic merges `message_start`'s initial reads/writes with `message_delta`'s final `output_tokens`; OpenAI Chat Completions streaming requires opting in via `stream_options: { include_usage: true }` — sent only for `descriptor.id === 'openai'` (`AiAssist.supportsStreamUsageOption`), since the shared adapter also carries providers whose tolerance for an unrecognized request field is unverified; usage stays silently absent for every other provider on this path, and the populated usage arrives on a terminal `choices: []` chunk, with `usage: null` on every chunk before it once the option is sent; OpenAI/xAI Responses streaming reads `response.completed`'s `response.usage`; Gemini repeats `usageMetadata` on every chunk with running totals; the adapter keeps the last one. `raw?: JsonObject` on `IAiCompletionUsage` carries the provider's own unnormalized usage block for anything the normalized shape drops (e.g. xAI's `cost_in_usd_ticks`). **Prompt-cache breakpoint emission (`IProviderCompletionParams.cache?: IAiCacheRequest`).** `IAiCacheRequest` carries `systemBreakpoints?: ReadonlyArray<number>` — strictly ascending UTF-16 offsets into `system`, each marking the end of a cacheable prefix — and `cacheKey?: string`, an opaque cache-routing key. Both are optional and additive: a request with no `cache` is byte-for-byte the same request a build predating this feature would send. `AiAssist.validateAiCacheRequest`/`validateCacheBreakpoints` **fail loudly and never clamp** — a non-ascending, out-of-range (not `> 0` and `< system.length`), or over-cap (when a `maxBreakpointWrites` cap is supplied) offset returns `Result.fail`, never a silently-trimmed plan. On **Anthropic**, `system` is split into content blocks at each breakpoint, with `cache_control: { type: 'ephemeral' }` on the block that ends each cacheable prefix (was a plain string). On **OpenAI Chat Completions and Responses**, the leading system message/item is split into content parts carrying `prompt_cache_breakpoint: { mode: 'explicit' }` — `prompt_cache_options` is never touched, so OpenAI's own implicit breakpoint and default caching mode are undisturbed; `prompt_cache_key` is sent (both routes) when `cacheKey` is supplied. **Breakpoints and the routing key are gated separately, because they are different capabilities with different support sets.** Breakpoint splitting is gated to `AiAssist.supportsPromptCacheBreakpoints(descriptor)` (`true` only for `descriptor.id === 'openai'`), the same write-side-tolerance reasoning as `supportsStreamUsageOption` — the shared adapter also carries xAI/Groq/Mistral/Ollama/`openai-compat`, none confirmed to tolerate a restructured `system` content array. The routing key is gated to `AiAssist.supportsPromptCacheRouting(descriptor)`, which returns an `IAiPromptCacheRoutingSupport` describing the **per-route transport** rather than a boolean: OpenAI takes `prompt_cache_key` as a body field on both routes; **xAI takes an `x-grok-conv-id` header on Chat Completions and `prompt_cache_key` on Responses**. xAI needs it — its cache matches byte-for-byte from the start of the messages array but is **per-server and evictable**, so two requests sharing a prefix can miss when routed to different servers. Measured on `grok-4.3`: a varying-tail warm call reads **1.9%** cached without the key and **99.7%** with it. A descriptor supporting neither still gets a request — body *and headers* — byte-identical to one a caller omitting `cache` would have sent. **Gemini has no breakpoint mechanism and ignores `cache` entirely.** There is no model-keyed capability/cap table (`IAiCacheCapability`) backing `maxBreakpointWrites` — none was built in any slice of this feature, and a caller building breakpoints from `@fgv/ts-prompt-assist`'s three-level stability vocabulary never needs one, since that vocabulary provably never emits more than two breakpoints. See `@fgv/ts-prompt-assist`'s `toCacheRequest` for deriving a plan from a resolved composition rather than hand-computing offsets. |
+| [`ai-assist`](https://github.com/ErikFortune/fgv/tree/release/libraries/ts-extras/src/packlets/ai-assist) | LLM provider client + JSON-tolerant response handling. `callProviderCompletion`/`callProviderCompletionStream` (OpenAI, xAI, Anthropic, Gemini), provider/model registry, `AiPrompt`. **Model aliases (`@<provider>:<role>`).** A model string that begins with the `@` sigil (`MODEL_ALIAS_SIGIL`) is an fgv-owned alias resolved through the owning descriptor's `aliases` map (`IModelAliasMap`) to the current concrete provider id; **any string without a leading `@` is a raw provider id and passes through verbatim** (back-compat is structural — Ollama `model:tag` ids, dated snapshots, and every existing `modelOverride` are unaffected). Resolution is `Result`-returning and registry-gated: an unregistered `@alias` fails loudly (typo/unknown) rather than hitting the wire. `resolveModelAlias(descriptor, model)` resolves one string (following a chain of `@` aliases until a concrete provider id is reached — one hop is the canonical case, not a limit; cycle-guarded); `resolveProviderModel(descriptor, modelOverride, context?)` is the call-time chokepoint (ModelSpecKey walk THEN alias resolution) used by completion / streaming / image / embedding / client-tool paths. `resolveImageCapability`/`resolveEmbeddingCapability` (look up a model's `IAiImageModelCapability`/`IAiEmbeddingModelCapability` by id) also resolve the alias first — pass either an `@alias` or a concrete provider id and both prefix-match against the correct capability entry; before this, an unresolved alias silently fell through to the provider's catch-all `modelPrefix: ''` rule and returned a confidently wrong capability rather than failing or returning `undefined`. **Quality-tier axis (`base`/`advanced`/`frontier`).** On top of the alias layer, one cross-provider quality axis selects the *completion* model: `ModelSpecKey = 'base' \| 'advanced' \| 'frontier' \| 'image' \| 'embedding'`, and a completion/streaming call takes an optional `tier?: 'advanced' \| 'frontier'` request param (omit → `base`). The three tier keys are the **only** completion-model selectors; `image`/`embedding` select the non-completion modalities. **Cascade:** a tier request walks an ordered fallback list and takes the first key present — `frontier → advanced → base`, `advanced → base`, `base` — so a provider only declares the tiers it differentiates (OpenAI wires all three — `frontier` → `gpt-5.6-sol`, which works on Chat Completions; Anthropic, Gemini, and xAI omit `frontier` and cascade to their `advanced` model; the previous frontier target `gpt-5.5-pro` is Responses-API-only and stays `modelOverride`-only). `base` is the required floor and universal fallback; `image`/`embedding` keep flat `modality → base` behavior. **Composition, not competition:** thinking (reasoning effort) and tools (server-side tools) are orthogonal request/capability params — they ride on top of whatever model the tier picked and **never select a model** (`ModelSpecKey` carries no `thinking`/`tools` keys — they were removed when the tier axis landed). `tier: 'base'` + a thinking config resolves the cheap base model and sends the thinking param to it; every base model is thinking-capable, so thinking composes with any tier with zero capability checks. A `frontier + thinking` request is just a frontier-tier completion with the thinking param set. **Per-provider tier maps:** OpenAI `base @openai:mini → gpt-5.6-luna`, `advanced @openai:flagship → gpt-5.6-terra`, `frontier @openai:pro → gpt-5.6-sol` (the 5.6 family works on chat completions; the previous frontier target `gpt-5.5-pro` remains Responses-API-only and `modelOverride`-only, routed via `responsesOnlyModelPrefixes`); Anthropic `base @anthropic:sonnet → claude-sonnet-5`, `advanced @anthropic:opus → claude-opus-5` (frontier unset → cascades to opus); Gemini `base @google-gemini:flash → gemini-3.5-flash`, `advanced @google-gemini:pro → gemini-3.1-pro-preview` (frontier unset → cascades to pro), `image @google-gemini:flash-image → gemini-3.1-flash-image`, `embedding @google-gemini:embedding → gemini-embedding-001`; xAI `base @xai-grok:standard → grok-4.3`, `advanced @xai-grok:flagship → grok-4.5` (frontier unset → cascades to flagship), `image @xai-grok:imagine → grok-imagine-image-quality` (the cheaper `@google-gemini:flash-lite → gemini-3.1-flash-lite` and the non-tier `@openai:nano`/`@anthropic:haiku`/`@anthropic:fable` aliases are `modelOverride`-only). **Maintenance loop = one edit + a testbed run:** on a provider line rotation edit the single alias value in that descriptor's `aliases` map (a tier re-slot edits the one `defaultModel` slot → alias mapping, no alias rename so no `modelOverride` ripple), then run the per-provider testbed scenario against the live API to confirm the new id answers — consumers and `defaultModel` reference the stable alias/tier slot and never change. The alias layer covers **selection/default churn only** — capability-detection `idPattern` rules and the typed `*ModelNames` unions remain manual axes (see TECH_DEBT). **Every turn entry point takes the unified `{ system?, messages: IChatMessage[] }` request shape (`IChatRequest`)** — `messages` is the ordered conversation, the last entry is the current user turn and the preceding entries are history; history is always linearized before the current turn (no head/tail asymmetry). `AiPrompt.toRequest()` lowers a system+user prompt to this shape. The proxy wire body serializes `{ system?, messages }`. **For JSON-shaped completions use `generateJsonCompletion<T>({ converter, ... })`** — it appends a smart "raw JSON only" prompt hint and runs the response through `fencedStringifiedJson`, which strips Markdown fences, leading preamble, and trailing prose before validating with the caller's `Converter<T>` or `Validator<T>`. The bare `extractJsonText` helper is exported for callers that just need wrapper-stripping; `fencedStringifiedJson({ extractor, inner })` is the extension point for custom extractors. **Don't reimplement fence-stripping in consumers.** **Native structured output (`structuredOutput` on every **non-streaming** completion request; the streaming paths deliberately do not support it).** Rather than only *asking* for JSON in the prompt, a caller can **tell the provider** — `structuredOutput: { mode: 'schema', schema }` (a `JsonSchema.ISchemaValidator`, **the same object you validate the reply with**, so the wire schema and the check cannot drift — the cloud sibling of `@fgv/ts-extras-ollama`'s `chatStructured`) or `{ mode: 'json-object' }` (syntactic validity only, arbitrary shape). Four wire formats behind it, declared per model family on `IAiProviderDescriptor.structuredOutput: IAiStructuredOutputCapability[]` and longest-prefix matched **after** alias resolution (`resolveStructuredOutputCapability`): `openai-json-schema` (`response_format`), `openai-responses-format` (`text.format`), `gemini-response-schema` (`generationConfig.responseMimeType` + `responseSchema`, run through the same draft-07 sanitizer the Gemini tool path uses), and `anthropic-tool-forced` — Anthropic has **no** response-format field, so its mechanism is a forced synthetic tool, which is why `'tool-forced'` is a distinct enforcement value and not a spelling of `'schema'`. **`IAiCompletionResponse.structuredOutput: StructuredOutputEnforcement` is REQUIRED, not optional** (`'none'` \| `'json-mode'` \| `'schema'` \| `'tool-forced'`): an optional field would make absence three-ways ambiguous — no capability / not requested / a build predating the feature — and disambiguating exactly that is what it is for. It reports what was **sent**, never whether *this* response conforms; that is your converter's answer and re-deriving it here would be a second source of truth. **An optional property is unsendable to the OpenAI strict formats** (every property must be in `required`), and that is refused rather than silently repaired — *unless* the property's node **already admits `null`**, in which case **`adaptOptionalToNullable: true`** hoists it into `required` instead of refusing the schema. The opt-in is not the caller asserting its validator tolerates `null`; the condition is read off the schema, so it cannot be asserted falsely. `optional(string({ nullable: true }))` accepts absent-or-null-or-value, so listing the key in `required` only removes the model's option to omit it and every permitted reply still satisfies the supplied schema — whereas a plain `optional(string())` rejects `null`, is not hoisted, and still refuses. Verification is `hasOptionalProperties` re-run on the rewritten schema, so a partly-hoistable schema degrades **whole** rather than going out half-adapted; the hoist is also gated on the format, so it is inert on Gemini and Anthropic, which have no such rule. **Prefer `optional(x({ nullable: true })) + adaptOptionalToNullable` to authoring a bare `nullable`** when absence is genuinely meaningful to you: the schema then states what your validator does rather than what one provider demands, and the provider accommodation stays in `resolveStructuredOutput` where it can be kept correct as providers change. **`onUnsupported` defaults to `'degrade'`, and that is only safe because the report is required** — degrade-and-tell-me is safe, degrade-silently is the failure this exists to remove, so the two are one decision. Pass `'fail'` for output that is persisted or put on a wire, where an unconstrained generation that happens to parse is worse than an error; leave it at `'degrade'` on paths *designed* to degrade. Structured output **conflicts with server-side tools on Anthropic and Gemini, for different reasons** — Anthropic's mechanism *is* `tools` + `tool_choice` (a wire-level clash), Gemini's lives in `generationConfig` and the exclusion is API-enforced — and that conflict **fails rather than degrading** (`onUnsupported` speaks to capability, not to a caller asking for two incompatible things). Under `'tool-forced'` the reply arrives in a `tool_use` block and is **re-serialized** into `content`, so `content` stays a JSON string on every provider and a converter never branches on which enforcement it got. **`generateJsonCompletion` adopts this for free**: `ISchemaValidator<T> extends Validator<T>`, so if you already author `converter` as `JsonSchema.object({...})` the library now sends it — **no new parameter** (which would reintroduce the converter/schema drift `JsonSchema` exists to remove), and a plain `Converter` carries no schema so existing callers are byte-for-byte unchanged and report `'none'`. Self-hosted providers (`ollama`, `openai-compat`) and `groq` declare **no** capability on purpose — any model can sit behind them, and a wrong capability claim is worse than none; they report `'none'` and the report makes that visible. **To find out *why* a JSON-shaped response failed to parse** (not just that it did), use `classifyJsonParseFailure(text)` → `JsonParseFailureReason` — a structural classifier (walks the JSON grammar; never regex-matches the engine's `JSON.parse` error string, so verdicts don't drift across Node/V8 versions) that names four property-name-position faults with `token` + `offset` (0-based into the original `text`, not the extracted substring): `unquoted-property-name`, `single-quoted-property-name`, `unterminated-property-name`, `elided-member`; everything else — including truncation, missing colons, and bad number literals — falls to the conservative `'unknown'` rather than guessing. **Total**: non-string input returns `'unknown'` instead of throwing, matching `extractJsonText`'s guard. **Both proxied completion paths honor `tier`**, resolving it client-side into a concrete `modelOverride` so a proxy needs no new vocabulary to serve a frontier request, and **every proxied entry point refuses `endpoint`** — completion, completion stream, embedding, image generation and list-models — rather than forwarding or dropping it: no proxy can confirm it honored it, and silently reaching the provider's default upstream would send the request somewhere the caller excluded. Use the direct entry point, or point the proxy itself at the intended upstream. It matters most on the embedding path, where aiming `endpoint` at `http://localhost:11434/v1` is the documented way to reach a local Ollama. `callProxiedListModels`'s `capabilityConfig` stays a **disclosed no-op** instead — the proxy returns models already classified, so an override could only arrive too late, and a worse classification is a degraded answer rather than a misrouted request. `callProxiedCompletion` additionally honors `structuredOutput` (including `adaptOptionalToNullable`) and returns `usage`, validated on arrival rather than cast — an unrecognized extra field is tolerated, since the proxy may be a newer build, but a block missing the required `reports` level yields `undefined` rather than a partially-trusted object. The proxied *stream* carries only `text-delta` / `tool-event` / `done` / `error`; the three `client-tool-*` variants are discarded, and client-tool turns are not proxiable. It validates only that type discriminator and forwards each event as-is, so a `usage` block on `done` reaches the caller typed but unchecked — the same terms as every other field on every forwarded event. **For image generation use `callProviderImageGeneration`/`callProxiedImageGeneration`** — supports the OpenAI `gpt-image-*` family (`openai-images`; DALL-E 3 was EOL 2026-05-12 and its options block no longer exists), xAI grok-imagine generations (`xai-images`) and edits (`xai-images-edits`), and Gemini image-output via generateContent (`gemini-image-out`). The layered options system provides top-level keys (`size`, `quality`, `seed`, `count`) alongside per-provider `models` blocks for provider-specific params (e.g. `{ provider: 'openai', family: 'gpt-image', config: { outputFormat, background, moderation, outputCompression } }`). Provider capability is declared on `IAiProviderDescriptor.imageGeneration: IAiImageModelCapability[]`; `imageOptionsResolver` translates the layered options into a wire-ready `IResolvedImageOptions`. **For harness-side client tools (tools the caller implements, not the provider) use `executeClientToolTurn`** — the single-turn helper for tool-use conversations. Supply `clientTools: IAiClientTool[]` alongside any `tools: IAiServerToolConfig[]`; the helper returns `{ events: AsyncIterable<IAiStreamEvent>, nextTurn: Promise<Result<IAiClientToolTurnResult>> }` where `events` forwards **every** `IAiStreamEvent` the underlying stream emits — `text-delta`, `tool-event`, and the terminal `done` (carrying `usage`) and `error` — *plus* the three `client-tool-*` dispatch events this layer adds, and `nextTurn` awaits the complete round-trip result (`continuation`, `truncated`, `fullText`, `toolConflicts`, and `usage` — one provider call per invocation, so one usage; the round loop is the caller re-invoking with `continuation.messages` — the provider-format wire messages to re-supply on the next turn). `IAiClientTool` carries `config: IAiClientToolConfig` (name, description, `parametersSchema: ISchemaValidator<TParams>` — use `JsonSchema.object(...)` from `@fgv/ts-json-base`) and `execute: (args: unknown) => Promise<Result<unknown>>`. Type the tool as `IAiClientTool` (unparameterized, default `unknown`) and validate args inside `execute` via `parametersSchema.validate(args)` — the `execute` callback is contravariant in `TParams` so a typed `IAiClientTool<{key:string}>` is not assignable to `IAiClientTool<unknown>`. For multi-turn conversations pass `continuationMessages: continuation.messages` (type `ReadonlyArray<JsonObject>`) — `continuation.messages` is **cumulative** (replace each round, do not manually concatenate; the library prepends the inbound tail automatically so the array always covers all rounds so far) — these are provider-format wire objects appended after the current user turn. The exact wire-shape handling is per-provider: **Anthropic** projects each entry to `{ role, content }` (extra fields dropped; invalid entries skipped); **Gemini** projects to `{ role, parts }` (same shape guard); **OpenAI Responses / xAI** pass entries through verbatim with a `JsonObject` guard (since OpenAI Responses items are a `type`-keyed discriminated union whose fields differ per item). Consumers should not assume arbitrary fields round-trip on every provider — the high-fidelity round-trip is on the OpenAI/xAI path; Anthropic and Gemini preserve only the projected fields. Cross-provider continuation works on **all four providers**. **Do not put continuation wire objects in `messages`** (the unified `IChatRequest` conversation turns) — `continuationMessages` is a distinct post-current-turn axis whose provider-native fields the normalized `messages` path would strip. `IResolvedThinkingConfig` is exported from the packlet for callers that pre-resolve thinking options (e.g. `{ anthropicEffort: 'low' }`) and pass them directly to `executeClientToolTurn`. **Tool parameters authored as `JsonSchema.object(...)` work transparently on Gemini** — the adapter sanitizes draft-07-only keywords (`additionalProperties`, `$schema`) recursively before submission, so strict-by-default schemas don't need consumer pre-processing. **Gemini API constraint:** Gemini's `generateContent` forbids combining built-in grounding (`web_search`) with function calling in the same request — pick one. The library **pre-empts this with a named `Result.fail` before any wire call**, so you get a legible refusal rather than the provider's `INVALID_ARGUMENT` HTTP 400. **Completion diagnostic:** `IAiStreamDone.incompleteReason?: string` (`@public`) carries the OpenAI/xAI Responses `incomplete_details.reason` (`'max_output_tokens'`, `'content_filter'`, …) when `truncated === true`; absent when the stream completed normally. **Provider-drift instrumentation:** Anthropic and OpenAI Responses adapters maintain a `RECOGNIZED_*_EVENTS` allowlist and log a one-time `logger.warn` per stream per unrecognized SSE event name. Warning starts with the stable `ai-assist:unrecognized-event` tag (filter on this prefix to alert on provider-API evolution); includes a **default-safe structural payload preview** (top-level JSON keys + length — never field values) for triage; names the allowlist constant so a developer can find the right list to update. Production deployments wire the `ILogger` via the streaming-call params (`IProviderCompletionStreamParams.logger` / `IExecuteClientToolTurnParams.logger` — NOT via the per-adapter `IStreamApiConfig`, which carries only `{ baseUrl, apiKey, model }`); deployments that don't (default `NoOpLogger`) get a silent no-op. Ops triaging an active drift signal can opt in to the **raw payload preview** by setting `AI_ASSIST_UNRECOGNIZED_EVENT_FULL_PAYLOAD=1` in the environment — keep this off in production by default since SSE payloads can carry tool args / user-conversation text / other sensitive content. Gemini-side drift instrumentation is queued (JSON-chunk wire shape doesn't fit the SSE-event-name allowlist concept). **For embeddings (`text → vector`) use `callProviderEmbedding`/`callProxiedEmbedding`** — the cross-provider embedding primitive (third modality alongside completion and image generation). Batch in (`input: string \| string[]`), `number[][]` out, `Result`-wrapped. Two wire formats behind one dispatcher: `openai-embeddings` (`POST /embeddings`) serves **OpenAI** (`text-embedding-3-*`), **Ollama** (point `endpoint` at `http://localhost:11434/v1`), **openai-compat** self-hosted servers, and **Mistral** (`mistral-embed`); `gemini-embeddings` (`POST /models/{model}:batchEmbedContents`) serves **Google Gemini** (`gemini-embedding-001`) with its `taskType` retrieval-asymmetry knob. Capability is declared on `IAiProviderDescriptor.embedding: IAiEmbeddingModelCapability[]` (model-prefix matched, longest wins) and selects the model via the `embedding` `ModelSpecKey`. Knob handling (`dimensions`, `taskType`) is **no-op-where-unsupported, not a failure** — a caller passes `taskType: 'retrieval-query'` once and it maps to Gemini's wire `RETRIEVAL_QUERY` while being a logged no-op on the (symmetric) OpenAI-format providers, so the cross-provider call site never branches. Empty input short-circuits to an empty result with no wire call; a batch over the capability's `maxBatchSize` fails fast (no auto-chunking). xAI and Anthropic declare no embedding capability (no first-party endpoint) and reject up front. Vectors are `number[]` (not `Float32Array`) for JSON-wire fidelity — call `Float32Array.from(vector)` at the vector-store boundary; the library does not L2-normalize (Gemini MRL-truncated vectors may need it). **Prompt-cache token accounting (`IAiCompletionResponse.usage?: IAiCompletionUsage`, also on `IAiStreamDone`).** Sibling to `IAiEmbeddingResult.usage` — present when the provider reports it, absent otherwise, never guessed. `AiCacheReportingLevel` (`'reads' \| 'reads-and-writes'` — no `'none'` member; "nothing reported" is `usage` itself being absent) is **required, not optional** on `IAiCompletionUsage`, for the same reason `structuredOutput` is required: an absent `cacheWriteTokens` is three-ways ambiguous (no write happened / this API cannot report writes / a build predating the field) and `reports` disambiguates it by construction. Normalized per wire shape: Anthropic Messages and OpenAI Responses report `'reads-and-writes'`; OpenAI/xAI Chat Completions and Gemini `generateContent` report `'reads'` only — Chat Completions has no `cache_write_tokens` field at all (never defaulted to `0`), and Gemini has no write concept in a `generateContent` call (writes are the out-of-band `cachedContents` resource, out of scope). The OpenAI/xAI Responses route is shared code with diverging behavior: `reports` is derived from **field presence** (`input_tokens_details.cache_write_tokens` present, even `0` → `'reads-and-writes'`; absent entirely → `'reads'`), not from provider identity — but only once a descriptor has cleared `AiAssist.supportsCacheUsageReporting`, the gate applied at the four completion sites it governs (non-streaming Chat Completions and Responses, Responses streaming, and `executeClientToolTurn`'s direct Responses call — streaming Chat Completions is gated by `supportsStreamUsageOption` instead, which is OpenAI-only, so xAI gets no usage on that one path) before any normalization runs, since those sites are shared by every `apiFormat: 'openai'` descriptor (Groq, Mistral, Ollama, self-hosted `openai-compat`), not just OpenAI and xAI Grok; an unconfirmed descriptor — including a future one — gets `usage: undefined` rather than a guess derived from whatever ordinary usage shape its wire happens to send. Gemini's footgun: `cachedContentTokenCount` sits **inside** `promptTokenCount`, unlike OpenAI where it sits in a sibling `…_details` object next to a separate total — `uncachedInputTokens` subtracts to correct for it, but only when the cached figure is itself known (never assumed zero from a merely-absent field). Streaming is covered from the same commit, not a follow-on: Anthropic merges `message_start`'s initial reads/writes with `message_delta`'s final `output_tokens`; OpenAI Chat Completions streaming requires opting in via `stream_options: { include_usage: true }` — sent only for `descriptor.id === 'openai'` (`AiAssist.supportsStreamUsageOption`), since the shared adapter also carries providers whose tolerance for an unrecognized request field is unverified; usage stays silently absent for every other provider on this path, and the populated usage arrives on a terminal `choices: []` chunk, with `usage: null` on every chunk before it once the option is sent; OpenAI/xAI Responses streaming reads `response.completed`'s `response.usage`; Gemini repeats `usageMetadata` on every chunk with running totals; the adapter keeps the last one. `raw?: JsonObject` on `IAiCompletionUsage` carries the provider's own unnormalized usage block for anything the normalized shape drops (e.g. xAI's `cost_in_usd_ticks`). **Prompt-cache breakpoint emission (`IProviderCompletionParams.cache?: IAiCacheRequest`).** `IAiCacheRequest` carries `systemBreakpoints?: ReadonlyArray<number>` — strictly ascending UTF-16 offsets into `system`, each marking the end of a cacheable prefix — and `cacheKey?: string`, an opaque cache-routing key. Both are optional and additive: a request with no `cache` is byte-for-byte the same request a build predating this feature would send. `AiAssist.validateAiCacheRequest`/`validateCacheBreakpoints` **fail loudly and never clamp** — a non-ascending, out-of-range (not `> 0` and `< system.length`), or over-cap (when a `maxBreakpointWrites` cap is supplied) offset returns `Result.fail`, never a silently-trimmed plan. On **Anthropic**, `system` is split into content blocks at each breakpoint, with `cache_control: { type: 'ephemeral' }` on the block that ends each cacheable prefix (was a plain string). On **OpenAI Chat Completions and Responses**, the leading system message/item is split into content parts carrying `prompt_cache_breakpoint: { mode: 'explicit' }` — `prompt_cache_options` is never touched, so OpenAI's own implicit breakpoint and default caching mode are undisturbed; `prompt_cache_key` is sent (both routes) when `cacheKey` is supplied. **Breakpoints and the routing key are gated separately, because they are different capabilities with different support sets.** Breakpoint splitting is gated to `AiAssist.supportsPromptCacheBreakpoints(descriptor)` (`true` only for `descriptor.id === 'openai'`), the same write-side-tolerance reasoning as `supportsStreamUsageOption` — the shared adapter also carries xAI/Groq/Mistral/Ollama/`openai-compat`, none confirmed to tolerate a restructured `system` content array. The routing key is gated to `AiAssist.supportsPromptCacheRouting(descriptor)`, which returns an `IAiPromptCacheRoutingSupport` describing the **per-route transport** rather than a boolean: OpenAI takes `prompt_cache_key` as a body field on both routes; **xAI takes an `x-grok-conv-id` header on Chat Completions and `prompt_cache_key` on Responses**. xAI needs it — its cache matches byte-for-byte from the start of the messages array but is **per-server and evictable**, so two requests sharing a prefix can miss when routed to different servers. Measured on `grok-4.3`: a varying-tail warm call reads **1.9%** cached without the key and **99.7%** with it. A descriptor supporting neither still gets a request — body *and headers* — byte-identical to one a caller omitting `cache` would have sent. **Gemini has no breakpoint mechanism and ignores `cache` entirely.** There is no model-keyed capability/cap table (`IAiCacheCapability`) backing `maxBreakpointWrites` — none was built in any slice of this feature, and a caller building breakpoints from `@fgv/ts-prompt-assist`'s three-level stability vocabulary never needs one, since that vocabulary provably never emits more than two breakpoints. **Streaming carries `cache` too** (`IProviderCompletionStreamParams.cache?` / `IExecuteClientToolTurnParams.cache?: IAiCacheRequest`) — the same plan, the same `validateAiCacheRequest` contract, and the identical per-descriptor gating reused verbatim from the non-streaming dispatch (Anthropic ungated, OpenAI/xAI breakpoints+routing gated by `supportsPromptCacheBreakpoints`/`supportsPromptCacheRouting`, Gemini ignores it). `executeClientToolTurn` represents one round of a multi-round tool loop, so `cache` is validated and applied fresh on **every** call against that call's own `system` — never cached across rounds, since a later round's system can differ from an earlier one's. `callProxiedCompletionStream` forwards `cache` as a plain `body.cache` field exactly as `callProxiedCompletion` does; unlike `endpoint`, a proxy that ignores it degrades to the no-cache request it would have sent anyway rather than misdirecting the request, so it is forwarded rather than refused. See `@fgv/ts-prompt-assist`'s `toCacheRequest` for deriving a plan from a resolved composition rather than hand-computing offsets. |
 ---
@@ -43,7 +43,7 @@
 - **Need constant-time byte comparison?** → `ICryptoProvider.timingSafeEqual(a, b)` from `@fgv/ts-extras/crypto-utils`. Returns `boolean` directly (not `Result`). Node impl delegates to `crypto.timingSafeEqual`; browser impl uses XOR-walk accumulator. Never use `===` or loop with early return for security-sensitive comparisons.
 - **Asking an LLM for JSON and getting a validated `T`?** → `AiAssist.generateJsonCompletion<T>({ converter, ... })` from `@fgv/ts-extras/ai-assist`. Tolerates Markdown fences, preamble, and trailing prose by default. Don't reimplement fence-stripping in consumers. **Author `converter` as `JsonSchema.object({...})`** (from `@fgv/ts-json-base`) rather than `Converters.object({...})` and the library also *tells the provider* — one object is the wire schema and the reply validator, so they cannot drift, and there is no second parameter to keep in sync. A plain `Converter` still works and sends nothing.
 - **Need the provider to constrain its output, not just be asked to?** → `structuredOutput` on any `callProviderCompletion` / `callProxiedCompletion` request: `{ mode: 'schema', schema }` for shape, `{ mode: 'json-object' }` for syntactic validity only. Read **`response.structuredOutput`** to learn what was actually enforced (`'none'` | `'json-mode'` | `'schema'` | `'tool-forced'`) — it is **required on every response**, because you cannot know up front which concrete model will serve you (a `tier` request cascades, aliases resolve at call time), so the report rides on the response rather than being a lookup you do yourself. It says what was **sent**, never whether *this* reply conforms — that is your converter's job and the library will not re-derive it. Unsupported combinations **degrade by default and say so**; pass `onUnsupported: 'fail'` when the output is persisted or put on a wire. **Don't hand-roll a `response_format` per provider** — the four wire shapes differ in more than field names, and Anthropic has none at all (it forces a tool, and the library re-serializes the tool input back into `content` so your converter does not branch).
-- **Running a tool-use conversation with harness-side client tools?** → `AiAssist.executeClientToolTurn({ descriptor, apiKey, system?, messages, clientTools, tools?, model?, resolvedThinking? })` from `@fgv/ts-extras/ai-assist`. Like every turn entry point it takes the unified `{ system?, messages }` request shape (the last `messages` entry is the current user turn; preceding entries are history). Returns `{ events, nextTurn }` — consumer drives the outer multi-turn loop. Pass `continuationMessages: continuation.messages` on subsequent turns — `continuation.messages` is **cumulative** (replace each round, do not manually concatenate); do NOT put continuation wire objects in `messages` (they are a distinct post-current-turn axis). Works on **all four providers** (Anthropic, OpenAI Responses, Gemini, xAI via OpenAI). Type client tools as `IAiClientTool` (unparameterized) and validate args inside `execute` — the callback is contravariant in `TParams`. Author the `parametersSchema` with `JsonSchema.object(...)` from `@fgv/ts-json-base`; `schema.validate(args)` is the round-trip verify step. **Model errors continue the turn; host-machinery errors end it.** An unknown tool name, an arg-validation failure, an `execute` failure and a gate `deny` all yield a `client-tool-result` with `isError: true` and let the model react on the next round; only a gate `fail`/reject terminates. So a `nextTurn` that succeeds does not mean every tool call succeeded — check `continuation.toolCallsSummary[].isError` if you need to know. (The unknown-tool case terminated the turn until 2026-09; a model that read a prose trailer as a tool call ended a turn that had every chance to recover.) **Provider tool exclusions are declared, not branched on.** `IAiProviderDescriptor.serverToolsExclusiveWithClientTools` names the server tools a provider refuses to accept alongside client tools — only Gemini declares anything (`['web_search']`, because `generateContent` HTTP-400s on grounding + `function_declarations`). `resolveToolConflicts(descriptor, serverTools, clientTools, policy?)` applies it generically, so **a host never writes `if (descriptor.apiFormat === 'gemini')` in its tool assembly** and the day a provider lifts its limit only the descriptor changes. `toolConflictPolicy` on the turn defaults to `'drop-server-tools'` (keep the client tools the host registered for this turn, drop the grounding); `'prefer-server-tools'` is the mirror; `'fail'` refuses up front, before any wire call. The turn result's **required** `toolConflicts: IAiToolConflictReport` names what was dropped and under which policy — a degraded turn is never a silent one, so a host can tell the person web search was unavailable. `resolveEffectiveTools` is the sibling that filters server tools against `supportedTools` and is unchanged; it cannot see client tools, which is why the exclusion needed its own resolver.
+- **Running a tool-use conversation with harness-side client tools?** → `AiAssist.executeClientToolTurn({ descriptor, apiKey, system?, messages, clientTools, tools?, model?, resolvedThinking? })` from `@fgv/ts-extras/ai-assist`. Like every turn entry point it takes the unified `{ system?, messages }` request shape (the last `messages` entry is the current user turn; preceding entries are history). Returns `{ events, nextTurn }` — consumer drives the outer multi-turn loop. **`nextTurn` only resolves once `events` has been iterated to completion** — it is settled from inside the generator backing `events`, so awaiting it alone hangs and never drains the response body. **Token usage is on both surfaces:** `events` forwards the terminal `done` event with its `usage?: IAiCompletionUsage`, and the same object is on the turn result as `IAiClientToolTurnResult.usage`, so a host accumulating per-turn cost never has to scrape the stream. One provider call per invocation means each result's `usage` already *is* one round's — there is no `perRound` array because it could only ever have one entry. Optional, not required like `toolConflicts`: the library always knows what it did to your tools, but cannot always know what a turn cost. Absent means **no normalized usage is exposed** — either the provider reported nothing, or it reported something the library declines to normalize because the descriptor is outside `supportsCacheUsageReporting` (groq/mistral/ollama/openai-compat share the OpenAI-format adapter with unverified usage shapes). Never a fabricated zero. Pass `continuationMessages: continuation.messages` on subsequent turns — `continuation.messages` is **cumulative** (replace each round, do not manually concatenate); do NOT put continuation wire objects in `messages` (they are a distinct post-current-turn axis). Works on **all four providers** (Anthropic, OpenAI Responses, Gemini, xAI via OpenAI) — a statement about provider coverage, not about runtime: `executeClientToolTurn` does not pre-flight `streamingCorsRestricted` and has no proxied entry point, so a **browser** client-tool turn against a CORS-restricted provider (today, xAI) reaches a direct fetch and fails there rather than with a `Result.fail`. Type client tools as `IAiClientTool` (unparameterized) and validate args inside `execute` — the callback is contravariant in `TParams`. Author the `parametersSchema` with `JsonSchema.object(...)` from `@fgv/ts-json-base`; `schema.validate(args)` is the round-trip verify step. **Model errors continue the turn; host-machinery errors end it.** An unknown tool name, an arg-validation failure, an `execute` failure and a gate `deny` all yield a `client-tool-result` with `isError: true` and let the model react on the next round; only a gate `fail`/reject terminates. So a `nextTurn` that succeeds does not mean every tool call succeeded — check `continuation.toolCallsSummary[].isError` if you need to know. (The unknown-tool case terminated the turn until 2026-09; a model that read a prose trailer as a tool call ended a turn that had every chance to recover.) **Provider tool exclusions are declared, not branched on.** `IAiProviderDescriptor.serverToolsExclusiveWithClientTools` names the server tools a provider refuses to accept alongside client tools — only Gemini declares anything (`['web_search']`, because `generateContent` HTTP-400s on grounding + `function_declarations`). `resolveToolConflicts(descriptor, serverTools, clientTools, policy?)` applies it generically, so **a host never writes `if (descriptor.apiFormat === 'gemini')` in its tool assembly** and the day a provider lifts its limit only the descriptor changes. `toolConflictPolicy` on the turn defaults to `'drop-server-tools'` (keep the client tools the host registered for this turn, drop the grounding); `'prefer-server-tools'` is the mirror; `'fail'` refuses up front, before any wire call. The turn result's **required** `toolConflicts: IAiToolConflictReport` names what was dropped and under which policy — a degraded turn is never a silent one, so a host can tell the person web search was unavailable. `resolveEffectiveTools` is the sibling that filters server tools against `supportedTools` and is unchanged; it cannot see client tools, which is why the exclusion needed its own resolver.
 - **Diagnosing an OpenAI/xAI Responses stream that completes empty?** → Check `IAiStreamDone.incompleteReason?: string` on the `done` event. `'max_output_tokens'` → reasoning + tools consumed the output budget (raise the cap or shorten the prompt); `'content_filter'` → safety filter blocked the response. Absent → stream completed normally; if you still see no text, pass an `ILogger` to the streaming call (`callProviderCompletionStream({ ..., logger })` or `executeClientToolTurn({ ..., logger })`) and look for `ai-assist:unrecognized-event` warns — the streaming adapter probably saw an event family it doesn't handle yet (provider-API evolution).
 - **Alerting on provider-API evolution affecting `@fgv/ts-extras/ai-assist`?** → Pass an `ILogger` via the higher-level streaming params (`IProviderCompletionStreamParams.logger`, `IExecuteClientToolTurnParams.logger`, etc.) and filter on the stable `ai-assist:unrecognized-event` warn prefix. The streaming helpers thread the logger down to the per-adapter unknown-event sites; the per-adapter `IStreamApiConfig` itself is just `{ baseUrl, apiKey, model }` and is not where consumers wire the logger. The Anthropic and OpenAI Responses adapters maintain per-stream-dedup'd allowlists of recognized SSE event names; an unrecognized event triggers one warn per stream per name including a length-capped structural payload preview (top-level JSON keys + length by default; raw payload via the `AI_ASSIST_UNRECOGNIZED_EVENT_FULL_PAYLOAD` env var). Use this in production to alert when a provider's wire shape changes (likely class of issue: adapter parse miss → silent feature degradation). Gemini's drift instrumentation is queued separately (different wire shape).
 - **Stripping LLM Markdown fences from raw text?** → `AiAssist.extractJsonText` (default extractor) or `AiAssist.fencedStringifiedJson({ extractor, inner })` (extension point) from `@fgv/ts-extras/ai-assist`.
@@ -68,6 +68,7 @@
 <!-- BEGIN GENERATED: recent-additions -->
+- **2026-09-23** — A tool-augmented or streamed chat turn can now carry prompt-cache breakpoints and a routing key, closing the one remaining hole (streaming) in ai-assist's prompt-cache emission surface. ([#688](https://github.com/ErikFortune/fgv/pull/688))
 - **2026-09-07** — ai-assist now places explicit prompt-cache breakpoints on Anthropic and OpenAI requests built from a ts-prompt-assist resolve, reports cache usage across every provider that supplies it, and diagnoses a cache-hostile composition before any request is sent. ([#671](https://github.com/ErikFortune/fgv/pull/671))
 - **2026-09-07** — Thinking config loses a required provider field that gated nothing, and gains 'none' — the cross-provider spelling for off that every provider had except the generic vocabulary. ([#667](https://github.com/ErikFortune/fgv/pull/667))
 - **2026-09-02** — Shipped: a rendered template, and a resolved prompt, can now say what they are made of — order, absolute size and binding provenance per section, with offsets computed during the render because recovering them by search is silently wrong. ([#663](https://github.com/ErikFortune/fgv/pull/663))

package/dist/packlets/ai-assist/chatRequestBuilders.js CHANGED Viewed

@@ -19,8 +19,8 @@
 // SOFTWARE.
 /**
  * Per-format chat request shape builders. Shared between the synchronous
- * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire
- * shapes stay consistent.
+ * (`completionClient.ts`) and streaming (`streamingClient.ts`) paths so the
+ * wire shapes stay consistent.
  *
  * @packageDocumentation
  */

package/dist/packlets/ai-assist/chatRequestBuilders.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"chatRequestBuilders.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/chatRequestBuilders.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/*\n Per-format chat request shape builders. Shared between the synchronous\n * (`apiClient.ts`) and streaming (`streamingClient.ts`) paths so the wire\n * shapes stay consistent.\n \n @packageDocumentation\n /\n\nimport { isJsonObject, type JsonObject } from '@fgv/ts-json-base';\nimport { type Converter, Converters, fail, Result, succeed } from '@fgv/ts-utils';\n\nimport { type IAiCacheRequest, splitSystemForCache } from './cacheRequest';\nimport { AiPrompt, type IAiImageAttachment, type IChatMessage, toDataUrl } from './model';\n\n/\n The result of splitting an {@link AiAssist.IChatRequest} into the per-builder\n * inputs: the current turn (as an {@link AiPrompt}, carrying system + the final\n * user message + any attachments) and the preceding conversation history.\n * @internal\n /\nexport interface ISplitChatRequest {\n /* The current turn lowered to an {@link AiPrompt} (system + user + attachments). /\n readonly prompt: AiPrompt;\n /* Prior conversation history — every message before the current turn. /\n readonly head: ReadonlyArray<IChatMessage>;\n}\n\n/\n Splits a unified {@link AiAssist.IChatRequest} into `{ prompt, head }` for the\n * per-provider builders. The last message is the current `user` turn; the\n * preceding messages are history (`head`). This is the single linearization\n * shared by every turn entry point, so the completion path and the client-tool\n * turn path place history at the identical position relative to the current turn.\n \n Fails when `messages` is empty (no current turn) or when the last message is\n * not a `user` turn — relabelling a trailing assistant message as the user turn\n * would be a silent footgun, so it is rejected loudly instead.\n \n @internal\n /\nexport function splitChatRequest(\n system: string \| undefined,\n messages: ReadonlyArray<IChatMessage>\n): Result<ISplitChatRequest> {\n if (messages.length === 0) {\n return fail('messages must contain at least one entry (the current user turn)');\n }\n const current = messages[messages.length - 1];\n if (current.role !== 'user') {\n return fail(`the last message must be the current user turn (role 'user'); got '${current.role}'`);\n }\n const head = messages.slice(0, messages.length - 1);\n const prompt = new AiPrompt(current.content, system ?? '', current.attachments);\n return succeed({ prompt, head });\n}\n\n/\n Rebuilds the ordered messages for a proxy wire body so that only the current\n * turn can carry attachments — history (non-current) messages are reduced to\n * `{ role, content }`. The direct per-provider builders already drop attachments\n * on history turns (only the current user turn's attachments are honored), so\n * normalizing here keeps the proxy wire shape consistent with the direct paths\n * and avoids transmitting attachment payloads the upstream provider would ignore.\n \n @internal\n /\nexport function normalizeOutboundMessages(split: ISplitChatRequest): IChatMessage[] {\n return [\n ...split.head.map((m) => ({ role: m.role, content: m.content })),\n ...split.prompt.toRequest().messages\n ];\n}\n\n/\n Converter for a rawTail message entry. Narrows a `JsonObject` to\n * `{ role: string; content: string \| unknown[] }` at runtime using the\n * Converter pattern. Entries that fail validation are silently skipped — the\n * surrounding function is infallible, and a malformed continuation message is\n * better omitted than transmitted verbatim.\n * @internal\n /\nconst rawTailMessageConverter: Converter<{ role: 'user' \| 'assistant'; content: string \| unknown[] }> =\n Converters.object<{ role: 'user' \| 'assistant'; content: string \| unknown[] }>(\n {\n role: Converters.enumeratedValue<'user' \| 'assistant'>(['user', 'assistant']),\n content: Converters.oneOf<string \| unknown[]>([\n Converters.string,\n Converters.isA('array', (v): v is unknown[] => Array.isArray(v))\n ])\n },\n { strict: false }\n );\n\n/\n Converter for an OpenAI / xAI Responses API `rawTail` item. These are\n * provider-native input items (`function_call`, `function_call_output`) whose\n * fields differ per item type, so — unlike the Anthropic `{ role, content }`\n * projection — the whole object is preserved verbatim.\n \n The static input is already typed `JsonObject`, so the `isJsonObject` guard\n * is a runtime backstop, not a compile-time narrowing: continuation messages\n * originate from a prior turn's `IAiClientToolContinuation.messages` and a\n * consumer may persist and reload them through untyped JSON before passing them\n * back. The guard preserves the same \"a malformed continuation message is\n * better omitted than transmitted verbatim\" posture as the Anthropic path —\n * non-object entries fail conversion and are skipped by the caller.\n * @internal\n /\nconst openAiRawTailItemConverter: Converter<JsonObject> = Converters.isA<JsonObject>(\n 'JsonObject',\n (v): v is JsonObject => isJsonObject(v)\n);\n\n/\n Converter for a Gemini `rawTail` item. Gemini continuation messages are\n * `{ role, parts }` turns (a model turn with `functionCall` parts followed by a\n * user turn with `functionResponse` parts). Narrows a `JsonObject` to\n * `{ role: 'user' \| 'model'; parts: Array<Record<string, unknown>> }`; entries\n * that fail validation are skipped by the caller.\n * @internal\n /\nconst geminiRawTailMessageConverter: Converter<{\n role: 'user' \| 'model';\n parts: unknown[];\n}> = Converters.object<{ role: 'user' \| 'model'; parts: unknown[] }>(\n {\n role: Converters.enumeratedValue<'user' \| 'model'>(['user', 'model']),\n // `parts` is preserved verbatim and serialized into the request body, so the\n // element shape is not narrowed here — `Array.isArray` soundly guarantees\n // `unknown[]` (narrowing to `Record<string, unknown>[]` would be an unchecked cast).\n parts: Converters.isA('array', (v): v is unknown[] => Array.isArray(v))\n },\n { strict: false }\n);\n\n/\n Optional history (`head`) and raw continuation (`rawTail`) messages to weave\n * around the prompt's current user message.\n \n @internal\n /\nexport interface IBuildMessagesOptions {\n /\n Prior conversation history inserted between the system prompt and the\n * prompt's current user message (multi-turn chat / correction retries). The\n * single ordered linearization is `[system, ...head, user, ...rawTail]`.\n /\n readonly head?: ReadonlyArray<IChatMessage>;\n /\n Raw JSON objects appended after the prompt's user message. Used to\n * inject provider-specific continuation messages (e.g. Anthropic assistant\n * turns with thinking blocks, OpenAI Responses `function_call` /\n * `function_call_output` items, Gemini `functionCall` / `functionResponse`\n * turns) that cannot be expressed as plain {@link IChatMessage} objects.\n \n Each builder applies its own provider-specific shape guard:\n * - {@link buildAnthropicMessages} projects each entry to `{ role, content }`.\n * - {@link buildMessages} (OpenAI / xAI Responses) preserves each item\n * verbatim (item fields differ per `type`), guarding only that it is a\n * JSON object.\n * - {@link buildGeminiContents} projects each entry to `{ role, parts }`.\n \n Entries that fail their builder's shape check are silently skipped (the\n * caller is responsible for supplying well-formed continuation messages).\n * Appended after the current user message.\n /\n readonly rawTail?: ReadonlyArray<JsonObject>;\n}\n\n/\n Builds the messages array from prompt + optional history (`head`) and raw\n * continuation (`rawTail`) messages. The caller supplies the system content\n * (string when no cache breakpoints are requested, parts array when they are\n * — see {@link buildOpenAiChatSystemContent} / {@link buildOpenAiResponsesSystemContent})\n * and the user content (string for text-only, parts array for vision prompts),\n * since both shapes differ by format.\n \n `rawTail` items (OpenAI / xAI Responses `function_call` /\n * `function_call_output` continuation items) are appended verbatim after the\n * user message — their fields differ per item `type`, so they are preserved\n * rather than projected. The return type is `Array<Record<string, unknown>>`\n * to accommodate both `{ role, content }` messages and these heterogeneous\n * input items.\n \n @internal\n /\nexport function buildMessages(\n systemContent: string \| unknown[],\n userContent: string \| unknown[],\n options?: IBuildMessagesOptions\n): Array<Record<string, unknown>> {\n const messages: Array<Record<string, unknown>> = [{ role: 'system', content: systemContent }];\n if (options?.head) {\n for (const msg of options.head) {\n messages.push({ role: msg.role, content: msg.content });\n }\n }\n messages.push({ role: 'user', content: userContent });\n // OpenAI / xAI Responses continuation items (function_call /\n // function_call_output) are appended verbatim — their field set differs per\n // item type, so the whole object is preserved rather than projected.\n if (options?.rawTail) {\n for (const item of options.rawTail) {\n const converted = openAiRawTailItemConverter.convert(item);\n if (converted.isSuccess()) {\n messages.push(converted.value);\n }\n }\n }\n return messages;\n}\n\n/\n Splits `segments` (from {@link splitSystemForCache}) into a single string when nothing carries\n * a breakpoint, or a content-part array in `partType`'s shape (with `prompt_cache_breakpoint` on\n * the parts that end a cacheable prefix) otherwise.\n \n @remarks\n * A single non-breakpointed segment (the common case: `cache` omitted or empty) returns the\n * plain string, byte-identical to a request built before cache support existed. Shared by\n * {@link buildOpenAiChatSystemContent} and {@link buildOpenAiResponsesSystemContent}, whose only\n * difference is the content-part `type` OpenAI's two APIs use (`'text'` vs `'input_text'`,\n * research.md §1.2).\n * @internal\n /\nfunction toOpenAiSystemContent(\n segments: ReadonlyArray<{ readonly text: string; readonly cacheBreakpoint: boolean }>,\n partType: 'text' \| 'input_text'\n): string \| unknown[] {\n if (segments.length === 1 && !segments[0].cacheBreakpoint) {\n return segments[0].text;\n }\n return segments.map((seg) => ({\n type: partType,\n text: seg.text,\n ...(seg.cacheBreakpoint\n ? {\n // eslint-disable-next-line @typescript-eslint/naming-convention -- wire field name\n prompt_cache_breakpoint: { mode: 'explicit' }\n }\n : {})\n }));\n}\n\n/\n Builds the system content for OpenAI Chat Completions, splitting `system` at `cache`'s\n * breakpoints (design.md §6.3) into content parts each carrying\n * `prompt_cache_breakpoint: { mode: 'explicit' }` where a cacheable prefix ends.\n * `prompt_cache_options` is never touched — OpenAI keeps its own implicit breakpoint and writes\n * up to the latest three of ours on top of it. Returns the plain `system` string when `cache` is\n * `undefined` or declares no breakpoints, byte-identical to a request built before cache support\n * existed.\n * @internal\n /\nexport function buildOpenAiChatSystemContent(\n system: string,\n cache: IAiCacheRequest \| undefined\n): Result<string \| unknown[]> {\n return splitSystemForCache(system, cache).onSuccess((segments) =>\n succeed(toOpenAiSystemContent(segments, 'text'))\n );\n}\n\n/\n Builds the system content for the OpenAI / xAI Responses API. Identical to\n * {@link buildOpenAiChatSystemContent} except for the content-part type (`'input_text'` instead\n * of `'text'`) — see research.md §1.2, \"Where the breakpoint may be attached.\"\n * @internal\n /\nexport function buildOpenAiResponsesSystemContent(\n system: string,\n cache: IAiCacheRequest \| undefined\n): Result<string \| unknown[]> {\n return splitSystemForCache(system, cache).onSuccess((segments) =>\n succeed(toOpenAiSystemContent(segments, 'input_text'))\n );\n}\n\n/\n Builds the Anthropic `system` field, splitting `system` at `cache`'s breakpoints into content\n * blocks carrying `cache_control: { type: 'ephemeral' }` on the block that ends each cacheable\n * prefix (design.md §6.1). Returns the plain `system` string when `cache` is `undefined` or\n * declares no breakpoints — byte-identical to `system: prompt.system` from a request built\n * before cache support existed.\n * @internal\n /\nexport function buildAnthropicSystem(\n system: string,\n cache: IAiCacheRequest \| undefined\n): Result<string \| unknown[]> {\n return splitSystemForCache(system, cache).onSuccess((segments) => {\n if (segments.length === 1 && !segments[0].cacheBreakpoint) {\n return succeed<string \| unknown[]>(segments[0].text);\n }\n return succeed<string \| unknown[]>(\n segments.map((seg) => ({\n type: 'text',\n text: seg.text,\n ...(seg.cacheBreakpoint ? { cache_control: { type: 'ephemeral' } } : {})\n }))\n );\n });\n}\n\n/\n Builds the user content for OpenAI Chat Completions when attachments are\n * present. Returns a string when there are no attachments.\n \n @internal\n /\nexport function buildOpenAiChatUserContent(prompt: AiPrompt): string \| unknown[] {\n if (prompt.attachments.length === 0) {\n return prompt.user;\n }\n return [\n { type: 'text', text: prompt.user },\n ...prompt.attachments.map((att: IAiImageAttachment) => ({\n type: 'image_url',\n image_url: {\n url: toDataUrl(att),\n ...(att.detail !== undefined ? { detail: att.detail } : {})\n }\n }))\n ];\n}\n\n/\n Builds the user content for OpenAI / xAI Responses API when attachments\n * are present. Responses API uses `input_text` / `input_image` part types,\n * distinct from Chat Completions' `text` / `image_url`.\n \n @internal\n /\nexport function buildOpenAiResponsesUserContent(prompt: AiPrompt): string \| unknown[] {\n if (prompt.attachments.length === 0) {\n return prompt.user;\n }\n return [\n { type: 'input_text', text: prompt.user },\n ...prompt.attachments.map((att: IAiImageAttachment) => ({\n type: 'input_image',\n image_url: toDataUrl(att),\n ...(att.detail !== undefined ? { detail: att.detail } : {})\n }))\n ];\n}\n\n/\n Builds the user-message content for Anthropic when attachments are present.\n \n @internal\n /\nexport function buildAnthropicUserContent(prompt: AiPrompt): string \| unknown[] {\n if (prompt.attachments.length === 0) {\n return prompt.user;\n }\n return [\n { type: 'text', text: prompt.user },\n ...prompt.attachments.map((att: IAiImageAttachment) => ({\n type: 'image',\n source: {\n type: 'base64',\n media_type: att.mimeType,\n data: att.base64\n }\n }))\n ];\n}\n\n/\n Builds the Gemini `parts` array for the user turn, including any image\n * attachments as `inlineData` parts.\n \n @internal\n /\nexport function buildGeminiUserParts(prompt: AiPrompt): Array<Record<string, unknown>> {\n const parts: Array<Record<string, unknown>> = [{ text: prompt.user }];\n for (const att of prompt.attachments) {\n parts.push({ inlineData: { mimeType: att.mimeType, data: att.base64 } });\n }\n return parts;\n}\n\n/\n Builds the Anthropic messages array, weaving any `head` history messages\n * between implicit system + the prompt's user message and appending `rawTail`\n * continuation messages after. System messages are filtered out (Anthropic uses\n * a top-level system field).\n \n @internal\n /\nexport function buildAnthropicMessages(\n prompt: AiPrompt,\n options?: IBuildMessagesOptions\n): Array<{ role: string; content: string \| unknown[] }> {\n const messages: Array<{ role: string; content: string \| unknown[] }> = [];\n if (options?.head) {\n for (const msg of options.head) {\n if (msg.role !== 'system') {\n messages.push({ role: msg.role, content: msg.content });\n }\n }\n }\n messages.push({ role: 'user', content: buildAnthropicUserContent(prompt) });\n if (options?.rawTail) {\n for (const msg of options.rawTail) {\n const converted = rawTailMessageConverter.convert(msg);\n if (converted.isSuccess()) {\n messages.push(converted.value);\n }\n }\n }\n return messages;\n}\n\n/\n Builds the Gemini `contents` array, weaving any `head` history messages before\n * the prompt's user parts and appending `rawTail` continuation messages after.\n * System messages are filtered out (Gemini uses a top-level systemInstruction\n * field) and assistant roles are mapped to Gemini's `model` role.\n \n @internal\n */\nexport function buildGeminiContents(\n prompt: AiPrompt,\n options?: IBuildMessagesOptions\n): Array<{ role: string; parts: unknown[] }> {\n const contents: Array<{ role: string; parts: unknown[] }> = [];\n if (options?.head) {\n for (const msg of options.head) {\n if (msg.role !== 'system') {\n contents.push({\n role: msg.role === 'assistant' ? 'model' : msg.role,\n parts: [{ text: msg.content }]\n });\n }\n }\n }\n contents.push({ role: 'user', parts: buildGeminiUserParts(prompt) });\n // Gemini continuation turns (model `functionCall` parts + user\n // `functionResponse` parts) are projected to `{ role, parts }`.\n if (options?.rawTail) {\n for (const item of options.rawTail) {\n const converted = geminiRawTailMessageConverter.convert(item);\n if (converted.isSuccess()) {\n contents.push(converted.value);\n }\n }\n }\n return contents;\n}\n"]}
1	+ {"version":3,"file":"chatRequestBuilders.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/chatRequestBuilders.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/*\n Per-format chat request shape builders. Shared between the synchronous\n * (`completionClient.ts`) and streaming (`streamingClient.ts`) paths so the\n * wire shapes stay consistent.\n \n @packageDocumentation\n /\n\nimport { isJsonObject, type JsonObject } from '@fgv/ts-json-base';\nimport { type Converter, Converters, fail, Result, succeed } from '@fgv/ts-utils';\n\nimport { type IAiCacheRequest, splitSystemForCache } from './cacheRequest';\nimport { AiPrompt, type IAiImageAttachment, type IChatMessage, toDataUrl } from './model';\n\n/\n The result of splitting an {@link AiAssist.IChatRequest} into the per-builder\n * inputs: the current turn (as an {@link AiPrompt}, carrying system + the final\n * user message + any attachments) and the preceding conversation history.\n * @internal\n /\nexport interface ISplitChatRequest {\n /* The current turn lowered to an {@link AiPrompt} (system + user + attachments). /\n readonly prompt: AiPrompt;\n /* Prior conversation history — every message before the current turn. /\n readonly head: ReadonlyArray<IChatMessage>;\n}\n\n/\n Splits a unified {@link AiAssist.IChatRequest} into `{ prompt, head }` for the\n * per-provider builders. The last message is the current `user` turn; the\n * preceding messages are history (`head`). This is the single linearization\n * shared by every turn entry point, so the completion path and the client-tool\n * turn path place history at the identical position relative to the current turn.\n \n Fails when `messages` is empty (no current turn) or when the last message is\n * not a `user` turn — relabelling a trailing assistant message as the user turn\n * would be a silent footgun, so it is rejected loudly instead.\n \n @internal\n /\nexport function splitChatRequest(\n system: string \| undefined,\n messages: ReadonlyArray<IChatMessage>\n): Result<ISplitChatRequest> {\n if (messages.length === 0) {\n return fail('messages must contain at least one entry (the current user turn)');\n }\n const current = messages[messages.length - 1];\n if (current.role !== 'user') {\n return fail(`the last message must be the current user turn (role 'user'); got '${current.role}'`);\n }\n const head = messages.slice(0, messages.length - 1);\n const prompt = new AiPrompt(current.content, system ?? '', current.attachments);\n return succeed({ prompt, head });\n}\n\n/\n Rebuilds the ordered messages for a proxy wire body so that only the current\n * turn can carry attachments — history (non-current) messages are reduced to\n * `{ role, content }`. The direct per-provider builders already drop attachments\n * on history turns (only the current user turn's attachments are honored), so\n * normalizing here keeps the proxy wire shape consistent with the direct paths\n * and avoids transmitting attachment payloads the upstream provider would ignore.\n \n @internal\n /\nexport function normalizeOutboundMessages(split: ISplitChatRequest): IChatMessage[] {\n return [\n ...split.head.map((m) => ({ role: m.role, content: m.content })),\n ...split.prompt.toRequest().messages\n ];\n}\n\n/\n Converter for a rawTail message entry. Narrows a `JsonObject` to\n * `{ role: string; content: string \| unknown[] }` at runtime using the\n * Converter pattern. Entries that fail validation are silently skipped — the\n * surrounding function is infallible, and a malformed continuation message is\n * better omitted than transmitted verbatim.\n * @internal\n /\nconst rawTailMessageConverter: Converter<{ role: 'user' \| 'assistant'; content: string \| unknown[] }> =\n Converters.object<{ role: 'user' \| 'assistant'; content: string \| unknown[] }>(\n {\n role: Converters.enumeratedValue<'user' \| 'assistant'>(['user', 'assistant']),\n content: Converters.oneOf<string \| unknown[]>([\n Converters.string,\n Converters.isA('array', (v): v is unknown[] => Array.isArray(v))\n ])\n },\n { strict: false }\n );\n\n/\n Converter for an OpenAI / xAI Responses API `rawTail` item. These are\n * provider-native input items (`function_call`, `function_call_output`) whose\n * fields differ per item type, so — unlike the Anthropic `{ role, content }`\n * projection — the whole object is preserved verbatim.\n \n The static input is already typed `JsonObject`, so the `isJsonObject` guard\n * is a runtime backstop, not a compile-time narrowing: continuation messages\n * originate from a prior turn's `IAiClientToolContinuation.messages` and a\n * consumer may persist and reload them through untyped JSON before passing them\n * back. The guard preserves the same \"a malformed continuation message is\n * better omitted than transmitted verbatim\" posture as the Anthropic path —\n * non-object entries fail conversion and are skipped by the caller.\n * @internal\n /\nconst openAiRawTailItemConverter: Converter<JsonObject> = Converters.isA<JsonObject>(\n 'JsonObject',\n (v): v is JsonObject => isJsonObject(v)\n);\n\n/\n Converter for a Gemini `rawTail` item. Gemini continuation messages are\n * `{ role, parts }` turns (a model turn with `functionCall` parts followed by a\n * user turn with `functionResponse` parts). Narrows a `JsonObject` to\n * `{ role: 'user' \| 'model'; parts: Array<Record<string, unknown>> }`; entries\n * that fail validation are skipped by the caller.\n * @internal\n /\nconst geminiRawTailMessageConverter: Converter<{\n role: 'user' \| 'model';\n parts: unknown[];\n}> = Converters.object<{ role: 'user' \| 'model'; parts: unknown[] }>(\n {\n role: Converters.enumeratedValue<'user' \| 'model'>(['user', 'model']),\n // `parts` is preserved verbatim and serialized into the request body, so the\n // element shape is not narrowed here — `Array.isArray` soundly guarantees\n // `unknown[]` (narrowing to `Record<string, unknown>[]` would be an unchecked cast).\n parts: Converters.isA('array', (v): v is unknown[] => Array.isArray(v))\n },\n { strict: false }\n);\n\n/\n Optional history (`head`) and raw continuation (`rawTail`) messages to weave\n * around the prompt's current user message.\n \n @internal\n /\nexport interface IBuildMessagesOptions {\n /\n Prior conversation history inserted between the system prompt and the\n * prompt's current user message (multi-turn chat / correction retries). The\n * single ordered linearization is `[system, ...head, user, ...rawTail]`.\n /\n readonly head?: ReadonlyArray<IChatMessage>;\n /\n Raw JSON objects appended after the prompt's user message. Used to\n * inject provider-specific continuation messages (e.g. Anthropic assistant\n * turns with thinking blocks, OpenAI Responses `function_call` /\n * `function_call_output` items, Gemini `functionCall` / `functionResponse`\n * turns) that cannot be expressed as plain {@link IChatMessage} objects.\n \n Each builder applies its own provider-specific shape guard:\n * - {@link buildAnthropicMessages} projects each entry to `{ role, content }`.\n * - {@link buildMessages} (OpenAI / xAI Responses) preserves each item\n * verbatim (item fields differ per `type`), guarding only that it is a\n * JSON object.\n * - {@link buildGeminiContents} projects each entry to `{ role, parts }`.\n \n Entries that fail their builder's shape check are silently skipped (the\n * caller is responsible for supplying well-formed continuation messages).\n * Appended after the current user message.\n /\n readonly rawTail?: ReadonlyArray<JsonObject>;\n}\n\n/\n Builds the messages array from prompt + optional history (`head`) and raw\n * continuation (`rawTail`) messages. The caller supplies the system content\n * (string when no cache breakpoints are requested, parts array when they are\n * — see {@link buildOpenAiChatSystemContent} / {@link buildOpenAiResponsesSystemContent})\n * and the user content (string for text-only, parts array for vision prompts),\n * since both shapes differ by format.\n \n `rawTail` items (OpenAI / xAI Responses `function_call` /\n * `function_call_output` continuation items) are appended verbatim after the\n * user message — their fields differ per item `type`, so they are preserved\n * rather than projected. The return type is `Array<Record<string, unknown>>`\n * to accommodate both `{ role, content }` messages and these heterogeneous\n * input items.\n \n @internal\n /\nexport function buildMessages(\n systemContent: string \| unknown[],\n userContent: string \| unknown[],\n options?: IBuildMessagesOptions\n): Array<Record<string, unknown>> {\n const messages: Array<Record<string, unknown>> = [{ role: 'system', content: systemContent }];\n if (options?.head) {\n for (const msg of options.head) {\n messages.push({ role: msg.role, content: msg.content });\n }\n }\n messages.push({ role: 'user', content: userContent });\n // OpenAI / xAI Responses continuation items (function_call /\n // function_call_output) are appended verbatim — their field set differs per\n // item type, so the whole object is preserved rather than projected.\n if (options?.rawTail) {\n for (const item of options.rawTail) {\n const converted = openAiRawTailItemConverter.convert(item);\n if (converted.isSuccess()) {\n messages.push(converted.value);\n }\n }\n }\n return messages;\n}\n\n/\n Splits `segments` (from {@link splitSystemForCache}) into a single string when nothing carries\n * a breakpoint, or a content-part array in `partType`'s shape (with `prompt_cache_breakpoint` on\n * the parts that end a cacheable prefix) otherwise.\n \n @remarks\n * A single non-breakpointed segment (the common case: `cache` omitted or empty) returns the\n * plain string, byte-identical to a request built before cache support existed. Shared by\n * {@link buildOpenAiChatSystemContent} and {@link buildOpenAiResponsesSystemContent}, whose only\n * difference is the content-part `type` OpenAI's two APIs use (`'text'` vs `'input_text'`,\n * research.md §1.2).\n * @internal\n /\nfunction toOpenAiSystemContent(\n segments: ReadonlyArray<{ readonly text: string; readonly cacheBreakpoint: boolean }>,\n partType: 'text' \| 'input_text'\n): string \| unknown[] {\n if (segments.length === 1 && !segments[0].cacheBreakpoint) {\n return segments[0].text;\n }\n return segments.map((seg) => ({\n type: partType,\n text: seg.text,\n ...(seg.cacheBreakpoint\n ? {\n // eslint-disable-next-line @typescript-eslint/naming-convention -- wire field name\n prompt_cache_breakpoint: { mode: 'explicit' }\n }\n : {})\n }));\n}\n\n/\n Builds the system content for OpenAI Chat Completions, splitting `system` at `cache`'s\n * breakpoints (design.md §6.3) into content parts each carrying\n * `prompt_cache_breakpoint: { mode: 'explicit' }` where a cacheable prefix ends.\n * `prompt_cache_options` is never touched — OpenAI keeps its own implicit breakpoint and writes\n * up to the latest three of ours on top of it. Returns the plain `system` string when `cache` is\n * `undefined` or declares no breakpoints, byte-identical to a request built before cache support\n * existed.\n * @internal\n /\nexport function buildOpenAiChatSystemContent(\n system: string,\n cache: IAiCacheRequest \| undefined\n): Result<string \| unknown[]> {\n return splitSystemForCache(system, cache).onSuccess((segments) =>\n succeed(toOpenAiSystemContent(segments, 'text'))\n );\n}\n\n/\n Builds the system content for the OpenAI / xAI Responses API. Identical to\n * {@link buildOpenAiChatSystemContent} except for the content-part type (`'input_text'` instead\n * of `'text'`) — see research.md §1.2, \"Where the breakpoint may be attached.\"\n * @internal\n /\nexport function buildOpenAiResponsesSystemContent(\n system: string,\n cache: IAiCacheRequest \| undefined\n): Result<string \| unknown[]> {\n return splitSystemForCache(system, cache).onSuccess((segments) =>\n succeed(toOpenAiSystemContent(segments, 'input_text'))\n );\n}\n\n/\n Builds the Anthropic `system` field, splitting `system` at `cache`'s breakpoints into content\n * blocks carrying `cache_control: { type: 'ephemeral' }` on the block that ends each cacheable\n * prefix (design.md §6.1). Returns the plain `system` string when `cache` is `undefined` or\n * declares no breakpoints — byte-identical to `system: prompt.system` from a request built\n * before cache support existed.\n * @internal\n /\nexport function buildAnthropicSystem(\n system: string,\n cache: IAiCacheRequest \| undefined\n): Result<string \| unknown[]> {\n return splitSystemForCache(system, cache).onSuccess((segments) => {\n if (segments.length === 1 && !segments[0].cacheBreakpoint) {\n return succeed<string \| unknown[]>(segments[0].text);\n }\n return succeed<string \| unknown[]>(\n segments.map((seg) => ({\n type: 'text',\n text: seg.text,\n ...(seg.cacheBreakpoint ? { cache_control: { type: 'ephemeral' } } : {})\n }))\n );\n });\n}\n\n/\n Builds the user content for OpenAI Chat Completions when attachments are\n * present. Returns a string when there are no attachments.\n \n @internal\n /\nexport function buildOpenAiChatUserContent(prompt: AiPrompt): string \| unknown[] {\n if (prompt.attachments.length === 0) {\n return prompt.user;\n }\n return [\n { type: 'text', text: prompt.user },\n ...prompt.attachments.map((att: IAiImageAttachment) => ({\n type: 'image_url',\n image_url: {\n url: toDataUrl(att),\n ...(att.detail !== undefined ? { detail: att.detail } : {})\n }\n }))\n ];\n}\n\n/\n Builds the user content for OpenAI / xAI Responses API when attachments\n * are present. Responses API uses `input_text` / `input_image` part types,\n * distinct from Chat Completions' `text` / `image_url`.\n \n @internal\n /\nexport function buildOpenAiResponsesUserContent(prompt: AiPrompt): string \| unknown[] {\n if (prompt.attachments.length === 0) {\n return prompt.user;\n }\n return [\n { type: 'input_text', text: prompt.user },\n ...prompt.attachments.map((att: IAiImageAttachment) => ({\n type: 'input_image',\n image_url: toDataUrl(att),\n ...(att.detail !== undefined ? { detail: att.detail } : {})\n }))\n ];\n}\n\n/\n Builds the user-message content for Anthropic when attachments are present.\n \n @internal\n /\nexport function buildAnthropicUserContent(prompt: AiPrompt): string \| unknown[] {\n if (prompt.attachments.length === 0) {\n return prompt.user;\n }\n return [\n { type: 'text', text: prompt.user },\n ...prompt.attachments.map((att: IAiImageAttachment) => ({\n type: 'image',\n source: {\n type: 'base64',\n media_type: att.mimeType,\n data: att.base64\n }\n }))\n ];\n}\n\n/\n Builds the Gemini `parts` array for the user turn, including any image\n * attachments as `inlineData` parts.\n \n @internal\n /\nexport function buildGeminiUserParts(prompt: AiPrompt): Array<Record<string, unknown>> {\n const parts: Array<Record<string, unknown>> = [{ text: prompt.user }];\n for (const att of prompt.attachments) {\n parts.push({ inlineData: { mimeType: att.mimeType, data: att.base64 } });\n }\n return parts;\n}\n\n/\n Builds the Anthropic messages array, weaving any `head` history messages\n * between implicit system + the prompt's user message and appending `rawTail`\n * continuation messages after. System messages are filtered out (Anthropic uses\n * a top-level system field).\n \n @internal\n /\nexport function buildAnthropicMessages(\n prompt: AiPrompt,\n options?: IBuildMessagesOptions\n): Array<{ role: string; content: string \| unknown[] }> {\n const messages: Array<{ role: string; content: string \| unknown[] }> = [];\n if (options?.head) {\n for (const msg of options.head) {\n if (msg.role !== 'system') {\n messages.push({ role: msg.role, content: msg.content });\n }\n }\n }\n messages.push({ role: 'user', content: buildAnthropicUserContent(prompt) });\n if (options?.rawTail) {\n for (const msg of options.rawTail) {\n const converted = rawTailMessageConverter.convert(msg);\n if (converted.isSuccess()) {\n messages.push(converted.value);\n }\n }\n }\n return messages;\n}\n\n/\n Builds the Gemini `contents` array, weaving any `head` history messages before\n * the prompt's user parts and appending `rawTail` continuation messages after.\n * System messages are filtered out (Gemini uses a top-level systemInstruction\n * field) and assistant roles are mapped to Gemini's `model` role.\n \n @internal\n */\nexport function buildGeminiContents(\n prompt: AiPrompt,\n options?: IBuildMessagesOptions\n): Array<{ role: string; parts: unknown[] }> {\n const contents: Array<{ role: string; parts: unknown[] }> = [];\n if (options?.head) {\n for (const msg of options.head) {\n if (msg.role !== 'system') {\n contents.push({\n role: msg.role === 'assistant' ? 'model' : msg.role,\n parts: [{ text: msg.content }]\n });\n }\n }\n }\n contents.push({ role: 'user', parts: buildGeminiUserParts(prompt) });\n // Gemini continuation turns (model `functionCall` parts + user\n // `functionResponse` parts) are projected to `{ role, parts }`.\n if (options?.rawTail) {\n for (const item of options.rawTail) {\n const converted = geminiRawTailMessageConverter.convert(item);\n if (converted.isSuccess()) {\n contents.push(converted.value);\n }\n }\n }\n return contents;\n}\n"]}

package/dist/packlets/ai-assist/completionClient.js CHANGED Viewed

@@ -28,6 +28,7 @@
 import { isJsonObject } from '@fgv/ts-json-base';
 import { captureResult, fail, succeed, Validators } from '@fgv/ts-utils';
 import { DEFAULT_ANTHROPIC_MAX_TOKENS, isAdaptiveThinkingModel, isResponsesOnlyModel, resolveProviderModel, usesMaxCompletionTokensField } from './model';
+import { aiCompletionUsage } from './converters';
 import { anthropicEffortToBudgetTokens, checkTemperatureConflict, mergeThinkingConfig, providerDiscriminatorForId } from './thinkingOptionsResolver';
 import { buildAnthropicMessages, buildAnthropicSystem, buildGeminiContents, buildMessages, buildOpenAiChatSystemContent, buildOpenAiChatUserContent, buildOpenAiResponsesSystemContent, buildOpenAiResponsesUserContent, normalizeOutboundMessages, splitChatRequest } from './chatRequestBuilders';
 import { anthropicAuthHeaders, bearerAuthHeader, geminiAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
@@ -543,12 +544,25 @@ export async function callProviderCompletion(params) {
  * CORS, and API key forwarding. The request body serializes the unified
  * {@link AiAssist.IChatRequest} shape (`system?` + `messages`). Enforces the same
  * non-empty / trailing-user-turn and image-input invariants as the direct path.
+ *
+ * @remarks
+ * Two parameters are handled before the body is composed, rather than forwarded.
+ * `tier` is resolved here and sent as a concrete `modelOverride`, because both
+ * halves of the resolution live on the descriptor the caller already holds — so a
+ * proxy needs no `tier` vocabulary, where a `tier` body field it did not understand
+ * would be ignored and silently serve a frontier request from the base model.
+ * `endpoint` is **refused**: it names where the prompt must go, the proxy is what
+ * makes that call, and the field has never been sent to one — so honoring it is
+ * unverifiable and ignoring it would reach the provider's default upstream instead
+ * of the host the caller pinned. Use `callProviderCompletion`, or point the
+ * proxy itself at the intended upstream.
+ *
  * @param proxyUrl - Base URL of the proxy server
  * @param params - Same parameters as {@link callProviderCompletion}
  * @public
  */
 export async function callProxiedCompletion(proxyUrl, params) {
-    const { descriptor, apiKey, system, messages, temperature, modelOverride, logger, tools, signal, thinking, maxTokens, structuredOutput, cache } = params;
+    const { descriptor, apiKey, system, messages, temperature, modelOverride, logger, tools, signal, thinking, maxTokens, structuredOutput, cache, tier, endpoint } = params;
     const splitResult = splitChatRequest(system, messages);
     if (splitResult.isFailure()) {
         return fail(splitResult.message);
@@ -556,6 +570,48 @@ export async function callProxiedCompletion(proxyUrl, params) {
     if (splitResult.value.prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
         return fail(`provider "${descriptor.id}" does not accept image input`);
     }
+    // `endpoint` names the upstream the request must reach. Unlike `tier` it cannot be
+    // resolved on this side, because the proxy is the one making that call — it would
+    // have to be forwarded and honored. No proxy honors it: the field has never been
+    // sent, so every deployed proxy would ignore it and fall back to the provider's
+    // public API.
+    //
+    // Silently is the problem. A caller names an endpoint to pin *where the prompt
+    // goes* — a self-hosted model, a LAN deployment, a residency boundary — so the
+    // failure is not a degraded answer, it is the content going somewhere they
+    // explicitly said it must not, discoverable only by watching the proxy's traffic.
+    // That is the same shape as the structured-output silent-drop this function
+    // already refuses to allow, with a worse consequence.
+    //
+    // So refuse rather than pretend. Honoring `endpoint` over a proxy needs a wire
+    // field AND a report-back the caller can verify, the way `structuredOutput` is
+    // acknowledged below; until that protocol exists, the direct path is where this
+    // parameter works.
+    if (endpoint !== undefined) {
+        return fail(`callProxiedCompletion: endpoint is not supported on the proxied path — a proxy ` +
+            `cannot confirm it honored it, and silently reaching the provider's default ` +
+            `upstream would send the request somewhere the caller excluded. Use ` +
+            `callProviderCompletion, or route the proxy itself at the intended upstream.`);
+    }
+    // The quality tier is resolved HERE rather than forwarded, because it can be:
+    // the tier walk and the alias map both live on the descriptor, which is
+    // client-side, so this side already holds everything the resolution needs.
+    // Sending the concrete model through the existing `modelOverride` field means a
+    // proxy needs no new vocabulary and an already-deployed one honors the tier
+    // without being updated — where a `tier` body field it did not understand would
+    // be ignored, silently serving a frontier request from the base model.
+    //
+    // Only when a tier was actually asked for. With no tier, `modelOverride` passes
+    // through exactly as before, including absent — which is what lets a proxy apply
+    // its own default.
+    let effectiveModelOverride = modelOverride;
+    if (tier !== undefined) {
+        const tierResult = resolveProviderModel(descriptor, modelOverride, tier);
+        if (tierResult.isFailure()) {
+            return fail(tierResult.message);
+        }
+        effectiveModelOverride = tierResult.value;
+    }
     const body = {
         providerId: descriptor.id,
         apiKey,
@@ -569,8 +625,8 @@ export async function callProxiedCompletion(proxyUrl, params) {
     if (system !== undefined) {
         body.system = system;
     }
-    if (modelOverride !== undefined) {
-        body.modelOverride = modelOverride;
+    if (effectiveModelOverride !== undefined) {
+        body.modelOverride = effectiveModelOverride;
     }
     if (tools && tools.length > 0) {
         body.tools = tools;
@@ -589,8 +645,10 @@ export async function callProxiedCompletion(proxyUrl, params) {
         // `JsonSchema.fromJson(raw)` before calling `callProviderCompletion`.
         body.structuredOutput =
             structuredOutput.mode === 'schema'
-                ? Object.assign({ mode: 'schema', schema: structuredOutput.schema.toJson() }, (structuredOutput.onUnsupported !== undefined
+                ? Object.assign(Object.assign({ mode: 'schema', schema: structuredOutput.schema.toJson() }, (structuredOutput.onUnsupported !== undefined
                     ? { onUnsupported: structuredOutput.onUnsupported }
+                    : {})), (structuredOutput.adaptOptionalToNullable !== undefined
+                    ? { adaptOptionalToNullable: structuredOutput.adaptOptionalToNullable }
                     : {})) : Object.assign({ mode: 'json-object' }, (structuredOutput.onUnsupported !== undefined
                 ? { onUnsupported: structuredOutput.onUnsupported }
                 : {}));
@@ -619,22 +677,24 @@ export async function callProxiedCompletion(proxyUrl, params) {
     // rather than a response claiming an enforcement nobody verified — a proxy
     // predating this feature drops the constraint silently, which is the exact
     // failure this surface exists to remove.
+    // A proxy relaying `callProviderCompletion`'s result carries an already-normalized
+    // IAiCompletionUsage, not a provider wire shape — so this validates that shape
+    // rather than reaching for the per-provider normalizers. A proxy that reports
+    // nothing, or reports something malformed, yields `undefined`: the documented
+    // "no normalized usage exposed", never a partially-trusted object and never a
+    // fabricated zero.
+    const usage = aiCompletionUsage.convert(response.usage).orDefault();
+    // Built once: the two returns differ only in the enforcement they report, and
+    // duplicating the shape is how a field added to one and not the other drifts.
+    const base = Object.assign({ content: response.content, truncated: response.truncated === true }, (usage !== undefined ? { usage } : {}));
     if (structuredOutput === undefined) {
-        return succeed({
-            content: response.content,
-            truncated: response.truncated === true,
-            structuredOutput: 'none'
-        });
+        return succeed(Object.assign(Object.assign({}, base), { structuredOutput: 'none' }));
     }
     if (!isStructuredOutputEnforcement(response.structuredOutput)) {
         return fail(`proxy did not report which structured-output constraint it applied ` +
             `(got ${JSON.stringify(response.structuredOutput)}); it may predate the feature and have ` +
             `dropped the request silently`);
     }
-    return succeed({
-        content: response.content,
-        truncated: response.truncated === true,
-        structuredOutput: response.structuredOutput
-    });
+    return succeed(Object.assign(Object.assign({}, base), { structuredOutput: response.structuredOutput }));
 }
 //# sourceMappingURL=completionClient.js.map