@absolutejs/ai 0.0.56 → 0.0.58

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

@@ -37,3 +37,10 @@ export { fetchProviderApiStatus, startProviderStatusMonitor, } from "./providerS
 export type { ProviderApiStatus, ProviderStatusMonitorOptions, } from "./providerStatusMonitor";
 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 { createAITextSource } from "./textSource";
+export type { AITextPassage, AITextSource } from "./textSource";
+export type { AITextPreparationCheckpoint } from "./prepareTextInput";

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

@@ -0,0 +1,25 @@
+import type { AIProviderConfig, AIProviderStreamParams } from "../../types/ai";
+/** Provider-reported limits. Some providers have separate input/output windows. */
+export type AIModelLimits = {
+    maxInputTokens: number;
+    maxOutputTokens: number;
+    contextWindowTokens?: number;
+};
+export type AIInputCapacity = {
+    limits: AIModelLimits;
+    inputTokens: number;
+    outputTokens: number;
+    availableInputTokens: number;
+    fits: boolean;
+};
+export declare class AIInputError extends Error {
+    readonly code: "capacity_unavailable" | "input_too_large" | "unsupported_content";
+    constructor(code: "capacity_unavailable" | "input_too_large" | "unsupported_content", message: string);
+}
+export declare const positiveTokenLimit: (value: unknown) => number;
+export declare const inputTokenCount: (value: unknown) => number;
+/** No character/token conversion guesses. Includes the serialized prompt and tools. */
+export declare const inspectAIInput: (provider: AIProviderConfig, params: AIProviderStreamParams) => Promise<AIInputCapacity>;
+/** Cache metadata per provider instance; use a zero TTL with rotating auth/headers. never cache failures. */
+export declare const cacheModelLimits: (load: (params: AIProviderStreamParams) => Promise<AIModelLimits>, ttlMs?: number) => (params: AIProviderStreamParams) => Promise<AIModelLimits>;
+export declare const capacityJson: (response: Response) => Promise<Record<string, unknown>>;

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

@@ -0,0 +1,33 @@
+import type { AIProviderConfig, AIProviderStreamParams, AIUsage } from "../../types/ai";
+export type AITextPreparationCheckpoint = {
+    version: 1;
+    taskHash: string;
+    prefixHash: string;
+    processedCharacters: number;
+    sectionsProcessed: number;
+    notes: string;
+};
+export type PreparedAITextInput = {
+    params: AIProviderStreamParams;
+    compacted: boolean;
+    sectionsProcessed: number;
+};
+export type PrepareAITextInputOptions = {
+    /** 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. */
+    onCheckpoint?: (checkpoint: AITextPreparationCheckpoint) => void | Promise<void>;
+    /** Persist originals BEFORE calling. Returned notes are not a replacement for source storage. */
+    onProgress?: (progress: {
+        processedCharacters: number;
+        totalCharacters: number;
+        sectionsProcessed: number;
+    }) => void;
+    /** 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 declare const prepareAITextInput: (provider: AIProviderConfig, params: AIProviderStreamParams, options?: PrepareAITextInputOptions) => Promise<PreparedAITextInput>;

package/dist/src/ai/providers/gemini.d.ts

@@ -3,6 +3,7 @@ type GeminiConfig = {
     apiKey: string;
     baseUrl?: string;
     imageModels?: Set<string> | string[];
+    fetch?: typeof globalThis.fetch;
 };
 export declare const gemini: (config: GeminiConfig) => AIProviderConfig;
 export {};

package/dist/src/ai/providers/openai.d.ts

@@ -1,5 +1,6 @@
 import type { AIProviderConfig, AIProviderStreamParams } from "../../../types/ai";
 export type OpenAIConfig = {
+    modelLimits?: (params: AIProviderStreamParams) => Promise<import("../inputCapacity").AIModelLimits>;
     apiKey?: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;

package/dist/src/ai/providers/openaiCapacity.d.ts

@@ -0,0 +1,11 @@
+import type { AIProviderConfig, AIProviderStreamParams } from "../../../types/ai";
+import { type AIModelLimits } from "../inputCapacity";
+export declare const openaiInputCapacity: (config: {
+    baseUrl: string;
+    fetch: typeof globalThis.fetch;
+    key: () => Promise<string>;
+    headers: (params: AIProviderStreamParams) => Promise<HeadersInit>;
+    body: (params: AIProviderStreamParams) => Record<string, unknown>;
+    /** For private deployments or models not yet in the documented catalog. */
+    modelLimits?: (params: AIProviderStreamParams) => Promise<AIModelLimits>;
+}) => NonNullable<AIProviderConfig["inputCapacity"]>;

package/dist/src/ai/providers/openaiResponses.d.ts

