@capybara-hq/kernel 0.1.0-rc.5 → 0.1.0-rc.6

package/dist/models/embeddings.d.ts

@@ -0,0 +1,82 @@
+import { type ExtensionEmbedRequest, type ExtensionEmbedResult, type ExtensionModelTarget, type ExtensionPermissions, type Logger } from "@capybara-hq/plugin-sdk";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { type HookRunner } from "../runtime/hook-calls.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { ModelPurposesService } from "./purposes.js";
+/** An extension's `permissions.models` (what it declared, as approved in its manifest). */
+export type DeclaredModelPurposes = readonly NonNullable<ExtensionPermissions["models"]>[number][];
+/** Most texts one `ctx.models.embed` call may carry (the kernel splits them by `maxBatch`). */
+export declare const EMBED_MAX_INPUTS = 2048;
+/**
+ * The `ctx.models` broker for embeddings (model platform spec B §5.4). Every call:
+ * - accepts only a purpose the calling extension declared in `permissions.models` with
+ *   `kind: "embedding"` (`model.purpose_unknown` otherwise: the manifest is what was approved), for
+ *   an org that enabled the extension (`extension.not_enabled`);
+ * - resolves the org's effective target ({@link ModelPurposesService.resolve}: unmapped, or mapped
+ *   to a model the org cannot use, is `model.unconfigured`) and the model in the org's view, enabled
+ *   and of kind `embedding` ({@link ProviderRegistry.resolve}, bound to the org's effective config);
+ * - fires `model.request` once (`purpose: "embedding"`, every text of the call, no conversation
+ *   fields) through the host's hook registry before anything is sent; a policy denial (a deny, a
+ *   hook error or timeout, a policy extension not loaded here or without a valid config in the org)
+ *   writes one `hook.denied` audit row and rejects with `ApiError("model.hook_denied")` (403) whose
+ *   message is the one a denied run step fails with: no provider call, no usage row. A call with no input sends nothing
+ *   and fires nothing;
+ * - splits the input into batches of the model's `maxBatch`, calls the provider's `embed` once per
+ *   batch in order with the extension's signal (plus the request's own `signal`), each batch
+ *   limited by `models.embedTimeoutMs` (`ModelError("timeout")`), checks each result ({@link validateEmbedResult}: a
+ *   wrong count, dimension or a non-finite number is a `ModelError` of kind `server`), and
+ *   concatenates the vectors; no retries (an extension retries itself if it wants to);
+ * - writes one `model_usage` row (the sum of the batches' input tokens) and announces it after the
+ *   commit (`model_usage.recorded`: the usage reporter's `ModelUsageJobs` enqueues its
+ *   `usage.report` delivery; the usage sweep catches up a lost one). A call that fails after the
+ *   provider answered some batches (an invalid result, a later batch failing) still records their
+ *   input tokens before the error reaches the extension; one that fails before any answer records
+ *   nothing.
+ * Purpose params are not sent: an `embed` request carries none (`EmbedRequest`).
+ */
+export declare class ModelEmbeddings {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly purposes;
+    private readonly providers;
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    private readonly events;
+    private readonly log;
+    /** `models.embedTimeoutMs` (hot). */
+    private readonly config;
+    constructor(kdb: KernelDb, txHost: TransactionHost, purposes: Pick<ModelPurposesService, "resolve">, providers: Pick<ProviderRegistry, "resolve">, 
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    events: Pick<KernelEvents, "emit">, log: Pick<Logger, "warn">, 
+    /** `models.embedTimeoutMs` (hot). */
+    config: Pick<KernelConfigService, "get">);
+    /** Refuses a purpose `plugin` did not declare with kind `embedding`, or an org it is off in. */
+    private admit;
+    /** The org's target for the purpose and the model bound to the org's config. */
+    private target;
+    /**
+     * One batch to the provider, limited by `models.embedTimeoutMs` (hot, read per call): at the limit
+     * the call's signal aborts and the batch fails with `ModelError("timeout")`, even when the
+     * provider ignores the signal (its late answer is dropped).
+     */
+    private callWithTimeout;
+    /**
+     * `ctx.models.embed` for `plugin` (its declared purposes), aborted by `signal`; `hooks` is the
+     * host's hook registry (`model.request`), absent only for a ctx built without a host (tests).
+     */
+    embed(plugin: string, declared: DeclaredModelPurposes, request: ExtensionEmbedRequest, signal: AbortSignal, hooks: HookRunner | undefined): Promise<ExtensionEmbedResult>;
+    /**
+     * `model.request` for an embed call (policy hooks may deny it). Rejects with the caller's abort
+     * reason when `signal` aborts while the hooks run (an abort is never a deny).
+     */
+    private checkHooks;
+    /** `ctx.models.describe` for `plugin`: null when the purpose maps to no model the org can use. */
+    describe(plugin: string, declared: DeclaredModelPurposes, req: {
+        orgId: string;
+        purpose: string;
+    }): Promise<ExtensionModelTarget | null>;
+    /** One `model_usage` row; its `usage.report` delivery is enqueued after the commit. */
+    private record;
+}

