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

package/dist/db/kernel-schema.js

@@ -0,0 +1,5 @@
+/** 把无类型的 Kysely 实例收窄成内核 schema 视图（`capybara`）。 */
+// biome-ignore lint/suspicious/noExplicitAny: 入口处接收无表结构类型的实例
+export function kernelDb(db) {
+    return db.withSchema("capybara");
+}

package/dist/db/migrator.d.ts

@@ -0,0 +1,28 @@
+/** 迁移文件名：`NNNN_<snake_desc>.sql`（其他文件忽略）。 */
+export declare const MIGRATION_FILE_RE: RegExp;
+/** 迁移器所有者：目标 schema 与迁移文件目录。 */
+export interface MigrationOwner {
+    schema: string;
+    dir: string;
+}
+/**
+ * 执行目录下尚未应用的 SQL 迁移。
+ * 使用独立的 pg.Client（不走连接池），在该会话上持有 advisory lock（按 schema 名哈希）；
+ * 结束时无论成败都 end() 会话，会话结束即释放锁，不会把持锁连接还给连接池。
+ * 执行前先校验已应用文件的 checksum 与编号顺序；每个文件在独立事务中执行。
+ * `opts.connectTimeoutMs` 为建立连接的超时（不设则 pg 无限等待）。
+ * `opts.signal` 中止时结束会话：先从另一条连接 `pg_terminate_backend` 迁移会话的后端（后端阻塞在
+ * advisory lock 或长语句上时不会读到客户端的断开，只 end() 会一直占着连接），再 end()；迁移以
+ * `aborted` 失败；中止时若仍在建立连接，直接销毁正在建立的套接字（不等 `connectTimeoutMs`）。
+ * 返回（或抛出）时会话与用于终止的连接都已结束。
+ */
+export declare function migrate(connectionString: string, owner: MigrationOwner, opts?: {
+    connectTimeoutMs?: number | undefined;
+    signal?: AbortSignal | undefined;
+    /** 迁移会话的 `statement_timeout`（毫秒）；不给不设。 */
+    statementTimeoutMs?: number | undefined;
+    /** 迁移会话的 `lock_timeout`（毫秒，含按 schema 的咨询锁）；不给不设。 */
+    lockTimeoutMs?: number | undefined;
+}): Promise<{
+    applied: string[];
+}>;

