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

package/dist/ai/ai.system-settings.js

@@ -0,0 +1,309 @@
+"use strict";
+// =============================================================================
+// System settings namespace `ai` (issue #677; namespace #423, epic #419, umbrella #418)
+// =============================================================================
+//
+// A declaration file: pure data, imports only leaf modules. Registered by
+// `settings/registry/system-settings.manifest.ts`. Recipe:
+// `settings/registry/README.md`.
+//
+// NO API KEY HERE, AND THERE NEVER MAY BE ONE: a user's own key is
+// `UserAiKey.secret`, in its own table; an org-wide fallback key belongs in the
+// encrypted credential store. Proved at compile time in
+// `common/schemas/settings.schema.ts` (`AI_SETTINGS_CARRIES_NO_SECRET`) and at
+// import time by the registry.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_SYSTEM_SETTINGS = void 0;
+const common_1 = require("@nestjs/common");
+const ai_1 = require("@marinoscar/platform-contract/ai");
+const ai_2 = require("@marinoscar/platform-contract/ai");
+const ai_3 = require("@marinoscar/platform-contract/ai");
+const index_1 = require("../core/index");
+const index_2 = require("../settings/index");
+const ai_provider_definition_1 = require("./providers/ai-provider-definition");
+// Registers the five built-in providers (side effect): the namespace below reads the registry.
+require("./providers/builtin-ai-providers");
+// OFF, and INERT: `enabled: false` is the point, matching every other feature
+// namespace that ships ahead of its own UI (`databaseBackup.enabled`,
+// `nodes.jobSecretBrokerEnabled`) — a fresh deployment does not gain an AI
+// capability nobody asked for by this namespace merely existing. `byok` is the
+// default key policy: every call uses its caller's own saved key, with no
+// deployment-wide fallback key to reason about or secure.
+// `allowBackgroundRuns: true` mirrors `jobs.history.purgeEnabled` being the one
+// "on" value in the operations block — the queue is this application's normal
+// way of doing anything that takes a while, and a deployment that has not
+// thought about AI at all should not have quietly disabled that path.
+// `logPromptContent: false` is a deliberate, named privacy default: prompt text
+// may carry a user's own sensitive input, and it must not land in a log line
+// nobody scoped for that.
+const AI_SYSTEM_DEFAULTS = {
+    enabled: false,
+    keyPolicy: 'byok',
+    providers: {
+        openai: {
+            enabled: false,
+        },
+        // #446 — off, like every provider slot: enabling one is an
+        // administrator's decision, made alongside its key.
+        anthropic: {
+            enabled: false,
+        },
+        // #447 — off, like every provider slot.
+        gemini: {
+            enabled: false,
+        },
+        // #448 — off, and with no endpoint: each needs a `baseUrl` before it can
+        // be enabled. Every other field is optional and absent means its default.
+        'azure-openai': {
+            enabled: false,
+        },
+        'openai-compatible': {
+            enabled: false,
+        },
+    },
+    defaults: {
+        allowBackgroundRuns: true,
+        // #449: realtime voice sessions OFF — minting one hands the browser an
+        // ephemeral provider secret and the server stops seeing the call.
+        allowRealtime: false,
+    },
+    logPromptContent: false,
+    // #443: `ai_usage_events` kept 180 days — twice the longest usage report
+    // window, so a 90-day report never reads a half-purged range.
+    usageRetentionDays: 180,
+    // #442: every provider-hosted tool OFF — each reaches outside the
+    // deployment and bills per use, so it is an administrator's decision.
+    hostedTools: {
+        web_search: false,
+        file_search: false,
+        code_interpreter: false,
+        image_generation: false,
+        mcp: false,
+        mcpAllowedHosts: [],
+    },
+    // #450: no limits — every field of `ai.limits` is optional and absent
+    // means unlimited, so an upgrade never starts refusing calls by itself.
+    limits: {},
+    // #739: ON — the deployment key keeps serving every organization that has
+    // no key of its own, exactly as before organizations had keys.
+    deploymentKeyServesOrgs: true,
+};
+const logger = new common_1.Logger('AiSettings');
+/**
+ * Each distinct read warning is logged ONCE per process: the namespace is read
+ * on every settings read and every five seconds by the policy cache, and a
+ * stored slot for a provider that is no longer registered stays stored until
+ * the next save.
+ */
+const warnedOnce = new Set();
+function warnOnce(message) {
+    if (warnedOnce.has(message))
+        return;
+    warnedOnce.add(message);
+    logger.warn(message);
+}
+/**
+ * The 400 for a `providers` PATCH or PUT the registry refuses: an id nobody
+ * registered, or settings that do not parse with the provider's own schema.
+ */
+function providerRejection(error) {
+    if (error instanceof index_1.PluggableUnknownError) {
+        throw new common_1.BadRequestException({
+            message: `Unknown AI provider "${error.id}". Registered: ${error.registeredIds.join(', ') || '(none)'}.`,
+            details: { reason: 'AI_UNKNOWN_PROVIDER', provider: error.id },
+        });
+    }
+    if (error instanceof index_1.PluggableSettingsError) {
+        throw new common_1.BadRequestException({
+            message: `The settings for AI provider "${error.id}" are not valid: ${error.message}`,
+            details: {
+                reason: 'AI_PROVIDER_SETTINGS_INVALID',
+                provider: error.id,
+                fields: [...new Set(error.issues.map((issue) => String(issue.path[0] ?? '')))].filter(Boolean),
+            },
+        });
+    }
+    throw error;
+}
+/**
+ * The `providers` record, validated against the provider registry: every
+ * entry must belong to a registered provider and parse with that provider's
+ * own `settingsSchema` (defaults filled). Used as the stored schema's
+ * `providers` field, so a PUT, and any value that reaches the stored schema,
+ * is checked by the provider that owns each slot.
+ */
+const registeredProvidersSchema = ai_1.systemAiSchema.shape.providers.transform((providers, ctx) => {
+    const next = {};
+    for (const [id, slot] of Object.entries(providers)) {
+        try {
+            next[id] = ai_provider_definition_1.aiProviderKind.parseSettings(id, slot);
+        }
+        catch (error) {
+            if (!(error instanceof index_1.PluggableUnknownError) && !(error instanceof index_1.PluggableSettingsError))
+                throw error;
+            ctx.addIssue({ code: 'custom', message: error.message, path: [id] });
+        }
+    }
+    return next;
+});
+/**
+ * The stored `ai` schema the settings registry uses: `systemAiSchema` with
+ * `providers` checked against the provider registry (which the contract
+ * package cannot see).
+ */
+const storedAiSchema = ai_1.systemAiSchema.extend({ providers: registeredProvidersSchema });
+/**
+ * `stored` (the raw `ai` namespace) with `providers` rebuilt from the
+ * provider registry — each REGISTERED provider's slot that parses with its
+ * own settings schema is kept, any other falls back to that provider's
+ * defaults, and a stored slot for a provider that is no longer registered is
+ * dropped with one warning — and `defaults` rebuilt field by field the same
+ * way (#449). Everything else in the namespace is left for `readNamespace` to
+ * salvage as usual.
+ *
+ * Why: a provider registered after a row was written (a built-in appended
+ * later, `anthropic` #446 and `gemini` #447; an app's own, PP-14.6) is absent
+ * from that row, and validating `providers` as one unit would then reset the
+ * operator's OpenAI switch and endpoint to the defaults on the first read
+ * after upgrading. Removing a provider's definition must not brick the row
+ * either, so its stored slot is ignored, never an error. `defaults` gets the
+ * same treatment, field by field, so a field appended to it later
+ * (`allowRealtime`, #449) cannot reset a stored `maxOutputTokensCap` or
+ * `allowBackgroundRuns` beside it.
+ */
+function withAiSlots(stored, helpers) {
+    // A missing or unusable namespace reads as an empty one: every registered
+    // provider still gets its default slot (the static defaults know only the built-ins).
+    const source = helpers.asPlainObject(stored) ?? {};
+    const known = ai_provider_definition_1.aiProviderKind.readSettingsRecord(helpers.asPlainObject(source.providers) ?? {}, warnOnce);
+    const storedDefaults = helpers.asPlainObject(source.defaults);
+    return {
+        ...source,
+        // Registered order (the built-ins first), every registered provider present.
+        providers: Object.fromEntries(ai_provider_definition_1.aiProviderKind.ids().map((id) => [id, known[id] ?? (0, ai_provider_definition_1.defaultAiProviderSlot)(id)])),
+        ...(storedDefaults
+            ? {
+                // An absent optional field (`maxOutputTokensCap`) stays absent.
+                defaults: Object.fromEntries(Object.entries(helpers.readNamespace(storedDefaults, ai_1.systemAiSchema.shape.defaults, AI_SYSTEM_DEFAULTS.defaults)).filter(([, value]) => value !== undefined)),
+            }
+            : {}),
+    };
+}
+/**
+ * PATCH merge of `providers`: for each provider the patch names, `undefined`
+ * keeps a setting, `null` removes it (back to the provider's default) and
+ * anything else replaces it; the result is validated with that provider's own
+ * schema (`mergeSettingsRecord`). A provider the patch does not name keeps its
+ * stored slot. An unregistered id, or settings that do not parse, are a 400.
+ */
+function mergeProviders(current, patch) {
+    const stored = structuredClone(current);
+    if (!patch)
+        return stored;
+    const cleaned = {};
+    for (const [id, slotPatch] of Object.entries(patch)) {
+        const kept = {};
+        for (const [field, value] of Object.entries(slotPatch)) {
+            if (value === undefined)
+                continue;
+            if (value === null) {
+                // Drop the stored value so the default applies; the merge below cannot "unset" a key.
+                if (stored[id])
+                    delete stored[id][field];
+                continue;
+            }
+            kept[field] = value;
+        }
+        cleaned[id] = kept;
+    }
+    try {
+        return ai_provider_definition_1.aiProviderKind.mergeSettingsRecord(stored, cleaned);
+    }
+    catch (error) {
+        return providerRejection(error);
+    }
+}
+/**
+ * Exported for the reference app's wiring and tests (route discovery, contract
+ * and egress suites); not part of the slice's documented surface.
+ *
+ * @internal
+ */
+exports.AI_SYSTEM_SETTINGS = {
+    key: 'ai',
+    description: 'Deployment-wide AI platform policy: the kill switch, key policy, provider slots, call defaults, hosted tools and limits.',
+    storedSchema: storedAiSchema,
+    patchSchema: ai_1.systemAiPatchSchema,
+    putSchema: ai_2.aiSettingsSchema,
+    wirePatchSchema: ai_2.aiSettingsPatchSchema,
+    responseSchema: ai_3.aiResponseSchema,
+    defaults: AI_SYSTEM_DEFAULTS,
+    requiredOnPut: false,
+    // A damaged `providers` block degrading to the default leaves `enabled`
+    // and `logPromptContent` next to it untouched — the same field-by-field
+    // salvage every namespace gets — and `providers` is salvaged one level
+    // deeper, per provider, first (`withAiSlots`).
+    read(stored, helpers) {
+        return helpers.readNamespace(withAiSlots(stored, helpers), storedAiSchema, AI_SYSTEM_DEFAULTS);
+    },
+    merge(current, patch) {
+        // Field by field, one level deep into each `providers.<id>` and
+        // `defaults`, exactly matching `storage`'s own shape. `??` is right for
+        // every REQUIRED field: none of them is nullable, and `??` leaves an
+        // omitted field at its current stored value.
+        //
+        // The OPTIONAL fields (`baseUrl`, `maxOutputTokensCap`, …) take the
+        // `storage.forcePathStyle` form instead (`mergeOptional`): absent keeps
+        // the stored value, explicit `null` REMOVES it. With `??` a null would
+        // fall through to the stored value and an override, once set, could never
+        // be cleared (#428).
+        //
+        // NOTHING HERE TOUCHES AN API KEY. There is no such field on this DTO,
+        // this stored value, or this merge.
+        return {
+            enabled: patch?.enabled ?? current.enabled,
+            keyPolicy: patch?.keyPolicy ?? current.keyPolicy,
+            providers: mergeProviders(current.providers, patch?.providers),
+            defaults: {
+                maxOutputTokensCap: (0, index_2.mergeOptional)(patch?.defaults?.maxOutputTokensCap, current.defaults.maxOutputTokensCap),
+                allowBackgroundRuns: patch?.defaults?.allowBackgroundRuns ?? current.defaults.allowBackgroundRuns,
+                allowRealtime: patch?.defaults?.allowRealtime ?? current.defaults.allowRealtime,
+            },
+            logPromptContent: patch?.logPromptContent ?? current.logPromptContent,
+            usageRetentionDays: patch?.usageRetentionDays ?? current.usageRetentionDays,
+            // #442: each switch field by field; the host list replaces wholesale
+            // (a merge could never remove a host). A fresh array either way, so
+            // the stored value never aliases the caller's or the default's.
+            hostedTools: {
+                web_search: patch?.hostedTools?.web_search ?? current.hostedTools.web_search,
+                file_search: patch?.hostedTools?.file_search ?? current.hostedTools.file_search,
+                code_interpreter: patch?.hostedTools?.code_interpreter ?? current.hostedTools.code_interpreter,
+                image_generation: patch?.hostedTools?.image_generation ?? current.hostedTools.image_generation,
+                mcp: patch?.hostedTools?.mcp ?? current.hostedTools.mcp,
+                mcpAllowedHosts: [...(patch?.hostedTools?.mcpAllowedHosts ?? current.hostedTools.mcpAllowedHosts)],
+            },
+            // #450: WHOLESALE — a present `limits` is the new value, an absent
+            // one keeps the stored value. A merge could never lift a limit (or
+            // drop a per-model entry), and absent is how a limit is lifted.
+            // Cloned either way so the stored value never aliases the caller's
+            // object or the module-level default.
+            limits: structuredClone(patch?.limits ?? current.limits),
+            deploymentKeyServesOrgs: patch?.deploymentKeyServesOrgs ?? current.deploymentKeyServesOrgs,
+        };
+    },
+    // #739: the org layer. An organization may only TIGHTEN the deployment's
+    // policy (`tightenAiPolicy`): AI off for its members, `byok` instead of
+    // `byok_with_org_fallback`, lower per-org daily caps, providers off.
+    org: {
+        schema: ai_1.orgAiSettingsSchema,
+        // Typed `unknown` in, so the declaration also fits the registry's
+        // `SystemSettingsNamespace<string, unknown>` list (parameters are
+        // contravariant); the registry hands in the salvaged value and the
+        // org's validated fields.
+        merge: (system, org) => (0, ai_1.tightenAiPolicy)(system, org),
+        readPermission: 'org_ai_config:read',
+        writePermission: 'org_ai_config:write',
+    },
+};
+//# sourceMappingURL=ai.system-settings.js.map

