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

package/dist/log.d.ts

@@ -0,0 +1,48 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+/** 日志级别，按严重程度递增。 */
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+/** 日志级别。 */
+export type LogLevel = (typeof LOG_LEVELS)[number];
+/** 内核 logger：在插件 Logger 之上增加 debug、运行时改级别与登记需打码的密钥值。 */
+export interface KernelLogger extends Logger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    readonly level: LogLevel;
+    /** 修改级别；非法级别抛错且保持原级别。 */
+    setLevel(level: string): void;
+    /**
+     * 登记部署方（运维）给的密钥值：内核配置与插件部署级配置里的 secret 字段。此后日志消息与字段里出现这些值都替换为
+     * `[REDACTED]`（顶层的 `ts` / `level` 不打码）。字符串与数字（转成字符串）登记，布尔不登记；
+     * 数组与对象递归展开其中的标量；短于 4 个字符的值不登记（会误伤普通文本）。
+     * 数值字段的字符串形式等于已登记值时同样打码。
+     */
+    addSecrets(values: readonly unknown[]): void;
+    /**
+     * 登记组织级插件配置里的密钥值（来源是组织管理员，不完全可信）：只登记长度 ≥ 12 的值，
+     * 放在单独的有界集合里（默认最多 10000 个，满了淘汰最早登记的），防止任一租户用 `info` 这类短值
+     * 遮蔽其他租户的日志，也防止集合无限增长；只在字段里打码，不动顶层 `msg`。展开规则同 `addSecrets`。
+     */
+    addOrgSecrets(values: readonly unknown[]): void;
+    /**
+     * 按已登记的密钥（部署方与组织来源，同日志字段的规则）给一段文本打码；写到日志之外的地方（如 PG 里给后台看的
+     * 报错说明）之前用。
+     */
+    redact(text: string): string;
+}
+/**
+ * 用与 logger 相同的匹配器打码任意文本（工具结果等不经过日志的内容用）：展开规则同 `addOrgSecrets`
+ * （URL 形式的值另登记 `user:password@` 片段），只取长度 ≥ `minLength` 的值（默认 12，同组织来源密钥；
+ * 不得小于匹配器的分桶前缀长度 4）。没有可用的值时原样返回。
+ */
+export declare function createRedactor(values: readonly unknown[], minLength?: number): (s: string) => string;
+/**
+ * 创建结构化 JSON logger：每条日志写一行 `{ ts, level, msg, ...fields }`。
+ * 字段不能覆盖 ts / level / msg；Error 序列化为 name / message / stack；
+ * 经 `addSecrets` 登记的部署方密钥在消息与字段的任何字符串里都被打码；经 `addOrgSecrets` 登记的组织来源密钥
+ * 只在字段里打码，不动顶层 msg；顶层 ts / level 从不打码。
+ * `opts.orgSecretCapacity` 为组织来源密钥集合的容量（测试用）；`opts.onMatcherBuild` 在每次重建匹配器时调用（测试用）。
+ */
+export declare function createLogger(level?: string, opts?: {
+    write?: (line: string) => void;
+    orgSecretCapacity?: number;
+    onMatcherBuild?: () => void;
+}): KernelLogger;

package/dist/log.js

