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

package/src/ai/README.md

@@ -39,17 +39,57 @@ returns final output and saved IDs; `stream(message, emit)` emits typed events
 and returns null after a `run.error` event. A conversation can be resumed by
 supplying its ID with matching user, scope and agent identity.
 
+Agents default to a maximum of eight model turns per run. Override the protected
+`maxTurns` property with a number to change that limit, or with `null` to allow
+the agent to finish without a turn ceiling. For example,
+`protected override readonly maxTurns = null;` applies to live runs, queued runs
+and resumed conversations. A model turn can request tools or produce the final
+answer; the agent stops naturally when it returns its final answer.
+
 Register `AgentRunJob` on the queue and call `registerQueuedAgent(name, Class)`
 at boot in both web and worker processes before using `agent.queue(message)`.
 Its constructor context must be serializable. Queued agents require the normal
 queue models and a worker listening on the selected queue.
 
+## Browser computer tools
+
+`computerTool` and the `Computer` type are exported from `@db3.ai/app/ai`.
+Implement the SDK `Computer` contract in an application-owned browser adapter:
+return PNG base64 from `screenshot()`, expose the matching viewport dimensions,
+and delegate mouse, keyboard, scroll and drag actions to that isolated browser.
+Add `computerTool({ name: 'computer', computer: adapter })` to the agent's tools
+with its normal title/description metadata. The existing Agents SDK runs the
+native computer-call/screenshot loop; do not create a second provider loop.
+A compatible model such as `gpt-6-luna` can combine this tool with ordinary
+function tools in the same run.
+
+The application owns allocation, navigation restrictions, deadlines, recordings,
+cleanup and evidence semantics. Provider-requested safety checks need explicit
+handling: returning `false` only omits acknowledgement and does not stop the SDK
+from executing input. Throw from `onSafetyCheck` when unattended execution must
+stop for review. Native tool-action errors may return an empty screenshot through
+the SDK; never treat the final model message alone as evidence of success.
+Screenshot inputs and tool outputs can be retained in local AI request records;
+apply the same access and retention rules as other private prompts. Resuming an
+AI conversation does not restore its browser session. See
+[OpenAI's computer-use guide](https://developers.openai.com/api/docs/guides/tools-computer-use)
+for the provider contract.
+
 ## Images, embeddings and structured output
 
 - `generateImage(input, { store })` returns image bytes and an optional app-owned
   storage reference. See [createHelpImage.ts](./examples/createHelpImage.ts).
 - `generateEmbedding(text, model?, options?)` returns a vector, model and request
   ID. The app owns indexing, source revisions and authorized retrieval.
+- `chunkEmbeddingText(text, { context })` prepares extracted text for the
+  `text-embedding-3-small`/`large` models using their `cl100k_base` tokenizer.
+  Documents that fit stay whole. Oversized documents split at headings,
+  paragraphs, sentences or whitespace, retaining bounded source context,
+  heading ancestry and up to 128 tokens of preceding overlap. Every complete
+  input stays within 8,000 tokens by default, including those prefixes.
+  Source offsets and exact text slices remain available for retrieval.
+  This helper makes no provider calls and does not extract HTML or generate
+  summaries. Context metadata is capped to leave room for source text.
 - `generateStructured({ instructions, input, schemaName, schema })` returns
   locally validated `data`, text and tracking IDs. Schemas use Zod.
 
@@ -57,6 +97,11 @@ Agent instances expose these same methods. Calls made inside an executing tool
 inherit the current conversation and parent request, including calls through
 `app().ai`. Nested calls cannot carry a second independent usage charge.
 
+See [prepareDocumentEmbeddings.ts](./examples/prepareDocumentEmbeddings.ts) for
+preparing and embedding passages. Applications own atomic publication, retries,
+source revision checks and permission-scoped retrieval. Keep the original
+source and its identity so a matching passage can be read in its wider context.
+
 ## Conversations and request records
 
 `AiConversation`, `AiMessage` and `AiRequest` are shipped ActiveRecord classes.
@@ -85,22 +130,35 @@ may contain private information. Apply your app's access and retention policy.
 `saveAiResponse: false` opts direct service calls out of record persistence.
 OpenAI text requests set `store: false`; that does not disable local tracking or
 all provider retention. Never expose provider credentials in client code.
+If a pending embedding request cannot be saved, `generateEmbedding()` throws
+`AIRequestTrackingError` before contacting the provider. Its `stage` identifies
+the pending write and its `code` includes only recognized database lock codes;
+the error deliberately omits the SQL exception because bindings may contain the
+input text. This is separate from a provider rejection or a terminal usage-save
+failure after provider execution.
 
 ## Models and cost estimates
 
-Select `gpt-6-astra` through a per-call `model` override or a named agent model
-in your app's AI config. OpenAI agents already use the Responses API required
-for Astra tool calls. Astra supports reasoning efforts `low` through `xhigh`
-in the framework; do not configure `none` or `minimal`, or custom `temperature`,
-`top_p` or log probabilities. Availability depends on the API project.
+Select `gpt-6-astra`, `gpt-6-sol` or `gpt-6-luna` through a per-call `model`
+override or a named agent model in your app's AI config. Astra is intended for
+the hardest tasks, Sol for demanding agent workflows, and Luna for focused,
+high-volume work. OpenAI agents already use the Responses API required for
+reasoning with tools. Preserve the workload's existing reasoning effort when
+migrating. All three support `low` through `xhigh` in the framework; Sol and
+Luna also support `none`. Do not use `minimal`, or custom `temperature`, `top_p`
+or log probabilities with reasoning enabled. Availability depends on the API
+project. Validate output quality and latency on representative application
+tasks before a production rollout.
 
 The shared `AI_MODEL_PRICING` table was checked against
 [OpenAI's API prices](https://developers.openai.com/api/docs/pricing) on
-2026-09-11. Standard USD prices per million tokens are:
+2026-09-25. Standard USD prices per million tokens are:
 
 | Model | Input | Cache read | Cache write | Output |
 | --- | ---: | ---: | ---: | ---: |
 | `gpt-6-astra` | $10.00 | $1.00 | $12.50 | $50.00 |
+| `gpt-6-sol` | $2.00 | $0.20 | $2.50 | $10.00 |
+| `gpt-6-luna` | $0.10 | $0.01 | $0.125 | $0.50 |
 | `gpt-5.6-sol` | $4.00 | $0.40 | $5.00 | $20.00 |
 | `gpt-5.6-terra` | $2.00 | $0.20 | $2.50 | $12.00 |
 | `gpt-5.6-luna` | $0.20 | $0.02 | $0.25 | $1.20 |
@@ -108,15 +166,31 @@ The shared `AI_MODEL_PRICING` table was checked against
 For these models, a request above 272,000 input tokens costs 2x all input
 rates and 1.5x output rates for the full request. Agent runs calculate this
 per provider request, so several short turns do not trigger the higher rates
-merely because their combined usage exceeds the threshold. Sol's published
+merely because their combined usage exceeds the threshold. GPT-5.6 Sol's published
 promotional rates are available at least through 2026-11-21; recheck the rate
 card when that period ends rather than assuming a future price.
 
-Direct OpenAI text and agent requests select Standard processing. Estimates
-exclude regional processing surcharges and other tiers. OpenRouter and xAI
+Direct OpenAI text and agent requests default to Standard processing. Pass
+`serviceTier: 'flex'` to `generateText`, `generateTextWithResponse` or
+`generateStructured`, or override `protected readonly serviceTier: AIServiceTier = 'flex'`
+on an `Agent` subclass (import the type from `@db3.ai/app/ai`). The property
+defaults to `'default'`; queued runs preserve the selected tier. Streaming and
+tool turns use the same tier. Separate calls inside tools do not inherit it.
+Nondefault tiers require an entirely OpenAI provider chain.
+
+For the six models above, Flex token rates are half Standard and Fast/Priority
+rates are twice Standard. Costs use each response's reported tier and model;
+unconfirmed nonstandard tiers or missing tier rate cards remain unpriced.
+Hosted-tool fees are unchanged. Estimates exclude regional surcharges. OpenRouter and xAI
 use their provider-reported billed costs. Updates affect new estimates and
 new request records; they do not rewrite stored costs or change app model defaults.
 
+The default `gpt-4.1-mini` model and its dated snapshots also have a rate card:
+$0.40 input, $0.10 cached input and $1.60 output per million tokens, verified
+against [the model documentation](https://developers.openai.com/api/docs/models/gpt-4.1-mini)
+on 2026-10-01. This estimate supports small browser agents such as Cloud's
+AI Test Engineer; interrupted requests with missing usage remain unpriced.
+
 Image pricing includes `gpt-image-2.5-flare` and `gpt-image-2`: $5 text input,
 $1.25 cached text input, $8 image input, $2 cached image input and $30 image
 output per million tokens. Dated Flare snapshots resolve to the same rate card.
@@ -138,17 +212,130 @@ OpenAI adapter and do not fail over. Other protocols need a driver implementatio
 Transient network, rate-limit, quota and server failures can advance to another
 provider. Authentication and request validation failures do not. Agent failover
 stops once the SDK emits an event, avoiding automatic replay of tool effects.
-The per-request timeout defaults to 60 seconds; SDK automatic retries are off.
+The per-request timeout defaults to 60 seconds for Standard and 15 minutes for
+Flex; an explicit `ai.timeoutMs` overrides either. Recovery-probe leases cover
+the selected timeout. SDK automatic retries remain off; existing bounded retry,
+deferral and provider-stop rules still apply. This option does not add durable
+checkpoints or guarantee multi-hour recovery. A partial stream or exhausted
+retry window can still fail; test locally before enabling workflows.
 
 The SQL-backed `AIRateLimiter` coordinates provider capacity across workers.
 Agents reserve capacity for each SDK HTTP request and record response headers
 before consuming the stream. Reservations are released before tools execute,
 so a tool can call the same model without waiting on its own parent agent.
 Transport failures also release reservations; later model turns reserve again.
-Quota and capacity deferrals integrate with queue retries. The `allowance` hook
+
+Bucket observation and reservation release are best-effort bookkeeping after
+provider work when they run as autocommit writes. Recognized SQL deadlocks and
+lock timeouts retry the same write up to three times, with 25 ms and 50 ms
+pauses; this never repeats the provider call or changes its saved outcome,
+usage or cost. Three attempts limit the number of writes, not total elapsed
+time: each attempt still uses the database session's lock-wait timeout.
+Release uses a conditional database update and only then marks the lease
+released in memory. Reusing a lease can therefore retry a failed release, while
+an already released or deleted row remains an idempotent success.
+
+A caller-owned transaction gets one attempt. Any bookkeeping or cleanup error
+propagates unchanged to that transaction's owner, and the limiter performs no
+further writes in the failed transaction. InnoDB can roll back the entire
+transaction on a deadlock, including earlier request/usage writes; swallowing
+that error would falsely imply a successful commit. Keep paid provider calls
+outside retryable database transactions. The limiter does not retry the whole
+transaction or replay a provider request.
+
+If an autocommit observation or release still fails, the original provider
+result or error continues. The previous database capacity remains in force,
+and an unreleased reservation stops counting at its existing ten-minute expiry.
+Global cleanup remains best effort outside caller-owned transactions and may
+be retried by application maintenance policy. Structured warnings identify
+`bucket:observe`, `reservation:release` or `reservation:cleanup`, with allowlisted
+SQL lock codes, attempt count, recovery state, whether the caller transaction
+failed, coordination/request IDs and expiry. They omit SQL, bindings, exception
+messages, prompts and responses. Monitor these warnings to investigate recurring
+contention; preserving the provider outcome does not establish its lock holder.
+
+Flare image buckets use a conservative local fallback of five requests per
+minute when response headers omit capacity; this is an admission policy, not
+an assertion about the account's provider tier. Observed headers remain authoritative.
+An image attempt deferred before provider execution is finalized in the audit
+trail rather than left pending. Queue owners retain durable waiting state separately.
+Direct text, image and embedding HTTP rejections throw `AIRequestError` with
+`code`, `status` and `requestId` when supplied; missing fields remain `null`.
+These identifiers exclude the provider payload and inputs. Known quota codes
+(`insufficient_quota`, `billing_hard_limit_reached`) and explicit “no credits
+remaining” responses are terminal direct-call failures, including code-less
+HTTP 429 responses. They do not become queue capacity deferrals. Ordinary
+throttling still raises `AIRateLimitDeferredError`. Existing agent quota retry
+and configured provider failover policies are separate from this direct-call path.
+Capacity deferrals integrate with queue retries. The `allowance` hook
 checks application budgets separately. Override `usageCharge()` and
 `settleUsage()` in an agent when your app needs an idempotent commercial ledger.
 
+## Provider account admission and recovery
+
+`AIProviderAdmission` shares account availability through a dedicated existing
+`ai_rate_limit_buckets` row. Its metadata is keyed by provider, normalized base
+URL and a one-way key digest, across models/endpoints and workers. Separate API keys are separate identities even if the provider funds them from the same billing account; the framework cannot infer that relationship. Raw keys,
+provider messages and prompts are never stored in this account state. Capacity
+limiting can be disabled without disabling account admission.
+
+Explicit `insufficient_quota`, `billing_hard_limit_reached` or “no credits
+remaining” responses immediately stop the account. Ordinary 429 capacity stays
+with the existing limiter. Network/timeouts/408/5xx and explicit overload/server
+errors start one continuous outage episode. Explicit caller cancellation does not
+trip an account outage or prove recovery; an existing recovery lease remains
+bounded. This lets independently authorized cleanup and later runs continue. `ai.providerAdmission` configures
+`initialSeconds` (30), `maxSeconds` (300), `failureWindowSeconds` (900) and
+`recoveryLeaseSeconds` (request timeout plus 30). Values must be positive; the
+recovery lease must exceed the request timeout. These conservative defaults
+limit a fifteen-minute outage to a few real recovery attempts, without assuming
+that credits will return automatically or using paid background probes.
+
+After cooldown only one real waiting request owns recovery. A crash leaves a
+bounded lease; generations and lease tokens prevent stale successes from
+clearing a newer outage or credit stop. The fixed episode deadline also stops
+newly dispatched jobs. Expired episodes and exhausted accounts remain stopped
+across restarts. `AIProviderDeferredError` releases queue reservations without
+spending a try; `AIProviderStoppedError` terminates immediately with a failed-job
+record and normal final-failure hooks, even when more tries were configured.
+After a completed model/tool turn, agents retry only the current model request
+when the SDK has emitted no event for that request. The SDK retains completed
+tools and exact current input, waits for shared admission, and allows at most
+eight retries inside the existing fifteen-minute episode deadline. Each retry
+reacquires capacity and exclusive recovery admission. Queue lease renewal remains
+active while this bounded in-process wait occupies the worker; it is not a durable
+checkpoint and a worker crash cannot promise continuation. Cancellation, exhausted
+quota, stateful requests and any current-request SDK event veto this recovery.
+Failures after such events still stop instead of replaying the whole agent.
+Saved attempts and results remain.
+Terminal errors expose `stopStage`: `quota` for exhausted admission, `deadline`
+for expired outage admission, and `stream-output` for an individual run stopped
+while the account may still be in cooldown. A streamed-output stop does not
+establish that the account deadline elapsed or require resetting the account.
+Observed deferrals carry recognized provider codes, rejection HTTP status and
+bounded support request IDs into the terminal error; blocked siblings retain
+unknown fields. Raw provider messages and payloads are not attached.
+
+After independently repairing availability or credits, an authorized server
+operator can select the configured account and reset its admission state:
+
+```ts
+const attempt = app().ai.resolveProviders()[0];
+if (!attempt) throw new Error('No configured provider account.');
+await app().ai.providerAdmission.reset(attempt);
+```
+
+This executes no HTTP, changes no key/model/billing setting and dispatches or
+replays no job. Failed jobs require a separately authorized retry. The reset
+must run on the deployed app/database with trusted server-side configuration;
+never expose credentials or this operation to an unscoped client.
+
+`generateEmbedding(..., { retainResult: true })` opts into retaining the completed
+vector in the existing request response. Applications may use this for partial
+workflow resume after authorizing scope and matching the exact full input/model.
+Default audits still keep dimensions only. Retention/access remain app policy.
+No new tables or migrations are required by this change.
+
 ## Verification
 
 ### Maintenance map
@@ -180,8 +367,26 @@ Framework maintainers run `npm run test:service --workspace @db3.ai/app -- ai`.
 Tests use real App, SDK, SQL and Storage with synthetic provider responses. The
 integration suite covers tools, history, ownership, queue reconstruction, nested
 request parentage, failover, image storage, embeddings and structured output.
+Limiter contention tests use disposable MariaDB and independent persisted-state
+reads to verify deadlock recovery, retry exhaustion, cleanup and preservation of
+provider success, rejection, deferral and transport failure. A real ambient
+deadlock regression also verifies rollback of an earlier caller write, error
+propagation and the absence of follow-up limiter queries in that transaction.
 The package is also installed and type-checked in an independent consumer.
 
 Installed app developers run their own tests using a disposable database and
 an injected `ai.fetch`. No live key is needed for simulated provider tests.
 See the [AI guides](https://db3.ai/docs/ai) for app-focused examples.
+
+SSE recovery requires an explicit `response.completed` event or compatible
+`[DONE]` marker, a complete event boundary and clean body EOF. The observer joins
+multiline `data` fields and supports LF, CR and CRLF across arbitrary UTF-8 byte
+fragments; it forwards original bytes unchanged. Malformed JSON, uncertain UTF-8,
+oversized events, incomplete EOF and cancellation retain the bounded recovery
+lease rather than asserting success. Retained lines/events are limited to one
+MiB of decoded characters; oversized events are discarded only by the observer
+until their blank boundary, and later valid quota events still stop the account.
+
+### Optional request failure isolation
+
+Text and structured calls may set `transientFailureScope: "request"` for optional work. Timeouts, transport failures and server errors then fail that request without opening the shared account outage circuit. Existing account admission stops and explicit quota exhaustion remain shared. Capacity limits, allowance checks and usage tracking still apply. This does not guarantee provider availability or remove the cost of a request.

package/src/ai/aiServiceTier.ts

@@ -0,0 +1,14 @@
+import type { AIServiceTier } from './contracts/AIServiceTier';
+import { AIConfigurationError } from './AIErrors';
+
+/** Validates explicit tiers before provider work; other providers retain their own defaults. */
+export function assertAIServiceTier(provider: string, tier: AIServiceTier): void {
+	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: unknown, requested: unknown): string | null {
+	if (typeof reported === 'string' && reported.length > 0) return reported;
+	return requested === undefined || requested === 'default' ? 'default' : null;
+}

package/src/ai/chunkEmbeddingText.ts

@@ -0,0 +1,137 @@
+import { Tiktoken } from 'js-tiktoken/lite';
+import cl100kBase from 'js-tiktoken/ranks/cl100k_base';
+import type { EmbeddingTextChunk, EmbeddingTextChunkOptions } from './contracts/EmbeddingTextChunk';
+
+let tokenizer: Tiktoken | undefined;
+
+/** Counts ordinary text, including literal special-token spellings, with cl100k_base. */
+function tokens(text: string): number {
+	tokenizer ??= new Tiktoken(cl100kBase);
+	return tokenizer.encode(text, [], []).length;
+}
+
+/**
+ * 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 function chunkEmbeddingText(text: string, options: EmbeddingTextChunkOptions = {}): EmbeddingTextChunk[] {
+	const maximum = options.maxTokens ?? 8000;
+	const overlap = options.overlapTokens ?? Math.min(128, Math.floor(maximum / 8));
+	if (!Number.isInteger(maximum) || maximum < 64 || maximum > 8191) throw new Error('Embedding chunks require maxTokens between 64 and 8191.');
+	if (!Number.isInteger(overlap) || overlap < 0 || overlap >= maximum / 2) throw new Error('Embedding overlap must be non-negative and smaller than half the input budget.');
+	if (!text.trim()) return [];
+	const contextBudget = Math.min(512, Math.floor(maximum / 8));
+	const context = boundedPrefix(options.context?.trim() ?? '', contextBudget);
+	const headings = markdownHeadings(text);
+	const chunks: EmbeddingTextChunk[] = [];
+	const fullInput = embeddingInput(context, null, text);
+	if (tokens(fullInput) <= maximum) return [{ index: 0, text, heading: null, input: fullInput, start: 0, end: text.length, tokens: tokens(fullInput) }];
+	let start = 0;
+	let contentStart = 0;
+	while (start < text.length) {
+		const activeHeading = headings.filter(heading => heading.start <= contentStart).at(-1)?.title ?? null;
+		const heading = activeHeading ? boundedPrefix(activeHeading, contextBudget) : null;
+		const prefix = embeddingInput(context, heading, '');
+		const available = maximum - tokens(prefix) - 8;
+		let end = start + fittingPrefixLength(text.slice(start), available);
+		if (end < text.length) end = naturalBoundary(text, start, end, headings.map(item => item.start));
+		let input = embeddingInput(context, heading, text.slice(start, end));
+		// BPE merges across the prefix boundary are verified against the final input.
+		while (tokens(input) > maximum && end > start) {
+			end = previousCharacter(text, end);
+			input = embeddingInput(context, heading, text.slice(start, end));
+		}
+		if (end <= start) throw new Error('Embedding context leaves no room for source text.');
+		chunks.push({ index: chunks.length, text: text.slice(start, end), heading, input, start, end, tokens: tokens(input) });
+		if (end === text.length) break;
+		contentStart = end;
+		const previousText = text.slice(start, end);
+		const overlapStart = overlap ? fittingSuffixStart(previousText, overlap) + start : end;
+		// Prefer a whole final paragraph when it fits inside the overlap budget.
+		const paragraphStart = text.lastIndexOf('\n\n', end - 3) + 2;
+		start = paragraphStart >= overlapStart && paragraphStart < end && paragraphStart > start
+			? paragraphStart : overlapStart > start ? overlapStart : end;
+	}
+	return chunks;
+}
+
+/** Builds a deterministic context prefix without rewriting source evidence. */
+function embeddingInput(context: string, heading: string | null, text: string): string {
+	return `${context ? `${context}\n` : ''}${heading ? `section: ${heading}\n` : ''}content:\n${text}`;
+}
+
+/** Finds a token-bounded prefix without cutting a Unicode code point. */
+function fittingPrefixLength(text: string, maximum: number): number {
+	if (tokens(text) <= maximum) return text.length;
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (tokens(text.slice(0, middle)) <= maximum) low = middle;
+		else high = middle - 1;
+	}
+	if (low > 0 && /[\uD800-\uDBFF]/.test(text[low - 1])) low -= 1;
+	return low;
+}
+
+/** Bounds repeated context so even unusually long metadata leaves room for source text. */
+function boundedPrefix(text: string, maximum: number): string {
+	return text.slice(0, fittingPrefixLength(text, maximum)).trim();
+}
+
+/** Locates a bounded overlap suffix on Unicode code-point boundaries. */
+function fittingSuffixStart(text: string, maximum: number): number {
+	let low = 0;
+	let high = text.length;
+	while (low < high) {
+		const middle = Math.floor((low + high) / 2);
+		if (tokens(text.slice(middle)) <= maximum) high = middle;
+		else low = middle + 1;
+	}
+	if (/[\uDC00-\uDFFF]/.test(text[low] ?? '')) low += 1;
+	return low;
+}
+
+/** Moves backwards by one Unicode code point. */
+function previousCharacter(text: string, end: number): number {
+	return end > 1 && /[\uDC00-\uDFFF]/.test(text[end - 1]) ? end - 2 : end - 1;
+}
+
+/** Prefers a heading or paragraph boundary, then sentences and whitespace, without emitting tiny fragments. */
+function naturalBoundary(text: string, start: number, end: number, headings: number[]): number {
+	const minimum = start + Math.floor((end - start) / 2);
+	const heading = headings.filter(position => position >= minimum && position <= end).at(-1);
+	if (heading !== undefined) return heading;
+	const candidate = text.slice(minimum, end);
+	for (const pattern of [/\n\s*\n/g, /[.!?。！？][\s]+/g, /\s+/g]) {
+		const match = [...candidate.matchAll(pattern)].at(-1);
+		if (match) return minimum + match.index! + match[0].length;
+	}
+	return end;
+}
+
+/** Reads Markdown heading ancestry while ignoring headings inside fenced code blocks. */
+function markdownHeadings(text: string): Array<{ start: number; title: string }> {
+	const headings: Array<{ start: number; title: string }> = [];
+	const hierarchy: string[] = [];
+	let fence: string | null = null;
+	for (const line of text.matchAll(/^.*(?:\n|$)/gm)) {
+		const delimiter = line[0].match(/^\s*(`{3,}|~{3,})/)?.[1];
+		if (delimiter) { fence = fence ? (delimiter[0] === fence[0] ? null : fence) : delimiter; continue; }
+		if (fence) continue;
+		const heading = line[0].match(/^(#{1,6})\s+(.+?)(?:\s+#+)?\s*$/);
+		if (!heading) continue;
+		hierarchy.length = heading[1].length;
+		hierarchy[heading[1].length - 1] = heading[2];
+		headings.push({ start: line.index!, title: hierarchy.filter(Boolean).join(' > ') });
+	}
+	return headings;
+}

package/src/ai/contracts/AI.ts

@@ -1,3 +1,4 @@
+import type { AIServiceTier } from './AIServiceTier';
 import type { TextResponsePayload } from '@db3.ai/pure';
 import type { ZodType } from 'zod';
 import type { AiConversation } from '../AiConversation.js';
@@ -140,6 +141,8 @@ export interface AIOptions {
 	fetch?: typeof fetch;
 	/** Rate limiter used before provider requests. Pass false only in isolated tests. */
 	rateLimiter?: AIRateLimiter | false;
+	/** Durable account admission policy; capacity limiter disabling never bypasses it. */
+	providerAdmission?: import('../AIProviderAdmission').AIProviderAdmissionOptions;
 	/** Optional customer allowance hook. Defaults to no-op until billing limits exist. */
 	allowance?: AIAllowanceChecker | false;
 }
@@ -148,6 +151,10 @@ export interface AIOptions {
  * Plain text request sent to the Responses API.
  */
 export interface GenerateTextInput {
+	/** Keep transient failures local to optional work; account quota and existing admission stops still apply. */
+	transientFailureScope?: 'account' | 'request';
+	/** Explicit OpenAI processing tier; defaults to Standard. No automatic tier fallback. */
+	serviceTier?: AIServiceTier;
 	/** Optional per-call model override for the OpenAI provider entry. */
 	model?: string;
 	/** Optional provider failover chain overriding the app default for this call. */
@@ -224,6 +231,10 @@ export interface AIResponseLogOptions extends Record<string, unknown> {
 
 /** Untrusted provider text response, including optional token usage. */
 export interface TextResponsePayloadWithUsage extends TextResponsePayload {
+	/** Actual model reported by the provider for billing. */
+	model?: unknown;
+	/** Actual processing tier reported by OpenAI, not the requested tier. */
+	service_tier?: unknown;
 	/** Provider completion status; omitted by some compatible endpoints. */
 	status?: unknown;
 	usage?: unknown;
@@ -378,3 +389,9 @@ export interface AIModels {
 	request: typeof AiRequest;
 	message: typeof import('../AiMessage').AiMessage;
 }
+
+/** Embedding persistence policy for workflows that must resume partial provider work. */
+export interface GenerateEmbeddingOptions extends RequestLogOptions {
+	/** Persist the completed vector in the existing request response for authorized resume. Defaults to false. */
+	retainResult?: boolean;
+}

package/src/ai/contracts/AIRequestErrorDiagnostics.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider response identifiers retained on a direct AI request failure.
+ *
+ * These fields exclude response bodies, credentials and customer inputs. Missing
+ * fields stay unknown rather than inferring an HTTP status from an error message.
+ */
+export interface AIRequestErrorDiagnostics {
+	/** HTTP response status, when a provider response was received. */
+	status?: number | null;
+	/** Provider request identifier from response headers, for support correlation. */
+	requestId?: string | null;
+}

package/src/ai/contracts/AIServiceTier.ts

@@ -0,0 +1,2 @@
+/** OpenAI processing tier. Default preserves Standard pricing; Flex is opt-in. */
+export type AIServiceTier = 'default' | 'flex' | 'fast' | 'priority';

package/src/ai/contracts/Agent.ts

@@ -3,6 +3,7 @@ import type { QueueJobId } from '@db3.ai/app/queue';
 import type { SerializedValueEnvelope } from '@db3.ai/app/serialization';
 import type { AiConversation } from '../AiConversation.js';
 import type { AiRequest, AiRequestRunCostSummary } from '../AiRequest.js';
+import type { AIServiceTier } from './AIServiceTier';
 import type { AgentCitation } from '@db3.ai/pure';
 
 export type { AgentCitation } from '@db3.ai/pure';
@@ -406,6 +407,8 @@ export interface BaseAgentContext {
  * Serializable payload stored on the queue for deferred agent execution.
  */
 export interface QueuedAgentRunPayload extends Record<string, unknown> {
+	/** Captured processing tier. Legacy payloads retain Standard processing. */
+	serviceTier?: AIServiceTier;
 	/**
 	 * Registered agent name used for worker registration and queue observability.
 	 */

package/src/ai/contracts/EmbeddingTextChunk.ts

@@ -0,0 +1,26 @@
+/** A source-backed passage prepared for the cl100k_base OpenAI embedding models. */
+export interface EmbeddingTextChunk {
+	/** Zero-based position within this source revision. */
+	index: number;
+	/** Exact source slice, including any overlap with the preceding chunk. */
+	text: string;
+	/** Heading hierarchy active at the new source text, excluding preceding overlap. */
+	heading: string | null;
+	/** Complete provider input, with bounded source context and heading prefix. */
+	input: string;
+	/** UTF-16 offsets into the original text; end is exclusive. */
+	start: number;
+	end: number;
+	/** Token count of the complete input, including context and overlap. */
+	tokens: number;
+}
+
+/** Controls deterministic text preparation; callers retain extraction, storage and authorization. */
+export interface EmbeddingTextChunkOptions {
+	/** Source title, description or other trusted context repeated on every passage. */
+	context?: string;
+	/** Complete input ceiling, including prefixes. Defaults to 8,000; cannot exceed 8,191. */
+	maxTokens?: number;
+	/** Maximum preceding text carried into the next passage. Defaults to 128 tokens. */
+	overlapTokens?: number;
+}

package/src/ai/contracts/Pricing.ts

@@ -5,13 +5,15 @@
  * the rates. `outputUSDPer1M` is null for input-only models such as embeddings.
  */
 export interface AIModelPricing {
+	/** Verified tier multipliers for this model only; absent tiers remain unpriced. */
+	serviceTierMultipliers?: Partial<Record<'flex' | 'fast' | 'priority', number>>;
 	inputUSDPer1M: number;
 	cachedInputUSDPer1M: number | null;
 	outputUSDPer1M: number | null;
 	/**
 	 * Multiplier applied to input tokens written into the provider prompt cache.
 	 *
-	 * GPT-5.6 and GPT-6 Astra report cache writes separately and bill them above
+	 * GPT-5.6 and GPT-6 models report cache writes separately and bill them above
 	 * the ordinary uncached input rate. Models without that charge omit it.
 	 */
 	cacheWriteInputMultiplier?: number;
@@ -47,6 +49,8 @@ export interface AIImageModelPricing {
  * Normalized token counts captured from a tracked AI provider response.
  */
 export interface AIRequestCostUsage {
+	/** Actual provider tier. Undefined retains legacy Standard; null means unknown. */
+	serviceTier?: string | null;
 	inputTokens: number | null;
 	outputTokens: number | null;
 	cachedTokens?: number | null;
@@ -58,6 +62,8 @@ export interface AIRequestCostUsage {
  * Per-provider-request usage retained from an aggregate Agents SDK run.
  */
 export interface AIRequestCostUsageEntry extends AIRequestCostUsage {
+	/** Actual provider model, when supplied with this completed response. */
+	model?: string;
 	/** Provider endpoint that reported this usage entry, when available. */
 	endpoint?: string;
 }

package/src/ai/contracts/Providers.ts

@@ -23,6 +23,8 @@ export interface AIProviderConfig {
  * One resolved, fully configured provider attempt in a failover chain.
  */
 export interface AIProviderAttempt {
+	/** Optional work isolates transient transport failures; quota and existing account stops remain shared. */
+	transientFailureScope?: 'account' | 'request';
 	/** Stable provider id persisted on tracking rows and bucket keys. */
 	provider: AIProvider;
 	/** Model sent to this provider. */

package/src/ai/contracts/index.ts

@@ -1,4 +1,5 @@
 export * from './AI';
+export * from './EmbeddingTextChunk';
 export * from './Agent';
 export * from './AiRequestRunCostSummary';
 export * from './Pricing';
@@ -6,3 +7,4 @@ export * from './Providers';
 export * from './RateLimits';
 export * from './ResponsesProviderCall';
 export * from './QuotaRetry';
+export type { AIRequestErrorDiagnostics } from './AIRequestErrorDiagnostics';

package/src/ai/examples/prepareDocumentEmbeddings.ts

@@ -0,0 +1,20 @@
+import { chunkEmbeddingText, type Ai } from '@db3.ai/app/ai';
+
+/**
+ * Prepares source-backed passages before making tracked embedding requests.
+ * The application supplies its configured AI service and publishes the returned
+ * collection only if the original source revision is still current.
+ *
+ * @param ai - Application AI service with its provider and allowance policy.
+ * @param text - Extracted source text or Markdown, without raw HTML.
+ * @param title - Source title repeated as context on every passage.
+ * @returns Ordered passages with their vectors, model and request identifiers.
+ */
+export async function prepareDocumentEmbeddings(ai: Ai, text: string, title: string) {
+	const results = [];
+	for (const chunk of chunkEmbeddingText(text, { context: `title: ${title}` })) {
+		const embedding = await ai.generateEmbedding(chunk.input);
+		results.push({ chunk, ...embedding });
+	}
+	return results;
+}