@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.5

package/dist/ai/core/provider-adapter.interface.d.ts

@@ -0,0 +1,261 @@
+import type { AiErrorCode } from './ai-error';
+import type { AiModelCapabilities } from './capabilities';
+import type { AiFileInputStrategies, AiResolvedStorageInputs } from './types/file-inputs.types';
+import type { AiAudioPort, AiEmbeddingsPort, AiImagesPort, AiRealtimePort } from './types/media.types';
+import type { AiResponse, AiResponseRequest, AiStreamEvent } from './types/responses.types';
+/**
+ * The `apiKey` a call carries when its provider needs none (#448): an
+ * OpenAI-compatible server the administrator marked `requiresKey: false`.
+ * The key resolver returns it with `keySource: 'none'`, and an adapter that
+ * sees it sends NO credential at all — it is a marker, never put on the wire,
+ * in a log line or in a row.
+ *
+ * @stability experimental
+ */
+export declare const AI_KEYLESS_API_KEY = "not-needed";
+/**
+ * Per-call context. The key is resolved per call by the runtime (org key or
+ * the user's own key, per policy) and handed to the adapter — adapters hold
+ * no credentials of their own.
+ *
+ * ⚠ `apiKey` is secret material: it must never appear in a log line, an
+ * `AiError`'s details, or a persisted row.
+ *
+ * @stability experimental
+ */
+export interface AiCallContext {
+    /** The key this call is made under (`AI_KEYLESS_API_KEY` for a keyless server). ⚠ Secret. */
+    apiKey: string;
+    /** The administrator's endpoint override, when the provider slot carries one. */
+    baseUrl?: string;
+    /**
+     * The provider's other NON-SECRET settings from its `ai.providers.<id>`
+     * slot (#448) — Azure's `apiVersion`/`apiStyle`/`deployments`, an
+     * OpenAI-compatible server's `apiStyle`/`requiresKey` — absent when the
+     * slot carries none. Each adapter reads it with its own schema; the
+     * runtime passes it through without interpreting it.
+     */
+    providerSettings?: Readonly<Record<string, unknown>>;
+    /** Aborts the provider call. */
+    signal?: AbortSignal;
+    /** The request id, for logs and the provider's metadata. */
+    requestId: string;
+    /**
+     * The request's storage-object inputs (#441), resolved and authorised by the
+     * runtime, keyed by `storageObjectId` — present only when the request
+     * carries any. ⚠ May hold presigned URLs: the same never-log rule as
+     * `apiKey` applies (see `types/file-inputs.types.ts`).
+     */
+    storageInputs?: AiResolvedStorageInputs;
+}
+/**
+ * The context a custom operation handler (`AiProviderAdapter.operations`)
+ * receives: the call's {@link AiCallContext} plus the model and operation the
+ * gate pipeline settled. ⚠ `apiKey` is secret material, as everywhere.
+ *
+ * @stability experimental
+ */
+export interface AiOperationContext extends AiCallContext {
+    /** The provider model id the call targets (already gated: enabled, reachable, declares the capability). */
+    readonly model: string;
+    /** The operation id being run (`audio.diarize`). */
+    readonly operation: string;
+}
+/**
+ * A custom operation an adapter implements (PP-14.17, #935): one entry of
+ * `AiProviderAdapter.operations`. The input arrives already validated by the
+ * operation's `inputSchema` (`registerAiOperation`) and the returned value is
+ * validated by its `outputSchema` before it leaves the runtime, so a handler
+ * does neither. It must not log, return or throw the key or the input.
+ *
+ * @param input - the validated input.
+ * @param ctx - the call's key, endpoint, settings, signal, model and operation.
+ * @returns the output, in the shape the operation's `outputSchema` declares.
+ *
+ * @stability experimental
+ */
+export type AiOperationHandler = (input: unknown, ctx: AiOperationContext) => Promise<unknown>;
+/**
+ * What a provider's model listing says about one model, beyond its id
+ * (#447). Every field is optional and PROVIDER-REPORTED: an adapter fills
+ * what its listing carries (Gemini reports token limits, supported methods
+ * and a thinking flag; OpenAI and Anthropic list ids only) and its own
+ * `classifyModel` is the only reader. It is never stored as-is — the
+ * classifier folds it into `AiModelCapabilities`, which is what the catalog
+ * keeps.
+ *
+ * @stability experimental
+ */
+export interface AiDiscoveredModelMetadata {
+    /** The provider's display name for the model. */
+    displayName?: string;
+    /** The most input tokens the provider says the model accepts. */
+    inputTokenLimit?: number;
+    /** The most output tokens the provider says the model produces. */
+    outputTokenLimit?: number;
+    /** Provider-named operations the model supports (Gemini: `generateContent`, `embedContent`, ...). */
+    supportedActions?: string[];
+    /** Whether the provider says the model thinks (extended reasoning). */
+    thinking?: boolean;
+}
+/**
+ * One model of a provider's listing (`listModels`).
+ *
+ * @stability experimental
+ */
+export interface AiDiscoveredModel {
+    /** The provider's model id. */
+    id: string;
+    /** The owner the provider reports. */
+    ownedBy?: string;
+    /** When the provider says the model was published. */
+    createdAt?: Date;
+    /** Optional listing metadata the adapter's `classifyModel` may use (#447). */
+    metadata?: AiDiscoveredModelMetadata;
+}
+/**
+ * The outcome of `verifyKey`. A rejected key is an ordinary answer
+ * (`ok: false, code: 'AI_KEY_INVALID'`), not an exception — the admin UI asks
+ * this question precisely when it expects "no" to be possible.
+ *
+ * @stability experimental
+ */
+export interface AiKeyVerification {
+    /** Whether the provider accepted the key. */
+    ok: boolean;
+    /** Why not (`AI_KEY_INVALID`, `AI_PROVIDER_UNAVAILABLE`, ...). */
+    code?: AiErrorCode;
+    /** A message safe to show (never the key). */
+    detail?: string;
+}
+/**
+ * The responses port a provider adapter implements (`responses` and the
+ * capabilities riding on it).
+ *
+ * @stability experimental
+ */
+export interface AiResponsesPort {
+    /**
+     * One complete response.
+     *
+     * @param req - the request.
+     * @param ctx - the call's key and signal.
+     */
+    create(req: AiResponseRequest, ctx: AiCallContext): Promise<AiResponse>;
+    /**
+     * One streamed response (see `AiStreamEvent` for the well-formedness rules).
+     *
+     * @param req - the request.
+     * @param ctx - the call's key and signal.
+     */
+    stream(req: AiResponseRequest, ctx: AiCallContext): AsyncIterable<AiStreamEvent>;
+}
+/**
+ * A provider adapter: the one place a provider SDK is called
+ * (`ai/providers/<provider>/`). It holds no key; every call receives one in
+ * its {@link AiCallContext}. Its capability ports' presence is the
+ * declaration of what it can do. Adding one: docs/specs/ai-platform.md §4.
+ *
+ * @stability experimental
+ */
+export interface AiProviderAdapter {
+    /** Stable identifier (`'openai'`). PERMANENT — stored in settings, catalog rows and usage rows. */
+    readonly id: string;
+    /** The name the admin UI shows. */
+    readonly displayName: string;
+    /**
+     * The provider's model listing, under the deployment's (or a probe's) key.
+     *
+     * @param ctx - the call's key and signal.
+     */
+    listModels(ctx: AiCallContext): Promise<AiDiscoveredModel[]>;
+    /**
+     * Whether the key in `ctx` works. A rejected key is an answer, not a throw.
+     *
+     * @param ctx - the call's key and signal.
+     */
+    verifyKey(ctx: AiCallContext): Promise<AiKeyVerification>;
+    /**
+     * `null` means "unclassified": the catalog stores it and an admin decides.
+     *
+     * `metadata` (#447) is what this adapter's own `listModels` reported for
+     * the id, passed back by the catalog sync so a classifier can ENRICH its
+     * rule table from provider facts (token limits, supported methods). It is
+     * absent everywhere else — a request-time lookup, a test, an adapter whose
+     * listing carries ids only — so a classifier must answer from the id alone
+     * when it is missing, and an adapter that ignores it stays correct.
+     */
+    classifyModel(modelId: string, metadata?: AiDiscoveredModelMetadata): AiModelCapabilities | null;
+    /**
+     * How this adapter wants storage-object image/file inputs delivered (#441).
+     * Presence is the declaration that it accepts them at all; absent, a
+     * request carrying one is refused with `AI_CAPABILITY_UNSUPPORTED`.
+     */
+    readonly fileInputStrategy?: AiFileInputStrategies;
+    /**
+     * Whether this provider stores responses, so a request may chain onto one
+     * with `AiResponseRequest.previousResponseId` (#446). ABSENT MEANS `true` —
+     * the Responses-shaped default, and what every adapter written before this
+     * flag (OpenAI, the fake provider) already does.
+     *
+     * A stateless provider (Anthropic's Messages API) declares `false`, and the
+     * runtime then:
+     *   - refuses a caller-supplied `previousResponseId` with
+     *     `AI_CAPABILITY_UNSUPPORTED` before any key is resolved (the caller
+     *     must send the conversation as `input` instead);
+     *   - runs the tool loop by RESENDING THE FULL HISTORY each round — the
+     *     original input, the model's own `message`/`reasoning`/`function_call`
+     *     items, and the tool outputs — instead of chaining.
+     *
+     * Unlike a capability port this is a behaviour flag, not a capability: the
+     * conversation still works, it just travels differently.
+     */
+    readonly supportsPreviousResponseId?: boolean;
+    /**
+     * Whether this provider executes the neutral hosted tools (#442: web
+     * search, file search, code interpreter, image generation, MCP) inside a
+     * response. ABSENT MEANS `true` — the pre-flag derivation, and what OpenAI
+     * and the fake provider rely on.
+     *
+     * Why a flag and not a port: hosted tools run INSIDE the `responses` port,
+     * so there is no separate port whose presence could declare them, and
+     * `hosted_tools` used to be derived from the `responses` port alone. A
+     * provider with a responses port but none of these tools (Anthropic, whose
+     * server tools are a different, unmapped set) declares `false`, so
+     * `AiProviderRegistry.supports(id, 'hosted_tools')` — and the admin view's
+     * `supportedCapabilities`, and the usable-models gate — stop claiming a
+     * capability the adapter's mapper would refuse.
+     */
+    readonly supportsHostedTools?: boolean;
+    /**
+     * The endpoint this adapter calls when the provider's settings slot carries
+     * no `baseUrl` (#773): the SDK default it passes to its client factory.
+     * Absent for a provider that has no default (Azure OpenAI and
+     * OpenAI-compatible need an administrator's endpoint). Read by the egress
+     * inventory (`network.egress`) to name the host a provider reaches, without
+     * a hard-coded table outside `ai/providers/`. Never a secret.
+     */
+    readonly defaultBaseUrl?: string;
+    /** Text, reasoning, tools, structured output, streaming, vision and file input. */
+    readonly responses?: AiResponsesPort;
+    /** Image generation (and editing, when `edit` is present). */
+    readonly images?: AiImagesPort;
+    /** Transcription and/or speech. */
+    readonly audio?: AiAudioPort;
+    /** Embeddings. */
+    readonly embeddings?: AiEmbeddingsPort;
+    /** Realtime voice sessions. */
+    readonly realtime?: AiRealtimePort;
+    /**
+     * Custom operations, by operation id (PP-14.17, #935): the way a provider
+     * serves a kind of call the platform has no built-in port for (diarization,
+     * moderation, rerank, OCR). Each key is an id registered with
+     * `registerAiOperation`; `AiService.forUser(...).run(id, input)` runs it
+     * through the same gate pipeline as a built-in port. Presence is the
+     * declaration, as with the ports: the registry derives that the provider
+     * supports the operation's capability from the entry, and a registered
+     * operation the adapter does not implement is refused for it.
+     */
+    readonly operations?: Readonly<Record<string, AiOperationHandler>>;
+}
+//# sourceMappingURL=provider-adapter.interface.d.ts.map

