@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/agents/definition.d.ts

@@ -0,0 +1,198 @@
+import { z } from "zod";
+/** 模型引用：供应商插件名 + 模型 id。 */
+export declare const ModelRef: z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+}, z.core.$strip>;
+export type ModelRef = z.infer<typeof ModelRef>;
+/**
+ * 模型参数（键为插件声明的参数键）：只接受标量；按该模型的 `parameters` 声明校验在 `AgentsService`
+ * 中进行（保存时严格，运行时宽松，见 plugin-sdk `validateParams` / `sanitizeParams`）。
+ */
+export declare const ModelParams: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+export type ModelParams = z.infer<typeof ModelParams>;
+/**
+ * 改名前（D17）保存的连接器引用 `{ kind: "app", appId, tools }` 规范化为 `{ kind: "connector", connectorId, tools }`
+ * （C27：已存 agent 版本不改写，读入时规范化；新保存只写 connector 形）。其余值原样返回。
+ */
+export declare function normalizeToolRef(v: unknown): unknown;
+/**
+ * agent 定义里对工具的引用：内置工具按名字；插件工具按插件名 + 工具名；连接器工具按连接器 id，
+ * `tools: "all"` = 该连接器当前所有启用的工具。旧形 `{ kind: "app", appId }` 仍可解析（见 {@link normalizeToolRef}）。
+ */
+export declare const AgentToolRef: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"builtin">;
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"plugin">;
+    plugin: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"connector">;
+    connectorId: z.ZodString;
+    tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+}, z.core.$strict>], "kind">, unknown>;
+export type AgentToolRef = z.output<typeof AgentToolRef>;
+/**
+ * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
+ * 只用于创建请求；修改与读出旧版本都不注入默认值。
+ */
+export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
+/** Roster names of inline templates and allowlisted org agents (the template name rule). */
+export declare const SUBAGENT_NAME_RE: RegExp;
+/**
+ * A sub-agent template written in the agent definition (phase C, spec §5.2): the fields of a
+ * plugin agent template (`AgentTemplate`, spec §16.1), with `skills` as skill ids (org skills the
+ * agent selects, or the agent's own) instead of names. Names and selections are checked on save
+ * (`agent.subagents_invalid`); the schema only bounds the input.
+ */
+export declare const InlineAgentTemplate: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    instructions: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    toolPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        ask: "ask";
+        deny: "deny";
+    }>>>;
+    model: z.ZodOptional<z.ZodEnum<{
+        capable: "capable";
+        fast: "fast";
+        inherit: "inherit";
+        standard: "standard";
+    }>>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        high: "high";
+        low: "low";
+        max: "max";
+        medium: "medium";
+        xhigh: "xhigh";
+    }>>;
+    maxSteps: z.ZodOptional<z.ZodNumber>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type InlineAgentTemplate = z.infer<typeof InlineAgentTemplate>;
+/**
+ * Sub-agents this agent may dispatch with the builtin `agent` tool (phase C, spec §5.2). No
+ * default: definitions without it are unchanged and gain no version.
+ */
+export declare const SubagentsSchema: z.ZodObject<{
+    general: z.ZodOptional<z.ZodBoolean>;
+    templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    inline: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        instructions: z.ZodString;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        toolPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            ask: "ask";
+            deny: "deny";
+        }>>>;
+        model: z.ZodOptional<z.ZodEnum<{
+            capable: "capable";
+            fast: "fast";
+            inherit: "inherit";
+            standard: "standard";
+        }>>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            low: "low";
+            max: "max";
+            medium: "medium";
+            xhigh: "xhigh";
+        }>>;
+        maxSteps: z.ZodOptional<z.ZodNumber>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agentId: z.ZodString;
+        as: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>>;
+    dispatchable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type Subagents = z.infer<typeof SubagentsSchema>;
+/** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
+export declare const AgentDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
+    instructions: z.ZodDefault<z.ZodString>;
+    model: z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strip>;
+    fallback: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strip>>>;
+    modelParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    fallbackParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"builtin">;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"plugin">;
+        plugin: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"connector">;
+        connectorId: z.ZodString;
+        tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+    }, z.core.$strict>], "kind">, unknown>>>;
+    toolPolicies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        ask: "ask";
+        deny: "deny";
+    }>>>;
+    skills: z.ZodOptional<z.ZodObject<{
+        orgSkills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        writePolicy: z.ZodOptional<z.ZodEnum<{
+            allow: "allow";
+            ask: "ask";
+        }>>;
+        pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    subagents: z.ZodOptional<z.ZodObject<{
+        general: z.ZodOptional<z.ZodBoolean>;
+        templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        inline: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            instructions: z.ZodString;
+            tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            toolPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                ask: "ask";
+                deny: "deny";
+            }>>>;
+            model: z.ZodOptional<z.ZodEnum<{
+                capable: "capable";
+                fast: "fast";
+                inherit: "inherit";
+                standard: "standard";
+            }>>;
+            effort: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                low: "low";
+                max: "max";
+                medium: "medium";
+                xhigh: "xhigh";
+            }>>;
+            maxSteps: z.ZodOptional<z.ZodNumber>;
+            skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>>;
+        agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            agentId: z.ZodString;
+            as: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strict>>>;
+        dispatchable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
+/**
+ * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
+ * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ */
+export declare function normalizeStoredDefinition(def: unknown): AgentDefinition;

