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

package/dist/skills/skills.service.js

@@ -11,6 +11,7 @@ import { randomUUID } from "node:crypto";
 import { parseSkillMd, SKILL_ENTRY_FILE } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
+import { skillDisabled } from "../agents/definition.js";
 import { offeredNamed } from "../catalog/component-state.js";
 import { PLATFORM_OWNER } from "../catalog/ownership.js";
 import { PlatformComponents } from "../catalog/platform-components.js";
@@ -27,12 +28,11 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { OrgLock } from "../orgs/org-lock.js";
-import { textBytesTokens } from "../runtime/context/tokens.js";
 import { StorageService } from "../storage/storage.service.js";
-import { invocationOf, PINNED_SKILLS_LIMITS } from "./catalog.js";
+import { invocationOf } from "./catalog.js";
 import { cancelRequestIn, } from "./conversation-catalog.js";
 import { readSkillPackage, skillManifest, } from "./package.js";
-import { PLATFORM_SOURCE, platformSkillsOn, platformSource, skillFileStore, skillVersionsById, usableSkills, } from "./usable.js";
+import { agentOwnSkillIds, builtinSkillIds, builtinSkillPlugins, linkedCopyIds, PLATFORM_SOURCE, platformSkillsOn, platformSource, skillFileStore, skillIdsOf, skillVersionsById, usableSkills, } from "./usable.js";
 /**
  * The skills named in `skillNames` an org would see twice if catalog item `itemId` brought its
  * skills (spec §9.2, Decision 8; rule 10 of the plugin scope spec): the org's own usable skills
@@ -130,114 +130,113 @@ const PUT_CONCURRENCY = 4;
 export const SKILL_BODY_MAX_BYTES = 1024 * 1024;
 const notFound = () => new ApiError("skill.not_found", "Skill not found");
 /**
- * 在调用方事务里核对 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 忽略已删除的技能）。
+ * 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 async function assertOrgSkills(db, orgId, ids, kept = new Set()) {
-    const details = [];
-    const seen = new Set();
-    ids.forEach((id, i) => {
-        if (seen.has(id))
-            details.push({ path: `skills.orgSkills.${i}`, message: "Duplicate skill" });
-        seen.add(id);
+export async function assertDisabledSkills(db, a) {
+    const kept = a.kept ?? [];
+    const keptPlugin = new Map();
+    const keptIds = new Set();
+    for (const r of kept) {
+        if (r.kind === "skill")
+            keptIds.add(r.skillId);
+        else
+            keptPlugin.set(r.plugin, r.skills === "all" ? "all" : new Set(r.skills));
+    }
+    const toCheck = [];
+    a.disabled.forEach((r, i) => {
+        if (r.kind === "skill") {
+            if (!keptIds.has(r.skillId))
+                toCheck.push({ i, r });
+            return;
+        }
+        const k = keptPlugin.get(r.plugin);
+        if (k === "all")
+            return;
+        if (k === undefined) {
+            toCheck.push({ i, r });
+            return;
+        }
+        // the plugin was turned off before: only the names added now are checked
+        if (r.skills === "all")
+            return;
+        const added = r.skills.filter((n) => !k.has(n));
+        if (added.length > 0)
+            toCheck.push({ i, r, names: added });
     });
-    const toCheck = [...seen].filter((id) => !kept.has(id));
-    if (toCheck.length > 0) {
-        // The org's skills, its copies linked to a platform skill while that one is on in the org
-        // (as `assertPinnedSkills` sees them), and platform skills on in the org (phase 2)
-        const found = [...(await skillVersionsById(db, orgId, toCheck)).values()]
-            .filter((r) => r.scope === "org")
-            .map((r) => r.id);
-        const live = new Set([...kept, ...found]);
-        ids.forEach((id, i) => {
-            if (!live.has(id)) {
+    if (toCheck.length === 0)
+        return;
+    const usable = await usableSkills(db, a.orgId);
+    const linked = await linkedCopyIds(db, a.orgId, usable.flatMap((u) => (u.origin === "platform" ? [u.id] : [])));
+    const builtinPlugins = await builtinSkillPlugins(db);
+    const builtinIds = new Set(await builtinSkillIds(db, a.orgId));
+    const { own, shared } = a.agentId === null
+        ? { own: [], shared: [] }
+        : await agentOwnSkillIds(db, { orgId: a.orgId, agentId: a.agentId });
+    const fixedIds = new Set([...own, ...shared]);
+    const details = [];
+    for (const { i, r, names } of toCheck) {
+        const path = `disabledSkills.${i}`;
+        if (r.kind === "skill") {
+            if (fixedIds.has(r.skillId)) {
                 details.push({
-                    path: `skills.orgSkills.${i}`,
-                    message: `Skill ${id} does not exist in this organization or has been deleted`,
+                    path,
+                    message: `Skill ${r.skillId} is this agent's own and cannot be turned off`,
+                });
+                continue;
+            }
+            const skill = usable.find((u) => skillIdsOf(u, linked).includes(r.skillId));
+            if (skill === undefined || skill.plugin !== null) {
+                details.push({
+                    path,
+                    message: `Skill ${r.skillId} is not a skill of this organization without a plugin`,
                 });
             }
-        });
-    }
-    if (details.length > 0) {
-        throw new ApiError("validation_failed", "Invalid skill references", details);
-    }
-}
-/**
- * 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).
- */
-export async function assertPinnedSkills(db, orgId, agentId, skills, kept = []) {
-    const pinned = skills?.pinned;
-    if (pinned === undefined)
-        return;
-    const details = [];
-    const seen = new Set();
-    const unique = [];
-    for (const id of pinned) {
-        if (seen.has(id)) {
-            details.push({ skill: id, reason: "duplicate" });
             continue;
         }
-        seen.add(id);
-        if (unique.length >= PINNED_SKILLS_LIMITS.count) {
-            details.push({ skill: id, reason: "too_many" });
+        if (builtinPlugins.has(r.plugin)) {
+            details.push({
+                path,
+                message: `The skills of built-in plugin "${r.plugin}" cannot be turned off`,
+            });
             continue;
         }
-        unique.push(id);
-    }
-    // org and agent skills, org copies linked to a platform skill (its current version) and platform
-    // skills on in the org (phase 2)
-    const byId = new Map([...(await skillVersionsById(db, orgId, unique)).values()].map((r) => [
-        r.id,
-        { id: r.id, scope: r.scope, agent_id: r.agentId, manifest: r.manifest },
-    ]));
-    const keptSet = new Set(kept);
-    const selected = new Set(skills?.orgSkills ?? []);
-    for (const id of unique) {
-        if (keptSet.has(id))
+        const ofPlugin = usable.filter((u) => u.plugin === r.plugin);
+        if (ofPlugin.length === 0) {
+            details.push({ path, message: `Plugin "${r.plugin}" has no skills in this organization` });
             continue;
-        const r = byId.get(id);
-        const own = r?.scope === "agent" && agentId !== null && r.agent_id === agentId;
-        if (!r || (r.scope === "agent" && !own))
-            details.push({ skill: id, reason: "not_found" });
-        else if (r.scope === "org" && !selected.has(id))
-            details.push({ skill: id, reason: "not_selected" });
-        else if (!invocationOf(r.manifest).model)
-            details.push({ skill: id, reason: "manual_only" });
-    }
-    const changed = pinned.length !== kept.length || pinned.some((id, i) => kept[i] !== id);
-    if (details.length === 0 && changed) {
-        let total = 0;
-        let over;
-        for (const id of unique) {
-            const size = byId.get(id)?.manifest.files.find((f) => f.path === SKILL_ENTRY_FILE)?.size ?? 0;
-            total += size;
-            if (over === undefined && total > PINNED_SKILLS_LIMITS.totalBytes)
-                over = id;
         }
-        if (over !== undefined)
-            details.push({ skill: over, reason: "too_large", totalBytes: total });
+        if (r.skills === "all")
+            continue;
+        for (const name of names ?? r.skills) {
+            const skill = ofPlugin.find((u) => u.name === name);
+            if (skill === undefined) {
+                details.push({ path, message: `Plugin "${r.plugin}" has no skill "${name}"` });
+            }
+            else if (builtinIds.has(skill.id) ||
+                (skill.platformSkillId !== undefined && builtinIds.has(skill.platformSkillId))) {
+                details.push({ path, message: `Built-in skill "${name}" cannot be turned off` });
+            }
+            else if (fixedIds.has(skill.id)) {
+                details.push({
+                    path,
+                    message: `Skill "${name}" was shared by this agent and cannot be turned off`,
+                });
+            }
+        }
     }
     if (details.length > 0) {
-        throw new ApiError("agent.pinned_invalid", `Invalid pinned skills: ${details.map((d) => `${d.skill} (${d.reason})`).join(", ")}`, details);
+        throw new ApiError("validation_failed", "Invalid skill references", details);
     }
 }
 const summary = (r) => {
-    const entryBytes = r.manifest?.files.find((f) => f.path === SKILL_ENTRY_FILE)?.size ?? 0;
     const inv = r.manifest ? invocationOf(r.manifest) : { model: true, user: true };
     return {
         id: r.id,
@@ -251,9 +250,6 @@ const summary = (r) => {
         updatedAt: r.updated_at,
         plugin: r.item_name,
         sourceFormat: r.source_format ?? "capybara",
-        suggestPinned: r.suggest_pinned ?? false,
-        entryBytes,
-        tokenEstimate: textBytesTokens(entryBytes),
         manual: inv.model === false,
         fork: inv.fork !== undefined,
         origin: "org",
@@ -276,7 +272,6 @@ const platformSummaryQuery = (db) => db
     "p.owner_org_id",
     "owner.name as owner_name",
     "v.source_format",
-    "v.suggest_pinned",
     "v.manifest",
 ])
     .where("p.deleted_at", "is", null);
@@ -293,7 +288,6 @@ const platformSummary = (r) => ({
         updated_at: r.updated_at,
         item_name: r.plugin_name,
         source_format: r.source_format,
-        suggest_pinned: r.suggest_pinned,
         manifest: r.manifest,
         shareable: false,
     }),
@@ -304,7 +298,7 @@ const platformSummary = (r) => ({
 });
 /**
  * Skills with their summary columns: the catalog item name (provenance) and the current version's
- * source format, pinned suggestion and manifest.
+ * source format and manifest.
  */
 const summaryQuery = (db) => db
     .selectFrom("skills as s")
@@ -322,7 +316,6 @@ const summaryQuery = (db) => db
     "s.updated_at",
     "i.name as item_name",
     "v.source_format",
-    "v.suggest_pinned",
     "v.manifest",
     "s.shareable",
 ]);
@@ -629,7 +622,6 @@ let SkillsService = class SkillsService {
             created_by: actorAccountId,
             ...provenance,
             source_format: opts.catalog?.format ?? "capybara",
-            suggest_pinned: opts.catalog?.suggestPinned ?? false,
         })
             .execute();
         await audit(this.db.db, {
@@ -728,7 +720,9 @@ let SkillsService = 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).
      */
     async list(orgId) {
         const usable = await usableSkills(this.db.db, orgId);
@@ -740,11 +734,14 @@ let SkillsService = class SkillsService {
             u.source.startsWith(PLATFORM_SOURCE)
             ? [[u.id, u.platformSkillId]]
             : []));
+        // builtin plugins' skills (and the org's pinned copies of them): every agent has them
+        const builtin = new Set(await builtinSkillIds(this.db.db, orgId));
         const own = orgIds.length === 0
             ? []
-            : await Promise.all((await summaryQuery(this.db.db).where("s.id", "in", orgIds).orderBy("s.name").execute()).map((r) => {
+            : await Promise.all((await summaryQuery(this.db.db).where("s.id", "in", orgIds).orderBy("s.name").execute()).map(async (r) => {
                 const to = promotedTo.get(r.id);
-                return to === undefined ? summary(r) : this.promotedSummary(r.id, to);
+                const s = to === undefined ? summary(r) : await this.promotedSummary(r.id, to);
+                return { ...s, builtin: builtin.has(r.id) };
             }));
         if (platformIds.length === 0)
             return own;
@@ -763,7 +760,11 @@ let SkillsService = class SkillsService {
             const k = l.platform_skill_id;
             linked.set(k, [...(linked.get(k) ?? []), l.id]);
         }
-        const platform = (await platformSummaryQuery(this.db.db).where("p.id", "in", platformIds).execute()).map((r) => ({ ...platformSummary(r), linkedIds: linked.get(r.id) ?? [] }));
+        const platform = (await platformSummaryQuery(this.db.db).where("p.id", "in", platformIds).execute()).map((r) => ({
+            ...platformSummary(r),
+            linkedIds: linked.get(r.id) ?? [],
+            builtin: builtin.has(r.id),
+        }));
         return [...own, ...platform].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : 1);
     }
     /**
@@ -816,6 +817,66 @@ let SkillsService = class SkillsService {
      * 404 while that skill is off in the org); a pinned copy keeps its own (Task 10).
      */
     async get(orgId, skillId) {
+        const detail = await this.detail(orgId, skillId);
+        return { ...detail, agentsOff: await this.agentsOff(orgId, detail) };
+    }
+    /**
+     * 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.
+     */
+    async agentsOff(orgId, skill) {
+        const db = this.db.db;
+        const usable = await usableSkills(db, orgId);
+        const linked = await linkedCopyIds(db, orgId, usable.flatMap((u) => (u.origin === "platform" ? [u.id] : [])));
+        const u = usable.find((x) => skillIdsOf(x, linked).includes(skill.id));
+        if (u === undefined)
+            return 0;
+        const ids = skillIdsOf(u, linked);
+        if (u.plugin !== null &&
+            u.origin === "platform" &&
+            (await builtinSkillPlugins(db)).has(u.plugin))
+            return 0;
+        const builtinIds = new Set(await builtinSkillIds(db, orgId));
+        if (ids.some((id) => builtinIds.has(id)))
+            return 0;
+        const rows = await db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select([
+            "agents.id",
+            sql `agent_versions.definition->'disabledSkills'`.as("disabled_skills"),
+        ])
+            .where("agents.org_id", "=", orgId)
+            .where("agents.deleted_at", "is", null)
+            .where(sql `jsonb_array_length(coalesce(agent_versions.definition->'disabledSkills', '[]'::jsonb)) > 0`)
+            .execute();
+        if (rows.length === 0)
+            return 0;
+        // the agent that shared an org skill always has it
+        const sharedBy = await db
+            .selectFrom("skills")
+            .select("origin_agent_id")
+            .where("org_id", "=", orgId)
+            .where("scope", "=", "org")
+            .where("deleted_at", "is", null)
+            .where("id", "in", ids)
+            .where("origin_agent_id", "is not", null)
+            .execute();
+        const sharers = new Set(sharedBy.map((r) => r.origin_agent_id));
+        return rows.filter((r) => !sharers.has(r.id) &&
+            Array.isArray(r.disabled_skills) &&
+            skillDisabled(r.disabled_skills, {
+                plugin: u.plugin,
+                name: u.name,
+                ids,
+            })).length;
+    }
+    /** The skill's detail without `agentsOff` (no agents scan; for names and checks). */
+    async detail(orgId, skillId) {
         const link = await this.db
             .selectFrom("skills")
             .select("platform_skill_id")

package/dist/skills/usable.d.ts

@@ -1,4 +1,5 @@
 import type { Logger, ObjectStore } from "@capybara-hq/plugin-sdk";
+import { type DisabledSkillRef } from "../agents/definition.js";
 import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
 /** The `source` prefix of a platform skill version in a snapshot or an invocation record. */
 export declare const PLATFORM_SOURCE = "platform:";
@@ -30,6 +31,13 @@ export interface UsableSkill {
     /** The platform skill whose content this is (a platform skill, or a linked org copy). */
     platformSkillId?: string;
 }
+/**
+ * A resolver's logger: name clashes are warnings; `debug` (the kernel logger has it) takes the ones
+ * nobody chose (a builtin skill no agent selected, shadowed for every resolution).
+ */
+type ResolveLog = Pick<Logger, "warn"> & {
+    debug?: (msg: string, fields?: Record<string, unknown>) => void;
+};
 /** A usable or selected skill with what the resolvers need beyond {@link UsableSkill}. */
 export interface SkillVersionRow extends UsableSkill {
     /** `agent`: an agent's own skill (never in the org library). Platform skills are `org`. */
@@ -57,18 +65,58 @@ export declare function pinnedSkillLinksServed(db: KernelSchemaDb, orgId: string
  * while the platform skill is on in the org; a pinned copy as its own version, while its platform
  * skill is on in the org (ruling P2-18); a platform skill id while it is on in the org.
  */
-export declare function skillVersionsById(db: KernelSchemaDb, orgId: string, ids: readonly string[], log?: Pick<Logger, "warn">): Promise<Map<string, SkillVersionRow>>;
+export declare function skillVersionsById(db: KernelSchemaDb, orgId: string, ids: readonly string[], log?: ResolveLog, 
+/** Ids nobody selected (builtin skills): a name clash of theirs is logged at `debug`. */
+quiet?: ReadonlySet<string>): Promise<Map<string, SkillVersionRow>>;
+/**
+ * The skill ids no agent can turn off (skill authoring spec §5.7, skills default-on spec §3): the
+ * live platform skills of the platform's builtin plugins (`catalog_items.builtin`, platform-owned),
+ * plus the org's pinned copies of them (a pinned copy shadows its platform skill by name, ruling
+ * P2-18). Whether each is on in the org (a component switch, the deployment's disable) is left to
+ * the resolvers.
+ */
+export declare function builtinSkillIds(db: KernelSchemaDb, orgId: string): Promise<string[]>;
+/**
+ * The names of the platform's builtin plugins (`catalog_items.builtin`, platform-owned, live): their
+ * skills are always on, and an agent cannot turn them off (skills default-on spec §3).
+ */
+export declare function builtinSkillPlugins(db: KernelSchemaDb): Promise<Set<string>>;
+/**
+ * The ids of the skills an agent always has, whatever its `disabledSkills` say: its own skills
+ * (`scope = 'agent'`) and the org skills it shared (`origin_agent_id`: the agent keeps a shared
+ * skill without a definition entry).
+ */
+export declare function agentOwnSkillIds(db: KernelSchemaDb, a: {
+    orgId: string;
+    agentId: string;
+}): Promise<{
+    own: string[];
+    shared: string[];
+}>;
+/**
+ * The org's copies linked to the platform skills `platformIds` without a pin (ruling B2), by
+ * platform skill id (the first by id when there are several): such a copy keeps its own id in an
+ * agent's catalog, as when it was selected, so the snapshot does not change when a copy gets
+ * linked.
+ */
+export declare function linkedCopyIds(db: KernelSchemaDb, orgId: string, platformIds: readonly string[]): Promise<Map<string, string>>;
+/**
+ * The ids a disabled skill entry may name for `r`: its own, the platform skill it serves and the
+ * org's linked copy listed under it (`linked`, from {@link linkedCopyIds}).
+ */
+export declare function skillIdsOf(r: UsableSkill, linked: ReadonlyMap<string, string>): string[];
 /**
- * The skills an agent selects, sorted by id: its own skills (`scope = 'agent'`), the org skills
- * it shared (`origin_agent_id`: the agent keeps a shared skill without a definition change) and
- * the ids of `orgSkills` that resolve ({@link skillVersionsById}: org skills, linked copies,
- * platform skills on in the org). Not deduplicated by name.
+ * The skills an agent has (skills default-on spec §3), sorted by id: its own skills, the org
+ * skills it shared, and every skill on in the org ({@link usableSkillVersions}) minus what
+ * `disabledSkills` turns off. A plugin entry matches a skill's `plugin` and name, a skill entry its
+ * id (or the platform skill a copy serves). The skills of builtin plugins, the agent's own and its
+ * shared ones are never turned off. Not deduplicated by name (`resolveSkills` ranks).
  */
-export declare function selectedSkills(db: KernelSchemaDb, a: {
+export declare function agentSkills(db: KernelSchemaDb, a: {
     orgId: string;
     agentId: string;
-    orgSkills: readonly string[];
-}, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;
+    disabledSkills: readonly DisabledSkillRef[];
+}, log?: ResolveLog): Promise<SkillVersionRow[]>;
 /**
  * The org's usable skills, sorted by name: its own live org skills (`scope = 'org'`, unlinked, or
  * pinned while their platform skill is on in the org, ruling P2-18) and the platform skills on in
@@ -80,3 +128,4 @@ export declare function selectedSkills(db: KernelSchemaDb, a: {
 export declare function usableSkills(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<UsableSkill[]>;
 /** {@link usableSkills} with each skill's manifest and format. */
 export declare function usableSkillVersions(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<SkillVersionRow[]>;
+export {};