package/dist/db/migrator.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import pg from "pg";
+import { pgConnectOptions } from "./pool.js";
+/** 迁移文件名：`NNNN_<snake_desc>.sql`（其他文件忽略）。 */
+export const MIGRATION_FILE_RE = /^\d{4}_[a-z0-9_]+\.sql$/;
+const ident = (s) => `"${s.replaceAll('"', '""')}"`;
+const num = (name) => Number.parseInt(name.slice(0, 4), 10);
+/**
+ * 执行目录下尚未应用的 SQL 迁移。
+ * 使用独立的 pg.Client（不走连接池），在该会话上持有 advisory lock（按 schema 名哈希）；
+ * 结束时无论成败都 end() 会话，会话结束即释放锁，不会把持锁连接还给连接池。
+ * 执行前先校验已应用文件的 checksum 与编号顺序；每个文件在独立事务中执行。
+ * `opts.connectTimeoutMs` 为建立连接的超时（不设则 pg 无限等待）。
+ * `opts.signal` 中止时结束会话：先从另一条连接 `pg_terminate_backend` 迁移会话的后端（后端阻塞在
+ * advisory lock 或长语句上时不会读到客户端的断开，只 end() 会一直占着连接），再 end()；迁移以
+ * `aborted` 失败；中止时若仍在建立连接，直接销毁正在建立的套接字（不等 `connectTimeoutMs`）。
+ * 返回（或抛出）时会话与用于终止的连接都已结束。
+ */
+export async function migrate(connectionString, owner, opts = {}) {
+    const { schema, dir } = owner;
+    const { signal } = opts;
+    if (signal?.aborted)
+        throw new Error(`Migration ${schema} aborted`);
+    const names = (await readdir(dir)).filter((f) => MIGRATION_FILE_RE.test(f)).sort();
+    const files = await Promise.all(names.map(async (name) => {
+        const content = await readFile(join(dir, name), "utf8");
+        return { name, content, checksum: createHash("sha256").update(content).digest("hex") };
+    }));
+    const table = `${ident(schema)}._migrations`;
+    // 读文件期间可能已中止（AbortSignal 不会对之后才挂上的监听器补发 abort）：连接前再查一次。
+    // 从这里到 client.connect() 之间没有 await，监听器挂上前不会错过中止。
+    if (signal?.aborted)
+        throw new Error(`Migration ${schema} aborted`);
+    const newClient = () => {
+        const c = new pg.Client({ connectionString, ...pgConnectOptions(opts) });
+        c.on("error", () => { });
+        return c;
+    };
+    const client = newClient();
+    let ending;
+    const end = () => {
+        ending ??= client.end().catch(() => { });
+        return ending;
+    };
+    /** 从独立连接终止迁移会话的后端，再结束本地会话。 */
+    const terminate = async () => {
+        // pg.Client 在握手时记录后端 pid（BackendKeyData），类型定义未暴露
+        const internals = client;
+        const pid = internals.processID;
+        if (!pid) {
+            // 还在建立连接（TCP / 启动握手未完成，没有后端可终止）：直接销毁正在建立的套接字，
+            // connect() 随即以连接中断失败，不必等到 connectTimeoutMs。这里不能先调 end()：
+            // pg 在 end() 之后收到断开不会再回调 connect()，connect 会一直挂着。
+            // connect 失败后由 finally 里的 end() 收尾（此时已是空操作）。
+            internals.connection?.stream?.destroy();
+            return;
+        }
+        const killer = newClient();
+        try {
+            await killer.connect();
+            await killer.query("select pg_terminate_backend($1)", [pid]);
+        }
+        catch {
+            // 尽力而为：终止失败时仍会 end() 本地会话
+        }
+        finally {
+            await killer.end().catch(() => { });
+        }
+        await end();
+    };
+    let aborting;
+    const onAbort = () => {
+        aborting ??= terminate();
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        await client.connect();
+        if (opts.statementTimeoutMs !== undefined) {
+            await client.query(`set statement_timeout = ${Math.max(1, Math.floor(opts.statementTimeoutMs))}`);
+        }
+        if (opts.lockTimeoutMs !== undefined) {
+            await client.query(`set lock_timeout = ${Math.max(1, Math.floor(opts.lockTimeoutMs))}`);
+        }
+        await client.query("select pg_advisory_lock(hashtext($1))", [`capybara-migrate:${schema}`]);
+        await client.query(`create schema if not exists ${ident(schema)}`);
+        await client.query(`create table if not exists ${table} (
+      name text primary key,
+      checksum text not null,
+      applied_at timestamptz not null default now()
+    )`);
+        const rows = (await client.query(`select name, checksum from ${table}`)).rows;
+        const done = new Map(rows.map((r) => [r.name, r.checksum]));
+        for (const f of files) {
+            const prev = done.get(f.name);
+            if (prev !== undefined && prev !== f.checksum) {
+                throw new Error(`Migration ${schema}/${f.name} was modified after being applied (checksum mismatch)`);
+            }
+        }
+        const highest = Math.max(-1, ...rows.map((r) => num(r.name)));
+        for (const f of files) {
+            if (!done.has(f.name) && num(f.name) < highest) {
+                throw new Error(`Migration ${schema}/${f.name} is out of order: a higher-numbered migration (${String(highest).padStart(4, "0")}) is already applied`);
+            }
+        }
+        const applied = [];
+        for (const f of files) {
+            if (done.has(f.name))
+                continue;
+            try {
+                await client.query("begin");
+                await client.query(`set local search_path to ${ident(schema)}, public`);
+                await client.query(f.content);
+                await client.query(`insert into ${table} (name, checksum) values ($1, $2)`, [
+                    f.name,
+                    f.checksum,
+                ]);
+                await client.query("commit");
+            }
+            catch (e) {
+                await client.query("rollback").catch(() => { });
+                const msg = e instanceof Error ? e.message : String(e);
+                throw new Error(`Migration ${schema}/${f.name} failed: ${msg}`, { cause: e });
+            }
+            applied.push(f.name);
+        }
+        return { applied };
+    }
+    catch (e) {
+        if (signal?.aborted)
+            throw new Error(`Migration ${schema} aborted`, { cause: e });
+        throw e;
+    }
+    finally {
+        signal?.removeEventListener("abort", onAbort);
+        await aborting;
+        await end();
+    }
+}

