@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/skills/changes.service.js

@@ -7,64 +7,45 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { randomUUID } from "node:crypto";
-import { parseSkillMd, SKILL_ENTRY_FILE, ToolError } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { visibleTo } from "../agents/agent-lookup.js";
-import { skillFilesPrefix } from "../conversations/attachments.service.js";
 import { EventLog } from "../conversations/event-log.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
+import { assertCustomAllowed } from "../identity/settings.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
-import { sameSnapshot, } from "../runtime/context/skills.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { StorageService } from "../storage/storage.service.js";
-import { fitPinned, invocationOf, lockLatestCatalog } from "./catalog.js";
+import { assertShareableName, isOrgAdmin, shareSkillIn } from "./agent-skills.service.js";
+import { cancelRequestIn, revertTrialCatalog, } from "./conversation-catalog.js";
+import { SkillsService } from "./skills.service.js";
 /**
- * 每个 agent 自己的技能（`scope = agent`）上限，含待批准的新技能。远低于目录快照的上限（`SKILLS_CATALOG_MAX`），
- * 正常使用不会让目录被截断。
+ * The cap on file contents read for one detail (a package may hold up to 50 MB; the inbox shows
+ * text for review, so files past the cap read as no content).
  */
-export const AGENT_SKILLS_MAX = 50;
-/** 写技能文件时的并发数。 */
-const PUT_CONCURRENCY = 4;
-/** 详情里读取文件内容的上限（草稿 ≤ 1MB，留余量）。 */
 const DETAIL_MAX_BYTES = 2 * 1024 * 1024;
-/** 收件箱一次最多返回的技能变更数。 */
+/** The most skill changes one inbox read returns. */
 export const SKILL_CHANGES_LIST_MAX = 100;
-// ---- 模型可见文案（英文） ----
-const STORAGE_UNAVAILABLE_TEXT = "File storage is temporarily unavailable, so the skill could not be saved; retry later.";
-const pendingElsewhereText = (name) => `Skill "${name}" already has a change awaiting the owner's approval (requested in another conversation), so it cannot be changed now; ask the user to have the owner decide that change first, or use a different skill name.`;
-const capText = () => `This agent already has ${AGENT_SKILLS_MAX} skills (including changes awaiting approval), the maximum; update an existing skill instead, or ask the agent's owner to delete one of this agent's skills.`;
-const AGENT_GONE_TEXT = "This agent no longer exists, so the skill cannot be saved; ask the user to start a conversation with another agent.";
 const iso = (v) => new Date(v).toISOString();