package/dist/ai/core/provider-adapter.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-adapter.interface.d.ts","sourceRoot":"","sources":["../../../src/ai/core/provider-adapter.interface.ts"],"names":[],"mappings":"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"}

package/dist/ai/core/provider-adapter.interface.js

@@ -0,0 +1,33 @@
+"use strict";
+// =============================================================================
+// AI provider adapter contract (issue #424, epic #419)
+// =============================================================================
+//
+// One class per provider implements this and self-registers with
+// `AiProviderRegistry` from its own `onModuleInit()` — the same explicit
+// registration `JobHandler` uses (see `jobs/job-handler.registry.ts` for why
+// explicit registration beats decorator discovery).
+//
+// CAPABILITY PORTS: PRESENCE IS THE DECLARATION. An adapter that can generate
+// images carries an `images` port; one that cannot leaves it `undefined`.
+// There is no `supportsImages: boolean` to disagree with the code — the same
+// idiom as `JobHandler.nodeResultSchema` + `persistNodeResult`.
+// `AiProviderRegistry.supports()` is the derivation.
+//
+// NO SDK TYPE CROSSES THIS BOUNDARY. Every method takes and returns the
+// neutral types in `./types`, and every failure is an `AiError` — an adapter
+// that lets a raw SDK error escape fails the conformance kit.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_KEYLESS_API_KEY = void 0;
+/**
+ * The `apiKey` a call carries when its provider needs none (#448): an
+ * OpenAI-compatible server the administrator marked `requiresKey: false`.
+ * The key resolver returns it with `keySource: 'none'`, and an adapter that
+ * sees it sends NO credential at all — it is a marker, never put on the wire,
+ * in a log line or in a row.
+ *
+ * @stability experimental
+ */
+exports.AI_KEYLESS_API_KEY = 'not-needed';
+//# sourceMappingURL=provider-adapter.interface.js.map

