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

package/dist/errors.js

@@ -0,0 +1,212 @@
+/**
+ * API 错误码与对应的 HTTP 状态码。错误响应统一为 `{ error: { code, message, details? } }`：
+ * `message` 为英文，界面文案以 `code` 为 key 走 i18n。后续任务往这里追加错误码。
+ */
+export const ERROR_CODES = {
+    internal: 500,
+    not_found: 404,
+    validation_failed: 400,
+    forbidden: 403,
+    conflict: 409,
+    payload_too_large: 413,
+    unsupported_media_type: 415,
+    rate_limited: 429,
+    "account.login_taken": 409,
+    "account.not_found": 404,
+    "account.last_enterprise_admin": 409,
+    "auth.account_disabled": 403,
+    "auth.required": 401,
+    "auth.token_expired": 401,
+    "auth.session_revoked": 401,
+    "auth.refresh_invalid": 401,
+    "auth.refresh_race": 401,
+    "auth.invalid_credentials": 401,
+    "auth.csrf": 403,
+    "auth.rate_limited": 429,
+    "auth.session_required": 403,
+    "token.not_found": 404,
+    "org.not_found": 404,
+    "org.creation_disabled": 403,
+    "org.slug_taken": 409,
+    "org.last_owner": 409,
+    "org.owner_required": 403,
+    "org.sandbox_egress_not_allowed": 400,
+    "member.not_found": 404,
+    "member.already_exists": 409,
+    "member.anonymous_guest": 409,
+    "invitation.invalid": 404,
+    "invitation.expired": 410,
+    "invitation.used": 409,
+    "extension.not_found": 404,
+    "extension.unavailable": 503,
+    "extension.no_org_config": 400,
+    "extension.config_invalid": 400,
+    "extension.config_readonly": 409,
+    "extension.dependency_missing": 409,
+    "extension.has_dependents": 409,
+    "extension.not_enabled": 409,
+    "extension.package_invalid": 400,
+    "extension.legacy_format": 422,
+    "extension.no_extension": 400,
+    "extension.package_too_large": 413,
+    "extension.config_declared": 409,
+    "extension.required": 409,
+    "extension.name_conflict": 409,
+    "extension.approval_stale": 409,
+    "extension.not_pending": 409,
+    "extension.package_unavailable": 409,
+    "extension.package_not_found": 404,
+    "extension.name_mismatch": 409,
+    "extension.downgrade_unsupported": 409,
+    "extension.not_disabled": 409,
+    "packages.npm_failed": 502,
+    "bootstrap.integrity_mismatch": 500,
+    "bootstrap.missing_file": 500,
+    "catalog.invalid_manifest": 422,
+    "catalog.legacy_format": 422,
+    "catalog.no_extension": 409,
+    "catalog.dependency_unresolved": 409,
+    "catalog.dependency_disabled": 409,
+    "catalog.dependency_cycle": 409,
+    "catalog.version_exists": 409,
+    "catalog.item_not_found": 404,
+    "catalog.name_conflict": 409,
+    "directory.not_configured": 409,
+    "catalog.item_disabled": 403,
+    "catalog.approval_required": 403,
+    "catalog.request_not_found": 404,
+    "catalog.request_decided": 409,
+    "catalog.custom_disabled": 403,
+    "catalog.not_deployed": 409,
+    "catalog.icon_not_found": 404,
+    "marketplace.not_found": 404,
+    "marketplace.entry_not_found": 404,
+    "marketplace.fetch_failed": 502,
+    "marketplace.invalid": 502,
+    "marketplace.integrity_mismatch": 502,
+    "marketplace.private_address": 422,
+    "marketplace.redirect": 422,
+    "marketplace.incompatible": 409,
+    "marketplace.package_mismatch": 409,
+    "marketplace.builtin": 409,
+    "marketplace.git_failed": 502,
+    "marketplace.git_too_large": 422,
+    "marketplace.git_unsupported_entry": 422,
+    "marketplace.host_not_allowed": 403,
+    "marketplace.path_unsupported": 422,
+    "plugin.review_stale": 409,
+    "plugin.staging_not_found": 404,
+    "plugin.install_failed": 502,
+    "plugin.install_not_found": 404,
+    "plugin.already_installed": 409,
+    "plugin.install_in_progress": 409,
+    "plugin.skill_conflict": 409,
+    "plugin.upgrade_stale": 409,
+    "plugin.upgrade_target_invalid": 409,
+    "plugin.upgrade_failed": 502,
+    "setup.already_completed": 409,
+    "setup.token_invalid": 403,
+    "agent.not_found": 404,
+    "agent.version_conflict": 409,
+    "agent.model_unavailable": 400,
+    /**
+     * `skills.pinned` of an agent definition is refused (details: `{ skill, reason, totalBytes? }`;
+     * reasons `not_selected`, `not_found`, `duplicate`, `too_many`, `too_large`, `manual_only`).
+     */
+    "agent.pinned_invalid": 400,
+    /** `subagents` of an agent definition is refused (details: `{ reason, path, value? }`). */
+    "agent.subagents_invalid": 400,
+    "conversation.not_found": 404,
+    "conversation.output_not_found": 404,
+    "conversation.artifact_not_found": 404,
+    "conversation.artifact_not_previewable": 400,
+    /** A file output whose stored object is gone (UI refresh B, decision 8). */
+    "conversation.artifact_removed": 410,
+    /** The conversation already holds `QUEUE_MAX_ITEMS` queued messages (UI refresh B). */
+    "conversation.queue_full": 409,
+    "conversation.queue_item_not_found": 404,
+    /** A sub-agent's conversation takes no messages from people (sub-agents spec §6.1). */
+    "conversation.read_only": 409,
+    "run.not_active": 409,
+    "connector.not_found": 404,
+    "connector.slug_taken": 409,
+    "connector.connect_failed": 502,
+    "connector.tool_not_found": 404,
+    "connector.tool_not_pending": 409,
+    "connector.resources_disabled": 409,
+    "approval.not_found": 404,
+    "approval.already_decided": 409,
+    "question.not_found": 404,
+    "question.already_answered": 409,
+    "tool_output.not_found": 404,
+    "credential.missing": 409,
+    "identity.taken": 409,
+    "identity.not_found": 404,
+    "identity.last_login_method": 409,
+    "bind.invalid": 404,
+    "channel.not_found": 404,
+    "channel.verify_failed": 502,
+    "channel.webhook_not_found": 404,
+    "channel.webhook_unavailable": 409,
+    "channel.webhook_retry": 503,
+    "ui.not_found": 404,
+    "ui.render_failed": 502,
+    "ui.action_failed": 502,
+    "ui.invalid_view": 502,
+    "ui.timeout": 504,
+    "storage.unavailable": 503,
+    "attachment.not_found": 404,
+    "attachment.not_ready": 409,
+    "attachment.too_large": 413,
+    "attachment.type_not_allowed": 415,
+    "attachment.too_many_pending": 429,
+    "sandbox.unavailable": 503,
+    "sandbox.busy": 409,
+    "sandbox.not_found": 404,
+    "skill.not_found": 404,
+    /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
+    "skill.invalid_package": 400,
+    /**
+     * A person invoked a skill (`/name`, phase D) that is not one of the agent's effective skills
+     * (`details: [{ reason: "not_found" }]`) or is hidden from the menu (`not_user_invocable`).
+     */
+    "skill.not_invocable": 400,
+    "skill_change.not_found": 404,
+    "skill_change.not_owner": 403,
+    "skill_change.already_decided": 409,
+    "trajectory.not_found": 404,
+    "eval.run_not_finished": 409,
+    "eval.case_too_large": 413,
+    "eval.call_not_found": 404,
+    "eval.set_not_found": 404,
+    "eval.case_not_found": 404,
+    "eval.case_exists": 409,
+    "eval.too_many_cases": 409,
+    "eval.agent_mismatch": 409,
+    "eval.run_not_found": 404,
+    "eval.token_cap_invalid": 400,
+    "eval.run_finished": 409,
+    "eval.nothing_to_replay": 409,
+    "eval.candidate_invalid": 400,
+    "model.unconfigured": 409,
+    "model.purpose_unknown": 404,
+    "eval.result_not_found": 404,
+};
+/** 业务代码抛出的 API 错误；由 HTTP 层的错误过滤器转成错误信封。 */
+export class ApiError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ApiError";
+    }
+    get status() {
+        return ERROR_CODES[this.code];
+    }
+}
+/** 错误信封的 body。 */
+export function errorBody(code, message, details) {
+    return { error: { code, message, ...(details !== undefined && { details }) } };
+}

