@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

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;