package/dist/agents/definition.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+/** 模型引用：供应商插件名 + 模型 id。 */
+export const ModelRef = z.object({ provider: z.string(), model: z.string() });
+/**
+ * 模型参数（键为插件声明的参数键）：只接受标量；按该模型的 `parameters` 声明校验在 `AgentsService`
+ * 中进行（保存时严格，运行时宽松，见 plugin-sdk `validateParams` / `sanitizeParams`）。
+ */
+export const ModelParams = z.record(z.string(), z.union([z.string(), z.number(), z.boolean()]));
+/**
+ * 改名前（D17）保存的连接器引用 `{ kind: "app", appId, tools }` 规范化为 `{ kind: "connector", connectorId, tools }`
+ * （C27：已存 agent 版本不改写，读入时规范化；新保存只写 connector 形）。其余值原样返回。
+ */
+export function normalizeToolRef(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return v;
+    const r = v;
+    if (r.kind !== "app")
+        return v;
+    const { kind: _kind, appId, ...rest } = r;
+    return { kind: "connector", connectorId: appId, ...rest };
+}
+/**
+ * agent 定义里对工具的引用：内置工具按名字；插件工具按插件名 + 工具名；连接器工具按连接器 id，
+ * `tools: "all"` = 该连接器当前所有启用的工具。旧形 `{ kind: "app", appId }` 仍可解析（见 {@link normalizeToolRef}）。
+ */
+export const AgentToolRef = z.preprocess(normalizeToolRef, z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("builtin"), name: z.string().min(1) }).strict(),
+    z
+        .object({ kind: z.literal("plugin"), plugin: z.string().min(1), name: z.string().min(1) })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("connector"),
+        connectorId: z.string().min(1),
+        tools: z.union([z.literal("all"), z.array(z.string().min(1)).min(1)]),
+    })
+        .strict(),
+]));
+/**
+ * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
+ * 只用于创建请求；修改与读出旧版本都不注入默认值。
+ */
+export const DEFAULT_AGENT_TOOLS = [
+    { kind: "builtin", name: "ask_user" },
+    { kind: "builtin", name: "read_tool_output" },
+];
+/** Roster names of inline templates and allowlisted org agents (the template name rule). */
+export const SUBAGENT_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/**
+ * A sub-agent template written in the agent definition (phase C, spec §5.2): the fields of a
+ * plugin agent template (`AgentTemplate`, spec §16.1), with `skills` as skill ids (org skills the
+ * agent selects, or the agent's own) instead of names. Names and selections are checked on save
+ * (`agent.subagents_invalid`); the schema only bounds the input.
+ */
+export const InlineAgentTemplate = z
+    .object({
+    name: z.string().min(1).max(64),
+    description: z.string().min(1).max(4096),
+    instructions: z.string().min(1).max(100_000),
+    tools: z.array(z.string().min(1).max(200)).max(200).optional(),
+    disallowedTools: z.array(z.string().min(1).max(200)).max(200).optional(),
+    toolPolicies: z.record(z.string(), z.enum(["ask", "deny"])).optional(),
+    model: z.enum(["inherit", "fast", "standard", "capable"]).optional(),
+    effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
+    maxSteps: z.number().int().min(1).max(10_000).optional(),
+    skills: z.array(z.string().min(1).max(100)).max(3).optional(),
+})
+    .strict();
+/**
+ * Sub-agents this agent may dispatch with the builtin `agent` tool (phase C, spec §5.2). No
+ * default: definitions without it are unchanged and gain no version.
+ */
+export const SubagentsSchema = z
+    .object({
+    /** Offer general-purpose (a copy of this agent). Default true. */
+    general: z.boolean().optional(),
+    /** Org agent template ids (installed from plugins), in roster order. */
+    templates: z.array(z.string().min(1).max(100)).max(20).optional(),
+    /** Templates written here. */
+    inline: z.array(InlineAgentTemplate).max(10).optional(),
+    /** Other org agents this agent may dispatch (§5.5), in roster order. */
+    agents: z
+        .array(z
+        .object({
+        agentId: z.string().min(1).max(100),
+        /** Roster name (`subagent_type`), the template name rule. */
+        as: z.string().min(1).max(64),
+        /** When to use it; shown in the tool description. */
+        description: z.string().min(1).max(1024),
+    })
+        .strict())
+        .max(10)
+        .optional(),
+    /** Other agents may dispatch this agent (§5.5). Default false. */
+    dispatchable: z.boolean().optional(),
+})
+    .strict();
+/** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
+export const AgentDefinitionSchema = z.object({
+    name: z.string().min(1).max(80),
+    avatarUrl: z.url().nullable().default(null),
+    instructions: z.string().max(100_000).default(""),
+    model: ModelRef,
+    fallback: ModelRef.nullable().default(null),
+    /** 主模型的参数（按主模型的声明校验）。 */
+    modelParams: ModelParams.default({}),
+    /** 兜底模型自己的参数（按兜底模型的声明校验）；兜底尝试只用这一份。 */
+    fallbackParams: ModelParams.default({}),
+    /** 引用的工具（M2 保存的 `tools: []` 仍然合法）；保存时校验引用存在，运行时由注册表解析。 */
+    tools: z.array(AgentToolRef).default([]),
+    /**
+     * 按工具 key 收紧策略（只能收紧：`ask` / `deny`，不接受 `allow`）；键必须是该 agent 引用的工具的 key。
+     * 较早保存的定义没有该字段，按空处理。
+     */
+    toolPolicies: z.record(z.string(), z.enum(["ask", "deny"])).default({}),
+    /**
+     * 技能（M5 T13）：`orgSkills` 是引用的组织技能 id（保存时校验属于本组织且未删除，不可重复）。
+     * agent 自己的技能（`scope=agent`）自动对它生效，不进定义。可省略（较早保存的定义也没有），按空处理；
+     * 不给默认值：没用技能的定义保存前后不变，不会因此多出一个版本。
+     * `writePolicy`（M6 T27，D10）：私有 agent 的 `skill_write` 是否固定确认，缺省按 `allow`（不写进定义）；
+     * 共享 agent 不论取值都走 R3 + R4。
+     */
+    skills: z
+        .object({
+        orgSkills: z.array(z.string().min(1).max(100)).max(100).default([]),
+        writePolicy: z.enum(["allow", "ask"]).optional(),
+        /**
+         * Pinned skills (phase B, spec §9.1): ids of selected org skills or of the agent's own
+         * skills, whose bodies apply throughout every conversation, in this order. At most
+         * `PINNED_SKILLS_LIMITS.count` (checked with the other rules by `assertPinnedSkills`, as
+         * `agent.pinned_invalid`; the schema only bounds the input). No default: definitions
+         * without it are unchanged.
+         */
+        pinned: z.array(z.string().min(1).max(100)).max(100).optional(),
+    })
+        .strict()
+        .optional(),
+    /** Sub-agents (phase C); offered only when the builtin `agent` tool is in `tools`. */
+    subagents: SubagentsSchema.optional(),
+});
+/**
+ * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
+ * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ */
+export function normalizeStoredDefinition(def) {
+    const d = def;
+    const tools = d.tools;
+    if (!Array.isArray(tools) || !tools.some((t) => t?.kind === "app")) {
+        return d;
+    }
+    return { ...d, tools: tools.map(normalizeToolRef) };
+}