@@ -0,0 +1,229 @@
+import { secretScalars } from "./config/fields.js";
+/** 日志级别，按严重程度递增。 */
+export const LOG_LEVELS = ["debug", "info", "warn", "error"];
+const LEVELS = LOG_LEVELS;
+const REDACTED = "[REDACTED]";
+const RESERVED = new Set(["ts", "level", "msg"]);
+/** 部署方密钥的最短登记长度：过短的值打码会误伤普通文本。 */
+const MIN_SECRET_LEN = 4;
+/** 组织来源密钥的最短登记长度。 */
+const MIN_ORG_SECRET_LEN = 12;
+/** 组织来源密钥集合的默认容量。 */
+const ORG_SECRET_CAPACITY = 10_000;
+/** 匹配器按前缀分桶的前缀长度（不超过两种最短登记长度）。 */
+const PREFIX_LEN = MIN_SECRET_LEN;
+/**
+ * 编译后的打码匹配器：按值的前 `PREFIX_LEN` 个字符分桶，桶内按长度降序。扫描字符串时每个位置查一次桶、
+ * 记下最长命中的区间，重叠或相邻的区间合并后替换；开销与字符串长度成正比，与登记的密钥数基本无关。
+ */
+function compileMatcher(values) {
+    const buckets = new Map();
+    for (const v of values) {
+        const key = v.slice(0, PREFIX_LEN);
+        const b = buckets.get(key);
+        if (b)
+            b.push(v);
+        else
+            buckets.set(key, [v]);
+    }
+    if (buckets.size === 0)
+        return (s) => s;
+    for (const b of buckets.values())
+        b.sort((a, c) => c.length - a.length);
+    return (s) => {
+        if (s.length < PREFIX_LEN)
+            return s;
+        // 每个位置都记下最长命中的区间 [i, i + len)，不跳过（否则先开始的密钥会吞掉与之重叠的后一个密钥的开头，
+        // 使后者剩余部分明文输出）；重叠或相邻的区间合并后整段替换为一个 [REDACTED]。
+        let out = "";
+        let last = 0;
+        let runStart = -1;
+        let runEnd = -1;
+        for (let i = 0; i <= s.length - PREFIX_LEN; i++) {
+            const b = buckets.get(s.slice(i, i + PREFIX_LEN));
+            const hit = b?.find((v) => s.startsWith(v, i));
+            if (!hit)
+                continue;
+            const end = i + hit.length;
+            if (runStart >= 0 && i <= runEnd) {
+                if (end > runEnd)
+                    runEnd = end;
+                continue;
+            }
+            if (runStart >= 0) {
+                out += s.slice(last, runStart) + REDACTED;
+                last = runEnd;
+            }
+            runStart = i;
+            runEnd = end;
+        }
+        if (runStart < 0)
+            return s;
+        return out + s.slice(last, runStart) + REDACTED + s.slice(runEnd);
+    };
+}
+/**
+ * 用与 logger 相同的匹配器打码任意文本（工具结果等不经过日志的内容用）：展开规则同 `addOrgSecrets`
+ * （URL 形式的值另登记 `user:password@` 片段），只取长度 ≥ `minLength` 的值（默认 12，同组织来源密钥；
+ * 不得小于匹配器的分桶前缀长度 4）。没有可用的值时原样返回。
+ */
+export function createRedactor(values, minLength = MIN_ORG_SECRET_LEN) {
+    const min = Math.max(minLength, PREFIX_LEN);
+    const set = new Set();
+    for (const v of secretScalars(values)) {
+        for (const s of expandSecret(v))
+            if (s.length >= min)
+                set.add(s);
+    }
+    return compileMatcher(set);
+}
+function isLevel(v) {
+    return LEVELS.includes(v);
+}
+function parseLevel(v) {
+    if (!isLevel(v))
+        throw new Error(`invalid log level "${v}" (expected ${LEVELS.join(", ")})`);
+    return v;
+}
+/**
+ * URL 形式的密钥（连接串）另外登记 `user:password@` 片段：同一凭据可能以别的 host / 参数出现。
+ * 不单独登记裸密码——开发环境常见「密码 = 用户名 = 库名 = schema 名」，会把正常字段全部打码。
+ */
+function expandSecret(value) {
+    const out = [value];
+    try {
+        const u = new URL(value);
+        if (u.password)
+            out.push(`${u.username}:${u.password}@`);
+    }
+    catch {
+        // 不是 URL
+    }
+    return out;
+}
+/**
+ * 创建结构化 JSON logger：每条日志写一行 `{ ts, level, msg, ...fields }`。
+ * 字段不能覆盖 ts / level / msg；Error 序列化为 name / message / stack；
+ * 经 `addSecrets` 登记的部署方密钥在消息与字段的任何字符串里都被打码；经 `addOrgSecrets` 登记的组织来源密钥
+ * 只在字段里打码，不动顶层 msg；顶层 ts / level 从不打码。
+ * `opts.orgSecretCapacity` 为组织来源密钥集合的容量（测试用）；`opts.onMatcherBuild` 在每次重建匹配器时调用（测试用）。
+ */
+export function createLogger(level = "info", opts = {}) {
+    let current = parseLevel(level);
+    const write = opts.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const orgCapacity = opts.orgSecretCapacity ?? ORG_SECRET_CAPACITY;
+    /** 部署方密钥（数量由配置决定，不淘汰）。 */
+    const secrets = new Set();
+    /** 组织来源密钥：Set 保持插入顺序，重复登记时移到末尾，满了从头淘汰（LRU）。 */
+    const orgSecrets = new Set();
+    /** 字段用：两个集合的并集；任一集合变化后置空，下次打码时重建一次。 */
+    let matcher;
+    /** 顶层 msg 用：只含部署方密钥；部署方集合变化后置空。 */
+    let deployMatcher;
+    const redact = (s) => {
+        if (!matcher) {
+            matcher = compileMatcher(new Set([...secrets, ...orgSecrets]));
+            opts.onMatcherBuild?.();
+        }
+        return matcher(s);
+    };
+    /** 顶层 msg 只按部署方密钥打码：组织来源的值不能遮蔽日志消息。 */
+    const redactMsg = (s) => {
+        if (!deployMatcher) {
+            deployMatcher = compileMatcher(secrets);
+            opts.onMatcherBuild?.();
+        }
+        return deployMatcher(s);
+    };
+    const isSecret = (v) => secrets.has(v) || orgSecrets.has(v);
+    const serialize = (entry) => {
+        const seen = new WeakSet();
+        return JSON.stringify(entry, function (key, value) {
+            if (this === entry && RESERVED.has(key)) {
+                return key === "msg" && typeof value === "string" ? redactMsg(value) : value;
+            }
+            if (typeof value === "string")
+                return redact(value);
+            if ((typeof value === "number" || typeof value === "bigint") && isSecret(String(value))) {
+                return REDACTED;
+            }
+            if (value instanceof Error) {
+                const e = {
+                    name: value.name,
+                    message: value.message,
+                    stack: value.stack,
+                };
+                if (value.cause !== undefined)
+                    e.cause = value.cause;
+                return e;
+            }
+            if (typeof value === "bigint")
+                return value.toString();
+            if (typeof value === "object" && value !== null) {
+                if (seen.has(value))
+                    return "[Circular]";
+                seen.add(value);
+            }
+            return value;
+        });
+    };
+    const emit = (lvl, msg, fields) => {
+        if (LEVELS.indexOf(lvl) < LEVELS.indexOf(current))
+            return;
+        const entry = { ts: new Date().toISOString(), level: lvl, msg };
+        for (const [k, v] of Object.entries(fields ?? {}))
+            if (!RESERVED.has(k))
+                entry[k] = v;
+        let line;
+        try {
+            line = serialize(entry);
+        }
+        catch {
+            line = serialize({ ts: entry.ts, level: lvl, msg, logError: "unserializable fields" });
+        }
+        write(line);
+    };
+    return {
+        debug: (msg, fields) => emit("debug", msg, fields),
+        info: (msg, fields) => emit("info", msg, fields),
+        warn: (msg, fields) => emit("warn", msg, fields),
+        error: (msg, fields) => emit("error", msg, fields),
+        get level() {
+            return current;
+        },
+        redact: (text) => redact(text),
+        setLevel(l) {
+            current = parseLevel(l);
+        },
+        addSecrets(values) {
+            for (const v of secretScalars(values)) {
+                for (const s of expandSecret(v)) {
+                    if (s.length >= MIN_SECRET_LEN && !secrets.has(s)) {
+                        secrets.add(s);
+                        matcher = undefined;
+                        deployMatcher = undefined;
+                    }
+                }
+            }
+        },
+        addOrgSecrets(values) {
+            for (const v of secretScalars(values)) {
+                for (const s of expandSecret(v)) {
+                    if (s.length < MIN_ORG_SECRET_LEN)
+                        continue;
+                    if (orgSecrets.has(s)) {
+                        // 刷新位置，不改变集合内容，无需重建匹配器
+                        orgSecrets.delete(s);
+                        orgSecrets.add(s);
+                        continue;
+                    }
+                    orgSecrets.add(s);
+                    while (orgSecrets.size > orgCapacity) {
+                        orgSecrets.delete(orgSecrets.values().next().value);
+                    }
+                    matcher = undefined;
+                }
+            }
+        },
+    };
+}

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;
+    }>;
+}