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

package/dist/agents/templates.js

@@ -9,8 +9,17 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { componentOn } from "../catalog/component-state.js";
+import { ownerOf, ownersOf } from "../catalog/ownership.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
-import { canonicalJson } from "../tools/registry.js";
+import { canonicalJson } from "../tools/canonical-json.js";
+import { loadLegacyScope } from "../tools/legacy-data.js";
+import { needsLegacyScope, normalizeToolKeys } from "./definition.js";
+/** The roster type of a template: `<plugin>:<name>`, the bare `<name>` without a plugin. */
+export const templateTypeOf = (plugin, name) => plugin ? `${plugin}:${name}` : name;
+/** Plugin install statuses that make a plugin on in the org (phase 1, org catalog state). */
+const LIVE_INSTALL = ["installing", "installed", "upgrading"];
 const baseQuery = (db, orgId) => db
     .selectFrom("agent_templates as t")
     .innerJoin("agent_template_versions as v", (j) => j.onRef("v.template_id", "=", "t.id").onRef("v.version", "=", "t.current_version"))
@@ -20,30 +29,457 @@ const baseQuery = (db, orgId) => db
     "t.plugin_name",
     "t.current_version",
     "t.catalog_item_id",
+    "t.platform_template_id",
+    "t.pinned_version",
     "v.definition",
     "v.source_format",
     "v.catalog_version",
 ])
     .where("t.org_id", "=", orgId)
     .where("t.deleted_at", "is", null);
