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

package/dist/schedules/unattended.js

@@ -0,0 +1,228 @@
+import { sql } from "kysely";
+import { readScheduleSettings } from "./effective-settings.js";
+/**
+ * The scheduled task run a kernel run serves (scheduled tasks spec §4, §7), or null for an attended
+ * run: `runs.scheduled_task_run_id`, set on the run a task's message triggered and inherited by the
+ * runs descending from it without a person (sub-agent runs, wake runs). A run whose task run row is
+ * gone is treated as attended.
+ */
+export async function unattendedTaskRunOf(db, runId) {
+    const row = await db
+        .selectFrom("runs as r")
+        .innerJoin("scheduled_task_runs as tr", "tr.id", "r.scheduled_task_run_id")
+        .select(["tr.id", "tr.task_id", "tr.trial"])
+        .where("r.id", "=", runId)
+        .executeTakeFirst();
+    return row ? { taskRunId: row.id, taskId: row.task_id, trial: row.trial } : null;
+}
+/**
+ * The `scheduled_task_run_id` a new run whose boundary (`runs.trigger_seq`) is event `seq` of
+ * `conversationId` gets (scheduled tasks spec §4), read in the caller's transaction:
+ * - a `user_message`: its schedule marker's task run; a sub-agent's task or `SendMessage` message
+ *   (`dispatch`): what its parent run has; a person's message: null;
+ * - a `background_task_finished`: what the run that launched the task has;
+ * - a `subagent_delivery`: what the child run that delivered it has (it inherited from its parent);
+ * - anything else, or no such event: null.
+ */
+export async function scheduledTaskRunAt(t, conversationId, seq) {
+    const ev = await t
+        .selectFrom("conversation_events")
+        .select(["type", "payload"])
+        .where("conversation_id", "=", conversationId)
+        .where("seq", "=", String(seq))
+        .executeTakeFirst();
+    if (!ev)
+        return null;
+    const p = ev.payload;
+    let runId;
+    if (ev.type === "user_message") {
+        if (typeof p.schedule?.taskRunId === "string")
+            return p.schedule.taskRunId;
+        if (typeof p.dispatch?.parentRunId === "string")
+            runId = p.dispatch.parentRunId;
+    }
+    else if (ev.type === "background_task_finished" && typeof p.taskId === "string") {
+        const task = await t
+            .selectFrom("background_tasks")
+            .select("run_id")
+            .where("id", "=", p.taskId)
+            .where("conversation_id", "=", conversationId)
+            .executeTakeFirst();
+        runId = task?.run_id;
+    }
+    else if (ev.type === "subagent_delivery" && typeof p.childRunId === "string") {
+        runId = p.childRunId;
+    }
+    if (runId === undefined)
+        return null;
+    const run = await t
+        .selectFrom("runs")
+        .select("scheduled_task_run_id")
+        .where("id", "=", runId)
+        .executeTakeFirst();
+    return run?.scheduled_task_run_id ?? null;
+}
+/** The tool result of an ask outside the task's grants in an unattended run, `fail` mode (§7). */
+export const UNATTENDED_ASK_ERROR = (tool) => `This scheduled run cannot ask for approval; the task's owner can add ${tool} to the task's approved tools.`;
+/**
+ * The Platform operations that change an agent's skills: an unattended run never calls them
+ * without a person (spec §7), even where a private agent's owner would not be asked. Each is a
+ * fixed ask there, outside every grant.
+ */
+export const UNATTENDED_SKILL_OPERATIONS = new Set([
+    "agents.register-skill",
+    "agents.delete-skill",
+    "agents.share-skill",
+]);
+/** Whether a call's policy key (`Platform:<operation>`) is one of {@link UNATTENDED_SKILL_OPERATIONS}. */
+export function changesAgentSkills(policyKey) {
+    const prefix = "Platform:";
+    return (policyKey.startsWith(prefix) && UNATTENDED_SKILL_OPERATIONS.has(policyKey.slice(prefix.length)));
+}
+/**
+ * The result of a fixed ask (R3, `requiresUserInteraction`, a skill change unattended, a per-call
+ * policy that never remembers) in an unattended run, `fail` mode: no grant can ever cover it, so
+ * it is not a missing grant either.
+ */
+export const UNATTENDED_FIXED_ASK_ERROR = (tool) => `${tool} always needs a person's approval, which a scheduled run cannot ask for; state what you wanted to do in your final answer.`;
+/** The result of `AskUserQuestion` (or any other input request) in an unattended run, `fail` mode. */
+export const UNATTENDED_QUESTION_ERROR = "No one is present in this scheduled run; decide with the information you have, or state the open question in your final answer.";
+/** The result of a call that needs the creator's personal connection, unattended, `fail` mode. */
+export const UNATTENDED_CONNECTION_ERROR = (connector) => `This scheduled run cannot ask the user to connect ${connector}; the task's owner can connect it before the next run.`;
+/** The note on a connector call whose elicitation was declined in an unattended run (`fail`). */
+export const UNATTENDED_ELICITATION_NOTE = "[The app asked for user input, but no one is present in this scheduled run, so the request was declined. Decide with the information you have, or state the open question in your final answer.]";
+/** The `missing_grants` entry of a personal connector the creator has not connected (§7). */
+export const connectionGrantKey = (connectorSlug) => `connection:${connectorSlug}`;
+/** The `missing_grants` entry of a refused network host (network ask-to-allow spec §8.1, §8.3). */
+export const networkGrantKey = (host) => `network:${host}`;
+/** An unattended run that is not a trial run: the §7 rules apply. */
+export const unattendedRules = (u) => u !== null && u !== undefined && !u.trial;
+/** In `fail` mode, an unattended run never waits for a person (§7). */
+export const unattendedFails = (u) => unattendedRules(u) && u.unattendedAsk === "fail";
+/**
+ * Whether the task's creator joined the run (scheduled tasks rulings, Task 7 and Task 8): the run's
+ * conversation holds a `user_message` after the run's boundary (`trigger_seq`) that the creator
+ * wrote (no schedule marker, no sub-agent dispatch, `authorAccountId` = the task's account) and
+ * that the run already absorbed (at or below the `absorbedUpToSeq` of its latest model call). The
+ * rest of such a run is attended. Another person's message (someone replying in a group thread the
+ * task posted into) does not make it attended: the task's grants are the creator's, and only the
+ * creator is the one asked.
+ */
+async function personJoined(db, runId) {
+    const row = await db
+        .selectFrom("runs as r")
+        .innerJoin("scheduled_task_runs as tr", "tr.id", "r.scheduled_task_run_id")
+        .innerJoin("scheduled_tasks as st", "st.id", "tr.task_id")
+        .select(sql `EXISTS (
+        SELECT 1 FROM capybara.conversation_events u
+        WHERE u.conversation_id = r.conversation_id
+          AND u.type = 'user_message'
+          AND u.seq > r.trigger_seq
+          AND NOT (u.payload ? 'schedule')
+          AND NOT (u.payload ? 'dispatch')
+          AND u.payload->>'authorAccountId' = st.account_id
+          AND u.seq <= (
+            SELECT COALESCE((m.payload->'request'->>'absorbedUpToSeq')::bigint, m.seq)
+            FROM capybara.conversation_events m
+            WHERE m.conversation_id = r.conversation_id AND m.run_id = r.id
+              AND m.type = 'model_call'
+            ORDER BY m.seq DESC
+            LIMIT 1
+          )
+      )`.as("joined"))
+        .where("r.id", "=", runId)
+        .executeTakeFirst();
+    return row?.joined === true;
+}
+/**
+ * The scheduled task context of a run's tool calls (`PolicyContext.unattended`), or null when the
+ * run is attended: it serves no task run, or a person's message joined it ({@link personJoined}).
+ * A trial run is returned with `trial: true` (attended; its approvals become task grants).
+ */
+export async function unattendedRunOf(db, config, orgId, runId) {
+    const run = await unattendedTaskRunOf(db, runId);
+    if (run === null)
+        return null;
+    if (!run.trial && (await personJoined(db, runId)))
+        return null;
+    const s = await readScheduleSettings(db, config, orgId);
+    return { ...run, unattendedAsk: s.unattendedAsk, forbiddenTools: s.forbiddenTools };
+}
+/**
+ * The scheduled task whose grants a run's actions use (spec §7; network ask-to-allow spec §8.1),
+ * or null: the run serves a task run that is no trial run and no person joined
+ * ({@link personJoined}): the same rule as {@link unattendedRules} on {@link unattendedRunOf},
+ * without the org's settings. `accountId`: the task's creator; `orgId`: the task's org.
+ */
+export async function taskGrantsRunOf(db, runId) {
+    const run = await unattendedTaskRunOf(db, runId);
+    if (run === null || run.trial)
+        return null;
+    if (await personJoined(db, runId))
+        return null;
+    const task = await db
+        .selectFrom("scheduled_tasks")
+        .select(["id", "account_id", "org_id"])
+        .where("id", "=", run.taskId)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    return task ? { taskId: task.id, accountId: task.account_id, orgId: task.org_id } : null;
+}
+/**
+ * Appends a key to a task run's `missing_grants` (a tool key, or `connection:<slug>`), once: one
+ * atomic update, so parallel calls of a run and of its sub-agents never lose or repeat a key.
+ */
+export async function appendMissingGrant(db, taskRunId, key) {
+    await db
+        .updateTable("scheduled_task_runs")
+        .set({
+        missing_grants: sql `CASE WHEN missing_grants ? ${key} THEN missing_grants
+        ELSE missing_grants || jsonb_build_array(${key}::text) END`,
+    })
+        .where("id", "=", taskRunId)
+        .execute();
+}
+/**
+ * The task grant that lets an unattended run use the open sandbox tier (sandbox dev tiers spec
+ * §11.4): without it a run of a scheduled task is capped at `dev` on a local device, and refused
+ * on an unsandboxed local device or a cloud device whose tier is open.
+ */
+export const TIER_OPEN_GRANT_KEY = "tier:open";
+/** The `spec_hash` the `tier:open` grant is stored with (no tool definition behind it). */
+export const TIER_GRANT_SPEC_HASH = "tier";
+/**
+ * The tier rule of an unattended run on `deviceId` (spec §11.4), or null when the run is attended
+ * (no task run, a trial run, or a person joined: the same rule as {@link taskGrantsRunOf}).
+ * `openGranted`: the task holds the `tier:open` grant and `deviceId` is a live device of the task's
+ * org owned by its creator (a creator approves for their own devices only, as with network
+ * grants). A deleted task grants nothing.
+ */
+export async function unattendedTierOf(db, runId, deviceId) {
+    const run = await unattendedTaskRunOf(db, runId);
+    if (run === null || run.trial)
+        return null;
+    if (await personJoined(db, runId))
+        return null;
+    const granted = await db
+        .selectFrom("scheduled_task_grants as g")
+        .innerJoin("scheduled_tasks as st", "st.id", "g.task_id")
+        .innerJoin("devices as d", (j) => j.onRef("d.org_id", "=", "st.org_id").onRef("d.owner_account_id", "=", "st.account_id"))
+        .select("g.task_id")
+        .where("g.task_id", "=", run.taskId)
+        .where("g.tool_key", "=", TIER_OPEN_GRANT_KEY)
+        .where("st.deleted_at", "is", null)
+        .where("d.id", "=", deviceId)
+        .where("d.deleted_at", "is", null)
+        .executeTakeFirst();
+    return { taskRunId: run.taskRunId, taskId: run.taskId, openGranted: granted !== undefined };
+}
+/**
+ * The tool error of a scheduled run on a device whose tier is open (cloud) without the task's
+ * `tier:open` grant (spec §11.4).
+ */
+export const UNATTENDED_OPEN_TIER_ERROR = "This device's sandbox level is open, which a scheduled run may use only when its task allows the open sandbox level; the task's owner can add tier:open to the task's approved tools, or lower the device's sandbox level.";
+/**
+ * The tool error of a scheduled run on a device that runs commands without a sandbox, without
+ * the task's `tier:open` grant (spec §11.4).
+ */
+export const UNATTENDED_UNSANDBOXED_ERROR = "This device runs commands without a sandbox, which a scheduled run may use only when its task allows the open sandbox level; the task's owner can add tier:open to the task's approved tools, or the device's owner can turn the sandbox back on with `capybara-device policy set isolation sandbox`.";

