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

package/dist/agents/from-template.service.d.ts

@@ -0,0 +1,60 @@
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { ModelPurposesService } from "../models/purposes.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService, type AgentView, type AgentVisibility } from "./agents.service.js";
+import type { ModelRef } from "./definition.js";
+import { type ModelSource, type PlanItem } from "./from-template.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+import type { ProfileInput } from "./profile.js";
+/** The preview of creating an agent from a template (`POST …/agents/from-template/preview`). */
+export interface TemplatePreview {
+    items: PlanItem[];
+    /** The automatic choice the dialog preselects (P4-4); null when the org has no usable model. */
+    model: (ModelRef & {
+        source: ModelSource;
+    }) | null;
+    dropped: string[];
+    previewHash: string;
+}
+export interface CreateFromTemplateRequest {
+    templateId: string;
+    name: string;
+    visibility?: AgentVisibility;
+    members?: string[];
+    model?: ModelRef;
+    avatar?: ProfileInput["avatar"];
+    previewHash: string;
+}
+/**
+ * Creating agents from templates (rulings P4-3…P4-8): the preview and the create both resolve the
+ * template with {@link planFromTemplate}; the create refuses a plan whose hash differs from the
+ * preview's (409 `agent.template_preview_stale`: the base part, and the automatic model's part when
+ * no model is chosen), writes the agent through
+ * {@link AgentsService.createFromTemplate}, and after the commit opens the pending connector request
+ * when the creator cannot configure connectors.
+ */
+export declare class AgentsFromTemplate {
+    private readonly db;
+    private readonly agents;
+    /** Extension tools loaded here and the org's enabled extensions. */
+    private readonly host;
+    private readonly providers;
+    /** The tier's purpose mapping (`subagent_<tier>`, P4-4). */
+    private readonly purposes;
+    private readonly requests;
+    private readonly log;
+    constructor(db: KernelDb, agents: AgentsService, 
+    /** Extension tools loaded here and the org's enabled extensions. */
+    host: Pick<ExtensionHost, "tools" | "enabledPlugins">, providers: Pick<ProviderRegistry, "resolve" | "list">, 
+    /** The tier's purpose mapping (`subagent_<tier>`, P4-4). */
+    purposes: Pick<ModelPurposesService, "resolve">, requests: PendingConnectorRequests, log: Pick<KernelLogger, "warn">);
+    /** The template, when usable in the org (P4-3); otherwise 404 `component.not_found`. */
+    private template;
+    private plan;
+    preview(orgId: string, templateId: string): Promise<TemplatePreview>;
+    create(orgId: string, actorAccountId: string, req: CreateFromTemplateRequest, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
+        agent: AgentView;
+    }>;
+}

package/dist/agents/from-template.service.js

