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

package/dist/sandbox/unreachable.d.ts

@@ -0,0 +1,30 @@
+/**
+ * How a provider call failed to reach the provider: `connect` when no connection was made (the
+ * request never reached the provider, so it did nothing), `dropped` when an open connection broke
+ * (the provider may have acted before it broke).
+ */
+export type ProviderConnectionFailure = "connect" | "dropped";
+/**
+ * Whether `e` is a network-level failure to reach the provider, and which kind. Providers may
+ * wrap the socket error (`fetch failed` with a `cause`, an `AggregateError` of one error per
+ * address, an SDK error with a `cause`), so the cause chain and `errors` are searched. The
+ * provider's own verdicts (`SandboxGoneError`, `FileSystemGoneError`) are never connection
+ * failures.
+ */
+export declare function providerConnectionFailure(e: unknown, depth?: number): ProviderConnectionFailure | undefined;
+/**
+ * A sandbox provider call that could not reach the provider (the socket proxy, the Docker daemon,
+ * the E2B API is down or misaddressed). An ordinary error to the sandbox lifecycle (never "gone":
+ * a network blip must not rebuild the instance); the tools turn it into an actionable tool error.
+ * `cause` is the provider's error, unchanged.
+ */
+export declare class SandboxProviderUnreachableError extends Error {
+    readonly failure: ProviderConnectionFailure;
+    constructor(failure: ProviderConnectionFailure, cause: unknown);
+}
+/**
+ * `impl` with every method's network-level failure rethrown as
+ * {@link SandboxProviderUnreachableError} (other errors and results unchanged): the one place a
+ * provider's connection failure is told apart from the kernel's own (database, Redis) failures.
+ */
+export declare function guardProviderConnection<P extends object>(impl: P): P;

package/dist/sandbox/unreachable.js