package/dist/agents/models.controller.d.ts

@@ -0,0 +1,13 @@
+import type { ModelInfo } from "@capybara-hq/plugin-sdk";
+import type { ProviderRegistry } from "../runtime/providers.js";
+/** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
+export declare class ModelsController {
+    private readonly registry;
+    constructor(registry: ProviderRegistry);
+    list(): Promise<{
+        providers: {
+            provider: string;
+            models: ModelInfo[];
+        }[];
+    }>;
+}

package/dist/agents/models.controller.js

@@ -0,0 +1,31 @@
+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, Get, Inject } from "@nestjs/common";
+import { PROVIDER_REGISTRY } from "../http/tokens.js";
+import { OrgAction } from "../orgs/org.guard.js";
+/** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
+let ModelsController = class ModelsController {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    async list() {
+        return { providers: await this.registry.list() };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("agents.use")
+], ModelsController.prototype, "list", null);
+ModelsController = __decorate([
+    Controller("api/v1/orgs/:orgId/models"),
+    __param(0, Inject(PROVIDER_REGISTRY))
+], ModelsController);
+export { ModelsController };

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

@@ -0,0 +1,15 @@
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { AgentTemplatesService, AgentTemplateView } from "./templates.js";
+/**
+ * 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.
+ */
+export declare class AgentTemplatesController {
+    private readonly templates;
+    constructor(templates: AgentTemplatesService);
+    list(org: OrgContext): Promise<{
+        templates: AgentTemplateView[];
+    }>;
+}

