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

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/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 `SkillWrite` 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 `SkillWrite` 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/package.d.ts

@@ -86,11 +86,6 @@ export declare function checkSkillFiles(files: SkillPackageFile[], opts?: {
  * 不合法 → {@link SkillArchiveError}。
  */
 export declare function readZipFiles(bytes: Uint8Array, maxBytes: number): Promise<SkillPackageFile[]>;
-/**
- * Checks skill files that are already unpacked (paths relative to the skill root), e.g. the ones
- * built from text, with the rules of {@link readSkillPackage}. Invalid -> `skill.invalid_package`.
- */
-export declare function checkBuiltSkillFiles(files: SkillPackageFile[]): SkillPackage;
 /** A validated skill package: its name, description, files and invocation. */
 export interface SkillPackageInput {
     name: string;

package/dist/skills/package.js

@@ -225,20 +225,6 @@ export async function readZipFiles(bytes, maxBytes) {
     }
     return raw;
 }
-/**
- * Checks skill files that are already unpacked (paths relative to the skill root), e.g. the ones
- * built from text, with the rules of {@link readSkillPackage}. Invalid -> `skill.invalid_package`.
- */
-export function checkBuiltSkillFiles(files) {
-    try {
-        return { ...checkSkillFiles(files), files };
-    }
-    catch (e) {
-        if (e instanceof SkillArchiveError)
-            throw invalid(e.problems);
-        throw e;
-    }
-}
 /**
  * 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.

package/dist/skills/skills.controller.js

@@ -70,16 +70,7 @@ let SkillsController = class SkillsController {
     async create(principal, org, body) {
         const p = requireUser(principal);
         const tokenId = patTokenId(p);
-        if (body.uploadId !== undefined) {
-            return this.skills.upload(org.orgId, p.account.id, body.uploadId, tokenId, body.shareable);
-        }
-        return this.skills.createFromText(org.orgId, p.account.id, {
-            name: body.name,
-            description: body.description,
-            body: body.body,
-            ...(body.shareable !== undefined && { shareable: body.shareable }),
-            ...(tokenId !== undefined && { actorTokenId: tokenId }),
-        });
+        return this.skills.upload(org.orgId, p.account.id, body.uploadId, tokenId, body.shareable);
     }
     async list(principal, org) {
         requireUser(principal);

package/dist/skills/skills.module.js

@@ -11,6 +11,7 @@ import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { StorageModule } from "../storage/storage.module.js";
+import { AgentSkillsService } from "./agent-skills.service.js";
 import { SkillsCatalogService } from "./catalog.js";
 import { SkillChangesService } from "./changes.service.js";
 import { SkillInvoker } from "./invoke.js";
@@ -32,8 +33,20 @@ SkillsModule = __decorate([
             // the owner's new version of a skill it promoted goes to the platform row (ruling P3-4)
             CatalogImportModule,
         ],
-        providers: [SkillsService, SkillChangesService, SkillsCatalogService, SkillInvoker],
-        exports: [SkillsService, SkillChangesService, SkillsCatalogService, SkillInvoker],
+        providers: [
+            AgentSkillsService,
+            SkillsService,
+            SkillChangesService,
+            SkillsCatalogService,
+            SkillInvoker,
+        ],
+        exports: [
+            AgentSkillsService,
+            SkillsService,
+            SkillChangesService,
+            SkillsCatalogService,
+            SkillInvoker,
+        ],
     })
 ], SkillsModule);
 export { SkillsModule };

package/dist/skills/skills.schemas.d.ts

@@ -1,21 +1,8 @@
 import { z } from "zod";
 import type { RouteSchemas } from "../platform/route-schemas.js";
-/**
- * The fields of `POST /skills` before the either-or refinement: zod 4 cannot `pick` / `omit` a
- * refined object, so operations build from these and the route validates {@link SkillCreateBody}.
- */
-export declare const SkillCreateFields: z.ZodObject<{
-    uploadId: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
-    description: z.ZodOptional<z.ZodString>;
-    body: z.ZodOptional<z.ZodString>;
-    shareable: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strict>;
+/** `POST /skills`: an uploaded skill package (`POST /skills/uploads` gives the id); no text form. */
 export declare const SkillCreateBody: z.ZodObject<{
-    uploadId: z.ZodOptional<z.ZodString>;
-    name: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
-    description: z.ZodOptional<z.ZodString>;
-    body: z.ZodOptional<z.ZodString>;
+    uploadId: z.ZodString;
     shareable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /** `:id` where the route validates it (`@ZParam`). */
@@ -41,6 +28,15 @@ export declare const AgentSkillPathParams: z.ZodObject<{
     agentId: z.ZodString;
     skillId: z.ZodString;
 }, z.core.$strip>;
+/** `POST /agents/:agentId/skills/uploads`: a skill package upload onto the agent. */
+export declare const AgentSkillUploadBody: z.ZodObject<{
+    name: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strict>;
+/** `POST /agents/:agentId/skills`: an uploaded package registered as one of the agent's skills. */
+export declare const AgentSkillRegisterBody: z.ZodObject<{
+    uploadId: z.ZodString;
+}, z.core.$strict>;
 /** `?conversationId=` of `GET /agents/:agentId/invocable-skills`. */
 export declare const InvocableSkillsQuerySchema: z.ZodObject<{
     conversationId: z.ZodOptional<z.ZodString>;

package/dist/skills/skills.schemas.js

@@ -1,25 +1,10 @@
-import { isSkillName, SKILL_LIMITS } from "@capybara-hq/plugin-sdk";
+import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import { SKILL_WRITE_MAX_BYTES } from "../tools/builtins/skill-write.js";
-/**
- * The fields of `POST /skills` before the either-or refinement: zod 4 cannot `pick` / `omit` a
- * refined object, so operations build from these and the route validates {@link SkillCreateBody}.
- */
-export const SkillCreateFields = z
-    .object({
-    uploadId: z.string().min(1).max(100).optional(),
-    name: z
-        .string()
-        .refine(isSkillName, "name must be 1-64 lowercase letters, digits and single hyphens")
-        .optional(),
-    description: z.string().min(1).max(SKILL_LIMITS.descriptionMaxChars).optional(),
-    body: z.string().max(SKILL_WRITE_MAX_BYTES).optional(),
-    shareable: z.boolean().optional(),
-})
+import { SKILL_PACKAGE_UPLOAD_MAX_BYTES } from "../conversations/attachments.service.js";
+/** `POST /skills`: an uploaded skill package (`POST /skills/uploads` gives the id); no text form. */
+export const SkillCreateBody = z
+    .object({ uploadId: z.string().min(1).max(100), shareable: z.boolean().optional() })
     .strict();
-export const SkillCreateBody = SkillCreateFields.refine((v) => v.uploadId !== undefined
-    ? v.name === undefined && v.description === undefined && v.body === undefined
-    : v.name !== undefined && v.description !== undefined && v.body !== undefined, "send either { uploadId } or { name, description, body }");
 /** `:id` where the route validates it (`@ZParam`). */
 export const SkillIdParams = z.object({ id: z.string().min(1).max(100) });
 /** `:id` where the route takes it as is (`@Param`). */
@@ -32,6 +17,19 @@ export const AgentSkillsListParams = z.object({ agentId: z.string().min(1).max(1
 export const AgentSkillPathParams = AgentSkillsListParams.extend({
     skillId: z.string().min(1).max(100),
 });
+/** `POST /agents/:agentId/skills/uploads`: a skill package upload onto the agent. */
+export const AgentSkillUploadBody = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(MEDIA_NAME_MAX_CHARS)
+        .refine((s) => !hasControlChars(s), "name must not contain control characters"),
+    size: z.number().int().min(1).max(SKILL_PACKAGE_UPLOAD_MAX_BYTES),
+})
+    .strict();
+/** `POST /agents/:agentId/skills`: an uploaded package registered as one of the agent's skills. */
+export const AgentSkillRegisterBody = z.object({ uploadId: z.string().min(1).max(100) }).strict();
 /** `?conversationId=` of `GET /agents/:agentId/invocable-skills`. */
 export const InvocableSkillsQuerySchema = z
     .object({ conversationId: z.string().min(1).max(100).optional() })
@@ -39,10 +37,19 @@ export const InvocableSkillsQuerySchema = z
 export const SKILL_ROUTES = [
     { route: "GET /api/v1/orgs/:orgId/skill-changes/:id", params: SkillChangePathParams },
     { route: "GET /api/v1/orgs/:orgId/agents/:agentId/skills", params: AgentSkillsListParams },
+    {
+        route: "POST /api/v1/orgs/:orgId/agents/:agentId/skills",
+        params: AgentSkillsListParams,
+        body: AgentSkillRegisterBody,
+    },
     {
         route: "DELETE /api/v1/orgs/:orgId/agents/:agentId/skills/:skillId",
         params: AgentSkillPathParams,
     },
+    {
+        route: "POST /api/v1/orgs/:orgId/agents/:agentId/skills/:skillId/share",
+        params: AgentSkillPathParams,
+    },
     {
         route: "GET /api/v1/orgs/:orgId/agents/:agentId/invocable-skills",
         params: AgentSkillsListParams,

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

@@ -1,11 +1,13 @@
 import type { AgentDefinition } from "../agents/definition.js";
 import { type Owner } from "../catalog/ownership.js";
-import { PlatformComponents } from "../catalog/platform-components.js";
+import { type OwnerVersion, PlatformComponents } from "../catalog/platform-components.js";
 import { AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
+import { EventLog } from "../conversations/event-log.js";
 import type { KernelSchemaDb, SkillManifest, SourceFormat } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
 import { StorageService } from "../storage/storage.service.js";
 import { type SkillPackageInput } from "./package.js";
@@ -149,9 +151,12 @@ export declare class SkillsService {
     private readonly orgLock;
     /** The owner's new versions of a skill it promoted go to the platform row (ruling P3-4). */
     private readonly platform;
+    private readonly eventLog;
+    private readonly log;
     constructor(db: KernelDb, storage: StorageService, attachments: AttachmentsService, txHost: TransactionHost, orgLock: OrgLock, 
     /** The owner's new versions of a skill it promoted go to the platform row (ruling P3-4). */
-    platform: PlatformComponents);
+    platform: PlatformComponents, eventLog: EventLog, log: KernelLogger);
+    private readonly catalogDeps;
     /**
      * Writes a package's files where its version will live: for a new version of a skill the org
      * promoted (ruling P3-3: a live org skill of the name linked without a pin to a platform skill
@@ -188,31 +193,6 @@ export declare class SkillsService {
      * ({@link createVersionIn} joins it).
      */
     private createUploadedVersionIn;
-    /**
-     * The read-only checks of {@link createFromText}, for the `Platform` tool's precheck (before the
-     * card): custom skills allowed, a valid `SKILL.md`, and no live org skill of the name. Throws the
-     * same `ApiError` the create would; the create checks the name again under its lock.
-     */
-    checkCreateFromText(orgId: string, input: {
-        name: string;
-        description: string;
-        body: string;
-    }): Promise<void>;
-    /**
-     * Creates an org skill from text (spec §14, P3-24): `SKILL.md` is built from the name,
-     * description and body ({@link buildSkillWrite}, the description a YAML string) and checked like
-     * an uploaded package. The same policy and name rules as an upload, except that a live org skill
-     * of that name is `skill.name_exists` (409) instead of a new version.
-     */
-    createFromText(orgId: string, actorAccountId: string, input: {
-        name: string;
-        description: string;
-        body: string;
-        shareable?: boolean;
-        actorTokenId?: string;
-        /** Merged into the audit event's detail (the `Platform` tool's `via: "agent"`). */
-        auditDetail?: Record<string, unknown>;
-    }): Promise<UploadedSkill>;
     /**
      * 用一组已校验的技能文件创建组织技能或给同名技能新增版本（上传与平台目录安装共用）：
      * 1. 把文件写到 `kernel/<orgId>/<prefix>`（缺省 `skills/<新 id>/`）；
@@ -230,8 +210,6 @@ export declare class SkillsService {
         auditDetail?: Record<string, unknown>;
         /** The owner shares a new skill with other orgs (default false). */
         shareable?: boolean;
-        /** A live org skill of the name is `skill.name_exists` instead of getting a new version. */
-        failIfExists?: boolean;
         /** Catalog provenance; `approvedBy` is the item whose policy approves it (default `itemId`). */
         catalog?: {
             itemId: string;
@@ -242,7 +220,24 @@ export declare class SkillsService {
             /** The plugin manifest suggests pinning this skill (spec §9.1). */
             suggestPinned?: boolean;
         };
+        /**
+         * The files are already stored (no storage I/O here, so it may join a transaction): at
+         * `prefix` in `kernel/<orgId>/`, or, for a skill the org promoted, the platform version
+         * {@link prepareStoredVersion} wrote. The caller discards that one when this fails.
+         */
+        stored?: {
+            owner?: OwnerVersion;
+        };
     }): Promise<UploadedSkill>;
+    /**
+     * For a new version whose files are already in `kernel/<orgId>/` (a proposed version's draft):
+     * when the org skill of that name is one the org promoted, writes the files as the platform
+     * row's next version (never inside a transaction) and returns it for
+     * `createVersionFromFiles({ stored: { owner } })`; else nothing is written.
+     */
+    prepareStoredVersion(orgId: string, pkg: SkillPackageInput): Promise<OwnerVersion | undefined>;
+    /** Deletes a platform version {@link prepareStoredVersion} wrote that was not used. */
+    discardStoredVersion(owner: OwnerVersion): Promise<void>;
     /** Writes a skill package's files to `kernel/<orgId>/<prefix>` (a few at a time). */
     private putFiles;
     /** The transaction of {@link createVersionFromFiles}. */
@@ -266,6 +261,16 @@ export declare class SkillsService {
      * `usableSkills`; `origin` tells them apart), each with the ids of those copies (`linkedIds`).
      */
     list(orgId: string): Promise<SkillSummary[]>;
+    /**
+     * The agent's skills as the agent page lists them, by name: {@link listForAgent} (`shared:
+     * false`) plus `sharePending`, true while a share request of the skill waits for an org admin,
+     * and the org skills the agent shared (`origin_agent_id`; `scope: 'org'`, `shared: true`, same
+     * id as before sharing): the agent keeps them without selecting them.
+     */
+    listOwnForAgent(orgId: string, agentId: string): Promise<(SkillSummary & {
+        sharePending: boolean;
+        shared: boolean;
+    })[]>;
     /** 对该 agent 自动生效的技能（`scope=agent`、未删除），按名字排序。 */
     listForAgent(orgId: string, agentId: string): Promise<SkillSummary[]>;
     /**
@@ -292,7 +297,9 @@ export declare class SkillsService {
     /**
      * In the caller's transaction (`mandatory`: the caller holds the org row lock and checked
      * `skills.manage`), soft-deletes an org-scope skill of the org: what {@link softDelete} writes
-     * (audit `skill.deleted`); missing or deleted -> `skill.not_found`. The owner delete of a
+     * (audit `skill.deleted`); missing or deleted -> `skill.not_found`. Its pending version
+     * proposals are cancelled in the same transaction (trials reverted; drafts deleted and events
+     * published after the commit). The owner delete of a
      * promoted skill (`OwnedItems.deleteSkill`) calls it after its platform row was dealt with.
      */
     deleteOrgSkillIn(orgId: string, skillId: string, actorAccountId: string, actorTokenId: string | undefined, auditDetail?: Record<string, unknown>): Promise<void>;