package/dist/ai/core/provider-adapter.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-adapter.interface.js","sourceRoot":"","sources":["../../../src/ai/core/provider-adapter.interface.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,uDAAuD;AACvD,gFAAgF;AAChF,EAAE;AACF,iEAAiE;AACjE,yEAAyE;AACzE,6EAA6E;AAC7E,oDAAoD;AACpD,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,6EAA6E;AAC7E,gEAAgE;AAChE,qDAAqD;AACrD,EAAE;AACF,wEAAwE;AACxE,6EAA6E;AAC7E,8DAA8D;AAC9D,gFAAgF;;;AAahF;;;;;;;;GAQG;AACU,QAAA,kBAAkB,GAAG,YAAY,CAAC"}

package/dist/ai/core/provider-registry.d.ts

@@ -0,0 +1,52 @@
+import { type AiCapability } from './capabilities';
+import { AiProviderAdapter } from './provider-adapter.interface';
+/**
+ * The capabilities an adapter's ports and operations make possible: the
+ * built-in ones in `BUILTIN_AI_CAPABILITIES` order, then the app's in
+ * registration order.
+ *
+ * @stability experimental
+ */
+export declare function adapterCapabilities(adapter: AiProviderAdapter): AiCapability[];
+/**
+ * Every provider adapter this process loaded, by id. Each provider module
+ * registers its adapter at module init; `AiService` and the catalogue look
+ * adapters up here, and `supports()` derives a provider's capabilities from
+ * the ports its adapter carries.
+ *
+ * @stability experimental
+ */
+export declare class AiProviderRegistry {
+    private readonly logger;
+    private readonly adapters;
+    /**
+     * Adds `adapter` under its own `id`. A duplicate id REPLACES the earlier
+     * registration and logs a warning — how a fork overrides a framework
+     * adapter without editing it (see `JobHandlerRegistry.register`).
+     */
+    register(adapter: AiProviderAdapter): void;
+    /** The adapter for `id`, or `undefined` — the caller decides what "unknown" means. */
+    get(id: string): AiProviderAdapter | undefined;
+    /** The adapter for `id`, or `AiError('AI_PROVIDER_DISABLED')` when none is registered. */
+    require(id: string): AiProviderAdapter;
+    /** Every registered provider id, in registration order. */
+    ids(): string[];
+    /** Whether provider `id` implements the port `cap` needs. `false` for an unknown id. */
+    supports(id: string, cap: AiCapability): boolean;
+    /**
+     * Whether provider `id` implements custom operation `operation`
+     * (`AiProviderAdapter.operations`). `false` for an unknown provider.
+     */
+    supportsOperation(id: string, operation: string): boolean;
+    /**
+     * Whether provider `id` can chain a request onto a stored response with
+     * `previousResponseId` (#446) — `AiProviderAdapter.supportsPreviousResponseId`,
+     * absent meaning `true`. An unknown id answers `true`: there is nothing
+     * registered to refuse on its behalf, and the gate pipeline refuses the id
+     * itself.
+     */
+    supportsPreviousResponseId(id: string): boolean;
+    /** Every capability provider `id` supports; empty for an unknown id. */
+    capabilities(id: string): AiCapability[];
+}
+//# sourceMappingURL=provider-registry.d.ts.map