package/dist/evals/budget.d.ts

@@ -0,0 +1,61 @@
+import type { ModelUsage } from "@capybara-hq/plugin-sdk";
+import type { KernelDb } from "../db/kernel-schema.js";
+/**
+ * 评测运行的 token 预算（C7）：`eval_runs.tokens_used` 在 PG 里原子累加，达到 `token_cap` 的同一条语句把
+ * 状态置为 `capped`；worker 每次请求前查 {@link runActive}，不活跃就不再发新请求。在途请求可以越过上限，
+ * 每个并发任务最多多一次请求（超出量 ≤ 在途任务数 × 一次请求）。
+ */
+/** 还在执行的运行状态。 */
+export declare const ACTIVE_EVAL_STATUSES: readonly ["queued", "running"];
+/** 一次请求计入预算的 token：用量四项之和（四项互不重叠，见 plugin-sdk `ModelUsage`）。 */
+export declare const usageTokens: (u: ModelUsage) => number;
+/**
+ * 累加用量：`UPDATE … RETURNING`，累加后 ≥ 上限且运行仍在执行 → 同一语句置 `capped`、记 `finished_at`。
+ * 运行已不在（被删）时返回 `{ used: 0, capped: true }`，调用方同样停下。
+ */
+export declare function consumeTokens(db: KernelDb, runId: string, tokens: number): Promise<{
+    used: number;
+    capped: boolean;
+}>;
+/** 连续出错熔断时运行记的原因（英文；界面按 code 走 i18n）。 */
+export declare const TOO_MANY_ERRORS: {
+    readonly code: "eval.too_many_errors";
+    readonly message: "The eval run stopped after too many consecutive failed results";
+};
+/**
+ * 记一条结果的结局（熔断，C7 之外的保护）：出错 → `consecutive_errors + 1`，达到 `maxConsecutive` 且运行仍在执行时
+ * 同一语句置 `failed`、记原因与 `finished_at`；成功 → 清零。返回运行是否因此被熔断。
+ * 多个任务并发时「连续」按写入顺序计（近似），足以挡住「每个请求都失败」的运行。
+ */
+export declare function recordOutcome(db: KernelDb, runId: string, ok: boolean, maxConsecutive: number): Promise<{
+    tripped: boolean;
+}>;
+/**
+ * 运行停下（取消 / 越限 / 熔断 / 删除评测集）时：还在等评委的结果（`judge_status = 'pending'`）记 `skipped`，
+ * 否则这些用例永远算不上做完。给了 `caseId` 只处理该用例。在途的评委请求做完后写不进来（条件是 pending），用量照样计入。
+ */
+export declare function skipPendingJudges(db: KernelDb, runId: string, caseId?: string): Promise<void>;
+/**
+ * 重算 `cases_done` = 结果全部结束、且没有等评委的结果的用例数（幂等：任务重做不会重复计数），达到 `cases_total` 且运行仍在执行 →
+ * `completed`。先锁运行行再数（READ COMMITTED 下新语句看得到其他任务已提交的结果），并发完成的任务不会互相覆盖。
+ * worker 每做完一个用例、取消、入队失败时都调用。在事务里调用时锁随事务释放。
+ */
+export declare function recountCases(db: KernelDb, runId: string): Promise<void>;
+/**
+ * 运行仍在执行（queued / running），且所属组织与评测集的 agent 都没有删除：取消、达到上限、已结束、运行行已删除、
+ * 组织或 agent 已删除都为 false（删除组织 / agent 时会显式取消运行，这里再兜一次底，挡住删除与请求之间的竞争）。
+ */
+export declare function runActive(db: KernelDb, runId: string): Promise<boolean>;
+/**
+ * 删除组织或 agent 时（调用方的事务内）取消其在执行的评测运行：运行置 `cancelled`，未开始的结果 `skipped`、
+ * 等评委的记 `skipped`，重算进度，每个运行写审计 `eval.run_cancelled`（detail 带原因）。在途请求做完后写不进新的请求
+ * （worker 每次请求前查 {@link runActive}）。运行创建者离开组织不取消（Ruling S1-b：管理员的评测运行是组织的工作）。
+ */
+export declare function cancelEvalRuns(trx: KernelDb, scope: {
+    orgId: string;
+    agentId?: string;
+}, actor: {
+    accountId: string;
+    tokenId?: string;
+}, reason: "org_deleted" | "agent_deleted"): Promise<string[]>;
+export declare const addUsage: (a: ModelUsage, b: ModelUsage) => ModelUsage;