@@ -1,5 +1,6 @@
 import type { AIProviderConfig, AIProviderStreamParams } from "../../../types/ai";
 export type OpenAIResponsesConfig = {
+    modelLimits?: (params: AIProviderStreamParams) => Promise<import("../inputCapacity").AIModelLimits>;
     apiKey?: string;
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
@@ -10,4 +11,5 @@ export type OpenAIResponsesConfig = {
     tokenSource?: () => Promise<string> | string;
     transformRequestBody?: (body: Record<string, unknown>, params: AIProviderStreamParams) => Record<string, unknown>;
 };
+export declare const buildResponsesRequestBody: (params: AIProviderStreamParams, isImageModel: boolean, capabilityModel?: string) => Record<string, unknown>;
 export declare const openaiResponses: (config: OpenAIResponsesConfig) => AIProviderConfig;

package/dist/src/ai/providers/openrouterClient.d.ts

@@ -624,7 +624,7 @@ export declare const createOpenRouterClient: (config: OpenRouterClientConfig) =>
     request: <T>(path: string, options?: OpenRouterHttpRequestOptions) => Promise<T>;
     requestRaw: (path: string, options?: OpenRouterHttpRequestOptions) => Promise<Response>;
     streamImage: (body: Omit<OpenRouterImageRequest, "stream">, options?: Omit<OpenRouterHttpRequestOptions, "body" | "method">) => AsyncGenerator<OpenRouterImageStreamEvent, void, any>;
-    respond: (body: OpenRouterResponsesRequest) => Promise<Response> | Promise<Record<string, unknown>>;
+    respond: (body: OpenRouterResponsesRequest) => Promise<Record<string, unknown>> | Promise<Response>;
     rerank: (body: OpenRouterRerankRequest) => Promise<OpenRouterRerankResponse>;
     speak: (body: OpenRouterSpeechRequest) => Promise<Response>;
     transcribe: (body: OpenRouterTranscriptionRequest | FormData) => Promise<OpenRouterTranscriptionResponse>;

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

@@ -3,6 +3,10 @@ import { type GenerateAIOptions, type GenerateAIToolCall } from "./generateAI";
 export type StreamAIWithToolsOptions = Omit<GenerateAIOptions, "tools" | "toolChoice"> & {
     /** Tools the model may call — each with a `handler` the loop runs on its behalf. */
     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. */
+    validateInput?: boolean;
     /** Max model⇄tool round-trips before forcing a final answer. Default 8. */
     maxTurns?: number;
     toolChoice?: AIProviderToolChoice;

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

@@ -0,0 +1,19 @@
+import type { AIProviderMessage, AIToolMap } from "../../types/ai";
+export type AITextPassage = {
+    sourceId: string;
+    role: AIProviderMessage["role"];
+    start: number;
+    end: number;
+    totalCharacters: number;
+    text: string;
+};
+/** Session-scoped, read-only access to original text. No network or model calls.
+ * IDs/UTF-16 offsets stay stable when later messages are appended. Results carry
+ * verbatim source, not generated summaries. Persist originals separately.
+ */
+export declare const createAITextSource: (messages: readonly AIProviderMessage[]) => {
+    search: (query: string, sourceId?: string) => AITextPassage[];
+    read: (sourceId: string, start?: number, length?: number) => AITextPassage;
+    tools: AIToolMap;
+};
+export type AITextSource = ReturnType<typeof createAITextSource>;

package/dist/types/ai.d.ts

@@ -331,6 +331,11 @@ export type AIProviderToolDefinition = {
     input_schema: Record<string, unknown>;
 };
 export type AIProviderConfig = {
+    inputCapacity?: {
+        outputTokens?: (params: AIProviderStreamParams) => number | undefined;
+        getLimits: (params: AIProviderStreamParams) => Promise<import("../src/ai/inputCapacity").AIModelLimits>;
+        countTokens: (params: AIProviderStreamParams) => Promise<number>;
+    };
     stream: (params: AIProviderStreamParams) => AsyncIterable<AIChunk>;
 };
 /** MCP-shaped behavior hints (all optional). Consumers exposing an AIToolMap

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/ai",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "homepage": "https://github.com/absolutejs/ai",
   "bugs": {
     "url": "https://github.com/absolutejs/ai/issues"
@@ -11,8 +11,10 @@
   "main": "./dist/ai/index.js",
   "types": "./dist/src/ai/index.d.ts",
   "files": [
-    "dist",
-    "README.md"
+    "CHANGELOG.md",
+    "README.md",
+    "changelog.json",
+    "dist"
   ],
   "exports": {
     ".": {
@@ -120,7 +122,9 @@
   },
   "devDependencies": {
     "@absolutejs/absolute": "^0.20.0-beta.0",
+    "@absolutejs/changelog": "^0.6.0",
     "@absolutejs/isolated-jsc": "0.6.0",
+    "@absolutejs/sync": "2.9.1",
     "@angular/core": "^21.0.0",
     "@eslint/js": "^10.0.1",
     "@types/bun": "1.3.9",
@@ -135,8 +139,7 @@
     "svelte": "5.55.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.56.1",
-    "vue": "3.5.27",
-    "@absolutejs/sync": "2.9.1"
+    "vue": "3.5.27"
   },
   "scripts": {
     "build": "bun run scripts/build.ts",
@@ -144,7 +147,9 @@
     "typecheck": "tsc --noEmit --project tsconfig.json",
     "lint": "eslint . --max-warnings 0",
     "format": "prettier --write .",
-    "release": "bun run format && bun run build && bun publish"
+    "release": "bun run format && bun run build && bun publish",
+    "check:package": "absolute-changelog check",
+    "prepublishOnly": "bun run check:package"
   },
   "publishConfig": {
     "access": "public"