-const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 const notFound = () => new ApiError("skill_change.not_found", "Skill change not found");
-/** The body of the SKILL.md a skill_write just stored (as run start would read it); null if unparsable. */
-function writtenBody(pkg) {
-    const md = pkg.files.find((f) => f.path === SKILL_ENTRY_FILE);
-    if (!md)
-        return null;
-    try {
-        const parsed = parseSkillMd(new TextDecoder("utf-8", { fatal: true }).decode(md.data));
-        return "errors" in parsed ? null : parsed.body;
-    }
-    catch {
-        return null;
-    }
-}
+const forbidden = () => new ApiError("forbidden", "Insufficient organization role");
 /**
- * agent 自写技能与共享 agent 的技能变更审批（M5 T15，R4）：
- * - `write`（工具 `skill_write` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
- *   期间只有发起对话试用（`resolveEffectiveSkills` 按对话合并）；两种情况都在同一事务里往发起对话追加一份
- *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `skill_load`；
- * - `decide`（HTTP，只有该 agent 当前的负责人）：批准 → 版本对所有对话生效（各对话下一次运行开始时写新快照）；
- *   拒绝 → 删除草稿对象，发起对话下一次运行开始时目录回到当前版本；
- * - 同一 agent 的同名技能最多一条待处理申请：同一对话再写取代旧的（旧的 cancelled、草稿删除、技能 id 不变），
- *   别的对话再写被拒绝（英文说明）。
- * 状态都在 PG（agent 行锁串行化同一 agent 的写与决定），文件在对象存储 `kernel/<orgId>/skills/<id>/`；无进程内状态。
+ * Skill change requests decided by org admins (spec §5.4, §5.5): an agent's owner asks to share
+ * one of its skills with the org (`kind = 'share'`, created by `AgentSkillsService.share`), and
+ * the maintainer of a shared skill proposes a new version of it (`kind = 'version'`, created by
+ * `AgentSkillsService.register`).
+ * - `decide` (HTTP, human only; org admins, role read live under the org row lock): approving a
+ *   share makes the skill an org skill with the requester as maintainer; approving a version
+ *   writes it as the org skill's next version (`SkillsService.createVersionFromFiles`, the draft
+ *   prefix becomes the version's) so every agent using it gets it at its next run start;
+ *   rejecting a version deletes its draft and reverts the proposing conversation's trial; a share
+ *   keeps its files whatever happens. A request that no longer applies (its agent deleted or
+ *   transferred, its skill deleted or already moved) is cancelled instead.
+ * State is in PG (the org row lock serializes decisions), files in object storage
+ * `kernel/<orgId>/skills/<id>/`; no in-process state.
  */
 let SkillChangesService = class SkillChangesService {
     db;
@@ -72,300 +53,209 @@ let SkillChangesService = class SkillChangesService {
     eventLog;
     log;
     txHost;
-    constructor(db, storage, eventLog, log, txHost) {
+    orgLock;
+    skills;
+    catalogDeps;
+    constructor(db, storage, eventLog, log, txHost, orgLock, 
+    /** An approved version is an org skill version. */
+    skills) {
         this.db = db;
         this.storage = storage;
         this.eventLog = eventLog;
         this.log = log;
         this.txHost = txHost;
-    }
-    /** 写技能（见类注释）。模型可见的失败抛 `ToolError`。 */
-    async write(ctx, pkg) {
-        let store;
-        try {
-            this.storage.assertAvailable();
-            store = this.storage.kernel(ctx.orgId);
-        }
-        catch (e) {
-            throw storageError(e);
-        }
-        const id = randomUUID();
-        const prefix = skillFilesPrefix(id);
-        try {
-            await putAll(store, prefix, pkg.files);
-        }
-        catch (e) {
-            await this.deletePrefix(ctx.orgId, prefix);
-            throw storageError(e);
-        }
-        let committed;
-        try {
-            committed = await this.writeIn(ctx, pkg, id, prefix);
-        }
-        catch (e) {
-            await this.deletePrefix(ctx.orgId, prefix);
-            throw e;
-        }
-        if (committed.toSeq !== null) {
-            await this.eventLog.notify(ctx.conversationId, committed.toSeq);
-        }
-        for (const p of committed.drop)
-            await this.deletePrefix(ctx.orgId, p);
-        return committed.outcome;
+        this.orgLock = orgLock;
+        this.skills = skills;
+        this.catalogDeps = { db, log, eventLog };
     }
     /**
-     * 负责人决定一条申请：只有该 agent 当前的负责人（实时读）能决定，其他人 → 403 `skill_change.not_owner`；
-     * 已处理 → 409 `skill_change.already_decided`；agent 已删除或申请不在本组织 → 404。
-     * 批准：在同一事务里新增版本（技能不存在则用预先分配的 id 新建）、`current_version` 指向它，草稿对象原样成为版本文件；
-     * 拒绝：提交后删除草稿对象。审计 `skill.change_decided`。
+     * An org admin decides a request (see the class comment): not an org admin -> 403 `forbidden`;
+     * already decided -> 409 `skill_change.already_decided`; not in this org -> 404. Approving
+     * re-checks `customSkills` (403 `catalog.custom_disabled`) and, for a share, the name (409
+     * `skill.name_exists`; the request stays pending). A share whose skill has a newer version than
+     * the one reviewed is cancelled, never shared. Audit `skill.change_decided` (and
+     * `skill.shared`). Of concurrent decisions one wins, the others get `already_decided`.
      */
     async decide(orgId, id, accountId, body, actorTokenId) {
         const head = await this.db
             .selectFrom("skill_change_requests")
-            .select("agent_id")
+            .selectAll()
             .where("id", "=", id)
             .where("org_id", "=", orgId)
             .executeTakeFirst();
         if (!head)
             throw notFound();
-        const done = await this.decideIn(orgId, id, accountId, body, actorTokenId, head.agent_id);
-        const row = done.updated;
-        if (done.revertSeq !== null) {
-            await this.eventLog.notify(row.requested_in_conversation, done.revertSeq);
+        // Refused before any file is read; re-checked under the org row lock
+        if (!(await isOrgAdmin(this.db.db, orgId, accountId)))
+            throw forbidden();
+        // An approved version needs its files as a package (read before the transaction) and, for a
+        // skill the org promoted, written as the platform row's next version: no storage writes run
+        // inside the transaction
+        let pkg;
+        let owner;
+        if (body.decision === "approve" && head.kind === "version" && head.status === "pending") {
+            await assertCustomAllowed(this.db.db, "customSkills");
+            pkg = await this.readDraft(orgId, head);
+            owner = await this.skills.prepareStoredVersion(orgId, pkg);
         }
-        if (row.status === "rejected")
-            await this.deletePrefix(orgId, row.object_prefix);
-        const [view] = await this.views([row]);
+        let done;
+        try {
+            done = await this.decideIn(orgId, id, accountId, body, actorTokenId, head, pkg, owner);
+        }
+        catch (e) {
+            if (owner !== undefined)
+                await this.skills.discardStoredVersion(owner);
+            throw e;
+        }
+        if (owner !== undefined && !done.usedOwner)
+            await this.skills.discardStoredVersion(owner);
+        for (const [conv, seq] of done.drafts.seqs)
+            await this.eventLog.notify(conv, seq);
+        for (const p of done.drafts.prefixes)
+            await this.deletePrefix(orgId, p);
+        const [view] = await this.views([done.updated]);
         if (!view)
             throw notFound();
         return view;
     }
-    /**
-     * 软删除 agent 自己的一个技能（只有该 agent 当前的负责人；其他人 403 `forbidden`）：技能不存在 / 已删除 / 不属于该
-     * agent → `skill.not_found`。同名的待处理改动一并取消（发起对话追加回退快照，提交后删草稿）。审计 `skill.deleted`。
-     * 各对话下一次运行开始时目录里去掉它；之后同名可再写为新技能。
-     */
-    async deleteAgentSkill(orgId, agentId, skillId, accountId, actorTokenId) {
-        const cancelled = await this.deleteAgentSkillIn(orgId, agentId, skillId, accountId, actorTokenId);
-        await this.finishCancel(orgId, cancelled);
-    }
-    /** The transaction of {@link write}. */
-    async writeIn(ctx, pkg, id, prefix) {
-        await this.keyShareOrg(ctx.orgId);
-        // NO KEY UPDATE, not UPDATE (here, in decide and in deleteAgentSkill): it still serializes
-        // the writes and decisions of one agent, but not the foreign key check (FOR KEY SHARE) of a
-        // transaction that already holds the conversation row this one locks last, e.g. an event
-        // log append updating that row a second time (the title job): FOR UPDATE made that 40P01
-        const agent = await this.db
-            .selectFrom("agents")
-            .select(["visibility", "deleted_at"])
-            .where("id", "=", ctx.agentId)
-            .where("org_id", "=", ctx.orgId)
-            .forNoKeyUpdate()
-            .executeTakeFirst();
-        if (!agent || agent.deleted_at !== null)
-            throw new ToolError(AGENT_GONE_TEXT);
-        // Then the conversation row (appendCatalog's lock, still after the agent row like decide),
-        // before the change request insert: its foreign key check takes FOR KEY SHARE on that row,
-        // and upgrading to FOR UPDATE afterwards deadlocked with another writer doing the same
-        await this.db
-            .selectFrom("conversations")
-            .select("id")
-            .where("id", "=", ctx.conversationId)
-            .forUpdate()
-            .execute();
-        const existing = await this.db
-            .selectFrom("skills")
-            .select(["id", "current_version"])
-            .where("org_id", "=", ctx.orgId)
-            .where("scope", "=", "agent")
-            .where("agent_id", "=", ctx.agentId)
-            .where("name", "=", pkg.name)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
-        const pend = await this.db
-            .selectFrom("skill_change_requests")
-            .selectAll()
-            .where("agent_id", "=", ctx.agentId)
-            .where("status", "=", "pending")
-            .where(sql `proposed_version -> 'manifest' ->> 'name'`, "=", pkg.name)
-            .forUpdate()
-            .executeTakeFirst();
-        const drop = [];
-        if (pend) {
-            if (pend.requested_in_conversation !== ctx.conversationId) {
-                throw new ToolError(pendingElsewhereText(pkg.name));
+    /** A version draft's files as a package (as registered), or 503 when one cannot be read. */
+    async readDraft(orgId, req) {
+        const store = this.storage.kernel(orgId);
+        const m = req.proposed_version.manifest;
+        const files = [];
+        for (const f of m.files) {
+            const got = await store.get(`${req.object_prefix}${f.path}`);
+            if (!got) {
+                throw new ApiError("storage.unavailable", "The proposed version's files cannot be read; try again later");
             }
-            // 同一对话再写：取代旧申请
-            await this.db
-                .updateTable("skill_change_requests")
-                .set({ status: "cancelled", decided_at: sql `now()` })
-                .where("id", "=", pend.id)
-                .execute();
-            drop.push(pend.object_prefix);
-            await audit(this.db.db, {
-                actorAccountId: ctx.accountId,
-                orgId: ctx.orgId,
-                action: "skill.change_decided",
-                target: pend.id,
-                detail: {
-                    decision: "cancelled",
-                    reason: "superseded",
-                    supersededBy: id,
-                    agentId: ctx.agentId,
-                    name: pkg.name,
-                },
-            });
-        }
-        if (!existing)
-            await this.assertBelowCap(ctx.agentId, pend?.id);
-        const version = (existing?.current_version ?? 0) + 1;
-        const skillId = existing?.id ?? pend?.proposed_version.skillId ?? randomUUID();
-        let outcome;
-        if (agent.visibility === "private") {
-            await this.createVersion({
-                orgId: ctx.orgId,
-                agentId: ctx.agentId,
-                skillId,
-                exists: existing !== undefined,
-                version,
-                manifest: pkg.manifest,
-                prefix,
-                createdBy: ctx.accountId,
-            });
-            await audit(this.db.db, {
-                actorAccountId: ctx.accountId,
-                orgId: ctx.orgId,
-                action: existing ? "skill.version_created" : "skill.created",
-                target: skillId,
-                detail: {
-                    name: pkg.name,
-                    version,
-                    files: pkg.manifest.files.length,
-                    agentId: ctx.agentId,
-                    conversationId: ctx.conversationId,
-                    via: "skill_write",
-                },
-            });
-            outcome = { kind: "version", skillId, version, created: !existing };
+            const data = new Uint8Array(await new Response(got.body).arrayBuffer());
+            files.push({ path: f.path, size: f.size, sha256: f.sha256, data });
         }
-        else {
-            const proposed = { skillId, version, manifest: pkg.manifest };
-            await this.db
-                .insertInto("skill_change_requests")
-                .values({
-                id,
-                org_id: ctx.orgId,
-                agent_id: ctx.agentId,
-                skill_id: existing?.id ?? null,
-                proposed_version: JSON.stringify(proposed),
-                object_prefix: prefix,
-                requested_by_account: ctx.accountId,
-                requested_in_conversation: ctx.conversationId,
-                decided_by: null,
-            })
-                .execute();
-            await audit(this.db.db, {
-                actorAccountId: ctx.accountId,
-                orgId: ctx.orgId,
-                action: "skill.change_requested",
-                target: id,
-                detail: {
-                    agentId: ctx.agentId,
-                    skillId: existing?.id ?? null,
-                    name: pkg.name,
-                    version,
-                    files: pkg.manifest.files.length,
-                    conversationId: ctx.conversationId,
-                },
-            });
-            outcome = { kind: "requested", requestId: id, skillId, version };
-        }
-        // 本对话立即看到新版本：在上一份快照上替换 / 加入这个技能（确定、来自日志；来源 = 本次的对象前缀）
-        // A pinned entry of this skill gets the version, source and body just written (phase B)
-        // A manual-only version (phase D) is never in the model's catalog: it removes the skill from
-        // the snapshot instead, and appendCatalog drops its pinned entry with it (no longer live)
-        const forModel = invocationOf(pkg.manifest).model;
-        const pinnedBody = writtenBody(pkg);
-        const toSeq = await this.appendCatalog(ctx.conversationId, (base) => ({
-            ...base,
-            skills: [
-                ...base.skills.filter((s) => s.name !== pkg.name),
-                ...(forModel
-                    ? [
-                        {
-                            id: skillId,
-                            name: pkg.name,
-                            description: pkg.description,
-                            version,
-                            source: prefix,
-                        },
-                    ]
-                    : []),
-            ],
-            ...(base.pinned && {
-                pinned: base.pinned.map((p) => p.id === skillId && pinnedBody !== null
-                    ? { id: skillId, version, name: pkg.name, source: prefix, body: pinnedBody }
-                    : p),
-            }),
-        }), `skills_catalog:write:${id}`, ctx.runId);
-        return { outcome, drop, toSeq };
+        return {
+            name: m.name,
+            description: m.description,
+            files,
+            ...(m.invocation !== undefined && { invocation: m.invocation }),
+        };
     }
-    /** The transaction of {@link decide}. */
-    async decideIn(orgId, id, accountId, body, actorTokenId, agentId) {
-        // 加锁顺序与 write 一致：组织行（KEY SHARE）→ agent 行 → 申请行 → 会话行
-        await this.keyShareOrg(orgId);
+    /**
+     * The transaction of {@link decide}. Lock order: org row (FOR NO KEY UPDATE, role re-checked) -> agent
+     * row -> the proposing conversation (a version's revert appends there) -> skill row -> request
+     * row, the order registration and sharing use.
+     */
+    async decideIn(orgId, id, accountId, body, actorTokenId, head, pkg, owner) {
+        await this.orgLock.lockAndAuthorize(orgId, accountId, "skills.manage");
         const agent = await this.db
             .selectFrom("agents")
             .select(["owner_account_id", "deleted_at"])
-            .where("id", "=", agentId)
+            .where("id", "=", head.agent_id)
             .forNoKeyUpdate()
             .executeTakeFirst();
-        if (!agent || agent.deleted_at !== null)
-            throw notFound();
+        if (head.kind === "version" && head.requested_in_conversation !== null) {
+            await this.db
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", head.requested_in_conversation)
+                .forUpdate()
+                .executeTakeFirst();
+        }
+        const skill = head.skill_id === null
+            ? undefined
+            : await this.db
+                .selectFrom("skills")
+                .select(["id", "scope", "agent_id", "name", "deleted_at", "current_version"])
+                .where("id", "=", head.skill_id)
+                .forUpdate()
+                .executeTakeFirst();
         const req = await this.db
             .selectFrom("skill_change_requests")
             .selectAll()
             .where("id", "=", id)
             .forUpdate()
             .executeTakeFirst();
-        // 首次读与加锁重读之间行被删了（agent / 组织被硬删除）→ 404，不是 500
+        // the row went between the first read and the lock (agent / org hard-deleted) -> 404, not 500
         if (!req)
             throw notFound();
-        if (agent.owner_account_id !== accountId) {
-            throw new ApiError("skill_change.not_owner", "Only the agent's owner can decide on its skill changes");
-        }
         if (req.status !== "pending") {
             throw new ApiError("skill_change.already_decided", "This skill change has already been decided");
         }
+        const drafts = { prefixes: [], seqs: [] };
+        // A share applies only to the version the admin reviewed; a version proposal only to the skill
+        // of its name
+        const applies = agent !== undefined &&
+            agent.deleted_at === null &&
+            skill !== undefined &&
+            skill.deleted_at === null &&
+            (req.kind === "share"
+                ? skill.scope === "agent" &&
+                    skill.agent_id === req.agent_id &&
+                    skill.current_version === req.proposed_version.version &&
+                    agent.owner_account_id === req.requested_by_account
+                : skill.scope === "org" && skill.name === req.proposed_version.manifest.name);
+        if (!applies) {
+            await cancelRequestIn(this.catalogDeps, req, drafts, {
+                actorAccountId: accountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                reason: "stale",
+            });
+            return { updated: await this.reread(id), drafts, usedOwner: false };
+        }
         const p = req.proposed_version;
         const approved = body.decision === "approve";
-        let skillId = req.skill_id;
         let version = p.version;
-        if (approved) {
-            const existing = await this.db
-                .selectFrom("skills")
-                .select(["id", "current_version"])
-                .where("org_id", "=", orgId)
-                .where("scope", "=", "agent")
-                .where("agent_id", "=", req.agent_id)
-                .where("name", "=", p.manifest.name)
-                .where("deleted_at", "is", null)
-                .forUpdate()
-                .executeTakeFirst();
-            skillId = existing?.id ?? p.skillId;
-            version = (existing?.current_version ?? 0) + 1;
-            await this.createVersion({
-                orgId,
+        if (approved && req.kind === "share") {
+            await assertCustomAllowed(this.db.db, "customSkills");
+            await assertShareableName(this.db, orgId, skill.name);
+            await shareSkillIn(this.db, {
+                skillId: skill.id,
                 agentId: req.agent_id,
-                skillId,
-                exists: existing !== undefined,
-                version,
-                manifest: p.manifest,
+                maintainerAccountId: req.requested_by_account,
+            });
+            await audit(this.db.db, {
+                actorAccountId: accountId,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                orgId,
+                action: "skill.shared",
+                target: skill.id,
+                detail: {
+                    name: skill.name,
+                    agentId: req.agent_id,
+                    maintainer: req.requested_by_account,
+                    requestId: id,
+                },
+            });
+        }
+        else if (approved) {
+            if (pkg === undefined)
+                throw new Error("an approved version needs its files");
+            await assertCustomAllowed(this.db.db, "customSkills");
+            // Joins this transaction without storage I/O: the version is the org skill's next one, the
+            // draft prefix its files; a skill the org promoted gets the platform version prepared before
+            const out = await this.skills.createVersionFromFiles(orgId, accountId, pkg, {
                 prefix: req.object_prefix,
-                createdBy: req.requested_by_account,
+                stored: owner !== undefined ? { owner } : {},
+                ...(actorTokenId !== undefined && { actorTokenId }),
+                auditDetail: {
+                    requestId: id,
+                    agentId: req.agent_id,
+                    requestedBy: req.requested_by_account,
+                },
             });
+            version = out.version;
+            const own = await this.db
+                .selectFrom("skill_versions")
+                .select("object_prefix")
+                .where("skill_id", "=", skill.id)
+                .where("version", "=", out.version)
+                .executeTakeFirst();
+            if (own?.object_prefix !== req.object_prefix) {
+                // Served from elsewhere (the platform row): the draft is not a version's files
+                const seq = await revertTrialCatalog(this.catalogDeps, req);
+                if (seq !== null && req.requested_in_conversation !== null) {
+                    drafts.seqs.push([req.requested_in_conversation, seq]);
+                }
+                drafts.prefixes.push(req.object_prefix);
+            }
         }
         const updated = await this.db
             .updateTable("skill_change_requests")
@@ -373,7 +263,6 @@ let SkillChangesService = class SkillChangesService {
             status: approved ? "approved" : "rejected",
             decided_by: accountId,
             decided_at: sql `now()`,
-            ...(approved && { skill_id: skillId }),
         })
             .where("id", "=", id)
             .returningAll()
@@ -386,136 +275,83 @@ let SkillChangesService = class SkillChangesService {
             target: id,
             detail: {
                 decision: approved ? "approved" : "rejected",
+                kind: req.kind,
                 agentId: req.agent_id,
-                skillId,
+                skillId: skill.id,
                 name: p.manifest.name,
-                version: approved ? version : p.version,
+                version,
                 requestedBy: req.requested_by_account,
-                conversationId: req.requested_in_conversation,
+                ...(req.requested_in_conversation !== null && {
+                    conversationId: req.requested_in_conversation,
+                }),
                 ...(body.note !== undefined && { note: body.note }),
             },
         });
-        // 拒绝：发起对话立即回退到正式版本（或移除），模型在当前位置看到提醒
-        const revertSeq = approved ? null : await this.revertTrial(req);
-        return { updated, revertSeq };
-    }
-    /** The transaction of {@link deleteAgentSkill}. */
-    async deleteAgentSkillIn(orgId, agentId, skillId, accountId, actorTokenId) {
-        await this.keyShareOrg(orgId);
-        const agent = await this.db
-            .selectFrom("agents")
-            .select(["owner_account_id", "deleted_at"])
-            .where("id", "=", agentId)
-            .where("org_id", "=", orgId)
-            .forNoKeyUpdate()
-            .executeTakeFirst();
-        const agentNotFound = () => new ApiError("agent.not_found", "Agent not found");
-        if (!agent || agent.deleted_at !== null)
-            throw agentNotFound();
-        if (agent.owner_account_id !== accountId) {
-            // 与 AgentsService 一致：看不到的 agent → 404，看得到但不是负责人 → 403
-            const visible = await this.db
-                .selectFrom("agents")
-                .select("id")
-                .where("id", "=", agentId)
-                .where(visibleTo(accountId))
-                .executeTakeFirst();
-            if (!visible)
-                throw agentNotFound();
-            throw new ApiError("forbidden", "Only the agent's owner can delete its skills");
+        // A rejected version: the proposing conversation goes back to the current version at once
+        // and the draft is deleted; a rejected share changes nothing
+        if (!approved && req.kind === "version") {
+            const seq = await revertTrialCatalog(this.catalogDeps, req);
+            if (seq !== null && req.requested_in_conversation !== null) {
+                drafts.seqs.push([req.requested_in_conversation, seq]);
+            }
+            drafts.prefixes.push(req.object_prefix);
         }
-        const r = await this.db
-            .updateTable("skills")
-            .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
-            .where("id", "=", skillId)
-            .where("org_id", "=", orgId)
-            .where("scope", "=", "agent")
-            .where("agent_id", "=", agentId)
-            .where("deleted_at", "is", null)
-            .returning(["name"])
-            .executeTakeFirst();
-        if (!r)
-            throw new ApiError("skill.not_found", "Skill not found");
-        const out = { prefixes: [], seqs: [] };
-        const pend = await this.db
+        return {
+            updated,
+            drafts,
+            usedOwner: approved && req.kind === "version" && owner !== undefined,
+        };
+    }
+    reread(id) {
+        return this.db
             .selectFrom("skill_change_requests")
             .selectAll()
-            .where("agent_id", "=", agentId)
-            .where("status", "=", "pending")
-            .where(sql `proposed_version -> 'manifest' ->> 'name'`, "=", r.name)
-            .forUpdate()
-            .executeTakeFirst();
-        if (pend) {
-            await this.db
-                .updateTable("skill_change_requests")
-                .set({ status: "cancelled", decided_at: sql `now()` })
-                .where("id", "=", pend.id)
-                .execute();
-            await audit(this.db.db, {
-                actorAccountId: accountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "skill.change_decided",
-                target: pend.id,
-                detail: { decision: "cancelled", reason: "skill_deleted", agentId, name: r.name },
-            });
-            const seq = await this.revertTrial(pend);
-            if (seq !== null)
-                out.seqs.push([pend.requested_in_conversation, seq]);
-            out.prefixes.push(pend.object_prefix);
-        }
-        await audit(this.db.db, {
-            actorAccountId: accountId,
-            ...(actorTokenId !== undefined && { actorTokenId }),
-            orgId,
-            action: "skill.deleted",
-            target: skillId,
-            detail: { name: r.name, agentId },
-        });
-        return out;
+            .where("id", "=", id)
+            .executeTakeFirstOrThrow();
     }
-    /** 当前用户（作为 agent 负责人）能决定的待处理申请，新的在前，最多 {@link SKILL_CHANGES_LIST_MAX} 条。 */
+    /**
+     * The org's pending requests when the account is an org admin (read live; anyone else gets
+     * none), newest first, at most {@link SKILL_CHANGES_LIST_MAX}.
+     */
     async listPending(orgId, accountId) {
+        if (!(await isOrgAdmin(this.db.db, orgId, accountId)))
+            return [];
         const rows = await this.db
             .selectFrom("skill_change_requests")
-            .innerJoin("agents", "agents.id", "skill_change_requests.agent_id")
-            .selectAll("skill_change_requests")
-            .where("skill_change_requests.org_id", "=", orgId)
-            .where("skill_change_requests.status", "=", "pending")
-            .where("agents.owner_account_id", "=", accountId)
-            .where("agents.deleted_at", "is", null)
-            .orderBy("skill_change_requests.created_at", "desc")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("status", "=", "pending")
+            .orderBy("created_at", "desc")
             .limit(SKILL_CHANGES_LIST_MAX)
             .execute();
         return this.views(rows);
     }
     /**
-     * 详情（含文件文本）：只有该 agent 的负责人与发起人能看，其他人一律 404（不泄露存在）。
-     * 草稿对象已删除（拒绝 / 取消）时文件内容为 null。
+     * The detail (with file texts): only org admins and the requester see it, anyone else 404 (the
+     * request's existence is not disclosed). A version draft's contents are null once it is deleted
+     * (rejected / cancelled); a share's files are the skill version's own and stay readable.
      */
     async get(orgId, id, accountId) {
         const row = await this.db
             .selectFrom("skill_change_requests")
-            .innerJoin("agents", "agents.id", "skill_change_requests.agent_id")
-            .selectAll("skill_change_requests")
-            .select("agents.owner_account_id")
-            .where("skill_change_requests.id", "=", id)
-            .where("skill_change_requests.org_id", "=", orgId)
-            .where("agents.deleted_at", "is", null)
+            .selectAll()
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
             .executeTakeFirst();
         if (!row)
             throw notFound();
-        if (row.owner_account_id !== accountId && row.requested_by_account !== accountId) {
+        if (row.requested_by_account !== accountId &&
+            !(await isOrgAdmin(this.db.db, orgId, accountId))) {
             throw notFound();
         }
         const [view] = await this.views([row]);
         if (!view)
             throw notFound();
-        const live = row.status === "pending" || row.status === "approved";
+        const live = row.kind === "share" || row.status === "pending" || row.status === "approved";
         const store = this.storage.kernel(orgId);
         const budget = { left: DETAIL_MAX_BYTES };
         const files = await readTexts(live ? store : undefined, row.object_prefix, row.proposed_version.manifest.files, budget);
-        // 改动已有技能：附上当前生效版本的文件（批准后它就是上一版，差异仍按申请时的当前版本显示）
+        // A change of an existing skill: the version in effect, for the difference
         let current = null;
         if (row.skill_id !== null) {
             const cur = await this.db
@@ -531,7 +367,7 @@ let SkillChangesService = class SkillChangesService {
                 .where("skills.id", "=", row.skill_id)
                 .where("skills.deleted_at", "is", null)
                 .executeTakeFirst();
-            // 已批准的申请自己就是当前版本：没有可比的「之前」，不给
+            // the request is the current version itself (a share, an approved version): no "before"
             if (cur && cur.object_prefix !== row.object_prefix) {
                 current = {
                     version: cur.version,
@@ -542,209 +378,42 @@ let SkillChangesService = class SkillChangesService {
         return { ...view, files, current };
     }
     /**
-     * 在事务 `t` 里由对话最新一份快照推出下一份并追加（不同才写）：先锁会话行（与 `EventLog.append` 同一把锁），
-     * 锁内读最新快照，保证「读最新 → 追加」之间没有别的快照插进来。返回写入的 seq，没写返回 null。
-     * Phase B: `derive` gets the whole latest payload, so `pinned` and `toolMap` are carried forward;
-     * a pinned entry is kept only while `skills` has the same id, version and source (pinned ⊆
-     * skills), and the pinned bodies still fit the size limit. The tool map is only recomputed at run
-     * start.
-     */
-    async appendCatalog(conversationId, derive, idemKey, runId) {
-        const base = (await lockLatestCatalog(this.db.db, conversationId)) ?? { skills: [] };
-        const derived = derive(base);
-        if (derived === null)
-            return null;
-        const skills = [...derived.skills].sort(byName);
-        const live = (p) => skills.some((s) => s.id === p.id && s.version === p.version && s.source === p.source);
-        const pinned = fitPinned((derived.pinned ?? []).filter(live), this.log, {
-            conversationId,
-        });
-        const next = {
-            skills,
-            ...(pinned.length > 0 && { pinned }),
-            ...(derived.toolMap !== undefined && { toolMap: derived.toolMap }),
-        };
-        if (sameSnapshot(base, next))
-            return null;
-        const written = await this.eventLog.appendIn(conversationId, [
-            {
-                type: "skills_catalog",
-                ...(runId !== undefined && { runId }),
-                idemKey,
-                payload: next,
-            },
-        ]);
-        return Math.max(...written.map((e) => e.seq));
-    }
-    /**
-     * 草稿不再生效（拒绝 / 取消）时，在事务 `t` 里给发起对话追加一份回退快照：由该对话最新一份快照推出——
-     * 来源是这份草稿的条目换成这个 agent 技能当前的正式版本（`t` 里已是决定之后的状态），没有正式版本就移除。
-     * 快照里已没有这份草稿 → 不写。对话正在运行时，提醒落在当前位置（构建时排在工具结果之后），下一步即生效。
-     * 移除时不推测同名的组织技能（快照里已被替换掉），下一次运行开始的解析会把它补回来。
+     * In the caller's transaction (`mandatory`: `AgentsService` holds the org and agent row locks),
+     * cancels the agent's pending requests of the given kinds (default both): marks them
+     * cancelled, audits, and for version drafts appends a reverting snapshot to each proposing
+     * conversation. The agent's delete cancels both kinds; an ownership transfer only shares (the
+     * new owner did not ask). After the commit the caller runs {@link finishCancel} to delete the
+     * drafts and publish the events.
      */
-    async revertTrial(req) {
-        const name = req.proposed_version.manifest.name;
-        const real = await this.db
-            .selectFrom("skills")
-            .innerJoin("skill_versions", (j) => j
-            .onRef("skill_versions.skill_id", "=", "skills.id")
-            .onRef("skill_versions.version", "=", "skills.current_version"))
-            .select([
-            "skills.id",
-            "skills.current_version",
-            "skill_versions.manifest",
-            "skill_versions.object_prefix",
-        ])
-            .where("skills.org_id", "=", req.org_id)
-            .where("skills.scope", "=", "agent")
-            .where("skills.agent_id", "=", req.agent_id)
-            .where("skills.name", "=", name)
-            .where("skills.deleted_at", "is", null)
-            .executeTakeFirst();
-        return this.appendCatalog(req.requested_in_conversation, (base) => {
-            if (!base.skills.some((s) => s.source === req.object_prefix))
-                return null;
-            const rest = base.skills.filter((s) => s.source !== req.object_prefix);
-            // The draft's pinned entry goes (Decision 8): the next run start pins the real version
-            return {
-                ...base,
-                // A manual-only current version (phase D) stays out of the model's catalog
-                skills: real && invocationOf(real.manifest).model
-                    ? [
-                        ...rest,
-                        {
-                            id: real.id,
-                            name,
-                            description: real.manifest.description,
-                            version: real.current_version,
-                            source: real.object_prefix,
-                        },
-                    ]
-                    : rest,
-                ...(base.pinned && {
-                    pinned: base.pinned.filter((p) => p.source !== req.object_prefix),
-                }),
-            };
-        }, `skills_catalog:revert:${req.id}`);
-    }
-    /**
-     * In the caller's transaction (`mandatory`: `AgentsService.softDelete` holds the org and agent
-     * row locks), cancels every pending skill change of the agent: marks them cancelled, audits, and
-     * appends a reverting snapshot to each requesting conversation. After the commit the caller runs
-     * {@link finishCancel} to delete the drafts and publish the events.
-     */
-    async cancelPendingForAgent(orgId, agentId, actorAccountId, reason, actorTokenId) {
+    async cancelPendingForAgent(orgId, agentId, actorAccountId, reason, actorTokenId, kinds = ["share", "version"]) {
         const rows = await this.db
             .selectFrom("skill_change_requests")
             .selectAll()
             .where("org_id", "=", orgId)
             .where("agent_id", "=", agentId)
             .where("status", "=", "pending")
+            .where("kind", "in", [...kinds])
             .orderBy("created_at")
             .forUpdate()
             .execute();
         const out = { prefixes: [], seqs: [] };
         for (const r of rows) {
-            await this.db
-                .updateTable("skill_change_requests")
-                .set({ status: "cancelled", decided_at: sql `now()` })
-                .where("id", "=", r.id)
-                .execute();
-            await audit(this.db.db, {
+            await cancelRequestIn(this.catalogDeps, r, out, {
                 actorAccountId,
                 ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "skill.change_decided",
-                target: r.id,
-                detail: { decision: "cancelled", reason, agentId, name: r.proposed_version.manifest.name },
+                reason,
             });
-            const seq = await this.revertTrial(r);
-            if (seq !== null)
-                out.seqs.push([r.requested_in_conversation, seq]);
-            out.prefixes.push(r.object_prefix);
         }
         return out;
     }
-    /** {@link cancelPendingForAgent} 提交之后：发布事件、尽力删除草稿对象。 */
+    /** After {@link cancelPendingForAgent} commits: publishes the events, deletes the drafts. */
     async finishCancel(orgId, c) {
         for (const [conv, seq] of c.seqs)
             await this.eventLog.notify(conv, seq);
         for (const p of c.prefixes)
             await this.deletePrefix(orgId, p);
     }
-    /** 新技能的数量上限（含待批准的新技能；`excluding` 是将被取代的申请）。 */
-    async assertBelowCap(agentId, excluding) {
-        const skills = await this.db
-            .selectFrom("skills")
-            .select((eb) => eb.fn.countAll().as("n"))
-            .where("scope", "=", "agent")
-            .where("agent_id", "=", agentId)
-            .where("deleted_at", "is", null)
-            .executeTakeFirstOrThrow();
-        let q = this.db
-            .selectFrom("skill_change_requests")
-            .select((eb) => eb.fn.countAll().as("n"))
-            .where("agent_id", "=", agentId)
-            .where("status", "=", "pending")
-            .where("skill_id", "is", null);
-        if (excluding !== undefined)
-            q = q.where("id", "!=", excluding);
-        const drafts = await q.executeTakeFirstOrThrow();
-        if (Number(skills.n) + Number(drafts.n) >= AGENT_SKILLS_MAX)
-            throw new ToolError(capText());
-    }
-    /** 写一个版本并让 `current_version` 指向它（技能不存在则新建）。 */
-    async createVersion(v) {
-        if (v.exists) {
-            await this.db
-                .updateTable("skills")
-                .set({
-                current_version: v.version,
-                description: v.manifest.description,
-                updated_at: sql `now()`,
-            })
-                .where("id", "=", v.skillId)
-                .execute();
-        }
-        else {
-            await this.db
-                .insertInto("skills")
-                .values({
-                id: v.skillId,
-                org_id: v.orgId,
-                scope: "agent",
-                agent_id: v.agentId,
-                name: v.manifest.name,
-                description: v.manifest.description,
-                current_version: v.version,
-                created_by: v.createdBy,
-            })
-                .execute();
-        }
-        await this.db
-            .insertInto("skill_versions")
-            .values({
-            skill_id: v.skillId,
-            version: v.version,
-            manifest: JSON.stringify(v.manifest),
-            object_prefix: v.prefix,
-            created_by: v.createdBy,
-        })
-            .execute();
-    }
-    /**
-     * 先给组织行加 KEY SHARE 锁，再锁 agent 行：与 `AgentsService`（组织行 FOR UPDATE → agent 行）同一顺序。
-     * 不先锁的话，本事务持有 agent 行后插入引用组织的行（外键取 KEY SHARE）会与之互相等待（40P01）。
-     */
-    async keyShareOrg(orgId) {
-        await this.db
-            .selectFrom("orgs")
-            .select("id")
-            .where("id", "=", orgId)
-            .forKeyShare()
-            .executeTakeFirst();
-    }
-    /** 尽力删除草稿对象（失败只记日志：孤儿对象随组织数据清理删除）。 */
+    /** Deletes draft objects best effort (a failure is only logged: org data cleanup removes them). */
     async deletePrefix(orgId, prefix) {
         try {
             await this.storage.kernel(orgId).deletePrefix(prefix);
@@ -753,7 +422,7 @@ let SkillChangesService = class SkillChangesService {
             this.log.warn("skill draft cleanup failed", { orgId, prefix, err });
         }
     }
-    /** 补齐 agent 名。 */
+    /** Adds the agent names and requester names. */
     async views(rows) {
         if (rows.length === 0)
             return [];
@@ -779,6 +448,7 @@ let SkillChangesService = class SkillChangesService {
         return rows.map((r) => ({
             id: r.id,
             orgId: r.org_id,
+            kind: r.kind,
             agent: { id: r.agent_id, name: names.get(r.agent_id) ?? "" },
             skillId: r.skill_id,
             name: r.proposed_version.manifest.name,
@@ -789,22 +459,16 @@ let SkillChangesService = class SkillChangesService {
             requestedBy: r.requested_by_account,
             requestedByName: requesterNames.get(r.requested_by_account) ?? "",
             requestedInConversation: r.requested_in_conversation,
-            conversationPath: `/chat/${r.requested_in_conversation}`,
+            conversationPath: r.requested_in_conversation === null ? null : `/chat/${r.requested_in_conversation}`,
             decidedBy: r.decided_by,
             decidedAt: r.decided_at === null ? null : iso(r.decided_at),
             createdAt: iso(r.created_at),
         }));
     }
 };
-__decorate([
-    Transactional()
-], SkillChangesService.prototype, "writeIn", null);
 __decorate([
     Transactional()
 ], SkillChangesService.prototype, "decideIn", null);
-__decorate([
-    Transactional()
-], SkillChangesService.prototype, "deleteAgentSkillIn", null);
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], SkillChangesService.prototype, "cancelPendingForAgent", null);
@@ -814,12 +478,16 @@ SkillChangesService = __decorate([
     __param(1, Inject(StorageService)),
     __param(2, Inject(EventLog)),
     __param(3, Inject(KERNEL_LOGGER)),
-    __param(4, Inject(TransactionHost))
+    __param(4, Inject(TransactionHost)),
+    __param(5, Inject(OrgLock)),
+    __param(6, Inject(SkillsService))
 ], SkillChangesService);
 export { SkillChangesService };
 /**
- * 按清单顺序读文件文本，共用读取额度 `budget`（超出、对象缺失、存储出错时该文件内容为 null）。
- * `store` 为 undefined 表示不读（如草稿已删除）。
+ * Reads the files' text in manifest order, sharing the read budget `budget`. A file's content is
+ * null past the budget, when its object is missing, on a storage error, and for a binary file
+ * (not valid UTF-8, or holding a NUL byte), so the inbox never shows garbage. `store` undefined
+ * means nothing is read (e.g. the draft is deleted).
  */
 async function readTexts(store, prefix, manifest, budget) {
     const out = [];
@@ -829,8 +497,10 @@ async function readTexts(store, prefix, manifest, budget) {
             try {
                 const got = await store.get(`${prefix}${f.path}`);
                 if (got) {
-                    content = await new Response(got.body).text();
+                    const bytes = await new Response(got.body).arrayBuffer();
                     budget.left -= f.size;
+                    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+                    content = text.includes("\u0000") ? null : text;
                 }
             }
             catch {
@@ -841,22 +511,3 @@ async function readTexts(store, prefix, manifest, budget) {
     }
     return out;
 }
-/** 并发写入全部文件。 */
-async function putAll(store, prefix, files) {
-    const queue = [...files];
-    await Promise.all(Array.from({ length: Math.min(PUT_CONCURRENCY, queue.length) }, async () => {
-        for (let f = queue.shift(); f; f = queue.shift()) {
-            await store.put(`${prefix}${f.path}`, f.data, {
-                contentType: "application/octet-stream",
-                size: f.size,
-            });
-        }
-    }));
-}
-/** 存储错误 → 给模型的说明（存储不可用可重试）；其余原样抛出。 */
-function storageError(e) {
-    if (e instanceof ApiError && e.code === "storage.unavailable") {
-        return new ToolError(STORAGE_UNAVAILABLE_TEXT);
-    }
-    return e;
-}