@@ -0,0 +1,108 @@
+import { isFileSystemGoneError, isSandboxGoneError } from "@capybara-hq/plugin-sdk";
+/** Codes of a connection that was never made (node `net` / `dns`, undici). */
+const CONNECT_CODES = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "EHOSTDOWN",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+/** Codes of a connection that broke after it was made. */
+const DROPPED_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EPIPE",
+    "ECONNABORTED",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CLOSED",
+]);
+/** System calls that open a connection: any error code they fail with means no connection. */
+const CONNECT_SYSCALLS = new Set(["connect", "getaddrinfo"]);
+const MAX_DEPTH = 5;
+/**
+ * Whether `e` is a network-level failure to reach the provider, and which kind. Providers may
+ * wrap the socket error (`fetch failed` with a `cause`, an `AggregateError` of one error per
+ * address, an SDK error with a `cause`), so the cause chain and `errors` are searched. The
+ * provider's own verdicts (`SandboxGoneError`, `FileSystemGoneError`) are never connection
+ * failures.
+ */
+export function providerConnectionFailure(e, depth = 0) {
+    if (depth > MAX_DEPTH || typeof e !== "object" || e === null)
+        return undefined;
+    if (isSandboxGoneError(e) || isFileSystemGoneError(e))
+        return undefined;
+    const { code, syscall, message, cause, errors } = e;
+    if (typeof code === "string") {
+        if (CONNECT_CODES.has(code))
+            return "connect";
+        if (typeof syscall === "string" && CONNECT_SYSCALLS.has(syscall))
+            return "connect";
+        if (DROPPED_CODES.has(code))
+            return "dropped";
+    }
+    if (typeof message === "string" && /socket hang up/i.test(message))
+        return "dropped";
+    let found;
+    if (Array.isArray(errors)) {
+        for (const inner of errors) {
+            const f = providerConnectionFailure(inner, depth + 1);
+            if (f === "dropped")
+                return f;
+            found ??= f;
+        }
+    }
+    return found ?? providerConnectionFailure(cause, depth + 1);
+}
+/**
+ * A sandbox provider call that could not reach the provider (the socket proxy, the Docker daemon,
+ * the E2B API is down or misaddressed). An ordinary error to the sandbox lifecycle (never "gone":
+ * a network blip must not rebuild the instance); the tools turn it into an actionable tool error.
+ * `cause` is the provider's error, unchanged.
+ */
+export class SandboxProviderUnreachableError extends Error {
+    failure;
+    constructor(failure, cause) {
+        const why = cause instanceof Error ? cause.message : String(cause);
+        super(`sandbox provider ${failure === "connect" ? "unreachable" : "connection dropped"}: ${why}`, { cause });
+        this.failure = failure;
+        this.name = "SandboxProviderUnreachableError";
+    }
+}
+function converted(e) {
+    if (e instanceof SandboxProviderUnreachableError)
+        return e;
+    const failure = providerConnectionFailure(e);
+    return failure === undefined ? e : new SandboxProviderUnreachableError(failure, e);
+}
+/**
+ * `impl` with every method's network-level failure rethrown as
+ * {@link SandboxProviderUnreachableError} (other errors and results unchanged): the one place a
+ * provider's connection failure is told apart from the kernel's own (database, Redis) failures.
+ */
+export function guardProviderConnection(impl) {
+    return new Proxy(impl, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop, target);
+            if (typeof value !== "function")
+                return value;
+            return (...args) => {
+                let r;
+                try {
+                    r = value.apply(target, args);
+                }
+                catch (e) {
+                    throw converted(e);
+                }
+                if (r instanceof Promise) {
+                    return r.catch((e) => {
+                        throw converted(e);
+                    });
+                }
+                return r;
+            };
+        },
+    });
+}

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,9 +62,9 @@ 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[]>;
+}, log?: Pick<Logger, "warn">): Promise<ResolvedSkill[]>;
 /** A pinned skill to read: an effective skill the agent version pins. */
 interface PinnedCandidate {
     id: string;
@@ -73,13 +75,14 @@ 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.
  */
 export declare function pinnedFailureText(e: ApiError): string;
 /**
- * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md`, verifies it against
+ * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md` (a platform version's
+ * `platform:<prefix>` from `deployment/<prefix>SKILL.md`), verifies it against
  * the manifest's size and sha256 and returns the parsed body, in order. Every failure throws
  * `storage.unavailable` (Decision 9: the run fails before any model request):
  * - a read error is retried once ({@link PINNED_READ_ATTEMPTS}), then is transient (the user
@@ -89,7 +92,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 +104,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 +120,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 +141,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,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;
+};
+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";
+import { selectedSkills, skillFileStore } from "./usable.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
@@ -57,43 +74,18 @@ function forModel(all, input, log) {
  * included and not truncated ({@link forModel} gives the model's part). Without
  * `conversationId` (a conversation not created yet) no trial draft applies.
  */
-export async function resolveSkills(db, input) {
-    const orgSkills = [...new Set(input.agent.skills?.orgSkills ?? [])];
-    const rows = await db
-        .selectFrom("skills")
-        .innerJoin("skill_versions", (j) => j
-        .onRef("skill_versions.skill_id", "=", "skills.id")
-        .onRef("skill_versions.version", "=", "skills.current_version"))
-        .leftJoin("catalog_items", "catalog_items.id", "skills.catalog_item_id")
-        .select([
-        "skills.id",
-        "skills.scope",
-        "skills.name",
-        "skills.current_version",
-        "skill_versions.manifest",
-        "skill_versions.object_prefix",
-        "skill_versions.source_format",
-        "catalog_items.name as item_name",
-    ])
-        .where("skills.org_id", "=", input.orgId)
-        .where("skills.deleted_at", "is", null)
-        .where((eb) => {
-        const agentOwn = eb.and([
-            eb("skills.scope", "=", "agent"),
-            eb("skills.agent_id", "=", input.agentId),
-        ]);
-        if (orgSkills.length === 0)
-            return agentOwn;
-        return eb.or([
-            agentOwn,
-            eb.and([eb("skills.scope", "=", "org"), eb("skills.id", "in", orgSkills)]),
-        ]);
-    })
-        .execute();
+export async function resolveSkills(db, input, log) {
+    // Phase 2 (Task 3): `orgSkills` ids may be org skills, org copies linked to a platform skill
+    // (served as its current version under the copy's id, ruling B2) or platform skill ids; only
+    // those usable in the org resolve (skills/usable.ts)
+    const rows = await selectedSkills(db, { orgId: input.orgId, agentId: input.agentId, orgSkills: input.agent.skills?.orgSkills ?? [] }, log);
+    // One skill per name: the agent's own, then an org skill or copy (an id the agent kept from
+    // before the platform component existed), then a platform skill id; ties by id
+    const rank = (r) => r.scope === "agent" ? 0 : r.platformSkillId === r.id ? 2 : 1;
     const byName = new Map();
     for (const r of rows) {
         const prev = byName.get(r.name);
-        if (!prev || (prev.scope === "org" && r.scope === "agent"))
+        if (!prev || rank(r) < rank(prev))
             byName.set(r.name, r);
     }
     const effective = new Map([...byName.values()].map((r) => [
@@ -102,12 +94,12 @@ export async function resolveSkills(db, input) {
             skill: {
                 id: r.id,
                 name: r.name,
-                description: r.manifest.description,
-                version: r.current_version,
-                source: r.object_prefix,
-                ...(r.item_name !== null && { plugin: r.item_name }),
+                description: r.description,
+                version: r.version,
+                source: r.source,
+                ...(r.plugin !== null && { plugin: r.plugin }),
             },
-            format: r.source_format,
+            format: r.format,
             manifest: r.manifest,
         },
     ]));
@@ -182,7 +174,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.
  */
@@ -194,7 +186,8 @@ export function pinnedFailureText(e) {
     return "File storage is temporarily unavailable, so this agent's pinned skills cannot be read; send the message again later.";
 }
 /**
- * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md`, verifies it against
+ * Reads each pinned skill's SKILL.md from `kernel/<orgId>/<source>SKILL.md` (a platform version's
+ * `platform:<prefix>` from `deployment/<prefix>SKILL.md`), verifies it against
  * the manifest's size and sha256 and returns the parsed body, in order. Every failure throws
  * `storage.unavailable` (Decision 9: the run fails before any model request):
  * - a read error is retried once ({@link PINNED_READ_ATTEMPTS}), then is transient (the user
@@ -208,9 +201,10 @@ export async function loadPinnedBodies(storage, orgId, pinned, opts = {}) {
     if (pinned.length === 0)
         return [];
     storage.assertAvailable();
-    const store = storage.kernel(orgId);
     const out = [];
     for (const p of pinned) {
+        // a platform version (`platform:<prefix>`) is read from deployment/ (ruling D2)
+        const { store, prefix } = skillFileStore(storage, orgId, p.source);
         const unreadable = (problem) => {
             opts.log?.error("pinned skill unreadable", {
                 orgId,
@@ -230,7 +224,7 @@ export async function loadPinnedBodies(storage, orgId, pinned, opts = {}) {
         for (let attempt = 1; bytes === null; attempt++) {
             let got;
             try {
-                got = await store.get(`${p.source}${SKILL_ENTRY_FILE}`, opts.signal && { signal: opts.signal });
+                got = await store.get(`${prefix}${SKILL_ENTRY_FILE}`, opts.signal && { signal: opts.signal });
                 if (got)
                     bytes = new Uint8Array(await new Response(got.body).arrayBuffer());
             }
@@ -287,9 +281,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 +312,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 +348,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, attempt === 1 ? log : undefined);
+            // 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";
@@ -12,6 +12,9 @@ declare const DecideBody: z.ZodObject<{
     }>;
     note: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+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 **当前的负责人**判定，
@@ -47,10 +50,14 @@ export declare class AgentSkillsController {
 /**
  * 收件箱（`GET /api/v1/orgs/:orgId/inbox`，计划取舍 C6：按类型汇总）：当前用户待处理的工具审批与
  * 能决定的技能变更，新的在前、最多 100 项（`truncated` 表示还有更多）。仅限用户主体。
+ * Org admins also see the org's open notices and dismiss them with
+ * `POST /api/v1/orgs/:orgId/inbox/notices/:id/dismiss`.
  */
 export declare class InboxController {
     private readonly inbox;
     constructor(inbox: InboxService);
     list(principal: Principal, org: OrgContext): Promise<InboxView>;
+    /** An org admin dismisses an org notice (`skill_renamed`) -> 204. */
+    dismissNotice(principal: Principal, org: OrgContext, params: z.infer<typeof NoticeParamsSchema>): Promise<void>;
 }
 export {};