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

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

@@ -0,0 +1,53 @@
+import { type Selectable } from "kysely";
+import type { EventLog } from "../conversations/event-log.js";
+import type { SkillChangeRequestsTable } from "../db/kernel-schema.js";
+import type { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { type SkillsSnapshot } from "../runtime/context/skills.js";
+/** What appending a conversation's skills catalog snapshot needs. */
+export interface ConversationCatalogDeps {
+    db: KernelDb;
+    log: KernelLogger;
+    eventLog: EventLog;
+}
+/** Cancelled requests: draft prefixes to delete and (conversation, seq) to publish after the commit. */
+export interface CancelledDrafts {
+    prefixes: string[];
+    seqs: [string, number][];
+}
+/**
+ * In the caller's transaction, derives the conversation's next skills catalog snapshot from its
+ * latest one and appends it (only when different). It first locks the conversation row (the lock
+ * `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.
+ */
+export declare function appendConversationCatalog(deps: ConversationCatalogDeps, conversationId: string, derive: (base: SkillsSnapshot) => SkillsSnapshot | null, idemKey: string, runId?: string | null): Promise<number | null>;
+/**
+ * When a draft stops applying (rejected / cancelled), appends a reverting snapshot to the
+ * requesting conversation in the caller's transaction: derived from that conversation's latest
+ * snapshot, the draft's entry is replaced by the skill's current real version (already the
+ * post-decision state in the transaction; for a version proposal the org skill it targets), or
+ * removed when there is none. No snapshot is written when the latest one no longer has the draft,
+ * nor for a request without a conversation or a share request (no trial). While the conversation
+ * runs, the notice lands at the current position (built after the tool results) and applies at
+ * the next step. A removal does not guess an org skill of the same name (it was replaced in the
+ * snapshot); the next run start's resolution brings it back.
+ */
+export declare function revertTrialCatalog(deps: ConversationCatalogDeps, req: Selectable<SkillChangeRequestsTable>): Promise<number | null>;
+/**
+ * In the caller's transaction (the request row locked), cancels a pending request: status
+ * `cancelled`, audit `skill.change_decided` with the reason. A version draft also gets a
+ * reverting snapshot in its conversation (unless `revert` is false: the caller appends the next
+ * one) and its prefix is queued in `out` for deletion after the commit; a share request points at
+ * the skill's own version files, which stay.
+ */
+export declare function cancelRequestIn(deps: ConversationCatalogDeps, req: Selectable<SkillChangeRequestsTable>, out: CancelledDrafts, how: {
+    actorAccountId: string;
+    actorTokenId?: string;
+    reason: string;
+    revert?: boolean;
+}): Promise<void>;

package/dist/skills/conversation-catalog.js

@@ -0,0 +1,149 @@
+import { sql } from "kysely";
+import { audit } from "../identity/audit.js";
+import { sameSnapshot, } from "../runtime/context/skills.js";
+import { fitPinned, 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
+ * latest one and appends it (only when different). It first locks the conversation row (the lock
+ * `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.
+ */
+export async function appendConversationCatalog(deps, conversationId, derive, idemKey, runId) {
+    const base = (await lockLatestCatalog(deps.db.db, conversationId)) ?? { skills: [] };
+    const derived = derive(base);
+    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))
+        return null;
+    const written = await deps.eventLog.appendIn(conversationId, [
+        {
+            type: "skills_catalog",
+            ...(runId !== undefined && runId !== null && { runId }),
+            idemKey,
+            payload: next,
+        },
+    ]);
+    return Math.max(...written.map((e) => e.seq));
+}
+/**
+ * When a draft stops applying (rejected / cancelled), appends a reverting snapshot to the
+ * requesting conversation in the caller's transaction: derived from that conversation's latest
+ * snapshot, the draft's entry is replaced by the skill's current real version (already the
+ * post-decision state in the transaction; for a version proposal the org skill it targets), or
+ * removed when there is none. No snapshot is written when the latest one no longer has the draft,
+ * nor for a request without a conversation or a share request (no trial). While the conversation
+ * runs, the notice lands at the current position (built after the tool results) and applies at
+ * the next step. A removal does not guess an org skill of the same name (it was replaced in the
+ * snapshot); the next run start's resolution brings it back.
+ */
+export async function revertTrialCatalog(deps, req) {
+    const conversationId = req.requested_in_conversation;
+    if (conversationId === null || req.kind === "share")
+        return null;
+    const name = req.proposed_version.manifest.name;
+    let q = deps.db
+        .selectFrom("skills")
+        .innerJoin("skill_versions", (j) => j
+        .onRef("skill_versions.skill_id", "=", "skills.id")
+        .onRef("skill_versions.version", "=", "skills.current_version"))
+        .select([
+        "skills.id",
+        "skills.current_version",
+        "skill_versions.manifest",
+        "skill_versions.object_prefix",
+    ])
+        .where("skills.org_id", "=", req.org_id)
+        .where("skills.deleted_at", "is", null);
+    // A proposal on a shared org skill goes back to that skill's current version; one served from
+    // a platform skill (promoted or linked without a pin) is removed instead, and the next run start
+    // resolves it again
+    q =
+        req.skill_id !== null
+            ? q
+                .where("skills.id", "=", req.skill_id)
+                .where("skills.scope", "=", "org")
+                .where((eb) => eb.or([
+                eb("skills.platform_skill_id", "is", null),
+                eb("skills.pinned_version", "is not", null),
+            ]))
+            : q
+                .where("skills.scope", "=", "agent")
+                .where("skills.agent_id", "=", req.agent_id)
+                .where("skills.name", "=", name);
+    const real = await q.executeTakeFirst();
+    return appendConversationCatalog(deps, conversationId, (base) => {
+        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
+            skills: real && invocationOf(real.manifest).model
+                ? [
+                    ...rest,
+                    {
+                        id: real.id,
+                        name,
+                        description: real.manifest.description,
+                        version: real.current_version,
+                        source: real.object_prefix,
+                    },
+                ]
+                : rest,
+            ...(base.pinned && {
+                pinned: base.pinned.filter((p) => p.source !== req.object_prefix),
+            }),
+        };
+    }, `skills_catalog:revert:${req.id}`);
+}
+/**
+ * In the caller's transaction (the request row locked), cancels a pending request: status
+ * `cancelled`, audit `skill.change_decided` with the reason. A version draft also gets a
+ * reverting snapshot in its conversation (unless `revert` is false: the caller appends the next
+ * one) and its prefix is queued in `out` for deletion after the commit; a share request points at
+ * the skill's own version files, which stay.
+ */
+export async function cancelRequestIn(deps, req, out, how) {
+    await deps.db
+        .updateTable("skill_change_requests")
+        .set({ status: "cancelled", decided_at: sql `now()` })
+        .where("id", "=", req.id)
+        .execute();
+    await audit(deps.db.db, {
+        actorAccountId: how.actorAccountId,
+        ...(how.actorTokenId !== undefined && { actorTokenId: how.actorTokenId }),
+        orgId: req.org_id,
+        action: "skill.change_decided",
+        target: req.id,
+        detail: {
+            decision: "cancelled",
+            reason: how.reason,
+            kind: req.kind,
+            agentId: req.agent_id,
+            name: req.proposed_version.manifest.name,
+        },
+    });
+    if (req.kind === "share")
+        return;
+    if (how.revert !== false) {
+        const seq = await revertTrialCatalog(deps, req);
+        if (seq !== null && req.requested_in_conversation !== null) {
+            out.seqs.push([req.requested_in_conversation, seq]);
+        }
+    }
+    out.prefixes.push(req.object_prefix);
+}

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

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import type { 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";

package/dist/skills/invocable.controller.js

@@ -8,13 +8,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Header, Inject, Param } from "@nestjs/common";
-import { z } from "zod";
 import { CurrentPrincipal, requireUser } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZQuery } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { SkillInvoker } from "./invoke.js";
-const ListQuery = z.object({ conversationId: z.string().min(1).max(100).optional() }).strict();
+import { InvocableSkillsQuerySchema } from "./skills.schemas.js";
+const ListQuery = InvocableSkillsQuerySchema;
 class InvocableSkillsQuery extends createZodDto(ListQuery, "InvocableSkillsQuery") {
 }
 /**

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

@@ -2,7 +2,7 @@
  * 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.
+ * invocation nobody can use. Uploads and native imports 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"];

package/dist/skills/invocation-keys.js

@@ -3,7 +3,7 @@ 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.
+ * invocation nobody can use. Uploads and native imports stay strict.
  */
 /** The frontmatter keys that make up a skill's invocation metadata. */
 export const INVOCATION_KEYS = [

package/dist/skills/invoke.d.ts

@@ -1,5 +1,5 @@
 import { AgentLookup } from "../agents/agent-lookup.js";
-import type { AgentDefinition } from "../agents/definition.js";
+import { type AgentDefinition } from "../agents/definition.js";
 import type { EventPayload } from "../conversations/events.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
@@ -121,14 +121,14 @@ export declare class SkillInvoker {
      * `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).
+     * `Bash` (batch 3 review m1).
      */
     renderTask(a: {
         orgId: string;
         conversationId: string;
         skill: InvocationRecord;
     }): Promise<{
-        task: (child: Pick<AgentDefinition, "tools">) => string;
+        task: (child: Pick<AgentDefinition, "disabledTools" | "subagentTools">) => string;
         warning?: string;
     }>;
     /** Reads and parses the version's SKILL.md (checked against the manifest), returns the body. */

package/dist/skills/invoke.js

@@ -7,16 +7,19 @@ 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 { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, } from "@capybara-hq/plugin-sdk";
+import { escapeSkillInvocationTags, hasShellInjection, parseSkillMd, renderSkillBody, renderSkillInvocation, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, skillDigest, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { AgentLookup } from "../agents/agent-lookup.js";
+import { builtinDisabled } from "../agents/definition.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { isGeneralAlias, resolveSkillForkType } from "../runtime/subagents/roster.js";
 import { StorageService } from "../storage/storage.service.js";
+import { BUILTIN } from "../tools/builtin-names.js";
 import { findSkillVersion, readSkillFile, SkillIntegrityError, } from "../tools/builtins/skill-load.js";
 import { invocationOf, resolveSkills } from "./catalog.js";
+import { skillFileStore } from "./usable.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`). */
@@ -142,14 +145,15 @@ let SkillInvoker = class SkillInvoker {
         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)
+            // the invocation itself makes the conversation's next run offer Skill (skillLoadOffered)
             ...(others && { files: "load" }),
             ...(hasShellInjection(body) &&
-                hasBuiltin(a.agent, "sandbox_bash") && { shellHint: true }),
+                hasBuiltin(a.agent, BUILTIN.Bash) && { shellHint: true }),
         };
         const input = {
             name: a.name,
             skillName: found.skill.name,
+            digest: skillDigest(found.manifest.files),
             version: found.skill.version,
             body,
             invocation: inv,
@@ -158,7 +162,7 @@ let SkillInvoker = class SkillInvoker {
         };
         // 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));
+        tooLarge(found.skill.name, () => renderSkillBody(body, inv, "", found.skill.name, input.digest));
         const args = a.args.trim();
         const record = {
             id: found.skill.id,
@@ -192,7 +196,7 @@ let SkillInvoker = class SkillInvoker {
      * `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).
+     * `Bash` (batch 3 review m1).
      */
     async renderTask(a) {
         const { skill } = a;
@@ -218,6 +222,7 @@ let SkillInvoker = class SkillInvoker {
         const task = (child) => renderSkillInvocation({
             name: skill.name,
             skillName: skill.name,
+            digest: skillDigest(found.manifest.files),
             version: skill.version,
             body,
             invocation: inv,
@@ -225,7 +230,7 @@ let SkillInvoker = class SkillInvoker {
             lines: {
                 ...(others && { files: "load" }),
                 ...(hasShellInjection(body) &&
-                    hasBuiltin(child, "sandbox_bash") && { shellHint: true }),
+                    hasBuiltin(child, BUILTIN.Bash) && { shellHint: true }),
             },
             lead: false,
         });
@@ -253,7 +258,9 @@ let SkillInvoker = class SkillInvoker {
         this.storage.assertAvailable();
         let bytes;
         try {
-            bytes = await readSkillFile(this.storage.kernel(orgId), `${r.skill.source}${SKILL_ENTRY_FILE}`, md);
+            // a platform version (`platform:<prefix>`) is read from deployment/ (ruling D2)
+            const { store, prefix } = skillFileStore(this.storage, orgId, r.skill.source);
+            bytes = await readSkillFile(store, `${prefix}${SKILL_ENTRY_FILE}`, md);
         }
         catch (e) {
             if (e instanceof SkillIntegrityError)
@@ -283,7 +290,13 @@ SkillInvoker = __decorate([
     __param(3, Inject(KERNEL_LOGGER))
 ], SkillInvoker);
 export { SkillInvoker };
-const hasBuiltin = (agent, name) => (agent.tools ?? []).some((t) => t.kind === "builtin" && t.name === name);
+/**
+ * Does the definition leave builtin `name` on (tools default-on spec §4): not turned off and not
+ * removed by a sub-agent's key filter. Whether it can run now (a sandbox) is not checked.
+ */
+const hasBuiltin = (agent, name) => !builtinDisabled(agent.disabledTools, name) &&
+    !(agent.subagentTools?.deny ?? []).includes(name) &&
+    (agent.subagentTools?.allow === undefined || agent.subagentTools.allow.includes(name));
 /** The skill's own body over the rendered limit: a 400 on `skill` naming the skill. */
 function tooLarge(name, render) {
     try {

package/dist/skills/package.d.ts

@@ -1,4 +1,5 @@
 import { type SkillInvocation } from "@capybara-hq/plugin-sdk";
+import type { SkillManifest } from "../db/kernel-schema.js";
 /**
  * 技能包（zip）解包与校验。zip 一律当作恶意输入：
  *
@@ -45,7 +46,7 @@ export interface SkillPackage {
 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
+ * skill upload maps it to `skill.invalid_package`, a platform catalog import to
  * `catalog.invalid_manifest`.
  */
 export declare class SkillArchiveError extends Error {
@@ -85,3 +86,16 @@ export declare function checkSkillFiles(files: SkillPackageFile[], opts?: {
  * 不合法 → {@link SkillArchiveError}。
  */
 export declare function readZipFiles(bytes: Uint8Array, maxBytes: number): Promise<SkillPackageFile[]>;
+/** A validated skill package: its name, description, files and invocation. */
+export interface SkillPackageInput {
+    name: string;
+    description: string;
+    files: SkillPackageFile[];
+    /** Phase D: stored in the manifest when it is not the default. */
+    invocation?: SkillInvocation;
+}
+/**
+ * The stored manifest of a skill package (the invocation only when it is not the default); org
+ * skills and platform skills store the same shape.
+ */
+export declare function skillManifest(pkg: SkillPackageInput): SkillManifest;

package/dist/skills/package.js

@@ -48,7 +48,7 @@ export function storedInvocation(i) {
 const ignored = (path) => path.startsWith("__MACOSX/") || path === ".DS_Store" || path.endsWith("/.DS_Store");
 /**
  * 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
+ * skill upload maps it to `skill.invalid_package`, a platform catalog import to
  * `catalog.invalid_manifest`.
  */
 export class SkillArchiveError extends Error {
@@ -225,3 +225,16 @@ export async function readZipFiles(bytes, maxBytes) {
     }
     return raw;
 }
+/**
+ * The stored manifest of a skill package (the invocation only when it is not the default); org
+ * skills and platform skills store the same shape.
+ */
+export function skillManifest(pkg) {
+    const invocation = pkg.invocation && storedInvocation(pkg.invocation);
+    return {
+        name: pkg.name,
+        description: pkg.description,
+        files: pkg.files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
+        ...(invocation !== undefined && { invocation }),
+    };
+}

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

@@ -1,14 +1,16 @@
 import { z } from "zod";
+import { OwnedItems, type OwnedSkillDeletePreview } from "../catalog/owned-items.js";
 import { type CreatedAttachment } from "../conversations/attachments.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { SkillCreateBody, SkillIdParams } from "./skills.schemas.js";
 import { type SkillDetail, type SkillSummary, SkillsService, type UploadedSkill } from "./skills.service.js";
 declare const UploadBody: z.ZodObject<{
     name: z.ZodString;
     size: z.ZodNumber;
 }, z.core.$strict>;
-declare const CreateBody: z.ZodObject<{
-    uploadId: z.ZodString;
+declare const ShareableBody: z.ZodObject<{
+    shareable: z.ZodBoolean;
 }, z.core.$strict>;
 /**
  * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
@@ -21,20 +23,44 @@ declare const CreateBody: z.ZodObject<{
  *      `POST /attachments/:id/finalize`, or skip it and let the next step finalize);
  *   3. `POST /` `{ uploadId }` unpacks and checks it, creating a skill or adding a version to the
  *      skill with the same name;
- *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3).
+ *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3; `GET /:id/delete-preview` says
+ *   what it does), `PUT /:id/shareable` sets 可共享 (plugin scope phase 3, ruling P3-6).
  * When the deployment setting `customSkills` is deny, registering an upload and creating both
  * return 403 `catalog.custom_disabled` (decided in the service, re-checked inside the org row lock
- * on create); installing skills from the enterprise catalog is unaffected.
+ * on create); installing skills from the platform catalog is unaffected.
  */
 export declare class SkillsController {
     private readonly skills;
-    constructor(skills: SkillsService);
+    /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
+    private readonly owned;
+    constructor(skills: SkillsService, 
+    /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
+    owned: OwnedItems);
     createUpload(principal: Principal, org: OrgContext, body: z.infer<typeof UploadBody>): Promise<CreatedAttachment>;
-    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<UploadedSkill>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof SkillCreateBody>): Promise<UploadedSkill>;
     list(principal: Principal, org: OrgContext): Promise<{
         skills: SkillSummary[];
     }>;
     get(principal: Principal, org: OrgContext, id: string): Promise<SkillDetail>;
+    /**
+     * 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 ->
+     * 409 `catalog.not_owned`); one it promoted writes its platform row too (ruling P3-2).
+     */
+    setShareable(principal: Principal, org: OrgContext, params: z.infer<typeof SkillIdParams>, body: z.infer<typeof ShareableBody>): Promise<{
+        id: string;
+        shareable: boolean;
+    }>;
+    /**
+     * What deleting the skill does (pre-flight F19, P3-19; nothing written): `outcome`
+     * `transferred` when it was shared and another org uses it (`orgs`), else `removed`; `agents`
+     * the org's agents that lose it.
+     */
+    deletePreview(principal: Principal, org: OrgContext, params: z.infer<typeof SkillIdParams>): Promise<OwnedSkillDeletePreview>;
+    /**
+     * Soft-deletes the skill; one the org shared that another org uses is transferred to the
+     * platform first (P3-19, platform notice `ownership_transferred`). 204.
+     */
     remove(principal: Principal, org: OrgContext, id: string): Promise<void>;
 }
 export {};

package/dist/skills/skills.controller.js

@@ -8,13 +8,15 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
-import { Controller, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put } from "@nestjs/common";
 import { z } from "zod";
+import { OwnedItems } from "../catalog/owned-items.js";
 import { SKILL_PACKAGE_UPLOAD_MAX_BYTES, } from "../conversations/attachments.service.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
-import { ZBody } from "../infra/validation/zod-params.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { SkillCreateBody, SkillIdParams, SkillShareableSchema } from "./skills.schemas.js";
 import { SkillsService, } from "./skills.service.js";
 const UploadBody = z
     .object({
@@ -26,10 +28,14 @@ const UploadBody = z
     size: z.number().int().min(1).max(SKILL_PACKAGE_UPLOAD_MAX_BYTES),
 })
     .strict();
-const CreateBody = z.object({ uploadId: z.string().min(1).max(100) }).strict();
 class SkillUploadBody extends createZodDto(UploadBody, "SkillUploadBody") {
 }
-class SkillCreateBody extends createZodDto(CreateBody, "SkillCreateBody") {
+class SkillCreateBodyDto extends createZodDto(SkillCreateBody, "SkillCreateBody") {
+}
+const ShareableBody = SkillShareableSchema;
+class SkillIdParamsDto extends createZodDto(SkillIdParams, "SkillIdParams") {
+}
+class SkillShareableBody extends createZodDto(ShareableBody, "SkillShareableBody") {
 }
 /**
  * The org skill library (`/api/v1/orgs/:orgId/skills`, human users only):
@@ -42,15 +48,20 @@ class SkillCreateBody extends createZodDto(CreateBody, "SkillCreateBody") {
  *      `POST /attachments/:id/finalize`, or skip it and let the next step finalize);
  *   3. `POST /` `{ uploadId }` unpacks and checks it, creating a skill or adding a version to the
  *      skill with the same name;
- *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3).
+ *   `DELETE /:id` soft-deletes (the web asks for confirmation, R3; `GET /:id/delete-preview` says
+ *   what it does), `PUT /:id/shareable` sets 可共享 (plugin scope phase 3, ruling P3-6).
  * When the deployment setting `customSkills` is deny, registering an upload and creating both
  * return 403 `catalog.custom_disabled` (decided in the service, re-checked inside the org row lock
- * on create); installing skills from the enterprise catalog is unaffected.
+ * on create); installing skills from the platform catalog is unaffected.
  */
 let SkillsController = class SkillsController {
     skills;
-    constructor(skills) {
+    owned;
+    constructor(skills, 
+    /** The org's own items: 可共享 and the delete of a promoted skill (rulings P3-3, P3-19). */
+    owned) {
         this.skills = skills;
+        this.owned = owned;
     }
     async createUpload(principal, org, body) {
         const p = requireUser(principal);
@@ -58,7 +69,8 @@ let SkillsController = class SkillsController {
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
-        return this.skills.upload(org.orgId, p.account.id, body.uploadId, patTokenId(p));
+        const tokenId = patTokenId(p);
+        return this.skills.upload(org.orgId, p.account.id, body.uploadId, tokenId, body.shareable);
     }
     async list(principal, org) {
         requireUser(principal);
@@ -68,9 +80,34 @@ let SkillsController = class SkillsController {
         requireUser(principal);
         return this.skills.get(org.orgId, id);
     }
+    /**
+     * 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 ->
+     * 409 `catalog.not_owned`); one it promoted writes its platform row too (ruling P3-2).
+     */
+    async setShareable(principal, org, params, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        await this.owned.setShareable(org.orgId, p.account.id, { kind: "skill", id: params.id }, body.shareable, tokenId !== undefined ? { actorTokenId: tokenId } : {});
+        return { id: params.id, shareable: body.shareable };
+    }
+    /**
+     * What deleting the skill does (pre-flight F19, P3-19; nothing written): `outcome`
+     * `transferred` when it was shared and another org uses it (`orgs`), else `removed`; `agents`
+     * the org's agents that lose it.
+     */
+    async deletePreview(principal, org, params) {
+        requireUser(principal);
+        return this.owned.previewSkillDelete(org.orgId, params.id);
+    }
+    /**
+     * Soft-deletes the skill; one the org shared that another org uses is transferred to the
+     * platform first (P3-19, platform notice `ownership_transferred`). 204.
+     */
     async remove(principal, org, id) {
         const p = requireUser(principal);
-        await this.skills.softDelete(org.orgId, id, p.account.id, patTokenId(p));
+        const tokenId = patTokenId(p);
+        await this.owned.deleteSkill(org.orgId, p.account.id, id, tokenId !== undefined ? { actorTokenId: tokenId } : {});
     }
 };
 __decorate([
@@ -85,7 +122,7 @@ __decorate([
     OrgAction("skills.manage"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, ZBody(SkillCreateBody))
+    __param(2, ZBody(SkillCreateBodyDto))
 ], SkillsController.prototype, "create", null);
 __decorate([
     Get(),
@@ -100,6 +137,21 @@ __decorate([
     __param(1, CurrentOrg()),
     __param(2, Param("id"))
 ], SkillsController.prototype, "get", null);
+__decorate([
+    Put(":id/shareable"),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SkillIdParamsDto)),
+    __param(3, ZBody(SkillShareableBody))
+], SkillsController.prototype, "setShareable", null);
+__decorate([
+    Get(":id/delete-preview"),
+    OrgAction("skills.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SkillIdParamsDto))
+], SkillsController.prototype, "deletePreview", null);
 __decorate([
     Delete(":id"),
     HttpCode(204),
@@ -110,6 +162,7 @@ __decorate([
 ], SkillsController.prototype, "remove", null);
 SkillsController = __decorate([
     Controller("api/v1/orgs/:orgId/skills"),
-    __param(0, Inject(SkillsService))
+    __param(0, Inject(SkillsService)),
+    __param(1, Inject(OwnedItems))
 ], SkillsController);
 export { SkillsController };