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

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`（工具 `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.
  */
 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): 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;
 }