package/dist/setup/oauth-token-probe.js

@@ -7,14 +7,18 @@ export const PROBE_CODE = "capybara-setup-probe";
 const PROBE_VERIFIER = "capybara-setup-probe-verifier-0000000000000";
 /** The most of a token endpoint answer the probe reads (an error body is a few hundred bytes). */
 const PROBE_MAX_BYTES = 64 * 1024;
-/** Codes that say the client authenticated and only the code was bad, as intended. */
-const ACCEPTED = new Set(["invalid_grant", "invalid_code"]);
-/** Codes that say the client id or secret is wrong (RFC 6749 and Slack's). */
+/**
+ * Codes that say the client authenticated and only the code was bad, as intended (RFC 6749,
+ * Slack's `invalid_code`, GitHub's `bad_verification_code`).
+ */
+const ACCEPTED = new Set(["invalid_grant", "invalid_code", "bad_verification_code"]);
+/** Codes that say the client id or secret is wrong (RFC 6749, Slack's and GitHub's). */
 const CLIENT_REFUSED = new Set([
     "invalid_client",
     "unauthorized_client",
     "invalid_client_id",
     "bad_client_secret",
+    "incorrect_client_credentials",
 ]);
 /** Codes that say the redirect URI is not registered (RFC 6749 servers and Slack's). */
 const REDIRECT_REFUSED = new Set(["redirect_uri_mismatch", "bad_redirect_uri"]);
