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

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import type { InvocableSkill, SkillInvoker } from "./invoke.js";
+import { type InvocableSkill, SkillInvoker } from "./invoke.js";
 declare const ListQuery: z.ZodObject<{
     conversationId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;

package/dist/skills/invocable.controller.js

@@ -7,13 +7,16 @@ 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, Get, Header, Inject, Param, Query } from "@nestjs/common";
+import { Controller, Get, Header, Inject, Param } from "@nestjs/common";
 import { z } from "zod";
-import { SKILL_INVOKER } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { SkillInvoker } from "./invoke.js";
 const ListQuery = z.object({ conversationId: z.string().min(1).max(100).optional() }).strict();
+class InvocableSkillsQuery extends createZodDto(ListQuery, "InvocableSkillsQuery") {
+}
 /**
  * The composer's `/` menu (phase D spec §4.5): `GET /api/v1/orgs/:orgId/agents/:agentId/
  * invocable-skills?conversationId=` lists the agent's effective skills a person can invoke, sorted
@@ -41,10 +44,10 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("agentId")),
-    __param(3, Query(new ZodPipe(ListQuery)))
+    __param(3, ZQuery(InvocableSkillsQuery))
 ], InvocableSkillsController.prototype, "list", null);
 InvocableSkillsController = __decorate([
     Controller("api/v1/orgs/:orgId/agents/:agentId/invocable-skills"),
-    __param(0, Inject(SKILL_INVOKER))
+    __param(0, Inject(SkillInvoker))
 ], InvocableSkillsController);
 export { InvocableSkillsController };

package/dist/skills/invoke.d.ts

@@ -1,10 +1,11 @@
-import { type Logger } from "@capybara-hq/plugin-sdk";
-import type { AgentsService } from "../agents/agents.service.js";
+import { AgentLookup } from "../agents/agent-lookup.js";
 import type { AgentDefinition } from "../agents/definition.js";
 import type { EventPayload } from "../conversations/events.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { StorageService } from "../storage/storage.service.js";
 /**
  * A person's skill invocation (phase D spec §3, §4): the `/` menu's list of the agent's invocable
  * skills, and the rendering of `/name args` into the model-visible text of their message. The skill
@@ -57,7 +58,7 @@ export declare const notInvocable: (reason: NotInvocableReason, name: string) =>
  * agent's effective skills now, with `user` not false. Its version may have changed: the queued
  * text stays as rendered when queued. Null when it is, else the reason.
  */
