@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { InvocableSkill, SkillInvoker } from "./invoke.js";
+declare const ListQuery: z.ZodObject<{
+    conversationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The composer's `/` menu (phase D spec §4.5): `GET /api/v1/orgs/:orgId/agents/:agentId/
+ * invocable-skills?conversationId=` lists the agent's effective skills a person can invoke, sorted
+ * by name. Agent-scoped because a conversation is created on its first send. People only
+ * (`agents.use`, human principals: invocations are sent from a conversation); an agent the caller
+ * cannot use → 404 `agent.not_found`; a `conversationId` that is not the caller's conversation with
+ * this agent → 404 `conversation.not_found` (with it, that conversation's trial drafts apply).
+ */
+export declare class InvocableSkillsController {
+    private readonly invoker;
+    constructor(invoker: SkillInvoker);
+    list(principal: Principal, org: OrgContext, agentId: string, q: z.infer<typeof ListQuery>): Promise<{
+        skills: InvocableSkill[];
+    }>;
+}
+export {};

package/dist/skills/invocable.controller.js

@@ -0,0 +1,50 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Header, Inject, Param, Query } from "@nestjs/common";
+import { z } from "zod";
+import { SKILL_INVOKER } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+const ListQuery = z.object({ conversationId: z.string().min(1).max(100).optional() }).strict();
+/**
+ * The composer's `/` menu (phase D spec §4.5): `GET /api/v1/orgs/:orgId/agents/:agentId/
+ * invocable-skills?conversationId=` lists the agent's effective skills a person can invoke, sorted
+ * by name. Agent-scoped because a conversation is created on its first send. People only
+ * (`agents.use`, human principals: invocations are sent from a conversation); an agent the caller
+ * cannot use → 404 `agent.not_found`; a `conversationId` that is not the caller's conversation with
+ * this agent → 404 `conversation.not_found` (with it, that conversation's trial drafts apply).
+ */
+let InvocableSkillsController = class InvocableSkillsController {
+    invoker;
+    constructor(invoker) {
+        this.invoker = invoker;
+    }
+    async list(principal, org, agentId, q) {
+        const p = requireUser(principal);
+        return {
+            skills: await this.invoker.listFor(org.orgId, agentId, p.account.id, q.conversationId),
+        };
+    }
+};
+__decorate([
+    Get(),
+    Header("cache-control", "private, no-store"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Query(new ZodPipe(ListQuery)))
+], InvocableSkillsController.prototype, "list", null);
+InvocableSkillsController = __decorate([
+    Controller("api/v1/orgs/:orgId/agents/:agentId/invocable-skills"),
+    __param(0, Inject(SKILL_INVOKER))
+], InvocableSkillsController);
+export { InvocableSkillsController };

package/dist/skills/invocation-keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The SKILL.md invocation keys (package ecosystem phase D) and their lenient reading: readers of
+ * stored files (catalog install and upgrade) and the Claude Code translation drop a key the strict
+ * `parseSkillMd` checks would refuse, with the reason, instead of refusing the skill or storing an
+ * invocation nobody can use. Uploads, native imports and `skill_write` stay strict.
+ */
+/** The frontmatter keys that make up a skill's invocation metadata. */
+export declare const INVOCATION_KEYS: readonly ["disable-model-invocation", "user-invocable", "context", "agent", "argument-hint", "arguments"];
+/** One dropped key (or `a, b` for a pair) and the strict check's reason (English). */
+export interface DroppedInvocationKey {
+    key: string;
+    problem: string;
+}
+/**
+ * The frontmatter without the invocation keys the strict checks refuse (each checked on its own by
+ * `parseSkillMd`, so the rules stay in one place), and what was dropped. When both
+ * `disable-model-invocation: true` and `user-invocable: false` remain, both go: the skill is then an
+ * ordinary one, as it was before phase D. Other keys are untouched.
+ */
+export declare function cleanInvocationKeys(fm: Readonly<Record<string, unknown>>): {
+    frontmatter: Record<string, unknown>;
+    dropped: DroppedInvocationKey[];
+};

package/dist/skills/invocation-keys.js

@@ -0,0 +1,44 @@
+import { parseSkillMd } from "@capybara-hq/plugin-sdk";
+/**
+ * The SKILL.md invocation keys (package ecosystem phase D) and their lenient reading: readers of
+ * stored files (catalog install and upgrade) and the Claude Code translation drop a key the strict
+ * `parseSkillMd` checks would refuse, with the reason, instead of refusing the skill or storing an
+ * invocation nobody can use. Uploads, native imports and `skill_write` stay strict.
+ */
+/** The frontmatter keys that make up a skill's invocation metadata. */
+export const INVOCATION_KEYS = [
+    "disable-model-invocation",
+    "user-invocable",
+    "context",
+    "agent",
+    "argument-hint",
+    "arguments",
+];
+const NOBODY = "a skill with disable-model-invocation: true and user-invocable: false cannot be used";
+/**
+ * The frontmatter without the invocation keys the strict checks refuse (each checked on its own by
+ * `parseSkillMd`, so the rules stay in one place), and what was dropped. When both
+ * `disable-model-invocation: true` and `user-invocable: false` remain, both go: the skill is then an
+ * ordinary one, as it was before phase D. Other keys are untouched.
+ */
+export function cleanInvocationKeys(fm) {
+    const frontmatter = { ...fm };
+    const dropped = [];
+    for (const key of INVOCATION_KEYS) {
+        const value = frontmatter[key];
+        if (value === undefined)
+            continue;
+        const probe = JSON.stringify({ name: "x", description: "x", [key]: value });
+        const r = parseSkillMd(`---\n${probe}\n---\n`);
+        if ("errors" in r) {
+            dropped.push({ key, problem: r.errors.join("; ") });
+            delete frontmatter[key];
+        }
+    }
+    if (frontmatter["disable-model-invocation"] === true && frontmatter["user-invocable"] === false) {
+        delete frontmatter["disable-model-invocation"];
+        delete frontmatter["user-invocable"];
+        dropped.push({ key: "disable-model-invocation, user-invocable", problem: NOBODY });
+    }
+    return { frontmatter, dropped };
+}

package/dist/skills/invoke.d.ts

@@ -0,0 +1,135 @@
+import { type Logger } from "@capybara-hq/plugin-sdk";
+import type { AgentsService } from "../agents/agents.service.js";
+import type { AgentDefinition } from "../agents/definition.js";
+import type { EventPayload } from "../conversations/events.js";
+import type { KernelDb } from "../db/kernel-schema.js";
+import { ApiError } from "../errors.js";
+import type { StorageService } from "../storage/storage.service.js";
+/**
+ * A person's skill invocation (phase D spec §3, §4): the `/` menu's list of the agent's invocable
+ * skills, and the rendering of `/name args` into the model-visible text of their message. The skill
+ * is resolved among the agent's effective skills **at send time** (its current version, the
+ * conversation's trial drafts), its SKILL.md is read from object storage and checked against the
+ * manifest, and it is rendered by the SDK; nothing is executed (A1). The caller appends the text as
+ * `content[0]` of the `user_message` together with {@link RenderedInvocation.skill}.
+ */
+/** One skill of the `/` menu (`GET …/agents/:agentId/invocable-skills`). */
+export interface InvocableSkill {
+    id: string;
+    name: string;
+    /** The plugin (catalog item) it came from. */
+    plugin?: string;
+    description: string;
+    version: number;
+    argumentHint?: string;
+    arguments?: string[];
+    /** Manual-only: not in the model's catalog. */
+    manual: boolean;
+    /** Runs as a sub-agent when a person invokes it. */
+    fork: boolean;
+}
+/** The `skill` field of a `user_message`. */
+export type InvocationRecord = NonNullable<EventPayload<"user_message">["skill"]>;
+/** The result of {@link SkillInvoker.prepare}. */
+export interface RenderedInvocation {
+    /** The model-visible text of the person's message (`content[0]`). */
+    text: string;
+    skill: InvocationRecord;
+    /**
+     * Fork only: the rendered skill without the lead sentence (the sub-agent's task). Checks the
+     * size at send time; the dispatch renders it again from the record ({@link SkillInvoker.renderTask}).
+     */
+    task?: string;
+    /** Fork only: the requested sub-agent type did not resolve (recorded at dispatch, §6.2). */
+    warning?: string;
+}
+/** `/name args` at the very start of a message, or null (`/etc/hosts`, ` /x`, `/Upper`). */
+export declare const parseSlashCommand: (text: string) => {
+    name: string;
+    args: string;
+} | null;
+/** Why a person cannot invoke a skill (`skill.not_invocable` details). */
+export type NotInvocableReason = "not_found" | "not_user_invocable";
+export declare const notInvocable: (reason: NotInvocableReason, name: string) => ApiError;
+/**
+ * Whether the skill a queued invocation recorded is still one a person can invoke in this
+ * conversation (phase D Task 9, checked again at dispatch): the same skill (by id) among the
+ * agent's effective skills now, with `user` not false. Its version may have changed: the queued
+ * text stays as rendered when queued. Null when it is, else the reason.
+ */
+export declare function recordedSkillBlocked(db: KernelDb, a: {
+    orgId: string;
+    agentId: string;
+    agent: Pick<AgentDefinition, "skills">;
+    conversationId: string;
+    skillId: string;
+}): Promise<NotInvocableReason | null>;
+/** The model-visible text of a fork invocation in the parent's log (spec §6.3, frozen). */
+export declare const forkLeadText: (name: string, agentType: string, args: string) => string;
+/** The warning recorded when a forked skill's `agent` does not resolve (spec §6.2). */
+export declare const forkAgentUnknownText: (name: string, agent: string) => string;
+export interface SkillInvokerDeps {
+    db: KernelDb;
+    storage: StorageService;
+    /** For {@link SkillInvoker.listFor} (the HTTP route's access check). */
+    agents?: Pick<AgentsService, "get">;
+    /** An unreadable SKILL.md is logged at `error` (skill id, version, source), as pinned skills. */
+    log?: Pick<Logger, "error">;
+}
+export declare class SkillInvoker {
+    private readonly d;
+    constructor(d: SkillInvokerDeps);
+    /**
+     * The `/` menu for `accountId`: the agent must be usable by them (`agent.not_found`), and with
+     * `conversationId` the conversation must be theirs and the agent's (`conversation.not_found`);
+     * then its trial drafts apply.
+     */
+    listFor(orgId: string, agentId: string, accountId: string, conversationId?: string): Promise<InvocableSkill[]>;
+    /**
+     * The agent's effective skills a person can invoke (`user` not false), sorted by name (code
+     * point order), model-invocable and manual-only alike (spec §3.1).
+     */
+    list(a: {
+        orgId: string;
+        agentId: string;
+        agent: Pick<AgentDefinition, "skills">;
+        conversationId?: string;
+    }): Promise<InvocableSkill[]>;
+    /**
+     * Resolves `name` among the agent's effective skills now, reads its SKILL.md and renders the
+     * invocation (spec §4.2, §4.3, §6.3). Refusals: `skill.not_invocable` (400); arguments or a
+     * rendered text over the limits → `validation_failed` (400); a storage failure or a SKILL.md
+     * that fails its integrity check → `storage.unavailable` (503). Nothing is written here.
+     */
+    prepare(a: {
+        orgId: string;
+        agentId: string;
+        /** Absent for the first message of a conversation not created yet. */
+        conversationId?: string;
+        agent: AgentDefinition;
+        name: string;
+        args: string;
+    }): Promise<RenderedInvocation>;
+    /**
+     * The task of a fork invocation's sub-agent (spec §6.2), rendered at dispatch from the version
+     * the person's message recorded (`skill.{id, source, version, arguments}`), never by name, so a
+     * skill changed since the send cannot run another version than the frozen lead names (batch 2
+     * review m4). The same `<skill_invocation>` text as the inline form without the lead sentence.
+     * `warning`: the skill asked for a sub-agent type that did not resolve (the recorded `agentType`
+     * is `general-purpose` for an `agent` other than Claude's built-in types). Throws
+     * `storage.unavailable` (`skill_unreadable`) when the version is gone or its SKILL.md cannot be
+     * read, plain `storage.unavailable` when storage is down. `task` renders the text for the
+     * sub-agent's effective definition: the shell-injection line only when the sub-agent has
+     * `sandbox_bash` (batch 3 review m1).
+     */
+    renderTask(a: {
+        orgId: string;
+        conversationId: string;
+        skill: InvocationRecord;
+    }): Promise<{
+        task: (child: Pick<AgentDefinition, "tools">) => string;
+        warning?: string;
+    }>;
+    /** Reads and parses the version's SKILL.md (checked against the manifest), returns the body. */
+    private readBody;
+}

package/dist/skills/invoke.js

@@ -0,0 +1,286 @@
+import { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+import { isGeneralAlias, resolveSkillForkType } from "../runtime/subagents/roster.js";
+import { findSkillVersion, readSkillFile, SkillIntegrityError, } from "../tools/builtins/skill-load.js";
+import { invocationOf, resolveSkills } from "./catalog.js";
+/** A leading `/<name>` or `/<plugin>:<name>`, then whitespace or the end (spec §3.2). */
+const SLASH_COMMAND_RE = /^\/([a-z0-9-]+(?::[a-z0-9-]+)?)(?:\s|$)/;
+/** `/name args` at the very start of a message, or null (`/etc/hosts`, ` /x`, `/Upper`). */
+export const parseSlashCommand = (text) => {
+    const m = SLASH_COMMAND_RE.exec(text);
+    if (!m)
+        return null;
+    return { name: m[1], args: text.slice(m[0].length).trim() };
+};
+/** A Claude Code style qualified name `<plugin>:<skill>`. */
+const QUALIFIED_RE = /^([a-z0-9][a-z0-9-]{0,63}):(.+)$/;
+/** The effective skill `name` names: exactly, or `<plugin>:<name>` for a plugin's skill. */
+function findSkill(all, name) {
+    const exact = all.find((r) => r.skill.name === name);
+    if (exact)
+        return exact;
+    const m = QUALIFIED_RE.exec(name);
+    if (!m)
+        return undefined;
+    return all.find((r) => r.skill.name === m[2] && r.skill.plugin === m[1]);
+}
+export const notInvocable = (reason, name) => new ApiError("skill.not_invocable", reason === "not_found"
+    ? `Skill "${name}" is not one of this agent's skills`
+    : `Skill "${name}" cannot be invoked by a person`, [{ reason }]);
+/**
+ * Whether the skill a queued invocation recorded is still one a person can invoke in this
+ * conversation (phase D Task 9, checked again at dispatch): the same skill (by id) among the
+ * agent's effective skills now, with `user` not false. Its version may have changed: the queued
+ * text stays as rendered when queued. Null when it is, else the reason.
+ */
+export async function recordedSkillBlocked(db, a) {
+    const found = (await resolveSkills(db, a)).find((r) => r.skill.id === a.skillId);
+    if (!found)
+        return "not_found";
+    return invocationOf(found.manifest).user ? null : "not_user_invocable";
+}
+/** The model-visible text of a fork invocation in the parent's log (spec §6.3, frozen). */
+export const forkLeadText = (name, agentType, args) => escapeSkillInvocationTags(`The user ran the skill "${name}" in a sub-agent (${agentType}) with /${name}${args === "" ? "" : ` ${args}`}. The sub-agent gets the skill's instructions as its task; its report follows. Do not do the task yourself.`);
+/** The warning recorded when a forked skill's `agent` does not resolve (spec §6.2). */
+export const forkAgentUnknownText = (name, agent) => `Skill "${name}" asked for sub-agent type "${agent}", which this agent does not have; it ran as general-purpose.`;
+export class SkillInvoker {
+    d;
+    constructor(d) {
+        this.d = d;
+    }
+    /**
+     * The `/` menu for `accountId`: the agent must be usable by them (`agent.not_found`), and with
+     * `conversationId` the conversation must be theirs and the agent's (`conversation.not_found`);
+     * then its trial drafts apply.
+     */
+    async listFor(orgId, agentId, accountId, conversationId) {
+        if (!this.d.agents)
+            throw new Error("SkillInvoker.listFor needs agents");
+        const agent = await this.d.agents.get(orgId, agentId, accountId);
+        if (conversationId !== undefined) {
+            const row = await this.d.db
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "=", conversationId)
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", accountId)
+                .where("agent_id", "=", agentId)
+                .where("kind", "=", "chat")
+                .executeTakeFirst();
+            if (!row)
+                throw new ApiError("conversation.not_found", "Conversation not found");
+        }
+        return this.list({
+            orgId,
+            agentId,
+            agent: agent.definition,
+            ...(conversationId !== undefined && { conversationId }),
+        });
+    }
+    /**
+     * The agent's effective skills a person can invoke (`user` not false), sorted by name (code
+     * point order), model-invocable and manual-only alike (spec §3.1).
+     */
+    async list(a) {
+        const all = await resolveSkills(this.d.db, a);
+        const out = [];
+        for (const r of all) {
+            const inv = invocationOf(r.manifest);
+            if (!inv.user)
+                continue;
+            out.push({
+                id: r.skill.id,
+                name: r.skill.name,
+                ...(r.skill.plugin !== undefined && { plugin: r.skill.plugin }),
+                description: r.skill.description,
+                version: r.skill.version,
+                ...(inv.argumentHint !== undefined && { argumentHint: inv.argumentHint }),
+                ...(inv.arguments !== undefined && { arguments: inv.arguments }),
+                manual: !inv.model,
+                fork: inv.fork !== undefined,
+            });
+        }
+        return out;
+    }
+    /**
+     * Resolves `name` among the agent's effective skills now, reads its SKILL.md and renders the
+     * invocation (spec §4.2, §4.3, §6.3). Refusals: `skill.not_invocable` (400); arguments or a
+     * rendered text over the limits → `validation_failed` (400); a storage failure or a SKILL.md
+     * that fails its integrity check → `storage.unavailable` (503). Nothing is written here.
+     */
+    async prepare(a) {
+        const all = await resolveSkills(this.d.db, a);
+        const found = findSkill(all, a.name);
+        if (!found)
+            throw notInvocable("not_found", a.name);
+        const inv = invocationOf(found.manifest);
+        if (!inv.user)
+            throw notInvocable("not_user_invocable", a.name);
+        const body = await this.readBody(a.orgId, found);
+        const others = found.manifest.files.some((f) => f.path !== SKILL_ENTRY_FILE);
+        const lines = {
+            // the invocation itself makes the conversation's next run offer skill_load (skillLoadOffered)
+            ...(others && { files: "load" }),
+            ...(hasShellInjection(body) &&
+                hasBuiltin(a.agent, "sandbox_bash") && { shellHint: true }),
+        };
+        const input = {
+            name: a.name,
+            skillName: found.skill.name,
+            version: found.skill.version,
+            body,
+            invocation: inv,
+            args: a.args,
+            lines,
+        };
+        // a SKILL.md whose body alone renders over the limit can never be invoked: say so, rather than
+        // "shorten the arguments"
+        tooLarge(found.skill.name, () => renderSkillBody(body, inv, "", found.skill.name));
+        const args = a.args.trim();
+        const record = {
+            id: found.skill.id,
+            version: found.skill.version,
+            source: found.skill.source,
+            name: found.skill.name,
+            ...(found.skill.plugin !== undefined && { plugin: found.skill.plugin }),
+            arguments: args,
+            mode: inv.fork ? "fork" : "inline",
+        };
+        if (!inv.fork)
+            return { text: rendered(() => renderSkillInvocation(input)), skill: record };
+        const task = rendered(() => renderSkillInvocation({ ...input, lead: false }));
+        const type = await resolveSkillForkType(this.d.db, a.orgId, a.agent, inv.fork.agent, found.skill.plugin);
+        return {
+            text: forkLeadText(a.name, type.agentType, args),
+            skill: { ...record, agentType: type.agentType },
+            task,
+            ...(type.unknown !== undefined && {
+                warning: forkAgentUnknownText(a.name, type.unknown),
+            }),
+        };
+    }
+    /**
+     * The task of a fork invocation's sub-agent (spec §6.2), rendered at dispatch from the version
+     * the person's message recorded (`skill.{id, source, version, arguments}`), never by name, so a
+     * skill changed since the send cannot run another version than the frozen lead names (batch 2
+     * review m4). The same `<skill_invocation>` text as the inline form without the lead sentence.
+     * `warning`: the skill asked for a sub-agent type that did not resolve (the recorded `agentType`
+     * is `general-purpose` for an `agent` other than Claude's built-in types). Throws
+     * `storage.unavailable` (`skill_unreadable`) when the version is gone or its SKILL.md cannot be
+     * read, plain `storage.unavailable` when storage is down. `task` renders the text for the
+     * sub-agent's effective definition: the shell-injection line only when the sub-agent has
+     * `sandbox_bash` (batch 3 review m1).
+     */
+    async renderTask(a) {
+        const { skill } = a;
+        const found = await findSkillVersion(this.d.db, a, { id: skill.id, source: skill.source });
+        if (!found) {
+            this.d.log?.error("invoked skill unreadable", {
+                orgId: a.orgId,
+                skillId: skill.id,
+                version: skill.version,
+                source: skill.source,
+                problem: "is gone",
+            });
+            throw new ApiError("storage.unavailable", `Skill ${skill.name} is gone`, [
+                { reason: "skill_unreadable", skillId: skill.id, name: skill.name },
+            ]);
+        }
+        const body = await this.readBody(a.orgId, {
+            skill: { id: skill.id, name: skill.name, version: skill.version, source: skill.source },
+            manifest: found.manifest,
+        });
+        const inv = invocationOf(found.manifest);
+        const others = found.manifest.files.some((f) => f.path !== SKILL_ENTRY_FILE);
+        const task = (child) => renderSkillInvocation({
+            name: skill.name,
+            skillName: skill.name,
+            version: skill.version,
+            body,
+            invocation: inv,
+            args: skill.arguments,
+            lines: {
+                ...(others && { files: "load" }),
+                ...(hasShellInjection(body) &&
+                    hasBuiltin(child, "sandbox_bash") && { shellHint: true }),
+            },
+            lead: false,
+        });
+        const asked = inv.fork?.agent;
+        const unknown = asked !== undefined && !isGeneralAlias(asked) && skill.agentType === "general-purpose";
+        return { task, ...(unknown && { warning: forkAgentUnknownText(skill.name, asked) }) };
+    }
+    /** Reads and parses the version's SKILL.md (checked against the manifest), returns the body. */
+    async readBody(orgId, r) {
+        const unreadable = (problem) => {
+            this.d.log?.error("invoked skill unreadable", {
+                orgId,
+                skillId: r.skill.id,
+                version: r.skill.version,
+                source: r.skill.source,
+                problem,
+            });
+            return new ApiError("storage.unavailable", `Skill ${r.skill.name} ${problem}`, [
+                { reason: "skill_unreadable", skillId: r.skill.id, name: r.skill.name },
+            ]);
+        };
+        const md = r.manifest.files.find((f) => f.path === SKILL_ENTRY_FILE);
+        if (!md)
+            throw unreadable(`has no ${SKILL_ENTRY_FILE}`);
+        this.d.storage.assertAvailable();
+        let bytes;
+        try {
+            bytes = await readSkillFile(this.d.storage.kernel(orgId), `${r.skill.source}${SKILL_ENTRY_FILE}`, md);
+        }
+        catch (e) {
+            if (e instanceof SkillIntegrityError)
+                throw unreadable("failed its integrity check");
+            if (e instanceof ApiError)
+                throw e;
+            throw new ApiError("storage.unavailable", "File storage is temporarily unavailable");
+        }
+        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");
+        return parsed.body;
+    }
+}
+const hasBuiltin = (agent, name) => (agent.tools ?? []).some((t) => t.kind === "builtin" && t.name === name);
+/** The skill's own body over the rendered limit: a 400 on `skill` naming the skill. */
+function tooLarge(name, render) {
+    try {
+        render();
+    }
+    catch (e) {
+        if (e instanceof RangeError) {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                {
+                    path: "skill",
+                    message: `the skill "${name}" is too large to invoke (its rendered text must be at most ${SKILL_INVOCATION_LIMITS.renderedMaxChars} characters)`,
+                },
+            ]);
+        }
+        throw e;
+    }
+}
+/** Runs an SDK render; its `RangeError` (a size limit) becomes a 400 on `text`. */
+function rendered(render) {
+    try {
+        return render();
+    }
+    catch (e) {
+        if (e instanceof RangeError) {
+            throw new ApiError("validation_failed", "Request validation failed", [
+                { path: "text", message: `${e.message}; shorten the arguments` },
+            ]);
+        }
+        throw e;
+    }
+}