@@ -23,7 +27,7 @@ const text = (en, zh) => ({ en, zh });
 export const PROBE_TEXTS = {
     accepted: text("The token endpoint accepted the client.", "令牌端点接受了这个客户端。"),
     clientRefused: text("The token endpoint refused the client id or secret.", "令牌端点拒绝了客户端 ID 或密钥。"),
-    clientFix: text("Copy the Client ID and Client Secret again from the app's Basic Information page.", "从应用的 Basic Information 页面重新复制 Client ID 和 Client Secret。"),
+    clientFix: text("Copy the client ID and client secret again from the app's settings page.", "从应用的设置页面重新复制 Client ID 和 Client Secret。"),
     redirectRefused: text("The app does not list the callback URL.", "应用的重定向地址里没有这个回调地址。"),
     unknown: text("Could not verify the client; retry later.", "无法验证这个客户端，请稍后重试。"),
     netDenied: text("The token endpoint's address is refused by this deployment's network rules; ask your super admin.", "这个部署的网络规则拒绝访问令牌端点的地址，请联系超级管理员。"),

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

@@ -71,11 +71,6 @@ export declare function shareSkillIn(db: KernelDb, v: {
     agentId: string;
     maintainerAccountId: string;
 }): Promise<void>;
-/** The body of a skill's SKILL.md (as run start would read it); null if unparsable. */
-export declare function skillMdBody(files: readonly {
-    path: string;
-    data: Uint8Array;
-}[]): string | null;
 /**
  * Takes a KEY SHARE lock on the org row before the agent row is locked: the order `AgentsService`
  * uses (org row FOR UPDATE -> agent row). Without it, a transaction holding the agent row that
@@ -238,9 +233,10 @@ export declare class AgentSkillsService {
     /** The transaction of {@link register}. */
     private registerIn;
     /**
-     * Spec §5.2: an agent's own skill may not take the name of an org skill the agent uses (selected
-     * in its current definition, or one it shared) unless the actor maintains it (then the
-     * registration is a version of it): 409 `skill.name_exists`.
+     * Spec §5.2: an agent's own skill may not take the name of an org skill the agent uses (one it
+     * has on: every org skill its current definition does not turn off, skills default-on spec §3,
+     * and the ones it shared) unless the actor maintains it (then the registration is a version of
+     * it): 409 `skill.name_exists`.
      */
     private assertNoUsedOrgSkillNamed;
     /**

package/dist/skills/agent-skills.service.js

@@ -8,10 +8,10 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 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 { visibleTo } from "../agents/agent-lookup.js";
+import { normalizeStoredDefinition } from "../agents/definition.js";
 import { offeredNamed } from "../catalog/component-state.js";
 import { AttachmentsService, SKILL_PACKAGE_CONTENT_TYPE, skillFilesPrefix, } from "../conversations/attachments.service.js";
 import { EventLog } from "../conversations/event-log.js";
@@ -29,6 +29,7 @@ import { invocationOf } from "./catalog.js";
 import { appendConversationCatalog, cancelRequestIn, } from "./conversation-catalog.js";
 import { readSkillPackage, skillManifest, } from "./package.js";
 import { SkillsService } from "./skills.service.js";
+import { agentSkills } from "./usable.js";
 /**
  * The cap on an agent's own skills (`scope = agent`). Far below the catalog snapshot's cap
  * (`SKILLS_CATALOG_MAX`), so normal use never truncates the catalog. Requests never add agent
@@ -90,8 +91,8 @@ export async function shareSkillIn(db, v) {
 }
 /**
  * The catalog snapshot `base` with skill `name` replaced by the version just written or proposed
- * (`source` = its prefix), or removed when that version is manual-only. A pinned entry of the
- * skill gets the new version, source and body; a manual-only version drops it (no longer live).
+ * (`source` = its prefix), or removed when that version is manual-only. Pinned skills of an old
+ * snapshot are not carried (skills default-on spec §8).
  */
 function withVersion(base, v) {
     return {
@@ -110,32 +111,8 @@ function withVersion(base, v) {
                 ]
                 : []),
         ],
-        ...(base.pinned && {
-            pinned: base.pinned.map((p) => p.id === v.skillId && v.pinnedBody !== null
-                ? {
-                    id: v.skillId,
-                    version: v.version,
-                    name: v.name,
-                    source: v.source,
-                    body: v.pinnedBody,
-                }
-                : p),
-        }),
     };
 }