package/dist/db/pool.d.ts

@@ -0,0 +1,21 @@
+import { Kysely } from "kysely";
+/** 内核连接池的 PG `application_name`（便于在 pg_stat_activity 中识别）。 */
+export declare const KERNEL_APPLICATION_NAME = "capybara-kernel";
+/**
+ * 内核建立 PG 连接时的公共参数：`connectTimeoutMs` → pg 的 `connectionTimeoutMillis`（未设置则不传，pg 无限等待）。
+ * 连接池与迁移器的独立连接共用。
+ */
+export declare function pgConnectOptions(cfg: {
+    connectTimeoutMs?: number | undefined;
+}): {
+    application_name: string;
+    connectionTimeoutMillis?: number;
+};
+/**
+ * 创建基于 pg 连接池的 Kysely 实例。
+ * 池上必须挂 error 监听：空闲连接出错（PG 重启、网络抖动）否则会成为未捕获异常使进程退出。
+ * `opts.connectTimeoutMs` 为建立连接的超时（不设则 pg 无限等待）。
+ */
+export declare function createDb(url: string, poolMax: number, onError?: (err: Error) => void, opts?: {
+    connectTimeoutMs?: number | undefined;
+}): Kysely<any>;

package/dist/db/pool.js

@@ -0,0 +1,28 @@
+import { Kysely, PostgresDialect } from "kysely";
+import pg from "pg";
+/** 内核连接池的 PG `application_name`（便于在 pg_stat_activity 中识别）。 */
+export const KERNEL_APPLICATION_NAME = "capybara-kernel";
+/**
+ * 内核建立 PG 连接时的公共参数：`connectTimeoutMs` → pg 的 `connectionTimeoutMillis`（未设置则不传，pg 无限等待）。
+ * 连接池与迁移器的独立连接共用。
+ */
+export function pgConnectOptions(cfg) {
+    return {
+        application_name: KERNEL_APPLICATION_NAME,
+        ...(cfg.connectTimeoutMs !== undefined && { connectionTimeoutMillis: cfg.connectTimeoutMs }),
+    };
+}
+/**
+ * 创建基于 pg 连接池的 Kysely 实例。
+ * 池上必须挂 error 监听：空闲连接出错（PG 重启、网络抖动）否则会成为未捕获异常使进程退出。
+ * `opts.connectTimeoutMs` 为建立连接的超时（不设则 pg 无限等待）。
+ */
+export function createDb(url, poolMax, onError = (err) => console.error("[db] idle client error:", err), opts = {}) {
+    const pool = new pg.Pool({
+        connectionString: url,
+        max: poolMax,
+        ...pgConnectOptions(opts),
+    });
+    pool.on("error", onError);
+    return new Kysely({ dialect: new PostgresDialect({ pool }) });
+}

