@aeye/core 0.5.4 → 0.6.0

package/README.md

@@ -408,6 +408,42 @@ const adaptivePrompt = new Prompt({
 });
 ```
 
+## Schema Fallbacks
+
+A provider that rejects a schema throws `SchemaRejectedError` with a `target` naming the output or the tool. The prompt then steps down its `schemaFallbacks`, by default `SCHEMA_FALLBACKS`: the rejected schema goes non-strict, then the output moves to JSON mode with its schema in the prompt (`schemaDelivery: 'json'`), then to plain text with its schema in the prompt (`'prompt'`). Steps stay on the request for the rest of the run, and each emits a `schemaFallback` event.
+
+```typescript
+import { Prompt, SCHEMA_FALLBACKS } from '@aeye/core';
+
+const prompt = new Prompt({
+  name: 'extract',
+  description: 'Extracts fields',
+  content: 'Extract the fields from: {{text}}',
+  schema,
+  schemaFallbacks: SCHEMA_FALLBACKS.filter(step => step.name !== 'json'),
+});
+```
+
+Providers use `schemaRejection(request, error)` to classify a bad request and `deliverSchema(request)` to send a `json` or `prompt` schema without changing the prompt's request.
+
+## Error Kinds
+
+Every prompt failure has `kind: 'model' | 'tool'`. `ToolInputError` (an unknown tool or bad arguments) and `OutputValidationError` (output that isn't JSON or fails the schema or `validate`) are model mistakes, fed back to the model for another try. `ToolExecutionError` is a tool's own throw. They appear on the `toolError` event's `failure`, on tool result messages' `failure`, and on the `textReset` event's `error`. A prompt that gives up throws a `PromptError` whose `cause` is the last failure.
+
+## Review
+
+`review` judges the parsed, validated output before it's returned. Feedback becomes a user message and the model answers again, up to `reviewRetries` times; after that the prompt throws a `PromptError` caused by a `ReviewRejectedError` with the last output.
+
+```typescript
+const answer = new Prompt({
+  name: 'answer',
+  description: 'Answers briefly',
+  content: 'Answer in under 20 words: {{question}}',
+  input: (input: { question: string }) => input,
+  review: (output) => output.split(' ').length < 20 ? { pass: true } : { feedback: 'Use fewer than 20 words.' },
+});
+```
+
 ## Model Capabilities
 
 @aeye uses a capability system for automatic model selection. Models advertise their capabilities and the library selects the best match for each request:
@@ -421,6 +457,8 @@ const adaptivePrompt = new Prompt({
 | `audio` | Text-to-speech |
 | `hearing` | Speech-to-text |
 | `embedding` | Text embeddings |
+| `rerank` | Ordering documents by relevance |
+| `decision` | Typed answers (probabilities, choices, scores) from decision models |
 | `tools` | Function/tool calling |
 | `json` | JSON output mode |
 | `structured` | Structured outputs with schemas |
@@ -541,7 +579,10 @@ class Prompt<TContext, TMetadata, TName extends string, TInput extends object, T
 - `content: string` - Handlebars template for the system/user message
 - `input?: (input: TInput, ctx: Context<TContext, TMetadata>) => Record<string, any>` - Maps raw input to template variables
 - `schema?: ZodType<TOutput> | ((input: TInput | undefined, ctx: Context<TContext, TMetadata>) => ZodType<TOutput> | false)` - Output schema; `false` disables structured output
-- `strict?: boolean` - Enforce strict Zod schema (default: `true`)
+- `strict?: boolean | number` - Strict tool inputs: `true` requires, `false` disables, a number is a preference priority (default: `1`)
+- `format?: ToolTextFormat` - Take free text (`{ type: 'text' }`) or grammar-constrained text (`{ type: 'grammar', syntax: 'lark' | 'regex', definition }`) as `input` instead of JSON; use `TEXT_TOOL_SCHEMA` as the schema
+- `defer?: boolean` - Load only when the model searches for it (OpenAI tool search)
+- `async?: boolean` - The model keeps working while the tool runs (OpenAI Responses)
 - `config?: Partial<Request> | ((input: TInput | undefined, ctx: Context<TContext, TMetadata>) => Partial<Request> | false)` - AI request overrides
 - `tools?: TTools` - Tools the prompt may call
 - `toolExecution?: 'sequential' | 'parallel' | 'immediate'` - Tool execution mode
@@ -549,8 +590,12 @@ class Prompt<TContext, TMetadata, TName extends string, TInput extends object, T
 - `toolIterations?: number` - Max tool-calling iterations (default: 3)
 - `toolsMax?: number` - Max successful tool calls
 - `outputRetries?: number` - Retry count for invalid structured outputs
+- `schemaDelivery?: 'auto' | 'structured' | 'json' | 'prompt'` - How the output schema reaches the model (default: `'auto'`)
+- `schemaFallbacks?: readonly SchemaFallback[]` - Steps taken when a provider rejects a schema (default: the context's, then `SCHEMA_FALLBACKS`)
 - `metadata?: TMetadata` - Static metadata for this prompt
 - `validate?: (output: TOutput, ctx: Context<TContext, TMetadata>) => void | Promise<void>` - Post-parse validation
+- `review?: (output: TDecoded, context: PromptReviewContext) => PromptReview | Promise<PromptReview>` - Review the valid output: `{ pass: true }` or `{ feedback }` for another round
+- `reviewRetries?: number` - Rounds the model gets to answer review feedback (default: 1)
 - `applicable?: (ctx: Context<TContext, TMetadata>) => boolean | Promise<boolean>` - Availability check
 
 **Methods:**
@@ -626,6 +671,8 @@ interface CoreContextFields {
   outputRetries?: number;
   // Number of context-trimming retries (default: 1)
   forgetRetries?: number;
+  // Steps a prompt takes when a provider rejects a schema (default: SCHEMA_FALLBACKS)
+  schemaFallbacks?: readonly SchemaFallback[];
 
   // Abort signal for cancellation
   signal?: AbortSignal;
@@ -644,9 +691,9 @@ interface Request {
   maxTokens?: number;
   stop?: string | string[];
   tools?: ToolDefinition[];
-  toolChoice?: 'auto' | 'required' | 'none' | { type: 'tool'; name: string };
-  responseFormat?: 'text' | 'json' | { type: 'json_schema'; schema: object; name: string; strict?: boolean };
-  reason?: { effort?: 'low' | 'medium' | 'high'; maxTokens?: number };
+  toolChoice?: 'auto' | 'required' | 'none' | { tool: string } | { allowed: string[]; required?: boolean };
+  responseFormat?: 'text' | 'json' | { type: ZodType; strict: boolean | number };
+  reason?: { effort?: ReasoningEffort; maxTokens?: number; summary?: 'auto' | 'concise' | 'detailed'; exclude?: boolean };
   frequencyPenalty?: number;
   presencePenalty?: number;
   seed?: number;

package/aeye-core-schema.md

@@ -35,7 +35,7 @@ A descriptor (see `src/schema.ts` line ~26 for the fully documented interface) d
 | `supportsRecursion` | Whether `$ref` self-reference works. |
 | `maxStrictTools` / `maxStrictOptionalParams` / `maxStrictUnionTypes` | Per-request slot budgets (`undefined` = no documented limit). |
 | `schemaSizeLimits` | Per-SCHEMA size ceilings — properties, nesting, total string characters, enum values (`undefined` = no documented limit) — see below. |
-| `maxEnumValues` | Opt-in ceiling on how many values ONE emitted `enum` may carry (`undefined` = no cap, and that is what every built-in declares) — see below. |
+| `maxEnumValues` | Opt-in ceiling on how many values ONE emitted `enum` may carry (`undefined` = no cap). `GOOGLE_STRICT`/`GOOGLE_NON_STRICT` declare 40, a MEASURED response to a real provider rejection; every other built-in declares none — see below. |
 
 ### `schemaSizeLimits` — how BIG one strict schema may be
 
@@ -60,7 +60,7 @@ Scope is Structured Outputs — a tool carrying `strict: true`, or a `json_schem
 
 The measurement is taken from the **Zod** schema rather than from the emitted JSON, so where an encoding is descriptor-dependent it counts the widest one (a record as its `{key, value}` pair form, a tuple as its numeric-key form). Over-counting costs strictness on a schema that would have fitted; under-counting costs an HTTP 400, so the rounding goes up. `$defs` entry names are not counted: they are generated at emit time, few, and short against a 120,000-character budget.
 