-/** The body of a skill's SKILL.md (as run start would read it); null if unparsable. */
-export function skillMdBody(files) {
-    const md = files.find((f) => f.path === SKILL_ENTRY_FILE);
-    if (!md)
-        return null;
-    try {
-        const parsed = parseSkillMd(new TextDecoder("utf-8", { fatal: true }).decode(md.data));
-        return "errors" in parsed ? null : parsed.body;
-    }
-    catch {
-        return null;
-    }
-}
 /**
  * Takes a KEY SHARE lock on the org row before the agent row is locked: the order `AgentsService`
  * uses (org row FOR UPDATE -> agent row). Without it, a transaction holding the agent row that
@@ -539,7 +516,6 @@ let AgentSkillsService = class AgentSkillsService {
             .executeTakeFirst();
         if (!v)
             return null;
-        const pinnedBody = skillMdBody(pkg.files);
         return appendConversationCatalog(this.catalogDeps, conversationId, (base) => withVersion(base, {
             skillId: out.skill.id,
             name: pkg.name,
@@ -547,7 +523,6 @@ let AgentSkillsService = class AgentSkillsService {
             version: out.version,
             source: v.object_prefix,
             forModel,
-            pinnedBody,
         }), `skills_catalog:register:${v.object_prefix}`, actor.runId);
     }
     /**
@@ -644,7 +619,6 @@ let AgentSkillsService = class AgentSkillsService {
         if (actor.conversationId !== undefined) {
             // The conversation sees the new version at once: this skill replaced / added in its latest
             // snapshot (source = this version's prefix)
-            const pinnedBody = skillMdBody(pkg.files);
             toSeq = await appendConversationCatalog(this.catalogDeps, actor.conversationId, (base) => withVersion(base, {
                 skillId,
                 name: pkg.name,
@@ -652,7 +626,6 @@ let AgentSkillsService = class AgentSkillsService {
                 version,
                 source: prefix,
                 forModel,
-                pinnedBody,
             }), `skills_catalog:register:${prefix}`, actor.runId);
         }
         return {
@@ -669,9 +642,10 @@ let AgentSkillsService = class AgentSkillsService {
         };
     }
     /**
-     * Spec §5.2: an agent's own skill may not take the name of an org skill the agent uses (selected
-     * in its current definition, or one it shared) unless the actor maintains it (then the
-     * registration is a version of it): 409 `skill.name_exists`.
+     * Spec §5.2: an agent's own skill may not take the name of an org skill the agent uses (one it
+     * has on: every org skill its current definition does not turn off, skills default-on spec §3,
+     * and the ones it shared) unless the actor maintains it (then the registration is a version of
+     * it): 409 `skill.name_exists`.
      */
     async assertNoUsedOrgSkillNamed(actor, name) {
         const def = await this.db
@@ -682,23 +656,16 @@ let AgentSkillsService = class AgentSkillsService {
             .select("agent_versions.definition")
             .where("agents.id", "=", actor.agentId)
             .executeTakeFirst();
-        const selected = def?.definition?.skills
-            ?.orgSkills;
-        const ids = Array.isArray(selected)
-            ? selected.filter((x) => typeof x === "string")
-            : [];
-        const used = await this.db
-            .selectFrom("skills")
-            .select("id")
-            .where("org_id", "=", actor.orgId)
-            .where("scope", "=", "org")
-            .where("name", "=", name)
-            .where("deleted_at", "is", null)
-            .where((eb) => eb.or([
-            eb("origin_agent_id", "=", actor.agentId),
-            ...(ids.length > 0 ? [eb("id", "in", ids)] : []),
-        ]))
-            .executeTakeFirst();
+        const disabledSkills = def === undefined ? [] : (normalizeStoredDefinition(def.definition).disabledSkills ?? []);
+        const used = (await agentSkills(this.db.db, {
+            orgId: actor.orgId,
+            agentId: actor.agentId,
+            disabledSkills,
+        })).find((r) => r.scope === "org" &&
+            r.name === name &&
+            // an org skill, or the org's copy linked to a platform skill (listed under the copy's id);
+            // a platform skill itself is not the org's to clash with
+            (r.origin === "org" || (r.platformSkillId !== undefined && r.id !== r.platformSkillId)));
         if (used) {
             throw new ApiError("skill.name_exists", `This agent uses the org skill "${name}", which only its maintainer can update; register the package under another name, or ask the skill's maintainer.`);
         }
@@ -780,7 +747,6 @@ let AgentSkillsService = class AgentSkillsService {
         const forModel = invocationOf(manifest).model;
         let toSeq = null;
         if (actor.conversationId !== undefined) {
-            const pinnedBody = skillMdBody(pkg.files);
             toSeq = await appendConversationCatalog(this.catalogDeps, actor.conversationId, (base) => withVersion(base, {
                 skillId: shared.id,
                 name: pkg.name,
@@ -788,7 +754,6 @@ let AgentSkillsService = class AgentSkillsService {
                 version,
                 source: prefix,
                 forModel,
-                pinnedBody,
             }), `skills_catalog:propose:${prefix}`, actor.runId);
         }
         return {

package/dist/skills/catalog.d.ts

@@ -1,33 +1,24 @@
-import { type Logger, type SkillInvocation } from "@capybara-hq/plugin-sdk";
+import type { Logger, SkillInvocation } from "@capybara-hq/plugin-sdk";
 import type { AgentDefinition } from "../agents/definition.js";
 import { EventLog } from "../conversations/event-log.js";
 import { type ConversationEvent } from "../conversations/events.js";
 import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.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 type { KernelLogger } from "../log.js";
-import { type CatalogSkill, type PinnedSkill, type SkillsSnapshot } from "../runtime/context/skills.js";
-import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
+import { type CatalogSkill, type SkillsSnapshot } from "../runtime/context/skills.js";
+import { type SkillVersionRow, type UsableSkill } 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 declare const PINNED_SKILLS_LIMITS: {
-    readonly count: 3;
-    readonly totalBytes: 32768;
-};
 /** {@link resolveEffectiveSkills} 的输入。 */
 export interface EffectiveSkillsInput {
     orgId: string;
     agentId: string;
-    /** 本次运行固定的 agent 版本的定义（`skills.orgSkills` 是选中的组织技能 id）。 */
-    agent: Pick<AgentDefinition, "skills">;
+    /** The definition of the run's agent version (`disabledSkills`: what it turns off). */
+    agent: Pick<AgentDefinition, "disabledSkills">;
     /**
      * The conversation id: a pending skill change of the agent (`skill_change_requests`, a version
      * draft) applies only in the conversation that proposed it (a trial) and is overlaid here.
@@ -35,12 +26,15 @@ export interface EffectiveSkillsInput {
     conversationId: string;
 }
 /**
- * 此刻对这个对话生效的技能，按名字（码点序）排序：
- * - 运行所用 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
@@ -58,6 +52,13 @@ export interface ResolvedSkill {
     format: SourceFormat;
     /** Its version's file manifest (a trial draft's proposed one). */
     manifest: SkillManifest;
+    /**
+     * Where it comes from, for the catalog budget's ranking: `scope` `agent` is the agent's own
+     * skill, `origin` `platform` a platform skill (or an org copy linked to one). A trial draft takes
+     * the entry it replaces (an agent's own skill when it replaces none).
+     */
+    scope: SkillVersionRow["scope"];
+    origin: UsableSkill["origin"];
 }
 /**
  * Every effective skill with its format and manifest, sorted by name, manual-only versions
@@ -67,43 +68,42 @@ export interface ResolvedSkill {
 export declare function resolveSkills(db: KernelSchemaDb, input: Omit<EffectiveSkillsInput, "conversationId"> & {
     conversationId?: string;
 }, log?: Pick<Logger, "warn">): Promise<ResolvedSkill[]>;
-/** A pinned skill to read: an effective skill the agent version pins. */
-interface PinnedCandidate {
-    id: string;
-    version: number;
-    name: string;
-    source: string;
-    manifest: SkillManifest;
-}
 /**
- * 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 rank of a skill in the catalog budget (skills default-on spec §7): 0 the agent's own skills
+ * (and the org skills it shared), 1 builtin skills, 2 the org's own skills (no plugin), 3 plugin
+ * skills.
  */
-export declare function pinnedFailureText(e: ApiError): string;
+export type BudgetTier = 0 | 1 | 2 | 3;
 /**
- * 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).
+ * 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.
  */
-export declare function loadPinnedBodies(storage: PrefixedStorage, orgId: string, pinned: readonly PinnedCandidate[], opts?: {
-    signal?: AbortSignal;
-    log?: Pick<Logger, "error">;
-}): Promise<PinnedSkill[]>;
+export declare function budgetTier(r: Pick<ResolvedSkill, "skill" | "scope" | "origin">, known: {
+    plugins: ReadonlySet<string>;
+    ids: ReadonlySet<string>;
+    shared: ReadonlySet<string>;
+}): BudgetTier;
+/** The characters a described entry takes in the listing: its line and the line break. */
+export declare const catalogLineChars: (s: Pick<CatalogSkill, "name" | "description">) => number;
+/** What {@link applyCatalogBudget} decided. */
+export interface CatalogBudgetResult {
+    /** The entries in their input order, those past the budget with `nameOnly: true`. */
+    skills: CatalogSkill[];
+    /** The characters every entry's described line would take ({@link catalogLineChars}). */
+    characters: number;
+    /** How many entries are name-only (0: everything fits). */
+    nameOnly: number;
+}
 /**
- * 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).
+ * 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 declare function fitPinned(pinned: readonly PinnedSkill[], log: Pick<Logger, "warn"> | undefined, input: Partial<Pick<EffectiveSkillsInput, "orgId" | "agentId" | "conversationId">>): PinnedSkill[];
+export declare function applyCatalogBudget(skills: readonly CatalogSkill[], budget: number, tierOf: () => Promise<(s: CatalogSkill) => BudgetTier>): Promise<CatalogBudgetResult>;
 /** `skills_catalog` 的幂等键：每次运行最多写一份。 */
 /**
  * 是否给模型 `Skill`：日志里有过技能目录快照（Ruling M17），**即使最新一份是空的**。构建请求与执行工具调用
@@ -136,20 +136,24 @@ export declare function lockLatestCatalog(db: KernelSchemaDb, conversationId: st
  * 解析、比较、追加在一个事务里、先锁会话行：否则在解析与追加之间提交的拒绝 + 回退快照会被过时的草稿条目盖回去。
  * 解析只读 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.
  */
 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);
+    private readonly config;
+    constructor(db: KernelDb, eventLog: EventLog, log: KernelLogger, txHost: TransactionHost, config: KernelConfigService);
     /**
      * Records the run start's snapshot (see the class comment). `opts.log`: the run's logger
      * (default the kernel logger).
@@ -159,7 +163,6 @@ export declare class SkillsCatalogService {
     }, opts?: {
         log?: Pick<Logger, "warn" | "error">;
     }): Promise<void>;
-    /** Step (2) of {@link record}: under the conversation row lock, resolve again and append. */
+    /** Under the conversation row lock, resolves the skills and appends a changed snapshot. */
     private append;
 }
-export {};