package/dist/evals/budget.js

@@ -0,0 +1,181 @@
+import { sql } from "kysely";
+import { audit } from "../identity/audit.js";
+/**
+ * 评测运行的 token 预算（C7）：`eval_runs.tokens_used` 在 PG 里原子累加，达到 `token_cap` 的同一条语句把
+ * 状态置为 `capped`；worker 每次请求前查 {@link runActive}，不活跃就不再发新请求。在途请求可以越过上限，
+ * 每个并发任务最多多一次请求（超出量 ≤ 在途任务数 × 一次请求）。
+ */
+/** 还在执行的运行状态。 */
+export const ACTIVE_EVAL_STATUSES = ["queued", "running"];
+/** 一次请求计入预算的 token：用量四项之和（四项互不重叠，见 plugin-sdk `ModelUsage`）。 */
+export const usageTokens = (u) => u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheWriteTokens;
+/**
+ * 累加用量：`UPDATE … RETURNING`，累加后 ≥ 上限且运行仍在执行 → 同一语句置 `capped`、记 `finished_at`。
+ * 运行已不在（被删）时返回 `{ used: 0, capped: true }`，调用方同样停下。
+ */
+export async function consumeTokens(db, runId, tokens) {
+    const n = Math.max(0, Math.trunc(tokens));
+    const reaches = sql `tokens_used + ${n} >= token_cap AND status IN ('queued', 'running')`;
+    const r = await db
+        .updateTable("eval_runs")
+        .set({
+        tokens_used: sql `tokens_used + ${n}`,
+        status: sql `CASE WHEN ${reaches} THEN 'capped' ELSE status END`,
+        finished_at: sql `CASE WHEN ${reaches} THEN now() ELSE finished_at END`,
+    })
+        .where("id", "=", runId)
+        .returning(["tokens_used", "status"])
+        .executeTakeFirst();
+    if (!r)
+        return { used: 0, capped: true };
+    return { used: Number(r.tokens_used), capped: r.status === "capped" };
+}
+/** 连续出错熔断时运行记的原因（英文；界面按 code 走 i18n）。 */
+export const TOO_MANY_ERRORS = {
+    code: "eval.too_many_errors",
+    message: "The eval run stopped after too many consecutive failed results",
+};
+/**
+ * 记一条结果的结局（熔断，C7 之外的保护）：出错 → `consecutive_errors + 1`，达到 `maxConsecutive` 且运行仍在执行时
+ * 同一语句置 `failed`、记原因与 `finished_at`；成功 → 清零。返回运行是否因此被熔断。
+ * 多个任务并发时「连续」按写入顺序计（近似），足以挡住「每个请求都失败」的运行。
+ */
+export async function recordOutcome(db, runId, ok, maxConsecutive) {
+    if (ok) {
+        await db
+            .updateTable("eval_runs")
+            .set({ consecutive_errors: 0 })
+            .where("id", "=", runId)
+            .where("consecutive_errors", ">", 0)
+            .execute();
+        return { tripped: false };
+    }
+    const trips = sql `consecutive_errors + 1 >= ${maxConsecutive} AND status IN ('queued', 'running')`;
+    const r = await db
+        .updateTable("eval_runs")
+        .set({
+        consecutive_errors: sql `consecutive_errors + 1`,
+        status: sql `CASE WHEN ${trips} THEN 'failed' ELSE status END`,
+        error: sql `CASE WHEN ${trips} THEN ${JSON.stringify(TOO_MANY_ERRORS)}::jsonb ELSE error END`,
+        finished_at: sql `CASE WHEN ${trips} THEN now() ELSE finished_at END`,
+    })
+        .where("id", "=", runId)
+        .returning(["status", "error"])
+        .executeTakeFirst();
+    const tripped = r?.status === "failed" && r.error?.code === TOO_MANY_ERRORS.code;
+    // 熔断：整个运行还在等的评委都记 skipped（与取消一致；在途的评委做完后写不进来）
+    if (tripped)
+        await skipPendingJudges(db, runId);
+    return { tripped };
+}
+/**
+ * 运行停下（取消 / 越限 / 熔断 / 删除评测集）时：还在等评委的结果（`judge_status = 'pending'`）记 `skipped`，
+ * 否则这些用例永远算不上做完。给了 `caseId` 只处理该用例。在途的评委请求做完后写不进来（条件是 pending），用量照样计入。
+ */
+export async function skipPendingJudges(db, runId, caseId) {
+    let q = db
+        .updateTable("eval_results")
+        .set({ judge_status: "skipped", updated_at: sql `now()` })
+        .where("run_id", "=", runId)
+        .where("judge_status", "=", "pending");
+    if (caseId !== undefined)
+        q = q.where("case_id", "=", caseId);
+    await q.execute();
+}
+/**
+ * 重算 `cases_done` = 结果全部结束、且没有等评委的结果的用例数（幂等：任务重做不会重复计数），达到 `cases_total` 且运行仍在执行 →
+ * `completed`。先锁运行行再数（READ COMMITTED 下新语句看得到其他任务已提交的结果），并发完成的任务不会互相覆盖。
+ * worker 每做完一个用例、取消、入队失败时都调用。在事务里调用时锁随事务释放。
+ */
+export async function recountCases(db, runId) {
+    const run = async (trx) => {
+        const row = await trx
+            .selectFrom("eval_runs")
+            .select(["cases_total", "status"])
+            .where("id", "=", runId)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row)
+            return;
+        const r = await sql `
+      SELECT count(*) AS n FROM (
+        SELECT case_id FROM capybara.eval_results WHERE run_id = ${runId}
+        GROUP BY case_id
+        HAVING bool_and(status IN ('done', 'error', 'skipped') AND judge_status <> 'pending')
+      ) finished`.execute(trx);
+        const done = Number(r.rows[0]?.n ?? 0);
+        const complete = done >= row.cases_total && ACTIVE_EVAL_STATUSES.includes(row.status);
+        await trx
+            .updateTable("eval_runs")
+            .set({
+            cases_done: done,
+            ...(complete && { status: "completed", finished_at: sql `now()` }),
+        })
+            .where("id", "=", runId)
+            .execute();
+    };
+    if (db.isTransaction)
+        await run(db);
+    else
+        await db.transaction().execute((trx) => run(trx));
+}
+/**
+ * 运行仍在执行（queued / running），且所属组织与评测集的 agent 都没有删除：取消、达到上限、已结束、运行行已删除、
+ * 组织或 agent 已删除都为 false（删除组织 / agent 时会显式取消运行，这里再兜一次底，挡住删除与请求之间的竞争）。
+ */
+export async function runActive(db, runId) {
+    const r = await db
+        .selectFrom("eval_runs as r")
+        .innerJoin("eval_sets as s", "s.id", "r.set_id")
+        .innerJoin("agents as a", "a.id", "s.agent_id")
+        .innerJoin("orgs as o", "o.id", "r.org_id")
+        .select("r.id")
+        .where("r.id", "=", runId)
+        .where("r.status", "in", [...ACTIVE_EVAL_STATUSES])
+        .where("a.deleted_at", "is", null)
+        .where("o.deleted_at", "is", null)
+        .executeTakeFirst();
+    return r !== undefined;
+}
+/**
+ * 删除组织或 agent 时（调用方的事务内）取消其在执行的评测运行：运行置 `cancelled`，未开始的结果 `skipped`、
+ * 等评委的记 `skipped`，重算进度，每个运行写审计 `eval.run_cancelled`（detail 带原因）。在途请求做完后写不进新的请求
+ * （worker 每次请求前查 {@link runActive}）。运行创建者离开组织不取消（Ruling S1-b：管理员的评测运行是组织的工作）。
+ */
+export async function cancelEvalRuns(trx, scope, actor, reason) {
+    let q = trx
+        .updateTable("eval_runs")
+        .set({ status: "cancelled", finished_at: sql `now()` })
+        .where("org_id", "=", scope.orgId)
+        .where("status", "in", [...ACTIVE_EVAL_STATUSES]);
+    if (scope.agentId !== undefined) {
+        const agentId = scope.agentId;
+        q = q.where("set_id", "in", (eb) => eb.selectFrom("eval_sets").select("id").where("agent_id", "=", agentId));
+    }
+    const runs = await q.returning("id").execute();
+    for (const r of runs) {
+        await trx
+            .updateTable("eval_results")
+            .set({ status: "skipped", updated_at: sql `now()` })
+            .where("run_id", "=", r.id)
+            .where("status", "=", "pending")
+            .execute();
+        await skipPendingJudges(trx, r.id);
+        await recountCases(trx, r.id);
+        await audit(trx, {
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
+            orgId: scope.orgId,
+            action: "eval.run_cancelled",
+            target: r.id,
+            detail: { reason },
+        });
+    }
+    return runs.map((r) => r.id);
+}
+export const addUsage = (a, b) => ({
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+    cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+});

