@capybara-hq/kernel 0.1.0-rc.19 → 0.1.0-rc.20

package/dist/skills/catalog.d.ts

@@ -29,8 +29,8 @@ export interface EffectiveSkillsInput {
     /** 本次运行固定的 agent 版本的定义（`skills.orgSkills` 是选中的组织技能 id）。 */
     agent: Pick<AgentDefinition, "skills">;
     /**
-     * 对话 id：共享 agent 待批准的技能改动（T15，`skill_change_requests`）只在发起它的对话里生效（试用），
-     * 在这里按对话覆盖。
+     * The conversation id: a pending skill change of the agent (`skill_change_requests`, a version
+     * draft) applies only in the conversation that proposed it (a trial) and is overlaid here.
      */
     conversationId: string;
 }
@@ -42,9 +42,11 @@ export interface EffectiveSkillsInput {
  * - 版本取 `current_version`，描述取该版本清单里的描述。
  * 组织技能与 agent 自己的技能同名时只保留 agent 自己的（更具体；`/skills/<name>/` 与按名字加载都不能有两个）。
  *
- * 试用（T15，R4）：这个 agent 待批准、且由本对话发起的技能改动，按名字替换对应技能的版本 / 新增技能
- * （id 为已有技能或预先分配的 id，版本为批准后预期的版本号）；其他对话照旧用 `current_version`。
- * 批准后版本成为当前版本，各对话下一次运行开始时由快照差异得到提醒；拒绝 / 取消后发起对话回到当前版本。
+ * Trials: a pending version proposal of this agent made in this conversation replaces, by name,
+ * the version of its skill (the id of the existing skill, the version it would become on
+ * approval); other conversations keep `current_version`. Once approved it is the current version
+ * and every conversation gets a notice from the snapshot difference at its next run start; after
+ * a reject or cancel the proposing conversation goes back to the current version.
  */
 export declare function resolveEffectiveSkills(db: KernelSchemaDb, input: EffectiveSkillsInput, log?: Pick<Logger, "warn">): Promise<CatalogSkill[]>;
 /** The invocation metadata of a skill version: the manifest's, or the defaults when absent. */
@@ -125,7 +127,7 @@ export declare const skillsCatalogIdemKey: (runId: string) => string;
 /**
  * 在调用方事务里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
  * `db` is the caller's transaction handle (`KernelDb.db` inside `@Transactional`).
- * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、SkillWrite、拒绝时的回退）插不进来。
+ * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、技能注册、拒绝时的回退）插不进来。
  */
 export declare function lockLatestCatalog(db: KernelSchemaDb, conversationId: string): Promise<SkillsSnapshot | undefined>;
 /**

package/dist/skills/catalog.js

@@ -40,9 +40,11 @@ export const PINNED_SKILLS_LIMITS = { count: 3, totalBytes: 32768 };
  * - 版本取 `current_version`，描述取该版本清单里的描述。
  * 组织技能与 agent 自己的技能同名时只保留 agent 自己的（更具体；`/skills/<name>/` 与按名字加载都不能有两个）。
  *
- * 试用（T15，R4）：这个 agent 待批准、且由本对话发起的技能改动，按名字替换对应技能的版本 / 新增技能
- * （id 为已有技能或预先分配的 id，版本为批准后预期的版本号）；其他对话照旧用 `current_version`。
- * 批准后版本成为当前版本，各对话下一次运行开始时由快照差异得到提醒；拒绝 / 取消后发起对话回到当前版本。
+ * Trials: a pending version proposal of this agent made in this conversation replaces, by name,
+ * the version of its skill (the id of the existing skill, the version it would become on
+ * approval); other conversations keep `current_version`. Once approved it is the current version
+ * and every conversation gets a notice from the snapshot difference at its next run start; after
+ * a reject or cancel the proposing conversation goes back to the current version.
  */
 export async function resolveEffectiveSkills(db, input, log) {
     return forModel(await resolveSkills(db, input), input, log).map((r) => r.skill);
@@ -112,6 +114,8 @@ export async function resolveSkills(db, input, log) {
             .where("agent_id", "=", input.agentId)
             .where("org_id", "=", input.orgId)
             .where("status", "=", "pending")
+            // a share request carries no new files: never a trial
+            .where("kind", "=", "version")
             .execute();
     for (const { proposed_version: p, object_prefix } of trials) {
         effective.set(p.manifest.name, {
@@ -314,7 +318,7 @@ export const skillsCatalogIdemKey = (runId) => `skills_catalog:${runId}`;
 /**
  * 在调用方事务里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
  * `db` is the caller's transaction handle (`KernelDb.db` inside `@Transactional`).
- * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、SkillWrite、拒绝时的回退）插不进来。
+ * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、技能注册、拒绝时的回退）插不进来。
  */
 export async function lockLatestCatalog(db, conversationId) {
     await db

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

@@ -1,10 +1,8 @@
 import { z } from "zod";
-import { AgentsService } from "../agents/agents.service.js";
 import { type Principal } from "../identity/principal.js";
 import { InboxService, type InboxView } from "../inbox/inbox.service.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { type SkillChangeDetail, SkillChangesService, type SkillChangeView } from "./changes.service.js";
-import { type SkillSummary, SkillsService } from "./skills.service.js";
 declare const DecideBody: z.ZodObject<{
     decision: z.ZodEnum<{
         approve: "approve";
@@ -16,9 +14,11 @@ declare const NoticeParamsSchema: z.ZodObject<{
     id: z.ZodString;
 }, z.core.$strip>;
 /**
- * 共享 agent 的技能变更申请（`/api/v1/orgs/:orgId/skill-changes`，M5 T15，R4）。动作 `approvals.decide`
- * （访客起、仅限用户主体：agent / 服务令牌不能决定，R2）；能否决定由服务按该 agent **当前的负责人**判定，
- * 其他人 403 `skill_change.not_owner`。详情只给负责人与发起人，其他人 404。
+ * Skill change requests (`/api/v1/orgs/:orgId/skill-changes`): sharing an agent skill with the org
+ * and version proposals on a shared skill (spec §5.4, §5.5), user principals only (agents and
+ * service tokens never decide). `GET /:id` is `approvals.decide`; the service shows it to org
+ * admins and the requester only, anyone else 404. `POST /:id/decide` is `skills.manage` (org
+ * admins; the service re-checks the role live under the org row lock).
  */
 export declare class SkillChangesController {
     private readonly changes;
@@ -30,23 +30,6 @@ export declare class SkillChangesController {
         skillChange: SkillChangeView;
     }>;
 }
-/**
- * agent 自己的技能（`/api/v1/orgs/:orgId/agents/:agentId/skills`，M5 T15 / T16）：
- * - `GET /`：列表（`scope=agent`、未删除，按名字），与 `GET /agents/:agentId` 同一可见性（`agents.use`；
- *   看不到的 agent → 404 `agent.not_found`；服务令牌只看到 visibility='org' 的 agent）；
- * - `DELETE /:skillId`：软删除，只有该 agent 当前的负责人（其他人 403 `forbidden`），仅限用户主体
- *   （`agents.create` 属 HUMAN_ONLY）。同名的待处理改动一并取消。
- */
-export declare class AgentSkillsController {
-    private readonly changes;
-    private readonly agents;
-    private readonly skills;
-    constructor(changes: SkillChangesService, agents: AgentsService, skills: SkillsService);
-    list(principal: Principal, org: OrgContext, agentId: string): Promise<{
-        skills: SkillSummary[];
-    }>;
-    remove(principal: Principal, org: OrgContext, agentId: string, skillId: string): Promise<void>;
-}
 /**
  * 收件箱（`GET /api/v1/orgs/:orgId/inbox`，计划取舍 C6：按类型汇总）：当前用户待处理的工具审批与
  * 能决定的技能变更，新的在前、最多 100 项（`truncated` 表示还有更多）。仅限用户主体。

package/dist/skills/changes.controller.js

@@ -7,9 +7,8 @@ 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 { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { Controller, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
 import { z } from "zod";
-import { AgentsService } from "../agents/agents.service.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { InboxNoticeParams } from "../inbox/inbox.schemas.js";
 import { InboxService } from "../inbox/inbox.service.js";
@@ -17,7 +16,6 @@ import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { SkillChangesService, } from "./changes.service.js";
-import { SkillsService } from "./skills.service.js";
 const DecideBody = z
     .object({
     decision: z.enum(["approve", "reject"]),
@@ -30,9 +28,11 @@ const NoticeParamsSchema = InboxNoticeParams;
 class NoticeParams extends createZodDto(NoticeParamsSchema, "InboxNoticeParams") {
 }
 /**
- * 共享 agent 的技能变更申请（`/api/v1/orgs/:orgId/skill-changes`，M5 T15，R4）。动作 `approvals.decide`
- * （访客起、仅限用户主体：agent / 服务令牌不能决定，R2）；能否决定由服务按该 agent **当前的负责人**判定，
- * 其他人 403 `skill_change.not_owner`。详情只给负责人与发起人，其他人 404。
+ * Skill change requests (`/api/v1/orgs/:orgId/skill-changes`): sharing an agent skill with the org
+ * and version proposals on a shared skill (spec §5.4, §5.5), user principals only (agents and
+ * service tokens never decide). `GET /:id` is `approvals.decide`; the service shows it to org
+ * admins and the requester only, anyone else 404. `POST /:id/decide` is `skills.manage` (org
+ * admins; the service re-checks the role live under the org row lock).
  */
 let SkillChangesController = class SkillChangesController {
     changes;
@@ -60,7 +60,7 @@ __decorate([
 __decorate([
     Post(":id/decide"),
     HttpCode(200),
-    OrgAction("approvals.decide"),
+    OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
@@ -71,54 +71,6 @@ SkillChangesController = __decorate([
     __param(0, Inject(SkillChangesService))
 ], SkillChangesController);
 export { SkillChangesController };
-/**
- * agent 自己的技能（`/api/v1/orgs/:orgId/agents/:agentId/skills`，M5 T15 / T16）：
- * - `GET /`：列表（`scope=agent`、未删除，按名字），与 `GET /agents/:agentId` 同一可见性（`agents.use`；
- *   看不到的 agent → 404 `agent.not_found`；服务令牌只看到 visibility='org' 的 agent）；
- * - `DELETE /:skillId`：软删除，只有该 agent 当前的负责人（其他人 403 `forbidden`），仅限用户主体
- *   （`agents.create` 属 HUMAN_ONLY）。同名的待处理改动一并取消。
- */
-let AgentSkillsController = class AgentSkillsController {
-    changes;
-    agents;
-    skills;
-    constructor(changes, agents, skills) {
-        this.changes = changes;
-        this.agents = agents;
-        this.skills = skills;
-    }
-    async list(principal, org, agentId) {
-        await this.agents.get(org.orgId, agentId, principal.kind === "user" ? principal.account.id : null);
-        return { skills: await this.skills.listForAgent(org.orgId, agentId) };
-    }
-    async remove(principal, org, agentId, skillId) {
-        const p = requireUser(principal);
-        await this.changes.deleteAgentSkill(org.orgId, agentId, skillId, p.account.id, patTokenId(p));
-    }
-};
-__decorate([
-    Get(),
-    OrgAction("agents.use"),
-    __param(0, CurrentPrincipal()),
-    __param(1, CurrentOrg()),
-    __param(2, Param("agentId"))
-], AgentSkillsController.prototype, "list", null);
-__decorate([
-    Delete(":skillId"),
-    HttpCode(204),
-    OrgAction("agents.create"),
-    __param(0, CurrentPrincipal()),
-    __param(1, CurrentOrg()),
-    __param(2, Param("agentId")),
-    __param(3, Param("skillId"))
-], AgentSkillsController.prototype, "remove", null);
-AgentSkillsController = __decorate([
-    Controller("api/v1/orgs/:orgId/agents/:agentId/skills"),
-    __param(0, Inject(SkillChangesService)),
-    __param(1, Inject(AgentsService)),
-    __param(2, Inject(SkillsService))
-], AgentSkillsController);
-export { AgentSkillsController };
 /**
  * 收件箱（`GET /api/v1/orgs/:orgId/inbox`，计划取舍 C6：按类型汇总）：当前用户待处理的工具审批与
  * 能决定的技能变更，新的在前、最多 100 项（`truncated` 表示还有更多）。仅限用户主体。

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

@@ -1,30 +1,31 @@
 import { EventLog } from "../conversations/event-log.js";
-import type { SkillManifest } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
 import { StorageService } from "../storage/storage.service.js";
-/**
- * 每个 agent 自己的技能（`scope = agent`）上限，含待批准的新技能。远低于目录快照的上限（`SKILLS_CATALOG_MAX`），
- * 正常使用不会让目录被截断。
- */
-export declare const AGENT_SKILLS_MAX = 50;
-/** 收件箱一次最多返回的技能变更数。 */
+import { type CancelledDrafts } from "./conversation-catalog.js";
+import { SkillsService } from "./skills.service.js";
+export type { CancelledDrafts } from "./conversation-catalog.js";
+/** The most skill changes one inbox read returns. */
 export declare const SKILL_CHANGES_LIST_MAX = 100;
 export type SkillChangeStatus = "pending" | "approved" | "rejected" | "cancelled";
-/** 一条技能变更申请（列表 / 收件箱）。 */
+/** A request kind: sharing an agent skill with the org, or a new version of a shared skill. */
+export type SkillChangeKind = "share" | "version";
+/** One skill change request (list / inbox). */
 export interface SkillChangeView {
     id: string;
     orgId: string;
+    kind: SkillChangeKind;
     agent: {
         id: string;
         name: string;
     };
-    /** 已有技能的 id；新技能为 null（批准后才有）。 */
+    /** A share: the agent skill; a version proposal: the shared org skill. */
     skillId: string | null;
     name: string;
     description: string;
-    /** 批准后预期的版本号。 */
+    /** A share: the version shared; a version proposal: the version it would become. */
     version: number;
     files: {
         path: string;
@@ -32,24 +33,26 @@ export interface SkillChangeView {
     }[];
     status: SkillChangeStatus;
     requestedBy: string;
-    /** 发起人的显示名（账号已不存在时为空串）。 */
+    /** The requester's display name (empty when the account no longer exists). */
     requestedByName: string;
-    requestedInConversation: string;
-    /** 网页中发起对话的路径（不含语言前缀）。 */
-    conversationPath: string;
+    /** The proposing conversation (null for a share request and a proposal made on the web). */
+    requestedInConversation: string | null;
+    /** The proposing conversation's web path (no locale prefix), or null. */
+    conversationPath: string | null;
     decidedBy: string | null;
     decidedAt: string | null;
     createdAt: string;
 }
-/** 详情里的一个文件：文本内容读不到（已删除、超出读取上限）时为 null。 */
+/** One file of a detail: its text, or null when it cannot be read (deleted, over the read cap). */
 export interface SkillChangeFile {
     path: string;
     size: number;
     content: string | null;
 }
 /**
- * 详情：每个文件附文本内容（草稿已删除时为 null）；`current` 是改动已有技能时该技能当前生效的版本
- * （网页据此显示差异），新技能或技能已删除时为 null。
+ * The detail: each file with its text (null when the draft is deleted); `current` is the version
+ * in effect when the request changes an existing skill (the web shows the difference), null for a
+ * share (the shared version is the current one) or when the skill is deleted.
  */
 export interface SkillChangeDetail extends Omit<SkillChangeView, "files"> {
     files: SkillChangeFile[];
@@ -58,53 +61,20 @@ export interface SkillChangeDetail extends Omit<SkillChangeView, "files"> {
         files: SkillChangeFile[];
     } | null;
 }
-/** {@link SkillChangesService.write} 的调用上下文（来自工具调用）。 */
-export interface SkillWriteContext {
-    orgId: string;
-    agentId: string;
-    /** 触发本次运行的人。 */
-    accountId: string;
-    conversationId: string;
-    runId?: string;
-}
-/** 已合成、已校验的技能（见 tools/builtins/skill-write.ts 的 `buildSkillWrite`）。 */
-export interface SkillWritePackage {
-    name: string;
-    description: string;
-    files: {
-        path: string;
-        data: Uint8Array;
-        size: number;
-    }[];
-    manifest: SkillManifest;
-}
-/** 写技能的结果：私有 agent 直接生成版本，共享 agent 生成变更申请。 */
-export type SkillWriteOutcome = {
-    kind: "version";
-    skillId: string;
-    version: number;
-    created: boolean;
-} | {
-    kind: "requested";
-    requestId: string;
-    skillId: string;
-    version: number;
-};
-/** 被取消的草稿：提交后要删的对象前缀与要发布的（对话, seq）。 */
-export interface CancelledDrafts {
-    prefixes: string[];
-    seqs: [string, number][];
-}
 /**
- * agent 自写技能与共享 agent 的技能变更审批（M5 T15，R4）：
- * - `write`（工具 `SkillWrite` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
- *   期间只有发起对话试用（`resolveEffectiveSkills` 按对话合并）；两种情况都在同一事务里往发起对话追加一份
- *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `Skill`；
- * - `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.
  */
 export declare class SkillChangesService {
     private readonly db;
@@ -112,74 +82,58 @@ export declare class SkillChangesService {
     private readonly eventLog;
     private readonly log;
     readonly txHost: TransactionHost;
-    constructor(db: KernelDb, storage: StorageService, eventLog: EventLog, log: KernelLogger, txHost: TransactionHost);
-    /** 写技能（见类注释）。模型可见的失败抛 `ToolError`。 */
-    write(ctx: SkillWriteContext, pkg: SkillWritePackage): Promise<SkillWriteOutcome>;
+    private readonly orgLock;
+    /** An approved version is an org skill version. */
+    private readonly skills;
+    private readonly catalogDeps;
+    constructor(db: KernelDb, storage: StorageService, eventLog: EventLog, log: KernelLogger, txHost: TransactionHost, orgLock: OrgLock, 
+    /** An approved version is an org skill version. */
+    skills: SkillsService);
     /**
-     * 负责人决定一条申请：只有该 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`.
      */
     decide(orgId: string, id: string, accountId: string, body: {
         decision: "approve" | "reject";
         note?: string | undefined;
     }, actorTokenId?: string): Promise<SkillChangeView>;
+    /** A version draft's files as a package (as registered), or 503 when one cannot be read. */
+    private readDraft;
     /**
-     * 软删除 agent 自己的一个技能（只有该 agent 当前的负责人；其他人 403 `forbidden`）：技能不存在 / 已删除 / 不属于该
-     * agent → `skill.not_found`。同名的待处理改动一并取消（发起对话追加回退快照，提交后删草稿）。审计 `skill.deleted`。
-     * 各对话下一次运行开始时目录里去掉它；之后同名可再写为新技能。
+     * 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.
      */
-    deleteAgentSkill(orgId: string, agentId: string, skillId: string, accountId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
-    /** The transaction of {@link write}. */
-    private writeIn;
-    /** The transaction of {@link decide}. */
     private decideIn;
-    /** The transaction of {@link deleteAgentSkill}. */
-    private deleteAgentSkillIn;
-    /** 当前用户（作为 agent 负责人）能决定的待处理申请，新的在前，最多 {@link SKILL_CHANGES_LIST_MAX} 条。 */
-    listPending(orgId: string, accountId: string): Promise<SkillChangeView[]>;
+    private reread;
     /**
-     * 详情（含文件文本）：只有该 agent 的负责人与发起人能看，其他人一律 404（不泄露存在）。
-     * 草稿对象已删除（拒绝 / 取消）时文件内容为 null。
+     * 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}.
      */
-    get(orgId: string, id: string, accountId: string): Promise<SkillChangeDetail>;
-    /**
-     * 在事务 `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.
-     */
-    private appendCatalog;
+    listPending(orgId: string, accountId: string): Promise<SkillChangeView[]>;
     /**
-     * 草稿不再生效（拒绝 / 取消）时，在事务 `t` 里给发起对话追加一份回退快照：由该对话最新一份快照推出——
-     * 来源是这份草稿的条目换成这个 agent 技能当前的正式版本（`t` 里已是决定之后的状态），没有正式版本就移除。
-     * 快照里已没有这份草稿 → 不写。对话正在运行时，提醒落在当前位置（构建时排在工具结果之后），下一步即生效。
-     * 移除时不推测同名的组织技能（快照里已被替换掉），下一次运行开始的解析会把它补回来。
+     * 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.
      */
-    private revertTrial;
+    get(orgId: string, id: string, accountId: string): Promise<SkillChangeDetail>;
     /**
-     * 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.
+     * 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.
      */
-    cancelPendingForAgent(orgId: string, agentId: string, actorAccountId: string, reason: string, actorTokenId?: string): Promise<CancelledDrafts>;
-    /** {@link cancelPendingForAgent} 提交之后：发布事件、尽力删除草稿对象。 */
+    cancelPendingForAgent(orgId: string, agentId: string, actorAccountId: string, reason: string, actorTokenId?: string, kinds?: readonly SkillChangeKind[]): Promise<CancelledDrafts>;
+    /** After {@link cancelPendingForAgent} commits: publishes the events, deletes the drafts. */
     finishCancel(orgId: string, c: CancelledDrafts): Promise<void>;
-    /** 新技能的数量上限（含待批准的新技能；`excluding` 是将被取代的申请）。 */
-    private assertBelowCap;
-    /** 写一个版本并让 `current_version` 指向它（技能不存在则新建）。 */
-    private createVersion;
-    /**
-     * 先给组织行加 KEY SHARE 锁，再锁 agent 行：与 `AgentsService`（组织行 FOR UPDATE → agent 行）同一顺序。
-     * 不先锁的话，本事务持有 agent 行后插入引用组织的行（外键取 KEY SHARE）会与之互相等待（40P01）。
-     */
-    private keyShareOrg;
-    /** 尽力删除草稿对象（失败只记日志：孤儿对象随组织数据清理删除）。 */
+    /** Deletes draft objects best effort (a failure is only logged: org data cleanup removes them). */
     private deletePrefix;
-    /** 补齐 agent 名。 */
+    /** Adds the agent names and requester names. */
     private views;
 }