package/dist/ai/core/provider-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.d.ts","sourceRoot":"","sources":["../../../src/ai/core/provider-registry.ts"],"names":[],"mappings":"AAoBA,OAAO,EAA2B,KAAK,YAAY,EAA4B,MAAM,gBAAgB,CAAC;AAGtG,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAgDjE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY,EAAE,CAO9E;AAED;;;;;;;GAOG;AACH,qBACa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAE9D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IAEjE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAc1C,sFAAsF;IACtF,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAI9C,0FAA0F;IAC1F,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB;IActC,2DAA2D;IAC3D,GAAG,IAAI,MAAM,EAAE;IAIf,wFAAwF;IACxF,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO;IAMhD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAMzD;;;;;;OAMG;IACH,0BAA0B,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/C,wEAAwE;IACxE,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,EAAE;CAKzC"}

package/dist/ai/core/provider-registry.js

@@ -0,0 +1,163 @@
+"use strict";
+// =============================================================================
+// AI provider registry (issue #424, epic #419)
+// =============================================================================
+//
+// The one place that knows which AI providers this process can talk to. It
+// mirrors `jobs/job-handler.registry.ts` deliberately — explicit
+// self-registration from each adapter's `onModuleInit()`, last registration
+// wins with a warning — so there is one pattern to learn, not two. Read that
+// file's header for why explicit registration beats decorator discovery.
+//
+// `supports()` is DERIVED from port presence and nothing else. There is no
+// capability list on an adapter to disagree with the code: an adapter that
+// carries an `images` port supports image generation; one that does not,
+// does not. Model-level capability (does THIS model reason?) is a separate
+// question answered by the catalog — see `capabilities.ts`.
+// =============================================================================
+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 AiProviderRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiProviderRegistry = void 0;
+exports.adapterCapabilities = adapterCapabilities;
+const common_1 = require("@nestjs/common");
+const ai_error_1 = require("./ai-error");
+const capabilities_1 = require("./capabilities");
+const capability_registry_1 = require("./capability-registry");
+const operation_registry_1 = require("./operation-registry");
+/**
+ * Which port (and, for optional port members, which method) each capability
+ * needs. The model-level text capabilities all ride on the `responses` port:
+ * at the PROVIDER level, "can this provider reason / call tools / stream" is
+ * the same question as "does it implement the responses port".
+ */
+const CAPABILITY_PORT = {
+    responses: (a) => a.responses !== undefined,
+    reasoning: (a) => a.responses !== undefined,
+    tools: (a) => a.responses !== undefined,
+    // Rides on the responses port, unless the adapter declares it runs none (#446).
+    hosted_tools: (a) => a.responses !== undefined && a.supportsHostedTools !== false,
+    structured_output: (a) => a.responses !== undefined,
+    streaming: (a) => a.responses !== undefined,
+    vision_input: (a) => a.responses !== undefined,
+    file_input: (a) => a.responses !== undefined,
+    image_generation: (a) => a.images !== undefined,
+    image_edit: (a) => typeof a.images?.edit === 'function',
+    audio_transcription: (a) => typeof a.audio?.transcribe === 'function',
+    audio_speech: (a) => typeof a.audio?.speech === 'function',
+    embeddings: (a) => a.embeddings !== undefined,
+    realtime: (a) => a.realtime !== undefined,
+};
+/**
+ * Whether `adapter` serves `cap`. A built-in capability is derived from the
+ * port it needs; an app capability (`registerAiCapability`) from a registered
+ * operation (`registerAiOperation`) the adapter implements under
+ * `AiProviderAdapter.operations` (PP-14.17, #935). Presence is the declaration
+ * either way.
+ */
+function adapterServes(adapter, cap) {
+    if (Object.hasOwn(CAPABILITY_PORT, cap))
+        return CAPABILITY_PORT[cap](adapter);
+    return operationsOf(adapter).some((operation) => (0, operation_registry_1.getAiOperation)(operation)?.capability === cap);
+}
+/** The operation ids `adapter` implements (own, function-valued entries of `operations`). */
+function operationsOf(adapter) {
+    const operations = adapter.operations;
+    if (!operations)
+        return [];
+    return Object.keys(operations).filter((id) => typeof operations[id] === 'function');
+}
+/**
+ * The capabilities an adapter's ports and operations make possible: the
+ * built-in ones in `BUILTIN_AI_CAPABILITIES` order, then the app's in
+ * registration order.
+ *
+ * @stability experimental
+ */
+function adapterCapabilities(adapter) {
+    const builtin = capabilities_1.BUILTIN_AI_CAPABILITIES.filter((cap) => CAPABILITY_PORT[cap](adapter));
+    const custom = (0, capability_registry_1.listAiCapabilities)()
+        .map((definition) => definition.id)
+        .filter((id) => !Object.hasOwn(CAPABILITY_PORT, id) && adapterServes(adapter, id));
+    return [...builtin, ...custom];
+}
+/**
+ * Every provider adapter this process loaded, by id. Each provider module
+ * registers its adapter at module init; `AiService` and the catalogue look
+ * adapters up here, and `supports()` derives a provider's capabilities from
+ * the ports its adapter carries.
+ *
+ * @stability experimental
+ */
+let AiProviderRegistry = AiProviderRegistry_1 = class AiProviderRegistry {
+    logger = new common_1.Logger(AiProviderRegistry_1.name);
+    adapters = new Map();
+    /**
+     * Adds `adapter` under its own `id`. A duplicate id REPLACES the earlier
+     * registration and logs a warning — how a fork overrides a framework
+     * adapter without editing it (see `JobHandlerRegistry.register`).
+     */
+    register(adapter) {
+        const existing = this.adapters.get(adapter.id);
+        if (existing) {
+            this.logger.warn(`Duplicate AI provider adapter for id "${adapter.id}": ` +
+                `${existing.constructor.name} is being replaced by ` +
+                `${adapter.constructor.name}. The last registration wins.`);
+        }
+        this.adapters.set(adapter.id, adapter);
+    }
+    /** The adapter for `id`, or `undefined` — the caller decides what "unknown" means. */
+    get(id) {
+        return this.adapters.get(id);
+    }
+    /** The adapter for `id`, or `AiError('AI_PROVIDER_DISABLED')` when none is registered. */
+    require(id) {
+        const adapter = this.adapters.get(id);
+        if (!adapter) {
+            throw new ai_error_1.AiError('AI_PROVIDER_DISABLED', `AI provider "${id}" is not available in this deployment.`, { details: { provider: id } });
+        }
+        return adapter;
+    }
+    /** Every registered provider id, in registration order. */
+    ids() {
+        return [...this.adapters.keys()];
+    }
+    /** Whether provider `id` implements the port `cap` needs. `false` for an unknown id. */
+    supports(id, cap) {
+        const adapter = this.adapters.get(id);
+        return adapter !== undefined && adapterServes(adapter, cap);
+    }
+    /**
+     * Whether provider `id` implements custom operation `operation`
+     * (`AiProviderAdapter.operations`). `false` for an unknown provider.
+     */
+    supportsOperation(id, operation) {
+        const operations = this.adapters.get(id)?.operations;
+        return operations !== undefined && Object.hasOwn(operations, operation) && typeof operations[operation] === 'function';
+    }
+    /**
+     * Whether provider `id` can chain a request onto a stored response with
+     * `previousResponseId` (#446) — `AiProviderAdapter.supportsPreviousResponseId`,
+     * absent meaning `true`. An unknown id answers `true`: there is nothing
+     * registered to refuse on its behalf, and the gate pipeline refuses the id
+     * itself.
+     */
+    supportsPreviousResponseId(id) {
+        return this.adapters.get(id)?.supportsPreviousResponseId !== false;
+    }
+    /** Every capability provider `id` supports; empty for an unknown id. */
+    capabilities(id) {
+        const adapter = this.adapters.get(id);
+        return adapter ? adapterCapabilities(adapter) : [];
+    }
+};
+exports.AiProviderRegistry = AiProviderRegistry;
+exports.AiProviderRegistry = AiProviderRegistry = AiProviderRegistry_1 = __decorate([
+    (0, common_1.Injectable)()
+], AiProviderRegistry);
+//# sourceMappingURL=provider-registry.js.map