@@ -0,0 +1,161 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { ExtensionHost } from "../extensions/host.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ModelPurposesService } from "../models/purposes.js";
+import { can } from "../orgs/roles.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService } from "./agents.service.js";
+import { planFromTemplate, } from "./from-template.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+import { loadTemplates } from "./templates.js";
+/**
+ * Creating agents from templates (rulings P4-3…P4-8): the preview and the create both resolve the
+ * template with {@link planFromTemplate}; the create refuses a plan whose hash differs from the
+ * preview's (409 `agent.template_preview_stale`: the base part, and the automatic model's part when
+ * no model is chosen), writes the agent through
+ * {@link AgentsService.createFromTemplate}, and after the commit opens the pending connector request
+ * when the creator cannot configure connectors.
+ */
+let AgentsFromTemplate = class AgentsFromTemplate {
+    db;
+    agents;
+    host;
+    providers;
+    purposes;
+    requests;
+    log;
+    constructor(db, agents, 
+    /** Extension tools loaded here and the org's enabled extensions. */
+    host, providers, 
+    /** The tier's purpose mapping (`subagent_<tier>`, P4-4). */
+    purposes, requests, log) {
+        this.db = db;
+        this.agents = agents;
+        this.host = host;
+        this.providers = providers;
+        this.purposes = purposes;
+        this.requests = requests;
+        this.log = log;
+    }
+    /** The template, when usable in the org (P4-3); otherwise 404 `component.not_found`. */
+    async template(orgId, templateId) {
+        const row = (await loadTemplates(this.db.db, orgId, [templateId])).get(templateId);
+        if (!row) {
+            throw new ApiError("component.not_found", "The agent template does not exist or is not available in this organization");
+        }
+        return row;
+    }
+    async plan(orgId, row, model) {
+        const opts = {
+            pluginTools: this.host.tools().map((t) => ({ plugin: t.plugin, name: t.spec.name })),
+            enabledPlugins: await this.host.enabledPlugins(orgId),
+            resolveModel: async (ref) => {
+                try {
+                    return (await this.providers.resolve(ref)).info.parameters;
+                }
+                catch {
+                    return null;
+                }
+            },
+            purpose: async (purpose) => {
+                try {
+                    return await this.purposes.resolve(orgId, purpose);
+                }
+                catch (e) {
+                    if (e instanceof ApiError)
+                        return null;
+                    throw e;
+                }
+            },
+            defaultModel: async () => {
+                for (const p of await this.providers.list()) {
+                    const m = p.models[0];
+                    if (m)
+                        return { provider: p.provider, model: m.id };
+                }
+                return null;
+            },
+            ...(model !== undefined && { model }),
+        };
+        return planFromTemplate(this.db.db, orgId, row, opts);
+    }
+    async preview(orgId, templateId) {
+        const plan = await this.plan(orgId, await this.template(orgId, templateId));
+        return {
+            items: plan.items,
+            model: plan.auto === null ? null : { ...plan.auto.ref, source: plan.auto.source },
+            dropped: plan.dropped,
+            previewHash: plan.hash,
+        };
+    }
+    async create(orgId, actorAccountId, req, actorTokenId, auditDetail) {
+        const row = await this.template(orgId, req.templateId);
+        const plan = await this.plan(orgId, row, req.model);
+        // the base part always; the automatic model's part only when the person chose none, so a
+        // silently changed choice is stale while an explicit one never is
+        const [base, auto] = req.previewHash.split(".");
+        if (base !== plan.baseHash || (req.model === undefined && auto !== plan.modelHash)) {
+            throw new ApiError("agent.template_preview_stale", "The template or the organization changed since the preview; preview it again");
+        }
+        if (plan.model === null) {
+            throw new ApiError("agent.model_unavailable", "No model is available for the new agent");
+        }
+        const { agent, role } = await this.agents.createFromTemplate(orgId, actorAccountId, {
+            definition: {
+                ...plan.definition,
+                name: req.name,
+                model: plan.model.ref,
+                modelParams: plan.model.params,
+            },
+            visibility: req.visibility ?? "private",
+            ...(req.members !== undefined && { memberIds: req.members }),
+            profile: {
+                description: plan.profile.description,
+                quickActions: plan.profile.quickActions,
+                ...(req.avatar != null && { avatar: req.avatar }),
+            },
+        }, { id: req.templateId, version: row.version, name: row.name }, actorTokenId, auditDetail);
+        const keys = (agent.definition.pendingConnectors ?? []).map((c) => c.key);
+        if (keys.length > 0 && !can(role, "connectors.manage")) {
+            try {
+                await this.requests.openFor({
+                    orgId,
+                    agentId: agent.id,
+                    ownerAccountId: agent.ownerAccountId,
+                    keys,
+                });
+            }
+            catch (err) {
+                // the agent stands; its 待配置 notice offers the request again (ruling P4-7)
+                this.log.warn("cannot open the pending connector request of a new agent", {
+                    orgId,
+                    agentId: agent.id,
+                    err,
+                });
+            }
+        }
+        return { agent };
+    }
+};
+AgentsFromTemplate = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(ExtensionHost)),
+    __param(3, Inject(ProviderRegistry)),
+    __param(4, Inject(ModelPurposesService)),
+    __param(5, Inject(PendingConnectorRequests)),
+    __param(6, Inject(KERNEL_LOGGER))
+], AgentsFromTemplate);
+export { AgentsFromTemplate };

