@db3.ai/app 0.1.0-beta.1

package/src/ai/ProviderCosts.ts

@@ -0,0 +1,156 @@
+import { AI_PROVIDER, type AIProvider } from './contracts/AI.js';
+
+const USD_COST_PRECISION = 100_000_000;
+const XAI_USD_TICKS_PER_DOLLAR = 10_000_000_000;
+
+/** Provider response field used as the authoritative billed-cost source. */
+export type ProviderReportedCostSource = 'openrouter_usage_cost' | 'xai_usage_cost_in_usd_ticks';
+
+/** Authoritative billed cost reported for one provider request. */
+export interface ProviderReportedCost {
+	/** Provider response id used to deduplicate repeated terminal stream events. */
+	responseId: string;
+	/** Billed request cost in USD, rounded to the application's stored precision. */
+	costUSD: number;
+	/** Provider response field from which the cost was derived. */
+	source: ProviderReportedCostSource;
+}
+
+/** Completeness summary for provider-reported costs across one agent attempt. */
+export interface ProviderReportedCostSummary {
+	/** Safely known subtotal across every captured provider response. */
+	knownCostUSD: number;
+	/** Complete attempt cost, or null when any expected response lacks billed cost. */
+	costUSD: number | null;
+	/** Number of unique provider responses with an authoritative billed cost. */
+	reportedRequestCount: number;
+	/** Number of provider requests reported by the Agents SDK. */
+	expectedRequestCount: number;
+	/** Provider fields that supplied the captured costs. */
+	sources: ProviderReportedCostSource[];
+}
+
+/**
+ * Extracts the authoritative billed USD cost from one provider payload.
+ *
+ * OpenRouter returns dollars in `usage.cost`. xAI returns integer USD ticks in
+ * `usage.cost_in_usd_ticks`, where ten billion ticks equal one US dollar.
+ * Other providers intentionally return null so locally estimated prices cannot
+ * be mistaken for the amount actually charged by an intermediary.
+ *
+ * @param provider - Provider that returned the payload.
+ * @param payload - Response object containing the provider usage block.
+ * @returns Provider-reported billed cost in USD, or null when unavailable.
+ */
+export function providerReportedCostUSD(provider: AIProvider | string | null, payload: unknown): number | null {
+	const usage = recordValue(recordValue(payload)?.usage);
+
+	if (!usage) return null;
+
+	if (provider === AI_PROVIDER.openrouter) {
+		return validNonNegativeNumber(usage.cost);
+	}
+
+	if (provider === AI_PROVIDER.xai) {
+		const ticks = validNonNegativeNumber(usage.cost_in_usd_ticks);
+
+		return ticks === null ? null : roundCostUSD(ticks / XAI_USD_TICKS_PER_DOLLAR);
+	}
+
+	return null;
+}
+
+/**
+ * Builds a deduplicatable cost entry for one terminal provider response.
+ *
+ * @param provider - Provider that returned the response.
+ * @param payload - Response object containing provider usage.
+ * @param responseId - Stable provider response identifier.
+ * @returns Captured provider cost, or null when the id or billed cost is absent.
+ */
+export function providerReportedCost(
+	provider: AIProvider | string | null,
+	payload: unknown,
+	responseId: unknown,
+): ProviderReportedCost | null {
+	if (typeof responseId !== 'string' || !responseId.trim()) return null;
+
+	const costUSD = providerReportedCostUSD(provider, payload);
+
+	if (costUSD === null) return null;
+
+	return {
+		responseId,
+		costUSD,
+		source: provider === AI_PROVIDER.xai
+			? 'xai_usage_cost_in_usd_ticks'
+			: 'openrouter_usage_cost',
+	};
+}
+
+/**
+ * Summarizes unique provider costs and fails closed when coverage is incomplete.
+ *
+ * @param costs - Cost entries keyed by provider response id.
+ * @param expectedRequestCount - Provider request count reported by the SDK.
+ * @returns Known subtotal plus an exact total only when every request is covered.
+ */
+export function summarizeProviderReportedCosts(
+	costs: Map<string, ProviderReportedCost>,
+	expectedRequestCount: number,
+): ProviderReportedCostSummary {
+	const entries = [...costs.values()];
+	const knownCostUSD = roundCostUSD(entries.reduce((total, entry) => total + entry.costUSD, 0));
+	const normalizedExpectedCount = Number.isFinite(expectedRequestCount) && expectedRequestCount >= 0
+		? Math.trunc(expectedRequestCount)
+		: 0;
+	const complete = normalizedExpectedCount > 0 && entries.length === normalizedExpectedCount;
+
+	return {
+		knownCostUSD,
+		costUSD: complete ? knownCostUSD : null,
+		reportedRequestCount: entries.length,
+		expectedRequestCount: normalizedExpectedCount,
+		sources: [...new Set(entries.map(entry => entry.source))],
+	};
+}
+
+/**
+ * Converts a provider numeric field into a safe non-negative number.
+ *
+ * @param value - Unknown numeric value from a provider response.
+ * @returns Rounded numeric value, or null when missing, negative, or invalid.
+ */
+function validNonNegativeNumber(value: unknown): number | null {
+	const parsed = typeof value === 'number'
+		? value
+		: typeof value === 'string' && value.trim()
+			? Number(value)
+			: null;
+
+	if (parsed === null || !Number.isFinite(parsed) || parsed < 0) return null;
+
+	return roundCostUSD(parsed);
+}
+
+/**
+ * Narrows an unknown value to a plain record.
+ *
+ * @param value - Unknown provider payload value.
+ * @returns Record value, or null for scalars and arrays.
+ */
+function recordValue(value: unknown): Record<string, unknown> | null {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+
+	return value as Record<string, unknown>;
+}
+
+/**
+ * Rounds provider billed cost to the precision stored on AiRequest.
+ *
+ * @param value - USD cost before persistence rounding.
+ * @returns Cost rounded to eight decimal places.
+ */
+function roundCostUSD(value: number): number {
+	return Math.round(value * USD_COST_PRECISION) / USD_COST_PRECISION;
+}