package/dist/evals/diff.d.ts

@@ -0,0 +1,55 @@
+import type { ContentBlock } from "@capybara-hq/plugin-sdk";
+/**
+ * 评分的结构差异（D3）：基线与候选的工具调用（名字与参数）、回复文本的相似度、停止原因。纯函数，不发请求。
+ * - 工具调用先按名字做 LCS 对齐（中间插入 / 删除一个调用不会让后面的全部错位）：对上的同名调用参数相同为
+ *   `same`（参数按规范化 JSON 比较，键顺序不同也算相同），否则 `args_changed`；两个对齐点之间多出来的
+ *   按位置配对为 `name_changed`，剩下的是 `added`（只在候选）/ `removed`（只在基线）；
+ *   两边调用数之积超过 {@link MAX_ALIGN_CELLS} 时不做对齐（DP 表是 O(n·m)），改为按位置逐个比较；
+ * - 文本相似度见 {@link textSimilarity}（C8）。
+ */
+export interface ToolCallDiffEntry {
+    index: number;
+    kind: "same" | "args_changed" | "name_changed" | "added" | "removed";
+    baseline?: {
+        name: string;
+        input: unknown;
+    };
+    candidate?: {
+        name: string;
+        input: unknown;
+    };
+}
+export interface StructuralDiff {
+    toolCalls: ToolCallDiffEntry[];
+    toolCallsMatch: boolean;
+    textSimilarity: number;
+    stopReasonMatch: boolean;
+}
+type Call = {
+    name: string;
+    input: unknown;
+};
+/** 词数之积超过它时只比是否相等（C8：LCS 是 O(n·m)）。 */
+export declare const MAX_LCS_CELLS = 4000000;
+/** 工具调用数之积超过它时按位置比较，不做名字对齐。 */
+export declare const MAX_ALIGN_CELLS = 1000000;
+/**
+ * 文本相似度（C8）：按空白切词，`2·LCS / (|a| + |b|)`；两边都没有词为 1；词数之积超过 {@link MAX_LCS_CELLS}
+ * 时只比是否相等（1 或 0）。
+ */
+export declare function textSimilarity(a: string, b: string): number;
+export declare function structuralDiff(baseline: {
+    toolCalls: Call[];
+    text: string;
+    stopReason: string | null;
+}, candidate: {
+    toolCalls: Call[];
+    text: string;
+    stopReason: string | null;
+}): StructuralDiff;
+/** 一条回复的工具调用与文本（文本块用换行连接；thinking 不算回复）。 */
+export declare function replyParts(content: readonly ContentBlock[]): {
+    toolCalls: Call[];
+    text: string;
+};
+export {};

