@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

package/dist/models/prices.d.ts

@@ -0,0 +1,53 @@
+import type { ModelUsage } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * 一个模型的价格（C2）：每百万 token，币种为部署设置 `priceCurrency`。由企业管理员录入，插件不声明价格。
+ * 缓存读 / 写价为 null 时按输入价计。
+ */
+export interface ModelPrice {
+    provider: string;
+    model: string;
+    inputPerMTok: number;
+    outputPerMTok: number;
+    cacheReadPerMTok: number | null;
+    cacheWritePerMTok: number | null;
+}
+/** 价格表：键为 {@link priceKey}（`${provider}\n${model}`）。 */
+export type PriceTable = ReadonlyMap<string, ModelPrice>;
+/** 价格表的键。供应商名与模型 id 不含换行，拼接不会撞键。 */
+export declare const priceKey: (provider: string, model: string) => string;
+/** 一次调用的估算成本；没有价格 → null。用量的四项互不重叠（见 plugin-sdk `ModelUsage`）。 */
+export declare function costOf(usage: ModelUsage, price: ModelPrice | undefined): number | null;
+/** `PUT /api/v1/admin/model-prices` 的 body：设一个价格，或 `price: null` 删除。 */
+export declare const MODEL_PRICE_PUT: z.ZodUnion<readonly [z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    inputPerMTok: z.ZodNumber;
+    outputPerMTok: z.ZodNumber;
+    cacheReadPerMTok: z.ZodNullable<z.ZodNumber>;
+    cacheWritePerMTok: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    price: z.ZodNull;
+}, z.core.$strict>]>;
+export type ModelPricePut = z.infer<typeof MODEL_PRICE_PUT>;
+/** 模型价格（PG `model_prices`）：每次读都查库，不在进程内缓存（多副本下改价立刻生效）。 */
+export declare class PricesService {
+    private readonly db;
+    constructor(db: KernelDb);
+    /** 全部价格，按 provider、model 排序。 */
+    list(): Promise<ModelPrice[]>;
+    /** 价格表（按 {@link priceKey} 查）。 */
+    table(): Promise<PriceTable>;
+    /**
+     * 设置或删除（`price: null`）一个模型的价格：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
+     * （否则 `forbidden`），写审计 `model_price.updated` / `model_price.deleted`。
+     */
+    put(input: ModelPrice | {
+        provider: string;
+        model: string;
+        price: null;
+    }, actorAccountId: string, actorTokenId?: string): Promise<void>;
+}

