@absolutejs/ai 0.0.58 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,31 @@ This file is generated by `absolute-changelog` from the entries in
 `changelog/`. Edit an entry, not this file — and add new ones under
 `changelog/unreleased/`.
 
+## 0.1.1 — 2026-09-16
+
+### Added
+
+- **Allow a separate preparation model with its own verified capacity while preserving the final answer model and invalidating notes when the preparation model changes** (`PrepareAITextInputOptions`, `prepareAITextInput`, `prepareAITextInputStep`)
+
+### Fixed
+
+- **Fill preparation sections with bounded tokenizer-checked refinement, avoid duplicate final counting, and honor cancellation before generation** (`prepareAITextInput`, `prepareAITextInputStep`)
+
+## 0.1.0 — 2026-09-16
+
+### Added
+
+- **Add one-section text preparation steps for durable workers, with explicit pending/ready outcomes and checkpoint persistence before yielding** (`prepareAITextInputStep`, `AITextPreparationStep`)
+- **Budget final retrieval instructions and tools before compacting text, with matching checkpoint invalidation** (`PrepareAITextInputOptions`, `prepareAITextInput`)
+
+### Changed
+
+- **Validate model capacity by default across generation, structured output, WebSocket and SSE entry points; reserve token headroom and support one protocol-preserving context recovery attempt. Providers without counting capability now fail explicitly; contextPolicy: false opts into raw behavior.** (`generateAI`, `generateAIWithTools`, `generateObjectAI`, `streamAI`, `streamAIToSSE`, `streamAIWithTools`, `inspectAIContext`, `createAIStoredToolResultRecovery`, `StreamAIWithToolsOptions`, `GenerateAIOptions`, `GenerateAIResult`, `GenerateObjectAIOptions`, `AIProviderConfig`, `StreamAIOptions`, `AIChatPluginConfig`)
+
+### Fixed
+
+- **Preserve conversation origin across long-text preparation sections, distinguish source facts from embedded instructions, reserve more of the available context for factual notes, and invalidate checkpoints from the previous preparation policy** (`prepareAITextInput`, `prepareAITextInputStep`)
+
 ## 0.0.58 — 2026-09-15
 
 ### Added

package/README.md

@@ -343,6 +343,20 @@ unchanged. Oversized text is read in counted sections into rolling notes; the
 final request is counted again before being returned. Summaries can lose detail,
 so persist the original source first and retain it for download and resume.
 
+Section sizing uses bounded tokenizer checks to fill available context more
+closely before generating notes. This reduces repeated note generation when
+halving alone would leave sections underfilled. Every generated section still
+passes the provider's token count and capacity checks; no character-to-token
+ratio is assumed. Existing checkpoints remain resumable.
+
+Use `preparationModel` to select a different model on the same provider for
+reading source sections into notes. Its own token capacity is checked; the
+returned final request keeps the original model and output budget. Changing
+this option invalidates saved notes. The default uses the original model.
+Evaluate factual coverage and original-source evidence with your workload
+before choosing a cheaper preparation model. Usage callbacks still report each
+preparation call, and provider instrumentation sees its actual model.
+
 ```ts
 import { prepareAITextInput } from "@absolutejs/ai";
 
@@ -358,6 +372,14 @@ for await (const chunk of provider.stream(prepared.params)) {
 }
 ```
 
+When compacted requests need extra retrieval tools or different instructions,
+pass them as `options.compactedContext` (`systemPrompt` and/or `tools`). These
+replace the corresponding fields only on the compacted path. Preparation checks
+that final context before reading the source and budgets the notes against it;
+send the returned `params` without adding uncounted tools afterward. Changing the
+compacted context invalidates a saved preparation checkpoint. Already-fitting
+requests retain their original tools and instructions.
+
 Anthropic and Gemini retrieve native model metadata and count using their native
 APIs. OpenAI uses its input-token counting API and an exact, documented model
 catalog because its model-list API does not expose context limits. OpenAI
@@ -403,3 +425,74 @@ and run `bun scripts/eval-text-source.ts`. It uses synthetic text, simulates a
 small context, and verifies that original-source lookups recover later budget
 and deadline corrections omitted from the notes. It makes real, billed model
 calls; the ordinary test suite uses deterministic local providers instead.
