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

package/dist/evals/runs.controller.js

@@ -0,0 +1,199 @@
+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, HttpCode, Inject, Param, Post, Put, Query } from "@nestjs/common";
+import { z } from "zod";
+import { ModelRef } from "../agents/definition.js";
+import { EVAL_RUNS } 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";
+const Candidate = z
+    .object({
+    agentVersion: z.number().int().min(1).optional(),
+    model: ModelRef.strict().optional(),
+    modelParams: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+    instructions: z.string().max(100_000).optional(),
+})
+    .strict();
+/** `tokenCap` 只校验类型，范围由服务判定（`eval.token_cap_invalid`）。 */
+const EstimateBody = z
+    .object({
+    mode: z.enum(["step", "run"]),
+    candidate: Candidate,
+    judge: z.boolean().default(false),
+    tokenCap: z.number().int().optional(),
+})
+    .strict();
+const StartBody = EstimateBody;
+/**
+ * `view=light`：不含内容块（结果表与轮询用，响应带 `asOf`）；缺省 `full`。`updatedSince`（ISO 时间）只取之后有变化的，
+ * 轮询时传上一次的 `asOf`。
+ */
+const ResultsQuery = z
+    .object({
+    after: z.string().max(100).optional(),
+    limit: z.coerce.number().int().min(1).max(200).default(50),
+    view: z.enum(["full", "light"]).default("full"),
+    updatedSince: z
+        .string()
+        .max(64)
+        .refine((v) => !Number.isNaN(Date.parse(v)), { message: "must be an ISO timestamp" })
+        .optional(),
+})
+    .strict();
+const LabelBody = z
+    .object({
+    label: z.enum(["pass", "fail"]).nullable(),
+    note: z.string().max(2000).optional(),
+})
+    .strict();
+/** 去掉 zod 输出里值为 undefined 的键（exactOptionalPropertyTypes）。 */
+function candidateOf(c) {
+    return {
+        ...(c.agentVersion !== undefined && { agentVersion: c.agentVersion }),
+        ...(c.model !== undefined && { model: c.model }),
+        ...(c.modelParams !== undefined && { modelParams: c.modelParams }),
+        ...(c.instructions !== undefined && { instructions: c.instructions }),
+    };
+}
+/**
+ * 评测运行（`/api/v1/orgs/:orgId/eval-sets/:setId/runs`、`/api/v1/orgs/:orgId/eval-runs/:runId[/results[/:resultId]]`）与
+ * 结果的人工标注（`/api/v1/orgs/:orgId/eval-results/:resultId/label`）：
+ * 全部 `evals.manage`（admin 起、只给人）。
+ */
+let EvalRunsController = class EvalRunsController {
+    runs;
+    constructor(runs) {
+        this.runs = runs;
+    }
+    async estimate(principal, org, setId, body) {
+        requireUser(principal);
+        return this.runs.estimate(org.orgId, setId, {
+            mode: body.mode,
+            candidate: candidateOf(body.candidate),
+            judge: body.judge,
+            ...(body.tokenCap !== undefined && { tokenCap: body.tokenCap }),
+        });
+    }
+    async start(principal, org, setId, body) {
+        const p = requireUser(principal);
+        const run = await this.runs.start(org.orgId, p.account.id, setId, {
+            mode: body.mode,
+            candidate: candidateOf(body.candidate),
+            judge: body.judge,
+            ...(body.tokenCap !== undefined && { tokenCap: body.tokenCap }),
+        }, patTokenId(p));
+        return { run };
+    }
+    async list(principal, org, setId) {
+        requireUser(principal);
+        return { runs: await this.runs.listForSet(org.orgId, setId) };
+    }
+    async get(principal, org, runId) {
+        requireUser(principal);
+        return { run: await this.runs.get(org.orgId, runId) };
+    }
+    async results(principal, org, runId, q) {
+        const p = requireUser(principal);
+        const query = {
+            limit: q.limit,
+            ...(q.after !== undefined && { after: q.after }),
+            ...(q.updatedSince !== undefined && { updatedSince: q.updatedSince }),
+        };
+        return q.view === "light"
+            ? this.runs.resultsLight(org.orgId, p.account.id, runId, query, patTokenId(p))
+            : this.runs.results(org.orgId, p.account.id, runId, query, patTokenId(p));
+    }
+    /** 一条结果的完整行（查看器按需读取）。 */
+    async result(principal, org, runId, resultId) {
+        const p = requireUser(principal);
+        return {
+            result: await this.runs.result(org.orgId, p.account.id, runId, resultId, patTokenId(p)),
+        };
+    }
+    async cancel(principal, org, runId) {
+        const p = requireUser(principal);
+        return { run: await this.runs.cancel(org.orgId, p.account.id, runId, patTokenId(p)) };
+    }
+    /** 人工标注一条结果：`label` 为 pass / fail，或 null 清除（备注随之清除）。 */
+    async label(principal, org, resultId, body) {
+        const p = requireUser(principal);
+        const result = await this.runs.label(org.orgId, p.account.id, resultId, { label: body.label, ...(body.note !== undefined && { note: body.note }) }, patTokenId(p));
+        return { result };
+    }
+};
+__decorate([
+    Post("eval-sets/:setId/runs/estimate"),
+    HttpCode(200),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("setId")),
+    __param(3, Body(new ZodPipe(EstimateBody)))
+], EvalRunsController.prototype, "estimate", null);
+__decorate([
+    Post("eval-sets/:setId/runs"),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("setId")),
+    __param(3, Body(new ZodPipe(StartBody)))
+], EvalRunsController.prototype, "start", null);
+__decorate([
+    Get("eval-sets/:setId/runs"),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("setId"))
+], EvalRunsController.prototype, "list", null);
+__decorate([
+    Get("eval-runs/:runId"),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("runId"))
+], EvalRunsController.prototype, "get", null);
+__decorate([
+    Get("eval-runs/:runId/results"),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("runId")),
+    __param(3, Query(new ZodPipe(ResultsQuery)))
+], EvalRunsController.prototype, "results", null);
+__decorate([
+    Get("eval-runs/:runId/results/:resultId"),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("runId")),
+    __param(3, Param("resultId"))
+], EvalRunsController.prototype, "result", null);
+__decorate([
+    Post("eval-runs/:runId/cancel"),
+    HttpCode(200),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("runId"))
+], EvalRunsController.prototype, "cancel", null);
+__decorate([
+    Put("eval-results/:resultId/label"),
+    OrgAction("evals.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("resultId")),
+    __param(3, Body(new ZodPipe(LabelBody)))
+], EvalRunsController.prototype, "label", null);
+EvalRunsController = __decorate([
+    Controller("api/v1/orgs/:orgId"),
+    __param(0, Inject(EVAL_RUNS))
+], EvalRunsController);
+export { EvalRunsController };

package/dist/evals/runs.service.d.ts

@@ -0,0 +1,275 @@
+import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { type AgentDefinition } from "../agents/definition.js";
+import type { KernelConfig } from "../config/schema.js";
+import { type Selection } from "../conversations/selection.js";
+import type { EvalResultStatus, EvalRunStatus, JudgeStatus, KernelDb } from "../db/kernel-schema.js";
+import type { SettingsService } from "../identity/settings.js";
+import { type PricesService } from "../models/prices.js";
+import type { ModelPurposesService } from "../models/purposes.js";
+import { type ProviderRegistry } from "../runtime/providers.js";
+import type { CaseSnapshot } from "./snapshot.js";
+import { type EvalCandidate } from "./step-replay.js";
+export type { EvalCandidate, EvalResultStatus, EvalRunStatus };
+/** 评测队列的 BullMQ 队列名（不含 `:`，C7）。 */
+export declare const EVAL_QUEUE_NAME = "cap-kernel-evals";
+/** 每个用例一个任务（C7；不含 `:`）。 */
+export declare const evalJobId: (runId: string, caseId: string) => string;
+/** 评测任务的数据。 */
+export interface EvalJobData {
+    runId: string;
+    caseId: string;
+    orgId: string;
+}
+/** 运行前的估算（D5：运行前显示预计请求数）。 */
+export interface EvalEstimate {
+    cases: number;
+    modelRequests: number;
+    judgeRequests: number;
+    /** 总数：候选请求 + 评委请求（{@link judgeTokens}）。达到上限的判断按它。 */
+    estimatedTokens: number;
+    /** 总成本：候选（按候选模型的价格）+ 评委；任一部分没有价格 → null。 */
+    estimatedCost: number | null;
+    /**
+     * 评委的份额（已含在总数里）：每条结果 = 系统提示词 + 评分标准 + 数据外壳 + 用户请求 + 两边回复（候选按与基线同量估算）
+     * + 输出上限 `min(评委模型上限, evals.judgeMaxOutputTokens)`。不开评委为 0。
+     */
+    judgeTokens: number;
+    /** 评委份额的成本，按 `eval` 用途生效的模型的价格；没有映射或没有价格 → null；不开评委为 0。 */
+    judgeCost: number | null;
+    currency: string;
+}
+/**
+ * 运行的汇总（F-C2：字段按 T6 的完整定义；比率无数据时为 null）。T4 只填计数，
+ * `toolCallsMatchRate` / `meanTextSimilarity` / `judgePassRate` / `humanPassRate` 由 T6 填。
+ */
+/** 估算响应里的 token 上限（D5）：部署默认、部署上限与本次生效的上限。 */
+export interface EvalTokenCaps {
+    defaultTokenCap: number;
+    maxTokenCap: number;
+    effectiveTokenCap: number;
+}
+export interface EvalSummary {
+    done: number;
+    errors: number;
+    skipped: number;
+    toolCallsMatchRate: number | null;
+    meanTextSimilarity: number | null;
+    judgePassRate: number | null;
+    /** 评委失败（解析失败 / 请求失败）的结果数。 */
+    judgeErrors: number;
+    humanPassRate: number | null;
+    labeled: number;
+    drifted: number;
+}
+export interface EvalRunView {
+    id: string;
+    setId: string;
+    mode: "step" | "run";
+    candidate: EvalCandidate;
+    judge: boolean;
+    status: EvalRunStatus;
+    tokenCap: number;
+    tokensUsed: number;
+    casesTotal: number;
+    casesDone: number;
+    estimate: EvalEstimate;
+    /** 运行结束后才有（queued / running 时为 null）。 */
+    summary: EvalSummary | null;
+    /** 运行 failed 的原因（如连续出错熔断 `eval.too_many_errors`；英文，界面按 code 走 i18n）。 */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    createdAt: string;
+    finishedAt: string | null;
+}
+/**
+ * 一条结果的轻量视图（结果表与轮询用）：不含基线 / 候选 / 差异 / 评委全文，只有状态与标量；完整内容按需读单条。
+ */
+export interface EvalResultLight {
+    id: string;
+    caseId: string;
+    step: number | null;
+    modelCallSeq: number | null;
+    status: EvalResultStatus;
+    judgeStatus: JudgeStatus;
+    /** 评委结论；没有结论（未评、失败）为 null。 */
+    verdict: "pass" | "fail" | null;
+    label: "pass" | "fail" | null;
+    driftCount: number;
+    /** 结果出错时的错误码。 */
+    errorCode: string | null;
+    /** 结构差异的两个标量（done 才有）。 */
+    toolCallsMatch: boolean | null;
+    textSimilarity: number | null;
+    updatedAt: string;
+}
+/** 一条结果（F-C1：与 `eval_results` 行一一对应，camelCase）。 */
+export interface EvalResultView {
+    id: string;
+    caseId: string;
+    step: number | null;
+    modelCallSeq: number | null;
+    status: EvalResultStatus;
+    baseline: unknown | null;
+    candidate: unknown | null;
+    diff: unknown | null;
+    judge: unknown | null;
+    /** 评委状态：none（不评）/ pending / done / error / skipped。 */
+    judgeStatus: JudgeStatus;
+    drift: string[];
+    error: unknown | null;
+    evalConversationId: string | null;
+    label: "pass" | "fail" | null;
+    labelNote: string | null;
+    labeledBy: string | null;
+    labeledAt: string | null;
+}
+/** 评测队列（生产方）：懒建连接；`close()` 关闭。 */
+export declare class EvalQueue {
+    private readonly redisUrl;
+    private readonly log;
+    private queue;
+    private conn;
+    private closed;
+    constructor(redisUrl: string, log: Pick<Logger, "error">);
+    private get;
+    enqueue(jobs: EvalJobData[]): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * 用例的原版本与定义：快照里的；快照缺（较早的快照）时查 `agent_versions`。The definition is the
+ * one the run used: with the person's model / effort switch in effect at its `run_started`
+ * applied (UI refresh B, `selectionAt`), which is also returned as `selection`.
+ */
+export declare function caseBase(db: KernelDb, s: CaseSnapshot): Promise<{
+    definition: AgentDefinition;
+    agentVersion: number;
+    selection: Selection;
+} | null>;
+/** 候选 agent 版本的定义（没给版本 → undefined）。 */
+export declare function versionDefinition(db: KernelDb, agentId: string, version: number | undefined): Promise<AgentDefinition | undefined>;
+/**
+ * 轻量列表的 `asOf`：本次读取时数据库的当前时间往前留的余量（毫秒）。下一次轮询以它为 `updatedSince`：
+ * 写结果的事务在读取之前开始、之后才提交时，`updated_at` 早于读取时间，留出余量才不会漏掉；重复的行由调用方按 id 合并。
+ */
+export declare const RESULTS_ASOF_OVERLAP_MS = 15000;
+export interface EvalRunsDeps {
+    db: KernelDb;
+    /** 查看结果审计的去重（`SET NX EX`）；不给时每次查看都写审计。 */
+    redis?: Pick<Redis, "set">;
+    config: () => KernelConfig;
+    registry: Pick<ProviderRegistry, "resolve">;
+    prices: Pick<PricesService, "table">;
+    settings: Pick<SettingsService, "get">;
+    queue: Pick<EvalQueue, "enqueue">;
+    /** 模型用途映射：开评委时 `eval` 用途必须已映射（否则 `model.unconfigured`）；估算按它给评委定价。 */
+    purposes: Pick<ModelPurposesService, "resolve">;
+}
+/**
+ * 评测运行（D5、C7）：估算、启动（校验候选、预建结果、每个用例入队一个任务）、查看、结果分页、取消。
+ * 执行在 `evals/worker.ts`。写操作在事务里锁组织行并复核角色（`evals.manage`）。
+ */
+export declare class EvalRunsService {
+    private readonly d;
+    constructor(d: EvalRunsDeps);
+    private liveSet;
+    /**
+     * 解析模型；不存在 / 不可用 → `eval.candidate_invalid`（供应商列表暂时失败照常抛出）。
+     * 按部署范围解析，与运行时一致；组织级模型准入若在第二段落地，须同样覆盖评测候选。
+     */
+    private resolveModel;
+    /**
+     * 校验候选：版本存在（该集合的 agent）、模型可解析、参数按所用模型的声明严格通过（`paramIssues`）。
+     * 所用模型 = 候选模型，否则候选版本的模型，否则 agent 当前版本的模型。返回候选版本的定义。
+     */
+    private checkCandidate;
+    /**
+     * 各用例的回放计划与成本：只读写入时存好的列（`plan_step` / `plan_run`、`base_model`），不读快照。
+     * 给了候选参数时按每个用例实际所用的模型严格校验（同一模型在一次调用里只解析一次）。
+     */
+    private plan;
+    /**
+     * 评委份额的估算设置（不开评委 → null）：输出上限 `min(评委模型上限, evals.judgeMaxOutputTokens)`、评委模型的价格。
+     * `eval` 用途没有映射时照常估算 token（按配置的上限），成本未知。
+     */
+    private judgePricing;
+    /** 估算只算会发请求的用例（候选不合法的用例不发请求）；开评委时评委份额单列，也计入总数。 */
+    private summarize;
+    /**
+     * 集合的 agent 已删除 → `agent.not_found`（删除 agent 会取消它的运行；之后再估算 / 启动只会建出全部跳过的运行）。
+     * 在事务里调用时 FOR SHARE，与删除 agent 互斥。
+     */
+    private assertAgentLive;
+    estimate(orgId: string, setId: string, input: {
+        mode: "step" | "run";
+        candidate: EvalCandidate;
+        judge: boolean;
+        tokenCap?: number;
+    }): Promise<{
+        estimate: EvalEstimate;
+    } & EvalTokenCaps>;
+    /** token 上限：给了就校验 [1, `evals.maxTokenCap`]，缺省 `evals.defaultTokenCap`（D5）。 */
+    private tokenCaps;
+    /**
+     * 启动：校验 token 上限（[1, `evals.maxTokenCap`]，缺省 `evals.defaultTokenCap`）、候选、评委用途；
+     * 没有可回放的 → `eval.nothing_to_replay`。事务内建运行行、预建 pending 结果，提交后每个用例入队一个任务；
+     * 入队失败 → 运行标 failed、结果 skipped，错误照常抛出。
+     */
+    start(orgId: string, actor: string, setId: string, input: {
+        mode: "step" | "run";
+        candidate: EvalCandidate;
+        judge: boolean;
+        tokenCap?: number;
+    }, actorTokenId?: string): Promise<EvalRunView>;
+    /** 各运行的汇总（只算已结束的）。 */
+    private summaries;
+    private static toView;
+    get(orgId: string, runId: string): Promise<EvalRunView>;
+    listForSet(orgId: string, setId: string): Promise<EvalRunView[]>;
+    /**
+     * 查看结果的审计 `eval.results_viewed`（结果里有回放出来的对话内容）：每位查看者每次运行每小时一条——Redis
+     * `SET NX EX` 去重（多副本共享），轻量轮询因此不会刷审计。Redis 不可用时照写（宁多不漏）。
+     */
+    private viewed;
+    /** 结果分页的公共部分：按 id 升序，`after` 为上一页最后一条的 id；`updatedSince` 只取之后有变化的。 */
+    private resultsQuery;
+    /** 结果分页（完整行）：按 id 升序，`after` 为上一页最后一条的 id。写查看审计（去重见 {@link viewed}）。 */
+    results(orgId: string, actor: string, runId: string, q: {
+        after?: string;
+        limit: number;
+        updatedSince?: string;
+    }, actorTokenId?: string): Promise<{
+        results: EvalResultView[];
+        next: string | null;
+    }>;
+    /**
+     * 结果分页（轻量，结果表与轮询用）：不含内容块。`asOf` 作为下一次轮询的 `updatedSince`（已留余量，
+     * 见 {@link RESULTS_ASOF_OVERLAP_MS}；重复的行由调用方按 id 合并）。
+     */
+    resultsLight(orgId: string, actor: string, runId: string, q: {
+        after?: string;
+        limit: number;
+        updatedSince?: string;
+    }, actorTokenId?: string): Promise<{
+        results: EvalResultLight[];
+        next: string | null;
+        asOf: string;
+    }>;
+    /** 一条结果的完整行（查看器按需读取）；不在该运行 / 本组织 → `eval.result_not_found`。写查看审计（去重）。 */
+    result(orgId: string, actor: string, runId: string, resultId: string, actorTokenId?: string): Promise<EvalResultView>;
+    /**
+     * 取消：queued / running → cancelled，尚未开始的结果立即 skipped；在途请求做完照常写入（C7 在途可超出），
+     * 之后的请求不再发。已结束 → `eval.run_finished`。
+     */
+    cancel(orgId: string, actor: string, runId: string, actorTokenId?: string): Promise<EvalRunView>;
+    /**
+     * 人工标注（D3）：标通过 / 不通过（附可选备注），`label: null` 清除标注与备注。评测集已删除、结果不属于本组织 →
+     * `eval.result_not_found`。事务内锁组织并复核 `evals.manage`，写审计 `eval.result_labeled`（不含备注全文）。
+     */
+    label(orgId: string, actor: string, resultId: string, input: {
+        label: "pass" | "fail" | null;
+        note?: string;
+    }, actorTokenId?: string): Promise<EvalResultView>;
+}