package/dist/models/prices.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+/** 价格表的键。供应商名与模型 id 不含换行，拼接不会撞键。 */
+export const priceKey = (provider, model) => `${provider}\n${model}`;
+/** 一次调用的估算成本；没有价格 → null。用量的四项互不重叠（见 plugin-sdk `ModelUsage`）。 */
+export function costOf(usage, price) {
+    if (price === undefined)
+        return null;
+    const cacheRead = price.cacheReadPerMTok ?? price.inputPerMTok;
+    const cacheWrite = price.cacheWritePerMTok ?? price.inputPerMTok;
+    return ((usage.inputTokens * price.inputPerMTok +
+        usage.outputTokens * price.outputPerMTok +
+        usage.cacheReadTokens * cacheRead +
+        usage.cacheWriteTokens * cacheWrite) /
+        1_000_000);
+}
+/** 单价：≥ 0 且 ≤ 1e6（有限数）。 */
+const PerMTok = z.number().min(0).max(1_000_000);
+const Name = z.string().min(1).max(200);
+/** `PUT /api/v1/admin/model-prices` 的 body：设一个价格，或 `price: null` 删除。 */
+export const MODEL_PRICE_PUT = z.union([
+    z
+        .object({
+        provider: Name,
+        model: Name,
+        inputPerMTok: PerMTok,
+        outputPerMTok: PerMTok,
+        cacheReadPerMTok: PerMTok.nullable(),
+        cacheWritePerMTok: PerMTok.nullable(),
+    })
+        .strict(),
+    z.object({ provider: Name, model: Name, price: z.null() }).strict(),
+]);
+const num = (v) => Number(v);
+const numOrNull = (v) => (v === null ? null : Number(v));
+/** 模型价格（PG `model_prices`）：每次读都查库，不在进程内缓存（多副本下改价立刻生效）。 */
+export class PricesService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 全部价格，按 provider、model 排序。 */
+    async list() {
+        const rows = await this.db
+            .selectFrom("model_prices")
+            .select([
+            "provider",
+            "model",
+            "input_per_mtok",
+            "output_per_mtok",
+            "cache_read_per_mtok",
+            "cache_write_per_mtok",
+        ])
+            .orderBy("provider")
+            .orderBy("model")
+            .execute();
+        return rows.map((r) => ({
+            provider: r.provider,
+            model: r.model,
+            inputPerMTok: num(r.input_per_mtok),
+            outputPerMTok: num(r.output_per_mtok),
+            cacheReadPerMTok: numOrNull(r.cache_read_per_mtok),
+            cacheWritePerMTok: numOrNull(r.cache_write_per_mtok),
+        }));
+    }
+    /** 价格表（按 {@link priceKey} 查）。 */
+    async table() {
+        return new Map((await this.list()).map((p) => [priceKey(p.provider, p.model), p]));
+    }
+    /**
+     * 设置或删除（`price: null`）一个模型的价格：事务内取企业管理员锁并复核发起人仍是活跃企业管理员
+     * （否则 `forbidden`），写审计 `model_price.updated` / `model_price.deleted`。
+     */
+    async put(input, actorAccountId, actorTokenId) {
+        const check = MODEL_PRICE_PUT.safeParse(input);
+        if (!check.success) {
+            throw new ApiError("validation_failed", "Invalid model price", check.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })));
+        }
+        const v = check.data;
+        await this.db.transaction().execute(async (trx) => {
+            await lockEnterpriseAdminsAndAuthorize(trx, actorAccountId);
+            const target = `${v.provider}/${v.model}`;
+            if ("price" in v) {
+                await trx
+                    .deleteFrom("model_prices")
+                    .where("provider", "=", v.provider)
+                    .where("model", "=", v.model)
+                    .execute();
+                await audit(trx, {
+                    actorAccountId,
+                    ...(actorTokenId !== undefined && { actorTokenId }),
+                    action: "model_price.deleted",
+                    target,
+                    detail: { provider: v.provider, model: v.model },
+                });
+                return;
+            }
+            const values = {
+                input_per_mtok: v.inputPerMTok,
+                output_per_mtok: v.outputPerMTok,
+                cache_read_per_mtok: v.cacheReadPerMTok,
+                cache_write_per_mtok: v.cacheWritePerMTok,
+                updated_by: actorAccountId,
+            };
+            await trx
+                .insertInto("model_prices")
+                .values({ provider: v.provider, model: v.model, ...values })
+                .onConflict((oc) => oc.columns(["provider", "model"]).doUpdateSet({ ...values, updated_at: new Date() }))
+                .execute();
+            await audit(trx, {
+                actorAccountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                action: "model_price.updated",
+                target,
+                detail: { ...v },
+            });
+        });
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type ModelPurposesService, type PurposePut, type PurposeTarget, type PurposeView } from "./purposes.js";
+/** body 的目标（参数缺省为 `{}`）。 */
+export declare const purposeTargetOf: (b: PurposePut) => PurposeTarget | null;
+/**
+ * 本组织的模型用途映射（`/api/v1/orgs/:orgId/model-purposes`）：`org.models.manage`（admin 起、只给人）。
+ * 列表给出每个用途的部署默认、组织覆盖与生效的映射；PUT 设置或（`target: null`）清除组织覆盖。
+ */
+export declare class ModelPurposesController {
+    private readonly purposes;
+    constructor(purposes: ModelPurposesService);
+    list(principal: Principal, org: OrgContext): Promise<{
+        purposes: PurposeView[];
+    }>;
+    put(principal: Principal, org: OrgContext, purpose: string, body: PurposePut): Promise<{
+        purpose: PurposeView;
+    }>;
+}

package/dist/models/purposes.controller.js

