@absolutejs/ai 0.0.58 → 0.1.1

package/dist/src/ai/contextPolicy.d.ts

@@ -0,0 +1,46 @@
+import type { AIChunk, AIProviderConfig, AIProviderMessage, AIProviderStreamParams } from "../../types/ai";
+import { type AIInputCapacity } from "./inputCapacity";
+/** Token budgets, never character approximations or guessed model limits. */
+export type AIContextBudget = {
+    /** Optional working target below the model's hard input capacity. */
+    workingInputTokens?: number;
+    /** Default: 1% of available input, capped at 2,048 tokens. */
+    countingMarginTokens?: number;
+    /** Default with tools: 10% of available input, capped at 8,192 tokens. */
+    toolResultReserveTokens?: number;
+};
+export type AIContextCapacity = AIInputCapacity & {
+    workingInputTokens: number;
+    countingMarginTokens: number;
+    toolResultReserveTokens: number;
+    withinWorkingLimit: boolean;
+};
+export type AIContextRecoveryReason = "working_limit" | "provider_rejection";
+export type AIContextEvent = {
+    type: "checked";
+    capacity: AIContextCapacity;
+} | {
+    type: "recovered";
+    reason: AIContextRecoveryReason;
+    before: AIContextCapacity;
+    after: AIContextCapacity;
+};
+export type AIContextPolicy = AIContextBudget & {
+    /** Called at most once per model turn, before any output. Preserve originals
+     * in application storage; return compacted/retrieved messages, never effects.
+     * Tool IDs/inputs, signed thinking, media, provider data and system messages
+     * must remain intact. Tool result text may be replaced with saved-source notes. */
+    recover?: (input: {
+        params: AIProviderStreamParams;
+        capacity: AIContextCapacity;
+        reason: AIContextRecoveryReason;
+    }) => Promise<AIProviderMessage[]>;
+    onEvent?: (event: AIContextEvent) => void;
+};
+export declare const inspectAIContext: (provider: AIProviderConfig, params: AIProviderStreamParams, budget?: AIContextBudget) => Promise<AIContextCapacity>;
+/** Only an explicit structured capacity rejection qualifies; arbitrary 400s,
+ * timeouts and provider outages do not. Provider adapters may add a classifier. */
+export declare const isAIContextRejection: (error: unknown) => boolean;
+/** Shared high-level dispatch. `false` deliberately opts into raw provider
+ * behavior. Recovery never replays emitted output or executes application tools. */
+export declare const streamWithAIContext: (provider: AIProviderConfig, params: AIProviderStreamParams, policy?: AIContextPolicy | false, onPrepared?: (params: AIProviderStreamParams) => void) => AsyncGenerator<AIChunk>;

package/dist/src/ai/generateAI.d.ts

