@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.5

package/dist/agents/templates.controller.js

@@ -7,31 +7,195 @@ 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 { Controller, Get, Inject } from "@nestjs/common";
+import { AGENT_TEMPLATE_NAME_RE } from "@capybara-hq/plugin-sdk";
+import { Controller, Delete, Get, Inject, Post, Put } from "@nestjs/common";
+import { z } from "zod";
+import { OwnedItems } from "../catalog/owned-items.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { OrgAgentTemplates, } from "./org-templates.js";
 import { AgentTemplatesService } from "./templates.js";
+const IdParams = z.object({ id: z.string().min(1).max(100) });
+const AgentIdParams = z.object({ agentId: z.string().min(1).max(100) });
+const ShareableBody = z.object({ shareable: z.boolean() }).strict();
+const SaveAsBody = z
+    .object({
+    /** The bare template name (the template name rule); unique in the org's usable set. */
+    name: z.string().regex(AGENT_TEMPLATE_NAME_RE),
+    /** When to use it (trimmed, as a template file's). */
+    description: z.string().trim().min(1).max(4096),
+})
+    .strict();
+const UpdateBody = z
+    .object({
+    /** The whole definition (the `AgentTemplate` shape), validated like a template file. */
+    definition: z.record(z.string(), z.unknown()),
+    /** The `version` the editor read; another one -> 409 `agent_template.version_conflict`. */
+    expectedVersion: z.number().int().min(1),
+})
+    .strict();
+class AgentTemplateIdParams extends createZodDto(IdParams, "AgentTemplateIdParams") {
+}
+class SaveAsAgentIdParams extends createZodDto(AgentIdParams, "SaveAsAgentIdParams") {
+}
+class AgentTemplateShareableBody extends createZodDto(ShareableBody, "AgentTemplateShareableBody") {
+}
+class SaveAsTemplateBody extends createZodDto(SaveAsBody, "SaveAsTemplateBody") {
+}
+class AgentTemplateUpdateBody extends createZodDto(UpdateBody, "AgentTemplateUpdateBody") {
+}
+const actorOpts = (p) => {
+    const tokenId = patTokenId(p);
+    return tokenId !== undefined ? { actorTokenId: tokenId } : {};
+};
 /**
- * The org's agent templates installed from plugins (`/api/v1/orgs/:orgId/agent-templates`, phase C
- * spec §17): the agent page lists them to select as sub-agents. Read with `agents.create`, the
- * permission of its only consumer, the agent editor (members, people only); a template carries no
- * secret, but guests and service tokens have no use for the list.
+ * The org's agent templates (`/api/v1/orgs/:orgId/agent-templates`, phase C spec §17; plugin scope
+ * phase 4, rulings P4-9 to P4-13). Reads with `agents.create` (members, people only): the list
+ * the agent editor and the 模板 tab show, and one template's detail with its definition. The org's
+ * own templates (saved from an agent, `POST orgs/:orgId/agents/:agentId/save-as-template`) are
+ * edited, deleted and made 可共享 by the owner org's admins (`agents.manage`, the action that
+ * manages agent templates).
  */
 let AgentTemplatesController = class AgentTemplatesController {
     templates;
-    constructor(templates) {
+    orgTemplates;
+    owned;
+    constructor(templates, orgTemplates, owned) {
         this.templates = templates;
+        this.orgTemplates = orgTemplates;
+        this.owned = owned;
     }
     async list(org) {
         return { templates: await this.templates.listForOrg(org.orgId) };
     }
+    /**
+     * One template usable in the org (an org template, a linked copy, a platform template on in
+     * the org) with its definition, owner and the org's flags (`owned`, `shareable`, `promoted`).
+     * Not usable here -> 404 `component.not_found`.
+     */
+    async get(principal, org, params) {
+        requireUser(principal);
+        return { template: await this.orgTemplates.detail(org.orgId, params.id) };
+    }
+    /**
+     * A new version of the org's own template (ruling P4-12): `{ definition, expectedVersion }` ->
+     * 200 `{ template }`; a stale version -> 409 `agent_template.version_conflict`; a template the
+     * org does not own -> 409 `catalog.not_owned`.
+     */
+    async update(principal, org, params, body) {
+        const p = requireUser(principal);
+        const template = await this.orgTemplates.update(org.orgId, p.account.id, params.id, body, patTokenId(p));
+        return { template };
+    }
+    /**
+     * What deleting the org's own template does (nothing written): `outcome` `transferred` when it
+     * was shared and another org uses it (`orgs`), else `removed`; `agents` the org's agents whose
+     * roster loses it.
+     */
+    async deletePreview(principal, org, params) {
+        requireUser(principal);
+        return this.owned.previewAgentTemplateDelete(org.orgId, params.id);
+    }
+    /**
+     * Deletes the org's own template (the P3 owner rules, ruling P4-12): one it shared that another
+     * org uses becomes the platform's (platform notice `ownership_transferred`). 200 `{ outcome }`.
+     */
+    async remove(principal, org, params) {
+        const p = requireUser(principal);
+        const outcome = await this.owned.deleteAgentTemplate(org.orgId, p.account.id, params.id, actorOpts(p));
+        return { outcome };
+    }
+    /**
+     * Sets 可共享 on the org's own agent template (`{ shareable }` -> 200 `{ id, shareable }`; an org
+     * template, ruling P4-13): a plugin's template or a copy of another owner's platform template
+     * -> 409 `catalog.not_owned`; one the org promoted writes its platform row too (ruling P3-2).
+     */
+    async setShareable(principal, org, params, body) {
+        const p = requireUser(principal);
+        await this.owned.setShareable(org.orgId, p.account.id, { kind: "agent_template", id: params.id }, body.shareable, actorOpts(p));
+        return { id: params.id, shareable: body.shareable };
+    }
 };
 __decorate([
     Get(),
     OrgAction("agents.create"),
     __param(0, CurrentOrg())
 ], AgentTemplatesController.prototype, "list", null);
+__decorate([
+    Get(":id"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(AgentTemplateIdParams))
+], AgentTemplatesController.prototype, "get", null);
+__decorate([
+    Put(":id"),
+    OrgAction("agents.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(AgentTemplateIdParams)),
+    __param(3, ZBody(AgentTemplateUpdateBody))
+], AgentTemplatesController.prototype, "update", null);
+__decorate([
+    Get(":id/delete-preview"),
+    OrgAction("agents.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(AgentTemplateIdParams))
+], AgentTemplatesController.prototype, "deletePreview", null);
+__decorate([
+    Delete(":id"),
+    OrgAction("agents.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(AgentTemplateIdParams))
+], AgentTemplatesController.prototype, "remove", null);
+__decorate([
+    Put(":id/shareable"),
+    OrgAction("agents.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(AgentTemplateIdParams)),
+    __param(3, ZBody(AgentTemplateShareableBody))
+], AgentTemplatesController.prototype, "setShareable", null);
 AgentTemplatesController = __decorate([
     Controller("api/v1/orgs/:orgId/agent-templates"),
-    __param(0, Inject(AgentTemplatesService))
+    __param(0, Inject(AgentTemplatesService)),
+    __param(1, Inject(OrgAgentTemplates)),
+    __param(2, Inject(OwnedItems))
 ], AgentTemplatesController);
 export { AgentTemplatesController };
+/**
+ * 另存为模板 (ruling P4-9; `agents.manage`, org admins): `POST
+ * /api/v1/orgs/:orgId/agents/:agentId/save-as-template { name, description }` -> 201
+ * `{ template, omitted }`. `template` is the new org template's detail (version 1, the bare
+ * `name`); `omitted` lists what the template leaves out (`SaveAsOmission`: allowlisted org agents
+ * in the roster, the agent's own skills, connectors and sub-agents no longer usable, entries past
+ * a limit). A name the org can already use as a type -> 409 `agent_template.name_taken` (details
+ * `[{ owner, templateId }]`). Its own controller: the agents controller is the agent CRUD.
+ */
+let AgentSaveAsTemplateController = class AgentSaveAsTemplateController {
+    orgTemplates;
+    constructor(orgTemplates) {
+        this.orgTemplates = orgTemplates;
+    }
+    async saveAs(principal, org, params, body) {
+        const p = requireUser(principal);
+        return this.orgTemplates.saveAs(org.orgId, p.account.id, params.agentId, body, patTokenId(p));
+    }
+};
+__decorate([
+    Post(":agentId/save-as-template"),
+    OrgAction("agents.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(SaveAsAgentIdParams)),
+    __param(3, ZBody(SaveAsTemplateBody))
+], AgentSaveAsTemplateController.prototype, "saveAs", null);
+AgentSaveAsTemplateController = __decorate([
+    Controller("api/v1/orgs/:orgId/agents"),
+    __param(0, Inject(OrgAgentTemplates))
+], AgentSaveAsTemplateController);
+export { AgentSaveAsTemplateController };

package/dist/agents/templates.d.ts

@@ -1,19 +1,24 @@
-import type { AgentTemplate, AgentTemplateTier } from "@capybara-hq/plugin-sdk";
+import type { AgentTemplate, AgentTemplateTier, Logger } from "@capybara-hq/plugin-sdk";
+import { type Owner } from "../catalog/ownership.js";
 import type { KernelSchemaDb, SourceFormat } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 /**
- * Agent templates installed in an org from plugins (sub-agents spec §16): `agent_templates` (one
- * live row per org, plugin and name) and `agent_template_versions` (the parsed template). Plugin
- * install, upgrade and uninstall write them through the `…In` functions in the caller's
- * transaction; the roster and the effective definition read them through {@link loadTemplates}.
- * No in-process state.
+ * Agent templates of an org (sub-agents spec §16): its own `agent_templates` (one live row per org,
+ * plugin and name) with `agent_template_versions` (the parsed template), and the platform templates
+ * (plugin scope phase 2, rulings A2, C2: `platform_agent_templates`) that are on in the org. Plugin
+ * install, upgrade and uninstall write the org rows through the `…In` functions in the caller's
+ * transaction; the roster and the effective definition read both through {@link loadTemplates}.
+ * An org copy linked to a platform template (ruling B2) resolves to the platform template's current
+ * version under the copy's own id unless pinned. A copy linked to a platform template its own org
+ * owns (promote on share, ruling P3-3) serves its own stored version while that is the platform
+ * template's current one, and is listed instead of it. No in-process state.
  */
-/** A live template of an org (`GET` listings, the agent page). */
+/** A usable template of an org (`GET` listings, the agent page). */
 export interface AgentTemplateView {
     id: string;
     name: string;
-    plugin: string;
-    /** The roster type `<plugin>:<name>`. */
+    plugin: string | null;
+    /** The roster type: `<plugin>:<name>`, or the bare `<name>` without a plugin. */
     type: string;
     description: string;
     model: AgentTemplateTier;
@@ -21,46 +26,145 @@ export interface AgentTemplateView {
     sourceFormat: SourceFormat;
     catalogItemId: string | null;
     catalogVersion: string | null;
+    /** `org`: the org's own template; `platform`: a platform template on in the org. */
+    origin: "org" | "platform";
+    /**
+     * Platform templates: this org's unpinned copies linked to it (ruling B2). They resolve to this
+     * template under their own ids, so an agent that selects one of them selects this template.
+     */
+    linkedIds?: string[];
 }
-/** A template row with its current definition. */
+/** A template with its current definition (an org row, a linked copy or a platform template). */
 export interface TemplateRow {
+    /** The org template's id (a linked copy keeps its own), or the platform template's. */
     id: string;
     name: string;
-    plugin: string;
+    plugin: string | null;
     version: number;
     template: AgentTemplate;
     sourceFormat: SourceFormat;
     catalogItemId: string | null;
     catalogVersion: string | null;
+    /** `platform` for a platform template and for a linked copy that resolves to one. */
+    origin: "org" | "platform";
+    /**
+     * The platform template whose content this is (a platform template, or an unpinned linked
+     * copy); absent for the org's own content (a pinned copy included). `subagent_started` records
+     * it, so evals tell the two version namespaces apart.
+     */
+    platformTemplateId?: string;
+    /**
+     * The org's own template it promoted (ruling P3-3), served from its platform template: listed
+     * as the org's own. Never recorded in an event.
+     */
+    ownedCopy?: true;
 }
-/** The live templates of `ids` in the org (deleted and foreign ids are left out), by id. */
-export declare function loadTemplates(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Map<string, TemplateRow>>;
+/** The roster type of a template: `<plugin>:<name>`, the bare `<name>` without a plugin. */
+export declare const templateTypeOf: (plugin: string | null, name: string) => string;
+/**
+ * The ids among `ids` of the platform templates on in the org (see {@link platformOn}), whatever
+ * the org's own templates are.
+ */
+export declare function platformTemplatesOn(db: KernelSchemaDb, orgId: string, ids: readonly string[]): Promise<Set<string>>;
+/**
+ * Rule 10 for platform agent template `component` (`plugin` / `name`: its roster type) newly
+ * offered to the org (ruling P4-13, as `skillNameClashes` for skills): the org's own live rows of
+ * that type (unlinked, or pinned) that are no copy of it (linked to it, or from its plugin), and
+ * the other platform templates of that type on in the org (two orgs' shared templates of one bare
+ * name, P3-5). `skills`: the clashing template ids; `owners`: each one's owner, in the same order
+ * (an org row without a plugin is the org's own; a plugin's row its catalog item's owner; a
+ * platform row its `owner_org_id`); `plugins`: the clashing platform templates' plugins.
+ */
+export declare function templateTypeClashes(db: KernelSchemaDb, orgId: string, component: {
+    id: string;
+    itemId: string | null;
+    plugin: string | null;
+    name: string;
+}): Promise<{
+    skills: string[];
+    plugins: string[];
+    owners: Owner[];
+}>;
+/**
+ * The org's live templates by id (`ids`; ids that are no usable template are missing): an org
+ * template with its current version; an org copy linked to a platform template without a pin
+ * (ruling B2) as that platform template's current version under the copy's id, while the platform
+ * template is on in the org; a pinned copy as its own version while its platform template is on in
+ * the org (ruling P2-18); a platform template id while it is on in the org, or, when an org row
+ * of the same component (unlinked or pinned) wins its type, as that row (its `id` is the row's: the
+ * roster lists the platform id as an alias). Deleted and foreign ids are left out. `log` receives
+ * the type-clash warnings.
+ */
+export declare function loadTemplates(db: KernelSchemaDb, orgId: string, ids: readonly string[], log?: Pick<Logger, "warn">): Promise<Map<string, TemplateRow>>;
+/**
+ * The org's usable templates, by plugin (none first), name and id: its own live templates
+ * (unlinked, or pinned while their platform template is on in the org, ruling P2-18) and the platform templates on in the org (see {@link platformOn}). An org
+ * copy linked without a pin is not listed: its platform template is; except the org's own template
+ * it promoted (ruling P3-3), listed once under its own id instead of the platform template. `log`
+ * receives the type-clash warnings.
+ */
+export declare function usableTemplates(db: KernelSchemaDb, orgId: string, log?: Pick<Logger, "warn">): Promise<TemplateRow[]>;
+/** The org's own agent template row (rulings P3-6, P4-13), as its owner acts on it. */
+export interface OwnTemplate {
+    id: string;
+    name: string;
+    current_version: number;
+    shareable: boolean;
+    /** The platform row it was promoted to (ruling P3-3), or null while it is an org row only. */
+    link: string | null;
+}
+/**
+ * The one "org's own template" predicate (rulings P3-6, P3-46, P4-13), shared by the template
+ * routes and `OwnedItems`: the org's live row `id` is its own when it is an org template (no
+ * plugin, no catalog item) that is unlinked, or linked without a pin to a live platform row the
+ * org owns (promoted on share). Returns the row (`forUpdate`: locked), `{ own: false, name }` for
+ * a row of the org that is not its own (a plugin's template, a copy of another owner's platform
+ * template), or undefined when the org has no live row `id`.
+ */
+export declare function readOwnTemplate(db: KernelSchemaDb, orgId: string, id: string, forUpdate: boolean): Promise<OwnTemplate | {
+    own: false;
+    name: string;
+} | undefined>;
+/**
+ * The listing view of a usable template; `linkedIds`: the org's unpinned copies linked to it (a
+ * platform template only).
+ */
+export declare function templateViewOf(t: TemplateRow, linkedIds: string[]): AgentTemplateView;
 /** Reads the org's agent templates (consumed by the roster, the agent page and Task 19's API). */
 export declare class AgentTemplatesService {
     private readonly db;
     constructor(db: KernelDb);
-    /** Every live template of the org, by plugin then name. */
+    /**
+     * Every usable template of the org ({@link usableTemplates}), by plugin then name; a platform
+     * template carries the ids of the org's unpinned copies linked to it (`linkedIds`).
+     */
     listForOrg(orgId: string): Promise<AgentTemplateView[]>;
-    /** A live template by id or by `<plugin>:<name>`; null when there is none. */
+    /** A usable template by id or by its roster type; null when there is none. */
     resolve(orgId: string, ref: string): Promise<{
         id: string;
         version: number;
-        plugin: string;
+        plugin: string | null;
         template: AgentTemplate;
     } | null>;
 }
-/** Where a template version comes from (a plugin version of the catalog). */
+/**
+ * Where a template version comes from: a plugin version of the catalog, or (ruling P4-9) the org
+ * itself (另存为模板, an edit of an org template): `plugin`, `catalogItemId` and `catalogVersion`
+ * null.
+ */
 export interface TemplateSource {
     orgId: string;
-    plugin: string;
-    catalogItemId: string;
-    catalogVersion: string;
+    plugin: string | null;
+    /** The catalog item of the plugin; absent or null for an org template (ruling P4-9). */
+    catalogItemId?: string | null;
+    catalogVersion: string | null;
     sourceFormat: SourceFormat;
 }
 /**
- * Writes `template` as the org's live template `<plugin>:<name>` in the caller's transaction (the
- * caller holds the org row lock): a new template (version 1, `created`), a new version of the live
- * one when its definition differs (`changed`, the version added), or nothing when it is equal.
+ * Writes `template` as the org's live template `<plugin>:<name>` (the bare `<name>` when `plugin`
+ * is null) in the caller's transaction (the caller holds the org row lock): a new template
+ * (version 1, `created`), a new version of the live one when its definition differs (`changed`,
+ * the version added), or nothing when it is equal.
  */
 export declare function putTemplateVersionIn(t: KernelSchemaDb, s: TemplateSource, template: AgentTemplate): Promise<{
     id: string;