package/dist/agents/instruction-files.d.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import type { AgentDefinition } from "./definition.js";
+/**
+ * Prompt files (spec 2026-11-04 §3.3): the authoring form of an agent's system prompt. The kernel
+ * joins them into `instructions` on save, and `instructions` stays the one model-visible field
+ * (build.ts, the sub-agent copy, eval candidates and replay keep reading it), so no log event
+ * changes shape and replay needs no new `DriftReason`.
+ */
+export type InstructionFile = {
+    name: string;
+    content: string;
+};
+/** The default and first file. */
+export declare const AGENTS_MD = "AGENTS.md";
+export declare const INSTRUCTION_FILE_LIMITS: {
+    /** At most this many files, at least one. */
+    readonly count: 20;
+    /** The joined text, the same bound as `instructions`. */
+    readonly joinedChars: 100000;
+};
+/** A file name: 1–64 characters without `/` or `\`, then `.md`. */
+export declare const INSTRUCTION_FILE_NAME_RE: RegExp;
+/**
+ * The starter prompt of a new agent created without one (model-visible once saved; English like
+ * every model-facing text).
+ */
+export declare const AGENTS_MD_STARTER: string;
+/**
+ * The model-visible join: one file gives exactly its content (so an old agent edited without
+ * adding files sends the same text as before); several files give `# <name>\n\n<content>` each,
+ * in order, joined by `\n\n`.
+ */
+export declare function joinInstructionFiles(files: readonly InstructionFile[]): string;
+/** The files of a definition; a definition without them (every old version) is one `AGENTS.md`. */
+export declare function readInstructionFiles(def: Pick<AgentDefinition, "instructions" | "instructionFiles">): InstructionFile[];
+export declare const InstructionFileSchema: z.ZodObject<{
+    name: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strict>;
+/**
+ * 1–20 files, names unique ignoring case (`AGENTS.md` and `agents.md` would collide on a
+ * case-insensitive file system), a joined total of at most 100 000 characters.
+ */
+export declare const InstructionFilesSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strict>>;
+/** A definition as a save request gives it: `instructions` may be left out. */
+export type AgentDefinitionInput = Omit<AgentDefinition, "instructions"> & {
+    instructions?: string | undefined;
+};
+/**
+ * Derives the stored definition of a save. With `instructionFiles`, `instructions` is their join
+ * (a differing `instructions` given with them → 400 `agent.instructions_mismatch`). With only
+ * `instructions` (old clients) the current files are kept while it equals their join, else the
+ * definition is stored as given, without files. Given neither,
+ * an update keeps the `current` version's prompt, and a new agent (`current` null) gets the
+ * `AGENTS.md` starter.
+ */
+export declare function deriveInstructions(def: AgentDefinitionInput, current: Pick<AgentDefinition, "instructions" | "instructionFiles"> | null): AgentDefinition;

package/dist/agents/instruction-files.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { ApiError } from "../errors.js";
+import { CONTROL_OR_HIDDEN_RE } from "../text.js";
+/** The default and first file. */
+export const AGENTS_MD = "AGENTS.md";
+export const INSTRUCTION_FILE_LIMITS = {
+    /** At most this many files, at least one. */
+    count: 20,
+    /** The joined text, the same bound as `instructions`. */
+    joinedChars: 100_000,
+};
+/** A file name: 1–64 characters without `/` or `\`, then `.md`. */
+export const INSTRUCTION_FILE_NAME_RE = /^[^/\\]{1,64}\.md$/;
+/**
+ * The starter prompt of a new agent created without one (model-visible once saved; English like
+ * every model-facing text).
+ */
+export const AGENTS_MD_STARTER = [
+    "You are an assistant for this team. Help people get their work done accurately and efficiently.",
+    "",
+    "- Tone: clear, friendly and concise. Use plain language, keep answers short, and add detail when asked.",
+    "- When a request is unclear or missing key details, ask one short clarifying question before acting.",
+    "  If you go ahead anyway, say what you assumed.",
+    "- If you don't know something or can't do it, say so instead of guessing.",
+].join("\n");
+/**
+ * The model-visible join: one file gives exactly its content (so an old agent edited without
+ * adding files sends the same text as before); several files give `# <name>\n\n<content>` each,
+ * in order, joined by `\n\n`.
+ */
+export function joinInstructionFiles(files) {
+    if (files.length === 1)
+        return files[0]?.content ?? "";
+    return files.map((f) => `# ${f.name}\n\n${f.content}`).join("\n\n");
+}
+/** The files of a definition; a definition without them (every old version) is one `AGENTS.md`. */
+export function readInstructionFiles(def) {
+    return def.instructionFiles ?? [{ name: AGENTS_MD, content: def.instructions }];
+}
+export const InstructionFileSchema = z
+    .object({
+    name: z
+        .string()
+        .regex(INSTRUCTION_FILE_NAME_RE, "a file name is 1–64 characters without / or \\, then .md")
+        .refine((n) => !CONTROL_OR_HIDDEN_RE.test(n), "a file name must not contain control or format characters"),
+    content: z.string().max(INSTRUCTION_FILE_LIMITS.joinedChars),
+})
+    .strict();
+/**
+ * 1–20 files, names unique ignoring case (`AGENTS.md` and `agents.md` would collide on a
+ * case-insensitive file system), a joined total of at most 100 000 characters.
+ */
+export const InstructionFilesSchema = z
+    .array(InstructionFileSchema)
+    .min(1)
+    .max(INSTRUCTION_FILE_LIMITS.count)
+    .superRefine((files, ctx) => {
+    const seen = new Set();
+    files.forEach((f, i) => {
+        const key = f.name.toLowerCase();
+        if (seen.has(key)) {
+            ctx.addIssue({ code: "custom", path: [i, "name"], message: `duplicate file ${f.name}` });
+        }
+        seen.add(key);
+    });
+    const joined = joinInstructionFiles(files).length;
+    if (joined > INSTRUCTION_FILE_LIMITS.joinedChars) {
+        ctx.addIssue({
+            code: "custom",
+            message: `the joined files are ${joined} characters, more than ${INSTRUCTION_FILE_LIMITS.joinedChars}`,
+        });
+    }
+});
+/**
+ * Derives the stored definition of a save. With `instructionFiles`, `instructions` is their join
+ * (a differing `instructions` given with them → 400 `agent.instructions_mismatch`). With only
+ * `instructions` (old clients) the current files are kept while it equals their join, else the
+ * definition is stored as given, without files. Given neither,
+ * an update keeps the `current` version's prompt, and a new agent (`current` null) gets the
+ * `AGENTS.md` starter.
+ */
+export function deriveInstructions(def, current) {
+    const { instructions, instructionFiles, ...rest } = def;
+    if (instructionFiles !== undefined) {
+        const joined = joinInstructionFiles(instructionFiles);
+        if (instructions !== undefined && instructions !== joined) {
+            throw new ApiError("agent.instructions_mismatch", "instructions differs from the join of instructionFiles; send only instructionFiles");
+        }
+        return { ...rest, instructions: joined, instructionFiles };
+    }
+    if (instructions !== undefined) {
+        // an old client re-sending the same joined text (an unrelated edit) keeps the files
+        const files = current?.instructionFiles;
+        if (files !== undefined && instructions === joinInstructionFiles(files)) {
+            return { ...rest, instructions, instructionFiles: files };
+        }
+        return { ...rest, instructions };
+    }
+    if (current !== null) {
+        return {
+            ...rest,
+            instructions: current.instructions,
+            ...(current.instructionFiles !== undefined && { instructionFiles: current.instructionFiles }),
+        };
+    }
+    return {
+        ...rest,
+        instructions: AGENTS_MD_STARTER,
+        instructionFiles: [{ name: AGENTS_MD, content: AGENTS_MD_STARTER }],
+    };
+}

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

@@ -1,12 +1,18 @@
-import type { ModelInfo } from "@capybara-hq/plugin-sdk";
+import type { LocalizedName, ModelInfo } from "@capybara-hq/plugin-sdk";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { ProviderRegistry } from "../runtime/providers.js";
-/** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
+/**
+ * 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。Each provider
+ * carries its extension's display name (null when it has none).
+ */
 export declare class ModelsController {
     private readonly registry;
-    constructor(registry: ProviderRegistry);
+    private readonly displayNames;
+    constructor(registry: ProviderRegistry, displayNames: ExtensionDisplayNames);
     list(): Promise<{
         providers: {
             provider: string;
+            displayName: LocalizedName | null;
             models: ModelInfo[];
         }[];
     }>;

package/dist/agents/models.controller.js

@@ -8,16 +8,30 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Get, Inject } from "@nestjs/common";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { OrgAction } from "../orgs/org.guard.js";
 import { ProviderRegistry } from "../runtime/providers.js";
-/** 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。 */
+/**
+ * 可选模型（`/api/v1/orgs/:orgId/models`）：已安装的模型供应商及其模型，列表缓存在 Redis。Each provider
+ * carries its extension's display name (null when it has none).
+ */
 let ModelsController = class ModelsController {
     registry;
-    constructor(registry) {
+    displayNames;
+    constructor(registry, displayNames) {
         this.registry = registry;
+        this.displayNames = displayNames;
     }
     async list() {
-        return { providers: await this.registry.list() };
+        const providers = await this.registry.list();
+        const names = await this.displayNames.many(providers.map((p) => p.provider));
+        return {
+            providers: providers.map((p) => ({
+                provider: p.provider,
+                displayName: names.get(p.provider) ?? null,
+                models: p.models,
+            })),
+        };
     }
 };
 __decorate([
@@ -26,6 +40,7 @@ __decorate([
 ], ModelsController.prototype, "list", null);
 ModelsController = __decorate([
     Controller("api/v1/orgs/:orgId/models"),
-    __param(0, Inject(ProviderRegistry))
+    __param(0, Inject(ProviderRegistry)),
+    __param(1, Inject(ExtensionDisplayNames))
 ], ModelsController);
 export { ModelsController };

package/dist/agents/org-templates.d.ts

@@ -0,0 +1,176 @@
+import { type AgentTemplate } from "@capybara-hq/plugin-sdk";
+import { type Owner } from "../catalog/ownership.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { AgentLookup, type AgentView } from "./agent-lookup.js";
+import { type AgentTemplateView } from "./templates.js";
+/** A template with its definition, as `GET orgs/:orgId/agent-templates/:id` answers. */
+export interface AgentTemplateDetail extends AgentTemplateView {
+    /** The current definition (the served version). */
+    definition: AgentTemplate;
+    /** Who owns it: the platform, or the org that created it (P3-14's shape). */
+    owner: Owner;
+    /**
+     * The org's own template (an org template, promoted or not; rulings P3-6, P4-12): its admins
+     * edit, delete and set 可共享 on it. Always false for a plugin's template.
+     */
+    owned: boolean;
+    /** 可共享 (only meaningful when `owned`). */
+    shareable: boolean;
+    /** Shared already: the platform row it was promoted to on share (ruling P3-3). */
+    promoted: boolean;
+    /**
+     * In the org's usable set (agents can be created from it here). False only when the owner reads
+     * its own template while it is not usable in its org (a promoted one switched off there).
+     */
+    usable: boolean;
+}
+/**
+ * What 另存为模板 left out (ruling P4-10), listed to the person: `kind` names the part of the
+ * agent, `name` the item (roster name, skill or connector name), `id` its id when it has one, and
+ * `reason`:
+ * - `org_agent`: an allowlisted org agent in the roster (an agent, not a template);
+ * - `unavailable`: a skill, sub-agent template or connector the org can no longer use;
+ * - `agent_skill`: one of the agent's own skills (not in the org library, so no other agent could
+ *   resolve it);
+ * - `no_endpoint`: a hand-configured connector without a URL to record (an inline OpenAPI document);
+ * - `unsupported_protocol`: a hand-configured connector of a kind other than MCP or OpenAPI;
+ * - `limit`: past a template limit (connectors 16, sub-agent types and inline 16, tools 200, a
+ *   connector entry's tools and policy keys 200 together: kind `tool_policy`, `name` the tool,
+ *   `id` the connector);
+ * - `connector_tool`: a policy on a tool of a connector the template does not carry (kind
+ *   `tool_policy`, `name` its key; carried connectors take their policies in `policies`), or a
+ *   connector tool key in an inline sub-agent's allowlist (kind `subagent_inline`,
+ *   `field: "tools"`, `name` the sub-agent): connector keys embed this org's connector slug;
+ * - `unsupported_field`: a field of an inline sub-agent a template's inline entry cannot hold
+ *   (kind `subagent_inline`, `field`: `disallowedTools`, `toolPolicies`, `effort` or `maxSteps`);
+ * - `model_param`: a model parameter other than a valid `effort` (kind `model_param`, `name` its
+ *   key): a template records only the effort (P4-10);
+ * - `fallback`: the fallback model and its parameters (kind `fallback_model`, `name`
+ *   `provider/model`): a template has no fallback;
+ * - `empty_text`: whitespace-only text a template requires (kind `subagent_inline` with `field`
+ *   `description` or `instructions`: the sub-agent is left out; kind `quick_action`, `name` its
+ *   title: the quick action is left out).
+ * An inline sub-agent's skills that are the agent's own (`agent_skill`), gone (`unavailable`) or
+ * past the 3 a template holds (`limit`) are listed as kind `skill`.
+ */
+export interface SaveAsOmission {
+    kind: "subagent_agent" | "subagent_template" | "subagent_inline" | "skill" | "connector" | "tool" | "tool_policy" | "model_param" | "fallback_model" | "quick_action";
+    name: string;
+    id?: string;
+    /** The field of an inline sub-agent left out (`connector_tool`, `unsupported_field`). */
+    field?: string;
+    reason: "org_agent" | "unavailable" | "agent_skill" | "no_endpoint" | "unsupported_protocol" | "limit" | "connector_tool" | "unsupported_field" | "model_param" | "fallback" | "empty_text";
+}
+/**
+ * Roster names no template may take (ruling T4-R15): `general-purpose`, always the roster's first
+ * entry. Claude Code's other built-in types (`Explore`, `Plan`) are capitalized, which the
+ * template name rule already refuses.
+ */
+export declare const RESERVED_TEMPLATE_NAMES: ReadonlySet<string>;
+/**
+ * A connector's URL as a template may record it (ruling P4-11): userinfo, query and fragment
+ * removed (they may carry credentials). Null when it is no absolute http(s) URL.
+ */
+export declare function sanitizeEndpoint(raw: string): string | null;
+/**
+ * Validates a template definition the way an `agents/<name>.md` file is (the SDK parser, so the
+ * two never drift): the definition minus `instructions` as the frontmatter (JSON is YAML), then
+ * the instructions as the body. Problems -> 400 `validation_failed` naming each.
+ */
+export declare function parseTemplateDefinition(definition: Record<string, unknown>): AgentTemplate;
+/**
+ * Ruling P4-11 on an edit: a `connectors[].needs.endpoint` that carries userinfo, a query or a
+ * fragment, or is no http(s) URL of at most 2048 characters, is refused with 400
+ * `validation_failed` naming the field and what it carries (an edit is never stripped silently).
+ * One that differs only by normalization (a trailing slash, the host's case) is accepted:
+ * returns the template with each such endpoint in its canonical {@link sanitizeEndpoint} form.
+ */
+export declare function canonicalEndpoints(template: AgentTemplate): AgentTemplate;
+/**
+ * The template an agent is saved as (rulings P4-10, P4-11), with what was left out. Pure reads of
+ * the org's state through `db`.
+ */
+export declare function templateFromAgent(db: KernelSchemaDb, orgId: string, agent: AgentView, meta: {
+    name: string;
+    description: string;
+}): Promise<{
+    template: AgentTemplate;
+    omitted: SaveAsOmission[];
+}>;
+/**
+ * The org's agent templates beyond the plugin ones (rulings P4-9 to P4-12): 另存为模板, the detail
+ * of a usable template and the owner's new versions. Writes run under the org row lock, with
+ * `agents.manage` re-checked there.
+ */
+export declare class OrgAgentTemplates {
+    private readonly kdb;
+    private readonly orgLock;
+    private readonly agents;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, orgLock: Pick<OrgLock, "lockAndAuthorize">, agents: Pick<AgentLookup, "view">, txHost: TransactionHost);
+    private get db();
+    /**
+     * 另存为模板 (ruling P4-9): the org's live agent `agentId` (any one: an org admin may edit every
+     * agent of the org) saved as the org template `name` (version 1, `plugin_name` null), mapped
+     * by {@link templateFromAgent}. The bare name must be free in the org (rule 10): a usable
+     * template of that type, one of the org's own rows of that name, or a live platform template
+     * the org created under that name -> 409 `agent_template.name_taken` naming its owner (details
+     * `[{ owner, templateId }]`). Audits `agent_template.created`.
+     */
+    saveAs(orgId: string, actor: string, agentId: string, meta: {
+        name: string;
+        description: string;
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
+        template: AgentTemplateDetail;
+        omitted: SaveAsOmission[];
+    }>;
+    /**
+     * Rule 10 for a new org template named `name` (a bare type): refused for a reserved roster name
+     * (details `[{ reserved: true }]`), and while the org's usable set has that type, the org has a
+     * live row of that name without a plugin (an unusable copy too: the live-name index), a
+     * plugin-less platform template of that name is offered to the org (ruling P2-3's alignment),
+     * or the platform has a live template the org created under that name (promotion would clash).
+     */
+    private assertNameFree;
+    /**
+     * A template usable in the org by id ({@link loadTemplates}: an org row, a linked copy, a
+     * platform template on in the org), or the org's own template whatever its switch, with its
+     * definition, owner and the org's flags. Otherwise -> 404 `component.not_found`.
+     */
+    detail(orgId: string, id: string): Promise<AgentTemplateDetail>;
+    /**
+     * A new version of the org's own template `id` (ruling P4-12; `agents.manage` re-checked under
+     * the org row lock): `definition` is validated like a template file and keeps its name;
+     * `expectedVersion` must be the version the editor read (else 409
+     * `agent_template.version_conflict`). An unshared template gets a new version of its org row; a
+     * promoted one a new version of its platform row (ruling P3-4), which the org row then serves
+     * (ruling P3-43), and the orgs using it are told (`shared_item_updated`). An unchanged
+     * definition writes nothing. Not the org's own -> 409 `catalog.not_owned`; missing -> 404.
+     * Agents created earlier are never touched. Audits `agent_template.updated`.
+     */
+    update(orgId: string, actor: string, id: string, body: {
+        definition: Record<string, unknown>;
+        expectedVersion: number;
+    }, actorTokenId?: string): Promise<AgentTemplateDetail>;
+    /**
+     * The org's own template `id` ({@link readOwnTemplate}, the predicate `OwnedItems` shares), or
+     * undefined: another org's, a plugin's, or a copy of a platform template it does not own.
+     */
+    private ownRow;
+    /**
+     * What the org's own template serves, read directly (its usable-set entry is missing while the
+     * org switched its promoted template off): the platform row's current version when it is newer
+     * than the org row's (ruling P3-43), else the org row's.
+     */
+    private ownServed;
+    /** 409 `catalog.not_owned` for a template the org has but does not own, else 404. */
+    private notOwnedOrMissing;
+    /**
+     * The owner of a usable template the org does not own itself: a platform template's (or a
+     * linked copy's) `owner_org_id`, a plugin template's catalog item owner, else the platform.
+     */
+    private ownerOfRow;
+}