package/dist/ai/core/provider-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-registry.js","sourceRoot":"","sources":["../../../src/ai/core/provider-registry.ts"],"names":[],"mappings":"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"}

package/dist/ai/core/structured-output.d.ts

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+/**
+ * A JSON Schema document, as plain data.
+ *
+ * @stability experimental
+ */
+export type AiJsonSchema = Record<string, unknown>;
+/**
+ * Converts a Zod schema to the JSON Schema a provider is sent.
+ *
+ * Uses zod's OUTPUT view — the shape the model must PRODUCE: every
+ * non-optional key is `required` and objects are closed
+ * (`additionalProperties: false`), which is what strict structured-output
+ * and strict function-calling modes require. The `$schema` marker is dropped
+ * because it describes the document, not the value, and some providers
+ * reject unknown top-level keywords.
+ *
+ * A schema JSON Schema cannot express (a `Date`, a `transform`, a function) is
+ * a programming error in the caller; it surfaces as
+ * `AiError('AI_INVALID_REQUEST')` so it follows the same error path as every
+ * other AI failure instead of escaping as a raw zod error.
+ *
+ * @stability experimental
+ */
+export declare function toJsonSchema(schema: z.ZodTypeAny): AiJsonSchema;
+/**
+ * One validation problem, safe to return to a client (no model output echoed).
+ *
+ * @stability experimental
+ */
+export interface AiStructuredOutputIssue {
+    /** Where in the output the problem is. */
+    path: Array<string | number>;
+    /** Zod's issue code. */
+    code: string;
+    /** What is wrong, in words. */
+    message: string;
+}
+/**
+ * Parses a model's text output and validates it against `schema`.
+ *
+ * Throws `AiError('AI_STRUCTURED_OUTPUT_INVALID')` (502 — the PROVIDER
+ * returned something unusable, not the caller) with the issues in
+ * `details.issues`. The raw text is deliberately NOT included: it is model
+ * output derived from the user's prompt, and error bodies get logged.
+ *
+ * @stability experimental
+ */
+export declare function parseStructured<S extends z.ZodTypeAny>(schema: S, text: string): z.output<S>;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/ai/core/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../../../src/ai/core/structured-output.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,YAAY,CAgB/D;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC7B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAsC5F"}