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

package/dist/skills/catalog.js

@@ -7,38 +7,28 @@ 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 { 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 { KernelConfigService } from "../infra/config/kernel-config.service.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";
+import { catalogLine, sameSnapshot, } from "../runtime/context/skills.js";
+import { agentOwnSkillIds, agentSkills, builtinSkillIds, builtinSkillPlugins, } from "./usable.js";
 /**
- * 技能目录快照（M5 T14，Ruling M17）：运行开始时解析「此刻对这个对话生效的技能」，与日志里最新一份快照不同才写
- * `skills_catalog`。模型看到的目录与 `Skill` 的名字解析只来自日志，不读实时的库。
- */
-/**
- * Pinned skill limits (spec §9.1): at most `count` pinned skills per agent, whose current SKILL.md
- * sizes total at most `totalBytes`. Saving checks both; at run time the pinned bodies are kept in
- * the agent's order while they fit.
- */
-export const PINNED_SKILLS_LIMITS = { count: 3, totalBytes: 32768 };
-/**
- * 此刻对这个对话生效的技能，按名字（码点序）排序：
- * - 运行所用 agent 版本选中的组织技能（`scope='org'`，id 在 `skills.orgSkills` 里）；
- * - 加上这个 agent 自己的技能（`scope='agent'`）；
- * - 已删除的跳过（保存过的 agent 版本仍可能引用它们）；
- * - 版本取 `current_version`，描述取该版本清单里的描述。
- * 组织技能与 agent 自己的技能同名时只保留 agent 自己的（更具体；`/skills/<name>/` 与按名字加载都不能有两个）。
+ * The skills in effect for this conversation now, sorted by name (code point order), as
+ * {@link agentSkills} resolves them (skills default-on spec §3):
+ * - the agent's own skills (`scope='agent'`) and the org skills it shared;
+ * - plus every skill on in the org, minus what the run's agent version's `disabledSkills` turns
+ *   off (never a builtin plugin's skill);
+ * - deleted skills are skipped;
+ * - the version is `current_version`, the description the one in that version's manifest.
+ * When an org skill and the agent's own skill share a name only the agent's own is kept (more
+ * specific; neither `/skills/<name>/` nor loading by name can have two).
  *
  * Trials: a pending version proposal of this agent made in this conversation replaces, by name,
  * the version of its skill (the id of the existing skill, the version it would become on
@@ -77,12 +67,13 @@ function forModel(all, input, log) {
  * `conversationId` (a conversation not created yet) no trial draft applies.
  */
 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 rows = await agentSkills(db, {
+        orgId: input.orgId,
+        agentId: input.agentId,
+        disabledSkills: input.agent.disabledSkills ?? [],
+    }, log);
+    // One skill per name: the agent's own, then an org skill or copy, then a platform skill; 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) {
@@ -103,6 +94,8 @@ export async function resolveSkills(db, input, log) {
             },
             format: r.format,
             manifest: r.manifest,
+            scope: r.scope,
+            origin: r.origin,
         },
     ]));
     const trials = input.conversationId === undefined
