@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/ai/Ai.js

@@ -1,4 +1,5 @@
-/// <reference path="./sdkNodeCompatibility.d.ts" preserve="true" />
+import { AIProviderAdmission, AIProviderDeferredError, AIProviderStoppedError } from './AIProviderAdmission.js';
+import { isQueueRetryLaterError } from '@db3.ai/app/queue';
 import OpenAI from 'openai';
 import { OpenAIProvider } from '@openai/agents';
 import { aiExecutionContext, scopedAiOptions } from './AiExecutionContext.js';
@@ -10,15 +11,17 @@ import { AiMessage, AI_MESSAGE_ROLE } from './AiMessage.js';
 import { AiRequest, AI_REQUEST_STATUS } from './AiRequest.js';
 const defaultAIConfig = { model: 'gpt-4.1-mini' };
 import { estimateTokensFromText } from './Estimates.js';
-import { calculateAIImageRequestCostUSD, calculateAIRequestCostUSD } from './Models.js';
+import { calculateAIImageRequestCostUSD, calculateAIRequestCostUSD } from './modelPricing.js';
 import { AI_PROVIDER } from './contracts/AI.js';
 import { AIAllowanceExceededError, AIConfigurationError, AIRequestError } from './AIErrors.js';
+import { AIRequestTrackingError } from './AIRequestTrackingError.js';
 import { isFailoverableFailure, isFailoverableResponse } from './AIFailover.js';
 import { providerChainFromEnvironment, resolveProviderChain, simulatedProviderOutage } from './AIProviders.js';
 import { AIRateLimitDeferredError, AIRateLimiter, embeddingsRateLimitEndpoint, imagesRateLimitEndpoint, providerResponseMetadata, responsesRateLimitEndpoint } from './AIRateLimiter.js';
 import { isOpenAIQuotaError, openAIProviderError } from './OpenAIProviderError.js';
 import { providerReportedCostUSD } from './ProviderCosts.js';
 import { sendResponsesRequest } from './ResponsesProviderCall.js';
+import { assertAIServiceTier, effectiveAIServiceTier } from './aiServiceTier.js';
 /**
  * Raised when exact provider usage could not be made durable after bounded retries.
  *
@@ -60,6 +63,7 @@ export class Ai {
     /** Logical ownership field used by this application. */
     scopeField;
     rateLimiter;