package/dist/db/sql-statements.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 迁移 SQL 的静态切分与「破坏性语句」判断（`tools/checks` 的迁移检查与插件包审阅共用）。
+ * 纯函数，不连库。迁移只做扩展：删表 / 删列、TRUNCATE、DELETE、RENAME、改列类型都算破坏性。
+ */
+export type SqlStatement = {
+    text: string;
+    line: number;
+    /** 语句里美元引用字符串的原文（不含定界符），按出现顺序；`DO $$ … $$` 的块体在这里。 */
+    bodies: string[];
+    /**
+     * 语句里双引号标识符的内容（`""` 已还原为 `"`），按出现顺序；`text` 里对应位置是 `""`。
+     */
+    quoted: string[];
+};
+/**
+ * 把 SQL 切成语句。忽略 `--` 行注释、块注释、单引号字符串（含 '' 转义）与美元引用字符串
+ * 中的 `;` 和关键字：注释被丢弃，字符串/美元引用/双引号标识符内容被抹成空串（美元引用原文另存于 `bodies`，
+ * 双引号标识符另存于 `quoted`）。
+ * line 为语句首个 token 的 1 基行号。
+ */
+export declare function splitSqlStatements(src: string): SqlStatement[];
+/**
+ * 语句（{@link splitSqlStatements} 的 text）是否为破坏性语句：DROP TABLE / SCHEMA、ALTER TABLE … DROP [COLUMN]
+ * 列（DROP NOT NULL / DEFAULT / EXPRESSION / IDENTITY / CONSTRAINT 不算）、TRUNCATE、DELETE FROM、RENAME、改列类型。
+ */
+export declare function isDestructiveSql(t: string): boolean;
+/**
+ * `DO` 块体（PL/pgSQL，{@link SqlStatement.bodies}）里是否有破坏性语句：块体按 `;` 切开后，从每个
+ * `ALTER` / `DROP` / `TRUNCATE` / `DELETE` 关键字起按 {@link isDestructiveSql} 判断（块体以 `BEGIN` / `IF … THEN`
+ * 开头，关键字不在语句首）。嵌套的美元引用一并检查。
+ */
+export declare function isDestructiveBody(body: string): boolean;
+/** 一段迁移 SQL 里的破坏性语句（行号 1 基，语句已压成一行）。 */
+export declare function destructiveStatements(sql: string): SqlStatement[];

package/dist/db/sql-statements.js

