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

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

@@ -0,0 +1,131 @@
+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, Delete, Get, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { AgentsService } from "../agents/agents.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 { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AgentSkillsService, } from "./agent-skills.service.js";
+import { AgentSkillRegisterBody, AgentSkillUploadBody } from "./skills.schemas.js";
+import { SkillsService } from "./skills.service.js";
+class AgentSkillUploadBodyDto extends createZodDto(AgentSkillUploadBody, "AgentSkillUploadBody") {
+}
+class AgentSkillRegisterBodyDto extends createZodDto(AgentSkillRegisterBody, "AgentSkillRegisterBody") {
+}
+/**
+ * An agent's own skills (`/api/v1/orgs/:orgId/agents/:agentId/skills`):
+ * - `GET /`: the list (`scope = agent`, live, plus the org skills the agent shared, `shared:
+ *   true`; by name; `sharePending` marks a skill whose share request waits for an org admin),
+ *   with the visibility of
+ *   `GET /agents/:agentId` (`agents.use`; an agent not visible -> 404 `agent.not_found`; a service
+ *   token sees only `visibility = 'org'` agents);
+ * - the writes are `agents.create` (HUMAN_ONLY) and only for the agent's current owner (others 403
+ *   `forbidden`, checked in the service):
+ *   1. `POST /uploads` `{ name, size }` registers a skill package upload (`application/zip`,
+ *      <= 50 MB, a presigned form as for org skills); agent skills are not governed by the
+ *      deployment's `customSkills` setting;
+ *   2. the browser uploads straight to object storage;
+ *   3. `POST /` `{ uploadId }` unpacks and checks it, creating the agent's skill or its next
+ *      version, or a version of a shared org skill the actor maintains (applied at once for an
+ *      org admin, else proposed; 200 `{ skill }`; the upload is consumed);
+ *   `DELETE /:skillId` soft-deletes one (a pending request of the same name is cancelled with it);
+ *   `POST /:skillId/share` shares one with the org (200 `{ share }`: shared at once for an org
+ *   admin, else a request the org admins decide).
+ */
+let AgentSkillsController = class AgentSkillsController {
+    agentSkills;
+    agents;
+    skills;
+    constructor(agentSkills, agents, skills) {
+        this.agentSkills = agentSkills;
+        this.agents = agents;
+        this.skills = skills;
+    }
+    async list(principal, org, agentId) {
+        await this.agents.get(org.orgId, agentId, principal.kind === "user" ? principal.account.id : null);
+        return { skills: await this.skills.listOwnForAgent(org.orgId, agentId) };
+    }
+    async createUpload(principal, org, agentId, body) {
+        const p = requireUser(principal);
+        return this.agentSkills.createAgentUpload(org.orgId, p.account.id, agentId, body);
+    }
+    async register(principal, org, agentId, body) {
+        const p = requireUser(principal);
+        return {
+            skill: await this.agentSkills.registerAgentUpload(org.orgId, p.account.id, agentId, body.uploadId, patTokenId(p)),
+        };
+    }
+    async share(principal, org, agentId, skillId) {
+        const p = requireUser(principal);
+        const actorTokenId = patTokenId(p);
+        return {
+            share: await this.agentSkills.share({
+                orgId: org.orgId,
+                agentId,
+                accountId: p.account.id,
+                ...(actorTokenId !== undefined && { actorTokenId }),
+            }, skillId),
+        };
+    }
+    async remove(principal, org, agentId, skillId) {
+        const p = requireUser(principal);
+        await this.agentSkills.deleteAgentSkill(org.orgId, agentId, skillId, p.account.id, patTokenId(p));
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId"))
+], AgentSkillsController.prototype, "list", null);
+__decorate([
+    Post("uploads"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, ZBody(AgentSkillUploadBodyDto))
+], AgentSkillsController.prototype, "createUpload", null);
+__decorate([
+    Post(),
+    HttpCode(200),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, ZBody(AgentSkillRegisterBodyDto))
+], AgentSkillsController.prototype, "register", null);
+__decorate([
+    Post(":skillId/share"),
+    HttpCode(200),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Param("skillId"))
+], AgentSkillsController.prototype, "share", null);
+__decorate([
+    Delete(":skillId"),
+    HttpCode(204),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Param("skillId"))
+], AgentSkillsController.prototype, "remove", null);
+AgentSkillsController = __decorate([
+    Controller("api/v1/orgs/:orgId/agents/:agentId/skills"),
+    __param(0, Inject(AgentSkillsService)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(SkillsService))
+], AgentSkillsController);
+export { AgentSkillsController };

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

