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

package/dist/skills/catalog.d.ts

@@ -1,15 +1,17 @@
 import { type Logger, type SkillInvocation } from "@capybara-hq/plugin-sdk";
-import { type Transaction } from "kysely";
 import type { AgentDefinition } from "../agents/definition.js";
-import type { EventLog } from "../conversations/event-log.js";
+import { EventLog } from "../conversations/event-log.js";
 import { type ConversationEvent } from "../conversations/events.js";
-import type { KernelDatabase, KernelDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
+import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
 import { type CatalogSkill, type PinnedSkill, type SkillsSnapshot } from "../runtime/context/skills.js";
-import type { StorageService } from "../storage/storage.service.js";
+import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
 /**
  * 技能目录快照（M5 T14，Ruling M17）：运行开始时解析「此刻对这个对话生效的技能」，与日志里最新一份快照不同才写
- * `skills_catalog`。模型看到的目录与 `skill_load` 的名字解析只来自日志，不读实时的库。
+ * `skills_catalog`。模型看到的目录与 `Skill` 的名字解析只来自日志，不读实时的库。
  */
 /**
  * Pinned skill limits (spec §9.1): at most `count` pinned skills per agent, whose current SKILL.md
@@ -44,7 +46,7 @@ export interface EffectiveSkillsInput {
  * （id 为已有技能或预先分配的 id，版本为批准后预期的版本号）；其他对话照旧用 `current_version`。
  * 批准后版本成为当前版本，各对话下一次运行开始时由快照差异得到提醒；拒绝 / 取消后发起对话回到当前版本。
  */
-export declare function resolveEffectiveSkills(db: KernelDb, input: EffectiveSkillsInput, log?: Pick<Logger, "warn">): Promise<CatalogSkill[]>;
+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. */
 export declare function invocationOf(manifest: Pick<SkillManifest, "invocation">): SkillInvocation;
 /** An effective skill with what the snapshot needs beyond its catalog entry. */
@@ -60,7 +62,7 @@ export interface ResolvedSkill {
  * included and not truncated ({@link forModel} gives the model's part). Without
  * `conversationId` (a conversation not created yet) no trial draft applies.
  */
-export declare function resolveSkills(db: KernelDb, input: Omit<EffectiveSkillsInput, "conversationId"> & {
+export declare function resolveSkills(db: KernelSchemaDb, input: Omit<EffectiveSkillsInput, "conversationId"> & {
     conversationId?: string;
 }): Promise<ResolvedSkill[]>;
 /** A pinned skill to read: an effective skill the agent version pins. */
@@ -73,7 +75,7 @@ interface PinnedCandidate {
 }
 /**
  * The `run_failed` message (shown to the user, English like the other run texts) for a
- * `storage.unavailable` from {@link recordSkillsCatalog}: a pinned SKILL.md that is missing,
+ * `storage.unavailable` from {@link SkillsCatalogService.record}: a pinned SKILL.md that is missing,
  * corrupt or unparsable points at the agent's owner, since sending again cannot help; anything
  * else is a transient storage failure.
  */
@@ -89,7 +91,7 @@ export declare function pinnedFailureText(e: ApiError): string;
  *   carries `details: [{ reason: "pinned_unreadable", skillId, name, source }]`
  *   ({@link pinnedFailureText} turns it into an owner-facing message).
  */
-export declare function loadPinnedBodies(storage: StorageService, orgId: string, pinned: readonly PinnedCandidate[], opts?: {
+export declare function loadPinnedBodies(storage: PrefixedStorage, orgId: string, pinned: readonly PinnedCandidate[], opts?: {
     signal?: AbortSignal;
     log?: Pick<Logger, "error">;
 }): Promise<PinnedSkill[]>;
@@ -101,9 +103,9 @@ export declare function loadPinnedBodies(storage: StorageService, orgId: string,
 export declare function fitPinned(pinned: readonly PinnedSkill[], log: Pick<Logger, "warn"> | undefined, input: Partial<Pick<EffectiveSkillsInput, "orgId" | "agentId" | "conversationId">>): PinnedSkill[];
 /** `skills_catalog` 的幂等键：每次运行最多写一份。 */
 /**
- * 是否给模型 `skill_load`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
+ * 是否给模型 `Skill`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
  * 用同一判定。不因空快照收回这个工具：工具集合一变缓存前缀就失效；而且 agent 没有别的工具时会发出「没有工具
- * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 skill_load 由 `NO_SKILLS_TEXT` 给出可执行的说明。
+ * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 Skill 由 `NO_SKILLS_TEXT` 给出可执行的说明。
  */
 export declare function skillLoadOffered(latest: Extract<ConversationEvent, {
     type: "skills_catalog";
@@ -117,13 +119,14 @@ invoked?: boolean): boolean;
 /** Whether `events` hold a person's skill invocation (a `user_message` with `skill`). */
 export declare const hasInvocation: (events: readonly ConversationEvent[]) => boolean;
 /** {@link skillLoadOffered} for a conversation, read from the database. */
-export declare function skillLoadOfferedIn(db: KernelDb, eventLog: Pick<EventLog, "latestOfType">, conversationId: string): Promise<boolean>;
+export declare function skillLoadOfferedIn(db: KernelSchemaDb, eventLog: Pick<EventLog, "latestOfType">, conversationId: string): Promise<boolean>;
 export declare const skillsCatalogIdemKey: (runId: string) => string;
 /**
- * 在事务 `t` 里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
- * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、skill_write、拒绝时的回退）插不进来。
+ * 在调用方事务里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
+ * `db` is the caller's transaction handle (`KernelDb.db` inside `@Transactional`).
+ * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、SkillWrite、拒绝时的回退）插不进来。
  */
-export declare function lockLatestCatalog(t: Transaction<KernelDatabase>, conversationId: string): Promise<SkillsSnapshot | undefined>;
+export declare function lockLatestCatalog(db: KernelSchemaDb, conversationId: string): Promise<SkillsSnapshot | undefined>;
 /**
  * 运行开始时记录技能目录快照：解析生效的技能，与日志里最新一份不同才写（带幂等键，崩溃重试不重复）。
  * 从没有快照、现在也没有技能 → 不写（没有技能的 agent 不出现目录）；之前有、现在全没了 → 写空快照（模型据此得知被移除）。
@@ -137,13 +140,23 @@ export declare function lockLatestCatalog(t: Transaction<KernelDatabase>, conver
  * whole thing starts over (at most {@link RECORD_ATTEMPTS} times, then `conflict`). A read failure
  * throws `storage.unavailable` before anything is written. Writes only when `!sameSnapshot`.
  */
-export declare function recordSkillsCatalog(deps: {
-    db: KernelDb;
-    eventLog: Pick<EventLog, "append" | "notify">;
-    log?: Pick<Logger, "warn" | "error">;
-    /** Reads pinned bodies; without it an agent with pinned skills fails `storage.unavailable`. */
-    storage?: StorageService;
-}, input: EffectiveSkillsInput & {
-    runId: string;
-}): Promise<void>;
+export declare class SkillsCatalogService {
+    private readonly db;
+    private readonly storage;
+    private readonly eventLog;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, storage: StorageService, eventLog: EventLog, log: KernelLogger, txHost: TransactionHost);
+    /**
+     * Records the run start's snapshot (see the class comment). `opts.log`: the run's logger
+     * (default the kernel logger).
+     */
+    record(input: EffectiveSkillsInput & {
+        runId: string;
+    }, opts?: {
+        log?: Pick<Logger, "warn" | "error">;
+    }): Promise<void>;
+    /** Step (2) of {@link record}: under the conversation row lock, resolve again and append. */
+    private append;
+}
 export {};

package/dist/skills/catalog.js

@@ -1,13 +1,29 @@
+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 { createHash } from "node:crypto";
 import { parseSkillMd, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { EventLog } from "../conversations/event-log.js";
 import { SKILLS_CATALOG_MAX } from "../conversations/events.js";
 import { ApiError } from "../errors.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 { CLAUDE_CODE_TOOL_MAP } from "../runtime/context/claude-tools.js";
 import { sameSnapshot, } from "../runtime/context/skills.js";
+import { StorageService } from "../storage/storage.service.js";
 /**
  * 技能目录快照（M5 T14，Ruling M17）：运行开始时解析「此刻对这个对话生效的技能」，与日志里最新一份快照不同才写
- * `skills_catalog`。模型看到的目录与 `skill_load` 的名字解析只来自日志，不读实时的库。
+ * `skills_catalog`。模型看到的目录与 `Skill` 的名字解析只来自日志，不读实时的库。
  */
 /**
  * Pinned skill limits (spec §9.1): at most `count` pinned skills per agent, whose current SKILL.md
@@ -182,7 +198,7 @@ const PINNED_UNREADABLE = "pinned_unreadable";
 const PINNED_READ_ATTEMPTS = 2;
 /**
  * The `run_failed` message (shown to the user, English like the other run texts) for a
- * `storage.unavailable` from {@link recordSkillsCatalog}: a pinned SKILL.md that is missing,
+ * `storage.unavailable` from {@link SkillsCatalogService.record}: a pinned SKILL.md that is missing,
  * corrupt or unparsable points at the agent's owner, since sending again cannot help; anything
  * else is a transient storage failure.
  */
@@ -287,9 +303,9 @@ export function fitPinned(pinned, log, input) {
 }
 /** `skills_catalog` 的幂等键：每次运行最多写一份。 */
 /**
- * 是否给模型 `skill_load`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
+ * 是否给模型 `Skill`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
  * 用同一判定。不因空快照收回这个工具：工具集合一变缓存前缀就失效；而且 agent 没有别的工具时会发出「没有工具
- * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 skill_load 由 `NO_SKILLS_TEXT` 给出可执行的说明。
+ * 但历史里有 tool_use」的请求，Anthropic 会拒绝。空目录下调用 Skill 由 `NO_SKILLS_TEXT` 给出可执行的说明。
  */
 export function skillLoadOffered(latest, 
 /**
@@ -318,17 +334,18 @@ export async function skillLoadOfferedIn(db, eventLog, conversationId) {
 }
 export const skillsCatalogIdemKey = (runId) => `skills_catalog:${runId}`;
 /**
- * 在事务 `t` 里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
- * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、skill_write、拒绝时的回退）插不进来。
+ * 在调用方事务里锁会话行（与 `EventLog.append` 同一把锁）并读最新一份技能目录快照（没有为 undefined）。
+ * `db` is the caller's transaction handle (`KernelDb.db` inside `@Transactional`).
+ * 「读最新 → 推出下一份 → 追加」都在这把锁内，别的写快照的事务（运行开始、SkillWrite、拒绝时的回退）插不进来。
  */
-export async function lockLatestCatalog(t, conversationId) {
-    await t
+export async function lockLatestCatalog(db, conversationId) {
+    await db
         .selectFrom("conversations")
         .select("id")
         .where("id", "=", conversationId)
         .forUpdate()
         .executeTakeFirst();
-    const last = await t
+    const last = await db
         .selectFrom("conversation_events")
         .select("payload")
         .where("conversation_id", "=", conversationId)
@@ -353,53 +370,79 @@ const RECORD_ATTEMPTS = 3;
  * whole thing starts over (at most {@link RECORD_ATTEMPTS} times, then `conflict`). A read failure
  * throws `storage.unavailable` before anything is written. Writes only when `!sameSnapshot`.
  */
-export async function recordSkillsCatalog(deps, input) {
-    for (let attempt = 1; attempt <= RECORD_ATTEMPTS; attempt++) {
-        const all = await resolveSkills(deps.db, input);
-        // Warn about manual-only pins once, on the first attempt
-        const first = pinnedCandidates(forModel(all, input), input.agent, input, all, attempt === 1 ? deps.log : undefined);
-        if (first.length > 0 && !deps.storage) {
-            throw storageUnavailable("No object storage to read pinned skills from");
+let SkillsCatalogService = class SkillsCatalogService {
+    db;
+    storage;
+    eventLog;
+    log;
+    txHost;
+    constructor(db, storage, eventLog, log, txHost) {
+        this.db = db;
+        this.storage = storage;
+        this.eventLog = eventLog;
+        this.log = log;
+        this.txHost = txHost;
+    }
+    /**
+     * Records the run start's snapshot (see the class comment). `opts.log`: the run's logger
+     * (default the kernel logger).
+     */
+    async record(input, opts = {}) {
+        const log = opts.log ?? this.log;
+        for (let attempt = 1; attempt <= RECORD_ATTEMPTS; attempt++) {
+            const all = await resolveSkills(this.db.db, input);
+            // Warn about manual-only pins once, on the first attempt
+            const first = pinnedCandidates(forModel(all, input), input.agent, input, all, attempt === 1 ? log : undefined);
+            const pinned = fitPinned(await loadPinnedBodies(this.storage, input.orgId, first, { log }), log, input);
+            const toSeq = await this.append(input, first, pinned, log);
+            if (toSeq === "retry")
+                continue;
+            if (toSeq !== null)
+                await this.eventLog.notify(input.conversationId, toSeq);
+            return;
         }
-        const pinned = fitPinned(deps.storage
-            ? await loadPinnedBodies(deps.storage, input.orgId, first, {
-                ...(deps.log && { log: deps.log }),
-            })
-            : [], deps.log, input);
-        const toSeq = await deps.db.transaction().execute(async (t) => {
-            const last = await lockLatestCatalog(t, input.conversationId);
-            const all = await resolveSkills(t, input);
-            const resolved = forModel(all, input, deps.log);
-            if (!sameCandidates(first, pinnedCandidates(resolved, input.agent, input, all))) {
-                return "retry";
-            }
-            const skills = resolved.map((r) => r.skill);
-            const next = {
-                skills,
-                ...(pinned.length > 0 && { pinned }),
-                // The model's (truncated) skills as before phase D, plus manual-only ones: a person can
-                // invoke one whose body names Claude tools (batch 1 review M8)
-                ...([...resolved, ...all.filter((r) => !invocationOf(r.manifest).model)].some((r) => r.format === "claude-code") && {
-                    toolMap: CLAUDE_CODE_TOOL_MAP,
-                }),
-            };
-            if (last ? sameSnapshot(last, next) : skills.length === 0)
-                return null;
-            const written = await deps.eventLog.append(input.conversationId, [
-                {
-                    type: "skills_catalog",
-                    runId: input.runId,
-                    idemKey: skillsCatalogIdemKey(input.runId),
-                    payload: next,
-                },
-            ], t);
-            return Math.max(...written.map((e) => e.seq));
-        });
-        if (toSeq === "retry")
-            continue;
-        if (toSeq !== null)
-            await deps.eventLog.notify(input.conversationId, toSeq);
-        return;
+        throw new ApiError("conflict", "The pinned skills kept changing while the run started; send the message again.");
     }
-    throw new ApiError("conflict", "The pinned skills kept changing while the run started; send the message again.");
-}
+    /** Step (2) of {@link record}: under the conversation row lock, resolve again and append. */
+    async append(input, first, pinned, log) {
+        const last = await lockLatestCatalog(this.db.db, input.conversationId);
+        const all = await resolveSkills(this.db.db, input);
+        const resolved = forModel(all, input, log);
+        if (!sameCandidates(first, pinnedCandidates(resolved, input.agent, input, all))) {
+            return "retry";
+        }
+        const skills = resolved.map((r) => r.skill);
+        const next = {
+            skills,
+            ...(pinned.length > 0 && { pinned }),
+            // The model's (truncated) skills as before phase D, plus manual-only ones: a person can
+            // invoke one whose body names Claude tools (batch 1 review M8)
+            ...([...resolved, ...all.filter((r) => !invocationOf(r.manifest).model)].some((r) => r.format === "claude-code") && {
+                toolMap: CLAUDE_CODE_TOOL_MAP,
+            }),
+        };
+        if (last ? sameSnapshot(last, next) : skills.length === 0)
+            return null;
+        const written = await this.eventLog.appendIn(input.conversationId, [
+            {
+                type: "skills_catalog",
+                runId: input.runId,
+                idemKey: skillsCatalogIdemKey(input.runId),
+                payload: next,
+            },
+        ]);
+        return Math.max(...written.map((e) => e.seq));
+    }
+};
+__decorate([
+    Transactional()
+], SkillsCatalogService.prototype, "append", null);
+SkillsCatalogService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(StorageService)),
+    __param(2, Inject(EventLog)),
+    __param(3, Inject(KERNEL_LOGGER)),
+    __param(4, Inject(TransactionHost))
+], SkillsCatalogService);
+export { SkillsCatalogService };

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

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import type { AgentsService } from "../agents/agents.service.js";
+import { AgentsService } from "../agents/agents.service.js";
 import { type Principal } from "../identity/principal.js";
-import type { InboxService, InboxView } from "../inbox/inbox.service.js";
+import { InboxService, type InboxView } from "../inbox/inbox.service.js";
 import { type OrgContext } from "../orgs/org.guard.js";
-import type { SkillChangeDetail, SkillChangesService, SkillChangeView } from "./changes.service.js";
-import type { SkillSummary, SkillsService } from "./skills.service.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";

package/dist/skills/changes.controller.js

@@ -7,18 +7,24 @@ 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 { 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 { AGENTS, INBOX, SKILL_CHANGES, SKILLS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
+import { AgentsService } from "../agents/agents.service.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { InboxService } from "../inbox/inbox.service.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 { SkillChangesService, } from "./changes.service.js";
+import { SkillsService } from "./skills.service.js";
 const DecideBody = z
     .object({
     decision: z.enum(["approve", "reject"]),
     note: z.string().max(1000).optional(),
 })
     .strict();
+class SkillChangeDecideBody extends createZodDto(DecideBody, "SkillChangeDecideBody") {
+}
 /**
  * 共享 agent 的技能变更申请（`/api/v1/orgs/:orgId/skill-changes`，M5 T15，R4）。动作 `approvals.decide`
  * （访客起、仅限用户主体：agent / 服务令牌不能决定，R2）；能否决定由服务按该 agent **当前的负责人**判定，
@@ -54,11 +60,11 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("id")),
-    __param(3, Body(new ZodPipe(DecideBody)))
+    __param(3, ZBody(SkillChangeDecideBody))
 ], SkillChangesController.prototype, "decide", null);
 SkillChangesController = __decorate([
     Controller("api/v1/orgs/:orgId/skill-changes"),
-    __param(0, Inject(SKILL_CHANGES))
+    __param(0, Inject(SkillChangesService))
 ], SkillChangesController);
 export { SkillChangesController };
 /**
@@ -104,9 +110,9 @@ __decorate([
 ], 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))
+    __param(0, Inject(SkillChangesService)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(SkillsService))
 ], AgentSkillsController);
 export { AgentSkillsController };
 /**
@@ -131,6 +137,6 @@ __decorate([
 ], InboxController.prototype, "list", null);
 InboxController = __decorate([
     Controller("api/v1/orgs/:orgId/inbox"),
-    __param(0, Inject(INBOX))
+    __param(0, Inject(InboxService))
 ], InboxController);
 export { InboxController };

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

@@ -1,9 +1,9 @@
-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>;
+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 { StorageService } from "../storage/storage.service.js";
 /**
  * 每个 agent 自己的技能（`scope = agent`）上限，含待批准的新技能。远低于目录快照的上限（`SKILLS_CATALOG_MAX`），
  * 正常使用不会让目录被截断。
@@ -95,17 +95,11 @@ 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 生成一条待负责人批准的申请，
+ * - `write`（工具 `SkillWrite` 调用）：私有 agent 直接生成新版本；共享 agent 生成一条待负责人批准的申请，
  *   期间只有发起对话试用（`resolveEffectiveSkills` 按对话合并）；两种情况都在同一事务里往发起对话追加一份
- *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `skill_load`；
+ *   技能目录快照（Ruling M17：日志是唯一事实源），同一运行的下一步即可 `Skill`；
  * - `decide`（HTTP，只有该 agent 当前的负责人）：批准 → 版本对所有对话生效（各对话下一次运行开始时写新快照）；
  *   拒绝 → 删除草稿对象，发起对话下一次运行开始时目录回到当前版本；
  * - 同一 agent 的同名技能最多一条待处理申请：同一对话再写取代旧的（旧的 cancelled、草稿删除、技能 id 不变），
@@ -113,8 +107,12 @@ export interface SkillChangesDeps {
  * 状态都在 PG（agent 行锁串行化同一 agent 的写与决定），文件在对象存储 `kernel/<orgId>/skills/<id>/`；无进程内状态。
  */
 export declare class SkillChangesService {
-    private readonly d;
-    constructor(d: SkillChangesDeps);
+    private readonly db;
+    private readonly storage;
+    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>;
     /**
@@ -133,6 +131,12 @@ export declare class SkillChangesService {
      * 各对话下一次运行开始时目录里去掉它；之后同名可再写为新技能。
      */
     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[]>;
     /**
@@ -157,19 +161,25 @@ export declare class SkillChangesService {
      */
     private revertTrial;
     /**
-     * 在事务 `t` 里取消该 agent 全部待处理的技能改动（agent 被删除时由 `AgentsService.softDelete` 调用）：
-     * 置 cancelled、审计、给各发起对话追加回退快照。提交后调用 {@link finishCancel} 删除草稿并发布事件。
+     * 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.
      */
-    cancelPendingForAgent(t: Trx, orgId: string, agentId: string, actorAccountId: string, reason: string, actorTokenId?: string): Promise<CancelledDrafts>;
+    cancelPendingForAgent(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;
+    /**
+     * 先给组织行加 KEY SHARE 锁，再锁 agent 行：与 `AgentsService`（组织行 FOR UPDATE → agent 行）同一顺序。
+     * 不先锁的话，本事务持有 agent 行后插入引用组织的行（外键取 KEY SHARE）会与之互相等待（40P01）。
+     */
+    private keyShareOrg;
     /** 尽力删除草稿对象（失败只记日志：孤儿对象随组织数据清理删除）。 */
     private deletePrefix;
     /** 补齐 agent 名。 */
     private views;
 }
-export {};