@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/ai/runtime/ai.service.js

@@ -0,0 +1,1848 @@
+"use strict";
+// =============================================================================
+// AiService — THE runtime facade (issue #432, epic #419)
+// =============================================================================
+//
+// The one injectable a fork uses to add AI to a feature:
+//
+//   constructor(private readonly ai: AiService) {}
+//   ...
+//   const res = await this.ai.forUser(userId).respond({ input: 'Summarise …' });
+//
+// No SDK, no key, no policy check of the caller's own. Every call runs the same
+// gate pipeline, in this order (docs/specs/ai-platform.md §2.18, §2.19, §2.23):
+//
+//   1. kill switch                     AI_DISABLED
+//   2. provider enabled + registered   AI_PROVIDER_DISABLED
+//      previousResponseId on a provider AI_CAPABILITY_UNSUPPORTED
+//      that cannot chain (#446)
+//   3. model enabled / capabilities /  AI_MODEL_NOT_ENABLED,
+//      key exists / key reaches model  AI_CAPABILITY_UNSUPPORTED,
+//                                      AI_KEY_REQUIRED, AI_MODEL_NOT_REACHABLE
+//      (UsableModelsService.assertUsable, with the capabilities the request's
+//      SHAPE needs — structured output, tools, reasoning, images, streaming)
+//   4. reasoning effort offered by the model
+//   5. clamp maxOutputTokens to the deployment cap, the model's
+//      `ai.limits.perModel` cap and the model's own limit (smallest wins)
+//   6. resolve the key (AiKeyResolver — the byok invariant lives there)
+//   6b. rate limits (#450, AiLimitsService) — now that whose key pays is
+//      known; AI_RATE_LIMITED (429) with `retryAfterMs` and `details.limit`
+//   7. call the adapter with { apiKey, baseUrl, signal, requestId }
+//   8. record ONE `ai_usage_events` row per round-trip (success, failure or
+//      cancellation) with whose key paid (AiUsageRecorder)
+//   9. trace it as an `ai.request` span (provider, model, operation, key
+//      source, status, token counts — never prompt text, never the key)
+//
+// NON-RESPONSES OPERATIONS (Phase 2, epic #420) run the SAME pipeline with
+// the steps that apply to them: `embed` (#440) is kill switch -> provider ->
+// model/capability/key/reach (with `embeddings` as the one capability
+// needed) -> key -> adapter -> usage row (`operation: 'embeddings'`) ->
+// span. Each operation has a `prepare…` of its own and shares `context()`
+// and `track()`; a later port (images, audio) is one more `prepare…`, one
+// more `TRACKED_OPERATIONS` entry and one more client method — never a
+// second pipeline.
+//
+// IMAGES (#437) are that shape plus a queue hop: `generateImage`/`editImage`
+// run `prepareImage` (kill switch -> shape -> provider -> model with
+// `image_generation`/`image_edit` -> an edit's input storage objects,
+// ownership included) and queue an `ai.image.generate` run; the job calls
+// `executeImageRun`, which runs `prepareImage` AGAIN, reads the inputs'
+// bytes, resolves the key, calls the port and records one usage row
+// (`operation: 'images'`, `units: { images: n }`).
+//
+// STORAGE-OBJECT INPUTS (#441). An `image`/`file` part naming a
+// `storageObjectId` is resolved INSIDE `prepare`, after step 4: the object
+// must be the caller's own (ownership only, like `ObjectsService`) and `ready`;
+// its MIME type decides its modality (an image type needs `vision_input`,
+// anything else `file_input`, both in the model's capabilities AND
+// `inputModalities`) and its size cap (`AI_STORAGE_INPUT_*_MAX_BYTES`); and
+// the provider must declare a `fileInputStrategy`. Only then — after the
+// gates, before the key — does `materializeStorageInputs` prepare what that
+// strategy needs (a 10-minute presigned GET URL, or a capped byte stream),
+// handed to the adapter in `ctx.storageInputs`. The REQUEST is never
+// rewritten: it keeps the id, so the prompt log, `ai_runs.request` and every
+// error carry no URL. `startRun` runs the checks now and the job resolves
+// again when it executes, with a fresh URL.
+//
+// HOSTED TOOLS (#442) add one gate between steps 2 and 3: every hosted
+// tool's shape is validated, its type must be switched on by an
+// administrator (`ai.hostedTools.<type>`) and an MCP server's host must pass
+// `mcpAllowedHosts` — else AI_TOOL_DISABLED (403); the model's
+// `hosted_tools` capability is then step 3's (AI_CAPABILITY_UNSUPPORTED).
+// Every result leaves through an `AiHostedOutputSettler`
+// (`ai-hosted-outputs.ts`): generated image bytes are stored by
+// `persistHostedImage` as the user's own storage objects (`AiOutputWriter`)
+// and never passed onward, and MCP header values are scrubbed from
+// everything returned. A hosted image counts as `units: { images: n }`.
+//
+// ⚠ MCP HEADERS are secret like the key: never logged (the prompt preview
+// shows instructions and input only), never on a span (`ai.hosted_tools`
+// names tool TYPES), never in a usage row, never stored with a background
+// run (`toStoredRunRequest` refuses them).
+//
+// TRANSCRIPTION (#438) is the same shape: `transcribe` runs
+// `prepareTranscription` (kill switch -> shape -> target, defaulting to the
+// first usable `audio_transcription` model -> provider -> model -> the
+// recording's storage object: ownership, readiness, `audio/*`/`video/mp4|webm`
+// and the port's `transcriptionMaxBytes`, all from the row) and queues an
+// `ai.audio.transcribe` run; `executeTranscriptionRun` gates again, STREAMS
+// the recording to the adapter through a size-capped reader (or, when the
+// row does not know the size yet, reads it with the cap enforced before the
+// call) and records one usage row (`operation: 'audio.transcribe'`,
+// `units: { audioSeconds }` when the provider reports a duration).
+//
+// SPEECH (#439): `speak` runs `prepareSpeech` (kill switch -> shape, input
+// at most 4096 characters -> target, defaulting to the first usable
+// `audio_speech` model -> provider -> model -> the voice, checked against
+// the model's catalog `voices` or the port's own list) and queues an
+// `ai.audio.speech` run; `executeSpeechRun` gates again, calls the port and
+// records one usage row (`operation: 'audio.speech'`, `units: { characters }`).
+// The handler stores the audio as the user's storage object.
+//
+// REALTIME (#449, docs/specs/ai-platform.md §2.15): `createRealtimeSession`
+// runs `prepareRealtime` (kill switch -> `ai.defaults.allowRealtime`
+// (AI_REALTIME_DISABLED) -> shape -> target, defaulting to the first usable
+// `realtime` model -> provider -> model with `realtime` -> the voice) and
+// then, synchronously, the shared key + rate-limit step and ONE adapter
+// call that mints an ephemeral client secret; one usage row
+// (`operation: 'realtime'`, `units: { sessions: 1 }`, no tokens — the media
+// never passes through here). No job: the long-running part is the call
+// between the browser and the provider.
+//
+// ⚠ THE EPHEMERAL SECRET is the one credential this facade returns. It
+// leaves through the result and nowhere else — no log line, no span, no
+// usage row — exactly like the key it was minted with, which never leaves
+// at all.
+//
+// ⚠ THE KEY. `apiKey` exists in this file only between step 6 and the
+// adapter call. It is never logged, never put on a span, never persisted and
+// never part of an error. A presigned input URL gets the same treatment.
+// =============================================================================
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var AiService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiService = exports.AI_PROMPT_LOG_MAX_CHARS = exports.AI_REQUEST_SPAN = void 0;
+exports.requiredCapabilities = requiredCapabilities;
+exports.clampOutputTokens = clampOutputTokens;
+exports.assertProviderOptionsShape = assertProviderOptionsShape;
+exports.containsKey = containsKey;
+exports.scrubKey = scrubKey;
+exports.toAiError = toAiError;
+exports.assertFeatureFits = assertFeatureFits;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const api_1 = require("@opentelemetry/api");
+const index_1 = require("../../otel-core/index");
+const index_2 = require("../../core/index");
+const index_3 = require("../../identity/index");
+const ai_config_service_1 = require("../config/ai-config.service");
+const ai_error_1 = require("../core/ai-error");
+const provider_adapter_interface_1 = require("../core/provider-adapter.interface");
+const operation_registry_1 = require("../core/operation-registry");
+const file_inputs_types_1 = require("../core/types/file-inputs.types");
+const hosted_tools_1 = require("../core/hosted-tools");
+const provider_registry_1 = require("../core/provider-registry");
+const structured_output_1 = require("../core/structured-output");
+const media_types_1 = require("../core/types/media.types");
+const ai_key_resolver_service_1 = require("../keys/ai-key-resolver.service");
+const usable_models_service_1 = require("../keys/usable-models.service");
+const ai_output_writer_1 = require("../storage/ai-output-writer");
+const ai_feature_registry_1 = require("../features/ai-feature.registry");
+const target_resolver_1 = require("./target-resolver");
+const ai_options_1 = require("../ai.options");
+const ai_storage_errors_1 = require("../storage/ai-storage-errors");
+const ai_storage_input_resolver_1 = require("../storage/ai-storage-input.resolver");
+const ai_audio_run_request_1 = require("./ai-audio-run-request");
+const ai_image_run_request_1 = require("./ai-image-run-request");
+const ai_provider_filename_1 = require("./ai-provider-filename");
+const ai_run_request_1 = require("./ai-run-request");
+const ai_hosted_outputs_1 = require("./ai-hosted-outputs");
+const ai_runs_service_1 = require("./ai-runs.service");
+const ai_transcription_extras_1 = require("./ai-transcription-extras");
+const ai_limits_service_1 = require("./ai-limits.service");
+const ai_tool_loop_1 = require("./ai-tool-loop");
+const ai_1 = require("@marinoscar/platform-contract/ai");
+const ai_usage_recorder_1 = require("./ai-usage.recorder");
+/** The facade's span — one per provider round-trip. The adapter's own `ai.provider.call` nests inside it. */
+exports.AI_REQUEST_SPAN = 'ai.request';
+const tracer = api_1.trace.getTracer((0, index_1.resolveServiceName)());
+/** Prompt text is logged (only when `ai.logPromptContent`) truncated to this many characters. */
+exports.AI_PROMPT_LOG_MAX_CHARS = 2048;
+/** The facade operations that are traced and recorded, and the usage `operation` each is billed as. */
+const TRACKED_OPERATIONS = {
+    'responses.create': 'responses',
+    'responses.stream': 'responses',
+    'embeddings.create': 'embeddings',
+    'images.generate': 'images',
+    'images.edit': 'images',
+    'audio.transcribe': 'audio.transcribe',
+    'audio.speech': 'audio.speech',
+    'realtime.session': 'realtime',
+};
+/** The usage `operation` a tracked call is billed as: the table's entry, or a custom operation's own id. */
+function usageOperationOf(call) {
+    return call.startsWith('operation:') ? call.slice('operation:'.length) : TRACKED_OPERATIONS[call];
+}
+/** A run's recorded feature as a scope field: attribution only, and only a well-formed id. */
+function attributedFeatureOf(opts) {
+    return typeof opts.feature === 'string' && ai_1.AI_FEATURE_ID_PATTERN.test(opts.feature)
+        ? { attributedFeature: opts.feature }
+        : {};
+}
+/** The feature a usage row and span carry: the gated one, else a run's recorded one. */
+function featureOfScope(scope) {
+    return scope.feature ?? scope.attributedFeature;
+}
+/**
+ * The AI runtime facade: the one way a feature calls a model. `forUser(userId)`
+ * returns a client whose every call runs the gate pipeline (kill switch,
+ * provider, model, capability, limits, key resolution) and records usage; the
+ * key is resolved per call and never leaves the server.
+ *
+ * @example
+ * ```ts
+ * const answer = await this.ai.forUser(userId, { orgId, feature: 'example_summary' }).respond({ input });
+ * ```
+ *
+ * @stability experimental
+ */
+let AiService = AiService_1 = class AiService {
+    aiConfig;
+    registry;
+    usableModels;
+    keyResolver;
+    prisma;
+    usage;
+    runs;
+    inputs;
+    outputs;
+    limits;
+    logger = new common_1.Logger(AiService_1.name);
+    constructor(aiConfig, registry, usableModels, keyResolver, prisma, usage, runs, inputs, outputs, limits, targetResolver, options) {
+        this.aiConfig = aiConfig;
+        this.registry = registry;
+        this.usableModels = usableModels;
+        this.keyResolver = keyResolver;
+        this.prisma = prisma;
+        this.usage = usage;
+        this.runs = runs;
+        this.inputs = inputs;
+        this.outputs = outputs;
+        this.limits = limits;
+        this.targets = targetResolver ?? new target_resolver_1.DefaultAiTargetResolver(prisma, registry, options ?? ai_options_1.DEFAULT_AI_OPTIONS);
+    }
+    targets;
+    /**
+     * The AI client for `userId`. Cheap — create one per request.
+     *
+     * `jobId` is internal plumbing for the background-run handler, so its
+     * usage rows name the job they were incurred under.
+     */
+    forUser(userId, scope = {}) {
+        const bound = {
+            userId,
+            orgId: scope.orgId,
+            jobId: scope.jobId,
+            runId: scope.runId,
+            ...(scope.feature !== undefined ? { feature: scope.feature } : {}),
+            ...attributedFeatureOf({ feature: scope.attributedFeature }),
+        };
+        return {
+            userId,
+            respond: (req, opts) => this.respond(bound, req, opts),
+            stream: (req, opts) => this.lazyStream(bound, req, opts),
+            openStream: (req, opts) => this.openStream(bound, req, opts),
+            respondStructured: (req, opts) => this.respondStructured(bound, req, opts),
+            runTools: (req, opts = {}) => (0, ai_tool_loop_1.runToolLoop)((next, callOpts) => this.respond(bound, next, callOpts), req, {
+                userId,
+                signal: opts.signal,
+                supportsPreviousResponseId: (provider) => this.registry.supportsPreviousResponseId(provider),
+            }),
+            startRun: (req) => this.startRun(bound, req),
+            embed: (req, opts) => this.embed(bound, req, opts),
+            generateImage: (req) => this.startImageRun(bound, 'images.generate', req),
+            editImage: (req) => this.startImageRun(bound, 'images.edit', req),
+            transcribe: (req) => this.startTranscriptionRun(bound, req),
+            speak: (req) => this.startSpeechRun(bound, req),
+            createRealtimeSession: (req, opts) => this.createRealtimeSession(bound, req, opts),
+            run: (operationId, input, opts) => this.runOperation(bound, operationId, input, opts),
+        };
+    }
+    /**
+     * The organization this call runs in: the scope's own, else (single tenancy)
+     * the default organization, else a `MissingOrgScopeError` (multi tenancy).
+     * Memoised on the scope, so one call resolves it once.
+     */
+    async orgOf(scope) {
+        scope.orgId ??= await (0, index_3.resolveOrgId)(this.prisma, scope.orgId, scope.jobId ? `AI call under job ${scope.jobId}` : `AI call for user ${scope.userId}`);
+        return scope.orgId;
+    }
+    // ---- respond ----------------------------------------------------------------
+    async respond(scope, req, opts = {}) {
+        const call = await this.prepare(scope.userId, req, { streaming: false, orgId: await this.orgOf(scope), feature: scope.feature });
+        return this.invoke(scope, call, opts);
+    }
+    async respondStructured(scope, req, opts = {}) {
+        const { schema, schemaName, strict, ...rest } = req;
+        const response = await this.respond(scope, { ...rest, structuredOutput: { name: schemaName ?? 'response', schema, strict: strict ?? true } }, opts);
+        return response;
+    }
+    async startRun(scope, req) {
+        const orgId = await this.orgOf(scope);
+        await this.aiConfig.assertEnabled(orgId);
+        if (!(await this.aiConfig.resolveForOrg(orgId)).defaults.allowBackgroundRuns) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'Background AI runs are disabled in this deployment.');
+        }
+        const call = await this.prepare(scope.userId, req, { streaming: false, orgId, feature: scope.feature });
+        return this.runs.create({
+            userId: scope.userId,
+            orgId,
+            provider: call.provider,
+            modelId: call.request.model,
+            // Named fields only, and never a key — see `ai-run-request.ts`.
+            request: (0, ai_run_request_1.toStoredRunRequest)(call.provider, call.request),
+            ...(scope.feature ? { feature: scope.feature } : {}),
+        });
+    }
+    /** Steps 6-7 for an already-gated call. */
+    async invoke(scope, call, opts) {
+        const storageInputs = await this.materializeStorageInputs(call);
+        const { ctx, keySource } = await this.context(scope, call, opts, () => responsePrompt(call.request), storageInputs);
+        const tracker = this.track(scope, call, keySource, 'responses.create');
+        let response;
+        try {
+            response = await call.port.create(call.request, ctx);
+        }
+        catch (err) {
+            const error = toAiError(err, opts.signal);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        // Adapters validate structured output themselves; a response they left
+        // unparsed (a truncated answer, say) is validated here, so a caller that
+        // asked for a schema never receives an unvalidated result.
+        const spec = call.request.structuredOutput;
+        if (spec && response.parsed === undefined) {
+            try {
+                response = { ...response, parsed: (0, structured_output_1.parseStructured)(spec.schema, response.outputText) };
+            }
+            catch (err) {
+                const error = toAiError(err, opts.signal);
+                // The round-trip happened (and was billed): keep its tokens.
+                await tracker.finish({ status: 'failed', result: response, errorCode: error.code });
+                throw error;
+            }
+        }
+        await tracker.finish({ status: 'succeeded', result: response, units: hostedImageUnits(response) });
+        return this.hostedOutputs(scope, call).response(response);
+    }
+    // ---- hosted-tool outputs ---------------------------------------------------------
+    /** The settler every result of `call` leaves through (see `ai-hosted-outputs.ts`). */
+    hostedOutputs(scope, call) {
+        return new ai_hosted_outputs_1.AiHostedOutputSettler({
+            userId: scope.userId,
+            ...(scope.orgId ? { orgId: scope.orgId } : {}),
+            ...(scope.jobId ? { jobId: scope.jobId } : {}),
+            ...(scope.runId ? { runId: scope.runId } : {}),
+        }, (0, hosted_tools_1.mcpHeaderValues)(call.request.tools), (owner, item, responseId) => this.persistHostedImage(owner, item, responseId));
+    }
+    /**
+     * Persists one hosted `image_generation` result (#442) through the AI
+     * output writer (#437): the bytes become a `ready` storage object OWNED BY
+     * THE USER under `ai-outputs/<userId>/<runId or responseId>/`, and the
+     * published result carries its `storageObjectId` — never the bytes. Called
+     * once per image, even when a stream shows the item twice.
+     *
+     * STORAGE UNAVAILABLE IS NOT A FAILED RESPONSE. The provider call already
+     * happened (and was billed), and the rest of the answer — text, citations,
+     * other tool calls — is intact, so the image is published with
+     * `storageObjectId: null` and `storageError: 'AI_STORAGE_UNAVAILABLE'`
+     * instead, and a warning is logged (never the bytes). A dedicated image
+     * run (`generateImage`) refuses up front instead; a hosted tool cannot,
+     * because whether the model draws anything is only known afterwards.
+     *
+     * @internal
+     */
+    async persistHostedImage(owner, item, responseId) {
+        const image = item.result?.image;
+        const published = await (0, ai_hosted_outputs_1.discardHostedImage)(owner, item);
+        if (!image)
+            return published;
+        const folder = owner.runId ?? outputFolder(responseId);
+        try {
+            await this.outputs.assertWritable();
+            const [stored] = await this.outputs.write({
+                userId: owner.userId,
+                orgId: owner.orgId ?? (await this.orgOf({ userId: owner.userId, jobId: owner.jobId })),
+                runId: folder,
+                files: [{ data: image.data, mimeType: image.mimeType }],
+                namePrefix: 'ai-image',
+                metadata: { tool: 'image_generation', ...(responseId ? { responseId } : {}) },
+            });
+            return { ...published, storageObjectId: stored.storageObjectId, mimeType: stored.mimeType };
+        }
+        catch (err) {
+            const reason = (0, ai_storage_errors_1.aiErrorFromStorage)(err)?.code ?? 'AI_STORAGE_UNAVAILABLE';
+            this.logger.warn(`Hosted image ${item.id ?? '(no id)'} for user ${owner.userId} was not stored (${reason}); ` +
+                'the response is returned without it');
+            return { ...published, storageObjectId: null, storageError: 'AI_STORAGE_UNAVAILABLE' };
+        }
+    }
+    // ---- embed ---------------------------------------------------------------------
+    async embed(scope, req, opts = {}) {
+        const call = await this.prepareEmbedding(scope.userId, req, scope.feature, await this.orgOf(scope));
+        const { ctx, keySource } = await this.context(scope, call, opts, () => call.request.input);
+        const tracker = this.track(scope, call, keySource, 'embeddings.create');
+        let result;
+        try {
+            result = await call.port.embed(call.request, ctx);
+        }
+        catch (err) {
+            const error = toAiError(err, opts.signal);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        await tracker.finish({ status: 'succeeded', result });
+        return result;
+    }
+    // ---- realtime ---------------------------------------------------------------------
+    async createRealtimeSession(scope, req, opts = {}) {
+        const call = await this.prepareRealtime(scope.userId, req, scope.feature, await this.orgOf(scope));
+        const { ctx, keySource } = await this.context(scope, call, opts, () => ({
+            instructions: call.request.instructions,
+        }));
+        const tracker = this.track(scope, call, keySource, 'realtime.session');
+        let session;
+        try {
+            session = await call.port.createSession(call.request, ctx);
+        }
+        catch (err) {
+            const error = toAiError(err, opts.signal);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        // ⚠ Only the request id reaches the tracker — never the secret.
+        await tracker.finish({
+            status: 'succeeded',
+            result: { providerRequestId: session.providerRequestId },
+            units: { sessions: 1 },
+        });
+        return {
+            provider: call.provider,
+            model: session.model || call.modelId,
+            voice: session.voice ?? call.request.voice,
+            clientSecret: session.clientSecret,
+            expiresAt: session.expiresAt,
+            connectUrl: session.connectUrl,
+        };
+    }
+    // ---- custom operations ------------------------------------------------------------
+    /**
+     * `run(operationId, input)` (PP-14.17, #935): one provider round-trip of a
+     * custom operation, through the same gates, key resolution, limits, usage
+     * row and span as every built-in port. See `AiUserClient.run`.
+     */
+    async runOperation(scope, operationId, input, opts = {}) {
+        const call = await this.prepareOperation(scope.userId, operationId, input, opts, await this.orgOf(scope), scope.feature);
+        // ⚠ The input is NOT passed as the debug prompt: an operation's input is
+        // whatever the app defined (a transcript, a document) and only the
+        // operation id is safe to name.
+        const { ctx, keySource } = await this.context(scope, call, opts, () => ({ operation: call.operation.id }));
+        const tracker = this.track(scope, call, keySource, `operation:${call.operation.id}`);
+        let output;
+        try {
+            output = await call.handler(call.input, { ...ctx, model: call.modelId, operation: call.operation.id });
+        }
+        catch (err) {
+            const error = scrubKey(toAiError(err, opts.signal), ctx.apiKey);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        // The output is the trust boundary on the way back: it must match the
+        // operation's schema, and it must not carry the key the call was made under.
+        const parsed = call.operation.outputSchema?.safeParse(output);
+        const unusable = !parsed?.success || containsKey(parsed.data, ctx.apiKey);
+        if (unusable) {
+            const error = new ai_error_1.AiError('AI_STRUCTURED_OUTPUT_INVALID', `The "${call.operation.id}" operation returned output that could not be accepted.`, { details: { operation: call.operation.id } });
+            // The round-trip happened (and may have been billed): record it failed.
+            await tracker.finish({ status: 'failed', errorCode: error.code });
+            throw error;
+        }
+        await tracker.finish({ status: 'succeeded', units: this.operationUnits(call, parsed.data) });
+        return parsed.data;
+    }
+    /** The non-token units one successful custom call reports; a throwing callback never fails the call. */
+    operationUnits(call, output) {
+        try {
+            return call.operation.usageUnits?.(output, call.input);
+        }
+        catch {
+            this.logger.warn(`The usageUnits callback of AI operation "${call.operation.id}" threw; no units are recorded`);
+            return undefined;
+        }
+    }
+    /**
+     * The gate pipeline for a custom operation: kill switch, the operation is
+     * registered and runnable, its `inputSchema`, target (an omitted model is
+     * the first usable model declaring the operation's capability whose
+     * provider implements it), provider, model with the capability (model AND
+     * provider), the feature's needs. Decrypts nothing.
+     *
+     * @internal
+     */
+    async prepareOperation(userId, operationId, input, opts, orgId, featureId) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(orgId);
+        const operation = (0, operation_registry_1.getAiOperation)(operationId);
+        if (!operation) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `AI operation "${operationId}" is not registered; register it with registerAiOperation.`, { details: { operation: operationId } });
+        }
+        if ((0, operation_registry_1.isBuiltinAiOperation)(operation.id) || !operation.inputSchema || !operation.outputSchema) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `AI operation "${operation.id}" is a built-in operation: call its own method, not run().`, { details: { operation: operation.id } });
+        }
+        const parsedInput = operation.inputSchema.safeParse(input);
+        if (!parsedInput.success) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `The input of AI operation "${operation.id}" is invalid.`, {
+                details: {
+                    operation: operation.id,
+                    // Paths, codes and the schema's own messages; never a value from the input.
+                    // An unrecognized-keys message names the input's keys, so it is left out.
+                    issues: parsedInput.error.issues.slice(0, 10).map((issue) => ({
+                        path: issue.path.map(String).join('.'),
+                        code: issue.code,
+                        ...(issue.code === 'unrecognized_keys' ? {} : { message: issue.message.slice(0, 200) }),
+                    })),
+                },
+            });
+        }
+        const feature = this.featureOf(featureId);
+        const { provider, model } = opts.model?.trim()
+            ? await this.resolveTarget(userId, opts, { orgId, feature })
+            : await this.firstUsableModel(userId, operation.capability, opts.provider, orgId, operation.id);
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, orgId);
+        // 3. Model enabled, the capability declared (model AND provider), key reach.
+        const { model: usable } = await this.usableModels.assertUsable(userId, provider, model, [operation.capability], { orgId });
+        assertFeatureFits(feature, provider, model, usable.capabilities);
+        const handler = this.registry.supportsOperation(provider, operation.id)
+            ? this.registry.get(provider)?.operations?.[operation.id]
+            : undefined;
+        if (!handler) {
+            // The provider may serve the capability through another operation; it does not implement this one.
+            throw capabilityUnsupported(provider, model, operation.capability);
+        }
+        const policy = await this.aiConfig.resolveForOrg(orgId);
+        return {
+            provider,
+            modelId: model,
+            operation,
+            handler,
+            input: parsedInput.data,
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    // ---- images ---------------------------------------------------------------------
+    async startImageRun(scope, operation, req) {
+        const orgId = await this.orgOf(scope);
+        const call = await this.prepareImage(scope.userId, operation, req, orgId, scope.feature);
+        return this.runs.create({
+            userId: scope.userId,
+            orgId,
+            provider: call.provider,
+            modelId: call.modelId,
+            request: call.stored,
+            jobType: ai_runs_service_1.AI_IMAGE_GENERATE_TYPE,
+            ...(scope.feature ? { feature: scope.feature } : {}),
+        });
+    }
+    /**
+     * Executes one stored image run for `userId` — the `ai.image.generate`
+     * handler's entry point, not a fork's (a fork calls `generateImage`/
+     * `editImage`, which queue). Re-runs every gate, reads an edit's input
+     * bytes, then makes ONE provider round-trip with one usage row.
+     *
+     * @internal
+     */
+    async executeImageRun(userId, stored, opts = {}) {
+        const scope = { userId, orgId: opts.orgId, jobId: opts.jobId, ...attributedFeatureOf(opts) };
+        const edit = stored.operation === 'images.edit';
+        const call = await this.prepareImage(userId, stored.operation, {
+            ...(0, ai_image_run_request_1.toImageGenerationRequest)(stored),
+            provider: stored.provider,
+            ...(edit
+                ? {
+                    imageStorageObjectIds: stored.imageStorageObjectIds ?? [],
+                    ...(stored.maskStorageObjectId ? { maskStorageObjectId: stored.maskStorageObjectId } : {}),
+                }
+                : {}),
+        }, await this.orgOf(scope));
+        await opts.beforeCall?.();
+        const images = [];
+        for (const input of call.inputs.images) {
+            images.push(await this.inputs.read(input, { maxBytes: media_types_1.AI_IMAGE_INPUT_MAX_BYTES, label: 'image' }));
+        }
+        const mask = call.inputs.mask
+            ? await this.inputs.read(call.inputs.mask, { maxBytes: media_types_1.AI_IMAGE_INPUT_MAX_BYTES, label: 'mask' })
+            : undefined;
+        const request = (0, ai_image_run_request_1.toImageGenerationRequest)(call.stored);
+        const { ctx, keySource } = await this.context(scope, call, opts, () => ({ prompt: request.prompt }));
+        const tracker = this.track(scope, call, keySource, call.operation);
+        let result;
+        try {
+            if (edit) {
+                // `prepareImage` refused a port without `edit`; this narrows the type.
+                const editPort = call.port.edit;
+                result = await editPort({ ...request, images, ...(mask ? { mask } : {}) }, ctx);
+            }
+            else {
+                result = await call.port.generate(request, ctx);
+            }
+        }
+        catch (err) {
+            const error = toAiError(err, opts.signal);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        await tracker.finish({ status: 'succeeded', result, units: { images: result.images.length } });
+        return result;
+    }
+    // ---- transcription ------------------------------------------------------------------
+    async startTranscriptionRun(scope, req) {
+        const orgId = await this.orgOf(scope);
+        const call = await this.prepareTranscription(scope.userId, req, orgId, scope.feature);
+        return this.runs.create({
+            userId: scope.userId,
+            orgId,
+            provider: call.provider,
+            modelId: call.modelId,
+            request: call.stored,
+            jobType: ai_runs_service_1.AI_AUDIO_TRANSCRIBE_TYPE,
+            ...(scope.feature ? { feature: scope.feature } : {}),
+        });
+    }
+    /**
+     * Executes one stored transcription run for `userId` — the
+     * `ai.audio.transcribe` handler's entry point, not a fork's (a fork calls
+     * `transcribe`, which queues). Re-runs every gate, opens the recording,
+     * then makes ONE provider round-trip with one usage row.
+     *
+     * @internal
+     */
+    async executeTranscriptionRun(userId, stored, opts = {}) {
+        const scope = { userId, orgId: opts.orgId, jobId: opts.jobId, ...attributedFeatureOf(opts) };
+        const call = await this.prepareTranscription(userId, {
+            storageObjectId: stored.storageObjectId,
+            provider: stored.provider,
+            model: stored.model,
+            ...transcriptionFields(stored),
+        }, await this.orgOf(scope));
+        await opts.beforeCall?.();
+        const audio = await this.openRecording(call);
+        let result;
+        try {
+            const { ctx, keySource } = await this.context(scope, call, opts, () => ({
+                language: call.stored.language,
+                prompt: call.stored.prompt,
+            }));
+            const tracker = this.track(scope, call, keySource, 'audio.transcribe');
+            const request = { model: call.modelId, audio: audio.payload, ...transcriptionFields(call.stored) };
+            try {
+                result = await call.transcribe(request, ctx);
+            }
+            catch (err) {
+                // A recording that turned out larger than its row said: the cap
+                // stopped the upload, and THAT is the answer, not the transport
+                // failure the SDK saw.
+                const error = audio.exceeded() ?? toAiError(err, opts.signal);
+                await tracker.finish(failure(error, opts.signal));
+                throw error;
+            }
+            result = this.boundExtras(result);
+            await tracker.finish({
+                status: 'succeeded',
+                result,
+                ...(result.durationSeconds !== undefined ? { units: { audioSeconds: result.durationSeconds } } : {}),
+            });
+        }
+        finally {
+            audio.close();
+        }
+        return result;
+    }
+    /**
+     * The result with its `extras` checked (PP-14.17, #935): kept when bounded
+     * and well-formed, dropped otherwise. The transcript is never lost to a bad
+     * extra, and the dropped value is never logged (it is the user's content).
+     */
+    boundExtras(result) {
+        if (result.extras === undefined)
+            return result;
+        const { extras, rejected } = (0, ai_transcription_extras_1.boundTranscriptionExtras)(result.extras);
+        const { extras: _dropped, ...rest } = result;
+        if (rejected) {
+            this.logger.warn(`Transcription extras from ${result.provider}/${result.model} were dropped (${rejected})`);
+        }
+        return extras ? { ...rest, extras } : rest;
+    }
+    /**
+     * The recording as the adapter receives it. A row that knows its size
+     * (already checked against the cap) is STREAMED through a reader that
+     * fails past `maxBytes`; a simple upload whose size is not recorded yet
+     * (`0`) is read with the cap enforced first, so an oversized file is
+     * refused before the provider is called either way.
+     */
+    async openRecording(call) {
+        const { input, maxBytes } = call;
+        if (input.size > 0) {
+            const capped = await this.inputs.openCapped(input, { maxBytes, label: 'audio' });
+            const filename = (0, ai_provider_filename_1.providerFileName)(input.name, input.mimeType);
+            return {
+                payload: { stream: capped.stream, mimeType: input.mimeType, filename, size: input.size },
+                exceeded: capped.exceeded,
+                close: capped.close,
+            };
+        }
+        const bytes = await this.inputs.read(input, { maxBytes, label: 'audio' });
+        const payload = { ...bytes, filename: (0, ai_provider_filename_1.providerFileName)(input.name, input.mimeType) };
+        return { payload, exceeded: () => undefined, close: () => undefined };
+    }
+    // ---- speech -------------------------------------------------------------------------
+    async startSpeechRun(scope, req) {
+        const orgId = await this.orgOf(scope);
+        const call = await this.prepareSpeech(scope.userId, req, scope.feature, orgId);
+        return this.runs.create({
+            userId: scope.userId,
+            orgId,
+            provider: call.provider,
+            modelId: call.modelId,
+            request: call.stored,
+            jobType: ai_runs_service_1.AI_AUDIO_SPEECH_TYPE,
+            ...(scope.feature ? { feature: scope.feature } : {}),
+        });
+    }
+    /**
+     * Executes one stored speech run for `userId` — the `ai.audio.speech`
+     * handler's entry point, not a fork's (a fork calls `speak`, which
+     * queues). Re-runs every gate, then makes ONE provider round-trip with one
+     * usage row (`units: { characters }`).
+     *
+     * @internal
+     */
+    async executeSpeechRun(userId, stored, opts = {}) {
+        const scope = { userId, orgId: opts.orgId, jobId: opts.jobId, ...attributedFeatureOf(opts) };
+        const call = await this.prepareSpeech(userId, {
+            input: stored.input,
+            voice: stored.voice,
+            provider: stored.provider,
+            model: stored.model,
+            format: stored.format,
+            ...speechFields(stored),
+        }, undefined, opts.orgId);
+        await opts.beforeCall?.();
+        const { ctx, keySource } = await this.context(scope, call, opts, () => ({
+            input: call.stored.input,
+            instructions: call.stored.instructions,
+        }));
+        const tracker = this.track(scope, call, keySource, 'audio.speech');
+        const request = {
+            model: call.modelId,
+            input: call.stored.input,
+            voice: call.stored.voice,
+            format: call.stored.format,
+            ...speechFields(call.stored),
+        };
+        let result;
+        try {
+            result = await call.speech(request, ctx);
+        }
+        catch (err) {
+            const error = toAiError(err, opts.signal);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        await tracker.finish({ status: 'succeeded', result, units: { characters: request.input.length } });
+        return result;
+    }
+    // ---- stream -------------------------------------------------------------------
+    async *lazyStream(scope, req, opts = {}) {
+        yield* await this.openStream(scope, req, opts);
+    }
+    async openStream(scope, req, opts = {}) {
+        const call = await this.prepare(scope.userId, req, { streaming: true, orgId: await this.orgOf(scope), feature: scope.feature });
+        const storageInputs = await this.materializeStorageInputs(call);
+        const { ctx, keySource } = await this.context(scope, call, opts, () => responsePrompt(call.request), storageInputs);
+        const tracker = this.track(scope, call, keySource, 'responses.stream');
+        const settler = this.hostedOutputs(scope, call);
+        let iterator;
+        // Prime the first event so a provider refusal that happens before the
+        // stream starts (a rejected key, a throttle) rejects THIS promise — the
+        // caller can still answer it as an ordinary error, not an in-band frame.
+        let first;
+        try {
+            iterator = call.port.stream(call.request, ctx)[Symbol.asyncIterator]();
+            first = await iterator.next();
+        }
+        catch (err) {
+            const error = toAiError(err, opts.signal);
+            await tracker.finish(failure(error, opts.signal));
+            throw error;
+        }
+        // An adapter that reports a failure as its very FIRST event has streamed
+        // nothing yet: that is a refusal, not a mid-stream failure, and it is
+        // answered the same way as one that threw.
+        if (!first.done && first.value.type === 'error') {
+            const { code, message } = first.value;
+            await iterator.return?.();
+            await tracker.finish({ status: 'failed', errorCode: code });
+            throw new ai_error_1.AiError(code, message);
+        }
+        return this.relay(first, iterator, tracker, settler, opts);
+    }
+    async *relay(first, iterator, tracker, settler, opts) {
+        let finished = false;
+        // Until a terminal event arrives, the stream ending means the consumer
+        // walked away (or the adapter broke the contract — also not a success).
+        let outcome = { status: 'cancelled' };
+        try {
+            let result = first;
+            while (!result.done) {
+                const event = result.value;
+                if (event.type === 'response.completed') {
+                    outcome = { status: 'succeeded', result: event.response, units: hostedImageUnits(event.response) };
+                }
+                else if (event.type === 'error') {
+                    outcome = { status: 'failed', errorCode: event.code };
+                }
+                yield await settler.event(event);
+                result = await iterator.next();
+            }
+            finished = true;
+            if (outcome.status === 'cancelled' && !opts.signal?.aborted) {
+                outcome = { status: 'failed', errorCode: 'AI_PROVIDER_UNAVAILABLE' };
+            }
+        }
+        catch (err) {
+            finished = true;
+            const error = toAiError(err, opts.signal);
+            outcome = failure(error, opts.signal);
+            throw error;
+        }
+        finally {
+            // A consumer that stopped early: let the adapter close its connection.
+            if (!finished)
+                await iterator.return?.();
+            await tracker.finish(outcome);
+        }
+    }
+    // ---- usage + tracing --------------------------------------------------------------
+    /** Opens the `ai.request` span and returns the once-only finisher for it. */
+    track(scope, call, keySource, operation) {
+        const feature = featureOfScope(scope);
+        const started = Date.now();
+        const span = tracer.startSpan(exports.AI_REQUEST_SPAN, {
+            kind: api_1.SpanKind.INTERNAL,
+            attributes: {
+                'ai.provider': call.provider,
+                'ai.model': call.modelId,
+                'ai.operation': usageOperationOf(operation),
+                'ai.key_source': keySource,
+                ...(call.keyTier ? { 'ai.key.tier': call.keyTier } : {}),
+                ...(feature ? { 'ai.feature': feature } : {}),
+                ...(call.hostedTools?.length ? { 'ai.hosted_tools': call.hostedTools.join(',') } : {}),
+            },
+        });
+        let done = false;
+        return {
+            finish: async (outcome) => {
+                if (done)
+                    return;
+                done = true;
+                const latencyMs = Date.now() - started;
+                const usage = outcome.result?.usage;
+                span.setAttribute('ai.status', outcome.status);
+                if (outcome.errorCode)
+                    span.setAttribute('ai.error_code', outcome.errorCode);
+                if (usage?.inputTokens !== undefined)
+                    span.setAttribute('ai.usage.input_tokens', usage.inputTokens);
+                if (usage?.outputTokens !== undefined)
+                    span.setAttribute('ai.usage.output_tokens', usage.outputTokens);
+                if (usage?.reasoningTokens !== undefined) {
+                    span.setAttribute('ai.usage.reasoning_tokens', usage.reasoningTokens);
+                }
+                span.setStatus(outcome.status === 'failed'
+                    ? { code: api_1.SpanStatusCode.ERROR, message: outcome.errorCode ?? 'failed' }
+                    : { code: api_1.SpanStatusCode.OK });
+                span.end();
+                this.logger.debug(`AI ${operation} ${call.provider}/${call.modelId} key=${keySource} ` +
+                    `${outcome.status}${outcome.errorCode ? ` (${outcome.errorCode})` : ''} in ${latencyMs}ms`);
+                await this.usage.record({
+                    userId: scope.userId,
+                    ...(scope.orgId ? { orgId: scope.orgId } : {}),
+                    provider: call.provider,
+                    modelId: call.modelId,
+                    operation: usageOperationOf(operation),
+                    keySource,
+                    usage,
+                    ...(outcome.units ? { units: outcome.units } : {}),
+                    latencyMs,
+                    status: outcome.status,
+                    errorCode: outcome.errorCode ?? null,
+                    providerRequestId: outcome.result?.providerRequestId ?? null,
+                    jobId: scope.jobId ?? null,
+                    ...(feature ? { feature } : {}),
+                });
+            },
+        };
+    }
+    // ---- the gate pipeline -----------------------------------------------------------
+    /**
+     * Steps 1-5 of the pipeline: everything but the key. Throws the exact
+     * `AiError` for the first gate that refuses. Decrypts nothing.
+     *
+     * @internal
+     */
+    async prepare(userId, req, opts) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(opts.orgId);
+        const feature = this.featureOf(opts.feature);
+        const { provider, model } = await this.resolveTarget(userId, req, { orgId: opts.orgId, feature });
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, opts.orgId);
+        const port = this.registry.get(provider)?.responses;
+        const policy = await this.aiConfig.resolveForOrg(opts.orgId);
+        // 2a. Response chaining (#446): a stateless provider stores no response
+        // to chain onto. Refused, not silently dropped — ignoring it would answer
+        // as if the conversation had just begun.
+        if (req.previousResponseId !== undefined && !this.registry.supportsPreviousResponseId(provider)) {
+            throw new ai_error_1.AiError('AI_CAPABILITY_UNSUPPORTED', `Provider "${provider}" does not support previousResponseId; send the conversation history as input instead.`, { details: { provider, model, capability: 'previous_response_id' } });
+        }
+        // 2b. Hosted tools (#442): well-formed, switched on by an administrator,
+        // and an MCP server on an allowed host.
+        (0, hosted_tools_1.assertHostedToolShapes)(req.tools);
+        (0, hosted_tools_1.assertHostedToolsAllowed)(req.tools, policy.hostedTools);
+        // 3. Model enabled, capabilities (model AND provider port), key reach.
+        const needed = requiredCapabilities(req, opts.streaming);
+        const { model: usable } = await this.usableModels.assertUsable(userId, provider, model, needed, { orgId: opts.orgId });
+        assertFeatureFits(feature, provider, model, usable.capabilities);
+        if (!port) {
+            // assertUsable already refused a provider without a responses port
+            // (`responses` is always in `needed`); this narrows the type.
+            throw capabilityUnsupported(provider, model, 'responses');
+        }
+        // 4. Reasoning effort must be one the model offers, when it says.
+        const effort = req.reasoning?.effort;
+        const efforts = usable.capabilities.reasoningEfforts;
+        if (effort && efforts && !efforts.includes(effort)) {
+            throw new ai_error_1.AiError('AI_CAPABILITY_UNSUPPORTED', `Model "${model}" does not offer reasoning effort "${effort}".`, { details: { provider, model, capability: 'reasoning', effort } });
+        }
+        // 4b. Storage-object inputs: ownership, readiness, modality, size, strategy.
+        const storageInputs = await this.planStorageInputs(userId, provider, model, usable, req.input, opts.orgId);
+        // 5. Clamp output tokens: the deployment cap and the model's own
+        // `ai.limits.perModel` cap (#450) combine — the smaller wins — and bound
+        // the call even when the request named no limit of its own.
+        const maxOutputTokens = clampOutputTokens(req.maxOutputTokens, (0, ai_limits_service_1.effectiveOutputTokensCap)(policy.defaults.maxOutputTokensCap, policy.limits, provider, model), usable.capabilities.maxOutputTokens);
+        const { provider: _provider, model: _model, ...rest } = req;
+        const request = { ...rest, model };
+        if (maxOutputTokens !== undefined) {
+            request.maxOutputTokens = maxOutputTokens;
+        }
+        const hostedTools = [...new Set((0, hosted_tools_1.hostedToolsOf)(request.tools).map((tool) => tool.type))];
+        return {
+            provider,
+            modelId: model,
+            port,
+            request,
+            model: usable,
+            storageInputs,
+            ...(hostedTools.length > 0 ? { hostedTools } : {}),
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    /**
+     * The gate pipeline for `embed`: kill switch, request shape, target,
+     * provider, then model/capability/key/reach with `embeddings` as the one
+     * capability needed. Decrypts nothing.
+     *
+     * @internal
+     */
+    async prepareEmbedding(userId, req, featureId, orgId) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(orgId);
+        assertEmbeddingShape(req);
+        if (!req.model?.trim()) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'Name the embedding model explicitly: vectors are only comparable within one model.');
+        }
+        const feature = this.featureOf(featureId);
+        const { provider, model } = await this.resolveTarget(userId, req, { feature });
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, orgId);
+        const port = this.registry.get(provider)?.embeddings;
+        // 3. Model enabled, `embeddings` declared (model AND provider port), key reach.
+        const { model: usableEmbedding } = await this.usableModels.assertUsable(userId, provider, model, ['embeddings'], { orgId });
+        assertFeatureFits(feature, provider, model, usableEmbedding.capabilities);
+        if (!port) {
+            // assertUsable already refused a provider without the port; this narrows the type.
+            throw capabilityUnsupported(provider, model, 'embeddings');
+        }
+        const policy = await this.aiConfig.resolveForOrg(orgId);
+        // Named fields only: whatever else the caller's object carried stays here.
+        const request = { model, input: req.input };
+        if (req.dimensions !== undefined)
+            request.dimensions = req.dimensions;
+        if (req.providerOptions !== undefined)
+            request.providerOptions = req.providerOptions;
+        return {
+            provider,
+            modelId: model,
+            port,
+            request,
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    /**
+     * The gate pipeline for an image generation or edit: kill switch, request
+     * shape, target, provider, model with `image_generation`/`image_edit` (model
+     * AND provider port), then — for an edit — every input storage object,
+     * checked for ownership, readiness, type and size from its row alone.
+     * Decrypts nothing and reads no bytes.
+     *
+     * @internal
+     */
+    async prepareImage(userId, operation, req, orgId, featureId) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(orgId);
+        const edit = operation === 'images.edit';
+        assertImageShape(req, edit);
+        if (!req.model?.trim()) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'Name the image model explicitly.');
+        }
+        const feature = this.featureOf(featureId);
+        const { provider, model } = await this.resolveTarget(userId, req, { orgId, feature });
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, orgId);
+        const port = this.registry.get(provider)?.images;
+        const capability = edit ? 'image_edit' : 'image_generation';
+        // 3. Model enabled, the capability declared (model AND provider port), key reach.
+        const { model: usableImage } = await this.usableModels.assertUsable(userId, provider, model, [capability], { orgId });
+        assertFeatureFits(feature, provider, model, usableImage.capabilities);
+        if (!port || (edit && !port.edit)) {
+            // assertUsable already refused a provider without the port; this narrows the type.
+            throw capabilityUnsupported(provider, model, capability);
+        }
+        // 4. An edit's inputs: the caller's own, ready, and the right kind.
+        const inputs = { images: [] };
+        if (edit) {
+            const { imageStorageObjectIds, maskStorageObjectId } = req;
+            for (const id of imageStorageObjectIds) {
+                inputs.images.push(await this.inputs.resolve(userId, id, {
+                    mimeTypes: media_types_1.AI_IMAGE_INPUT_MIME_TYPES,
+                    maxBytes: media_types_1.AI_IMAGE_INPUT_MAX_BYTES,
+                    label: 'image',
+                    ...(orgId ? { orgId } : {}),
+                }));
+            }
+            if (maskStorageObjectId) {
+                inputs.mask = await this.inputs.resolve(userId, maskStorageObjectId, {
+                    mimeTypes: media_types_1.AI_IMAGE_MASK_MIME_TYPES,
+                    maxBytes: media_types_1.AI_IMAGE_INPUT_MAX_BYTES,
+                    label: 'mask',
+                    ...(orgId ? { orgId } : {}),
+                });
+            }
+        }
+        const policy = await this.aiConfig.resolveForOrg(orgId);
+        // Named fields only: whatever else the caller's object carried stays here.
+        const stored = ai_image_run_request_1.storedAiImageRunRequestSchema.parse({
+            operation,
+            provider,
+            ...(0, ai_image_run_request_1.toImageGenerationRequest)({ operation, provider, ...req, model }),
+            ...(edit
+                ? {
+                    imageStorageObjectIds: inputs.images.map((input) => input.id),
+                    ...(inputs.mask ? { maskStorageObjectId: inputs.mask.id } : {}),
+                }
+                : {}),
+        });
+        return {
+            operation,
+            provider,
+            modelId: model,
+            port,
+            stored,
+            inputs,
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    /**
+     * Step 4b: every storage-object part of `input`, authorised and checked
+     * from its row alone (see the file header). Reads no bytes and presigns
+     * nothing — `startRun` calls this too, and must not.
+     *
+     * @throws NotFoundException / ForbiddenException for an unknown object or
+     *   another user's (the answers `ObjectsService` gives);
+     *   AiError('AI_INVALID_REQUEST') for a part with both `url` and
+     *   `storageObjectId`, too many parts, an object not ready, an image part
+     *   that is not an image, or an object over its modality's cap;
+     *   AiError('AI_CAPABILITY_UNSUPPORTED') when the model lacks the
+     *   modality or the provider declares no `fileInputStrategy`.
+     */
+    async planStorageInputs(userId, provider, model, usable, input, orgId) {
+        const parts = storageParts(input);
+        if (parts.length === 0)
+            return [];
+        for (const part of parts) {
+            if (part.url !== undefined) {
+                throw new ai_error_1.AiError('AI_INVALID_REQUEST', `An ${part.type} part takes a url OR a storageObjectId, not both.`, {
+                    details: { part: part.type, storageObjectId: part.storageObjectId },
+                });
+            }
+        }
+        const distinct = new Set(parts.map((part) => part.storageObjectId));
+        if (distinct.size > file_inputs_types_1.AI_STORAGE_INPUTS_MAX) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `At most ${file_inputs_types_1.AI_STORAGE_INPUTS_MAX} stored files per request.`, {
+                details: { storageInputs: distinct.size, max: file_inputs_types_1.AI_STORAGE_INPUTS_MAX },
+            });
+        }
+        const strategies = this.registry.get(provider)?.fileInputStrategy;
+        if (!strategies) {
+            throw new ai_error_1.AiError('AI_CAPABILITY_UNSUPPORTED', `The "${provider}" provider does not accept stored files as inputs; pass a url.`, { details: { provider, model, capability: 'file_input' } });
+        }
+        const planned = new Map();
+        for (const part of parts) {
+            const id = part.storageObjectId;
+            let plan = planned.get(id);
+            if (!plan) {
+                const resolved = await this.inputs.resolve(userId, id, { label: part.type, ...(orgId ? { orgId } : {}) });
+                const modality = (0, file_inputs_types_1.storageInputModality)(resolved.mimeType);
+                const maxBytes = (0, file_inputs_types_1.storageInputMaxBytes)(modality);
+                if (resolved.size > maxBytes) {
+                    throw new ai_error_1.AiError('AI_INVALID_REQUEST', `The ${modality} storage object is larger than ${maxBytes} bytes (${maxBytes / 1024 / 1024} MiB).`, { details: { storageObjectId: id, size: resolved.size, maxBytes } });
+                }
+                const capability = modality === 'image' ? 'vision_input' : 'file_input';
+                const caps = usable.capabilities;
+                if (!caps.capabilities.includes(capability) || !caps.inputModalities.includes(modality)) {
+                    throw new ai_error_1.AiError('AI_CAPABILITY_UNSUPPORTED', `Model "${model}" does not accept ${modality} inputs (${resolved.mimeType}).`, { details: { provider, model, capability, storageObjectId: id, mimeType: resolved.mimeType } });
+                }
+                plan = { input: resolved, modality, strategy: strategies[modality] };
+                planned.set(id, plan);
+            }
+            if (part.type === 'image' && plan.modality !== 'image') {
+                throw new ai_error_1.AiError('AI_INVALID_REQUEST', `An image part must reference an image (PNG, JPEG, GIF or WebP); this object is ` +
+                    `${plan.input.mimeType} — send it as a file part.`, { details: { storageObjectId: id, mimeType: plan.input.mimeType } });
+            }
+        }
+        return [...planned.values()];
+    }
+    /**
+     * After the gates, before the key: what each planned input's delivery
+     * strategy needs, for ONE provider call — a fresh presigned URL, or a
+     * capped byte stream. A storage failure here is `AI_STORAGE_UNAVAILABLE`
+     * (nothing was sent, so no usage row).
+     *
+     * ⚠ The URLs exist only in the returned map, which only `ctx` carries.
+     */
+    async materializeStorageInputs(call) {
+        if (call.storageInputs.length === 0)
+            return undefined;
+        const resolved = new Map();
+        for (const { input, modality, strategy } of call.storageInputs) {
+            const base = {
+                storageObjectId: input.id,
+                modality,
+                mimeType: input.mimeType,
+                // The wire name, normalised for providers that sniff the extension.
+                filename: (0, ai_provider_filename_1.providerFileName)(input.name, input.mimeType),
+                strategy,
+            };
+            if (strategy === 'presigned_url') {
+                let url;
+                try {
+                    url = await this.inputs.presign(input, file_inputs_types_1.AI_STORAGE_INPUT_URL_TTL_SECONDS);
+                }
+                catch (err) {
+                    throw storageInputFailure(err);
+                }
+                resolved.set(input.id, { ...base, url });
+            }
+            else {
+                const limits = { maxBytes: (0, file_inputs_types_1.storageInputMaxBytes)(modality), label: modality };
+                resolved.set(input.id, {
+                    ...base,
+                    open: () => this.inputs.open(input, limits).catch((err) => Promise.reject(storageInputFailure(err))),
+                    read: () => this.inputs.read(input, limits).catch((err) => Promise.reject(storageInputFailure(err))),
+                });
+            }
+        }
+        return resolved;
+    }
+    /**
+     * The gate pipeline for a transcription: kill switch, request shape,
+     * target (an omitted model is the first usable `audio_transcription`
+     * model), provider, model with `audio_transcription` (model AND provider
+     * port), then the recording's storage object — ownership, readiness, an
+     * audio (or MP4/WebM video) type, and the port's size limit — from its row
+     * alone. Decrypts nothing and reads no bytes.
+     *
+     * @internal
+     */
+    async prepareTranscription(userId, req, orgId, featureId) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(orgId);
+        assertTranscriptionShape(req);
+        const feature = this.featureOf(featureId);
+        const { provider, model } = req.model?.trim()
+            ? await this.resolveTarget(userId, req, { orgId, feature })
+            : await this.firstUsableModel(userId, 'audio_transcription', req.provider, orgId);
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, orgId);
+        const port = this.registry.get(provider)?.audio;
+        // 3. Model enabled, `audio_transcription` declared (model AND port), key reach.
+        const { model: usableTranscription } = await this.usableModels.assertUsable(userId, provider, model, ['audio_transcription'], { orgId });
+        assertFeatureFits(feature, provider, model, usableTranscription.capabilities);
+        const transcribe = port?.transcribe?.bind(port);
+        if (!port || !transcribe) {
+            // assertUsable already refused a provider without the method; this narrows the type.
+            throw capabilityUnsupported(provider, model, 'audio_transcription');
+        }
+        // 4. The recording: the caller's own, ready, audio, within the provider's limit.
+        const maxBytes = port.transcriptionMaxBytes ?? media_types_1.AI_TRANSCRIPTION_DEFAULT_MAX_BYTES;
+        const input = await this.inputs.resolve(userId, req.storageObjectId, {
+            mimeTypes: media_types_1.AI_TRANSCRIPTION_INPUT_MIME_TYPES,
+            maxBytes,
+            label: 'audio',
+            ...(orgId ? { orgId } : {}),
+        });
+        const policy = await this.aiConfig.resolveForOrg(orgId);
+        // Named fields only: whatever else the caller's object carried stays here.
+        const stored = ai_audio_run_request_1.storedAiTranscriptionRunRequestSchema.parse({
+            operation: ai_audio_run_request_1.AI_TRANSCRIBE_OPERATION,
+            provider,
+            model,
+            storageObjectId: input.id,
+            ...transcriptionFields(req),
+        });
+        return {
+            provider,
+            modelId: model,
+            transcribe,
+            stored,
+            input,
+            maxBytes,
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    /**
+     * The gate pipeline for speech: kill switch, request shape (input at most
+     * `AI_SPEECH_INPUT_MAX_CHARS`), target (an omitted model is the first
+     * usable `audio_speech` model), provider, model with `audio_speech` (model
+     * AND provider port), then the voice — the request's, else the model's
+     * first — checked against the model's catalog `voices`, else the port's.
+     * Decrypts nothing.
+     *
+     * @internal
+     */
+    async prepareSpeech(userId, req, featureId, orgId) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(orgId);
+        assertSpeechShape(req);
+        const feature = this.featureOf(featureId);
+        const { provider, model } = req.model?.trim()
+            ? await this.resolveTarget(userId, req, { feature })
+            : await this.firstUsableModel(userId, 'audio_speech', req.provider, orgId);
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, orgId);
+        const port = this.registry.get(provider)?.audio;
+        // 3. Model enabled, `audio_speech` declared (model AND port), key reach.
+        const { model: usable } = await this.usableModels.assertUsable(userId, provider, model, ['audio_speech'], { orgId });
+        assertFeatureFits(feature, provider, model, usable.capabilities);
+        const speech = port?.speech?.bind(port);
+        if (!port || !speech) {
+            // assertUsable already refused a provider without the method; this narrows the type.
+            throw capabilityUnsupported(provider, model, 'audio_speech');
+        }
+        // 4. The voice: one this model speaks.
+        const voices = usable.capabilities.voices ?? port.voices;
+        const voice = req.voice ?? voices?.[0];
+        if (!voice) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Name a voice: model "${model}" lists none.`, {
+                details: { provider, model },
+            });
+        }
+        if (voices && !voices.includes(voice)) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Model "${model}" does not speak in voice "${voice}".`, {
+                details: { provider, model, voice, voices: [...voices] },
+            });
+        }
+        const policy = await this.aiConfig.resolveForOrg(orgId);
+        // Named fields only: whatever else the caller's object carried stays here.
+        const stored = ai_audio_run_request_1.storedAiSpeechRunRequestSchema.parse({
+            operation: ai_audio_run_request_1.AI_SPEECH_OPERATION,
+            provider,
+            model,
+            input: req.input,
+            voice,
+            format: req.format ?? 'mp3',
+            ...speechFields(req),
+        });
+        return {
+            provider,
+            modelId: model,
+            speech,
+            stored,
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    /**
+     * The gate pipeline for a realtime session (#449): kill switch,
+     * `ai.defaults.allowRealtime`, request shape, target (an omitted model is
+     * the first usable `realtime` model), provider, model with `realtime`
+     * (model AND provider port), then the voice — the request's, else the
+     * model's first — checked against the model's catalog `voices`, else the
+     * port's. The deployment's output-token cap becomes the session's initial
+     * `maxOutputTokens`. Decrypts nothing.
+     *
+     * @internal
+     */
+    async prepareRealtime(userId, req, featureId, orgId) {
+        // 1. Kill switch — before anything else is read.
+        await this.aiConfig.assertEnabled(orgId);
+        // 1b. The realtime switch: minting hands the browser a provider secret
+        // and the server stops seeing the call, so it is opt-in (§2.15).
+        const policy = await this.aiConfig.resolveForOrg(orgId);
+        if (!policy.defaults.allowRealtime) {
+            throw new ai_error_1.AiError('AI_REALTIME_DISABLED', 'Realtime voice sessions are disabled in this deployment.');
+        }
+        assertRealtimeShape(req);
+        const feature = this.featureOf(featureId);
+        const { provider, model } = req.model?.trim()
+            ? await this.resolveTarget(userId, req, { feature })
+            : await this.firstUsableModel(userId, 'realtime', req.provider, orgId);
+        // 2. Provider enabled in settings AND registered in this process.
+        const slot = await this.aiConfig.assertProviderEnabled(provider, orgId);
+        const port = this.registry.get(provider)?.realtime;
+        // 3. Model enabled, `realtime` declared (model AND port), key reach.
+        const { model: usable } = await this.usableModels.assertUsable(userId, provider, model, ['realtime'], { orgId });
+        assertFeatureFits(feature, provider, model, usable.capabilities);
+        if (!port) {
+            // assertUsable already refused a provider without the port; this narrows the type.
+            throw capabilityUnsupported(provider, model, 'realtime');
+        }
+        // 4. The voice: one this model speaks.
+        const voices = usable.capabilities.voices ?? port.voices;
+        const voice = req.voice ?? voices?.[0];
+        if (!voice) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Name a voice: model "${model}" lists none.`, {
+                details: { provider, model },
+            });
+        }
+        if (voices && !voices.includes(voice)) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Model "${model}" does not speak in voice "${voice}".`, {
+                details: { provider, model, voice, voices: [...voices] },
+            });
+        }
+        // 5. The deployment's output cap as the session's initial default — the
+        // client may change it over its data channel, so it bounds nothing the
+        // user cannot lift; it is a sensible starting point, not an enforcement.
+        const maxOutputTokens = clampOutputTokens(undefined, (0, ai_limits_service_1.effectiveOutputTokensCap)(policy.defaults.maxOutputTokensCap, policy.limits, provider, model), usable.capabilities.maxOutputTokens);
+        // Named fields only: whatever else the caller's object carried stays here.
+        const request = { model, voice };
+        if (req.instructions !== undefined)
+            request.instructions = req.instructions;
+        if (req.turnDetection !== undefined)
+            request.turnDetection = req.turnDetection;
+        if (req.tools !== undefined)
+            request.tools = req.tools;
+        if (req.providerOptions !== undefined)
+            request.providerOptions = req.providerOptions;
+        if (maxOutputTokens !== undefined)
+            request.maxOutputTokens = maxOutputTokens;
+        return {
+            provider,
+            modelId: model,
+            port,
+            request,
+            ...(0, ai_config_service_1.providerCallSettings)(slot),
+            logPromptContent: policy.logPromptContent,
+        };
+    }
+    /**
+     * The first model `userId` can use right now that declares `capability`
+     * (on `provider`, when given) — in `GET /api/ai/models` order. For an
+     * operation whose model is never the chat `ai.defaultModel`.
+     */
+    async firstUsableModel(userId, capability, provider, orgId, operation) {
+        const usable = await this.usableModels.listForUser(userId, orgId ? { orgId } : {});
+        const match = usable.find((m) => (provider === undefined || m.provider === provider) &&
+            m.capabilities.capabilities.includes(capability) &&
+            this.registry.supports(m.provider, capability) &&
+            (operation === undefined || this.registry.supportsOperation(m.provider, operation)));
+        if (!match) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `No model selected, and no model available to you supports ${capability}.`, { details: { capability, ...(provider ? { provider } : {}) } });
+        }
+        return { provider: match.provider, model: match.modelId };
+    }
+    /**
+     * Step 6: resolve the key, apply the rate limits (6b) and build the
+     * adapter context. `prompt` is the
+     * request's content, rendered only for the opt-in debug line.
+     */
+    async context(scope, call, opts, prompt, storageInputs) {
+        if (opts.signal?.aborted) {
+            throw cancelled(call.provider);
+        }
+        const orgId = await this.orgOf(scope);
+        // #739: the org tier needs the call's organization.
+        const { apiKey, keySource, tier } = await this.keyResolver.resolve(scope.userId, call.provider, { orgId });
+        call.keyTier = tier;
+        // 6b. Rate limits (#450) — here because the org-key limits need to know
+        // whose key pays. A refusal records no usage row: nothing was sent.
+        await this.limits.enforce({
+            userId: scope.userId,
+            orgId,
+            provider: call.provider,
+            modelId: call.modelId,
+            keySource,
+        });
+        const requestId = (0, node_crypto_1.randomUUID)();
+        if (call.logPromptContent) {
+            this.logger.debug(`AI prompt ${requestId} (${call.provider}/${call.modelId}): ${promptPreview(prompt())}`);
+        }
+        return {
+            ctx: {
+                apiKey,
+                requestId,
+                ...(call.baseUrl ? { baseUrl: call.baseUrl } : {}),
+                ...(call.providerSettings ? { providerSettings: call.providerSettings } : {}),
+                ...(opts.signal ? { signal: opts.signal } : {}),
+                ...(storageInputs ? { storageInputs } : {}),
+            },
+            keySource,
+        };
+    }
+    /**
+     * Which (provider, model) the request targets: the bound
+     * `AI_TARGET_RESOLVER` (#739), by default the base order (see `AiRequest`
+     * and `DefaultAiTargetResolver`). `null` from the resolver is "no model".
+     */
+    async resolveTarget(userId, req, ctx = {}) {
+        const target = await this.targets.resolve({
+            userId,
+            ...(ctx.orgId !== undefined ? { orgId: ctx.orgId } : {}),
+            ...(ctx.feature ? { feature: ctx.feature.id } : {}),
+            requested: {
+                ...(req.provider !== undefined ? { provider: req.provider } : {}),
+                ...(req.model !== undefined ? { model: req.model } : {}),
+            },
+        });
+        if (!target) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'No model selected.', {
+                ...(ctx.feature ? { details: { feature: ctx.feature.id } } : {}),
+            });
+        }
+        return { provider: target.provider, model: target.model };
+    }
+    /** The registered feature a call names, or `undefined`; an unknown id is AI_INVALID_REQUEST. */
+    featureOf(id) {
+        if (id === undefined)
+            return undefined;
+        const feature = (0, ai_feature_registry_1.getAiFeature)(id);
+        if (!feature) {
+            throw new ai_error_1.AiError('AI_INVALID_REQUEST', `AI feature "${id}" is not registered.`, { details: { feature: id } });
+        }
+        return feature;
+    }
+};
+exports.AiService = AiService;
+exports.AiService = AiService = AiService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(4, (0, common_1.Inject)(index_2.PLATFORM_PRISMA)),
+    __param(10, (0, common_1.Optional)()),
+    __param(10, (0, common_1.Inject)(target_resolver_1.AI_TARGET_RESOLVER)),
+    __param(11, (0, common_1.Optional)()),
+    __param(11, (0, common_1.Inject)(ai_options_1.AI_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [ai_config_service_1.AiConfigService,
+        provider_registry_1.AiProviderRegistry,
+        usable_models_service_1.UsableModelsService,
+        ai_key_resolver_service_1.AiKeyResolver, Object, ai_usage_recorder_1.AiUsageRecorder,
+        ai_runs_service_1.AiRunsService,
+        ai_storage_input_resolver_1.AiStorageInputResolver,
+        ai_output_writer_1.AiOutputWriter,
+        ai_limits_service_1.AiLimitsService, Object, Object])
+], AiService);
+// ---- helpers ---------------------------------------------------------------------------
+/**
+ * The model capabilities a request's SHAPE needs. `responses` always; the
+ * rest follow from what the request carries.
+ */
+function requiredCapabilities(req, streaming) {
+    const needed = new Set(['responses']);
+    if (streaming)
+        needed.add('streaming');
+    if (req.structuredOutput)
+        needed.add('structured_output');
+    if (req.reasoning?.effort)
+        needed.add('reasoning');
+    for (const tool of req.tools ?? []) {
+        needed.add(tool.type === 'function' ? 'tools' : 'hosted_tools');
+    }
+    if (Array.isArray(req.input)) {
+        for (const item of req.input) {
+            if (item.type !== 'message')
+                continue;
+            for (const part of item.content) {
+                // A stored object's modality follows its MIME type, not the part's
+                // type; `planStorageInputs` checks it once the row is read.
+                if (part.type !== 'text' && part.storageObjectId !== undefined)
+                    continue;
+                if (part.type === 'image')
+                    needed.add('vision_input');
+                if (part.type === 'file')
+                    needed.add('file_input');
+            }
+        }
+    }
+    return [...needed];
+}
+/**
+ * The effective `maxOutputTokens`: the caller's value bounded by the
+ * deployment cap and the model's own limit. With no caller value, the
+ * deployment cap still bounds the call (it "bounds every call"); the model's
+ * limit alone does not invent one.
+ */
+function clampOutputTokens(requested, deploymentCap, modelMax) {
+    if (requested !== undefined && (!Number.isInteger(requested) || requested < 1)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'maxOutputTokens must be a positive integer.', {
+            details: { maxOutputTokens: requested },
+        });
+    }
+    const bounds = [requested ?? deploymentCap, deploymentCap, modelMax].filter((value) => value !== undefined);
+    if (requested === undefined && deploymentCap === undefined) {
+        return undefined;
+    }
+    return Math.min(...bounds);
+}
+/**
+ * An embedding request's shape, checked before any gate reads a table: 1 to
+ * `AI_EMBEDDINGS_MAX_INPUTS` non-empty texts, and a positive integer
+ * `dimensions` when given. An oversized batch is refused, never split — the
+ * caller decides how to chunk (and, for a backfill, queues its own job).
+ */
+function assertEmbeddingShape(req) {
+    const inputs = typeof req.input === 'string' ? [req.input] : req.input;
+    if (!Array.isArray(inputs) || inputs.length === 0) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'Embeddings need at least one input text.');
+    }
+    if (inputs.length > media_types_1.AI_EMBEDDINGS_MAX_INPUTS) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `At most ${media_types_1.AI_EMBEDDINGS_MAX_INPUTS} inputs per embeddings call; split the batch into chunks ` +
+            '(for a large backfill, enqueue a job that embeds one chunk at a time).', { details: { inputs: inputs.length, max: media_types_1.AI_EMBEDDINGS_MAX_INPUTS } });
+    }
+    const empty = inputs.findIndex((text) => typeof text !== 'string' || text.length === 0);
+    if (empty !== -1) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'Embedding inputs must be non-empty strings.', {
+            details: { index: empty },
+        });
+    }
+    if (req.dimensions !== undefined && (!Number.isInteger(req.dimensions) || req.dimensions < 1)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'dimensions must be a positive integer.', {
+            details: { dimensions: req.dimensions },
+        });
+    }
+}
+/**
+ * An image request's shape, checked before any gate reads a table: a
+ * non-empty prompt within `AI_IMAGE_PROMPT_MAX_CHARS`, `n` in 1-4, and — for
+ * an edit — 1 to `AI_IMAGE_EDIT_MAX_INPUTS` distinct source images.
+ */
+function assertImageShape(req, edit) {
+    if (typeof req.prompt !== 'string' || req.prompt.trim().length === 0) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'An image request needs a non-empty prompt.');
+    }
+    if (req.prompt.length > media_types_1.AI_IMAGE_PROMPT_MAX_CHARS) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `The prompt is longer than ${media_types_1.AI_IMAGE_PROMPT_MAX_CHARS} characters.`, {
+            details: { max: media_types_1.AI_IMAGE_PROMPT_MAX_CHARS },
+        });
+    }
+    if (req.n !== undefined && (!Number.isInteger(req.n) || req.n < 1 || req.n > media_types_1.AI_IMAGES_MAX_N)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `n must be an integer from 1 to ${media_types_1.AI_IMAGES_MAX_N}.`, {
+            details: { n: req.n, max: media_types_1.AI_IMAGES_MAX_N },
+        });
+    }
+    if (!edit)
+        return;
+    const ids = req.imageStorageObjectIds;
+    if (!Array.isArray(ids) || ids.length === 0 || ids.length > media_types_1.AI_IMAGE_EDIT_MAX_INPUTS) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `An image edit needs 1 to ${media_types_1.AI_IMAGE_EDIT_MAX_INPUTS} source images (imageStorageObjectIds).`, { details: { max: media_types_1.AI_IMAGE_EDIT_MAX_INPUTS } });
+    }
+    if (new Set(ids).size !== ids.length) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'imageStorageObjectIds must not repeat an id.');
+    }
+}
+/** Every image/file part of `input` that names a storage object, in order. */
+function storageParts(input) {
+    if (!Array.isArray(input))
+        return [];
+    const parts = [];
+    for (const item of input) {
+        if (item.type !== 'message')
+            continue;
+        for (const part of item.content) {
+            if (part.type !== 'text' && part.storageObjectId !== undefined)
+                parts.push(part);
+        }
+    }
+    return parts;
+}
+/**
+ * A storage failure while preparing or reading an input, as an `AiError`:
+ * the input resolver's own `AiError` (a too-large stream) unchanged,
+ * unconfigured storage (and a vanished object) as `aiErrorFromStorage` maps
+ * them, anything else `AI_STORAGE_UNAVAILABLE`. Never the URL.
+ */
+function storageInputFailure(err) {
+    if (err instanceof ai_error_1.AiError)
+        return err;
+    return ((0, ai_storage_errors_1.aiErrorFromStorage)(err) ??
+        new ai_error_1.AiError('AI_STORAGE_UNAVAILABLE', 'A stored input could not be read from object storage.', { cause: err }));
+}
+/** `{ images: n }` for the hosted images a response generated, or nothing when it drew none. */
+function hostedImageUnits(response) {
+    const images = response.output.filter((item) => item.type === 'hosted_tool_call' && item.tool === 'image_generation' && !!item.result?.image).length;
+    return images > 0 ? { images } : undefined;
+}
+/**
+ * The storage folder for a response's hosted outputs outside a background
+ * run: the provider's response id, reduced to key-safe characters, or a fresh
+ * id when there is none.
+ */
+function outputFolder(responseId) {
+    const safe = (responseId ?? '').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 128);
+    return safe || (0, node_crypto_1.randomUUID)();
+}
+/**
+ * A transcription request's shape, checked before any gate reads a table: a
+ * storage object id, an ISO-639 language code, a prompt within
+ * `AI_TRANSCRIPTION_PROMPT_MAX_CHARS`, and known, distinct timestamp
+ * granularities.
+ */
+function assertTranscriptionShape(req) {
+    if (typeof req.storageObjectId !== 'string' || req.storageObjectId.trim().length === 0) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'A transcription needs the recording\'s storageObjectId.');
+    }
+    if (req.language !== undefined && !ai_audio_run_request_1.AI_LANGUAGE_CODE.test(req.language)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'language must be an ISO-639-1 code such as "en".', {
+            details: { language: req.language },
+        });
+    }
+    if (req.prompt !== undefined && (req.prompt.length === 0 || req.prompt.length > media_types_1.AI_TRANSCRIPTION_PROMPT_MAX_CHARS)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `prompt must be 1 to ${media_types_1.AI_TRANSCRIPTION_PROMPT_MAX_CHARS} characters.`, {
+            details: { max: media_types_1.AI_TRANSCRIPTION_PROMPT_MAX_CHARS },
+        });
+    }
+    if (req.providerOptions !== undefined)
+        assertProviderOptionsShape(req.providerOptions);
+    const granularities = req.timestampGranularities;
+    if (granularities !== undefined &&
+        (!Array.isArray(granularities) ||
+            granularities.length === 0 ||
+            new Set(granularities).size !== granularities.length ||
+            granularities.some((g) => !media_types_1.AI_TRANSCRIPTION_TIMESTAMP_GRANULARITIES.includes(g)))) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `timestampGranularities must be distinct values of ${media_types_1.AI_TRANSCRIPTION_TIMESTAMP_GRANULARITIES.join(', ')}.`);
+    }
+}
+/**
+ * `providerOptions` must be a plain JSON object of at most
+ * `AI_PROVIDER_OPTIONS_MAX_BYTES` serialised bytes (PP-14.17, #935). The
+ * error names the limit and never the value: the options are passed to the
+ * adapter and nothing else.
+ */
+function assertProviderOptionsShape(options) {
+    let size = Number.POSITIVE_INFINITY;
+    if (typeof options === 'object' && options !== null && !Array.isArray(options)) {
+        try {
+            size = Buffer.byteLength(JSON.stringify(options), 'utf8');
+        }
+        catch {
+            // Not JSON (a cycle, a bigint): stays infinite.
+        }
+    }
+    if (size > media_types_1.AI_PROVIDER_OPTIONS_MAX_BYTES) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `providerOptions must be a JSON object of at most ${media_types_1.AI_PROVIDER_OPTIONS_MAX_BYTES} bytes.`, { details: { max: media_types_1.AI_PROVIDER_OPTIONS_MAX_BYTES } });
+    }
+}
+/** The optional, provider-facing fields of a transcription request (named fields only). */
+function transcriptionFields(req) {
+    return {
+        ...(req.language !== undefined ? { language: req.language } : {}),
+        ...(req.prompt !== undefined ? { prompt: req.prompt } : {}),
+        ...(req.timestampGranularities !== undefined ? { timestampGranularities: [...req.timestampGranularities] } : {}),
+        ...(req.providerOptions !== undefined ? { providerOptions: req.providerOptions } : {}),
+    };
+}
+/**
+ * A speech request's shape, checked before any gate reads a table: 1 to
+ * `AI_SPEECH_INPUT_MAX_CHARS` characters of input, a non-empty voice when
+ * given, a known format, instructions within their limit, and a speed in
+ * range.
+ */
+/**
+ * A realtime request's shape, checked before any gate reads a table:
+ * instructions within `AI_REALTIME_INSTRUCTIONS_MAX_CHARS`, and only function
+ * tools (a hosted tool has no meaning in a browser-held session).
+ */
+function assertRealtimeShape(req) {
+    if (req.instructions !== undefined && req.instructions.length > media_types_1.AI_REALTIME_INSTRUCTIONS_MAX_CHARS) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Realtime instructions may be at most ${media_types_1.AI_REALTIME_INSTRUCTIONS_MAX_CHARS} characters.`);
+    }
+    if (req.tools?.some((tool) => tool.type !== 'function')) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'A realtime session takes function tools only.');
+    }
+}
+function assertSpeechShape(req) {
+    if (typeof req.input !== 'string' || req.input.trim().length === 0) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'Speech needs non-empty input text.');
+    }
+    if (req.input.length > media_types_1.AI_SPEECH_INPUT_MAX_CHARS) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Speech input is longer than ${media_types_1.AI_SPEECH_INPUT_MAX_CHARS} characters; split the text into several runs.`, { details: { length: req.input.length, max: media_types_1.AI_SPEECH_INPUT_MAX_CHARS } });
+    }
+    if (req.voice !== undefined && (typeof req.voice !== 'string' || req.voice.trim().length === 0 || req.voice.length > 64)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', 'voice must be a voice name.');
+    }
+    if (req.format !== undefined && !media_types_1.AI_SPEECH_FORMATS.includes(req.format)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `format must be one of ${media_types_1.AI_SPEECH_FORMATS.join(', ')}.`, {
+            details: { format: req.format },
+        });
+    }
+    if (req.instructions !== undefined &&
+        (req.instructions.length === 0 || req.instructions.length > media_types_1.AI_SPEECH_INSTRUCTIONS_MAX_CHARS)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `instructions must be 1 to ${media_types_1.AI_SPEECH_INSTRUCTIONS_MAX_CHARS} characters.`);
+    }
+    if (req.speed !== undefined &&
+        !(typeof req.speed === 'number' && req.speed >= media_types_1.AI_SPEECH_SPEED_MIN && req.speed <= media_types_1.AI_SPEECH_SPEED_MAX)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `speed must be from ${media_types_1.AI_SPEECH_SPEED_MIN} to ${media_types_1.AI_SPEECH_SPEED_MAX}.`, {
+            details: { speed: req.speed },
+        });
+    }
+}
+/** The optional, provider-facing fields of a speech request (named fields only). */
+function speechFields(req) {
+    return {
+        ...(req.instructions !== undefined ? { instructions: req.instructions } : {}),
+        ...(req.speed !== undefined ? { speed: req.speed } : {}),
+        ...(req.providerOptions !== undefined ? { providerOptions: req.providerOptions } : {}),
+    };
+}
+/** The outcome of a round-trip that threw. An abort is a cancellation, not a failure. */
+/**
+ * Whether `value`, serialised, contains `apiKey`: a custom operation's output
+ * must never echo the key it was called under (PP-14.17, #935). The keyless
+ * marker and an empty key are not secrets.
+ */
+function containsKey(value, apiKey) {
+    if (!apiKey || apiKey === provider_adapter_interface_1.AI_KEYLESS_API_KEY)
+        return false;
+    let serialised;
+    try {
+        serialised = JSON.stringify(value);
+    }
+    catch {
+        return true; // not serialisable: refuse rather than guess
+    }
+    return serialised !== undefined && (serialised.includes(apiKey) || serialised.includes(JSON.stringify(apiKey).slice(1, -1)));
+}
+/**
+ * `error`, or a generic error of the same code when its message or details
+ * carry `apiKey`. A custom operation's handler is app code, trusted less than
+ * the built-in adapters, and an error is the likeliest place a key leaks.
+ */
+function scrubKey(error, apiKey) {
+    if (!containsKey({ message: error.message, body: error.toJSON() }, apiKey))
+        return error;
+    return new ai_error_1.AiError(error.code, 'The provider call failed.', {
+        ...(error.retryAfterMs !== undefined ? { retryAfterMs: error.retryAfterMs } : {}),
+    });
+}
+function failure(error, signal) {
+    return signal?.aborted
+        ? { status: 'cancelled', errorCode: error.code }
+        : { status: 'failed', errorCode: error.code };
+}
+function capabilityUnsupported(provider, model, capability) {
+    return new ai_error_1.AiError('AI_CAPABILITY_UNSUPPORTED', `Model "${model}" does not support ${capability}.`, {
+        details: { provider, model, capability },
+    });
+}
+function cancelled(provider) {
+    return new ai_error_1.AiError('AI_PROVIDER_UNAVAILABLE', 'The AI request was cancelled.', {
+        details: { provider, aborted: true },
+    });
+}
+/**
+ * Normalises anything a provider call threw. An abort is reported as a
+ * cancellation (never as the raw `AbortError`), everything else via
+ * `AiError.wrap` — so nothing raw escapes the facade.
+ */
+function toAiError(err, signal) {
+    if (err instanceof ai_error_1.AiError)
+        return err;
+    if (signal?.aborted) {
+        return new ai_error_1.AiError('AI_PROVIDER_UNAVAILABLE', 'The AI request was cancelled.', {
+            cause: err,
+            details: { aborted: true },
+        });
+    }
+    return ai_error_1.AiError.wrap(err);
+}
+/** What of a responses request the opt-in debug line shows. */
+function responsePrompt(req) {
+    return { instructions: req.instructions, input: req.input };
+}
+/** Prompt text for the opt-in debug log line, truncated. Never the key. */
+function promptPreview(content) {
+    const text = JSON.stringify(content);
+    return text.length > exports.AI_PROMPT_LOG_MAX_CHARS
+        ? `${text.slice(0, exports.AI_PROMPT_LOG_MAX_CHARS)}… (truncated)`
+        : text;
+}
+/**
+ * Refuses a model that does not fit the feature a call is made for (#739):
+ * a missing `needs` capability or input modality, or a provider outside the
+ * feature's allow-list. AI_INVALID_REQUEST, naming what is missing.
+ */
+function assertFeatureFits(feature, provider, model, capabilities) {
+    if (!feature)
+        return;
+    if (feature.providers && !feature.providers.includes(provider)) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `AI feature "${feature.id}" does not run on provider "${provider}".`, { details: { feature: feature.id, provider, model, allowedProviders: [...feature.providers] } });
+    }
+    const missing = feature.needs.filter((need) => !capabilities.capabilities.includes(need));
+    const missingModalities = (feature.inputModalities ?? []).filter((modality) => !capabilities.inputModalities.includes(modality));
+    if (missing.length > 0 || missingModalities.length > 0) {
+        throw new ai_error_1.AiError('AI_INVALID_REQUEST', `Model "${model}" does not have what AI feature "${feature.id}" needs.`, {
+            details: {
+                feature: feature.id,
+                provider,
+                model,
+                ...(missing.length > 0 ? { missingCapabilities: missing } : {}),
+                ...(missingModalities.length > 0 ? { missingInputModalities: missingModalities } : {}),
+            },
+        });
+    }
+}
+//# sourceMappingURL=ai.service.js.map