-### `maxEnumValues` — an opt-in dialect ceiling that WIDENS, and why no built-in sets one
+### `maxEnumValues` — an opt-in dialect ceiling that WIDENS, and why only Google sets one
 
 Some providers may reject a schema whose `enum` is simply too long. That is **not** one of the per-request budgets above: those are strict-mode allowances the `SchemaBudget` spends across a whole request, degrading an item that no longer fits to the family's non-strict descriptor, whereas this one would fire whatever the strictness, so it is enforced structurally at the point an `enum` is emitted.
 
@@ -75,15 +75,19 @@ Truncating would make the values past the cap **unreachable** — the wire schem
 
 The trade is enforcement: a widened node no longer rejects a value structurally, so whatever validates the model's output afterwards must. `Tool.parse` does — it runs against the ORIGINAL zod schema, whose `enum` is untouched — so a hallucinated member comes back as a normal, re-promptable validation error.
 
-**No built-in descriptor declares a cap, and that is a measured result.** The field exists because a large `enum` was believed to make Gemini answer `400 INVALID_ARGUMENT`. Measured against `google/gemini-3-flash-preview` through OpenRouter (2026-08-23), it does not: single-parameter enums at 50/64/72/80/96/128/256/512/1024/**2048** values (52 KB of tool schema) all returned HTTP 200 with the expected tool call, under `tool_choice` both `required` (which is what makes Gemini compile a decoding grammar) and `auto` — as did 96 values with 80-character members, 20 tools each carrying a 96-value enum in one request, a 96-value enum next to `strict: true` / `minItems` / `propertyOrdering` / a sibling `anyOf`, and a 2048-value enum inside a `response_format` schema. Reliability was compared too, since a cap's whole cost is losing the enum's can't-hallucinate guarantee: 10 trials each of `enum` vs plain-string-with-full-list, over confusable near-duplicate names, at 96 and again at 512 values — both picked the correct member 10/10 with zero off-list answers.
+**`GOOGLE_STRICT`/`GOOGLE_NON_STRICT` declare `maxEnumValues: 40`. Every other built-in declares no cap.** The field exists because a large `enum` was believed to make Gemini answer `400 INVALID_ARGUMENT`. An initial round of measurement against `google/gemini-3-flash-preview` through OpenRouter (2026-08-23) looked like it disproved that: single-parameter enums at 50/64/72/80/96/128/256/512/1024/**2048** SYNTHETIC values (`name_0`, `name_1`, …) all returned HTTP 200, as did an eleven-tool roster modelled on a real kind-authoring agent with a 96-value enum on one tool.
 
-A second pass answered the obvious objection — that an isolated probe is not what a real session sends. Same date and model, upstream **pinned to Google AI Studio** with fallbacks off (the upstream that served the production failures), an eleven-tool roster emitted through this library for a Google model and modelled on a real kind-authoring agent (`fn_load` / `fn_search` / `type_load` / `api_signature` / `api_set` / …, real descriptions, real system prompt): a 96-value enum on one of those tools returned 200 with the expected tool call under `tool_choice` `required` and `auto` alike, as did the same roster at 8 values and a tool carrying a bare typeless `{}` property.
+**That conclusion was wrong, because none of it used the CONTENT of a real session.** A third round replayed the exact wire bytes of an actual product request — `fn_load`'s `names` array, enum-constrained to a real session's 98 known component/fn names (`default_renderer`, `QueryWidget`, `ConfirmPrompt`, `list_widget_types`, …) — and it 400'd, reproducibly, twice, byte-for-byte identical to what was actually sent. Bisecting that real value list: 90 values passes, 93 fails. Bisecting what differs from the earlier synthetic probes: 98 SHORT synthetic values (284 total characters) pass; 206 short values matching the real list's total character count (714 characters) also pass; only the real, longer, identifier-shaped values fail, and only past ~92 of them. So the limit tracks neither raw member count nor total character/byte budget — most likely actual tokenized grammar-state count, which short repetitive synthetic strings compress far below what real identifier text does at the same count or character budget. This is why the first two rounds' synthetic and lightly-realistic probes never tripped it.
 
-The caveat that keeps that from being proof: the **control** — the recursive `$defs/Any` shape documented elsewhere in this file as 100% reproducible HTTP 400 — also returned 200, pinned and unpinned, forced and automatic, both hand-built and as the product's real 32 KB gin `api_set` schema. That failure class is not visible from this route today, so treat the numbers as evidence, not a verdict.
+The widen-to-string fallback this field triggers was verified against the exact failing real schema: dropping `enum` and putting the same 98 values into the `description` of a plain string field returned HTTP 200 with the expected tool call — confirming the fallback mechanism actually fixes the failure it exists for, not just a synthetic stand-in.
 
-One trap for whoever measures this next: at `max_tokens: 64` the `$defs/Any` tool answered `finish_reason: "length"` with no tool call and empty content, which reads exactly like a grammar that produced nothing. It is not — this model spends reasoning tokens first, and at 400 the identical request emitted a correct call in 28 output tokens. Give a forced-tool probe room before calling an empty completion a failure.
+`40` is not a measured edge — it is a conservative floor with roughly 2x margin under the real one (90 passes / 93 fails) measured on this one real value set. Given the failure tracks content, not just count, a different session's actual name list could plausibly fail at a different count; 40 was also the cap the product that surfaced this ran under in production for months, which is corroborating evidence it holds in practice, not just in this one measurement.
 
-So: **set this only against a measured provider rejection, and set it as high as the measurement allows.** An `enum` that fits is the more correct encoding, because it is the one the model cannot answer outside of.
+The reliability comparison from the earlier rounds still stands and is why a cap is preferable to leaving every enum uncapped "to be safe" at a much lower number: `enum` vs plain-string-with-full-list, 10 trials each over confusable near-duplicate names at 96 and 512 values, scored 10/10 on-target with zero off-list answers for BOTH encodings. So there is no reliability cost to raising this cap later if a higher safe value is measured — only downside risk to leaving it too high.
+
+One trap for whoever measures this next: with `max_tokens` at 64, a forced-tool probe can come back `finish_reason: "length"` with no tool call and empty content, which reads exactly like a grammar that produced nothing. It usually is not — this model spends reasoning tokens first. Give a forced-tool probe room before calling an empty completion a failure.
+
+So: **set this only where a provider is MEASURED to reject a large enum using the SESSION'S OWN real content, not synthetic stand-ins, and set it conservatively below the measured edge until more value sets are tested.** An `enum` that fits is the more correct encoding, because it is the one the model cannot answer outside of.
 
 ### `anyEncoding` — and what each mode requires
 

package/dist/common.d.ts

@@ -1,4 +1,4 @@
-import { Chunk, Events, Model, ModelInput, Reasoning, Response, Runner, Usage } from "./types";
+import { Chunk, Events, GeneratedAudio, Model, ModelInput, Reasoning, Response, Runner, Usage } from "./types";
 /**
  * A flexible function type that can be:
  * - A direct value of type R
@@ -145,6 +145,14 @@ export declare function getModel(input: ModelInput | undefined): Model | undefin
  * @returns The aggregated Response object.
  */
 export declare function getResponseFromChunks(chunks: Chunk[], model?: ModelInput): Response;