@@ -118,6 +111,7 @@ export async function resolveSkills(db, input, log) {
             .where("kind", "=", "version")
             .execute();
     for (const { proposed_version: p, object_prefix } of trials) {
+        const replaced = effective.get(p.manifest.name);
         effective.set(p.manifest.name, {
             skill: {
                 id: p.skillId,
@@ -128,160 +122,61 @@ export async function resolveSkills(db, input, log) {
             },
             format: "capybara",
             manifest: p.manifest,
+            scope: replaced?.scope ?? "agent",
+            origin: replaced?.origin ?? "org",
         });
     }
     return [...effective.values()].sort((a, b) => a.skill.name < b.skill.name ? -1 : a.skill.name > b.skill.name ? 1 : 0);
 }
 /**
- * The pinned skills of the run's agent version that are effective now, in the definition's order
- * (unique, at most {@link PINNED_SKILLS_LIMITS}.count). An id that is not in the model's catalog
- * (`model`: deleted, deselected, its plugin uninstalled, shadowed by an agent skill of the same
- * name) is skipped; one whose current version is manual-only (phase D) is skipped with a warning
- * when `log` is given.
+ * The {@link BudgetTier} of a resolved skill: the agent's own (`scope` `agent`, or an org skill it
+ * shared, `known.shared`: always on, never turned off, spec §3), else builtin (a platform skill of
+ * a builtin plugin, `known.plugins`, or one of `known.ids`, as `builtinSkillIds` gives them), else
+ * the org's own (no plugin), else a plugin skill.
  */
-function pinnedCandidates(model, agent, input, all, log) {
-    const byId = new Map(model.map((r) => [r.skill.id, r]));
-    const manual = new Map(all.filter((r) => !invocationOf(r.manifest).model).map((r) => [r.skill.id, r]));
-    const out = [];
-    for (const id of new Set(agent.skills?.pinned ?? [])) {
-        const m = manual.get(id);
-        if (m) {
-            log?.warn("pinned skill is manual-only", {
-                orgId: input.orgId,
-                agentId: input.agentId,
-                conversationId: input.conversationId,
-                skillId: id,
-                name: m.skill.name,
-                version: m.skill.version,
-            });
-            continue;
-        }
-        const r = byId.get(id);
-        if (!r)
-            continue;
-        const { name, version, source } = r.skill;
-        out.push({ id, version, name, source, manifest: r.manifest });
-        if (out.length >= PINNED_SKILLS_LIMITS.count)
-            break;
+export function budgetTier(r, known) {
+    if (r.scope === "agent" || known.shared.has(r.skill.id))
+        return 0;
+    const plugin = r.skill.plugin;
+    if ((r.origin === "platform" && plugin !== undefined && known.plugins.has(plugin)) ||
+        known.ids.has(r.skill.id)) {
+        return 1;
     }
-    return out;
+    return plugin === undefined ? 2 : 3;
 }
-const sameCandidates = (a, b) => a.length === b.length &&
-    a.every((p, i) => {
-        const q = b[i];
-        return q !== undefined && p.id === q.id && p.version === q.version && p.source === q.source;
-    });
-const storageUnavailable = (message) => new ApiError("storage.unavailable", message);
-/** `details[0].reason` of a pinned SKILL.md that cannot be used whatever the retries. */
-const PINNED_UNREADABLE = "pinned_unreadable";
-/** Read attempts per pinned SKILL.md (a transient storage error is retried once). */
-const PINNED_READ_ATTEMPTS = 2;
+/** The characters a described entry takes in the listing: its line and the line break. */
+export const catalogLineChars = (s) => [...catalogLine(s)].length + 1;
 /**
- * The `run_failed` message (shown to the user, English like the other run texts) for a
- * `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.
+ * The catalog budget (skills default-on spec §7): the entries ranked by `tierOf` (then by name, in
+ * code point order) keep their descriptions while the running total of their rendered lines
+ * ({@link catalogLineChars}) stays within `budget`; the first one past it and every one after it
+ * are name-only. Pure and deterministic; `tierOf` is only called when the whole listing does not
+ * fit. Entries keep their input order; any `nameOnly` they carry is replaced.
  */
-export function pinnedFailureText(e) {
-    const d = e.details?.[0];
-    if (d?.reason === PINNED_UNREADABLE) {
-        return `Pinned skill "${d.name}" cannot be read; ask the agent's owner to unpin it or upload it again.`;
-    }
-    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` (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
- *   sends again);
- * - a manifest without SKILL.md, a missing object, an integrity mismatch, non-UTF-8 or an
- *   unparsable file is permanent: logged at `error` with the skill id and source, and the error
- *   carries `details: [{ reason: "pinned_unreadable", skillId, name, source }]`
- *   ({@link pinnedFailureText} turns it into an owner-facing message).
- */
-export async function loadPinnedBodies(storage, orgId, pinned, opts = {}) {
-    if (pinned.length === 0)
-        return [];
-    storage.assertAvailable();
-    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,
-                skillId: p.id,
-                version: p.version,
-                source: p.source,
-                problem,
-            });
-            return new ApiError("storage.unavailable", `Pinned skill ${p.name} ${problem}`, [
-                { reason: PINNED_UNREADABLE, skillId: p.id, name: p.name, source: p.source },
-            ]);
-        };
-        const entry = p.manifest.files.find((f) => f.path === SKILL_ENTRY_FILE);
-        if (!entry)
-            throw unreadable(`has no ${SKILL_ENTRY_FILE} in its manifest`);
-        let bytes = null;
-        for (let attempt = 1; bytes === null; attempt++) {
-            let got;
-            try {
-                got = await store.get(`${prefix}${SKILL_ENTRY_FILE}`, opts.signal && { signal: opts.signal });
-                if (got)
-                    bytes = new Uint8Array(await new Response(got.body).arrayBuffer());
-            }
-            catch {
-                if (attempt >= PINNED_READ_ATTEMPTS) {
-                    throw storageUnavailable(`Cannot read pinned skill ${p.name} from storage`);
-                }
-                continue;
-            }
-            if (!got)
-                throw unreadable("is missing from storage");
-        }
-        if (bytes.byteLength !== entry.size ||
-            createHash("sha256").update(bytes).digest("hex") !== entry.sha256) {
-            throw unreadable("failed its integrity check");
-        }
-        let text;
-        try {
-            text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-        }
-        catch {
-            throw unreadable("is not UTF-8");
-        }
-        const parsed = parseSkillMd(text, { invocationKeys: false });
-        if ("errors" in parsed)
-            throw unreadable("cannot be parsed");
-        out.push({ id: p.id, version: p.version, name: p.name, source: p.source, body: parsed.body });
-    }
-    return out;
-}
-/**
- * The pinned skills that fit: in order while the running total of UTF-8 body bytes stays within
- * {@link PINNED_SKILLS_LIMITS}.totalBytes; the first that does not fit and every later one are
- * dropped with a warning (Review Focus 4: a pinned skill's new version can push a saved set over).
- */
-export function fitPinned(pinned, log, input) {
-    const enc = new TextEncoder();
+export async function applyCatalogBudget(skills, budget, tierOf) {
+    const described = skills.map(({ nameOnly: _n, ...s }) => s);
+    const cost = described.map(catalogLineChars);
+    const characters = cost.reduce((a, b) => a + b, 0);
+    if (characters <= budget)
+        return { skills: described, characters, nameOnly: 0 };
+    const tier = await tierOf();
+    const order = described
+        .map((s, i) => ({ s, i, t: tier(s) }))
+        .sort((a, b) => a.t !== b.t ? a.t - b.t : a.s.name < b.s.name ? -1 : a.s.name > b.s.name ? 1 : a.i - b.i);
+    const cut = new Set();
     let total = 0;
-    for (let i = 0; i < pinned.length; i++) {
-        total += enc.encode(pinned[i].body).byteLength;
-        if (total > PINNED_SKILLS_LIMITS.totalBytes) {
-            log?.warn("pinned skills over the limit", {
-                orgId: input.orgId,
-                agentId: input.agentId,
-                conversationId: input.conversationId,
-                kept: pinned.slice(0, i).map((p) => p.name),
-                dropped: pinned.slice(i).map((p) => p.name),
-                maxBytes: PINNED_SKILLS_LIMITS.totalBytes,
-            });
-            return pinned.slice(0, i);
-        }
+    for (const { i } of order) {
+        const c = cost[i];
+        if (cut.size === 0 && total + c <= budget)
+            total += c;
+        else
+            cut.add(i);
     }
-    return [...pinned];
+    return {
+        skills: described.map((s, i) => (cut.has(i) ? { ...s, nameOnly: true } : s)),
+        characters,
+        nameOnly: cut.size,
+    };
 }
 /** `skills_catalog` 的幂等键：每次运行最多写一份。 */
 /**
@@ -337,66 +232,74 @@ export async function lockLatestCatalog(db, conversationId) {
         .executeTakeFirst();
     return last ? last.payload : undefined;
 }
-/** How often run start re-resolves when the pinned set changed while its bodies were read. */
-const RECORD_ATTEMPTS = 3;
 /**
  * 运行开始时记录技能目录快照：解析生效的技能，与日志里最新一份不同才写（带幂等键，崩溃重试不重复）。
  * 从没有快照、现在也没有技能 → 不写（没有技能的 agent 不出现目录）；之前有、现在全没了 → 写空快照（模型据此得知被移除）。
  * 解析、比较、追加在一个事务里、先锁会话行：否则在解析与追加之间提交的拒绝 + 回退快照会被过时的草稿条目盖回去。
  * 解析只读 skills / agents / 申请（不加锁），不会与别的路径形成死锁。
  *
- * Phase B: the snapshot also carries each skill's `plugin`, the pinned skills' bodies (`pinned`)
- * and the Claude Code tool-name map (`toolMap`, iff an effective skill has source format
- * `claude-code`). Pinned bodies are read from object storage outside the transaction (1); inside
- * it the skills are resolved again (2), and when the pinned identities changed meanwhile the
- * 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`.
+ * The snapshot also carries each skill's `plugin` and the Claude Code tool-name map (`toolMap`,
+ * iff an effective skill has source format `claude-code`). It never carries `pinned` any more
+ * (skills default-on spec §8): a conversation whose latest snapshot has pins gets one without them,
+ * and the request tells the model they were removed. Run start reads no object storage.
+ *
+ * The catalog budget (`skills.catalogBudgetChars`, spec §7) is applied here and recorded in the
+ * snapshot: entries past it carry `nameOnly: true` ({@link applyCatalogBudget}); the cut is logged
+ * as `skills.catalog_over_budget`. A changed budget writes a new snapshot at the next run start
+ * only when an entry crosses it. Snapshots appended elsewhere (a skill registration, a trial's
+ * revert) carry the entries forward as they are; the next run start applies the budget again.
  */
 let SkillsCatalogService = class SkillsCatalogService {
     db;
-    storage;
     eventLog;
     log;
     txHost;
-    constructor(db, storage, eventLog, log, txHost) {
+    config;
+    constructor(db, eventLog, log, txHost, config) {
         this.db = db;
-        this.storage = storage;
         this.eventLog = eventLog;
         this.log = log;
         this.txHost = txHost;
+        this.config = config;
     }
     /**
      * 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;
-        }
-        throw new ApiError("conflict", "The pinned skills kept changing while the run started; send the message again.");
+        const toSeq = await this.append(input, opts.log ?? this.log);
+        if (toSeq !== null)
+            await this.eventLog.notify(input.conversationId, toSeq);
     }
-    /** Step (2) of {@link record}: under the conversation row lock, resolve again and append. */
-    async append(input, first, pinned, log) {
+    /** Under the conversation row lock, resolves the skills and appends a changed snapshot. */
+    async append(input, log) {
         const last = await lockLatestCatalog(this.db.db, input.conversationId);
-        const all = await resolveSkills(this.db.db, input);
+        const all = await resolveSkills(this.db.db, input, log);
         const resolved = forModel(all, input, log);
-        if (!sameCandidates(first, pinnedCandidates(resolved, input.agent, input, all))) {
-            return "retry";
+        const budget = this.config.get().skills.catalogBudgetChars;
+        const cut = await applyCatalogBudget(resolved.map((r) => r.skill), budget, async () => {
+            const plugins = await builtinSkillPlugins(this.db.db);
+            const ids = new Set(await builtinSkillIds(this.db.db, input.orgId));
+            const shared = new Set((await agentOwnSkillIds(this.db.db, input)).shared);
+            // names are unique in the catalog
+            const tiers = new Map(resolved.map((r) => [r.skill.name, budgetTier(r, { plugins, ids, shared })]));
+            return (s) => tiers.get(s.name) ?? 3;
+        });
+        const skills = cut.skills;
+        if (cut.nameOnly > 0) {
+            this.log.info("skills.catalog_over_budget", {
+                orgId: input.orgId,
+                agentId: input.agentId,
+                conversationId: input.conversationId,
+                runId: input.runId,
+                entries: skills.length,
+                nameOnly: cut.nameOnly,
+                characters: cut.characters,
+                budget,
+            });
         }
-        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") && {
@@ -422,9 +325,9 @@ __decorate([
 SkillsCatalogService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
-    __param(1, Inject(StorageService)),
-    __param(2, Inject(EventLog)),
-    __param(3, Inject(KERNEL_LOGGER)),
-    __param(4, Inject(TransactionHost))
+    __param(1, Inject(EventLog)),
+    __param(2, Inject(KERNEL_LOGGER)),
+    __param(3, Inject(TransactionHost)),
+    __param(4, Inject(KernelConfigService))
 ], SkillsCatalogService);
 export { SkillsCatalogService };

package/dist/skills/conversation-catalog.d.ts

@@ -21,9 +21,9 @@ export interface CancelledDrafts {
  * `EventLog.append` takes) and reads the latest snapshot under it, so no other snapshot slips in
  * between "read latest" and "append". Returns the seq written, or null when nothing was written;
  * the caller calls `eventLog.notify` after the commit.
- * `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.
+ * `derive` gets the whole latest payload, so `toolMap` is carried forward (it is only recomputed at
+ * run start). `pinned` of an old snapshot never is: new snapshots carry no pinned skills (skills
+ * default-on spec §8).
  */
 export declare function appendConversationCatalog(deps: ConversationCatalogDeps, conversationId: string, derive: (base: SkillsSnapshot) => SkillsSnapshot | null, idemKey: string, runId?: string | null): Promise<number | null>;
 /**

package/dist/skills/conversation-catalog.js

@@ -1,7 +1,7 @@
 import { sql } from "kysely";
 import { audit } from "../identity/audit.js";
-import { sameSnapshot, } from "../runtime/context/skills.js";
-import { fitPinned, invocationOf, lockLatestCatalog } from "./catalog.js";
+import { sameSnapshot } from "../runtime/context/skills.js";
+import { invocationOf, lockLatestCatalog } from "./catalog.js";
 const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
 /**
  * In the caller's transaction, derives the conversation's next skills catalog snapshot from its
@@ -9,9 +9,9 @@ const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
  * `EventLog.append` takes) and reads the latest snapshot under it, so no other snapshot slips in
  * between "read latest" and "append". Returns the seq written, or null when nothing was written;
  * the caller calls `eventLog.notify` after the commit.
- * `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.
+ * `derive` gets the whole latest payload, so `toolMap` is carried forward (it is only recomputed at
+ * run start). `pinned` of an old snapshot never is: new snapshots carry no pinned skills (skills
+ * default-on spec §8).
  */
 export async function appendConversationCatalog(deps, conversationId, derive, idemKey, runId) {
     const base = (await lockLatestCatalog(deps.db.db, conversationId)) ?? { skills: [] };
@@ -19,11 +19,8 @@ export async function appendConversationCatalog(deps, conversationId, derive, id
     if (derived === null)
         return null;
     const skills = [...derived.skills].sort(byName);
-    const live = (p) => skills.some((s) => s.id === p.id && s.version === p.version && s.source === p.source);
-    const pinned = fitPinned((derived.pinned ?? []).filter(live), deps.log, { conversationId });
     const next = {
         skills,
-        ...(pinned.length > 0 && { pinned }),
         ...(derived.toolMap !== undefined && { toolMap: derived.toolMap }),
     };
     if (sameSnapshot(base, next))
@@ -88,7 +85,6 @@ export async function revertTrialCatalog(deps, req) {
         if (!base.skills.some((s) => s.source === req.object_prefix))
             return null;
         const rest = base.skills.filter((s) => s.source !== req.object_prefix);
-        // The draft's pinned entry goes (Decision 8): the next run start pins the real version
         return {
             ...base,
             // A manual-only current version (phase D) stays out of the model's catalog
@@ -104,9 +100,6 @@ export async function revertTrialCatalog(deps, req) {
                     },
                 ]
                 : rest,
-            ...(base.pinned && {
-                pinned: base.pinned.filter((p) => p.source !== req.object_prefix),
-            }),
         };
     }, `skills_catalog:revert:${req.id}`);
 }

package/dist/skills/invoke.d.ts

@@ -61,7 +61,7 @@ export declare const notInvocable: (reason: NotInvocableReason, name: string) =>
 export declare function recordedSkillBlocked(db: KernelSchemaDb, a: {
     orgId: string;
     agentId: string;
-    agent: Pick<AgentDefinition, "skills">;
+    agent: Pick<AgentDefinition, "disabledSkills">;
     conversationId: string;
     skillId: string;
 }): Promise<NotInvocableReason | null>;
@@ -93,7 +93,7 @@ export declare class SkillInvoker {
     list(a: {
         orgId: string;
         agentId: string;
-        agent: Pick<AgentDefinition, "skills">;
+        agent: Pick<AgentDefinition, "disabledSkills">;
         conversationId?: string;
     }): Promise<InvocableSkill[]>;
     /**

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

@@ -41,7 +41,9 @@ export declare class SkillsController {
     list(principal: Principal, org: OrgContext): Promise<{
         skills: SkillSummary[];
     }>;
-    get(principal: Principal, org: OrgContext, id: string): Promise<SkillDetail>;
+    get(principal: Principal, org: OrgContext, id: string): Promise<SkillDetail & {
+        agentsOff: number;
+    }>;
     /**
      * Sets 可共享 on the org's own skill (`{ shareable }` -> 200 `{ id, shareable }`): only an org
      * skill of the org's own (P3-6: an agent's skill or a copy of another owner's platform skill ->

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

@@ -1,4 +1,4 @@
-import type { AgentDefinition } from "../agents/definition.js";
+import { type DisabledSkillRef } from "../agents/definition.js";
 import { type Owner } from "../catalog/ownership.js";
 import { type OwnerVersion, PlatformComponents } from "../catalog/platform-components.js";
 import { AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
@@ -53,12 +53,6 @@ export interface SkillSummary {
     plugin: string | null;
     /** The format of the plugin the current version came from. */
     sourceFormat: SourceFormat;
-    /** The plugin suggests pinning the current version (spec §9.1). */
-    suggestPinned: boolean;
-    /** SKILL.md size of the current version, in bytes (0 when the manifest has none). */
-    entryBytes: number;
-    /** Token estimate of the SKILL.md of the current version (ASCII rule: bytes / 4). */
-    tokenEstimate: number;
     /** Phase D: the current version is manual-only (not in the model's catalog). */
     manual: boolean;
     /** Phase D: the current version runs as a sub-agent when a person invokes it. */
@@ -84,6 +78,12 @@ export interface SkillSummary {
      * selects this skill.
      */
     linkedIds?: string[];
+    /**
+     * In the library list only (true or false on every item there, absent elsewhere): a platform
+     * skill of a builtin plugin (`platformBuiltin`: builtin and platform-owned) or the org's pinned
+     * copy of one. Every agent has it and none can turn it off (skills default-on spec §3).
+     */
+    builtin?: boolean;
 }
 /** 技能的一个版本（含文件清单）。 */
 export interface SkillVersionView {
@@ -111,33 +111,23 @@ export interface UploadedSkill {
     created: boolean;
 }
 /**
- * 在调用方事务里核对 agent 定义引用的组织技能：每个 id 都必须是该组织未删除的 `scope=org` 技能
- * (or, phase 2, a platform skill on in the org: skills/usable.ts)，
- * 否则 `validation_failed`（path `skills.orgSkills.<i>`）；不可重复。调用方须已锁组织行（技能删除同样锁组织行，二者串行）。
- * `kept`：当前版本里已有的引用（保存时合法），修改时不再核对——技能之后被删也不挡住其他改动（运行时由 T14 忽略已删除的技能）。
- */
-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). */
- | "manual_only";
-/**
- * Checks `skills.pinned` of an agent definition in the caller's transaction (the org row is locked,
- * like {@link assertOrgSkills}); throws 400 `agent.pinned_invalid` with one detail per problem
- * (`{ skill, reason, totalBytes? }`):
- * - `duplicate`: an id listed twice; `too_many`: every id past {@link PINNED_SKILLS_LIMITS}.count;
- * - each newly added id (not in `kept`, the current definition's pinned ids) must be a live org
- *   skill listed in `skills.orgSkills` (else `not_selected`) or a live skill of this agent
- *   (`agentId`; null when creating), else `not_found`. Kept ids are not re-checked: a pinned skill
- *   deleted later does not block other edits (the run ignores it);
- * - `manual_only` (phase D): a newly added id whose current version is manual-only
- *   (`invocation.model === false`); a kept one that became manual-only is dropped at run time;
- * - `too_large`: the current SKILL.md sizes of the live pinned skills total more than
- *   {@link PINNED_SKILLS_LIMITS}.totalBytes (named by the first skill past the limit). Checked only
- *   when the pinned list changed: a pinned skill's new version never blocks an unrelated edit (the
- *   run keeps what fits).
+ * Checks `disabledSkills` of an agent definition in the caller's transaction (skills default-on
+ * spec §4); throws 400 `validation_failed` with one detail per problem at `disabledSkills.<i>`:
+ * - a plugin entry must name a plugin with at least one skill usable in the org, and each name must
+ *   be a skill of it;
+ * - a skill entry must name a usable org skill without a plugin;
+ * - a builtin plugin, a builtin skill, the agent's own skill or an org skill it shared cannot be
+ *   turned off.
+ * What the current version already turns off (`kept`) is not checked again: a whole entry, or the
+ * names a plugin entry kept, so a plugin switched off or uninstalled later never blocks other edits.
  */
-export declare function assertPinnedSkills(db: KernelSchemaDb, orgId: string, agentId: string | null, skills: AgentDefinition["skills"], kept?: readonly string[]): Promise<void>;
+export declare function assertDisabledSkills(db: KernelSchemaDb, a: {
+    orgId: string;
+    /** Null when creating. */
+    agentId: string | null;
+    disabled: readonly DisabledSkillRef[];
+    kept?: readonly DisabledSkillRef[];
+}): Promise<void>;
 /**
  * 技能库（M5 T13）：组织技能的上传（新技能或新版本）、列表、详情与软删除。
  * 字节在对象存储 `kernel/<orgId>/skills/<uploadId>/<path>`，元数据在 PG；无进程内状态，可多副本共用。
@@ -217,8 +207,6 @@ export declare class SkillsService {
             approvedBy?: string;
             /** The catalog version's source format (default capybara). */
             format?: SourceFormat;
-            /** The plugin manifest suggests pinning this skill (spec §9.1). */
-            suggestPinned?: boolean;
         };
         /**
          * The files are already stored (no storage I/O here, so it may join a transaction): at
@@ -258,7 +246,9 @@ export declare class SkillsService {
     /**
      * The org skill library, sorted by name: the org's live `scope=org` skills except copies linked
      * to a platform skill without a pin, and the platform skills on in the org (phase 2,
-     * `usableSkills`; `origin` tells them apart), each with the ids of those copies (`linkedIds`).
+     * `usableSkills`; `origin` tells them apart), each with the ids of those copies (`linkedIds`);
+     * every item carries `builtin`: true for a platform skill of a builtin plugin or the org's pinned
+     * copy of one (every agent has it, none can turn it off).
      */
     list(orgId: string): Promise<SkillSummary[]>;
     /**
@@ -279,7 +269,18 @@ export declare class SkillsService {
      * content under its own id, so its detail is the platform skill's (its id, versions and body;
      * 404 while that skill is off in the org); a pinned copy keeps its own (Task 10).
      */
-    get(orgId: string, skillId: string): Promise<SkillDetail>;
+    get(orgId: string, skillId: string): Promise<SkillDetail & {
+        agentsOff: number;
+    }>;
+    /**
+     * How many of the org's live agents turn the skill off in their current version (skills
+     * default-on spec §10: 「N 个智能体关闭了它」): matched by the rule of `agentSkills` against the
+     * skill as the org's usable set holds it. A builtin skill, one not usable in the org and an org
+     * skill for the agent that shared it count 0.
+     */
+    private agentsOff;
+    /** The skill's detail without `agentsOff` (no agents scan; for names and checks). */
+    detail(orgId: string, skillId: string): Promise<SkillDetail>;
     /**
      * A platform skill's detail (phase 2): only while it is on in the org, else `skill.not_found`.
      * Its versions are the platform skill's.