@@ -1,10 +1,12 @@
-import type { AICitationChunk, AIProviderConfig, AIProviderMessage, AIProviderResponseFormat, AIProviderToolChoice, AIProviderToolDefinition, AIResponseMetadata, AIToolMap, AIUsage, ReasoningConfig } from "../../types/ai";
+import { type AIContextPolicy } from "./contextPolicy";
+import type { AICitationChunk, AIProviderConfig, AIProviderContentBlock, AIProviderMessage, AIProviderResponseFormat, AIProviderToolChoice, AIProviderToolDefinition, AIResponseMetadata, AIToolMap, AIUsage, ReasoningConfig } from "../../types/ai";
 export type GenerateAIToolCall = {
     id: string;
     name: string;
     input: unknown;
 };
 export type GenerateAIOptions = {
+    contextPolicy?: AIContextPolicy | false;
     provider: AIProviderConfig;
     model: string;
     messages: AIProviderMessage[];
@@ -26,6 +28,10 @@ export type GenerateAIOptions = {
     signal?: AbortSignal;
 };
 export type GenerateAIResult = {
+    /** Exact assistant blocks retained for protocol-safe tool/repair turns. */
+    contentBlocks?: AIProviderContentBlock[];
+    /** Actual request history after any context recovery. */
+    requestMessages?: AIProviderMessage[];
     citations: AICitationChunk[];
     metadata?: AIResponseMetadata;
     text: string;
@@ -67,6 +73,7 @@ export declare const toProviderTools: (tools: AIToolMap) => AIProviderToolDefini
  */
 export declare const generateAIWithTools: (options: GenerateAIWithToolsOptions) => Promise<GenerateAIWithToolsResult>;
 export type GenerateObjectAIOptions<T> = {
+    contextPolicy?: AIContextPolicy | false;
     provider: AIProviderConfig;
     model: string;
     messages: AIProviderMessage[];

package/dist/src/ai/index.d.ts

@@ -39,8 +39,11 @@ export * from "../../types/ai";
 export type { SessionStore } from "../../types/session";
 export { AIInputError, inspectAIInput } from "./inputCapacity";
 export type { AIModelLimits, AIInputCapacity } from "./inputCapacity";
-export { prepareAITextInput } from "./prepareTextInput";
-export type { PreparedAITextInput, PrepareAITextInputOptions, } from "./prepareTextInput";
+export { prepareAITextInput, prepareAITextInputStep } from "./prepareTextInput";
+export type { PreparedAITextInput, AITextPreparationStep, PrepareAITextInputOptions, } from "./prepareTextInput";
 export { createAITextSource } from "./textSource";
 export type { AITextPassage, AITextSource } from "./textSource";
 export type { AITextPreparationCheckpoint } from "./prepareTextInput";
+export { inspectAIContext, streamWithAIContext, isAIContextRejection, } from "./contextPolicy";
+export type { AIContextBudget, AIContextCapacity, AIContextPolicy, AIContextEvent, AIContextRecoveryReason, } from "./contextPolicy";
+export { createAIStoredToolResultRecovery } from "./storedToolResultRecovery";

package/dist/src/ai/prepareTextInput.d.ts

@@ -1,3 +1,4 @@
+import { type AIContextBudget } from "./contextPolicy";
 import type { AIProviderConfig, AIProviderStreamParams, AIUsage } from "../../types/ai";
 export type AITextPreparationCheckpoint = {
     version: 1;
@@ -13,6 +14,15 @@ export type PreparedAITextInput = {
     sectionsProcessed: number;
 };
 export type PrepareAITextInputOptions = {
+    contextBudget?: AIContextBudget;
+    /** Optional model on the same provider for source-note preparation only.
+     * The final request retains params.model. Validate quality for your workload
+     * before choosing a cheaper model; originals must remain available. */
+    preparationModel?: string;
+    /** Final instructions/tools used only after compaction, counted before reading
+     * the source. Retrieval tools must not be added after preparation has fitted
+     * the final request. The direct, already-fitting request is unchanged. */
+    compactedContext?: Pick<AIProviderStreamParams, "systemPrompt" | "tools">;
     /** Reuse only a server-owned checkpoint. Originals and task fingerprints are validated. */
     checkpoint?: AITextPreparationCheckpoint;
     /** Save after each finished section, before the next model call. Never accept client-supplied notes. */
@@ -26,8 +36,19 @@ export type PrepareAITextInputOptions = {
     /** Each section is a real model call; applications must meter its usage. */
     onUsage?: (usage: AIUsage) => void;
 };
-/** Fit text using this provider's tokenizer and model capacity. Never truncates source.
- * Oversized conversations are read sequentially into rolling notes, with every section
- * counted before generation. Originals and tool history are never mutated.
+export type AITextPreparationStep = {
+    status: "ready";
+    prepared: PreparedAITextInput;
+} | {
+    status: "pending";
+    checkpoint: AITextPreparationCheckpoint;
+};
+/** Process at most one source section. Persist the checkpoint and schedule a
+ * continuation when pending; never send partial notes as a completed request.
+ * A final continuation validates the assembled request without another model
+ * call. The caller owns durable scheduling, originals and attempt fencing.
  */
+export declare const prepareAITextInputStep: (provider: AIProviderConfig, params: AIProviderStreamParams, options?: PrepareAITextInputOptions) => Promise<AITextPreparationStep>;
+/** Prepare all sections in this invocation. Use prepareAITextInputStep for
+ * bounded durable workers; this convenience entrypoint retains its contract. */
 export declare const prepareAITextInput: (provider: AIProviderConfig, params: AIProviderStreamParams, options?: PrepareAITextInputOptions) => Promise<PreparedAITextInput>;

package/dist/src/ai/storedToolResultRecovery.d.ts

@@ -0,0 +1,7 @@
+import type { AIContextPolicy } from "./contextPolicy";
+/** Reclaim older results ONLY for tools that reread immutable saved sources.
+ * The caller guarantees these names can reproduce the original at the same
+ * authorized version. Other results, calls, thinking and the newest lookup stay
+ * intact. This does not delete originals, summarize facts, run tools, or truncate
+ * the latest evidence. If that is insufficient, the policy fails explicitly. */
+export declare const createAIStoredToolResultRecovery: (toolNames: readonly string[]) => NonNullable<AIContextPolicy["recover"]>;

package/dist/src/ai/streamAIWithTools.d.ts

@@ -5,7 +5,7 @@ export type StreamAIWithToolsOptions = Omit<GenerateAIOptions, "tools" | "toolCh
     tools: AIToolMap;
     /** Stop immediately after one of these tools executes successfully; do not generate an extra reply. */
     stopAfterTools?: string[];
-    /** Count every model request, including added tool results, against provider capacity. */
+    /** @deprecated Capacity validation is automatic. Use contextPolicy; false is the explicit raw opt-out. */
     validateInput?: boolean;
     /** Max model⇄tool round-trips before forcing a final answer. Default 8. */
     maxTurns?: number;

package/dist/types/ai.d.ts

@@ -332,6 +332,8 @@ export type AIProviderToolDefinition = {
 };
 export type AIProviderConfig = {
     inputCapacity?: {
+        /** Recognize only genuine model-context rejections, never arbitrary 400s. */
+        isContextError?: (error: unknown) => boolean;
         outputTokens?: (params: AIProviderStreamParams) => number | undefined;
         getLimits: (params: AIProviderStreamParams) => Promise<import("../src/ai/inputCapacity").AIModelLimits>;
         countTokens: (params: AIProviderStreamParams) => Promise<number>;
@@ -604,6 +606,8 @@ export type AIConversationSummary = {
     lastMessageAt?: number;
 };
 export type StreamAIOptions = {
+    /** Automatic capacity checks; false explicitly selects raw provider behavior. */
+    contextPolicy?: import("../src/ai/contextPolicy").AIContextPolicy | false;
     provider: AIProviderConfig;
     model: string;
     messages?: AIProviderMessage[];
@@ -797,6 +801,7 @@ export type AIHTMXRenderConfig = {
     error?: (message: string) => string;
 };
 export type AIChatPluginConfig = {
+    contextPolicy?: import("../src/ai/contextPolicy").AIContextPolicy | false;
     path?: string;
     provider: (providerName: string) => AIProviderConfig;
     model?: string | ((providerName: string) => string);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/ai",
-  "version": "0.0.58",
+  "version": "0.1.1",
   "homepage": "https://github.com/absolutejs/ai",
   "bugs": {
     "url": "https://github.com/absolutejs/ai/issues"
@@ -124,7 +124,7 @@
     "@absolutejs/absolute": "^0.20.0-beta.0",
     "@absolutejs/changelog": "^0.6.0",
     "@absolutejs/isolated-jsc": "0.6.0",
-    "@absolutejs/sync": "2.9.1",
+    "@absolutejs/sync": "2.14.0",
     "@angular/core": "^21.0.0",
     "@eslint/js": "^10.0.1",
     "@types/bun": "1.3.9",
@@ -145,6 +145,7 @@
     "build": "bun run scripts/build.ts",
     "config": "absolute config",
     "typecheck": "tsc --noEmit --project tsconfig.json",
+    "test:built-context": "bun scripts/verifyBuiltContext.ts",
     "lint": "eslint . --max-warnings 0",
     "format": "prettier --write .",
     "release": "bun run format && bun run build && bun publish",