+/**
+ * Appends a partial audio chunk onto accumulated audio.
+ *
+ * @param target - The audio accumulated so far.
+ * @param add - The partial audio to append.
+ * @returns The combined audio.
+ */
+export declare function accumulateAudio(target: GeneratedAudio | undefined, add: GeneratedAudio): GeneratedAudio;
 /**
  * Generates a plain text representation of reasoning data.
  *
@@ -153,13 +161,30 @@ export declare function getResponseFromChunks(chunks: Chunk[], model?: ModelInpu
  */
 export declare function getReasoningText(reasoning: Reasoning | undefined): string;
 /**
- * Accumulates reasoning data by merging an additional Reasoning object into a target Reasoning object.
+ * Accumulates streamed reasoning: the reasoning so far with the next part
+ * appended, as a new object that shares nothing mutable with either input.
+ *
+ * Providers stream reasoning as deltas, never repeating what was sent, so
+ * `content` and each detail's `text`, `summary` and `data` concatenate. A
+ * detail continues an earlier one of the same type with the same id (when
+ * both have one) or index: OpenRouter sends a block's text and later its
+ * signature at one index, and Gemini's text and encrypted reasoning share
+ * index 0 under different types. The provider is whichever part names it.
  *
- * @param target - The target Reasoning object to accumulate into.
- * @param add - The Reasoning object to add from.
- * @returns - The updated Reasoning object.
+ * @param target - The reasoning accumulated so far.
+ * @param add - The reasoning to append.
+ * @returns - The accumulated reasoning.
  */
 export declare function accumulateReasoning(target: Reasoning | undefined, add?: Reasoning): Reasoning | undefined;