+
+For durable workers, `prepareAITextInputStep(provider, params, options)` processes
+at most one source section and returns either `{ status: "pending", checkpoint }`
+or `{ status: "ready", prepared }`. Persist originals and the exact request,
+save the checkpoint under the current job attempt, and enqueue another step when
+pending. The final continuation validates the assembled request without another
+model call. A pending checkpoint is not a completed model input. Persistence
+errors propagate before a step reports success; the caller owns atomic scheduling,
+retry limits and attempt fencing. `prepareAITextInput` retains its existing
+all-sections convenience behavior.
+
+### Automatic context policy (next breaking release)
+
+High-level generation, structured-output, streaming and chat-plugin entry points
+now validate every final model request automatically, including requests after
+local tools and structured-output repair. The provider owns model metadata and
+counting; unknown models or providers without that capability raise
+`AIInputError` with `code: "capacity_unavailable"`. A character count is never
+used as a model limit. Counting can require an additional provider API request.
+
+The shared `contextPolicy` reserves the provider's effective output budget, plus
+1% of available input (capped at 2,048 tokens) for counting margin and, when local
+tools are enabled, 10% (capped at 8,192 tokens) for tool-result growth. These are
+configurable working-budget defaults, not claimed model limits or quality-optimal
+settings. `workingInputTokens` can set a lower application target.
+`prepareAITextInput` and `prepareAITextInputStep` use the same budgets through
+`contextBudget`, so preparation does not fill headroom reserved by generation.
+
+```ts
+const contextPolicy = {
+  workingInputTokens: 80_000,
+  // Only tools backed by immutable, authorized saved originals:
+  recover: createAIStoredToolResultRecovery([
+    "search_text_source",
+    "read_text_source",
+  ]),
+};
+const result = await generateAIWithTools({
+  provider,
+  model,
+  messages,
+  tools,
+  contextPolicy,
+});
+```
+
+The saved-source recovery helper replaces only older lookup results with explicit
+reread instructions. It keeps the newest lookup, source-call arguments and every
+other tool result. It never deletes originals, runs tools, invents a summary or
+truncates the newest passage. Callers must ensure listed tools can reread the same
+immutable versions. If this cannot fit the budget, `input_too_large` is returned.
+This helper is not appropriate for unsaved or changing external results.
+
+A custom `recover({params, capacity, reason})` may instead return compacted or
+retrieved messages after saving originals. It runs at most once per model turn,
+receives an isolated snapshot, and must actually reduce token usage and fit the
+working budget. Tool calls/results must keep their IDs and grouping; signed
+thinking, media, provider data and system messages cannot change. The recovered
+history is retained across later tool turns. Recovery never reexecutes a tool.
+A second rejection, unsupported error, or error after any emitted chunk propagates
+without a capacity retry. Recognized provider rejection formats are deliberately
+narrow; other adapters may supply `inputCapacity.isContextError`.
+
+Migration: supply provider capacity support, or explicitly use
+`contextPolicy: false` to retain raw behavior. Direct `provider.stream(params)`
+remains the raw seam. The old `streamAIWithTools.validateInput` flag is deprecated;
+its explicit `false` remains an opt-out unless `contextPolicy` is supplied.
+`contextPolicy` also passes through `aiChat` and the compatible RAG chat plugin.
+Applications should surface typed failures with saved-input retry UI. These
+changes do not guarantee detection of every provider-side accounting discrepancy
+or provide exactly-once external execution after a process crash.

package/changelog.json