package/src/ai/README.md

@@ -0,0 +1,187 @@
+# AI
+
+Build AI features inside your db3 application with `app().ai` and `Agent`.
+The service owns provider execution, rate limits and request tracking. Your app
+owns prompts, tools, authorization, storage destinations and commercial policy.
+
+## Start in your app
+
+The generated app configures `new App({ ai: config.ai })` and includes
+`AiConversation`, `AiMessage`, `AiRequest`, `AiRateLimitBucket` and
+`AiRateLimitReservation` in its migration registry. Set `OPENAI_API_KEY` and
+`OPENAI_MODEL` in the server `.env`, apply migrations and restart. Existing apps
+must register these models and generate a committed migration before using AI.
+
+```ts
+import { app } from '@db3.ai/app/server';
+
+const result = await app().ai.generateTextWithResponse({
+	instructions: 'Summarise this note in three short points.',
+	input: note.body,
+	maxOutputTokens: 400,
+}, { user: userId, scope: teamId });
+```
+
+`generateText()` returns a string. `generateTextWithResponse()` also returns the
+saved request and conversation IDs. Direct generation tracks a conversation but
+does not replay its previous messages; use an agent for conversational memory.
+
+## Agents and function calls
+
+Create a class under your app's `server/agents/` directory extending `Agent`.
+Implement `instructions()` and `tools()`. Use the exported `tool` helper with a
+Zod parameter schema to expose an application function. Install `zod` as an app
+dependency when importing it in your tools.
+
+See [HelpAgent.ts](./examples/HelpAgent.ts) for a tested function-calling agent.
+Its context selects a trusted storage path, user and scope. `run(message)`
+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.
+
+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.
+
+## 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.
+- `generateStructured({ instructions, input, schemaName, schema })` returns
+  locally validated `data`, text and tracking IDs. Schemas use Zod.
+
+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.
+
+## Conversations and request records
+
+`AiConversation`, `AiMessage` and `AiRequest` are shipped ActiveRecord classes.
+Extend them in your app and configure `ai.models` with the replacement
+constructors. Replace the corresponding entries in your migration registry and
+generate a migration. See [Conversation.ts](./examples/Conversation.ts).
+Keep table names unless you also override the related model link fields.
+
+`user` and `scope` store optional application identifiers. An app may replace
+these fields with typed model links. `scopeField` adapts an existing logical
+ownership field; calls using that adapter supply that field in logging options.
+
+Use `agentConversationTimeline(messages, toolDefinitions, requests)` to rebuild
+stream-compatible history after authorizing access. The formatter includes
+diagnostic prompt items; filter those from ordinary user views. It supplies
+data for your renderer, not a history endpoint or UI component.
+
+Every provider attempt retains status, input, response, usage and timing.
+`AiRequest.runCostSummary(id)` aggregates recursively linked provider work
+without counting the root aggregate twice. Unknown usage and costs remain
+unknown. When `unpricedRequestCount` is nonzero, `totalCostUSD` is only the known
+subtotal. Price estimates are not invoices or a customer credit ledger.
+
+Request persistence is enabled by default. Prompts, responses and tool results
+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.
+
+## 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.
+
+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:
+
+| Model | Input | Cache read | Cache write | Output |
+| --- | ---: | ---: | ---: | ---: |
+| `gpt-6-astra` | $10.00 | $1.00 | $12.50 | $50.00 |
+| `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 |
+
+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
+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
+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.
+
+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.
+The models can consume different token counts at the same size and quality;
+image costs use actual reported usage, not fixed per-image estimates. Apps
+select Flare through `ImageGeneration` or a per-call `model` override.
+
+## Providers and failover
+
+Configure `ai.provider` with one provider, an ordered list or an ordered record
+of provider/model pairs. Registered providers are OpenAI, OpenRouter, Groq, xAI
+and DeepSeek. Provider keys, base URLs and model defaults use their corresponding
+server environment variables. Calls and agent subclasses can select a chain.
+
+Text and structured output require the Responses API. Agents also support the
+registered Chat Completions providers. Images and embeddings currently use the
+OpenAI adapter and do not fail over. Other protocols need a driver implementation.
+
+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 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
+checks application budgets separately. Override `usageCharge()` and
+`settleUsage()` in an agent when your app needs an idempotent commercial ledger.
+
+## Verification
+
+### Maintenance map
+
+- `Ai.ts`: direct provider requests, allowance hooks and tracking lifecycle.
+- `Agent.ts`: conversational runs, tool events, provider attempts, queue setup
+  and application extension hooks.
+- `contracts/`: shared service, agent, event, provider and limiter contracts.
+- `AgentHistory.ts`: transport-independent timeline reconstruction.
+- `toolHelpers.ts`: typed context access, progress, errors and model attachments.
+- `AgentRunJob.ts` and `registry.ts`: validation and durable reconstruction;
+  applications register their own classes and model identities.
+- `AiConversation.ts`, `AiMessage.ts`, `AiRequest.ts`: extensible record models.
+- `AIRateLimiter.ts`, `AIProviders.ts`, `AIFailover.ts` and `OpenAIQuotaRetry.ts`:
+  provider capacity, selection and retry behavior.
+
+Keep application-specific context, authorization, billing, prompts and storage
+placement in application subclasses or adapters. Shared tool helpers preserve
+the application's context type; applications need not copy their implementations.
+
+The pinned Agents SDK currently needs `sdkNodeCompatibility.d.ts` for strict
+Node declaration checking. It describes the SDK emitter through its own event
+contract and does not replace runtime code or augment Node globally. Staging
+ships that declaration and rewrites its reference to the installed location.
+Remove the shim when the unmodified SDK passes the packed consumer with
+`skipLibCheck: false`; do not disable the check to upgrade the dependency.
+
+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.
+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.

package/src/ai/ResponsesProviderCall.ts

@@ -0,0 +1,34 @@
+import type { ResponsesProviderCallInput, ResponsesProviderCallResult } from './contracts/ResponsesProviderCall';
+export type { ResponsesProviderCallInput, ResponsesProviderCallResult } from './contracts/ResponsesProviderCall';
+import { providerResponseMetadata } from './AIRateLimiter.js';
+import type { TextResponsePayloadWithUsage } from './contracts/AI.js';
+
+/**
+ * Sends one Responses API request to an OpenAI-compatible provider.
+ *
+ * This is pure transport: it performs the HTTP call and parses the payload and
+ * headers. Tracking, rate limiting, failover policy, and error shaping stay in
+ * the AI service so every attempt in a failover chain shares one lifecycle.
+ *
+ * @param input - Provider connection, request payload, and fetch implementation.
+ * @returns Raw provider response for the caller to classify.
+ */
+export async function sendResponsesRequest(input: ResponsesProviderCallInput): Promise<ResponsesProviderCallResult> {
+	const response = await input.fetcher(`${input.baseUrl}/responses`, {
+		method: 'POST',
+		headers: {
+			authorization: `Bearer ${input.apiKey}`,
+			'content-type': 'application/json',
+		},
+		body: JSON.stringify(input.request),
+	});
+	const metadata = providerResponseMetadata(response.headers);
+	const payload = await response.json().catch(() => null) as TextResponsePayloadWithUsage | null;
+
+	return {
+		ok: response.ok,
+		status: response.status,
+		payload,
+		metadata,
+	};
+}

package/src/ai/agentCitations.ts

@@ -0,0 +1,186 @@
+import { agentCitationOccurrenceKey, normalizedAgentCitations, type AgentCitation } from '@db3.ai/pure';
+
+/**
+ * Extracts a normalized URL citation from a Responses streaming annotation.
+ *
+ * @param record - Raw `response.output_text.annotation.added` event.
+ * @returns Valid URL citation, or null for unsupported annotations.
+ */
+export function agentCitationFromStreamRecord(record: Record<string, unknown>): AgentCitation | null {
+	if (record.type !== 'response.output_text.annotation.added') return null;
+
+	const annotation = recordValue(record.annotation);
+	const itemId = stringValue(record.item_id) || stringValue(record.itemId);
+	const annotationIndex = integerValue(record.annotation_index) ?? integerValue(record.annotationIndex);
+	const contentIndex = integerValue(record.content_index) ?? integerValue(record.contentIndex) ?? 0;
+
+	return providerUrlCitation(annotation, {
+		id: citationId(itemId, contentIndex, annotationIndex),
+		offset: contentIndex === 0 ? 0 : null,
+	});
+}
+
+/**
+ * Extracts URL citations from the final Agents SDK model response.
+ *
+ * A null result means the provider did not expose an authoritative annotation
+ * collection, so callers may fall back to citations observed in stream events.
+ * An empty array is authoritative and means the final response had no citations.
+ *
+ * @param rawResponses - Agents SDK model responses generated by the run.
+ * @returns Final normalized citations, or null when annotations are unavailable.
+ */
+export function agentCitationsFromFinalModelResponse(rawResponses: unknown): AgentCitation[] | null {
+	if (!Array.isArray(rawResponses) || rawResponses.length === 0) return null;
+
+	const response = recordValue(rawResponses.at(-1));
+	const output = Array.isArray(response?.output) ? response.output : null;
+
+	if (!output || output.length === 0) return null;
+
+	const message = recordValue(output.at(-1));
+
+	if (!message) return null;
+
+	const content = message.type === 'message' && Array.isArray(message.content)
+		? message.content
+		: null;
+
+	if (!content) return null;
+
+	const messageId = stringValue(message.id);
+	const citations: AgentCitation[] = [];
+	let textOffset = 0;
+	let hasAnnotationCollection = false;
+
+	for (let contentIndex = 0; contentIndex < content.length; contentIndex += 1) {
+		const part = recordValue(content[contentIndex]);
+
+		if (part?.type !== 'output_text') continue;
+
+		const providerData = recordValue(part.providerData);
+		const annotations = Array.isArray(providerData?.annotations)
+			? providerData.annotations
+			: Array.isArray(part.annotations)
+				? part.annotations
+				: null;
+
+		if (annotations) {
+			hasAnnotationCollection = true;
+
+			for (let annotationIndex = 0; annotationIndex < annotations.length; annotationIndex += 1) {
+				const citation = providerUrlCitation(recordValue(annotations[annotationIndex]), {
+					id: citationId(messageId, contentIndex, annotationIndex),
+					offset: textOffset,
+				});
+
+				if (citation) citations.push(citation);
+			}
+		}
+
+		textOffset += stringValue(part.text)?.length ?? 0;
+	}
+
+	return hasAnnotationCollection ? normalizedAgentCitations(citations) : null;
+}
+
+/**
+ * Adds a citation to an in-memory collection when its occurrence is new.
+ *
+ * @param citations - Mutable citations collected for the current attempt.
+ * @param citation - Citation occurrence to remember.
+ * @returns True when the citation was added.
+ */
+export function rememberAgentCitation(citations: AgentCitation[], citation: AgentCitation): boolean {
+	const key = agentCitationOccurrenceKey(citation);
+
+	if (citations.some(existing => agentCitationOccurrenceKey(existing) === key)) return false;
+
+	citations.push(citation);
+
+	return true;
+}
+
+/**
+ * Context needed to normalize a provider URL annotation.
+ */
+interface ProviderCitationContext {
+	/** Stable id assigned to this annotation occurrence. */
+	id: string;
+
+	/** Character offset of the containing output-text part. */
+	offset: number | null;
+}
+
+/**
+ * Converts a provider URL annotation into application's public citation contract.
+ *
+ * @param annotation - Raw provider annotation object.
+ * @param context - Stable id and complete-message character offset.
+ * @returns Valid normalized citation, or null when required data is absent.
+ */
+function providerUrlCitation(annotation: Record<string, unknown> | null, context: ProviderCitationContext): AgentCitation | null {
+	if (!annotation || annotation.type !== 'url_citation' || context.offset === null) return null;
+
+	const startIndex = integerValue(annotation.start_index) ?? integerValue(annotation.startIndex);
+	const endIndex = integerValue(annotation.end_index) ?? integerValue(annotation.endIndex);
+	const title = stringValue(annotation.title)?.trim();
+	const url = stringValue(annotation.url)?.trim();
+
+	if (startIndex === null || endIndex === null || !title || !url) return null;
+
+	const citations = normalizedAgentCitations([{
+		id: context.id,
+		type: 'url',
+		title,
+		url,
+		startIndex: context.offset + startIndex,
+		endIndex: context.offset + endIndex,
+	}]);
+
+	return citations[0] ?? null;
+}
+
+/**
+ * Builds a stable id for one provider citation occurrence.
+ *
+ * @param itemId - Provider output message id when available.
+ * @param contentIndex - Output-text part index within the message.
+ * @param annotationIndex - Annotation index within the output-text part.
+ * @returns Stable citation id for streaming and restored UI state.
+ */
+function citationId(itemId: string | null, contentIndex: number, annotationIndex: number | null): string {
+	return `${itemId || 'output'}:${contentIndex}:${annotationIndex ?? 0}`;
+}
+
+/**
+ * Narrows an unknown JSON value to a non-array record.
+ *
+ * @param value - Unknown provider value.
+ * @returns Object record, or null for primitives and arrays.
+ */
+function recordValue(value: unknown): Record<string, unknown> | null {
+	return value && typeof value === 'object' && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+/**
+ * Reads a non-empty string from an unknown provider value.
+ *
+ * @param value - Unknown provider value.
+ * @returns String value, or null when absent.
+ */
+function stringValue(value: unknown): string | null {
+	return typeof value === 'string' && value ? value : null;
+}
+
+/**
+ * Reads a non-negative integer from an unknown provider value.
+ *
+ * @param value - Unknown provider index value.
+ * @returns Non-negative integer, or null when invalid.
+ */
+function integerValue(value: unknown): number | null {
+	return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null;
+}