@@ -0,0 +1,168 @@
+/**
+ * 迁移 SQL 的静态切分与「破坏性语句」判断（`tools/checks` 的迁移检查与插件包审阅共用）。
+ * 纯函数，不连库。迁移只做扩展：删表 / 删列、TRUNCATE、DELETE、RENAME、改列类型都算破坏性。
+ */
+/**
+ * 把 SQL 切成语句。忽略 `--` 行注释、块注释、单引号字符串（含 '' 转义）与美元引用字符串
+ * 中的 `;` 和关键字：注释被丢弃，字符串/美元引用/双引号标识符内容被抹成空串（美元引用原文另存于 `bodies`，
+ * 双引号标识符另存于 `quoted`）。
+ * line 为语句首个 token 的 1 基行号。
+ */
+export function splitSqlStatements(src) {
+    const out = [];
+    let text = "";
+    let line = 1;
+    let startLine = 0;
+    let bodies = [];
+    let quoted = [];
+    let i = 0;
+    const push = (chunk) => {
+        if (startLine === 0 && chunk.trim() !== "")
+            startLine = line;
+        text += chunk;
+    };
+    const flush = () => {
+        if (text.trim() !== "") {
+            out.push({ text: text.replace(/\s+/g, " ").trim(), line: startLine, bodies, quoted });
+        }
+        text = "";
+        startLine = 0;
+        bodies = [];
+        quoted = [];
+    };
+    while (i < src.length) {
+        const c = src[i];
+        const two = src.slice(i, i + 2);
+        if (two === "--") {
+            while (i < src.length && src[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (two === "/*") {
+            let depth = 1;
+            i += 2;
+            while (i < src.length && depth > 0) {
+                if (src.startsWith("/*", i)) {
+                    depth++;
+                    i += 2;
+                }
+                else if (src.startsWith("*/", i)) {
+                    depth--;
+                    i += 2;
+                }
+                else {
+                    if (src[i] === "\n")
+                        line++;
+                    i++;
+                }
+            }
+            push(" ");
+            continue;
+        }
+        if (c === "'") {
+            push("'");
+            i++;
+            while (i < src.length) {
+                if (src[i] === "'" && src[i + 1] === "'")
+                    i += 2;
+                else if (src[i] === "'")
+                    break;
+                else {
+                    if (src[i] === "\n")
+                        line++;
+                    i++;
+                }
+            }
+            i++;
+            push("'");
+            continue;
+        }
+        if (c === '"') {
+            push('"');
+            i++;
+            const from = i;
+            while (i < src.length) {
+                if (src[i] === '"' && src[i + 1] === '"')
+                    i += 2;
+                else if (src[i] === '"')
+                    break;
+                else {
+                    if (src[i] === "\n")
+                        line++;
+                    i++;
+                }
+            }
+            quoted.push(src.slice(from, Math.min(i, src.length)).replaceAll('""', '"'));
+            i++;
+            push('"');
+            continue;
+        }
+        if (c === "$") {
+            const m = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(src.slice(i));
+            if (m) {
+                const tag = m[0];
+                const end = src.indexOf(tag, i + tag.length);
+                const stop = end === -1 ? src.length : end + tag.length;
+                push("$$");
+                bodies.push(src.slice(i + tag.length, end === -1 ? src.length : end));
+                for (let k = i; k < stop; k++)
+                    if (src[k] === "\n")
+                        line++;
+                i = stop;
+                continue;
+            }
+        }
+        if (c === ";") {
+            flush();
+            i++;
+            continue;
+        }
+        push(c);
+        if (c === "\n")
+            line++;
+        i++;
+    }
+    flush();
+    return out;
+}
+/**
+ * 语句（{@link splitSqlStatements} 的 text）是否为破坏性语句：DROP TABLE / SCHEMA、ALTER TABLE … DROP [COLUMN]
+ * 列（DROP NOT NULL / DEFAULT / EXPRESSION / IDENTITY / CONSTRAINT 不算）、TRUNCATE、DELETE FROM、RENAME、改列类型。
+ */
+export function isDestructiveSql(t) {
+    if (/^ALTER\s+TABLE\b/i.test(t)) {
+        for (const m of t.matchAll(/\bDROP\s+(COLUMN\s+)?(IF\s+EXISTS\s+)?(NOT\s+NULL\b|DEFAULT\b|EXPRESSION\b|IDENTITY\b|CONSTRAINT\b|\S+)/gi)) {
+            const kw = (m[3] ?? "").toUpperCase();
+            if (!m[1] && /^(NOT\s+NULL|DEFAULT|EXPRESSION|IDENTITY|CONSTRAINT)$/.test(kw))
+                continue;
+            return true;
+        }
+    }
+    return (/^DROP\s+(?:TABLE|SCHEMA)\b/i.test(t) ||
+        /^TRUNCATE\b/i.test(t) ||
+        /^DELETE\s+FROM\b/i.test(t) ||
+        /\bRENAME\b/i.test(t) ||
+        /\bALTER\s+(?:COLUMN\s+)?\S+\s+(?:SET\s+DATA\s+)?TYPE\b/i.test(t));
+}
+/**
+ * `DO` 块体（PL/pgSQL，{@link SqlStatement.bodies}）里是否有破坏性语句：块体按 `;` 切开后，从每个
+ * `ALTER` / `DROP` / `TRUNCATE` / `DELETE` 关键字起按 {@link isDestructiveSql} 判断（块体以 `BEGIN` / `IF … THEN`
+ * 开头，关键字不在语句首）。嵌套的美元引用一并检查。
+ */
+export function isDestructiveBody(body) {
+    for (const st of splitSqlStatements(body)) {
+        if (/\bRENAME\b/i.test(st.text))
+            return true;
+        for (const m of st.text.matchAll(/\b(?:ALTER|DROP|TRUNCATE|DELETE)\b/gi)) {
+            if (isDestructiveSql(st.text.slice(m.index ?? 0)))
+                return true;
+        }
+        if (st.bodies.some(isDestructiveBody))
+            return true;
+    }
+    return false;
+}
+/** 一段迁移 SQL 里的破坏性语句（行号 1 基，语句已压成一行）。 */
+export function destructiveStatements(sql) {
+    return splitSqlStatements(sql).filter((s) => isDestructiveSql(s.text));
+}

package/dist/errors.d.ts

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