@@ -1,47 +1,121 @@
 {
-	"contract": 1,
-	"name": "@absolutejs/ai",
-	"releases": [
-		{
-			"changes": [
-				{
-					"kind": "added",
-					"summary": "Keep compacted text useful with read-only original-source search, checkpointed ingestion, and capacity-checked terminal tool loops",
-					"symbols": [
-						"createAITextSource",
-						"prepareAITextInput",
-						"PrepareAITextInputOptions",
-						"streamAIWithTools",
-						"StreamAIWithToolsOptions"
-					]
-				}
-			],
-			"date": "2026-09-15",
-			"version": "0.0.58"
-		},
-		{
-			"changes": [
-				{
-					"kind": "internal",
-					"summary": "Regenerate the OpenRouter client declaration with equivalent reordered response union types",
-					"symbols": [
-						"createOpenRouterClient"
-					]
-				},
-				{
-					"kind": "added",
-					"summary": "Add model-specific token capacity, optional provider capacity configuration, and recoverable long-text preparation",
-					"symbols": [
-						"inspectAIInput",
-						"prepareAITextInput",
-						"AIProviderConfig",
-						"OpenAIConfig",
-						"OpenAIResponsesConfig"
-					]
-				}
-			],
-			"date": "2026-09-15",
-			"version": "0.0.57"
-		}
-	]
+  "contract": 1,
+  "name": "@absolutejs/ai",
+  "releases": [
+    {
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Allow a separate preparation model with its own verified capacity while preserving the final answer model and invalidating notes when the preparation model changes",
+          "symbols": [
+            "PrepareAITextInputOptions",
+            "prepareAITextInput",
+            "prepareAITextInputStep"
+          ]
+        },
+        {
+          "kind": "fixed",
+          "summary": "Fill preparation sections with bounded tokenizer-checked refinement, avoid duplicate final counting, and honor cancellation before generation",
+          "symbols": [
+            "prepareAITextInput",
+            "prepareAITextInputStep"
+          ]
+        }
+      ],
+      "date": "2026-09-16",
+      "version": "0.1.1"
+    },
+    {
+      "changes": [
+        {
+          "kind": "changed",
+          "summary": "Validate model capacity by default across generation, structured output, WebSocket and SSE entry points; reserve token headroom and support one protocol-preserving context recovery attempt. Providers without counting capability now fail explicitly; contextPolicy: false opts into raw behavior.",
+          "symbols": [
+            "generateAI",
+            "generateAIWithTools",
+            "generateObjectAI",
+            "streamAI",
+            "streamAIToSSE",
+            "streamAIWithTools",
+            "inspectAIContext",
+            "createAIStoredToolResultRecovery",
+            "StreamAIWithToolsOptions",
+            "GenerateAIOptions",
+            "GenerateAIResult",
+            "GenerateObjectAIOptions",
+            "AIProviderConfig",
+            "StreamAIOptions",
+            "AIChatPluginConfig"
+          ]
+        },
+        {
+          "kind": "added",
+          "summary": "Add one-section text preparation steps for durable workers, with explicit pending/ready outcomes and checkpoint persistence before yielding",
+          "symbols": [
+            "prepareAITextInputStep",
+            "AITextPreparationStep"
+          ]
+        },
+        {
+          "kind": "added",
+          "summary": "Budget final retrieval instructions and tools before compacting text, with matching checkpoint invalidation",
+          "symbols": [
+            "PrepareAITextInputOptions",
+            "prepareAITextInput"
+          ]
+        },
+        {
+          "kind": "fixed",
+          "summary": "Preserve conversation origin across long-text preparation sections, distinguish source facts from embedded instructions, reserve more of the available context for factual notes, and invalidate checkpoints from the previous preparation policy",
+          "symbols": [
+            "prepareAITextInput",
+            "prepareAITextInputStep"
+          ]
+        }
+      ],
+      "date": "2026-09-16",
+      "version": "0.1.0"
+    },
+    {
+      "changes": [
+        {
+          "kind": "added",
+          "summary": "Keep compacted text useful with read-only original-source search, checkpointed ingestion, and capacity-checked terminal tool loops",
+          "symbols": [
+            "createAITextSource",
+            "prepareAITextInput",
+            "PrepareAITextInputOptions",
+            "streamAIWithTools",
+            "StreamAIWithToolsOptions"
+          ]
+        }
+      ],
+      "date": "2026-09-15",
+      "version": "0.0.58"
+    },
+    {
+      "changes": [
+        {
+          "kind": "internal",
+          "summary": "Regenerate the OpenRouter client declaration with equivalent reordered response union types",
+          "symbols": [
+            "createOpenRouterClient"
+          ]
+        },
+        {
+          "kind": "added",
+          "summary": "Add model-specific token capacity, optional provider capacity configuration, and recoverable long-text preparation",
+          "symbols": [
+            "inspectAIInput",
+            "prepareAITextInput",
+            "AIProviderConfig",
+            "OpenAIConfig",
+            "OpenAIResponsesConfig"
+          ]
+        }
+      ],
+      "date": "2026-09-15",
+      "version": "0.0.57"
+    }
+  ]
 }