package/dist/skills/package.d.ts

@@ -0,0 +1,87 @@
+import { type SkillInvocation } from "@capybara-hq/plugin-sdk";
+/**
+ * 技能包（zip）解包与校验。zip 一律当作恶意输入：
+ *
+ * - 解析用 yauzl（3.4.0，固定版本）：只信中央目录、按条目随机读取（不按本地头顺序猜），自带
+ *   `validateEntrySizes`（实际解压出的字节数必须等于声明值）与文件名检查（绝对路径、盘符、`..`、
+ *   `strictFileNames` 下的反斜杠）。不选 fflate：它的同步解压会先把整个条目解到内存，流式解压又按本地头顺序走，
+ *   遇到声明与实际不一致的恶意包更难兜住。
+ * - 此外自己再按**实际**解压出的字节数计数：单文件超过 {@link SKILL_LIMITS.fileBytes}、累计超过
+ *   {@link SKILL_LIMITS.totalBytes} 立即中止；条目数上限 {@link SKILL_PACKAGE_MAX_ENTRIES}；声明的压缩比
+ *   超过 {@link MAX_COMPRESSION_RATIO}（且解压后超过 1 MiB）视为 zip 炸弹，提前拒绝、不做解压
+ *   （deflate 的理论上限约 1032:1，正常文本即使高度重复也远低于 1000:1；真正兜底的是按实际字节的上限）；拒绝符号链接与其他非普通文件
+ *   （外部属性里的 Unix mode）、加密条目、stored / deflate 之外的压缩方法。
+ * - 路径与清单规则（必须有 SKILL.md、去重、大小写冲突、控制字符、沙箱路径）见 plugin-sdk `validateSkillPackage`。
+ *
+ * 整个 zip（≤ {@link SKILL_PACKAGE_MAX_BYTES}）与解出的文件（≤ 50MB）都在内存里处理。
+ */
+/** 技能包 zip 本身的大小上限（字节）。 */
+export declare const SKILL_PACKAGE_MAX_BYTES: number;
+/** zip 中央目录的条目数上限（含目录项与被忽略的条目）。 */
+export declare const SKILL_PACKAGE_MAX_ENTRIES = 1000;
+/** 单个条目声明的「解压后 / 压缩后」比值上限（只挡近乎单一字节重复的炸弹，正常文本不会触发）。 */
+export declare const MAX_COMPRESSION_RATIO = 1000;
+/** 包里的一个文件（路径相对于技能根目录）。 */
+export interface SkillPackageFile {
+    path: string;
+    size: number;
+    /** 十六进制 sha256。 */
+    sha256: string;
+    data: Uint8Array;
+}
+/** 解包并校验后的技能包。 */
+export interface SkillPackage {
+    name: string;
+    description: string;
+    /** Read from the SKILL.md frontmatter (phase D). */
+    invocation: SkillInvocation;
+    files: SkillPackageFile[];
+}
+/**
+ * The `invocation` to store in a version's manifest: undefined for the defaults (a skill both the
+ * model and a person can invoke, with no fork, hint or named arguments), so ordinary skills keep
+ * their manifest unchanged.
+ */
+export declare function storedInvocation(i: SkillInvocation): SkillInvocation | undefined;
+/**
+ * Invalid zip or skill content (`problems` lists each one, in English). Independent of HTTP: a
+ * skill upload maps it to `skill.invalid_package`, an enterprise catalog import to
+ * `catalog.invalid_manifest`.
+ */
+export declare class SkillArchiveError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/**
+ * 外层目录规则：根目录有 SKILL.md → 原样使用；否则当且仅当全部文件都在同一个顶层目录 `D/` 下、且 `D/SKILL.md`
+ * 存在时，去掉 `D/`（如 GitHub 下载的 `repo-main/`；目录名不必等于技能名，技能名只取 SKILL.md 的 name，
+ * 沙箱路径用 `/skills/<name>/`）。其他情况（多个顶层条目、SKILL.md 只在更深的目录里）不猜，按缺少 SKILL.md 拒绝。
+ */
+export declare function stripWrapper<T extends {
+    path: string;
+}>(files: T[], entryFile?: string): T[];
+/**
+ * 解包并校验技能包：返回 SKILL.md 里的 name / description 与全部文件（含 sha256）。
+ * 外层目录按 {@link stripWrapper} 的规则去掉。
+ * 任何问题 → `skill.invalid_package`（400），details 逐条列出。
+ */
+export declare function readSkillPackage(bytes: Uint8Array): Promise<SkillPackage>;
+/**
+ * Checks a set of skill files (paths relative to the skill root): the rules of plugin-sdk
+ * `validateSkillPackage`, SKILL.md strict UTF-8 with valid frontmatter. Returns its name,
+ * description and invocation metadata. Invalid → {@link SkillArchiveError}. `invocationKeys: false`
+ * (files stored before phase D, Claude Code imports) skips the invocation key checks and leaves out
+ * of the invocation every key they would refuse ({@link cleanInvocationKeys}).
+ */
+export declare function checkSkillFiles(files: SkillPackageFile[], opts?: {
+    invocationKeys?: boolean;
+}): {
+    name: string;
+    description: string;
+    invocation: SkillInvocation;
+};
+/**
+ * 读 zip 里的全部普通文件（规则与上限见文件头；`maxBytes` 为 zip 本身的上限），不去外层目录、不看内容。
+ * 不合法 → {@link SkillArchiveError}。
+ */
+export declare function readZipFiles(bytes: Uint8Array, maxBytes: number): Promise<SkillPackageFile[]>;