@@ -0,0 +1,56 @@
+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 { Body, Controller, Get, Inject, Param, Put } from "@nestjs/common";
+import { MODEL_PURPOSES } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { PURPOSE_PUT, } from "./purposes.js";
+/** body 的目标（参数缺省为 `{}`）。 */
+export const purposeTargetOf = (b) => b.target === null ? null : { model: b.target.model, params: b.target.params ?? {} };
+/**
+ * 本组织的模型用途映射（`/api/v1/orgs/:orgId/model-purposes`）：`org.models.manage`（admin 起、只给人）。
+ * 列表给出每个用途的部署默认、组织覆盖与生效的映射；PUT 设置或（`target: null`）清除组织覆盖。
+ */
+let ModelPurposesController = class ModelPurposesController {
+    purposes;
+    constructor(purposes) {
+        this.purposes = purposes;
+    }
+    async list(principal, org) {
+        requireUser(principal);
+        return { purposes: await this.purposes.list(org.orgId) };
+    }
+    async put(principal, org, purpose, body) {
+        const p = requireUser(principal);
+        return {
+            purpose: await this.purposes.setOrg(org.orgId, purpose, purposeTargetOf(body), p.account.id, patTokenId(p)),
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.models.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], ModelPurposesController.prototype, "list", null);
+__decorate([
+    Put(":purpose"),
+    OrgAction("org.models.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("purpose")),
+    __param(3, Body(new ZodPipe(PURPOSE_PUT)))
+], ModelPurposesController.prototype, "put", null);
+ModelPurposesController = __decorate([
+    Controller("api/v1/orgs/:orgId/model-purposes"),
+    __param(0, Inject(MODEL_PURPOSES))
+], ModelPurposesController);
+export { ModelPurposesController };

package/dist/models/purposes.d.ts

@@ -0,0 +1,140 @@
+import { type ContentBlock, type ExtensionManifest, type ModelRequest, type ModelUsage, type ParamValue, type StopReason } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { ModelRef } from "../agents/definition.js";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { type ProviderRegistry } from "../runtime/providers.js";
+/**
+ * 模型用途映射（C9）：内核与插件按「用途」取模型，不在代码里写死模型。
+ * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
+ * - 映射 = 部署默认（`org_id` 为 null，企业管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
+ *   生效的映射先取组织覆盖、再取部署默认，都没有 → `model.unconfigured`；
+ * - 目标模型按部署范围解析（与运行时一致），参数按目标模型自己的声明严格校验；不做模型白名单；
+ * - 每次都查 PG，不在进程内缓存（多副本下改映射立即生效）。`ctx.models` 仍预留，插件暂不能调用。
+ */
+/**
+ * Purposes the kernel declares: the eval judge, and the three sub-agent model tiers (phase C,
+ * spec §5.4: `fast` / `standard` / `capable` → `subagent_<tier>`; an unmapped tier runs on the
+ * parent's model).
+ */
+export declare const KERNEL_PURPOSES: readonly [{
+    readonly purpose: "eval";
+    readonly kind: "chat";
+    readonly label: {
+        readonly zh: "评测评委";
+        readonly en: "Eval judge";
+    };
+}, {
+    readonly purpose: "title";
+    readonly kind: "chat";
+    readonly label: {
+        readonly zh: "会话标题";
+        readonly en: "Conversation titles";
+    };
+}, {
+    readonly purpose: "subagent_fast";
+    readonly kind: "chat";
+    readonly label: {
+        readonly zh: "子代理：快速";
+        readonly en: "Sub-agent: fast";
+    };
+}, {
+    readonly purpose: "subagent_standard";
+    readonly kind: "chat";
+    readonly label: {
+        readonly zh: "子代理：标准";
+        readonly en: "Sub-agent: standard";
+    };
+}, {
+    readonly purpose: "subagent_capable";
+    readonly kind: "chat";
+    readonly label: {
+        readonly zh: "子代理：最强";
+        readonly en: "Sub-agent: capable";
+    };
+}];
+/** 一个用途映射到的模型与参数。 */
+export interface PurposeTarget {
+    model: ModelRef;
+    params: Record<string, ParamValue>;
+}
+export interface PurposeView {
+    purpose: string;
+    kind: "chat" | "embedding";
+    label: {
+        zh: string;
+        en: string;
+    };
+    /** `kernel` 或声明它的插件名。 */
+    declaredBy: string;
+    default: PurposeTarget | null;
+    override: PurposeTarget | null;
+    effective: PurposeTarget | null;
+}
+/** `PUT …/model-purposes/:purpose` 的 body：设映射，或 `target: null` 清除。 */
+export declare const PURPOSE_PUT: z.ZodObject<{
+    target: z.ZodNullable<z.ZodObject<{
+        model: z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strict>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PurposePut = z.infer<typeof PURPOSE_PUT>;
+/**
+ * 用途请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是应计入预算的估算用量（输入估算 + 已流出字符 / 4，
+ * 与评测回放一致），`cause` 是原始错误。请求发出之前的失败（未映射、模型不可用）原样抛出。
+ */
+export declare class PurposeAttemptError extends Error {
+    readonly cause: unknown;
+    readonly tokens: number;
+    readonly provider: string;
+    readonly model: string;
+    constructor(cause: unknown, tokens: number, provider: string, model: string);
+}
+export interface ModelPurposesDeps {
+    db: KernelDb;
+    registry: Pick<ProviderRegistry, "resolve">;
+    config: () => KernelConfig;
+    /** 已加载插件的清单（取 `permissions.models`）。 */
+    manifests: () => readonly ExtensionManifest[];
+}
+export declare class ModelPurposesService {
+    private readonly d;
+    constructor(d: ModelPurposesDeps);
+    /** 全部已声明的用途：内核的在前，其后按插件加载顺序。 */
+    private declared;
+    private find;
+    private rows;
+    private views;
+    /** 全部用途与映射；不给 `orgId` = 部署级视图（`override` 一律为 null）。 */
+    list(orgId?: string): Promise<PurposeView[]>;
+    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
+    private check;
+    private set;
+    /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
+    setDefault(purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
+    /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
+    setOrg(orgId: string, purpose: string, target: PurposeTarget | null, actor: string, actorTokenId?: string): Promise<PurposeView>;
+    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。 */
+    resolve(orgId: string, purpose: string): Promise<PurposeTarget>;
+    /**
+     * 按用途发一次对话请求：解析映射、按目标模型的声明宽松处理参数（补默认值，与运行时一致），用 `consumeModelStream`
+     * 收完（只有流空闲看门狗）。输出上限取 `min(req.maxOutputTokens, 目标模型的 maxOutputTokens)`。
+     * 请求发出之前的失败原样抛出；发出之后的失败包成 {@link PurposeAttemptError}（带估算用量）。
+     * `opts.fallback`: the target used when the purpose is not mapped (`model.unconfigured`).
+     * `opts.beforeSend`: called with the resolved target and the final request just before sending;
+     * what it throws is thrown as is (a pre-send failure, e.g. a denied `model.request` hook).
+     */
+    chat(orgId: string, purpose: string, req: Omit<ModelRequest, "model" | "params">, signal: AbortSignal, opts?: {
+        fallback?: PurposeTarget;
+        beforeSend?: (target: ModelRef, request: ModelRequest) => Promise<void>;
+    }): Promise<{
+        content: ContentBlock[];
+        stopReason: StopReason;
+        usage: ModelUsage;
+        provider: string;
+        model: string;
+    }>;
+}

package/dist/models/purposes.js

@@ -0,0 +1,267 @@
+import { sanitizeParams, } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { paramIssues } from "../agents/agents.service.js";
+import { ModelRef } from "../agents/definition.js";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { lockEnterpriseAdminsAndAuthorize } from "../identity/enterprise-admin.js";
+import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
+import { estimateTokens } from "../runtime/context/tokens.js";
+import { consumeModelStream } from "../runtime/model-call.js";
+import { ProviderListError } from "../runtime/providers.js";
+/**
+ * 模型用途映射（C9）：内核与插件按「用途」取模型，不在代码里写死模型。
+ * - 用途 = 内核用途 {@link KERNEL_PURPOSES}（目前只有评委 `eval`），或已加载插件 `permissions.models` 声明的；
+ * - 映射 = 部署默认（`org_id` 为 null，企业管理员设）+ 组织覆盖（组织管理员设，`org.models.manage`）；
+ *   生效的映射先取组织覆盖、再取部署默认，都没有 → `model.unconfigured`；
+ * - 目标模型按部署范围解析（与运行时一致），参数按目标模型自己的声明严格校验；不做模型白名单；
+ * - 每次都查 PG，不在进程内缓存（多副本下改映射立即生效）。`ctx.models` 仍预留，插件暂不能调用。
+ */
+/**
+ * Purposes the kernel declares: the eval judge, and the three sub-agent model tiers (phase C,
+ * spec §5.4: `fast` / `standard` / `capable` → `subagent_<tier>`; an unmapped tier runs on the
+ * parent's model).
+ */
+export const KERNEL_PURPOSES = [
+    { purpose: "eval", kind: "chat", label: { zh: "评测评委", en: "Eval judge" } },
+    /** Conversation titles (UI refresh B); unmapped → the conversation's current chat model. */
+    { purpose: "title", kind: "chat", label: { zh: "会话标题", en: "Conversation titles" } },
+    {
+        purpose: "subagent_fast",
+        kind: "chat",
+        label: { zh: "子代理：快速", en: "Sub-agent: fast" },
+    },
+    {
+        purpose: "subagent_standard",
+        kind: "chat",
+        label: { zh: "子代理：标准", en: "Sub-agent: standard" },
+    },
+    {
+        purpose: "subagent_capable",
+        kind: "chat",
+        label: { zh: "子代理：最强", en: "Sub-agent: capable" },
+    },
+];
+/** `PUT …/model-purposes/:purpose` 的 body：设映射，或 `target: null` 清除。 */
+export const PURPOSE_PUT = z
+    .object({
+    target: z
+        .object({
+        model: ModelRef.strict(),
+        params: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    })
+        .strict()
+        .nullable(),
+})
+    .strict();
+/**
+ * 用途请求已经发出、但没有正常收完（出错、超时、中止）：`tokens` 是应计入预算的估算用量（输入估算 + 已流出字符 / 4，
+ * 与评测回放一致），`cause` 是原始错误。请求发出之前的失败（未映射、模型不可用）原样抛出。
+ */
+export class PurposeAttemptError extends Error {
+    cause;
+    tokens;
+    provider;
+    model;
+    constructor(cause, tokens, provider, model) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.cause = cause;
+        this.tokens = tokens;
+        this.provider = provider;
+        this.model = model;
+        this.name = "PurposeAttemptError";
+    }
+}
+const unknownPurpose = (purpose) => new ApiError("model.purpose_unknown", `Unknown model purpose "${purpose}"`);
+const invalid = (details) => new ApiError("validation_failed", "Invalid purpose target", details);
+const targetOf = (r) => r === undefined
+    ? null
+    : {
+        model: { provider: r.provider, model: r.model },
+        params: (r.params ?? {}),
+    };
+export class ModelPurposesService {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /** 全部已声明的用途：内核的在前，其后按插件加载顺序。 */
+    declared() {
+        const out = KERNEL_PURPOSES.map((p) => ({
+            purpose: p.purpose,
+            kind: p.kind,
+            label: { ...p.label },
+            declaredBy: "kernel",
+        }));
+        const seen = new Set(out.map((p) => p.purpose));
+        for (const m of this.d.manifests()) {
+            for (const p of m.permissions?.models ?? []) {
+                if (seen.has(p.purpose))
+                    continue;
+                seen.add(p.purpose);
+                out.push({
+                    purpose: p.purpose,
+                    kind: p.kind,
+                    label: { zh: p.label.zh, en: p.label.en },
+                    declaredBy: m.name,
+                });
+            }
+        }
+        return out;
+    }
+    find(purpose) {
+        const p = this.declared().find((x) => x.purpose === purpose);
+        if (!p)
+            throw unknownPurpose(purpose);
+        return p;
+    }
+    async rows(purposes, orgId) {
+        if (purposes.length === 0)
+            return [];
+        return this.d.db
+            .selectFrom("model_purpose_mappings")
+            .select(["org_id", "purpose", "provider", "model", "params"])
+            .where("purpose", "in", purposes)
+            .where((eb) => orgId === undefined
+            ? eb("org_id", "is", null)
+            : eb.or([eb("org_id", "is", null), eb("org_id", "=", orgId)]))
+            .execute();
+    }
+    async views(decl, orgId) {
+        const rows = await this.rows(decl.map((p) => p.purpose), orgId);
+        return decl.map((p) => {
+            const def = targetOf(rows.find((r) => r.purpose === p.purpose && r.org_id === null));
+            const ovr = orgId === undefined
+                ? null
+                : targetOf(rows.find((r) => r.purpose === p.purpose && r.org_id === orgId));
+            return { ...p, default: def, override: ovr, effective: ovr ?? def };
+        });
+    }
+    /** 全部用途与映射；不给 `orgId` = 部署级视图（`override` 一律为 null）。 */
+    async list(orgId) {
+        return this.views(this.declared(), orgId);
+    }
+    /** 校验目标：模型可解析（部署范围）、参数按它的声明严格通过。 */
+    async check(target) {
+        let info;
+        try {
+            ({ info } = await this.d.registry.resolve(target.model));
+        }
+        catch (e) {
+            if (e instanceof ProviderListError)
+                throw e;
+            if (e instanceof ApiError && e.code === "agent.model_unavailable") {
+                throw invalid([{ path: "target.model", message: "model is not available" }]);
+            }
+            throw e;
+        }
+        const issues = paramIssues("target.params", info.parameters, target.params);
+        if (issues.length > 0)
+            throw invalid(issues);
+    }
+    async set(orgId, purpose, target, actor, actorTokenId) {
+        const decl = this.find(purpose);
+        if (target)
+            await this.check(target);
+        await this.d.db.transaction().execute(async (trx) => {
+            if (orgId === null)
+                await lockEnterpriseAdminsAndAuthorize(trx, actor);
+            else
+                await lockOrgAndAuthorize(trx, orgId, actor, "org.models.manage");
+            if (target === null) {
+                await trx
+                    .deleteFrom("model_purpose_mappings")
+                    .where("purpose", "=", purpose)
+                    .where((eb) => (orgId === null ? eb("org_id", "is", null) : eb("org_id", "=", orgId)))
+                    .execute();
+            }
+            else {
+                const values = {
+                    provider: target.model.provider,
+                    model: target.model.model,
+                    params: JSON.stringify(target.params),
+                    updated_by: actor,
+                };
+                await trx
+                    .insertInto("model_purpose_mappings")
+                    .values({ org_id: orgId, purpose, ...values })
+                    .onConflict((oc) => oc
+                    .constraint("model_purpose_mappings_scope_key")
+                    .doUpdateSet({ ...values, updated_at: new Date() }))
+                    .execute();
+            }
+            await audit(trx, {
+                actorAccountId: actor,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                ...(orgId !== null && { orgId }),
+                action: "model.purpose_mapped",
+                target: purpose,
+                detail: { scope: orgId === null ? "deployment" : "org", target },
+            });
+        });
+        const [view] = await this.views([decl], orgId ?? undefined);
+        return view;
+    }
+    /** 设置（或 `null` 清除）部署默认；只有企业管理员（事务内复核）。 */
+    setDefault(purpose, target, actor, actorTokenId) {
+        return this.set(null, purpose, target, actor, actorTokenId);
+    }
+    /** 设置（或 `null` 清除）组织覆盖；事务内锁组织并复核 `org.models.manage`。 */
+    setOrg(orgId, purpose, target, actor, actorTokenId) {
+        return this.set(orgId, purpose, target, actor, actorTokenId);
+    }
+    /** 生效的映射：组织覆盖，否则部署默认；都没有 → `model.unconfigured`；用途未声明 → `model.purpose_unknown`。 */
+    async resolve(orgId, purpose) {
+        const [view] = await this.views([this.find(purpose)], orgId);
+        if (!view?.effective) {
+            throw new ApiError("model.unconfigured", `No model is configured for the "${purpose}" purpose`);
+        }
+        return view.effective;
+    }
+    /**
+     * 按用途发一次对话请求：解析映射、按目标模型的声明宽松处理参数（补默认值，与运行时一致），用 `consumeModelStream`
+     * 收完（只有流空闲看门狗）。输出上限取 `min(req.maxOutputTokens, 目标模型的 maxOutputTokens)`。
+     * 请求发出之前的失败原样抛出；发出之后的失败包成 {@link PurposeAttemptError}（带估算用量）。
+     * `opts.fallback`: the target used when the purpose is not mapped (`model.unconfigured`).
+     * `opts.beforeSend`: called with the resolved target and the final request just before sending;
+     * what it throws is thrown as is (a pre-send failure, e.g. a denied `model.request` hook).
+     */
+    async chat(orgId, purpose, req, signal, opts = {}) {
+        let target;
+        try {
+            target = await this.resolve(orgId, purpose);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError && e.code === "model.unconfigured") || !opts.fallback)
+                throw e;
+            target = opts.fallback;
+        }
+        const { provider, info } = await this.d.registry.resolve(target.model);
+        const request = {
+            ...req,
+            model: info.id,
+            params: sanitizeParams(info.parameters, target.params).value,
+            // 输出上限不超过目标模型自己的上限（与运行时 assembleModelRequest 一致）
+            maxOutputTokens: Math.min(req.maxOutputTokens, info.maxOutputTokens),
+        };
+        const idleMs = info.streamIdleTimeoutMs ?? this.d.config().runtime.streamIdleMs;
+        await opts.beforeSend?.(target.model, request);
+        let chars = 0;
+        try {
+            const out = await consumeModelStream(provider, request, idleMs, signal, (ev) => {
+                chars += ev.text.length;
+            });
+            return {
+                content: out.content,
+                stopReason: out.stopReason,
+                usage: out.usage,
+                provider: target.model.provider,
+                model: target.model.model,
+            };
+        }
+        catch (err) {
+            const tokens = estimateTokens(request.messages, request.system, request.tools) + Math.ceil(chars / 4);
+            throw new PurposeAttemptError(err, tokens, target.model.provider, target.model.model);
+        }
+    }
+}