-const rowOf = (r) => ({
+/**
+ * The ids among `platformIds` of the live platform templates owned by `orgId` (promoted from its
+ * own templates, ruling P3-3).
+ */
+async function ownedPlatformIds(db, orgId, platformIds) {
+    if (platformIds.length === 0)
+        return new Set();
+    const rows = await db
+        .selectFrom("platform_agent_templates")
+        .select("id")
+        .where("id", "in", [...new Set(platformIds)])
+        .where("owner_org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .execute();
+    return new Set(rows.map((r) => r.id));
+}
+/**
+ * Stored rows as {@link TemplateRow}s; tool keys read as current keys (tool naming spec §8.3): old
+ * builtin names always, rc `<x>__<tool>` keys with the org's legacy scope, read once when needed.
+ */
+async function normalized(db, orgId, rows) {
+    const scope = rows.some((r) => needsLegacyScope(r.definition))
+        ? await loadLegacyScope(db, orgId)
+        : undefined;
+    return rows.map(({ definition, ...r }) => ({
+        ...r,
+        template: normalizeToolKeys(definition, scope),
+    }));
+}
+const orgRaw = (r) => ({
     id: r.id,
     name: r.name,
     plugin: r.plugin_name,
     version: r.current_version,
-    template: r.definition,
+    definition: r.definition,
     sourceFormat: r.source_format,
     catalogItemId: r.catalog_item_id,
     catalogVersion: r.catalog_version,
+    // a pinned copy keeps its link but serves its own version: no platform content source
+    origin: "org",
 });
-/** The live templates of `ids` in the org (deleted and foreign ids are left out), by id. */
-export async function loadTemplates(db, orgId, ids) {
+/** The live platform template rows on in the org (`ids`: only those), before any type clash. */
+async function platformRowsOn(db, orgId, ids) {
+    if (ids !== undefined && ids.length === 0)
+        return [];
+    let q = db
+        .selectFrom("platform_agent_templates as p")
+        .innerJoin("platform_agent_template_versions as v", (j) => j.onRef("v.template_id", "=", "p.id").onRef("v.version", "=", "p.current_version"))
+        .leftJoin("catalog_items as c", (j) => j.onRef("c.id", "=", "p.catalog_item_id").on("c.deleted_at", "is", null))
+        .select((eb) => [
+        "p.id",
+        "p.name",
+        "p.plugin_name",
+        "p.catalog_item_id",
+        "p.current_version",
+        "p.scope_mode",
+        "p.scope",
+        "v.definition",
+        "v.source_format",
+        "v.catalog_version",
+        "c.id as item_id",
+        "c.disabled as item_disabled",
+        "c.builtin as item_builtin",
+        eb
+            .exists(eb
+            .selectFrom("plugin_installs as a")
+            .select("a.id")
+            .whereRef("a.item_id", "=", "p.catalog_item_id")
+            .where("a.org_id", "=", orgId)
+            .where("a.status", "in", [...LIVE_INSTALL]))
+            .as("installed"),
+        eb
+            .exists(eb
+            .selectFrom("component_scope_orgs as l")
+            .select("l.org_id")
+            .where("l.kind", "=", "agent_template")
+            .whereRef("l.component_id", "=", "p.id")
+            .where("l.org_id", "=", orgId))
+            .as("listed"),
+        eb
+            .selectFrom("component_org_switches as w")
+            .select("w.enabled")
+            .where("w.kind", "=", "agent_template")
+            .whereRef("w.component_id", "=", "p.id")
+            .where("w.org_id", "=", orgId)
+            .as("switch"),
+    ])
+        .where("p.deleted_at", "is", null)
+        .where("p.disabled", "=", false);
+    if (ids !== undefined)
+        q = q.where("p.id", "in", [...ids]);
+    // the predicate of component scope (catalog/component-state.ts); `disabled` is filtered above
+    return (await q.execute()).filter((r) => componentOn({ scopeMode: r.scope_mode, scope: r.scope, disabled: false, itemId: r.catalog_item_id }, r.catalog_item_id === null
+        ? null
+        : {
+            live: r.item_id !== null,
+            disabled: r.item_disabled === true,
+            builtin: r.item_builtin === true,
+            // the plugin's own scope and list do not decide whether a component is on
+            scope: "optional",
+            listed: false,
+            installed: Boolean(r.installed),
+        }, Boolean(r.listed), r.switch ?? null));
+}
+/**
+ * The ids among `ids` of the platform templates on in the org (see {@link platformOn}), whatever
+ * the org's own templates are.
+ */
+export async function platformTemplatesOn(db, orgId, ids) {
+    return new Set((await platformRowsOn(db, orgId, ids)).map((r) => r.id));
+}
+/**
+ * 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 async function templateTypeClashes(db, orgId, component) {
+    const own = await db
+        .selectFrom("agent_templates as t")
+        .select(["t.id", "t.platform_template_id", "t.catalog_item_id"])
+        .where("t.org_id", "=", orgId)
+        .where("t.deleted_at", "is", null)
+        .where("t.name", "=", component.name)
+        .where((eb) => component.plugin === null
+        ? eb("t.plugin_name", "is", null)
+        : eb("t.plugin_name", "=", component.plugin))
+        .where((eb) => eb.or([eb("t.platform_template_id", "is", null), eb("t.pinned_version", "is not", null)]))
+        .execute();
+    const ownRows = own.filter((r) => r.platform_template_id !== component.id &&
+        (component.itemId === null || r.catalog_item_id !== component.itemId));
+    const others = await db
+        .selectFrom("platform_agent_templates")
+        .select(["id", "plugin_name", "owner_org_id"])
+        .where("name", "=", component.name)
+        .where((eb) => component.plugin === null
+        ? eb("plugin_name", "is", null)
+        : eb("plugin_name", "=", component.plugin))
+        .where("deleted_at", "is", null)
+        .where("id", "!=", component.id)
+        .execute();
+    const on = await platformTemplatesOn(db, orgId, others.map((o) => o.id));
+    const platform = others.filter((o) => on.has(o.id));
+    // a plugin's row: its catalog item's owner (`catalog_items.id` is a uuid, the column text)
+    const itemIds = [
+        ...new Set(ownRows.flatMap((r) => (r.catalog_item_id === null ? [] : [r.catalog_item_id]))),
+    ];
+    const itemOwner = new Map((itemIds.length === 0
+        ? []
+        : await db
+            .selectFrom("catalog_items")
+            .select(["id", "owner_org_id"])
+            .where(sql `id::text`, "in", itemIds)
+            .execute()).map((i) => [String(i.id), i.owner_org_id]));
+    const ownerIds = [
+        ...ownRows.map((r) => component.plugin === null
+            ? orgId
+            : r.catalog_item_id === null
+                ? null
+                : (itemOwner.get(r.catalog_item_id) ?? null)),
+        ...platform.map((o) => o.owner_org_id),
+    ];
+    const owners = await ownersOf(db, ownerIds.filter((x) => x !== null));
+    return {
+        skills: [...ownRows.map((r) => r.id), ...platform.map((o) => o.id)],
+        plugins: platform.flatMap((o) => (o.plugin_name === null ? [] : [o.plugin_name])),
+        owners: ownerIds.map((x) => ownerOf(x, owners)),
+    };
+}
+/**
+ * The ids among `ids` (platform templates that org copies are pinned to) whose pinned copies the
+ * org may use (ruling P2-18): the platform template is on in the org, or it was removed by a
+ * plugin update (soft-deleted, ruling P2-7: a pinned copy then keeps its own version as the org's).
+ */
+async function pinnedTemplateLinksServed(db, orgId, ids) {
     if (ids.length === 0)
+        return new Set();
+    const removed = await db
+        .selectFrom("platform_agent_templates")
+        .select("id")
+        .where("id", "in", [...ids])
+        .where("deleted_at", "is not", null)
+        .execute();
+    return new Set([...(await platformTemplatesOn(db, orgId, ids)), ...removed.map((r) => r.id)]);
+}
+/**
+ * The platform templates on in the org (`ids`: only those), minus the ones whose type an org
+ * template of its own (unlinked, or pinned) already has (the org's wins; logged unless it is a copy
+ * of the same component: linked to it, or from the same catalog item; `shadowed` maps such a
+ * platform id to that org row's id). On in the org:
+ * - never when the template or its plugin is disabled (or its plugin is deleted);
+ * - `follow`: its plugin is on in the org (a live install, or builtin) and no component switch of
+ *   the org says off;
+ * - `own`: `wantedOn` over the template's own scope, the org's list membership and its switch.
+ * One query for the templates with their plugin and org state, one for the org's clashing rows.
+ */
+async function platformOn(db, orgId, ids, log) {
+    const shadowed = new Map();
+    const rows = await platformRowsOn(db, orgId, ids);
+    if (rows.length === 0)
+        return { rows: [], shadowed };
+    const own = await db
+        .selectFrom("agent_templates")
+        .select(["id", "name", "plugin_name", "platform_template_id", "catalog_item_id"])
+        .where("org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .where((eb) => eb.or([eb("platform_template_id", "is", null), eb("pinned_version", "is not", null)]))
+        .where("name", "in", [...new Set(rows.map((r) => r.name))])
+        .execute();
+    const ownByType = new Map(own.map((r) => [templateTypeOf(r.plugin_name, r.name), r]));
+    const out = [];
+    for (const r of rows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))) {
+        const o = ownByType.get(templateTypeOf(r.plugin_name, r.name));
+        if (o) {
+            const sameComponent = o.platform_template_id === r.id ||
+                (o.catalog_item_id !== null && o.catalog_item_id === r.catalog_item_id);
+            if (!sameComponent) {
+                log?.warn("platform agent template shadowed by an org template of the same type", {
+                    orgId,
+                    type: templateTypeOf(r.plugin_name, r.name),
+                    platformTemplateId: r.id,
+                    templateId: o.id,
+                });
+            }
+            else {
+                shadowed.set(r.id, o.id);
+            }
+            continue;
+        }
+        out.push({
+            id: r.id,
+            name: r.name,
+            plugin: r.plugin_name,
+            version: r.current_version,
+            definition: r.definition,
+            sourceFormat: r.source_format,
+            catalogItemId: r.catalog_item_id,
+            catalogVersion: r.catalog_version,
+            origin: "platform",
+            platformTemplateId: r.id,
+        });
+    }
+    return { rows: out, shadowed };
+}
+/**
+ * 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 async function loadTemplates(db, orgId, ids, log) {
+    const unique = [...new Set(ids)];
+    if (unique.length === 0)
         return new Map();
-    const rows = await baseQuery(db, orgId)
-        .where("t.id", "in", [...ids])
+    const rows = await baseQuery(db, orgId).where("t.id", "in", unique).execute();
+    const linked = new Set(rows.filter((r) => r.platform_template_id !== null && r.pinned_version === null));
+    const known = new Set(rows.map((r) => r.id));
+    const platformIds = [
+        ...new Set([
+            ...unique.filter((id) => !known.has(id)),
+            ...[...linked].map((r) => r.platform_template_id),
+        ]),
+    ];
+    const on = await platformOn(db, orgId, platformIds, log);
+    const platform = new Map(on.rows.map((p) => [p.id, p]));
+    const owned = await ownedPlatformIds(db, orgId, [...linked].map((r) => r.platform_template_id));
+    // ruling P2-18: a pinned copy serves its own version while its platform template is on
+    const pinnedOn = await pinnedTemplateLinksServed(db, orgId, [
+        ...new Set(rows.flatMap((r) => r.platform_template_id !== null && r.pinned_version !== null
+            ? [r.platform_template_id]
+            : [])),
+    ]);
+    // a selected platform id shadowed by an org row of the same component resolves to that row
+    const shadowIds = unique.filter((id) => !known.has(id) && on.shadowed.has(id));
+    const shadowRows = new Map((shadowIds.length === 0
+        ? []
+        : await baseQuery(db, orgId)
+            .where("t.id", "in", [...new Set(shadowIds.map((id) => on.shadowed.get(id)))])
+            .execute()).map((r) => [r.id, orgRaw(r)]));
+    const raw = [];
+    for (const r of rows) {
+        if (linked.has(r)) {
+            const p = platform.get(r.platform_template_id);
+            if (!p)
+                continue;
+            if (!owned.has(p.id)) {
+                raw.push({ key: r.id, row: { ...p, id: r.id } });
+            }
+            else if (r.current_version === p.version) {
+                // the org's own template, promoted (ruling P3-3) at the same version: its own stored
+                // version, so the roster and `subagent_started` see what they saw before
+                raw.push({ key: r.id, row: orgRaw(r) });
+            }
+            else {
+                // a newer platform version: under its id, with the copy's roster type
+                raw.push({ key: r.id, row: { ...p, id: r.id, plugin: r.plugin_name, ownedCopy: true } });
+            }
+            continue;
+        }
+        if (r.platform_template_id !== null && !pinnedOn.has(r.platform_template_id))
+            continue;
+        raw.push({ key: r.id, row: orgRaw(r) });
+    }
+    for (const id of unique) {
+        if (known.has(id))
+            continue;
+        const p = platform.get(id);
+        if (p) {
+            raw.push({ key: id, row: p });
+            continue;
+        }
+        const o = shadowRows.get(on.shadowed.get(id) ?? "");
+        if (o)
+            raw.push({ key: id, row: o });
+    }
+    const done = await normalized(db, orgId, raw.map((x) => x.row));
+    return new Map(raw.map((x, i) => [x.key, done[i]]));
+}
+/**
+ * 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 async function usableTemplates(db, orgId, log) {
+    const own = await baseQuery(db, orgId)
+        .where((eb) => eb.or([eb("t.platform_template_id", "is", null), eb("t.pinned_version", "is not", null)]))
+        .execute();
+    // ruling P2-18: a pinned copy follows its platform template's availability (the pin fixes the
+    // version only)
+    const pinnedOn = await pinnedTemplateLinksServed(db, orgId, [
+        ...new Set(own.flatMap((r) => (r.platform_template_id === null ? [] : [r.platform_template_id]))),
+    ]);
+    // the org's own templates it promoted: under their own ids, instead of their platform templates
+    const promoted = await db
+        .selectFrom("agent_templates as t")
+        .innerJoin("platform_agent_templates as p", "p.id", "t.platform_template_id")
+        .select(["t.id", "t.platform_template_id"])
+        .where("t.org_id", "=", orgId)
+        .where("t.deleted_at", "is", null)
+        .where("t.pinned_version", "is", null)
+        .where("p.owner_org_id", "=", orgId)
+        .where("p.deleted_at", "is", null)
         .execute();
-    return new Map(rows.map((r) => [r.id, rowOf(r)]));
+    const promotedTo = new Set(promoted.map((r) => r.platform_template_id));
+    const served = promoted.length === 0
+        ? []
+        : [
+            ...(await loadTemplates(db, orgId, promoted.map((r) => r.id), log)).values(),
+        ];
+    const rows = [
+        ...(await normalized(db, orgId, [
+            ...own
+                .filter((r) => r.platform_template_id === null || pinnedOn.has(r.platform_template_id))
+                .map(orgRaw),
+            ...(await platformOn(db, orgId, undefined, log)).rows.filter((p) => !promotedTo.has(p.id)),
+        ])),
+        ...served,
+    ];
+    const key = (t) => [t.plugin ?? "", t.name, t.id];
+    return rows.sort((a, b) => {
+        const [x, y] = [key(a), key(b)];
+        for (let i = 0; i < x.length; i++) {
+            if (x[i] !== y[i])
+                return x[i] < y[i] ? -1 : 1;
+        }
+        return 0;
+    });
+}
+/**
+ * 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 async function readOwnTemplate(db, orgId, id, forUpdate) {
+    let q = db
+        .selectFrom("agent_templates as t")
+        .leftJoin("platform_agent_templates as p", "p.id", "t.platform_template_id")
+        .select([
+        "t.id",
+        "t.name",
+        "t.current_version",
+        "t.shareable",
+        "t.plugin_name",
+        "t.catalog_item_id",
+        "t.platform_template_id",
+        "t.pinned_version",
+        "p.owner_org_id",
+        "p.deleted_at as p_deleted_at",
+    ])
+        .where("t.id", "=", id)
+        .where("t.org_id", "=", orgId)
+        .where("t.deleted_at", "is", null);
+    if (forUpdate)
+        q = q.forUpdate("t");
+    const r = await q.executeTakeFirst();
+    if (!r)
+        return undefined;
+    const notOwn = { own: false, name: r.name };
+    if (r.plugin_name !== null || r.catalog_item_id !== null)
+        return notOwn;
+    const own = {
+        id: r.id,
+        name: r.name,
+        current_version: r.current_version,
+        shareable: r.shareable,
+    };
+    if (r.platform_template_id === null)
+        return { ...own, link: null };
+    const promoted = r.pinned_version === null && r.owner_org_id === orgId && r.p_deleted_at === null;
+    return promoted ? { ...own, link: r.platform_template_id } : notOwn;
+}
+/**
+ * The listing view of a usable template; `linkedIds`: the org's unpinned copies linked to it (a
+ * platform template only).
+ */
+export function templateViewOf(t, linkedIds) {
+    return {
+        id: t.id,
+        name: t.name,
+        plugin: t.plugin,
+        type: templateTypeOf(t.plugin, t.name),
+        description: typeof t.template.description === "string" ? t.template.description : "",
+        model: t.template.model ?? "inherit",
+        version: t.version,
+        sourceFormat: t.sourceFormat,
+        catalogItemId: t.catalogItemId,
+        catalogVersion: t.catalogVersion,
+        // the org's own template it promoted is the org's own, whatever version it serves
+        origin: t.ownedCopy ? "org" : t.origin,
+        ...(t.origin === "platform" && !t.ownedCopy && { linkedIds }),
+    };
 }
 /** Reads the org's agent templates (consumed by the roster, the agent page and Task 19's API). */
 let AgentTemplatesService = class AgentTemplatesService {
@@ -51,40 +487,37 @@ let AgentTemplatesService = class AgentTemplatesService {
     constructor(db) {
         this.db = db;
     }
-    /** 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`).
+     */
     async listForOrg(orgId) {
-        const rows = await baseQuery(this.db.db, orgId)
-            .orderBy("t.plugin_name")
-            .orderBy("t.name")
-            .execute();
-        return rows.map((r) => {
-            const t = rowOf(r);
-            return {
-                id: t.id,
-                name: t.name,
-                plugin: t.plugin,
-                type: `${t.plugin}:${t.name}`,
-                description: typeof t.template.description === "string" ? t.template.description : "",
-                model: t.template.model ?? "inherit",
-                version: t.version,
-                sourceFormat: t.sourceFormat,
-                catalogItemId: t.catalogItemId,
-                catalogVersion: t.catalogVersion,
-            };
-        });
+        const usable = await usableTemplates(this.db.db, orgId);
+        const platformIds = usable.filter((t) => t.origin === "platform").map((t) => t.id);
+        const links = platformIds.length === 0
+            ? []
+            : await this.db.db
+                .selectFrom("agent_templates")
+                .select(["id", "platform_template_id"])
+                .where("org_id", "=", orgId)
+                .where("deleted_at", "is", null)
+                .where("pinned_version", "is", null)
+                .where("platform_template_id", "in", platformIds)
+                .orderBy("id")
+                .execute();
+        const linked = new Map();
+        for (const l of links) {
+            const k = l.platform_template_id;
+            linked.set(k, [...(linked.get(k) ?? []), l.id]);
+        }
+        return usable.map((t) => templateViewOf(t, linked.get(t.id) ?? []));
     }
-    /** 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. */
     async resolve(orgId, ref) {
-        const i = ref.indexOf(":");
-        let q = baseQuery(this.db.db, orgId);
-        q =
-            i < 0
-                ? q.where("t.id", "=", ref)
-                : q.where("t.plugin_name", "=", ref.slice(0, i)).where("t.name", "=", ref.slice(i + 1));
-        const r = await q.executeTakeFirst();
-        if (!r)
+        const t = (await loadTemplates(this.db.db, orgId, [ref])).get(ref) ??
+            (await usableTemplates(this.db.db, orgId)).find((u) => templateTypeOf(u.plugin, u.name) === ref);
+        if (!t)
             return null;
-        const t = rowOf(r);
         return { id: t.id, version: t.version, plugin: t.plugin, template: t.template };
     }
 };
@@ -94,9 +527,10 @@ AgentTemplatesService = __decorate([
 ], AgentTemplatesService);
 export { AgentTemplatesService };
 /**
- * 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 async function putTemplateVersionIn(t, s, template) {
     const live = await t
@@ -104,7 +538,7 @@ export async function putTemplateVersionIn(t, s, template) {
         .innerJoin("agent_template_versions as v", (j) => j.onRef("v.template_id", "=", "a.id").onRef("v.version", "=", "a.current_version"))
         .select(["a.id", "a.current_version", "v.definition"])
         .where("a.org_id", "=", s.orgId)
-        .where("a.plugin_name", "=", s.plugin)
+        .where((eb) => s.plugin === null ? eb("a.plugin_name", "is", null) : eb("a.plugin_name", "=", s.plugin))
         .where("a.name", "=", template.name)
         .where("a.deleted_at", "is", null)
         .forUpdate("a")
@@ -121,7 +555,7 @@ export async function putTemplateVersionIn(t, s, template) {
             id,
             org_id: s.orgId,
             name: template.name,
-            catalog_item_id: s.catalogItemId,
+            catalog_item_id: s.catalogItemId ?? null,
             plugin_name: s.plugin,
             current_version: 1,
         })
@@ -140,7 +574,11 @@ export async function putTemplateVersionIn(t, s, template) {
     if (live) {
         await t
             .updateTable("agent_templates")
-            .set({ current_version: version, catalog_item_id: s.catalogItemId, updated_at: new Date() })
+            .set({
+            current_version: version,
+            catalog_item_id: s.catalogItemId ?? null,
+            updated_at: new Date(),
+        })
             .where("id", "=", id)
             .execute();
     }

package/dist/agents/templates.schemas.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+export declare const AgentTemplateIdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export declare const SaveAsAgentIdParams: z.ZodObject<{
+    agentId: z.ZodString;
+}, z.core.$strip>;
+export declare const SaveAsTemplateBody: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>;
+export declare const AgentTemplateShareableBody: z.ZodObject<{
+    shareable: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const AgentTemplateUpdateBody: z.ZodObject<{
+    definition: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>;
+export declare const AGENT_TEMPLATE_ROUTES: readonly RouteSchemas[];

package/dist/agents/templates.schemas.js

@@ -0,0 +1,45 @@
+import { AGENT_TEMPLATE_NAME_RE } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+export const AgentTemplateIdParams = z.object({ id: z.string().min(1).max(100) });
+export const SaveAsAgentIdParams = z.object({ agentId: z.string().min(1).max(100) });
+export const SaveAsTemplateBody = 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();
+export const AgentTemplateShareableBody = z.object({ shareable: z.boolean() }).strict();
+export const AgentTemplateUpdateBody = 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();
+export const AGENT_TEMPLATE_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/agent-templates" },
+    { route: "GET /api/v1/orgs/:orgId/agent-templates/:id", params: AgentTemplateIdParams },
+    {
+        route: "POST /api/v1/orgs/:orgId/agents/:agentId/save-as-template",
+        params: SaveAsAgentIdParams,
+        body: SaveAsTemplateBody,
+    },
+    {
+        route: "PUT /api/v1/orgs/:orgId/agent-templates/:id",
+        params: AgentTemplateIdParams,
+        body: AgentTemplateUpdateBody,
+    },
+    {
+        route: "GET /api/v1/orgs/:orgId/agent-templates/:id/delete-preview",
+        params: AgentTemplateIdParams,
+    },
+    { route: "DELETE /api/v1/orgs/:orgId/agent-templates/:id", params: AgentTemplateIdParams },
+    {
+        route: "PUT /api/v1/orgs/:orgId/agent-templates/:id/shareable",
+        params: AgentTemplateIdParams,
+        body: AgentTemplateShareableBody,
+    },
+];