@@ -0,0 +1,262 @@
+import { AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
+import { EventLog } from "../conversations/event-log.js";
+import type { KernelSchemaDb, SkillManifest } from "../db/kernel-schema.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 { SkillsService } from "./skills.service.js";
+/**
+ * The cap on an agent's own skills (`scope = agent`). Far below the catalog snapshot's cap
+ * (`SKILLS_CATALOG_MAX`), so normal use never truncates the catalog. Requests never add agent
+ * skills (a share moves an existing one out, a version proposal targets an org skill), so they
+ * do not count.
+ */
+export declare const AGENT_SKILLS_MAX = 50;
+/** Who registers or deletes an agent's skill, and from where. */
+export interface AgentSkillActor {
+    orgId: string;
+    agentId: string;
+    /** The person acting (the run's trigger account for an agent). */
+    accountId: string;
+    /** The conversation that gets a catalog snapshot with the new version (agent registrations). */
+    conversationId?: string;
+    runId?: string | null;
+    actorTokenId?: string;
+    /** Merged into the audit detail (e.g. `viaAgent(...)`). */
+    auditDetail?: Record<string, unknown>;
+}
+/** The result of {@link AgentSkillsService.register}. */
+export type RegisterOutcome = {
+    kind: "version";
+    skillId: string;
+    name: string;
+    version: number;
+    created: boolean;
+    /** The version is manual-only: not in the model's catalog. */
+    manualOnly: boolean;
+} | {
+    /** A version proposal on a shared org skill the actor maintains, for an org admin to decide. */
+    kind: "proposed";
+    requestId: string;
+    skillId: string;
+    name: string;
+    version: number;
+    manualOnly: boolean;
+};
+/** The result of {@link AgentSkillsService.share}. */
+export type ShareOutcome = {
+    kind: "shared";
+    skillId: string;
+} | {
+    kind: "requested";
+    requestId: string;
+};
+/** Whether the account is an admin (or owner) of the org, read live. */
+export declare function isOrgAdmin(db: KernelSchemaDb, orgId: string, accountId: string): Promise<boolean>;
+/**
+ * In the caller's transaction, refuses sharing a skill named `name` when the org already has a
+ * live org skill of that name or a platform skill of that name is offered to the org (409
+ * `skill.name_exists`): skill names are unique in an org.
+ */
+export declare function assertShareableName(db: KernelDb, orgId: string, name: string): Promise<void>;
+/**
+ * In the caller's transaction (the skill row locked), turns an agent skill into an org skill: the
+ * org owns it, `agent_id` is cleared, the agent it came from and its maintainer are recorded.
+ * Its versions stay.
+ */
+export declare function shareSkillIn(db: KernelDb, v: {
+    skillId: string;
+    agentId: string;
+    maintainerAccountId: string;
+}): Promise<void>;
+/** The body of a skill's SKILL.md (as run start would read it); null if unparsable. */
+export declare function skillMdBody(files: readonly {
+    path: string;
+    data: Uint8Array;
+}[]): string | null;
+/**
+ * Takes a KEY SHARE lock on the org row before the agent row is locked: the order `AgentsService`
+ * uses (org row FOR UPDATE -> agent row). Without it, a transaction holding the agent row that
+ * inserts a row referencing the org (the foreign key takes KEY SHARE) can deadlock with it (40P01).
+ */
+export declare function keyShareOrg(db: KernelDb, orgId: string): Promise<void>;
+/**
+ * The cap on new agent skills: at {@link AGENT_SKILLS_MAX} live own skills -> 409
+ * `skill.agent_cap`. Runs in the caller's transaction.
+ */
+export declare function assertBelowAgentSkillCap(db: KernelDb, agentId: string): Promise<void>;
+/** Writes a version of an agent skill and points `current_version` at it (creating the skill). */
+export declare function createAgentSkillVersion(db: KernelDb, v: {
+    orgId: string;
+    agentId: string;
+    skillId: string;
+    exists: boolean;
+    version: number;
+    manifest: SkillManifest;
+    prefix: string;
+    createdBy: string;
+}): Promise<void>;
+/**
+ * An agent's own skills (`scope = agent`): only the agent's current owner (read live) registers
+ * a zip package as one of them, deletes one or shares one with the org; anyone else gets 403
+ * `forbidden` (404 `agent.not_found` when the agent is not visible to them).
+ *
+ * `register` reads the zip with the one package reader (`readSkillPackage`), writes the files under
+ * a fresh `skills/<id>/` prefix before the transaction, then in one transaction (lock order org ->
+ * agent -> conversation -> skill rows -> request rows) creates the skill or its next version,
+ * audits, and appends a `skills_catalog` snapshot to `conversationId` when given so the same run
+ * can `Skill` it at its next step. On failure the prefix is deleted. A package named like a shared
+ * org skill the actor maintains (and the agent has no own skill of that name) is a new version of
+ * that org skill instead (spec §5.5): an org admin's applies at once, anyone else's becomes a
+ * version proposal an org admin decides, tried only in the proposing conversation.
+ *
+ * `share` (spec §5.4) turns an agent skill into an org skill at once when the owner is an org
+ * admin, else records a share request for the org admins. All state is in PG and object storage.
+ */
+export declare class AgentSkillsService {
+    private readonly db;
+    private readonly storage;
+    private readonly eventLog;
+    private readonly log;
+    readonly txHost: TransactionHost;
+    /** An org admin maintainer's version of a shared skill is an org skill version. */
+    private readonly skills;
+    private readonly attachments;
+    private readonly orgLock;
+    private readonly catalogDeps;
+    constructor(db: KernelDb, storage: StorageService, eventLog: EventLog, log: KernelLogger, txHost: TransactionHost, 
+    /** An org admin maintainer's version of a shared skill is an org skill version. */
+    skills: SkillsService, attachments: AttachmentsService, orgLock: OrgLock);
+    /**
+     * Registers a skill package upload onto an agent (presigned, `application/zip`, <= 50 MB): only
+     * the agent's current owner (403 `forbidden`, 404 `agent.not_found` when not visible). Agent
+     * skills are not governed by the deployment's `customSkills` setting, so it is not checked.
+     */
+    createAgentUpload(orgId: string, accountId: string, agentId: string, input: {
+        name: string;
+        size: number;
+    }): Promise<CreatedAttachment>;
+    /**
+     * Registers an uploaded package as one of the agent's own skills ({@link register}): the owner
+     * is checked before the upload is read (a non-owner learns nothing about it), the zip is read
+     * from the uploader's own upload (`attachment.not_found` otherwise) and the upload is consumed
+     * in the register transaction (of concurrent requests for it only one registers).
+     */
+    registerAgentUpload(orgId: string, accountId: string, agentId: string, uploadId: string, actorTokenId?: string): Promise<RegisterOutcome>;
+    /**
+     * Registers a zip package as one of the agent's own skills, or as a new version of a shared org
+     * skill the actor maintains (see the class comment). `opts.inTransaction` runs in the register
+     * transaction after the agent row lock, before the skill rows (e.g. consuming the upload the zip
+     * came from, so a concurrent retry of the same upload registers nothing).
+     *
+     * A version proposal refuses with 409 `skill.proposal_pending_elsewhere` while another
+     * conversation (or another agent of the maintainer) has a pending proposal of that skill; one
+     * pending from the same conversation is superseded (cancelled, its draft deleted). Versions of a
+     * shared skill (proposed or applied) are refused while `customSkills` is denied. A new own skill
+     * named like an org skill the agent uses (not maintained by the actor) -> 409
+     * `skill.name_exists`. A new version of an own skill cancels its pending share request.
+     */
+    register(actor: AgentSkillActor, zip: Uint8Array, opts?: {
+        inTransaction?: () => Promise<void>;
+    }): Promise<RegisterOutcome>;
+    /**
+     * Shares one of the agent's own skills with the org (only the agent's current owner; the
+     * deployment's `customSkills` must allow it, else 403 `catalog.custom_disabled`). The org may
+     * not already have a skill of that name (409 `skill.name_exists`).
+     * - An org admin owner: in one transaction the skill becomes an org skill (`scope = org`,
+     *   `agent_id` cleared, `origin_agent_id` = the agent, `maintainer_account_id` = the actor);
+     *   audit `skill.shared`. Its id, versions and files stay, and the agent keeps resolving it.
+     * - Anyone else: a share request for the org admins (`kind = 'share'`, the current version, no
+     *   new files: its prefix is the version's and never deleted); a pending one -> 409
+     *   `skill.share_pending`. Audit `skill.share_requested`.
+     */
+    share(actor: AgentSkillActor, skillId: string): Promise<ShareOutcome>;
+    /**
+     * Soft-deletes one of the agent's own skills (only the agent's current owner; others 403
+     * `forbidden`): missing / already deleted / not this agent's -> `skill.not_found`. A pending
+     * request of the same name is cancelled with it (a version draft: a reverting snapshot in the
+     * requesting conversation, its draft deleted after the commit; a share request keeps its
+     * files). Audits `skill.deleted`. Every conversation drops it at its next run start; the name
+     * can then be registered again as a new skill.
+     */
+    deleteAgentSkill(orgId: string, agentId: string, skillId: string, accountId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<void>;
+    /**
+     * The owner check without a lock (operation prechecks, and before storage writes): a live agent
+     * of the org whose current owner is `accountId`; visible but not owned -> 403 `forbidden`, not
+     * visible -> 404 `agent.not_found`.
+     */
+    assertOwner(orgId: string, agentId: string, accountId: string): Promise<void>;
+    /**
+     * Whether the account maintains a live shared org skill and is an org admin, read live: then a
+     * registration may apply a version to an org skill at once (the Platform operation's
+     * confirmation class is `org` for it, before the package name is known).
+     */
+    mayApplyOrgVersions(orgId: string, accountId: string): Promise<boolean>;
+    /** Reads the agent row (locked FOR NO KEY UPDATE when `lock`) and applies the owner check. */
+    private checkOwner;
+    /**
+     * The live shared org skill named `name` that `accountId` maintains, when the agent has no own
+     * skill of that name (locked FOR UPDATE when `lock`, after the own skill row was looked at).
+     */
+    private maintainedSkill;
+    /**
+     * Whether registering `name` applies a version to a shared org skill at once: the actor, an org
+     * admin, maintains a live org skill of that name and the agent has no own skill of it.
+     */
+    private appliesToOrgSkill;
+    /**
+     * An org admin maintainer's new version of a shared skill: written as an org skill version
+     * (`SkillsService.createVersionFromFiles`, which re-checks `skills.manage` under the org row
+     * lock and handles a skill the org promoted), then the registering conversation's catalog gets
+     * it at once. {@link claimIn} ran first.
+     */
+    private applyOrgVersion;
+    /**
+     * Before {@link applyOrgVersion} writes the version, in a transaction of its own: re-checks the
+     * owner (agent row lock) and that the actor still maintains the org skill of that name with no
+     * own skill of it (skill row lock); cancels the skill's pending version proposals (an older one
+     * must not overwrite this version later: reverting snapshots, drafts deleted after the commit)
+     * and runs `inTransaction` (consuming the upload). Returns null, cancelling and consuming
+     * nothing, when the skill no longer qualifies or a proposal appeared in a conversation that was
+     * not locked first (the caller registers it the ordinary way).
+     * Lock order org -> agent -> the proposals' conversations -> skill row -> request rows.
+     */
+    private claimIn;
+    /**
+     * After {@link applyOrgVersion}: appends a snapshot to the conversation (of this org and agent)
+     * with the org skill's new version. A version served from the platform row (a skill the org
+     * promoted) has no version row of the org: nothing is appended, the next run start resolves it.
+     */
+    private appendAppliedIn;
+    /**
+     * Locks the conversation row (the snapshot append's lock): a conversation of this org with this
+     * agent only (defense in depth: callers pass the run's own), else `conversation.not_found`.
+     */
+    private lockConversation;
+    /** The transaction of {@link register}. */
+    private registerIn;
+    /**
+     * Spec §5.2: an agent's own skill may not take the name of an org skill the agent uses (selected
+     * in its current definition, or one it shared) unless the actor maintains it (then the
+     * registration is a version of it): 409 `skill.name_exists`.
+     */
+    private assertNoUsedOrgSkillNamed;
+    /**
+     * In {@link registerIn} (the org skill row locked): a version proposal on the shared skill. The
+     * pending proposals of that skill (and any pending request of this agent with the name) are
+     * locked: one from another conversation refuses, ones from this conversation are superseded.
+     * The trial applies only in the proposing conversation (the catalog overlay reads pending
+     * `version` requests by conversation).
+     */
+    private proposeIn;
+    /** The transaction of {@link share} (lock order org -> agent -> skill row -> request rows). */
+    private shareIn;
+    /** The transaction of {@link deleteAgentSkill}. */
+    private deleteAgentSkillIn;
+    /** Writes the files under `prefix` in the org's kernel space, a few at a time. */
+    private putFiles;
+    /** Deletes objects best effort (a failure is only logged: org data cleanup removes orphans). */
+    private deletePrefix;
+}