+/**
+ * Whether reasoning goes back to a provider: it came from there, or names no
+ * provider. Signed and encrypted reasoning only verifies where it was made.
+ *
+ * @param reasoning - The reasoning of an earlier assistant turn.
+ * @param provider - The provider the conversation goes to.
+ * @returns - Whether to replay the reasoning.
+ */
+export declare function replaysTo(reasoning: Reasoning | undefined, provider: string): reasoning is Reasoning;
 /**
  * Converts a Response object into an array of Chunk objects.
  *

package/dist/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAmB,MAAM,EAAY,KAAK,EAAE,UAAU,EAAE,SAAS,EAAY,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEpI;;;;;GAKG;AACH,MAAM,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEzG;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAChD,CAAC,GACD,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,MAAM,CAAC,GACnC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GACxB,CAAC,GACD,CAAC,GACH,CAAC,CAAC;AAER;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC;AAE3F;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,IACvD,CAAC,SAAS,SAAS,GACf,MAAM,OAAO,CAAC,SAAS,CAAC,GACxB,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAC5B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC1B,KAAK,CACZ;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,SAAS,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAA;AAClH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;AACzG,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,EAAE,CAAC,CAAC,CAAA;AA2B3I;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CASnF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAC/B,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,GACrB,cAAc,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CActD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAMlF;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAChD,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,SAAS,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GACzC,QAAQ,CAAC,CAAC,CAAC,GACX,CAAC,CACN;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,EAAE,KAAK,QAkGzD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAOpD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAKrD;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAYpD;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,KAAK,CAAC;AACnD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,CAAC;AAK3E;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,KAAK,GAAE,UAAsB,GAAG,QAAQ,CAiC9F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAoBzE;AAgBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAgDzG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,EAAE,CAsBjE;AAED;;;;;GAKG,CACH,wBAAgB,UAAU,CAAC,KAAK,SAAS,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAgHpF;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqCtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GAEV;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,GACzE,SAAS,CAqBZ"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"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"}

package/dist/common.js

@@ -127,6 +127,22 @@ export async function consumeAll(gen) {
     }
     return results;
 }
+/**
+ * Adds every count in `add` onto `target`, treating a missing count as zero.
+ *
+ * @param target - The counts to add into (mutated).
+ * @param add - The counts to add.
+ * @returns The target.
+ */
+function sumCounts(target, add) {
+    for (const key in add) {
+        const value = add[key];
+        if (value !== undefined) {
+            target[key] = (target[key] ?? 0) + value;
+        }
+    }
+    return target;
+}
 /**
  * Accumulates usage statistics by adding values from one Usage object to another.
  * Handles the nested structure matching ModelPricing.
@@ -139,92 +155,40 @@ export function accumulateUsage(target, add) {
     if (!add) {
         return;
     }
-    // Accumulate text usage
-    if (add.text) {
-        if (!target.text) {
-            target.text = {};
-        }
-        if (add.text.input !== undefined) {
-            target.text.input = (target.text.input || 0) + add.text.input;
-        }
-        if (add.text.output !== undefined) {
-            target.text.output = (target.text.output || 0) + add.text.output;
-        }
-        if (add.text.cached !== undefined) {
-            target.text.cached = (target.text.cached || 0) + add.text.cached;
-        }
-    }
-    // Accumulate audio usage
-    if (add.audio) {
-        if (!target.audio) {
-            target.audio = {};
-        }
-        if (add.audio.input !== undefined) {
-            target.audio.input = (target.audio.input || 0) + add.audio.input;
-        }
-        if (add.audio.output !== undefined) {
-            target.audio.output = (target.audio.output || 0) + add.audio.output;
-        }
-        if (add.audio.seconds !== undefined) {
-            target.audio.seconds = (target.audio.seconds || 0) + add.audio.seconds;
-        }
-    }
-    // Accumulate image usage
+    if (add.text)
+        target.text = sumCounts(target.text ?? {}, add.text);
+    if (add.audio)
+        target.audio = sumCounts(target.audio ?? {}, add.audio);
+    if (add.reasoning)
+        target.reasoning = sumCounts(target.reasoning ?? {}, add.reasoning);
+    if (add.embeddings)
+        target.embeddings = sumCounts(target.embeddings ?? {}, add.embeddings);
+    if (add.tools)
+        target.tools = sumCounts(target.tools ?? {}, add.tools);
+    // Image input is a count; image output merges by quality and size
     if (add.image) {
-        if (!target.image) {
-            target.image = { output: [] };
-        }
+        const image = target.image ?? (target.image = {});
         if (add.image.input !== undefined) {
-            target.image.input = (target.image.input || 0) + add.image.input;
+            image.input = (image.input ?? 0) + add.image.input;
+        }
+        if (add.image.tokens !== undefined) {
+            image.tokens = (image.tokens ?? 0) + add.image.tokens;
         }
-        if (add.image.output) {
-            if (!target.image.output) {
-                target.image.output = [];
+        for (const addOutput of add.image.output ?? []) {
+            const outputs = image.output ?? (image.output = []);
+            const existing = outputs.find(o => o.quality === addOutput.quality &&
+                o.size.width === addOutput.size.width &&
+                o.size.height === addOutput.size.height);
+            if (existing) {
+                existing.count += addOutput.count;
             }
-            // Merge image outputs by quality and size
-            for (const addOutput of add.image.output) {
-                const existing = target.image.output.find(o => o.quality === addOutput.quality &&
-                    o.size.width === addOutput.size.width &&
-                    o.size.height === addOutput.size.height);
-                if (existing) {
-                    existing.count += addOutput.count;
-                }
-                else {
-                    target.image.output.push({ ...addOutput });
-                }
+            else {
+                outputs.push({ ...addOutput });
             }
         }
     }
-    // Accumulate reasoning usage
-    if (add.reasoning) {
-        if (!target.reasoning) {
-            target.reasoning = {};
-        }
-        if (add.reasoning.input !== undefined) {
-            target.reasoning.input = (target.reasoning.input || 0) + add.reasoning.input;
-        }
-        if (add.reasoning.output !== undefined) {
-            target.reasoning.output = (target.reasoning.output || 0) + add.reasoning.output;
-        }
-        if (add.reasoning.cached !== undefined) {
-            target.reasoning.cached = (target.reasoning.cached || 0) + add.reasoning.cached;
-        }
-    }
-    // Accumulate embeddings usage
-    if (add.embeddings) {
-        if (!target.embeddings) {
-            target.embeddings = {};
-        }
-        if (add.embeddings.count !== undefined) {
-            target.embeddings.count = (target.embeddings.count || 0) + add.embeddings.count;
-        }
-        if (add.embeddings.tokens !== undefined) {
-            target.embeddings.tokens = (target.embeddings.tokens || 0) + add.embeddings.tokens;
-        }
-    }
-    // Accumulate cost
     if (add.cost !== undefined) {
-        target.cost = (target.cost || 0) + add.cost;
+        target.cost = (target.cost ?? 0) + add.cost;
     }
 }
 /**
@@ -309,7 +273,7 @@ export function getResponseFromChunks(chunks, model = 'unknown') {
             resp.model = chunk.model;
         }
         if (chunk.refusal) {
-            resp.refusal = chunk.refusal;
+            resp.refusal = (resp.refusal ?? '') + chunk.refusal;
         }
         if (chunk.toolCall) {
             resp.toolCalls = resp.toolCalls || [];
@@ -319,9 +283,48 @@ export function getResponseFromChunks(chunks, model = 'unknown') {
             resp.usage = resp.usage || {};
             accumulateUsage(resp.usage, chunk.usage);
         }
+        if (chunk.citations) {
+            resp.citations = [...resp.citations ?? [], ...chunk.citations];
+        }
+        if (chunk.images) {
+            resp.images = [...resp.images ?? [], ...chunk.images];
+        }
+        if (chunk.audio) {
+            resp.audio = accumulateAudio(resp.audio, chunk.audio);
+        }
+        if (chunk.moderation) {
+            resp.moderation = { ...resp.moderation, ...chunk.moderation };
+        }
+        if (chunk.serviceTier) {
+            resp.serviceTier = chunk.serviceTier;
+        }
     }
     return resp;
 }
+/**
+ * The base64 encoding of two base64 strings' bytes joined. Each streamed part
+ * is encoded on its own, so a padded last block of the first is re-encoded
+ * with the bytes that follow.
+ */
+function joinBase64(x, y) {
+    return x.endsWith('=') ? x.slice(0, -4) + btoa(atob(x.slice(-4)) + atob(y)) : x + y;
+}
+/**
+ * Appends a partial audio chunk onto accumulated audio.
+ *
+ * @param target - The audio accumulated so far.
+ * @param add - The partial audio to append.
+ * @returns The combined audio.
+ */
+export function accumulateAudio(target, add) {
+    const join = (x, y, by) => x === undefined || y === undefined ? x ?? y : by(x, y);
+    return {
+        id: add.id ?? target?.id,
+        format: add.format ?? target?.format,
+        data: join(target?.data, add.data, joinBase64),
+        transcript: join(target?.transcript, add.transcript, (x, y) => x + y),
+    };
+}
 /**
  * Generates a plain text representation of reasoning data.
  *
@@ -348,66 +351,63 @@ export function getReasoningText(reasoning) {
     }
     return parts.join('\n\n');
 }
-// Only appends y to x if neither contains the other
-function appendMaybe(x, y) {
-    if (!x) {
-        return y;
-    }
-    if (!y) {
-        return x;
-    }
-    if (!x.includes(y) && !y.includes(x)) {
-        return x + y;
-    }
-    return x;
+/** Two streamed pieces of text joined, either of which may be missing. */
+function concat(x, y) {
+    return x && y ? x + y : x || y || undefined;
 }
 /**
- * Accumulates reasoning data by merging an additional Reasoning object into a target Reasoning object.
+ * Accumulates streamed reasoning: the reasoning so far with the next part
+ * appended, as a new object that shares nothing mutable with either input.
+ *
+ * Providers stream reasoning as deltas, never repeating what was sent, so
+ * `content` and each detail's `text`, `summary` and `data` concatenate. A
+ * detail continues an earlier one of the same type with the same id (when
+ * both have one) or index: OpenRouter sends a block's text and later its
+ * signature at one index, and Gemini's text and encrypted reasoning share
+ * index 0 under different types. The provider is whichever part names it.
  *
- * @param target - The target Reasoning object to accumulate into.
- * @param add - The Reasoning object to add from.
- * @returns - The updated Reasoning object.
+ * @param target - The reasoning accumulated so far.
+ * @param add - The reasoning to append.
+ * @returns - The accumulated reasoning.
  */
 export function accumulateReasoning(target, add) {
-    if (!target) {
-        return add;
-    }
     if (!add) {
         return target;
     }
-    if (add.content) {
-        target.content = appendMaybe(target.content || undefined, add.content);
-    }
-    if (add.details?.length) {
-        target.details = target.details || [];
-        for (const detail of add.details) {
-            let existing = target.details.find(d => (detail.id && d.id && detail.id === d.id) ||
-                (detail.index !== undefined && d.index !== undefined && detail.index === d.index));
-            const missingIdentifiers = add.details.every(d => !d.id && d.index === undefined) &&
-                target.details.every(d => !d.id && d.index === undefined);
-            if (missingIdentifiers) {
-                existing = target.details.find(d => d.type === detail.type);
-            }
-            if (existing) {
-                if (detail.data) {
-                    existing.data = appendMaybe(existing.data, detail.data);
-                }
-                if (detail.text) {
-                    existing.text = appendMaybe(existing.text, detail.text);
-                    if (detail.signature) {
-                        existing.signature = detail.signature;
-                    }
-                }
-                if (detail.summary) {
-                    existing.summary = appendMaybe(existing.summary, detail.summary);
-                }
-            }
-            else {
-                target.details.push(detail);
-            }
+    const details = [...target?.details ?? []];
+    for (const detail of add.details ?? []) {
+        const at = details.findIndex(d => d.type === detail.type && (d.id && detail.id ? d.id === detail.id : d.index === detail.index));
+        if (at === -1) {
+            details.push(detail);
+        }
+        else {
+            const existing = details[at];
+            details[at] = {
+                ...existing,
+                id: existing.id || detail.id,
+                text: concat(existing.text, detail.text),
+                summary: concat(existing.summary, detail.summary),
+                data: concat(existing.data, detail.data),
+                signature: detail.signature ?? existing.signature,
+            };
         }
     }
-    return target;
+    return {
+        content: concat(target?.content, add.content),
+        details: details.length ? details : undefined,
+        provider: target?.provider ?? add.provider,
+    };
+}
+/**
+ * Whether reasoning goes back to a provider: it came from there, or names no
+ * provider. Signed and encrypted reasoning only verifies where it was made.
+ *
+ * @param reasoning - The reasoning of an earlier assistant turn.
+ * @param provider - The provider the conversation goes to.
+ * @returns - Whether to replay the reasoning.
+ */
+export function replaysTo(reasoning, provider) {
+    return !!reasoning && (!reasoning.provider || reasoning.provider === provider);
 }
 /**
  * Converts a Response object into an array of Chunk objects.
@@ -431,6 +431,11 @@ export function getChunksFromResponse(response) {
         finishReason: response.finishReason,
         usage: response.usage,
         model: response.model,
+        citations: response.citations,
+        images: response.images,
+        audio: response.audio,
+        moderation: response.moderation,
+        serviceTier: response.serviceTier,
     });
     return chunks;
 }