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

package/dist/skills/package.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { parseSkillMd, SKILL_ENTRY_FILE, SKILL_LIMITS, skillInvocation, validateSkillPackage, } from "@capybara-hq/plugin-sdk";
+import yauzl from "yauzl";
+import { ApiError } from "../errors.js";
+import { cleanInvocationKeys } from "./invocation-keys.js";
+/**
+ * 技能包（zip）解包与校验。zip 一律当作恶意输入：
+ *
+ * - 解析用 yauzl（3.4.0，固定版本）：只信中央目录、按条目随机读取（不按本地头顺序猜），自带
+ *   `validateEntrySizes`（实际解压出的字节数必须等于声明值）与文件名检查（绝对路径、盘符、`..`、
+ *   `strictFileNames` 下的反斜杠）。不选 fflate：它的同步解压会先把整个条目解到内存，流式解压又按本地头顺序走，
+ *   遇到声明与实际不一致的恶意包更难兜住。
+ * - 此外自己再按**实际**解压出的字节数计数：单文件超过 {@link SKILL_LIMITS.fileBytes}、累计超过
+ *   {@link SKILL_LIMITS.totalBytes} 立即中止；条目数上限 {@link SKILL_PACKAGE_MAX_ENTRIES}；声明的压缩比
+ *   超过 {@link MAX_COMPRESSION_RATIO}（且解压后超过 1 MiB）视为 zip 炸弹，提前拒绝、不做解压
+ *   （deflate 的理论上限约 1032:1，正常文本即使高度重复也远低于 1000:1；真正兜底的是按实际字节的上限）；拒绝符号链接与其他非普通文件
+ *   （外部属性里的 Unix mode）、加密条目、stored / deflate 之外的压缩方法。
+ * - 路径与清单规则（必须有 SKILL.md、去重、大小写冲突、控制字符、沙箱路径）见 plugin-sdk `validateSkillPackage`。
+ *
+ * 整个 zip（≤ {@link SKILL_PACKAGE_MAX_BYTES}）与解出的文件（≤ 50MB）都在内存里处理。
+ */
+/** 技能包 zip 本身的大小上限（字节）。 */
+export const SKILL_PACKAGE_MAX_BYTES = 50 * 1024 * 1024;
+/** zip 中央目录的条目数上限（含目录项与被忽略的条目）。 */
+export const SKILL_PACKAGE_MAX_ENTRIES = 1000;
+/** 单个条目声明的「解压后 / 压缩后」比值上限（只挡近乎单一字节重复的炸弹，正常文本不会触发）。 */
+export const MAX_COMPRESSION_RATIO = 1000;
+/** 解压后不超过这么大的条目不看压缩比（小文本本来就能压得很小）。 */
+const RATIO_MIN_BYTES = 1024 * 1024;
+const S_IFMT = 0o170000;
+const S_IFREG = 0o100000;
+const S_IFDIR = 0o040000;
+const S_IFLNK = 0o120000;
+/**
+ * The `invocation` to store in a version's manifest: undefined for the defaults (a skill both the
+ * model and a person can invoke, with no fork, hint or named arguments), so ordinary skills keep
+ * their manifest unchanged.
+ */
+export function storedInvocation(i) {
+    const plain = i.model &&
+        i.user &&
+        i.fork === undefined &&
+        i.argumentHint === undefined &&
+        i.arguments === undefined;
+    return plain ? undefined : i;
+}
+/** 打包工具顺手带上的垃圾文件：macOS 的资源分支目录与 Finder 的 `.DS_Store`，直接跳过。 */
+const ignored = (path) => path.startsWith("__MACOSX/") || path === ".DS_Store" || path.endsWith("/.DS_Store");
+/**
+ * Invalid zip or skill content (`problems` lists each one, in English). Independent of HTTP: a
+ * skill upload maps it to `skill.invalid_package`, an enterprise catalog import to
+ * `catalog.invalid_manifest`.
+ */
+export class SkillArchiveError extends Error {
+    problems;
+    constructor(problems) {
+        super(problems[0] ?? "unknown problem");
+        this.name = "SkillArchiveError";
+        this.problems = problems;
+    }
+}
+const problem = (problems) => new SkillArchiveError(problems);
+const invalid = (problems) => new ApiError("skill.invalid_package", `Invalid skill package: ${problems[0] ?? "unknown problem"}`, problems.map((message) => ({ path: "package", message })));
+/** 读一个条目的全部字节：按实际字节数计数，超过 `max` 立即中止。 */
+async function readEntry(zip, entry, max, onTooBig) {
+    const stream = await zip.openReadStreamPromise(entry);
+    const hash = createHash("sha256");
+    const chunks = [];
+    let n = 0;
+    try {
+        for await (const chunk of stream) {
+            n += chunk.length;
+            if (n > max)
+                throw onTooBig();
+            hash.update(chunk);
+            chunks.push(chunk);
+        }
+    }
+    finally {
+        stream.destroy();
+    }
+    return { data: new Uint8Array(Buffer.concat(chunks)), sha256: hash.digest("hex") };
+}
+/**
+ * 外层目录规则：根目录有 SKILL.md → 原样使用；否则当且仅当全部文件都在同一个顶层目录 `D/` 下、且 `D/SKILL.md`
+ * 存在时，去掉 `D/`（如 GitHub 下载的 `repo-main/`；目录名不必等于技能名，技能名只取 SKILL.md 的 name，
+ * 沙箱路径用 `/skills/<name>/`）。其他情况（多个顶层条目、SKILL.md 只在更深的目录里）不猜，按缺少 SKILL.md 拒绝。
+ */
+export function stripWrapper(files, entryFile = SKILL_ENTRY_FILE) {
+    if (files.some((f) => f.path === entryFile))
+        return files;
+    if (!files.every((f) => f.path.includes("/")))
+        return files;
+    const tops = new Set(files.map((f) => f.path.slice(0, f.path.indexOf("/"))));
+    const top = tops.size === 1 ? [...tops][0] : undefined;
+    if (top === undefined || !files.some((f) => f.path === `${top}/${entryFile}`)) {
+        return files;
+    }
+    return files.map((f) => ({ ...f, path: f.path.slice(top.length + 1) }));
+}
+/**
+ * 解包并校验技能包：返回 SKILL.md 里的 name / description 与全部文件（含 sha256）。
+ * 外层目录按 {@link stripWrapper} 的规则去掉。
+ * 任何问题 → `skill.invalid_package`（400），details 逐条列出。
+ */
+export async function readSkillPackage(bytes) {
+    try {
+        const files = stripWrapper(await readZipFiles(bytes, SKILL_PACKAGE_MAX_BYTES));
+        return { ...checkSkillFiles(files), files };
+    }
+    catch (e) {
+        if (e instanceof SkillArchiveError)
+            throw invalid(e.problems);
+        throw e;
+    }
+}
+/**
+ * Checks a set of skill files (paths relative to the skill root): the rules of plugin-sdk
+ * `validateSkillPackage`, SKILL.md strict UTF-8 with valid frontmatter. Returns its name,
+ * description and invocation metadata. Invalid → {@link SkillArchiveError}. `invocationKeys: false`
+ * (files stored before phase D, Claude Code imports) skips the invocation key checks and leaves out
+ * of the invocation every key they would refuse ({@link cleanInvocationKeys}).
+ */
+export function checkSkillFiles(files, opts = {}) {
+    const problems = validateSkillPackage(files);
+    if (problems.length > 0)
+        throw problem(problems);
+    const entryFile = files.find((f) => f.path === SKILL_ENTRY_FILE);
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(entryFile.data);
+    }
+    catch {
+        throw problem([`${SKILL_ENTRY_FILE} is not valid UTF-8 text`]);
+    }
+    const parsed = parseSkillMd(text, opts);
+    if ("errors" in parsed)
+        throw problem(parsed.errors.map((m) => `${SKILL_ENTRY_FILE}: ${m}`));
+    // Lenient: the keys the strict checks would refuse are dropped, so no reader stores an
+    // invocation nobody can use or over-long display text (batch 1 review M2)
+    const fm = opts.invocationKeys === false
+        ? cleanInvocationKeys(parsed.frontmatter).frontmatter
+        : parsed.frontmatter;
+    return {
+        name: parsed.name,
+        description: parsed.description,
+        invocation: skillInvocation(fm),
+    };
+}
+/**
+ * 读 zip 里的全部普通文件（规则与上限见文件头；`maxBytes` 为 zip 本身的上限），不去外层目录、不看内容。
+ * 不合法 → {@link SkillArchiveError}。
+ */
+export async function readZipFiles(bytes, maxBytes) {
+    const invalid = problem;
+    if (bytes.byteLength > maxBytes) {
+        throw invalid([`the zip file is larger than ${maxBytes} bytes`]);
+    }
+    const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let zip;
+    try {
+        zip = await yauzl.fromBufferPromise(buf, {
+            lazyEntries: true,
+            autoClose: true,
+            decodeStrings: true,
+            strictFileNames: true,
+            validateEntrySizes: true,
+        });
+    }
+    catch {
+        throw invalid(["the file is not a valid zip archive"]);
+    }
+    if (zip.entryCount > SKILL_PACKAGE_MAX_ENTRIES) {
+        zip.close();
+        throw invalid([`the zip archive has more than ${SKILL_PACKAGE_MAX_ENTRIES} entries`]);
+    }
+    const raw = [];
+    let total = 0;
+    let current = "";
+    try {
+        for await (const entry of zip.eachEntry()) {
+            const name = entry.fileName;
+            current = name;
+            if (ignored(name))
+                continue;
+            const type = (entry.externalFileAttributes >>> 16) & 0xffff & S_IFMT;
+            if (type === S_IFLNK)
+                throw invalid([`${name}: symbolic links are not allowed`]);
+            if (name.endsWith("/")) {
+                if (type !== 0 && type !== S_IFDIR)
+                    throw invalid([`${name}: not a regular file`]);
+                continue;
+            }
+            if (type !== 0 && type !== S_IFREG) {
+                throw invalid([`${name}: only regular files are allowed (not a regular file)`]);
+            }
+            if (entry.isEncrypted())
+                throw invalid([`${name}: encrypted entries are not supported`]);
+            if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+                throw invalid([`${name}: unsupported compression method ${entry.compressionMethod}`]);
+            }
+            const tooBig = () => invalid([`${name}: file is larger than ${SKILL_LIMITS.fileBytes} bytes`]);
+            const tooMuch = () => invalid([`package is larger than ${SKILL_LIMITS.totalBytes} bytes in total`]);
+            if (entry.uncompressedSize > SKILL_LIMITS.fileBytes)
+                throw tooBig();
+            if (total + entry.uncompressedSize > SKILL_LIMITS.totalBytes)
+                throw tooMuch();
+            if (entry.uncompressedSize > RATIO_MIN_BYTES &&
+                entry.uncompressedSize > Math.max(1, entry.compressedSize) * MAX_COMPRESSION_RATIO) {
+                throw invalid([`${name}: suspicious compression ratio (possible zip bomb)`]);
+            }
+            const remaining = SKILL_LIMITS.totalBytes - total;
+            const max = Math.min(SKILL_LIMITS.fileBytes, remaining);
+            const { data, sha256 } = await readEntry(zip, entry, max, () => max < SKILL_LIMITS.fileBytes ? tooMuch() : tooBig());
+            total += data.byteLength;
+            raw.push({ path: name, size: data.byteLength, sha256, data });
+        }
+    }
+    catch (e) {
+        zip.close();
+        if (e instanceof SkillArchiveError)
+            throw e;
+        const msg = e instanceof Error ? e.message : String(e);
+        throw invalid([current ? `${current}: ${msg}` : `the zip archive is malformed: ${msg}`]);
+    }
+    return raw;
+}