-export declare function recordedSkillBlocked(db: KernelDb, a: {
+export declare function recordedSkillBlocked(db: KernelSchemaDb, a: {
     orgId: string;
     agentId: string;
     agent: Pick<AgentDefinition, "skills">;
@@ -68,17 +69,17 @@ export declare function recordedSkillBlocked(db: KernelDb, a: {
 export declare const forkLeadText: (name: string, agentType: string, args: string) => string;
 /** The warning recorded when a forked skill's `agent` does not resolve (spec §6.2). */
 export declare const forkAgentUnknownText: (name: string, agent: string) => string;
-export interface SkillInvokerDeps {
-    db: KernelDb;
-    storage: StorageService;
-    /** For {@link SkillInvoker.listFor} (the HTTP route's access check). */
-    agents?: Pick<AgentsService, "get">;
-    /** An unreadable SKILL.md is logged at `error` (skill id, version, source), as pinned skills. */
-    log?: Pick<Logger, "error">;
-}
+/**
+ * Skill invocations by a person (one provider: the HTTP routes, IM channels and fork dispatch all
+ * use it). Unreadable SKILL.md files are logged at `error` (skill id, version, source), as pinned
+ * skills; the agent access check of {@link SkillInvoker.listFor} is `AgentLookup.get`.
+ */
 export declare class SkillInvoker {
-    private readonly d;
-    constructor(d: SkillInvokerDeps);
+    private readonly db;
+    private readonly storage;
+    private readonly agents;
+    private readonly log;
+    constructor(db: KernelDb, storage: StorageService, agents: Pick<AgentLookup, "get">, log: KernelLogger);
     /**
      * The `/` menu for `accountId`: the agent must be usable by them (`agent.not_found`), and with
      * `conversationId` the conversation must be theirs and the agent's (`conversation.not_found`);

package/dist/skills/invoke.js

@@ -1,6 +1,20 @@
+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 { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { AgentLookup } from "../agents/agent-lookup.js";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { isGeneralAlias, resolveSkillForkType } from "../runtime/subagents/roster.js";
+import { StorageService } from "../storage/storage.service.js";
 import { findSkillVersion, readSkillFile, SkillIntegrityError, } from "../tools/builtins/skill-load.js";
 import { invocationOf, resolveSkills } from "./catalog.js";
 /** A leading `/<name>` or `/<plugin>:<name>`, then whitespace or the end (spec §3.2). */
@@ -43,10 +57,21 @@ export async function recordedSkillBlocked(db, a) {
 export const forkLeadText = (name, agentType, args) => escapeSkillInvocationTags(`The user ran the skill "${name}" in a sub-agent (${agentType}) with /${name}${args === "" ? "" : ` ${args}`}. The sub-agent gets the skill's instructions as its task; its report follows. Do not do the task yourself.`);
 /** The warning recorded when a forked skill's `agent` does not resolve (spec §6.2). */
 export const forkAgentUnknownText = (name, agent) => `Skill "${name}" asked for sub-agent type "${agent}", which this agent does not have; it ran as general-purpose.`;
-export class SkillInvoker {
-    d;
-    constructor(d) {
-        this.d = d;
+/**
+ * Skill invocations by a person (one provider: the HTTP routes, IM channels and fork dispatch all
+ * use it). Unreadable SKILL.md files are logged at `error` (skill id, version, source), as pinned
+ * skills; the agent access check of {@link SkillInvoker.listFor} is `AgentLookup.get`.
+ */
+let SkillInvoker = class SkillInvoker {
+    db;
+    storage;
+    agents;
+    log;
+    constructor(db, storage, agents, log) {
+        this.db = db;
+        this.storage = storage;
+        this.agents = agents;
+        this.log = log;
     }
     /**
      * The `/` menu for `accountId`: the agent must be usable by them (`agent.not_found`), and with
@@ -54,11 +79,9 @@ export class SkillInvoker {
      * then its trial drafts apply.
      */
     async listFor(orgId, agentId, accountId, conversationId) {
-        if (!this.d.agents)
-            throw new Error("SkillInvoker.listFor needs agents");
-        const agent = await this.d.agents.get(orgId, agentId, accountId);
+        const agent = await this.agents.get(orgId, agentId, accountId);
         if (conversationId !== undefined) {
-            const row = await this.d.db
+            const row = await this.db
                 .selectFrom("conversations")
                 .select("id")
                 .where("id", "=", conversationId)
@@ -82,7 +105,7 @@ export class SkillInvoker {
      * point order), model-invocable and manual-only alike (spec §3.1).
      */
     async list(a) {
-        const all = await resolveSkills(this.d.db, a);
+        const all = await resolveSkills(this.db.db, a);
         const out = [];
         for (const r of all) {
             const inv = invocationOf(r.manifest);
@@ -109,7 +132,7 @@ export class SkillInvoker {
      * that fails its integrity check → `storage.unavailable` (503). Nothing is written here.
      */
     async prepare(a) {
-        const all = await resolveSkills(this.d.db, a);
+        const all = await resolveSkills(this.db.db, a);
         const found = findSkill(all, a.name);
         if (!found)
             throw notInvocable("not_found", a.name);
@@ -149,7 +172,7 @@ export class SkillInvoker {
         if (!inv.fork)
             return { text: rendered(() => renderSkillInvocation(input)), skill: record };
         const task = rendered(() => renderSkillInvocation({ ...input, lead: false }));
-        const type = await resolveSkillForkType(this.d.db, a.orgId, a.agent, inv.fork.agent, found.skill.plugin);
+        const type = await resolveSkillForkType(this.db.db, a.orgId, a.agent, inv.fork.agent, found.skill.plugin);
         return {
             text: forkLeadText(a.name, type.agentType, args),
             skill: { ...record, agentType: type.agentType },
@@ -173,9 +196,9 @@ export class SkillInvoker {
      */
     async renderTask(a) {
         const { skill } = a;
-        const found = await findSkillVersion(this.d.db, a, { id: skill.id, source: skill.source });
+        const found = await findSkillVersion(this.db.db, a, { id: skill.id, source: skill.source });
         if (!found) {
-            this.d.log?.error("invoked skill unreadable", {
+            this.log.error("invoked skill unreadable", {
                 orgId: a.orgId,
                 skillId: skill.id,
                 version: skill.version,
@@ -213,7 +236,7 @@ export class SkillInvoker {
     /** Reads and parses the version's SKILL.md (checked against the manifest), returns the body. */
     async readBody(orgId, r) {
         const unreadable = (problem) => {
-            this.d.log?.error("invoked skill unreadable", {
+            this.log.error("invoked skill unreadable", {
                 orgId,
                 skillId: r.skill.id,
                 version: r.skill.version,
@@ -227,10 +250,10 @@ export class SkillInvoker {
         const md = r.manifest.files.find((f) => f.path === SKILL_ENTRY_FILE);
         if (!md)
             throw unreadable(`has no ${SKILL_ENTRY_FILE}`);
-        this.d.storage.assertAvailable();
+        this.storage.assertAvailable();
         let bytes;
         try {
-            bytes = await readSkillFile(this.d.storage.kernel(orgId), `${r.skill.source}${SKILL_ENTRY_FILE}`, md);
+            bytes = await readSkillFile(this.storage.kernel(orgId), `${r.skill.source}${SKILL_ENTRY_FILE}`, md);
         }
         catch (e) {
             if (e instanceof SkillIntegrityError)
@@ -251,7 +274,15 @@ export class SkillInvoker {
             throw unreadable("cannot be parsed");
         return parsed.body;
     }
-}
+};
+SkillInvoker = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(AgentLookup)),
+    __param(3, Inject(KERNEL_LOGGER))
+], SkillInvoker);
+export { SkillInvoker };
 const hasBuiltin = (agent, name) => (agent.tools ?? []).some((t) => t.kind === "builtin" && t.name === name);
 /** The skill's own body over the rendered limit: a 400 on `skill` naming the skill. */
 function tooLarge(name, render) {

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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { type CreatedAttachment } from "../conversations/attachments.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import type { SkillDetail, SkillSummary, SkillsService, UploadedSkill } from "./skills.service.js";
+import { type SkillDetail, type SkillSummary, SkillsService, type UploadedSkill } from "./skills.service.js";
 declare const UploadBody: z.ZodObject<{
     name: z.ZodString;
     size: z.ZodNumber;

package/dist/skills/skills.controller.js

@@ -8,13 +8,14 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
 import { z } from "zod";
 import { SKILL_PACKAGE_UPLOAD_MAX_BYTES, } from "../conversations/attachments.service.js";
-import { SKILLS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { SkillsService, } from "./skills.service.js";
 const UploadBody = z
     .object({
     name: z
@@ -26,6 +27,10 @@ const UploadBody = z
 })
     .strict();
 const CreateBody = z.object({ uploadId: z.string().min(1).max(100) }).strict();
+class SkillUploadBody extends createZodDto(UploadBody, "SkillUploadBody") {
+}
+class SkillCreateBody extends createZodDto(CreateBody, "SkillCreateBody") {
+}
 /**
  * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
  * - read: `skills.read` (member and up) — `GET /` list, `GET /:id` detail (versions and file
@@ -73,14 +78,14 @@ __decorate([
     OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(UploadBody)))
+    __param(2, ZBody(SkillUploadBody))
 ], SkillsController.prototype, "createUpload", null);
 __decorate([
     Post(),
     OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(CreateBody)))
+    __param(2, ZBody(SkillCreateBody))
 ], SkillsController.prototype, "create", null);
 __decorate([
     Get(),
@@ -105,6 +110,6 @@ __decorate([
 ], SkillsController.prototype, "remove", null);
 SkillsController = __decorate([
     Controller("api/v1/orgs/:orgId/skills"),
-    __param(0, Inject(SKILLS))
+    __param(0, Inject(SkillsService))
 ], SkillsController);
 export { SkillsController };

package/dist/skills/skills.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Skills: the org library, agent-written skills and their approvals, the run start's skills
+ * catalog snapshot and the one {@link SkillInvoker}.
+ */
+export declare class SkillsModule {
+}

package/dist/skills/skills.module.js

@@ -0,0 +1,30 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { AgentLookupModule } from "../agents/agent-lookup.js";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
+import { EventLogModule } from "../conversations/event-log.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { StorageModule } from "../storage/storage.module.js";
+import { SkillsCatalogService } from "./catalog.js";
+import { SkillChangesService } from "./changes.service.js";
+import { SkillInvoker } from "./invoke.js";
+import { SkillsService } from "./skills.service.js";
+/**
+ * Skills: the org library, agent-written skills and their approvals, the run start's skills
+ * catalog snapshot and the one {@link SkillInvoker}.
+ */
+let SkillsModule = class SkillsModule {
+};
+SkillsModule = __decorate([
+    Module({
+        imports: [StorageModule, OrgLockModule, EventLogModule, AttachmentsModule, AgentLookupModule],
+        providers: [SkillsService, SkillChangesService, SkillsCatalogService, SkillInvoker],
+        exports: [SkillsService, SkillChangesService, SkillsCatalogService, SkillInvoker],
+    })
+], SkillsModule);
+export { SkillsModule };

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

@@ -1,12 +1,13 @@
 import { type SkillInvocation } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
 import type { AgentDefinition } from "../agents/definition.js";
-import { type AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
-import type { KernelDatabase, KernelDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+import { AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
+import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { StorageService } from "../storage/storage.service.js";
 import { type SkillPackageFile } from "./package.js";
-type Trx = Transaction<KernelDatabase>;
 /** Where an org skill came from (spec §9.2): the org's own, or a catalog plugin at a version. */
 export type SkillSource = {
     kind: "org";
@@ -26,7 +27,7 @@ export interface SkillConflict {
  * agent) and the skills of other catalog items. A skill of the same item (a reinstall or upgrade)
  * is not a conflict. In the order of `skillNames`.
  */
-export declare function skillConflicts(db: KernelDb | Trx, orgId: string, itemId: string, skillNames: readonly string[]): Promise<SkillConflict[]>;
+export declare function skillConflicts(db: KernelSchemaDb, orgId: string, itemId: string, skillNames: readonly string[]): Promise<SkillConflict[]>;
 /** One line of the conflict message (spec §9.2). */
 export declare function skillConflictLine(c: SkillConflict): string;
 /** 409 `plugin.skill_conflict`: one message line and one detail per conflicting skill. */
@@ -82,17 +83,12 @@ export interface UploadedSkill {
     version: number;
     created: boolean;
 }
-export interface SkillsDeps {
-    db: KernelDb;
-    storage: StorageService;
-    attachments: Pick<AttachmentsService, "create" | "readSkillPackage" | "consumeSkillPackage">;
-}
 /**
  * 在调用方事务里核对 agent 定义引用的组织技能：每个 id 都必须是该组织未删除的 `scope=org` 技能，
  * 否则 `validation_failed`（path `skills.orgSkills.<i>`）；不可重复。调用方须已锁组织行（技能删除同样锁组织行，二者串行）。
  * `kept`：当前版本里已有的引用（保存时合法），修改时不再核对——技能之后被删也不挡住其他改动（运行时由 T14 忽略已删除的技能）。
  */
-export declare function assertOrgSkills(t: Trx, orgId: string, ids: readonly string[], kept?: ReadonlySet<string>): Promise<void>;
+export declare function assertOrgSkills(db: KernelSchemaDb, orgId: string, ids: readonly string[], kept?: ReadonlySet<string>): Promise<void>;
 /** Why a pinned skill reference is refused (`agent.pinned_invalid` details). */
 export type PinnedSkillProblem = "not_selected" | "not_found" | "duplicate" | "too_many" | "too_large"
 /** Phase D: the skill's current version is manual-only (not in the model's catalog). */
@@ -113,14 +109,26 @@ export type PinnedSkillProblem = "not_selected" | "not_found" | "duplicate" | "t
  *   when the pinned list changed: a pinned skill's new version never blocks an unrelated edit (the
  *   run keeps what fits).
  */
-export declare function assertPinnedSkills(t: Trx, orgId: string, agentId: string | null, skills: AgentDefinition["skills"], kept?: readonly string[]): Promise<void>;
+export declare function assertPinnedSkills(db: KernelSchemaDb, orgId: string, agentId: string | null, skills: AgentDefinition["skills"], kept?: readonly string[]): Promise<void>;
 /**
  * 技能库（M5 T13）：组织技能的上传（新技能或新版本）、列表、详情与软删除。
  * 字节在对象存储 `kernel/<orgId>/skills/<uploadId>/<path>`，元数据在 PG；无进程内状态，可多副本共用。
  */
+/** A validated skill package: its name, description, files and invocation. */
+interface SkillPackageInput {
+    name: string;
+    description: string;
+    files: SkillPackageFile[];
+    /** Phase D: stored in the manifest when it is not the default. */
+    invocation?: SkillInvocation;
+}
 export declare class SkillsService {
-    private readonly d;
-    constructor(d: SkillsDeps);
+    private readonly db;
+    private readonly storage;
+    private readonly attachments;
+    readonly txHost: TransactionHost;
+    private readonly orgLock;
+    constructor(db: KernelDb, storage: StorageService, attachments: AttachmentsService, txHost: TransactionHost, orgLock: OrgLock);
     /** 登记一个技能包上传（预签名 POST，`application/zip`，≤ 50MB）；角色由路由的 `skills.manage` 把关。 */
     createUpload(orgId: string, accountId: string, input: {
         name: string;
@@ -136,24 +144,24 @@ export declare class SkillsService {
      * 同一上传已经产生过版本（上次提交了、响应丢了而重试）→ 直接返回那个版本（同组织、同一发起人）。
      */
     upload(orgId: string, actorAccountId: string, uploadId: string, actorTokenId?: string): Promise<UploadedSkill>;
+    /**
+     * The transaction of {@link upload}: under the org row lock (re-checking `skills.manage`), the
+     * custom-skill policy is re-checked and the upload consumed (of concurrent requests for the same
+     * upload only one succeeds), then the version is written in the same transaction
+     * ({@link createVersionIn} joins it).
+     */
+    private createUploadedVersionIn;
     /**
      * 用一组已校验的技能文件创建组织技能或给同名技能新增版本（上传与企业目录安装共用）：
      * 1. 把文件写到 `kernel/<orgId>/<prefix>`（缺省 `skills/<新 id>/`）；
-     * 2. 一个事务里：锁组织行并复核 `skills.manage`，执行 `inTransaction`（上传：标记上传已用；目录：按条目策略复核），
+     * 2. 一个事务里：锁组织行并复核 `skills.manage`（目录安装：按条目策略复核），
      *    同名未删除的组织技能存在则 `current_version + 1`，否则新建；技能与版本都记下 `directory` 来源（没有则清空：
      *    自定义上传盖在目录技能上就不再算目录安装），写版本与审计
      *    （`skill.created` / `skill.version_created`，目录安装时 detail 带 directory）。
      */
-    createVersionFromFiles(orgId: string, actorAccountId: string, pkg: {
-        name: string;
-        description: string;
-        files: SkillPackageFile[];
-        /** Phase D: stored in the manifest when it is not the default. */
-        invocation?: SkillInvocation;
-    }, opts?: {
+    createVersionFromFiles(orgId: string, actorAccountId: string, pkg: SkillPackageInput, opts?: {
         prefix?: string;
         actorTokenId?: string;
-        inTransaction?: (t: Trx) => Promise<void>;
         /** Catalog provenance; `approvedBy` is the item whose policy approves it (default `itemId`). */
         catalog?: {
             itemId: string;
@@ -165,16 +173,23 @@ export declare class SkillsService {
             suggestPinned?: boolean;
         };
     }): Promise<UploadedSkill>;
+    /** Writes a skill package's files to `kernel/<orgId>/<prefix>` (a few at a time). */
+    private putFiles;
+    /** The transaction of {@link createVersionFromFiles}. */
+    private createVersionIn;
     /**
-     * 在调用方事务里撤销应用安装给已有技能加的版本（调用方已锁组织行）：只有当前版本仍是 `version` 时才退回上一版本并删掉
-     * 该版本行（之后又有新版本则不动，返回 false），技能的描述与目录来源也退回上一版本的。审计 `skill.version_reverted`。
+     * In the caller's transaction (`mandatory`: the caller holds the org row lock), reverts the
+     * version a plugin install added to an existing skill: only while `version` is still current,
+     * back to the previous version, deleting this version's row (returns false when a newer version
+     * exists); the skill's description and catalog source revert too. Audit `skill.version_reverted`.
      */
-    revertVersionIn(t: Trx, orgId: string, skillId: string, version: number, actorAccountId: string, reason: string): Promise<boolean>;
+    revertVersionIn(orgId: string, skillId: string, version: number, actorAccountId: string, reason: string): Promise<boolean>;
     /**
-     * 在调用方事务里软删除组织技能（调用方已锁组织行；应用安装的回滚与卸载用）。审计 `skill.deleted`（带 reason）。
-     * 已删除 / 不存在时返回 false。
+     * In the caller's transaction (`mandatory`: the caller holds the org row lock), soft-deletes an
+     * org skill (plugin install rollback and uninstall). Audit `skill.deleted` with the reason.
+     * Returns false when it is already deleted or missing.
      */
-    softDeleteIn(t: Trx, orgId: string, skillId: string, actorAccountId: string, reason: string): Promise<boolean>;
+    softDeleteIn(orgId: string, skillId: string, actorAccountId: string, reason: string): Promise<boolean>;
     /** 组织技能库（`scope=org`、未删除），按名字排序。 */
     list(orgId: string): Promise<SkillSummary[]>;
     /** 对该 agent 自动生效的技能（`scope=agent`、未删除），按名字排序。 */
@@ -188,5 +203,7 @@ export declare class SkillsService {
      * 保存时会被拒绝（运行时由 T14 忽略已删除的技能）。不存在 / 已删除 → `skill.not_found`。
      */
     softDelete(orgId: string, skillId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /** The transaction of {@link softDelete}. */
+    private softDeleteTx;
 }
 export {};