@absolutejs/ai 0.0.57 → 0.1.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ 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.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
+
+- **Keep compacted text useful with read-only original-source search, checkpointed ingestion, and capacity-checked terminal tool loops** (`createAITextSource`, `prepareAITextInput`, `PrepareAITextInputOptions`, `streamAIWithTools`, `StreamAIWithToolsOptions`)
+
 ## 0.0.57 — 2026-09-15
 
 ### Added

package/README.md

@@ -358,6 +358,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
@@ -371,3 +379,99 @@ multimodal histories rather than flattening them. Handle preparation errors in
 the UI while preserving the original input; expose retry without clearing the
 conversation. File upload/storage limits are application transport limits and
 should be reported separately from model capacity.
+
+#### Keep originals useful after compaction
+
+`createAITextSource(messages)` builds a session-scoped, read-only source index.
+Its `tools` map exposes `search_text_source` and `read_text_source` for use with
+`streamAIWithTools`. Search returns bounded **verbatim** passages with stable
+message IDs and character offsets; read can retrieve adjoining passages. This
+is lexical search, so ask the model to try alternate terms and never treat no
+matches as proof a fact is absent. Keep originals persisted and rebuild the
+index on resume. The index performs no model calls or external network access.
+
+Attach these tools when using compacted notes, and instruct the model to verify
+numbers, dates, exceptions, and corrections in the originals before finalizing.
+Never make the rolling summary the only accessible copy of a large document.
+
+`prepareAITextInput` accepts a server-owned `checkpoint` and calls
+`onCheckpoint` after each completed section. Store that checkpoint for retries;
+its model/task and original-prefix fingerprints must match before it is reused.
+Edited input or changed instructions invalidate it. Original text remains the
+source of truth. Do not accept checkpoints or generated notes from a client.
+
+`streamAIWithTools({ validateInput: true, ... })` checks every model request,
+including accumulated tool results, before sending it. It also rejects streams
+that end without a completion marker. `stopAfterTools: ["finish"]` stops after a
+named tool succeeds, avoiding an extra generation or later tool side effects
+when the application is ready to validate and persist a result.
+
+For a bounded live regression against the intake model, set `ANTHROPIC_API_KEY`
+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

@@ -2,6 +2,74 @@
 	"contract": 1,
 	"name": "@absolutejs/ai",
 	"releases": [
+		{
+			"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": [
 				{