package/dist/models/embeddings.js

@@ -0,0 +1,326 @@
+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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { ModelError, validateEmbedResult, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { isExtensionEnabled } from "../extensions/enabled.js";
+import { audit } from "../identity/audit.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { embeddingDeniedAudit } from "../runtime/hook-calls.js";
+import { modelDeniedText } from "../runtime/model-call.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { ModelPurposesService } from "./purposes.js";
+/** Most texts one `ctx.models.embed` call may carry (the kernel splits them by `maxBatch`). */
+export const EMBED_MAX_INPUTS = 2048;
+/**
+ * The `ctx.models` broker for embeddings (model platform spec B §5.4). Every call:
+ * - accepts only a purpose the calling extension declared in `permissions.models` with
+ *   `kind: "embedding"` (`model.purpose_unknown` otherwise: the manifest is what was approved), for
+ *   an org that enabled the extension (`extension.not_enabled`);
+ * - resolves the org's effective target ({@link ModelPurposesService.resolve}: unmapped, or mapped
+ *   to a model the org cannot use, is `model.unconfigured`) and the model in the org's view, enabled
+ *   and of kind `embedding` ({@link ProviderRegistry.resolve}, bound to the org's effective config);
+ * - fires `model.request` once (`purpose: "embedding"`, every text of the call, no conversation
+ *   fields) through the host's hook registry before anything is sent; a policy denial (a deny, a
+ *   hook error or timeout, a policy extension not loaded here or without a valid config in the org)
+ *   writes one `hook.denied` audit row and rejects with `ApiError("model.hook_denied")` (403) whose
+ *   message is the one a denied run step fails with: no provider call, no usage row. A call with no input sends nothing
+ *   and fires nothing;
+ * - splits the input into batches of the model's `maxBatch`, calls the provider's `embed` once per
+ *   batch in order with the extension's signal (plus the request's own `signal`), each batch
+ *   limited by `models.embedTimeoutMs` (`ModelError("timeout")`), checks each result ({@link validateEmbedResult}: a
+ *   wrong count, dimension or a non-finite number is a `ModelError` of kind `server`), and
+ *   concatenates the vectors; no retries (an extension retries itself if it wants to);
+ * - writes one `model_usage` row (the sum of the batches' input tokens) and announces it after the
+ *   commit (`model_usage.recorded`: the usage reporter's `ModelUsageJobs` enqueues its
+ *   `usage.report` delivery; the usage sweep catches up a lost one). A call that fails after the
+ *   provider answered some batches (an invalid result, a later batch failing) still records their
+ *   input tokens before the error reaches the extension; one that fails before any answer records
+ *   nothing.
+ * Purpose params are not sent: an `embed` request carries none (`EmbedRequest`).
+ */
+let ModelEmbeddings = class ModelEmbeddings {
+    kdb;
+    txHost;
+    purposes;
+    providers;
+    events;
+    log;
+    config;
+    constructor(kdb, txHost, purposes, providers, 
+    /** `model_usage.recorded`: the usage reporter enqueues the row's delivery. */
+    events, log, 
+    /** `models.embedTimeoutMs` (hot). */
+    config) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+        this.purposes = purposes;
+        this.providers = providers;
+        this.events = events;
+        this.log = log;
+        this.config = config;
+    }
+    /** Refuses a purpose `plugin` did not declare with kind `embedding`, or an org it is off in. */
+    async admit(plugin, declared, orgId, purpose) {
+        if (!declared.some((d) => d.purpose === purpose && d.kind === "embedding")) {
+            throw new ApiError("model.purpose_unknown", `Extension ${plugin} declared no embedding purpose "${purpose}" in permissions.models`);
+        }
+        if (!(await isExtensionEnabled(this.kdb.db, orgId, plugin))) {
+            throw new ApiError("extension.not_enabled", `Extension ${plugin} is not enabled in organization ${orgId}`);
+        }
+    }
+    /** The org's target for the purpose and the model bound to the org's config. */
+    async target(orgId, purpose) {
+        const target = await this.purposes.resolve(orgId, purpose);
+        const { provider, info } = await this.providers.resolve(orgId, target.model, {
+            kind: "embedding",
+        });
+        if (info.embedding === undefined || provider.embed === undefined) {
+            // the registry drops such models from the list; kept as a guard
+            throw new ApiError("model.unconfigured", `The model configured for the "${purpose}" purpose cannot embed`);
+        }
+        return {
+            ref: target.model,
+            info: info.embedding,
+            embed: provider.embed.bind(provider),
+        };
+    }
+    /**
+     * One batch to the provider, limited by `models.embedTimeoutMs` (hot, read per call): at the limit
+     * the call's signal aborts and the batch fails with `ModelError("timeout")`, even when the
+     * provider ignores the signal (its late answer is dropped).
+     */
+    async callWithTimeout(embed, batch, signal, model) {
+        const ms = this.config.get().models.embedTimeoutMs;
+        const timer = new AbortController();
+        const both = AbortSignal.any([signal, timer.signal]);
+        let handle;
+        let onAbort;
+        const call = Promise.resolve().then(() => embed(batch, { signal: both }));
+        call.catch(() => { });
+        try {
+            return await Promise.race([
+                call,
+                new Promise((_, reject) => {
+                    handle = setTimeout(() => {
+                        const err = new ModelError("timeout", `Model ${model.provider}/${model.id} did not answer an embed call within ${ms} ms`);
+                        timer.abort(err);
+                        reject(err);
+                    }, ms);
+                    onAbort = () => reject(signal.reason);
+                    signal.addEventListener("abort", onAbort, { once: true });
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(handle);
+            // ctx.signal lives as long as the instance: never leave a listener per batch on it
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * `ctx.models.embed` for `plugin` (its declared purposes), aborted by `signal`; `hooks` is the
+     * host's hook registry (`model.request`), absent only for a ctx built without a host (tests).
+     */
+    async embed(plugin, declared, request, signal, hooks) {
+        checkRequest(request);
+        // a copy, read once: the texts the hooks see are the texts sent, whatever the extension does
+        // with its own request object meanwhile
+        const req = { ...request, input: request.input.slice() };
+        await this.admit(plugin, declared, req.orgId, req.purpose);
+        const t = await this.target(req.orgId, req.purpose);
+        const dimensions = req.dimensions ?? t.info.defaultDimensions;
+        if (!t.info.dimensions.includes(dimensions)) {
+            throw new ApiError("validation_failed", `Model ${t.ref.provider}/${t.ref.model} cannot produce ${dimensions} dimensions (it offers ${t.info.dimensions.join(", ")})`);
+        }
+        const model = { provider: t.ref.provider, id: t.ref.model };
+        if (req.input.length === 0)
+            return { vectors: [], model, dimensions };
+        const vectors = [];
+        /** Input tokens of the batches the provider answered (billed even if the call fails later). */
+        let inputTokens = 0;
+        let answered = 0;
+        const size = Math.max(1, t.info.maxBatch);
+        // the instance's signal (revocation) and the caller's own (e.g. its tool call aborted)
+        const callSignal = req.signal ? AbortSignal.any([signal, req.signal]) : signal;
+        await this.checkHooks(hooks, plugin, req, model, callSignal);
+        try {
+            for (let i = 0; i < req.input.length; i += size) {
+                callSignal.throwIfAborted();
+                const batch = {
+                    model: t.ref.model,
+                    input: req.input.slice(i, i + size),
+                    ...(req.dimensions !== undefined && { dimensions: req.dimensions }),
+                    ...(req.inputType !== undefined && { inputType: req.inputType }),
+                };
+                const res = await this.callWithTimeout(t.embed, batch, callSignal, model);
+                answered++;
+                inputTokens += tokensOf(res);
+                const problem = checkResult(batch, t.info, res);
+                if (problem !== null) {
+                    throw new ModelError("server", `Model ${model.provider}/${model.id} returned an invalid embedding: ${problem}`);
+                }
+                for (const v of res.vectors)
+                    vectors.push(v);
+            }
+        }
+        catch (err) {
+            // the batches already answered were billed by the provider: recorded, then the error
+            if (answered > 0) {
+                await this.record(plugin, req.orgId, req.purpose, model, inputTokens).catch((e) => this.log.warn("cannot record the usage of a failed embed call", {
+                    plugin,
+                    orgId: req.orgId,
+                    err: e,
+                }));
+            }
+            throw err;
+        }
+        await this.record(plugin, req.orgId, req.purpose, model, inputTokens);
+        return { vectors, model, dimensions };
+    }
+    /**
+     * `model.request` for an embed call (policy hooks may deny it). Rejects with the caller's abort
+     * reason when `signal` aborts while the hooks run (an abort is never a deny).
+     */
+    async checkHooks(hooks, plugin, req, model, signal) {
+        if (!hooks?.has("model.request"))
+            return;
+        const call = {
+            purpose: "embedding",
+            orgId: req.orgId,
+            extension: plugin,
+            embeddingPurpose: req.purpose,
+            provider: model.provider,
+            model: model.id,
+            input: req.input,
+            ...(req.dimensions !== undefined && { dimensions: req.dimensions }),
+            ...(req.inputType !== undefined && { inputType: req.inputType }),
+        };
+        const verdict = await hooks.run("model.request", call, signal);
+        if (verdict.allowed)
+            return;
+        await audit(this.kdb.db, embeddingDeniedAudit(call, verdict));
+        this.log.warn("embed call blocked by a policy hook", {
+            plugin,
+            orgId: req.orgId,
+            hookPlugin: verdict.plugin,
+            cause: verdict.cause,
+        });
+        throw new ApiError("model.hook_denied", modelDeniedText(verdict.plugin, verdict.reason));
+    }
+    /** `ctx.models.describe` for `plugin`: null when the purpose maps to no model the org can use. */
+    async describe(plugin, declared, req) {
+        if (typeof req?.orgId !== "string" || typeof req.purpose !== "string") {
+            throw new ApiError("validation_failed", "describe needs orgId and purpose strings");
+        }
+        await this.admit(plugin, declared, req.orgId, req.purpose);
+        try {
+            const t = await this.target(req.orgId, req.purpose);
+            return {
+                provider: t.ref.provider,
+                id: t.ref.model,
+                kind: "embedding",
+                embedding: structuredClone(t.info),
+            };
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.code === "model.unconfigured")
+                return null;
+            throw e;
+        }
+    }
+    /** One `model_usage` row; its `usage.report` delivery is enqueued after the commit. */
+    async record(plugin, orgId, purpose, model, inputTokens) {
+        const row = await this.kdb.db
+            .insertInto("model_usage")
+            .values({
+            org_id: orgId,
+            extension: plugin,
+            purpose,
+            provider: model.provider,
+            model: model.id,
+            input_tokens: Math.round(inputTokens),
+        })
+            .returning("id")
+            .executeTakeFirstOrThrow();
+        // fire and forget: the extension's call never waits on the enqueue (PG, Redis); a lost one is
+        // caught up by the usage sweep
+        afterCommit(() => {
+            void this.events
+                .emit("model_usage.recorded", { id: row.id })
+                .catch((err) => this.log.warn("model usage event failed", { usageId: row.id, err }));
+        });
+    }
+};
+__decorate([
+    Transactional()
+], ModelEmbeddings.prototype, "record", null);
+ModelEmbeddings = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(ModelPurposesService)),
+    __param(3, Inject(ProviderRegistry)),
+    __param(4, Inject(KernelEvents)),
+    __param(5, Inject(KERNEL_LOGGER)),
+    __param(6, Inject(KernelConfigService))
+], ModelEmbeddings);
+export { ModelEmbeddings };
+/** A result's input tokens when it reports a usable number, else 0 (an invalid result). */
+function tokensOf(res) {
+    const n = res?.usage?.inputTokens;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? n : 0;
+}
+/** The request's shape (an extension is untyped JavaScript at run time). */
+function checkRequest(req) {
+    const bad = (why) => {
+        throw new ApiError("validation_failed", `Invalid embed request: ${why}`);
+    };
+    if (typeof req !== "object" || req === null)
+        bad("expected an object");
+    if (typeof req.orgId !== "string" || req.orgId === "")
+        bad("orgId must be a string");
+    if (typeof req.purpose !== "string" || req.purpose === "")
+        bad("purpose must be a string");
+    if (!Array.isArray(req.input) || req.input.some((t) => typeof t !== "string")) {
+        bad("input must be an array of strings");
+    }
+    if (req.input.length > EMBED_MAX_INPUTS)
+        bad(`at most ${EMBED_MAX_INPUTS} inputs per call`);
+    if (req.dimensions !== undefined && !Number.isInteger(req.dimensions)) {
+        bad("dimensions must be an integer");
+    }
+    if (req.signal !== undefined && !(req.signal instanceof AbortSignal)) {
+        bad("signal must be an AbortSignal");
+    }
+    if (req.inputType !== undefined && req.inputType !== "query" && req.inputType !== "document") {
+        bad('inputType must be "query" or "document"');
+    }
+}
+/** {@link validateEmbedResult}, plus the result's own shape (a provider is untyped at run time). */
+function checkResult(req, info, res) {
+    const r = res;
+    if (typeof r !== "object" || r === null || !Array.isArray(r.vectors))
+        return "no vectors";
+    if (!r.vectors.every((v) => Array.isArray(v)))
+        return "a vector is not an array";
+    const tokens = r.usage?.inputTokens;
+    if (typeof tokens !== "number" || !Number.isFinite(tokens) || tokens < 0) {
+        return "usage.inputTokens is not a non-negative number";
+    }
+    return validateEmbedResult(req, info, r);
+}

package/dist/models/enablement.controller.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type ModelDisableResult, ModelEnablement } from "./enablement.js";
+/** `:provider` of a disabled-list route. */
+export declare const ModelProviderParams: z.ZodObject<{
+    provider: z.ZodString;
+}, z.core.$strip>;
+declare const ModelProviderParamsDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    provider: z.ZodString;
+}, z.core.$strip>>;
+export declare class ModelProviderParamsDto extends ModelProviderParamsDto_base {
+}
+/**
+ * The body of a disabled-list PATCH: the model ids of the provider to disable and to enable. An id
+ * in neither list keeps its stored state (a page never drops ids it does not show); an id in both
+ * is a 400 `validation_failed`.
+ */
+export declare const ModelDisabledPatch: z.ZodObject<{
+    disable: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enable: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const ModelDisabledPatchDto_base: import("../infra/validation/create-zod-dto.js").ZodDtoClass<z.ZodObject<{
+    disable: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enable: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+export declare class ModelDisabledPatchDto extends ModelDisabledPatchDto_base {
+}
+/**
+ * The org's disabled models of one provider (`PATCH /api/v1/orgs/:orgId/models/:provider/disabled`,
+ * spec B §5.3): `org.models.manage`, people only. Disables and enables the ids the body names; the
+ * response lists the org's agents and purposes that now point at a newly disabled model (the
+ * disable is not refused for them).
+ */
+export declare class ModelEnablementController {
+    private readonly enablement;
+    constructor(enablement: ModelEnablement);
+    patch(principal: Principal, org: OrgContext, params: z.infer<typeof ModelProviderParams>, body: z.infer<typeof ModelDisabledPatch>): Promise<ModelDisableResult>;
+}
+export {};

package/dist/models/enablement.controller.js

@@ -0,0 +1,74 @@
+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 __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Inject, Patch } from "@nestjs/common";
+import { z } from "zod";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ModelEnablement } from "./enablement.js";
+/** `:provider` of a disabled-list route. */
+export const ModelProviderParams = z.object({ provider: z.string().min(1).max(200) });
+export class ModelProviderParamsDto extends createZodDto(ModelProviderParams, "ModelProviderParams") {
+}
+const modelIds = z.array(z.string().min(1).max(200)).max(5000).default([]);
+/**
+ * The body of a disabled-list PATCH: the model ids of the provider to disable and to enable. An id
+ * in neither list keeps its stored state (a page never drops ids it does not show); an id in both
+ * is a 400 `validation_failed`.
+ */
+export const ModelDisabledPatch = z
+    .object({ disable: modelIds, enable: modelIds })
+    .strict()
+    .superRefine((v, ctx) => {
+    const disable = new Set(v.disable);
+    const both = [...new Set(v.enable.filter((m) => disable.has(m)))];
+    if (both.length > 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["enable"],
+            message: `A model cannot be both disabled and enabled: ${both.join(", ")}`,
+        });
+    }
+});
+export class ModelDisabledPatchDto extends createZodDto(ModelDisabledPatch, "ModelDisabledPatch") {
+}
+/**
+ * The org's disabled models of one provider (`PATCH /api/v1/orgs/:orgId/models/:provider/disabled`,
+ * spec B §5.3): `org.models.manage`, people only. Disables and enables the ids the body names; the
+ * response lists the org's agents and purposes that now point at a newly disabled model (the
+ * disable is not refused for them).
+ */
+let ModelEnablementController = class ModelEnablementController {
+    enablement;
+    constructor(enablement) {
+        this.enablement = enablement;
+    }
+    async patch(principal, org, params, body) {
+        const p = requireUser(principal);
+        return this.enablement.setOrg(org.orgId, params.provider, body, {
+            accountId: p.account.id,
+            tokenId: patTokenId(p),
+        });
+    }
+};
+__decorate([
+    Patch(":provider/disabled"),
+    OrgAction("org.models.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ModelProviderParamsDto)),
+    __param(3, ZBody(ModelDisabledPatchDto))
+], ModelEnablementController.prototype, "patch", null);
+ModelEnablementController = __decorate([
+    Controller("api/v1/orgs/:orgId/models"),
+    __param(0, Inject(ModelEnablement))
+], ModelEnablementController);
+export { ModelEnablementController };

package/dist/models/enablement.d.ts

@@ -0,0 +1,99 @@
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { SuperAdminLock } from "../identity/super-admin.js";
+import { CacheService } from "../infra/cache/cache.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+/** The key of a model in a disabled set: `provider\u0000model`. */
+export declare const modelKey: (provider: string, model: string) => string;
+/** An agent whose current version uses a newly disabled model as its main model or fallback. */
+export interface AffectedModelAgent {
+    id: string;
+    name: string;
+    orgId: string;
+}
+/** A purpose mapping targeting a newly disabled model: a deployment default (`orgId` null) or an org override. */
+export interface AffectedModelPurpose {
+    purpose: string;
+    orgId: string | null;
+}
+/** The result of a disabled-list write: what now points at a model it disabled (spec B §5.3). */
+export interface ModelDisableResult {
+    affected: {
+        agents: AffectedModelAgent[];
+        purposes: AffectedModelPurpose[];
+    };
+}
+/**
+ * A change to one layer's disabled list of a provider: ids to disable and ids to enable. An id in
+ * neither list keeps its stored state; an id in both is refused.
+ */
+export interface ModelDisableChange {
+    disable: string[];
+    enable: string[];
+}
+/** The acting person of a write. */
+export interface ModelDisableActor {
+    accountId: string;
+    tokenId?: string | undefined;
+}
+/**
+ * Models disabled on two layers (spec B §5.3, table `model_disabled`): the platform's list (the
+ * super admin; such a model is invisible to every org) and each org's (an org admin). Every model a
+ * provider lists is enabled unless a layer disabled it; a row keys on the model id, so it applies to
+ * whichever list the org sees, and an id the list does not contain is kept harmlessly. Disabling
+ * never creates an org config copy.
+ *
+ * The lists are read from PG and cached in Redis (`@Cacheable`, evicted after the commit of each
+ * write), never in process memory. `ProviderRegistry` filters its lists and `resolve` with them;
+ * purposes check their targets with {@link isEnabled}.
+ */
+export declare class ModelEnablement {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    readonly cacheService: CacheService;
+    private readonly extensions;
+    private readonly adminLock;
+    private readonly orgLock;
+    constructor(kdb: KernelDb, txHost: TransactionHost, cacheService: CacheService, extensions: Pick<ExtensionRegistry, "list">, adminLock: Pick<SuperAdminLock, "lockAndAuthorize">, orgLock: Pick<OrgLock, "lockAndAuthorize">);
+    private get db();
+    /** One layer's disabled models (keys {@link modelKey}): the platform's (`null`) or the org's own. */
+    disabled(orgId: string | null): Promise<Set<string>>;
+    private disabledKeys;
+    private rowsOf;
+    /**
+     * The extensions `orgId` explicitly turned off: a row of the org's own switch
+     * (`extension_org_configs.enabled = false`, what the org's extension or plugin switch writes when
+     * an org admin turns it off), never a required bootstrap plugin. An extension with no row for the
+     * org is not in the set (it keeps working as before: spec A §8 with B's no-breakage anti-goal).
+     * Read from PG on every call (one small query; the switch has its own writers, nothing to evict).
+     */
+    switchedOff(orgId: string): Promise<Set<string>>;
+    /** Whether neither the platform nor `orgId` disabled the model (the lists only; see the class). */
+    isEnabled(orgId: string, provider: string, model: string): Promise<boolean>;
+    /**
+     * Changes the platform's disabled ids of `provider` by `change` (super admin, re-checked under
+     * the lock): ids in neither list keep their stored state. Returns what now points at a newly
+     * disabled model, across orgs.
+     */
+    setPlatform(provider: string, change: ModelDisableChange, actor: ModelDisableActor): Promise<ModelDisableResult>;
+    /**
+     * Changes the org's disabled ids of `provider` by `change` (`org.models.manage`, re-checked under
+     * the org lock): ids in neither list keep their stored state, so rows for models the org's page
+     * does not show (platform-disabled, or no longer listed) survive. Returns what in the org now
+     * points at a newly disabled model (its agents, its overrides and the deployment defaults it uses).
+     */
+    setOrg(orgId: string, provider: string, change: ModelDisableChange, actor: ModelDisableActor): Promise<ModelDisableResult>;
+    private apply;
+    /** Live agents (of `orgId`, or of every org) whose current version uses one of `models`. */
+    private agentsUsing;
+    /**
+     * Purpose mappings targeting one of `models`: for the platform every default and override, for
+     * an org its overrides and the deployment defaults (an org that disabled a default's model has
+     * that purpose unconfigured).
+     */
+    private purposesUsing;
+}
+/** The one {@link ModelEnablement}: the provider registry, purposes and the controllers read it. */
+export declare class ModelEnablementModule {
+}