package/dist/ai/ai.system-settings.js.map

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

package/dist/ai/ai.user-settings.d.ts

@@ -0,0 +1,67 @@
+import { type UserAiSettingsPatchValue, type UserAiSettingsValue } from '@marinoscar/platform-contract/ai';
+/**
+ * Exported for the reference app's wiring and tests (route discovery, contract
+ * and egress suites); not part of the slice's documented surface.
+ *
+ * @internal
+ */
+export declare const AI_USER_SETTINGS: {
+    key: "ai";
+    description: string;
+    schema: import("zod").ZodObject<{
+        defaultModel: import("zod").ZodNullable<import("zod").ZodObject<{
+            provider: import("zod").ZodString;
+            modelId: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    patchSchema: import("zod").ZodObject<{
+        defaultModel: import("zod").ZodNullable<import("zod").ZodObject<{
+            provider: import("zod").ZodString;
+            modelId: import("zod").ZodString;
+        }, import("zod/v4/core").$strip>>;
+    }, import("zod/v4/core").$strip>;
+    responseSchema: null;
+    /**
+     * Merge the `ai` namespace (#423, epic #419, umbrella #418).
+     *
+     * - patch absent  → keep the stored namespace untouched
+     * - patch is `null` → clear the whole namespace (back to "no default
+     *   model chosen", the same state an untouched account is in)
+     * - patch is an object → REPLACES the namespace wholesale. Unlike
+     *   `dataTables`/`navigation`, there is only one field
+     *   (`defaultModel`, a single (provider, modelId) pair) and
+     *   `userAiSettingsPatchSchema` makes it REQUIRED-BUT-NULLABLE, not
+     *   independently optional — so whenever a caller sends `ai` at all, it
+     *   already states the field in full (an object, or `null` to clear just
+     *   the selection while keeping the namespace present). There is no
+     *   "field omitted" case to merge field-by-field the way
+     *   `navigation.railCollapsed` has.
+     */
+    merge(current: UserAiSettingsValue | undefined, patch: UserAiSettingsPatchValue | null | undefined): {
+        defaultModel: {
+            provider: string;
+            modelId: string;
+        } | null;
+    } | undefined;
+};
+declare module '../settings/index' {
+    interface UserSettingsNamespaces {
+        /**
+         * AI preferences (#423, epic #419, umbrella #418): which (provider, model)
+         * an AI surface should pre-select. Absent means "no default model chosen"
+         * — the same sparse-optional contract every namespace follows, so an
+         * untouched account is not materialised with a preference nobody set.
+         */
+        ai: UserAiSettingsValue;
+    }
+    interface UserSettingsNamespaceDeclarations {
+        /**
+         * The `ai` namespace's declaration (`AI_USER_SETTINGS`), for the composed
+         * schemas' types. Documented on the constant itself.
+         *
+         * @internal
+         */
+        ai: typeof AI_USER_SETTINGS;
+    }
+}
+//# sourceMappingURL=ai.user-settings.d.ts.map

package/dist/ai/ai.user-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.user-settings.d.ts","sourceRoot":"","sources":["../../src/ai/ai.user-settings.ts"],"names":[],"mappings":"AAaA,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACzB,MAAM,kCAAkC,CAAC;AAG1C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;IAe3B;;;;;;;;;;;;;;;OAeG;mBACY,mBAAmB,GAAG,SAAS,SAAS,wBAAwB,GAAG,IAAI,GAAG,SAAS;;;;;;CAWd,CAAC;AAEvF,OAAO,QAAQ,mBAAmB,CAAC;IACjC,UAAU,sBAAsB;QAC9B;;;;;WAKG;QACH,EAAE,EAAE,mBAAmB,CAAC;KACzB;IACD,UAAU,iCAAiC;QACzC;;;;;WAKG;QACH,EAAE,EAAE,OAAO,gBAAgB,CAAC;KAC7B;CACF"}

package/dist/ai/ai.user-settings.js

@@ -0,0 +1,64 @@
+"use strict";
+// =============================================================================
+// User settings namespace `ai` (issue #677; namespace #423, epic #419, umbrella #418)
+// =============================================================================
+//
+// Declaration file: pure data, imports only leaf modules. Registered by
+// `settings/registry/user-settings.manifest.ts`. Recipe:
+// `settings/registry/README.md`. The merge moved verbatim from
+// `UserSettingsService.mergeAi`.
+//
+// NON-SECRET ONLY: a user's own provider key is `UserAiKey.secret`, in its own
+// table, never here. See `userAiSettingsSchema` for the full argument.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AI_USER_SETTINGS = void 0;
+const ai_1 = require("@marinoscar/platform-contract/ai");
+/**
+ * Exported for the reference app's wiring and tests (route discovery, contract
+ * and egress suites); not part of the slice's documented surface.
+ *
+ * @internal
+ */
+exports.AI_USER_SETTINGS = {
+    key: 'ai',
+    description: 'Per-user AI preferences: which (provider, model) an AI surface pre-selects.',
+    schema: ai_1.userAiSettingsSchema,
+    // The outer `.nullable()` clears the whole `ai` namespace (back to "no
+    // default model, no other AI preference set"); the inner nullability on
+    // `defaultModel` (see `userAiSettingsPatchSchema`) is what lets
+    // `{ "ai": { "defaultModel": null } }` clear just the selection while
+    // leaving the namespace itself present. Same two-level shape
+    // `dataTablesPatchSchema` uses.
+    patchSchema: ai_1.userAiSettingsPatchSchema,
+    // The documented response (`userSettingsResponseSchema`) has never declared
+    // `ai`, although `GET /api/user-settings` returns it. Kept `null` so the
+    // OpenAPI document is unchanged by #677.
+    responseSchema: null,
+    /**
+     * Merge the `ai` namespace (#423, epic #419, umbrella #418).
+     *
+     * - patch absent  → keep the stored namespace untouched
+     * - patch is `null` → clear the whole namespace (back to "no default
+     *   model chosen", the same state an untouched account is in)
+     * - patch is an object → REPLACES the namespace wholesale. Unlike
+     *   `dataTables`/`navigation`, there is only one field
+     *   (`defaultModel`, a single (provider, modelId) pair) and
+     *   `userAiSettingsPatchSchema` makes it REQUIRED-BUT-NULLABLE, not
+     *   independently optional — so whenever a caller sends `ai` at all, it
+     *   already states the field in full (an object, or `null` to clear just
+     *   the selection while keeping the namespace present). There is no
+     *   "field omitted" case to merge field-by-field the way
+     *   `navigation.railCollapsed` has.
+     */
+    merge(current, patch) {
+        if (patch === undefined) {
+            return current;
+        }
+        if (patch === null) {
+            return undefined;
+        }
+        return { defaultModel: patch.defaultModel };
+    },
+};
+//# sourceMappingURL=ai.user-settings.js.map

package/dist/ai/ai.user-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.user-settings.js","sourceRoot":"","sources":["../../src/ai/ai.user-settings.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,sFAAsF;AACtF,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,yDAAyD;AACzD,+DAA+D;AAC/D,iCAAiC;AACjC,EAAE;AACF,+EAA+E;AAC/E,uEAAuE;AACvE,gFAAgF;;;AAEhF,yDAK0C;AAG1C;;;;;GAKG;AACU,QAAA,gBAAgB,GAAG;IAC9B,GAAG,EAAE,IAAI;IACT,WAAW,EAAE,6EAA6E;IAC1F,MAAM,EAAE,yBAAoB;IAC5B,uEAAuE;IACvE,wEAAwE;IACxE,gEAAgE;IAChE,sEAAsE;IACtE,6DAA6D;IAC7D,gCAAgC;IAChC,WAAW,EAAE,8BAAyB;IACtC,4EAA4E;IAC5E,yEAAyE;IACzE,yCAAyC;IACzC,cAAc,EAAE,IAAI;IACpB;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,OAAwC,EAAE,KAAkD;QAChG,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC;IAC9C,CAAC;CACmF,CAAC"}

package/dist/ai/catalog/ai-catalog-refresh.handler.d.ts

@@ -0,0 +1,34 @@
+import { OnModuleInit } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+import type { Job } from '../../jobs/index';
+import { z } from 'zod';
+import { JobExecutionProfile } from '../../jobs/index';
+import { JobHandler } from '../../jobs/index';
+import { JobHandlerRegistry } from '../../jobs/index';
+import { AiCatalogService } from './ai-catalog.service';
+/** What a refresh job carries. `actorUserId` is present only for an admin-requested refresh. */
+export declare const aiCatalogRefreshPayloadSchema: z.ZodObject<{
+    providerId: z.ZodString;
+    actorUserId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AiCatalogRefreshPayload = z.infer<typeof aiCatalogRefreshPayloadSchema>;
+export declare class AiCatalogRefreshHandler implements JobHandler, OnModuleInit {
+    private readonly registry;
+    private readonly catalog;
+    private readonly events?;
+    private readonly logger;
+    readonly type = "ai.catalog.refresh";
+    readonly label = "AI model catalog refresh";
+    /** One `listModels` round trip plus one transaction: five minutes is generous. */
+    readonly profile: JobExecutionProfile;
+    constructor(registry: JobHandlerRegistry, catalog: AiCatalogService, events?: EventEmitter2 | undefined);
+    onModuleInit(): void;
+    process(job: Job): Promise<void>;
+    /**
+     * The exported hook (`ai-catalog.events.ts`). Wrapped because
+     * `EventEmitter2` dispatches synchronously: a listener that throws must not
+     * turn a committed sync into a failed job.
+     */
+    private emitSynced;
+}
+//# sourceMappingURL=ai-catalog-refresh.handler.d.ts.map

package/dist/ai/catalog/ai-catalog-refresh.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-catalog-refresh.handler.d.ts","sourceRoot":"","sources":["../../../src/ai/catalog/ai-catalog-refresh.handler.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAsB,YAAY,EAAY,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAEL,gBAAgB,EAEjB,MAAM,sBAAsB,CAAC;AAG9B,gGAAgG;AAChG,eAAO,MAAM,6BAA6B;;;iBAGxC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF,qBACa,uBAAwB,YAAW,UAAU,EAAE,YAAY;IAWpE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAZtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;IAEnE,QAAQ,CAAC,IAAI,wBAA2B;IAExC,QAAQ,CAAC,KAAK,8BAA8B;IAE5C,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAgD;gBAGlE,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,gBAAgB,EACb,MAAM,CAAC,EAAE,aAAa,YAAA;IAGrD,YAAY,IAAI,IAAI;IAId,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IA2CtC;;;;OAIG;IACH,OAAO,CAAC,UAAU;CAUnB"}

package/dist/ai/catalog/ai-catalog-refresh.handler.js

@@ -0,0 +1,121 @@
+"use strict";
+// =============================================================================
+// `ai.catalog.refresh` job handler (issue #427, epic #419)
+// =============================================================================
+//
+// Runs `AiCatalogService.sync` for the one provider named in the payload.
+// Enqueued by the daily `AiCatalogRefreshTask` and by the admin "refresh
+// models" route (#428), both with payload `{ providerId }`, subjectType
+// `'ai_provider'`, subjectId `providerId`.
+//
+// SERVER-ONLY, PERMANENTLY. No `nodeResultSchema`/`persistNodeResult`: the
+// sync talks to the provider with the deployment's ADMIN key, and no AI key
+// may ever be brokered to a worker node (docs/specs/ai-platform.md §2.20).
+//
+// KILL SWITCH. When AI (or this provider) has been turned off since the job
+// was queued, the sync reports `skipped` and this handler RETURNS NORMALLY:
+// the platform being off is an expected outcome, not a failure, so it must
+// neither burn an attempt nor fire `jobs.job_failed`.
+//
+// RATE LIMITS. `AiError('AI_RATE_LIMITED')` is rethrown as the queue's
+// `RateLimitError`, so a provider throttle defers the job instead of charging
+// one of its attempts.
+// =============================================================================
+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 AiCatalogRefreshHandler_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AiCatalogRefreshHandler = exports.aiCatalogRefreshPayloadSchema = void 0;
+const common_1 = require("@nestjs/common");
+const event_emitter_1 = require("@nestjs/event-emitter");
+const zod_1 = require("zod");
+const index_1 = require("../../jobs/index");
+const ai_error_1 = require("../core/ai-error");
+const ai_catalog_service_1 = require("./ai-catalog.service");
+const ai_catalog_events_1 = require("./ai-catalog.events");
+/** What a refresh job carries. `actorUserId` is present only for an admin-requested refresh. */
+exports.aiCatalogRefreshPayloadSchema = zod_1.z.object({
+    providerId: zod_1.z.string().min(1),
+    actorUserId: zod_1.z.string().uuid().optional(),
+});
+let AiCatalogRefreshHandler = AiCatalogRefreshHandler_1 = class AiCatalogRefreshHandler {
+    registry;
+    catalog;
+    events;
+    logger = new common_1.Logger(AiCatalogRefreshHandler_1.name);
+    type = ai_catalog_service_1.AI_CATALOG_REFRESH_TYPE;
+    label = 'AI model catalog refresh';
+    /** One `listModels` round trip plus one transaction: five minutes is generous. */
+    profile = { maxRuntimeMs: 5 * 60_000, maxAttempts: 3 };
+    constructor(registry, catalog, events) {
+        this.registry = registry;
+        this.catalog = catalog;
+        this.events = events;
+    }
+    onModuleInit() {
+        this.registry.register(this);
+    }
+    async process(job) {
+        const parsed = exports.aiCatalogRefreshPayloadSchema.safeParse(job.payload);
+        if (!parsed.success) {
+            throw new Error(`Invalid ${ai_catalog_service_1.AI_CATALOG_REFRESH_TYPE} payload: expected { providerId }`);
+        }
+        const { providerId, actorUserId } = parsed.data;
+        let result;
+        try {
+            result = await this.catalog.sync(providerId, { actorUserId, jobId: job.id });
+        }
+        catch (error) {
+            if (error instanceof ai_error_1.AiError) {
+                throw error.toRateLimitError() ?? error;
+            }
+            throw error;
+        }
+        if ((0, ai_catalog_service_1.isCatalogSyncSkipped)(result)) {
+            this.logger.log(`Catalog refresh for "${providerId}" skipped (${result.skipped}); job ${job.id} is a no-op`);
+            return;
+        }
+        this.logger.log(`Catalog refresh for "${providerId}" done: ${result.total} listed, ` +
+            `${result.added} added, ${result.updated} updated, ${result.deprecated} deprecated`);
+        this.emitSynced({
+            providerId,
+            added: result.added,
+            updated: result.updated,
+            deprecated: result.deprecated,
+            jobId: job.id,
+        });
+    }
+    /**
+     * The exported hook (`ai-catalog.events.ts`). Wrapped because
+     * `EventEmitter2` dispatches synchronously: a listener that throws must not
+     * turn a committed sync into a failed job.
+     */
+    emitSynced(event) {
+        try {
+            this.events?.emit(ai_catalog_events_1.AI_CATALOG_SYNCED_EVENT, event);
+        }
+        catch (error) {
+            this.logger.error(`An ${ai_catalog_events_1.AI_CATALOG_SYNCED_EVENT} listener threw for "${event.providerId}"; the sync is ` +
+                `unaffected: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+};
+exports.AiCatalogRefreshHandler = AiCatalogRefreshHandler;
+exports.AiCatalogRefreshHandler = AiCatalogRefreshHandler = AiCatalogRefreshHandler_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(2, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [index_1.JobHandlerRegistry,
+        ai_catalog_service_1.AiCatalogService,
+        event_emitter_1.EventEmitter2])
+], AiCatalogRefreshHandler);
+//# sourceMappingURL=ai-catalog-refresh.handler.js.map

package/dist/ai/catalog/ai-catalog-refresh.handler.js.map

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

package/dist/ai/catalog/ai-catalog-refresh.task.d.ts

@@ -0,0 +1,15 @@
+import { JobsService } from '../../jobs/index';
+import { SystemSettingsService } from '../../settings/index';
+export declare class AiCatalogRefreshTask {
+    private readonly systemSettings;
+    private readonly jobs;
+    private readonly logger;
+    constructor(systemSettings: SystemSettingsService, jobs: JobsService);
+    handleCron(): Promise<void>;
+    /**
+     * The providers a refresh is due for: every enabled provider, and none at
+     * all while the platform's kill switch is off (docs/specs/ai-platform.md §2.19).
+     */
+    dueProviders(): Promise<string[]>;
+}
+//# sourceMappingURL=ai-catalog-refresh.task.d.ts.map

package/dist/ai/catalog/ai-catalog-refresh.task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-catalog-refresh.task.d.ts","sourceRoot":"","sources":["../../../src/ai/catalog/ai-catalog-refresh.task.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,qBACa,oBAAoB;IAI7B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;gBAG7C,cAAc,EAAE,qBAAqB,EACrC,IAAI,EAAE,WAAW;IAI9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA+BjC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;CAaxC"}