package/dist/skills/skills.controller.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { type CreatedAttachment } from "../conversations/attachments.service.js";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { SkillDetail, SkillSummary, SkillsService, UploadedSkill } from "./skills.service.js";
+declare const UploadBody: z.ZodObject<{
+    name: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strict>;
+declare const CreateBody: z.ZodObject<{
+    uploadId: z.ZodString;
+}, z.core.$strict>;
+/**
+ * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
+ * - read: `skills.read` (member and up) — `GET /` list, `GET /:id` detail (versions and file
+ *   lists);
+ * - write: `skills.manage` (admin and up) —
+ *   1. `POST /uploads` registers a skill package upload (`application/zip`, ≤ 50MB, returns a
+ *      presigned form, used like chat attachments);
+ *   2. the browser uploads straight to object storage (it may call
+ *      `POST /attachments/:id/finalize`, or skip it and let the next step finalize);
+ *   3. `POST /` `{ uploadId }` unpacks and checks it, creating a skill or adding a version to the
+ *      skill with the same name;
+ *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3).
+ * When the deployment setting `customSkills` is deny, registering an upload and creating both
+ * return 403 `catalog.custom_disabled` (decided in the service, re-checked inside the org row lock
+ * on create); installing skills from the enterprise catalog is unaffected.
+ */
+export declare class SkillsController {
+    private readonly skills;
+    constructor(skills: SkillsService);
+    createUpload(principal: Principal, org: OrgContext, body: z.infer<typeof UploadBody>): Promise<CreatedAttachment>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<UploadedSkill>;
+    list(principal: Principal, org: OrgContext): Promise<{
+        skills: SkillSummary[];
+    }>;
+    get(principal: Principal, org: OrgContext, id: string): Promise<SkillDetail>;
+    remove(principal: Principal, org: OrgContext, id: string): Promise<void>;
+}
+export {};

package/dist/skills/skills.controller.js

@@ -0,0 +1,110 @@
+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 { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
+import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { z } from "zod";
+import { SKILL_PACKAGE_UPLOAD_MAX_BYTES, } from "../conversations/attachments.service.js";
+import { SKILLS } 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 UploadBody = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(MEDIA_NAME_MAX_CHARS)
+        .refine((s) => !hasControlChars(s), "name must not contain control characters"),
+    size: z.number().int().min(1).max(SKILL_PACKAGE_UPLOAD_MAX_BYTES),
+})
+    .strict();
+const CreateBody = z.object({ uploadId: z.string().min(1).max(100) }).strict();
+/**
+ * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
+ * - read: `skills.read` (member and up) — `GET /` list, `GET /:id` detail (versions and file
+ *   lists);
+ * - write: `skills.manage` (admin and up) —
+ *   1. `POST /uploads` registers a skill package upload (`application/zip`, ≤ 50MB, returns a
+ *      presigned form, used like chat attachments);
+ *   2. the browser uploads straight to object storage (it may call
+ *      `POST /attachments/:id/finalize`, or skip it and let the next step finalize);
+ *   3. `POST /` `{ uploadId }` unpacks and checks it, creating a skill or adding a version to the
+ *      skill with the same name;
+ *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3).
+ * When the deployment setting `customSkills` is deny, registering an upload and creating both
+ * return 403 `catalog.custom_disabled` (decided in the service, re-checked inside the org row lock
+ * on create); installing skills from the enterprise catalog is unaffected.
+ */
+let SkillsController = class SkillsController {
+    skills;
+    constructor(skills) {
+        this.skills = skills;
+    }
+    async createUpload(principal, org, body) {
+        const p = requireUser(principal);
+        return this.skills.createUpload(org.orgId, p.account.id, body);
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return this.skills.upload(org.orgId, p.account.id, body.uploadId, patTokenId(p));
+    }
+    async list(principal, org) {
+        requireUser(principal);
+        return { skills: await this.skills.list(org.orgId) };
+    }
+    async get(principal, org, id) {
+        requireUser(principal);
+        return this.skills.get(org.orgId, id);
+    }
+    async remove(principal, org, id) {
+        const p = requireUser(principal);
+        await this.skills.softDelete(org.orgId, id, p.account.id, patTokenId(p));
+    }
+};
+__decorate([
+    Post("uploads"),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(UploadBody)))
+], SkillsController.prototype, "createUpload", null);
+__decorate([
+    Post(),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(CreateBody)))
+], SkillsController.prototype, "create", null);
+__decorate([
+    Get(),
+    OrgAction("skills.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], SkillsController.prototype, "list", null);
+__decorate([
+    Get(":id"),
+    OrgAction("skills.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], SkillsController.prototype, "get", null);
+__decorate([
+    Delete(":id"),
+    HttpCode(204),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], SkillsController.prototype, "remove", null);
+SkillsController = __decorate([
+    Controller("api/v1/orgs/:orgId/skills"),
+    __param(0, Inject(SKILLS))
+], SkillsController);
+export { SkillsController };

package/dist/skills/skills.service.d.ts

@@ -0,0 +1,192 @@
+import { type SkillInvocation } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { AgentDefinition } from "../agents/definition.js";
+import { type AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
+import type { KernelDatabase, KernelDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import type { StorageService } from "../storage/storage.service.js";
+import { type SkillPackageFile } from "./package.js";
+type Trx = Transaction<KernelDatabase>;
+/** Where an org skill came from (spec §9.2): the org's own, or a catalog plugin at a version. */
+export type SkillSource = {
+    kind: "org";
+} | {
+    kind: "plugin";
+    name: string;
+    version: string;
+};
+/** An org skill that a plugin install would overwrite. */
+export interface SkillConflict {
+    skill: string;
+    source: SkillSource;
+}
+/**
+ * The live org skills named in `skillNames` whose provenance is not catalog item `itemId` (spec
+ * §9.2, Decision 8): the org's own skills (`catalog_item_id` null: uploaded or written by an
+ * agent) and the skills of other catalog items. A skill of the same item (a reinstall or upgrade)
+ * is not a conflict. In the order of `skillNames`.
+ */
+export declare function skillConflicts(db: KernelDb | Trx, orgId: string, itemId: string, skillNames: readonly string[]): Promise<SkillConflict[]>;
+/** One line of the conflict message (spec §9.2). */
+export declare function skillConflictLine(c: SkillConflict): string;
+/** 409 `plugin.skill_conflict`: one message line and one detail per conflicting skill. */
+export declare function skillConflictError(conflicts: readonly SkillConflict[]): ApiError;
+/** 技能列表项。 */
+export interface SkillSummary {
+    id: string;
+    scope: "org" | "agent";
+    agentId: string | null;
+    name: string;
+    description: string;
+    currentVersion: number;
+    createdBy: string;
+    createdAt: Date;
+    updatedAt: Date;
+    /** The catalog item name the skill came from; null for the org's own (uploaded or written). */
+    plugin: string | null;
+    /** The format of the plugin the current version came from. */
+    sourceFormat: SourceFormat;
+    /** The plugin suggests pinning the current version (spec §9.1). */
+    suggestPinned: boolean;
+    /** SKILL.md size of the current version, in bytes (0 when the manifest has none). */
+    entryBytes: number;
+    /** Token estimate of the SKILL.md of the current version (ASCII rule: bytes / 4). */
+    tokenEstimate: number;
+    /** Phase D: the current version is manual-only (not in the model's catalog). */
+    manual: boolean;
+    /** Phase D: the current version runs as a sub-agent when a person invokes it. */
+    fork: boolean;
+}
+/** 技能的一个版本（含文件清单）。 */
+export interface SkillVersionView {
+    version: number;
+    files: SkillManifest["files"];
+    description: string;
+    createdBy: string;
+    createdAt: Date;
+}
+/** 技能详情：各版本新的在前。 */
+export interface SkillDetail extends SkillSummary {
+    versions: SkillVersionView[];
+    /**
+     * 当前版本 SKILL.md 的正文（去掉 frontmatter；网页按纯文本显示）。超过 {@link SKILL_BODY_MAX_BYTES}、
+     * 读不到（对象缺失、存储不可用）或不是 UTF-8 时为 null。
+     */
+    body: string | null;
+}
+/** 详情里读取 SKILL.md 正文的上限。 */
+export declare const SKILL_BODY_MAX_BYTES: number;
+/** `POST /skills` 的结果：`created` 为 true 表示新技能，否则是已有技能的新版本。 */
+export interface UploadedSkill {
+    skill: SkillSummary;
+    version: number;
+    created: boolean;
+}
+export interface SkillsDeps {
+    db: KernelDb;
+    storage: StorageService;
+    attachments: Pick<AttachmentsService, "create" | "readSkillPackage" | "consumeSkillPackage">;
+}
+/**
+ * 在调用方事务里核对 agent 定义引用的组织技能：每个 id 都必须是该组织未删除的 `scope=org` 技能，
+ * 否则 `validation_failed`（path `skills.orgSkills.<i>`）；不可重复。调用方须已锁组织行（技能删除同样锁组织行，二者串行）。
+ * `kept`：当前版本里已有的引用（保存时合法），修改时不再核对——技能之后被删也不挡住其他改动（运行时由 T14 忽略已删除的技能）。
+ */
+export declare function assertOrgSkills(t: Trx, orgId: string, ids: readonly string[], kept?: ReadonlySet<string>): Promise<void>;
+/** Why a pinned skill reference is refused (`agent.pinned_invalid` details). */
+export type PinnedSkillProblem = "not_selected" | "not_found" | "duplicate" | "too_many" | "too_large"
+/** Phase D: the skill's current version is manual-only (not in the model's catalog). */
+ | "manual_only";
+/**
+ * Checks `skills.pinned` of an agent definition in the caller's transaction (the org row is locked,
+ * like {@link assertOrgSkills}); throws 400 `agent.pinned_invalid` with one detail per problem
+ * (`{ skill, reason, totalBytes? }`):
+ * - `duplicate`: an id listed twice; `too_many`: every id past {@link PINNED_SKILLS_LIMITS}.count;
+ * - each newly added id (not in `kept`, the current definition's pinned ids) must be a live org
+ *   skill listed in `skills.orgSkills` (else `not_selected`) or a live skill of this agent
+ *   (`agentId`; null when creating), else `not_found`. Kept ids are not re-checked: a pinned skill
+ *   deleted later does not block other edits (the run ignores it);
+ * - `manual_only` (phase D): a newly added id whose current version is manual-only
+ *   (`invocation.model === false`); a kept one that became manual-only is dropped at run time;
+ * - `too_large`: the current SKILL.md sizes of the live pinned skills total more than
+ *   {@link PINNED_SKILLS_LIMITS}.totalBytes (named by the first skill past the limit). Checked only
+ *   when the pinned list changed: a pinned skill's new version never blocks an unrelated edit (the
+ *   run keeps what fits).
+ */
+export declare function assertPinnedSkills(t: Trx, orgId: string, agentId: string | null, skills: AgentDefinition["skills"], kept?: readonly string[]): Promise<void>;
+/**
+ * 技能库（M5 T13）：组织技能的上传（新技能或新版本）、列表、详情与软删除。
+ * 字节在对象存储 `kernel/<orgId>/skills/<uploadId>/<path>`，元数据在 PG；无进程内状态，可多副本共用。
+ */
+export declare class SkillsService {
+    private readonly d;
+    constructor(d: SkillsDeps);
+    /** 登记一个技能包上传（预签名 POST，`application/zip`，≤ 50MB）；角色由路由的 `skills.manage` 把关。 */
+    createUpload(orgId: string, accountId: string, input: {
+        name: string;
+        size: number;
+    }): Promise<CreatedAttachment>;
+    /**
+     * 用一个技能包上传创建技能或新增版本：
+     * 1. 取上传的 zip（只有上传者；未 finalize 的先 finalize），解包校验（`skill.invalid_package`）；
+     * 2. 把文件写到 `skills/<uploadId>/`（键只取决于上传 id 与包内路径：重试幂等）；
+     * 3. 一个事务里：锁组织行并复核 `skills.manage`，把上传标记为已用掉（并发的同一上传只有一个成功），
+     *    同名未删除的组织技能存在则 `current_version + 1`，否则新建（组织行锁串行化，版本号不会重复），写版本与审计。
+     * 第 3 步之前中断不会留下可见的版本；已写的文件由清理任务在上传过期后删除（未被任何版本引用时）。
+     * 同一上传已经产生过版本（上次提交了、响应丢了而重试）→ 直接返回那个版本（同组织、同一发起人）。
+     */
+    upload(orgId: string, actorAccountId: string, uploadId: string, actorTokenId?: string): Promise<UploadedSkill>;
+    /**
+     * 用一组已校验的技能文件创建组织技能或给同名技能新增版本（上传与企业目录安装共用）：
+     * 1. 把文件写到 `kernel/<orgId>/<prefix>`（缺省 `skills/<新 id>/`）；
+     * 2. 一个事务里：锁组织行并复核 `skills.manage`，执行 `inTransaction`（上传：标记上传已用；目录：按条目策略复核），
+     *    同名未删除的组织技能存在则 `current_version + 1`，否则新建；技能与版本都记下 `directory` 来源（没有则清空：
+     *    自定义上传盖在目录技能上就不再算目录安装），写版本与审计
+     *    （`skill.created` / `skill.version_created`，目录安装时 detail 带 directory）。
+     */
+    createVersionFromFiles(orgId: string, actorAccountId: string, pkg: {
+        name: string;
+        description: string;
+        files: SkillPackageFile[];
+        /** Phase D: stored in the manifest when it is not the default. */
+        invocation?: SkillInvocation;
+    }, opts?: {
+        prefix?: string;
+        actorTokenId?: string;
+        inTransaction?: (t: Trx) => Promise<void>;
+        /** Catalog provenance; `approvedBy` is the item whose policy approves it (default `itemId`). */
+        catalog?: {
+            itemId: string;
+            version: string;
+            approvedBy?: string;
+            /** The catalog version's source format (default capybara). */
+            format?: SourceFormat;
+            /** The plugin manifest suggests pinning this skill (spec §9.1). */
+            suggestPinned?: boolean;
+        };
+    }): Promise<UploadedSkill>;
+    /**
+     * 在调用方事务里撤销应用安装给已有技能加的版本（调用方已锁组织行）：只有当前版本仍是 `version` 时才退回上一版本并删掉
+     * 该版本行（之后又有新版本则不动，返回 false），技能的描述与目录来源也退回上一版本的。审计 `skill.version_reverted`。
+     */
+    revertVersionIn(t: Trx, orgId: string, skillId: string, version: number, actorAccountId: string, reason: string): Promise<boolean>;
+    /**
+     * 在调用方事务里软删除组织技能（调用方已锁组织行；应用安装的回滚与卸载用）。审计 `skill.deleted`（带 reason）。
+     * 已删除 / 不存在时返回 false。
+     */
+    softDeleteIn(t: Trx, orgId: string, skillId: string, actorAccountId: string, reason: string): Promise<boolean>;
+    /** 组织技能库（`scope=org`、未删除），按名字排序。 */
+    list(orgId: string): Promise<SkillSummary[]>;
+    /** 对该 agent 自动生效的技能（`scope=agent`、未删除），按名字排序。 */
+    listForAgent(orgId: string, agentId: string): Promise<SkillSummary[]>;
+    /** 组织技能详情：各版本与文件清单。不存在 / 已删除 / 不是组织技能 → `skill.not_found`。 */
+    get(orgId: string, skillId: string): Promise<SkillDetail>;
+    /** 读某版本 SKILL.md 的正文（见 {@link SkillDetail.body}）；任何读取问题都返回 null，不让详情失败。 */
+    private readBody;
+    /**
+     * 软删除组织技能（`skills.manage`，在组织行锁内复核）。之后同名可重新上传为新技能；引用它的 agent 定义
+     * 保存时会被拒绝（运行时由 T14 忽略已删除的技能）。不存在 / 已删除 → `skill.not_found`。
+     */
+    softDelete(orgId: string, skillId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+}
+export {};