package/dist/agents/templates.controller.js

@@ -0,0 +1,37 @@
+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, Get, Inject } from "@nestjs/common";
+import { AGENT_TEMPLATES } from "../http/tokens.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+/**
+ * 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.
+ */
+let AgentTemplatesController = class AgentTemplatesController {
+    templates;
+    constructor(templates) {
+        this.templates = templates;
+    }
+    async list(org) {
+        return { templates: await this.templates.listForOrg(org.orgId) };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("agents.create"),
+    __param(0, CurrentOrg())
+], AgentTemplatesController.prototype, "list", null);
+AgentTemplatesController = __decorate([
+    Controller("api/v1/orgs/:orgId/agent-templates"),
+    __param(0, Inject(AGENT_TEMPLATES))
+], AgentTemplatesController);
+export { AgentTemplatesController };

package/dist/agents/templates.d.ts

@@ -0,0 +1,83 @@
+import type { AgentTemplate, AgentTemplateTier } from "@capybara-hq/plugin-sdk";
+import type { Transaction } from "kysely";
+import type { KernelDatabase, KernelDb, SourceFormat } from "../db/kernel-schema.js";
+type Trx = Transaction<KernelDatabase>;
+/**
+ * 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.
+ */
+/** A live template of an org (`GET` listings, the agent page). */
+export interface AgentTemplateView {
+    id: string;
+    name: string;
+    plugin: string;
+    /** The roster type `<plugin>:<name>`. */
+    type: string;
+    description: string;
+    model: AgentTemplateTier;
+    version: number;
+    sourceFormat: SourceFormat;
+    catalogItemId: string | null;
+    catalogVersion: string | null;
+}
+/** A template row with its current definition. */
+export interface TemplateRow {
+    id: string;
+    name: string;
+    plugin: string;
+    version: number;
+    template: AgentTemplate;
+    sourceFormat: SourceFormat;
+    catalogItemId: string | null;
+    catalogVersion: string | null;
+}
+/** The live templates of `ids` in the org (deleted and foreign ids are left out), by id. */
+export declare function loadTemplates(db: KernelDb | Trx, orgId: string, ids: readonly string[]): Promise<Map<string, TemplateRow>>;
+/** 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. */
+    listForOrg(orgId: string): Promise<AgentTemplateView[]>;
+    /** A live template by id or by `<plugin>:<name>`; null when there is none. */
+    resolve(orgId: string, ref: string): Promise<{
+        id: string;
+        version: number;
+        plugin: string;
+        template: AgentTemplate;
+    } | null>;
+}
+/** Where a template version comes from (a plugin version of the catalog). */
+export interface TemplateSource {
+    orgId: string;
+    plugin: string;
+    catalogItemId: string;
+    catalogVersion: string;
+    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.
+ */
+export declare function putTemplateVersionIn(t: Trx, s: TemplateSource, template: AgentTemplate): Promise<{
+    id: string;
+    version: number;
+    created: boolean;
+    changed: boolean;
+}>;
+/**
+ * Undoes `version` of a live template when it is still the current one (an install or upgrade
+ * rolled back): the version row goes and the template is back at the version before. Returns
+ * whether anything changed.
+ */
+export declare function revertTemplateVersionIn(t: Trx, orgId: string, id: string, version: number): Promise<boolean>;
+/**
+ * Removes a template (soft delete: sub-agents already started keep their frozen definition, and
+ * the roster skips it). Returns whether it was live.
+ */
+export declare function softDeleteTemplateIn(t: Trx, orgId: string, id: string): Promise<boolean>;
+export {};