package/dist/evals/diff.js

@@ -0,0 +1,133 @@
+import { matchKey } from "./recorded-tools.js";
+/** 词数之积超过它时只比是否相等（C8：LCS 是 O(n·m)）。 */
+export const MAX_LCS_CELLS = 4_000_000;
+const words = (s) => s.split(/\s+/).filter((w) => w.length > 0);
+/** 工具调用数之积超过它时按位置比较，不做名字对齐。 */
+export const MAX_ALIGN_CELLS = 1_000_000;
+/** 两个序列的 LCS 长度（两行滚动数组，行长取较短的一边）。 */
+function lcsLength(x, y, eq) {
+    const [a, b] = x.length >= y.length ? [x, y] : [y, x];
+    let prev = new Array(b.length + 1).fill(0);
+    let cur = new Array(b.length + 1).fill(0);
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            cur[j] = eq(a[i - 1], b[j - 1])
+                ? prev[j - 1] + 1
+                : Math.max(prev[j], cur[j - 1]);
+        }
+        [prev, cur] = [cur, prev];
+    }
+    return prev[b.length];
+}
+/**
+ * 文本相似度（C8）：按空白切词，`2·LCS / (|a| + |b|)`；两边都没有词为 1；词数之积超过 {@link MAX_LCS_CELLS}
+ * 时只比是否相等（1 或 0）。
+ */
+export function textSimilarity(a, b) {
+    const x = words(a);
+    const y = words(b);
+    if (x.length === 0 && y.length === 0)
+        return 1;
+    if (x.length === 0 || y.length === 0)
+        return 0;
+    if (x.length * y.length > MAX_LCS_CELLS) {
+        return x.length === y.length && x.every((w, i) => w === y[i]) ? 1 : 0;
+    }
+    return (2 * lcsLength(x, y, (p, q) => p === q)) / (x.length + y.length);
+}
+/** 按名字的 LCS 对齐：返回对上的下标对（升序）。 */
+function alignByName(a, b) {
+    const n = a.length;
+    const m = b.length;
+    if (n * m > MAX_ALIGN_CELLS) {
+        // 规模过大：按位置比较（同一位置同名的算对上，其余由 gap 按位置配对为 name_changed / added / removed）
+        const pairs = [];
+        for (let i = 0; i < Math.min(n, m); i++)
+            if (a[i]?.name === b[i]?.name)
+                pairs.push([i, i]);
+        return pairs;
+    }
+    // 工具调用数通常很少，完整 DP 表即可
+    const t = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            const row = t[i];
+            row[j] =
+                a[i]?.name === b[j]?.name
+                    ? t[i + 1][j + 1] + 1
+                    : Math.max(t[i + 1][j], row[j + 1]);
+        }
+    }
+    const pairs = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i]?.name === b[j]?.name) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (t[i + 1][j] >= t[i][j + 1]) {
+            i++;
+        }
+        else {
+            j++;
+        }
+    }
+    return pairs;
+}
+function diffToolCalls(a, b) {
+    const kinds = [];
+    const gap = (ai, aEnd, bj, bEnd) => {
+        while (ai < aEnd && bj < bEnd) {
+            kinds.push({
+                kind: "name_changed",
+                baseline: a[ai],
+                candidate: b[bj],
+            });
+            ai++;
+            bj++;
+        }
+        for (; ai < aEnd; ai++)
+            kinds.push({ kind: "removed", baseline: a[ai] });
+        for (; bj < bEnd; bj++)
+            kinds.push({ kind: "added", candidate: b[bj] });
+    };
+    let i = 0;
+    let j = 0;
+    for (const [pi, pj] of alignByName(a, b)) {
+        gap(i, pi, j, pj);
+        const x = a[pi];
+        const y = b[pj];
+        kinds.push({
+            kind: matchKey(x.name, x.input) === matchKey(y.name, y.input) ? "same" : "args_changed",
+            baseline: x,
+            candidate: y,
+        });
+        i = pi + 1;
+        j = pj + 1;
+    }
+    gap(i, a.length, j, b.length);
+    return kinds.map((k, index) => ({ index, ...k }));
+}
+export function structuralDiff(baseline, candidate) {
+    const toolCalls = diffToolCalls(baseline.toolCalls, candidate.toolCalls);
+    return {
+        toolCalls,
+        toolCallsMatch: toolCalls.every((e) => e.kind === "same"),
+        textSimilarity: textSimilarity(baseline.text, candidate.text),
+        stopReasonMatch: baseline.stopReason === candidate.stopReason,
+    };
+}
+/** 一条回复的工具调用与文本（文本块用换行连接；thinking 不算回复）。 */
+export function replyParts(content) {
+    const toolCalls = [];
+    const texts = [];
+    for (const b of content) {
+        if (b.type === "tool_call")
+            toolCalls.push({ name: b.name, input: b.input });
+        else if (b.type === "text")
+            texts.push(b.text);
+    }
+    return { toolCalls, text: texts.join("\n") };
+}