+    providerAdmission;
     /**
      * Create an AI service instance.
      *
@@ -71,6 +75,9 @@ export class Ai {
         this.modelConfig = modelConfig;
         if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0))
             throw new AIConfigurationError('timeoutMs must be positive.');
+        this.providerAdmission = new AIProviderAdmission({ recoveryLeaseSeconds: (options.timeoutMs ?? 60_000) / 1000 + 30, ...options.providerAdmission });
+        if ((options.providerAdmission?.recoveryLeaseSeconds ?? Infinity) * 1000 <= (options.timeoutMs ?? 60_000))
+            throw new AIConfigurationError('Recovery lease must exceed provider timeout.');
         this.models = { conversation: AiConversation, request: AiRequest, message: AiMessage, ...options.models };
         this.scopeField = options.scopeField ?? 'scope';
         this.rateLimiter = options.rateLimiter === false
@@ -190,6 +197,8 @@ export class Ai {
         const result = await this.generateTextResult({
             model: input.model,
             provider: input.provider,
+            transientFailureScope: input.transientFailureScope,
+            serviceTier: input.serviceTier,
             instructions: input.instructions,
             input: input.input,
             maxOutputTokens: input.maxOutputTokens,
@@ -241,6 +250,10 @@ export class Ai {
         const operation = options.operation ?? 'responses.create';
         const attempts = this.resolveProviders(input.provider ?? null, input.model ?? null)
             .filter(attempt => attempt.supportsResponsesApi);
+        const serviceTier = input.serviceTier ?? 'default';
+        for (const attempt of attempts)
+            assertAIServiceTier(attempt.provider, serviceTier);
+        const timeoutMs = this.requestTimeoutMs(serviceTier);
         const attemptFailures = [];
         let tracked = null;
         let trackedSettled = false;
@@ -248,7 +261,7 @@ export class Ai {
             throw new AIConfigurationError('No configured AI provider in the chain supports the Responses API.');
         }
         for (let index = 0; index < attempts.length; index++) {
-            const attempt = attempts[index];
+            const attempt = { ...attempts[index], transientFailureScope: input.transientFailureScope };
             const hasFallback = index < attempts.length - 1;
             const attemptStartMs = Date.now();
             const request = {
@@ -256,7 +269,7 @@ export class Ai {
                 instructions: input.instructions,
                 input: input.input,
                 store: false,
-                ...(attempt.provider === AI_PROVIDER.openai ? { service_tier: 'default' } : {}),
+                ...(attempt.provider === AI_PROVIDER.openai ? { service_tier: serviceTier } : {}),
                 ...maxOutputTokensPayload(input.maxOutputTokens),
                 ...extraRequest,
             };
@@ -302,12 +315,13 @@ export class Ai {
                     baseUrl: attempt.baseUrl,
                     apiKey: attempt.apiKey,
                     request,
-                    fetcher: this.fetcher(),
+                    fetcher: this.providerAdmission.transport(attempt, this.fetcher(timeoutMs), timeoutMs),
                 });
                 const { payload, metadata } = result;
-                if (!result.ok) {
+                const admissionFailure = this.providerAdmission.requestFailure(attempt, null);
+                if (!result.ok || admissionFailure) {
                     const message = responseErrorMessage(payload) || `AI provider ${attempt.provider} request failed with HTTP ${result.status}.`;
-                    if (hasFallback && isFailoverableResponse(result.status, payload)) {
+                    if (hasFallback && (isFailoverableFailure(admissionFailure) || isFailoverableResponse(result.status, payload))) {
                         const failure = providerAttemptFailure(attempt, attemptStartMs, message, result.status, responseErrorCode(payload));
                         attemptFailures.push(failure);
                         if (tracked) {
@@ -325,9 +339,9 @@ export class Ai {
                         lease = null;
                         continue;
                     }
-                    const deferred = isRateLimitFailure(result.status, payload)
+                    const deferred = admissionFailure ?? (isRateLimitFailure(result.status, payload)
                         ? rateLimitDeferredError(lease, metadata, message)
-                        : null;
+                        : null);
                     if (tracked) {
                         attachProviderAttempts(tracked.aiRequest, attemptFailures);
                         await this.failTrackedRequest(tracked, payload, message, metadata, lease);
@@ -337,7 +351,7 @@ export class Ai {
                     lease = null;
                     if (deferred)
                         throw deferred;
-                    throw new AIRequestError(message, responseErrorCode(payload));
+                    throw new AIRequestError(message, responseErrorCode(payload), { status: result.status, requestId: metadata.providerRequestId });
                 }
                 const text = payload?.status !== undefined && payload.status !== 'completed' ? null : responseOutputText(payload);
                 if (!text) {
@@ -405,9 +419,9 @@ export class Ai {
                     }
                     continue;
                 }
-                if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
+                if (tracked && !trackedSettled && (!(error instanceof AIRequestError) || error instanceof AIProviderStoppedError) && !(error instanceof AIRateLimitDeferredError)) {
                     attachProviderAttempts(tracked.aiRequest, attemptFailures);
-                    await this.failTrackedRequest(tracked, null, errorMessage(error), emptyProviderResponseMetadata(), failedLease, providerStarted);
+                    await this.failTrackedRequest(tracked, providerAdmissionResponse(error), errorMessage(error), providerAdmissionMetadata(error), failedLease, providerAdmissionStarted(error, providerStarted));
                 }
                 throw error;
             }
@@ -447,7 +461,7 @@ export class Ai {
      */
     async appendTrackedProviderAttempt(tracked, input) {
         const usage = tokenUsage(input.response);
-        const modelCostUSD = textRequestCostUSD(input.attempt.provider, input.attempt.model, usage, input.response);
+        const modelCostUSD = textRequestCostUSD(input.attempt.provider, input.attempt.model, usage, input.response, input.request.service_tier);
         const aiRequest = new this.models.request({
             conversation: tracked.conversation,
             parentAiRequest: tracked.aiRequest,
@@ -565,7 +579,7 @@ export class Ai {
      */
     async completeTrackedRequest(tracked, response, metadata = emptyProviderResponseMetadata(), lease = null) {
         const usage = tokenUsage(response);
-        const costUSD = textRequestCostUSD(tracked.provider, tracked.model, usage, response);
+        const costUSD = textRequestCostUSD(tracked.provider, tracked.model, usage, response, asRecord(tracked.aiRequest.request)?.service_tier);
         tracked.aiRequest.assign({
             response,
             providerRequestId: metadata.providerRequestId,
@@ -600,7 +614,7 @@ export class Ai {
         const usage = tokenUsage(response);
         const costUSD = !providerStarted
             ? 0
-            : textRequestCostUSD(tracked.provider, tracked.model, usage, response);
+            : textRequestCostUSD(tracked.provider, tracked.model, usage, response, asRecord(tracked.aiRequest.request)?.service_tier);
         tracked.aiRequest.assign({
             response,
             providerRequestId: metadata.providerRequestId,
@@ -715,7 +729,13 @@ export class Ai {
             request,
             metadata: options.metadata ?? null,
             startedAt: new Date(),
-        }).save();
+        });
+        try {
+            await aiRequest.save();
+        }
+        catch (error) {
+            throw new AIRequestTrackingError(error);
+        }
         return {
             aiRequest,
             startTimeMs,
@@ -725,11 +745,11 @@ export class Ai {
     /**
      * Mark an embedding request completed with normalized token usage.
      */
-    async completeTrackedEmbeddingRequest(tracked, response, metadata = emptyProviderResponseMetadata(), lease = null) {
+    async completeTrackedEmbeddingRequest(tracked, response, metadata = emptyProviderResponseMetadata(), lease = null, retainResult = false) {
         const usage = embeddingTokenUsage(response);
         const costUSD = calculateAIRequestCostUSD(tracked.model, usage);
         tracked.aiRequest.assign({
-            response: compactEmbeddingResponse(response),
+            response: retainResult ? response : compactEmbeddingResponse(response),
             providerRequestId: metadata.providerRequestId,
             providerProcessingMs: metadata.providerProcessingMs,
             rateLimitBucket: lease?.bucket ?? null,
@@ -929,9 +949,11 @@ export class Ai {
      * @param initialLease - Optional preflight reservation consumed by the first request.
      * @returns SDK provider using the service's transport and rate-limit lifecycle.
      */
-    createAgentProvider(attempt, initialLease = null) {
+    createAgentProvider(attempt, initialLease = null, serviceTier = 'default') {
+        assertAIServiceTier(attempt.provider, serviceTier);
+        const timeoutMs = this.requestTimeoutMs(serviceTier);
         return new OpenAIProvider({
-            openAIClient: new OpenAI({ apiKey: attempt.apiKey, baseURL: attempt.baseUrl, fetch: this.agentFetcher(attempt, initialLease), timeout: this.options.timeoutMs ?? 60_000, maxRetries: 0 }),
+            openAIClient: new OpenAI({ apiKey: attempt.apiKey, baseURL: attempt.baseUrl, fetch: this.agentFetcher(attempt, initialLease, timeoutMs), timeout: timeoutMs, maxRetries: 0 }),
             useResponses: attempt.supportsResponsesApi,
         });
     }
@@ -947,9 +969,9 @@ export class Ai {
      * @param initialLease - First-request reservation, if acquired by the agent.
      * @returns Transport that maintains provider capacity and request diagnostics.
      */
-    agentFetcher(attempt, initialLease) {
+    agentFetcher(attempt, initialLease, timeoutMs) {
         let pendingLease = initialLease;
-        const transport = this.fetcher();
+        const transport = this.providerAdmission.transport(attempt, this.fetcher(timeoutMs), timeoutMs);
         return async (url, init) => {
             const aiRequest = aiExecutionContext.getStore()?.aiRequest ?? null;
             const lease = pendingLease ?? await this.acquireRateLimit({
@@ -986,12 +1008,20 @@ export class Ai {
             }
         };
     }
+    /** Resolves the account connection for OpenAI-only images and embeddings. */
+    openAIAdmissionAttempt(model) {
+        return { provider: AI_PROVIDER.openai, model, apiKey: this.requireApiKey(), baseUrl: this.baseUrl(), supportsResponsesApi: true };
+    }
+    /** Resolves a tier-aware request timeout while respecting an explicit service override. */
+    requestTimeoutMs(serviceTier) {
+        return this.options.timeoutMs ?? (serviceTier === 'flex' ? 900_000 : 60_000);
+    }
     /**
      * Fetch implementation used by provider calls.
      */
-    fetcher() {
+    fetcher(timeoutMs = this.options.timeoutMs ?? 60_000) {
         const transport = this.options.fetch || fetch;
-        return (url, init) => transport(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(this.options.timeoutMs ?? 60_000) });
+        return (url, init) => transport(url, { ...init, signal: init?.signal ?? AbortSignal.timeout(timeoutMs) });
     }
     /**
      * Responses API base URL with trailing slashes removed.
@@ -1077,6 +1107,7 @@ export class Ai {
         const model = input.model || this.config('ImageGeneration', 'gpt-image-2');
         const prompt = input.prompt.replace(/\s+/g, ' ').trim();
         const outputFormat = input.outputFormat ?? 'png';
+        const admissionAttempt = this.openAIAdmissionAttempt(model);
         const operation = options.operation ?? 'images.generate';
         const request = {
             model,
@@ -1125,7 +1156,7 @@ export class Ai {
             });
             await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
             providerStarted = true;
-            const response = await this.fetcher()(this.imagesUrl(), {
+            const response = await this.providerAdmission.transport(admissionAttempt, this.fetcher())(this.imagesUrl(), {
                 method: 'POST',
                 headers: {
                     authorization: `Bearer ${apiKey}`,
@@ -1135,11 +1166,12 @@ export class Ai {
             });
             const metadata = providerResponseMetadata(response.headers);
             const payload = await response.json().catch(() => null);
-            if (!response.ok) {
+            const admissionFailure = this.providerAdmission.requestFailure(admissionAttempt, null);
+            if (!response.ok || admissionFailure) {
                 const message = responseErrorMessage(payload) || `OpenAI image request failed with HTTP ${response.status}.`;
-                const deferred = isRateLimitFailure(response.status, payload)
+                const deferred = admissionFailure ?? (isRateLimitFailure(response.status, payload)
                     ? rateLimitDeferredError(lease, metadata, message)
-                    : null;
+                    : null);
                 if (tracked) {
                     await this.failTrackedImageRequest(tracked, payload, message, metadata, lease);
                     trackedSettled = true;
@@ -1148,7 +1180,7 @@ export class Ai {
                 lease = null;
                 if (deferred)
                     throw deferred;
-                throw new AIRequestError(message, responseErrorCode(payload));
+                throw new AIRequestError(message, responseErrorCode(payload), { status: response.status, requestId: metadata.providerRequestId });
             }
             const b64Json = imageBase64(payload);
             if (!b64Json) {
@@ -1209,10 +1241,10 @@ export class Ai {
                 }
             }
             await this.releaseRateLimit(lease);
-            if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
-                await this.failTrackedImageRequest(tracked, null, errorMessage(error), emptyProviderResponseMetadata(), lease, providerStarted);
+            if (tracked && !trackedSettled) {
+                await this.failTrackedImageRequest(tracked, providerAdmissionResponse(error), errorMessage(error), providerAdmissionMetadata(error), lease, providerAdmissionStarted(error, providerStarted));
             }
-            if (error instanceof AIRateLimitDeferredError)
+            if (isQueueRetryLaterError(error) || error instanceof AIProviderStoppedError)
                 throw error;
             if (error instanceof AIAllowanceExceededError)
                 throw error;
@@ -1235,6 +1267,7 @@ export class Ai {
         if (!input)
             throw new Error('Input is required for embedding generation.');
         const apiKey = this.requireApiKey();
+        const admissionAttempt = this.openAIAdmissionAttempt(model);
         const operation = options.operation ?? 'embeddings.create';
         const request = {
             model,
@@ -1273,7 +1306,7 @@ export class Ai {
             });
             await this.attachRateLimitRequest(lease, tracked?.aiRequest ?? null);
             providerStarted = true;
-            const response = await this.fetcher()(this.embeddingsUrl(), {
+            const response = await this.providerAdmission.transport(admissionAttempt, this.fetcher())(this.embeddingsUrl(), {
                 method: 'POST',
                 headers: {
                     authorization: `Bearer ${apiKey}`,
@@ -1283,11 +1316,12 @@ export class Ai {
             });
             const metadata = providerResponseMetadata(response.headers);
             const payload = await response.json().catch(() => null);
-            if (!response.ok) {
+            const admissionFailure = this.providerAdmission.requestFailure(admissionAttempt, null);
+            if (!response.ok || admissionFailure) {
                 const message = responseErrorMessage(payload) || `OpenAI embedding request failed with HTTP ${response.status}.`;
-                const deferred = isRateLimitFailure(response.status, payload)
+                const deferred = admissionFailure ?? (isRateLimitFailure(response.status, payload)
                     ? rateLimitDeferredError(lease, metadata, message)
-                    : null;
+                    : null);
                 if (tracked) {
                     await this.failTrackedEmbeddingRequest(tracked, payload, message, metadata, lease);
                     trackedSettled = true;
@@ -1296,7 +1330,7 @@ export class Ai {
                 lease = null;
                 if (deferred)
                     throw deferred;
-                throw new AIRequestError(message, responseErrorCode(payload));
+                throw new AIRequestError(message, responseErrorCode(payload), { status: response.status, requestId: metadata.providerRequestId });
             }
             const vector = payload?.data?.[0]?.embedding;
             if (!Array.isArray(vector)) {
@@ -1310,7 +1344,7 @@ export class Ai {
                 throw new AIRequestError(message, responseErrorCode(payload));
             }
             if (tracked) {
-                await this.completeTrackedEmbeddingRequest(tracked, payload, metadata, lease);
+                await this.completeTrackedEmbeddingRequest(tracked, payload, metadata, lease, options.retainResult === true);
                 trackedSettled = true;
             }
             await this.observeRateLimit(lease, metadata);
@@ -1331,10 +1365,12 @@ export class Ai {
                 }
             }
             await this.releaseRateLimit(lease);
-            if (tracked && !trackedSettled && !(error instanceof AIRequestError) && !(error instanceof AIRateLimitDeferredError)) {
-                await this.failTrackedEmbeddingRequest(tracked, null, errorMessage(error), emptyProviderResponseMetadata(), lease, providerStarted);
+            if (tracked && !trackedSettled && (!(error instanceof AIRequestError) || error instanceof AIProviderStoppedError) && !(error instanceof AIRateLimitDeferredError)) {
+                await this.failTrackedEmbeddingRequest(tracked, providerAdmissionResponse(error), errorMessage(error), providerAdmissionMetadata(error), lease, providerAdmissionStarted(error, providerStarted));
             }
-            if (error instanceof AIRateLimitDeferredError)
+            if (isQueueRetryLaterError(error) || error instanceof AIProviderStoppedError)
+                throw error;
+            if (error instanceof AIRequestTrackingError)
                 throw error;
             if (error instanceof AIRequestError)
                 throw error;
@@ -1487,7 +1523,9 @@ function attachProviderAttempts(aiRequest, failures) {
  * @returns True when the provider indicates a rate-limit failure.
  */
 function isRateLimitFailure(status, payload) {
-    if (isOpenAIQuotaError(payload))
+    // Some credit-exhaustion responses omit a stable code. Do not turn their
+    // explicit billing failure into an unlimited queue capacity deferral.
+    if (isOpenAIQuotaError(payload) || /\b(?:you have )?no credits remaining\b/i.test(openAIProviderError(payload).message))
         return false;
     const code = responseErrorCode(payload);
     return code === 'rate_limit_exceeded' || (status === 429 && code === null);
@@ -1552,9 +1590,9 @@ function rateLimitResetAt(metadata) {
  * @param payload - Raw provider response containing billed-cost extensions.
  * @returns Exact billed cost in USD, or null when it cannot be established.
  */
-function textRequestCostUSD(provider, model, usage, payload) {
+function textRequestCostUSD(provider, model, usage, payload, requestedTier) {
     if (provider === AI_PROVIDER.openai) {
-        return calculateAIRequestCostUSD(model, usage);
+        return calculateAIRequestCostUSD(typeof payload?.model === 'string' ? payload.model : model, { ...usage, serviceTier: effectiveAIServiceTier(payload?.service_tier, requestedTier) });
     }
     return providerReportedCostUSD(provider, payload);
 }
@@ -1769,3 +1807,15 @@ function scopeRecordId(scope) {
     const id = scope?.id;
     return id === null || id === undefined ? null : String(id);
 }
+/** Retains safe provider diagnostics for admission failures in the existing audit trail. */
+function providerAdmissionResponse(error) {
+    return error instanceof AIProviderStoppedError ? { error: { code: error.providerCode ?? error.code, message: error.message } } : null;
+}
+/** Distinguishes actual provider rejection from blocked-before-provider work. */
+function providerAdmissionStarted(error, fallback) {
+    return error instanceof AIProviderStoppedError || error instanceof AIProviderDeferredError ? error.providerStarted : fallback;
+}
+/** Keeps provider support identifiers without duplicating response bodies. */
+function providerAdmissionMetadata(error) {
+    return { ...emptyProviderResponseMetadata(), providerRequestId: error instanceof AIProviderStoppedError ? error.requestId : null };
+}

package/dist/ai/OpenAIProviderError.js

@@ -40,7 +40,7 @@ export function openAIProviderError(value) {
  */
 export function isOpenAIQuotaError(value) {
     const code = openAIProviderError(value).code;
-    return code !== null && OPENAI_QUOTA_ERROR_CODES.has(code);
+    return (code !== null && OPENAI_QUOTA_ERROR_CODES.has(code)) || /\b(?:you have )?no credits remaining\b/i.test(openAIProviderError(value).message);
 }
 /**
  * Narrows an unknown value to a non-array object record.

package/dist/ai/ProviderSseObserver.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Observes SSE framing without rewriting transport bytes or dispatching SDK events.
+ * CR, LF and CRLF terminate lines; blank lines dispatch joined data fields. An
+ * oversized event is discarded until its blank boundary, allowing later errors
+ * to remain observable. Malformed or unfinished input permanently disqualifies
+ * this observer from asserting recovery, even if a later event completes.
+ */
+export declare class ProviderSseObserver {
+    #private;
+    readonly onData: (data: string) => Promise<void>;
+    /** Receives complete joined data fields; the caller owns provider semantics. */
+    constructor(onData: (data: string) => Promise<void>);
+    /** Records malformed JSON/encoding while continuing to observe later events. */
+    invalidate(): void;
+    /** True only when every observed event is valid and ends at a blank boundary. */
+    get complete(): boolean;
+    /** Consumes one decoded fragment; CRLF may be split between calls. */
+    push(text: string): Promise<void>;
+}

package/dist/ai/ProviderSseObserver.js

@@ -0,0 +1,98 @@
+/** Maximum retained decoded characters for one SSE line or joined data event. */
+const MAX_EVENT_CHARACTERS = 1_048_576;
+/**
+ * Observes SSE framing without rewriting transport bytes or dispatching SDK events.
+ * CR, LF and CRLF terminate lines; blank lines dispatch joined data fields. An
+ * oversized event is discarded until its blank boundary, allowing later errors
+ * to remain observable. Malformed or unfinished input permanently disqualifies
+ * this observer from asserting recovery, even if a later event completes.
+ */
+export class ProviderSseObserver {
+    onData;
+    #line = '';
+    #lineNonempty = false;
+    #skipLf = false;
+    #data = [];
+    #dataLength = 0;
+    #eventOpen = false;
+    #discardEvent = false;
+    #valid = true;
+    /** Receives complete joined data fields; the caller owns provider semantics. */
+    constructor(onData) {
+        this.onData = onData;
+    }
+    /** Records malformed JSON/encoding while continuing to observe later events. */
+    invalidate() { this.#valid = false; }
+    /** True only when every observed event is valid and ends at a blank boundary. */
+    get complete() { return this.#valid && !this.#lineNonempty && !this.#eventOpen && !this.#discardEvent; }
+    /** Consumes one decoded fragment; CRLF may be split between calls. */
+    async push(text) {
+        let start = 0;
+        for (let index = 0; index < text.length; index++) {
+            const character = text[index];
+            if (this.#skipLf) {
+                this.#skipLf = false;
+                if (character === '\n') {
+                    start = index + 1;
+                    continue;
+                }
+            }
+            if (character !== '\r' && character !== '\n')
+                continue;
+            this.#append(text.slice(start, index));
+            await this.#finishLine();
+            this.#skipLf = character === '\r';
+            start = index + 1;
+        }
+        this.#append(text.slice(start));
+    }
+    /** Bounds retained line and event storage before adding another fragment. */
+    #append(fragment) {
+        if (!fragment.length)
+            return;
+        this.#lineNonempty = true;
+        if (this.#discardEvent)
+            return;
+        if (this.#line.length + this.#dataLength + fragment.length > MAX_EVENT_CHARACTERS) {
+            this.invalidate();
+            this.#discardEvent = true;
+            this.#line = '';
+            this.#data = [];
+            this.#dataLength = 0;
+        }
+        else
+            this.#line += fragment;
+    }
+    /** Dispatches only complete events, retaining SSE's joined-data semantics. */
+    async #finishLine() {
+        const line = this.#line;
+        const nonempty = this.#lineNonempty;
+        this.#line = '';
+        this.#lineNonempty = false;
+        if (!nonempty) {
+            const data = this.#discardEvent || !this.#data.length ? null : this.#data.join('\n');
+            this.#data = [];
+            this.#dataLength = 0;
+            this.#eventOpen = false;
+            this.#discardEvent = false;
+            if (data !== null)
+                await this.onData(data);
+            return;
+        }
+        if (this.#discardEvent || line.startsWith(':'))
+            return;
+        this.#eventOpen = true;
+        if (line !== 'data' && !line.startsWith('data:'))
+            return;
+        const data = line === 'data' ? '' : line.slice(line[5] === ' ' ? 6 : 5);
+        this.#dataLength += data.length + 1;
+        if (this.#dataLength > MAX_EVENT_CHARACTERS) {
+            this.invalidate();
+            this.#discardEvent = true;
+            this.#data = [];
+            this.#dataLength = 0;
+        }
+        else
+            this.#data.push(data);
+    }
+}

package/dist/ai/aiServiceTier.d.ts

@@ -0,0 +1,5 @@
+import type { AIServiceTier } from './contracts/AIServiceTier.js';
+/** Validates explicit tiers before provider work; other providers retain their own defaults. */
+export declare function assertAIServiceTier(provider: string, tier: AIServiceTier): void;
+/** Resolves billed tier without treating an unconfirmed Flex/Fast request as discounted usage. */
+export declare function effectiveAIServiceTier(reported: unknown, requested: unknown): string | null;

package/dist/ai/aiServiceTier.js

@@ -0,0 +1,14 @@
+import { AIConfigurationError } from './AIErrors.js';
+/** Validates explicit tiers before provider work; other providers retain their own defaults. */
+export function assertAIServiceTier(provider, tier) {
+    if (!['default', 'flex', 'fast', 'priority'].includes(tier))
+        throw new AIConfigurationError('Unsupported AI service tier.');
+    if (provider !== 'openai' && tier !== 'default')
+        throw new AIConfigurationError('Explicit AI service tiers require the OpenAI provider.');
+}
+/** Resolves billed tier without treating an unconfirmed Flex/Fast request as discounted usage. */
+export function effectiveAIServiceTier(reported, requested) {
+    if (typeof reported === 'string' && reported.length > 0)
+        return reported;
+    return requested === undefined || requested === 'default' ? 'default' : null;
+}

package/dist/ai/chunkEmbeddingText.d.ts

@@ -0,0 +1,14 @@
+import type { EmbeddingTextChunk, EmbeddingTextChunkOptions } from './contracts/EmbeddingTextChunk.js';
+/**
+ * Keeps fitting documents whole and splits oversized Markdown at natural boundaries.
+ * Each passage retains source offsets, bounded shared context, its heading hierarchy
+ * and a small overlap. Uses cl100k_base, as used by text-embedding-3-small/large.
+ * No provider requests or generated summaries are involved.
+ *
+ * @param text - Extracted text or Markdown; HTML extraction belongs to the caller.
+ * @param options - Context and token budgets for the complete embedding input.
+ * @returns Ordered passages whose source ranges cover all of the original text.
+ * @example
+ * const chunks = chunkEmbeddingText(page.text, { context: `Title: ${page.title}` });
+ */
+export declare function chunkEmbeddingText(text: string, options?: EmbeddingTextChunkOptions): EmbeddingTextChunk[];