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

package/dist/skills/changes.controller.js

@@ -0,0 +1,136 @@
+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 { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { z } from "zod";
+import { AGENTS, INBOX, SKILL_CHANGES, 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 DecideBody = z
+    .object({
+    decision: z.enum(["approve", "reject"]),
+    note: z.string().max(1000).optional(),
+})
+    .strict();
+/**
+ * 共享 agent 的技能变更申请（`/api/v1/orgs/:orgId/skill-changes`，M5 T15，R4）。动作 `approvals.decide`
+ * （访客起、仅限用户主体：agent / 服务令牌不能决定，R2）；能否决定由服务按该 agent **当前的负责人**判定，
+ * 其他人 403 `skill_change.not_owner`。详情只给负责人与发起人，其他人 404。
+ */
+let SkillChangesController = class SkillChangesController {
+    changes;
+    constructor(changes) {
+        this.changes = changes;
+    }
+    async get(principal, org, id) {
+        const p = requireUser(principal);
+        return { skillChange: await this.changes.get(org.orgId, id, p.account.id) };
+    }
+    async decide(principal, org, id, body) {
+        const p = requireUser(principal);
+        return {
+            skillChange: await this.changes.decide(org.orgId, id, p.account.id, body, patTokenId(p)),
+        };
+    }
+};
+__decorate([
+    Get(":id"),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id"))
+], SkillChangesController.prototype, "get", null);
+__decorate([
+    Post(":id/decide"),
+    HttpCode(200),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("id")),
+    __param(3, Body(new ZodPipe(DecideBody)))
+], SkillChangesController.prototype, "decide", null);
+SkillChangesController = __decorate([
+    Controller("api/v1/orgs/:orgId/skill-changes"),
+    __param(0, Inject(SKILL_CHANGES))
+], 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(SKILL_CHANGES)),
+    __param(1, Inject(AGENTS)),
+    __param(2, Inject(SKILLS))
+], AgentSkillsController);
+export { AgentSkillsController };
+/**
+ * 收件箱（`GET /api/v1/orgs/:orgId/inbox`，计划取舍 C6：按类型汇总）：当前用户待处理的工具审批与
+ * 能决定的技能变更，新的在前、最多 100 项（`truncated` 表示还有更多）。仅限用户主体。
+ */
+let InboxController = class InboxController {
+    inbox;
+    constructor(inbox) {
+        this.inbox = inbox;
+    }
+    async list(principal, org) {
+        const p = requireUser(principal);
+        return this.inbox.list(org.orgId, p.account.id);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("approvals.decide"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], InboxController.prototype, "list", null);
+InboxController = __decorate([
+    Controller("api/v1/orgs/:orgId/inbox"),
+    __param(0, Inject(INBOX))
+], InboxController);
+export { InboxController };

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

@@ -0,0 +1,175 @@
+import { type Logger } from "@capybara-hq/plugin-sdk";
+import { type Transaction } from "kysely";
+import type { EventLog } from "../conversations/event-log.js";
+import type { KernelDatabase, KernelDb, SkillManifest } from "../db/kernel-schema.js";
+import type { StorageService } from "../storage/storage.service.js";
+type Trx = Transaction<KernelDatabase>;
+/**
+ * 每个 agent 自己的技能（`scope = agent`）上限，含待批准的新技能。远低于目录快照的上限（`SKILLS_CATALOG_MAX`），
+ * 正常使用不会让目录被截断。
+ */
+export declare const AGENT_SKILLS_MAX = 50;
+/** 收件箱一次最多返回的技能变更数。 */
+export declare const SKILL_CHANGES_LIST_MAX = 100;
+export type SkillChangeStatus = "pending" | "approved" | "rejected" | "cancelled";
+/** 一条技能变更申请（列表 / 收件箱）。 */
+export interface SkillChangeView {
+    id: string;
+    orgId: string;
+    agent: {
+        id: string;
+        name: string;
+    };
+    /** 已有技能的 id；新技能为 null（批准后才有）。 */
+    skillId: string | null;
+    name: string;
+    description: string;
+    /** 批准后预期的版本号。 */
+    version: number;
+    files: {
+        path: string;
+        size: number;
+    }[];
+    status: SkillChangeStatus;
+    requestedBy: string;
+    /** 发起人的显示名（账号已不存在时为空串）。 */
+    requestedByName: string;
+    requestedInConversation: string;
+    /** 网页中发起对话的路径（不含语言前缀）。 */
+    conversationPath: string;
+    decidedBy: string | null;
+    decidedAt: string | null;
+    createdAt: string;
+}
+/** 详情里的一个文件：文本内容读不到（已删除、超出读取上限）时为 null。 */
+export interface SkillChangeFile {
+    path: string;
+    size: number;
+    content: string | null;
+}
+/**
+ * 详情：每个文件附文本内容（草稿已删除时为 null）；`current` 是改动已有技能时该技能当前生效的版本
+ * （网页据此显示差异），新技能或技能已删除时为 null。
+ */
+export interface SkillChangeDetail extends Omit<SkillChangeView, "files"> {
+    files: SkillChangeFile[];
+    current: {
+        version: number;
+        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][];
+}
+export interface SkillChangesDeps {
+    db: KernelDb;
+    storage: StorageService;
+    eventLog: Pick<EventLog, "append" | "notify">;
+    log: Pick<Logger, "warn">;
+}
+/**
+ * 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>/`；无进程内状态。
+ */
+export declare class SkillChangesService {
+    private readonly d;
+    constructor(d: SkillChangesDeps);
+    /** 写技能（见类注释）。模型可见的失败抛 `ToolError`。 */
+    write(ctx: SkillWriteContext, pkg: SkillWritePackage): Promise<SkillWriteOutcome>;
+    /**
+     * 负责人决定一条申请：只有该 agent 当前的负责人（实时读）能决定，其他人 → 403 `skill_change.not_owner`；
+     * 已处理 → 409 `skill_change.already_decided`；agent 已删除或申请不在本组织 → 404。
+     * 批准：在同一事务里新增版本（技能不存在则用预先分配的 id 新建）、`current_version` 指向它，草稿对象原样成为版本文件；
+     * 拒绝：提交后删除草稿对象。审计 `skill.change_decided`。
+     */
+    decide(orgId: string, id: string, accountId: string, body: {
+        decision: "approve" | "reject";
+        note?: string | undefined;
+    }, actorTokenId?: string): Promise<SkillChangeView>;
+    /**
+     * 软删除 agent 自己的一个技能（只有该 agent 当前的负责人；其他人 403 `forbidden`）：技能不存在 / 已删除 / 不属于该
+     * agent → `skill.not_found`。同名的待处理改动一并取消（发起对话追加回退快照，提交后删草稿）。审计 `skill.deleted`。
+     * 各对话下一次运行开始时目录里去掉它；之后同名可再写为新技能。
+     */
+    deleteAgentSkill(orgId: string, agentId: string, skillId: string, accountId: string, actorTokenId?: string): Promise<void>;
+    /** 当前用户（作为 agent 负责人）能决定的待处理申请，新的在前，最多 {@link SKILL_CHANGES_LIST_MAX} 条。 */
+    listPending(orgId: string, accountId: string): Promise<SkillChangeView[]>;
+    /**
+     * 详情（含文件文本）：只有该 agent 的负责人与发起人能看，其他人一律 404（不泄露存在）。
+     * 草稿对象已删除（拒绝 / 取消）时文件内容为 null。
+     */
+    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;
+    /**
+     * 草稿不再生效（拒绝 / 取消）时，在事务 `t` 里给发起对话追加一份回退快照：由该对话最新一份快照推出——
+     * 来源是这份草稿的条目换成这个 agent 技能当前的正式版本（`t` 里已是决定之后的状态），没有正式版本就移除。
+     * 快照里已没有这份草稿 → 不写。对话正在运行时，提醒落在当前位置（构建时排在工具结果之后），下一步即生效。
+     * 移除时不推测同名的组织技能（快照里已被替换掉），下一次运行开始的解析会把它补回来。
+     */
+    private revertTrial;
+    /**
+     * 在事务 `t` 里取消该 agent 全部待处理的技能改动（agent 被删除时由 `AgentsService.softDelete` 调用）：
+     * 置 cancelled、审计、给各发起对话追加回退快照。提交后调用 {@link finishCancel} 删除草稿并发布事件。
+     */
+    cancelPendingForAgent(t: Trx, orgId: string, agentId: string, actorAccountId: string, reason: string, actorTokenId?: string): Promise<CancelledDrafts>;
+    /** {@link cancelPendingForAgent} 提交之后：发布事件、尽力删除草稿对象。 */
+    finishCancel(orgId: string, c: CancelledDrafts): Promise<void>;
+    /** 新技能的数量上限（含待批准的新技能；`excluding` 是将被取代的申请）。 */
+    private assertBelowCap;
+    /** 写一个版本并让 `current_version` 指向它（技能不存在则新建）。 */
+    private createVersion;
+    /** 尽力删除草稿对象（失败只记日志：孤儿对象随组织数据清理删除）。 */
+    private deletePrefix;
+    /** 补齐 agent 名。 */
+    private views;
+}
+export {};