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

package/dist/agents/pending-connectors.service.js

@@ -0,0 +1,282 @@
+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 { connectorToolKey } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { roleAtLeast } from "../orgs/roles.js";
+import { AgentLookup, isAgentVisibleTo } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.js";
+import { normalizeStoredDefinition, } from "./definition.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RANK = { ask: 1, deny: 2 };
+const MISMATCH = {
+    template: "The connector was not made from the connector template this entry needs",
+    protocol: "The connector's protocol is not the one this entry needs",
+    tools: "The connector offers none of the tools this entry needs",
+    not_synced: "The connector has not listed its tools yet; authorize the connector first, then bind it",
+};
+const mismatch = (reason) => new ApiError("agent.pending_connector_mismatch", MISMATCH[reason], [{ reason }]);
+const connectorNotFound = () => new ApiError("connector.not_found", "Connector not found");
+/**
+ * Resolving an agent's pending connectors (rulings P4-6, P4-7): binding a connector of the org to a
+ * pending entry, and the agent's connector setup request (re-opening it, reading the latest).
+ * Writes run under the org row lock and the agent row lock ({@link AgentsService.lockForWrite}: the
+ * owner or an org admin+).
+ */
+let PendingConnectorsService = class PendingConnectorsService {
+    kdb;
+    agents;
+    lookup;
+    requests;
+    txHost;
+    constructor(kdb, agents, lookup, requests, txHost) {
+        this.kdb = kdb;
+        this.agents = agents;
+        this.lookup = lookup;
+        this.requests = requests;
+        this.txHost = txHost;
+    }
+    /** The current version's definition of a locked agent. */
+    async currentDefinition(agentId, version) {
+        const row = await this.kdb.db
+            .selectFrom("agent_versions")
+            .select("definition")
+            .where("agent_id", "=", agentId)
+            .where("version", "=", version)
+            .executeTakeFirstOrThrow();
+        return normalizeStoredDefinition(row.definition);
+    }
+    /**
+     * Binds connector `connectorId` to the agent's pending entry `key` (ruling P4-6; P4-T6-1,
+     * P4-T6-2): a new agent version with a connector ref to it (merged into an existing ref of that
+     * connector) for the entry's tools the connector offers (all of them when the entry names none),
+     * the entry's policies on those tools (the tighter one wins), and without the entry; then the
+     * setup request narrows or closes (`approved`). Refused: no entry `key` -> 404
+     * `agent.pending_connector_not_found`; a connector that is missing, deleted or of another org ->
+     * 404 `connector.not_found`; another connector template (a `template` entry), another protocol
+     * (a `needs` entry), no tool snapshot yet (`not_synced`: an authorization-code connector nobody
+     * authorized) or none of the entry's tools -> 400 `agent.pending_connector_mismatch`.
+     * Audits `agent.pending_connector_bound`.
+     */
+    async bind(orgId, agentId, key, connectorId, actor, actorTokenId) {
+        const t = this.kdb.db;
+        const before = await this.agents.lockForWrite(orgId, agentId, actor);
+        const def = await this.currentDefinition(agentId, before.current_version);
+        const pending = def.pendingConnectors ?? [];
+        const entry = pending.find((c) => c.key === key);
+        if (!entry) {
+            throw new ApiError("agent.pending_connector_not_found", "The agent has no pending connector with this key");
+        }
+        if (!UUID_RE.test(connectorId))
+            throw connectorNotFound();
+        const c = await t
+            .selectFrom("connectors")
+            .select(["id", "slug", "connector", "platform_template_id", "tools_synced_at"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!c)
+            throw connectorNotFound();
+        if ("template" in entry.source) {
+            if (c.platform_template_id !== entry.source.template)
+                throw mismatch("template");
+        }
+        else if (c.connector !== entry.source.needs.protocol) {
+            throw mismatch("protocol");
+        }
+        // an authorization-code connector before its first snapshot has no tools to pick from: never
+        // bind "all" blind and drop the entry's policies; the entry stays pending (fix round 1)
+        if (c.tools_synced_at === null)
+            throw mismatch("not_synced");
+        const rows = await t
+            .selectFrom("connector_tools")
+            .select(["name", "status"])
+            .where("connector_id", "=", c.id)
+            .orderBy("name")
+            .execute();
+        const offered = rows.map((r) => r.name);
+        const dropped = [];
+        // an entry naming no tools takes them all (P4-T6-2)
+        let names = "all";
+        if (entry.tools !== undefined && entry.tools.length > 0) {
+            const present = entry.tools.filter((n) => offered.includes(n));
+            if (present.length === 0)
+                throw mismatch("tools");
+            for (const n of entry.tools)
+                if (!present.includes(n))
+                    dropped.push(`tools.${n}`);
+            // naming every enabled tool of this connector is "all": 另存为模板 writes an agent's
+            // 全部工具 as the enabled names (P4-11), and binding gives it back as 全部工具 (P4-T6-12)
+            const enabled = rows.filter((r) => r.status === "enabled").map((r) => r.name);
+            const coversAll = enabled.length > 0 && enabled.every((n) => present.includes(n));
+            names = coversAll ? "all" : present;
+        }
+        const kept = names === "all" ? offered : names;
+        const toolPolicies = { ...def.toolPolicies };
+        for (const [n, p] of Object.entries(entry.policies ?? {})) {
+            if (!kept.includes(n)) {
+                dropped.push(`policies.${n}`);
+                continue;
+            }
+            const k = connectorToolKey(c.slug, n);
+            const prev = toolPolicies[k];
+            if (prev === undefined || RANK[p] > RANK[prev])
+                toolPolicies[k] = p;
+        }
+        let merged = false;
+        const tools = def.tools.map((r) => {
+            if (r.kind !== "connector" || r.connectorId !== c.id || merged)
+                return r;
+            merged = true;
+            if (r.tools === "all")
+                return r;
+            return {
+                ...r,
+                tools: names === "all" ? "all" : [...new Set([...r.tools, ...names])],
+            };
+        });
+        if (!merged)
+            tools.push({ kind: "connector", connectorId: c.id, tools: names });
+        const left = pending.filter((x) => x.key !== key);
+        const { pendingConnectors: _old, ...rest } = def;
+        const next = {
+            ...rest,
+            tools,
+            toolPolicies,
+            ...(left.length > 0 && { pendingConnectors: left }),
+        };
+        const toVersion = before.current_version + 1;
+        await t
+            .insertInto("agent_versions")
+            .values({
+            agent_id: agentId,
+            version: toVersion,
+            definition: JSON.stringify(next),
+            created_by: actor,
+        })
+            .execute();
+        await t
+            .updateTable("agents")
+            .set({ current_version: toVersion, updated_at: sql `now()` })
+            .where("id", "=", agentId)
+            .execute();
+        await audit(t, {
+            actorAccountId: actor,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "agent.pending_connector_bound",
+            target: agentId,
+            detail: { key, connectorId: c.id, fromVersion: before.current_version, toVersion },
+        });
+        await this.requests.settleIn({
+            orgId,
+            agentId,
+            keys: left.map((x) => x.key),
+            close: "approved",
+            actor,
+            actorTokenId,
+        });
+        return { agent: await this.lookup.view(agentId), dropped };
+    }
+    /**
+     * (Re-)opens the agent's connector setup request (ruling P4-T6-7; the owner or an org admin+):
+     * the pending one when it has one (`created` false), else a new one for the current pending
+     * keys, requested by the agent's owner (P4-T6-4). No pending connectors -> 409
+     * `agent.no_pending_connectors`.
+     */
+    async reopen(orgId, agentId, actor, actorTokenId) {
+        const before = await this.agents.lockForWrite(orgId, agentId, actor);
+        const def = await this.currentDefinition(agentId, before.current_version);
+        const keys = (def.pendingConnectors ?? []).map((c) => c.key);
+        if (keys.length === 0) {
+            throw new ApiError("agent.no_pending_connectors", "The agent has no connectors waiting to be configured");
+        }
+        const owner = await this.kdb.db
+            .selectFrom("agents")
+            .select("owner_account_id")
+            .where("id", "=", agentId)
+            .executeTakeFirstOrThrow();
+        const r = await this.requests.open({
+            orgId,
+            agentId,
+            requestedBy: owner.owner_account_id,
+            actor,
+            actorTokenId,
+        });
+        // the agent row is locked above, so the keys read there are still pending
+        if (r === null)
+            throw new Error(`agent ${agentId} lost its pending connectors under its lock`);
+        return r;
+    }
+    /**
+     * The id of the agent's latest connector setup request (any status), or null. Authorized as the
+     * writes are (fix round 1): the agent's owner or an org admin+, whether or not the agent is
+     * visible to them; a member who sees the agent otherwise -> 403 `forbidden`; anyone else, or a
+     * deleted agent -> 404 `agent.not_found`.
+     */
+    async latestRequest(orgId, agentId, viewer) {
+        const t = this.kdb.db;
+        const [agent, member] = await Promise.all([
+            t
+                .selectFrom("agents")
+                .select("owner_account_id")
+                .where("id", "=", agentId)
+                .where("org_id", "=", orgId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst(),
+            t
+                .selectFrom("memberships")
+                .select("role")
+                .where("org_id", "=", orgId)
+                .where("account_id", "=", viewer)
+                .executeTakeFirst(),
+        ]);
+        if (!agent || !member)
+            throw new ApiError("agent.not_found", "Agent not found");
+        if (agent.owner_account_id !== viewer && !roleAtLeast(member.role, "admin")) {
+            if (await isAgentVisibleTo(t, agentId, viewer)) {
+                throw new ApiError("forbidden", "Only the agent owner or an organization admin can see its connector setup request");
+            }
+            throw new ApiError("agent.not_found", "Agent not found");
+        }
+        const row = await this.kdb.db
+            .selectFrom("catalog_requests")
+            .select("id")
+            .where("org_id", "=", orgId)
+            .where("agent_id", "=", agentId)
+            .where("kind", "=", "connector_setup")
+            .orderBy("created_at", "desc")
+            .orderBy("id", "desc")
+            .executeTakeFirst();
+        return row?.id ?? null;
+    }
+};
+__decorate([
+    Transactional()
+], PendingConnectorsService.prototype, "bind", null);
+__decorate([
+    Transactional()
+], PendingConnectorsService.prototype, "reopen", null);
+PendingConnectorsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(AgentLookup)),
+    __param(3, Inject(PendingConnectorRequests)),
+    __param(4, Inject(TransactionHost))
+], PendingConnectorsService);
+export { PendingConnectorsService };

package/dist/agents/profile.d.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+/** The ten built-in pixel-animal avatars (drawn by `@capybara-hq/design`). */
+export declare const PRESET_IDS: readonly ["capybara", "black-bear", "panda", "elephant", "fox", "owl", "penguin", "rabbit", "turtle", "whale"];
+export type PresetId = (typeof PRESET_IDS)[number];
+export declare const PROFILE_LIMITS: {
+    readonly description: 500;
+    readonly quickActions: 9;
+    readonly title: 40;
+    readonly body: 20000;
+};
+/** A random preset id: the avatar of an agent created without one. */
+export declare function randomPreset(): PresetId;
+export declare const AgentAvatarSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"preset">;
+    id: z.ZodEnum<{
+        "black-bear": "black-bear";
+        capybara: "capybara";
+        elephant: "elephant";
+        fox: "fox";
+        owl: "owl";
+        panda: "panda";
+        penguin: "penguin";
+        rabbit: "rabbit";
+        turtle: "turtle";
+        whale: "whale";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    uploadId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"external">;
+    url: z.ZodURL;
+}, z.core.$strict>], "kind">;
+/** `null` only for agents created before profiles existed. */
+export type AgentAvatar = z.infer<typeof AgentAvatarSchema> | null;
+export declare const QuickActionSchema: z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodString;
+}, z.core.$strict>;
+export type QuickAction = z.infer<typeof QuickActionSchema>;
+export declare const DescriptionSchema: z.ZodString;
+export declare const QuickActionsSchema: z.ZodArray<z.ZodObject<{
+    title: z.ZodString;
+    body: z.ZodString;
+}, z.core.$strict>>;
+/** What a client may write (`external` is migrated data only). */
+export declare const AvatarInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"preset">;
+    id: z.ZodEnum<{
+        "black-bear": "black-bear";
+        capybara: "capybara";
+        elephant: "elephant";
+        fox: "fox";
+        owl: "owl";
+        panda: "panda";
+        penguin: "penguin";
+        rabbit: "rabbit";
+        turtle: "turtle";
+        whale: "whale";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+    uploadId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const ProfileInputSchema: z.ZodObject<{
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"preset">;
+        id: z.ZodEnum<{
+            "black-bear": "black-bear";
+            capybara: "capybara";
+            elephant: "elephant";
+            fox: "fox";
+            owl: "owl";
+            panda: "panda";
+            penguin: "penguin";
+            rabbit: "rabbit";
+            turtle: "turtle";
+            whale: "whale";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"upload">;
+        uploadId: z.ZodString;
+    }, z.core.$strict>], "kind">>>;
+    description: z.ZodOptional<z.ZodString>;
+    quickActions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        body: z.ZodString;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type ProfileInput = z.infer<typeof ProfileInputSchema>;
+export interface AgentProfile {
+    avatar: AgentAvatar;
+    description: string;
+    quickActions: QuickAction[];
+    updatedAt: string;
+}

package/dist/agents/profile.js

@@ -0,0 +1,51 @@
+import { randomInt } from "node:crypto";
+import { z } from "zod";
+/** The ten built-in pixel-animal avatars (drawn by `@capybara-hq/design`). */
+export const PRESET_IDS = [
+    "capybara",
+    "black-bear",
+    "panda",
+    "elephant",
+    "fox",
+    "owl",
+    "penguin",
+    "rabbit",
+    "turtle",
+    "whale",
+];
+export const PROFILE_LIMITS = {
+    description: 500,
+    quickActions: 9,
+    title: 40,
+    body: 20_000,
+};
+/** A random preset id: the avatar of an agent created without one. */
+export function randomPreset() {
+    return PRESET_IDS[randomInt(PRESET_IDS.length)];
+}
+export const AgentAvatarSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("preset"), id: z.enum(PRESET_IDS) }).strict(),
+    z.object({ kind: z.literal("upload"), uploadId: z.string().min(1).max(200) }).strict(),
+    // only produced by the migration of `definition.avatarUrl`; never accepted from a client
+    z.object({ kind: z.literal("external"), url: z.url() }).strict(),
+]);
+export const QuickActionSchema = z
+    .object({
+    title: z.string().min(1).max(PROFILE_LIMITS.title),
+    body: z.string().min(1).max(PROFILE_LIMITS.body),
+})
+    .strict();
+export const DescriptionSchema = z.string().max(PROFILE_LIMITS.description);
+export const QuickActionsSchema = z.array(QuickActionSchema).max(PROFILE_LIMITS.quickActions);
+/** What a client may write (`external` is migrated data only). */
+export const AvatarInputSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("preset"), id: z.enum(PRESET_IDS) }).strict(),
+    z.object({ kind: z.literal("upload"), uploadId: z.string().min(1).max(200) }).strict(),
+]);
+export const ProfileInputSchema = z
+    .object({
+    avatar: AvatarInputSchema.nullable().optional(),
+    description: DescriptionSchema.optional(),
+    quickActions: QuickActionsSchema.optional(),
+})
+    .strict();

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

@@ -0,0 +1,26 @@
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService } from "./agents.service.js";
+/**
+ * Whether the org can run (`/api/v1/orgs/:orgId/readiness`, web-order spec §3.8): the web app
+ * decides between the shell and the setup layout with it. `modelProvider` is `ready` when a
+ * model-provider extension is loaded (enabled and configured), from extension state only, never
+ * a vendor call; `agents` is the number of agents the caller can see (the agent list's
+ * visibility). Humans and service tokens (`org.read`).
+ *
+ * `modelProvider` is deployment-wide, not about this org: model providers are not org-scoped
+ * (an org's model purposes map onto the deployment's providers but cannot add one), so every org
+ * of the deployment reads the same value. It is read from this replica's provider registry, which
+ * follows the per-replica extension reconcile: right after a provider is enabled, a replica that
+ * has not reconciled yet may still answer `none` for a moment.
+ */
+export declare class ReadinessController {
+    private readonly registry;
+    private readonly agents;
+    constructor(registry: ProviderRegistry, agents: AgentsService);
+    get(principal: Principal, org: OrgContext): Promise<{
+        modelProvider: "ready" | "none";
+        agents: number;
+    }>;
+}

package/dist/agents/readiness.controller.js

@@ -0,0 +1,56 @@
+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 { CurrentPrincipal } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { AgentsService } from "./agents.service.js";
+/** Service tokens have no account: they see `visibility='org'` agents only (as the agent list). */
+const viewerOf = (p) => (p.kind === "user" ? p.account.id : null);
+/**
+ * Whether the org can run (`/api/v1/orgs/:orgId/readiness`, web-order spec §3.8): the web app
+ * decides between the shell and the setup layout with it. `modelProvider` is `ready` when a
+ * model-provider extension is loaded (enabled and configured), from extension state only, never
+ * a vendor call; `agents` is the number of agents the caller can see (the agent list's
+ * visibility). Humans and service tokens (`org.read`).
+ *
+ * `modelProvider` is deployment-wide, not about this org: model providers are not org-scoped
+ * (an org's model purposes map onto the deployment's providers but cannot add one), so every org
+ * of the deployment reads the same value. It is read from this replica's provider registry, which
+ * follows the per-replica extension reconcile: right after a provider is enabled, a replica that
+ * has not reconciled yet may still answer `none` for a moment.
+ */
+let ReadinessController = class ReadinessController {
+    registry;
+    agents;
+    constructor(registry, agents) {
+        this.registry = registry;
+        this.agents = agents;
+    }
+    async get(principal, org) {
+        const visible = await this.agents.listVisible(org.orgId, viewerOf(principal));
+        return {
+            modelProvider: this.registry.hasProvider() ? "ready" : "none",
+            agents: visible.length,
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], ReadinessController.prototype, "get", null);
+ReadinessController = __decorate([
+    Controller("api/v1/orgs/:orgId/readiness"),
+    __param(0, Inject(ProviderRegistry)),
+    __param(1, Inject(AgentsService))
+], ReadinessController);
+export { ReadinessController };

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

@@ -1,15 +1,96 @@
+import { z } from "zod";
+import { OwnedItems, type OwnedSkillDeletePreview } from "../catalog/owned-items.js";
+import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { type AgentTemplateDetail, OrgAgentTemplates, type SaveAsOmission } from "./org-templates.js";
 import { AgentTemplatesService, type AgentTemplateView } from "./templates.js";
+declare const IdParams: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+declare const AgentIdParams: z.ZodObject<{
+    agentId: z.ZodString;
+}, z.core.$strip>;
+declare const ShareableBody: z.ZodObject<{
+    shareable: z.ZodBoolean;
+}, z.core.$strict>;
+declare const SaveAsBody: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>;
+declare const UpdateBody: z.ZodObject<{
+    definition: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    expectedVersion: z.ZodNumber;
+}, z.core.$strict>;
 /**
- * The org's agent templates installed from plugins (`/api/v1/orgs/:orgId/agent-templates`, phase C
- * spec §17): the agent page lists them to select as sub-agents. Read with `agents.create`, the
- * permission of its only consumer, the agent editor (members, people only); a template carries no
- * secret, but guests and service tokens have no use for the list.
+ * The org's agent templates (`/api/v1/orgs/:orgId/agent-templates`, phase C spec §17; plugin scope
+ * phase 4, rulings P4-9 to P4-13). Reads with `agents.create` (members, people only): the list
+ * the agent editor and the 模板 tab show, and one template's detail with its definition. The org's
+ * own templates (saved from an agent, `POST orgs/:orgId/agents/:agentId/save-as-template`) are
+ * edited, deleted and made 可共享 by the owner org's admins (`agents.manage`, the action that
+ * manages agent templates).
  */
 export declare class AgentTemplatesController {
     private readonly templates;
-    constructor(templates: AgentTemplatesService);
+    private readonly orgTemplates;
+    private readonly owned;
+    constructor(templates: AgentTemplatesService, orgTemplates: OrgAgentTemplates, owned: OwnedItems);
     list(org: OrgContext): Promise<{
         templates: AgentTemplateView[];
     }>;
+    /**
+     * One template usable in the org (an org template, a linked copy, a platform template on in
+     * the org) with its definition, owner and the org's flags (`owned`, `shareable`, `promoted`).
+     * Not usable here -> 404 `component.not_found`.
+     */
+    get(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>): Promise<{
+        template: AgentTemplateDetail;
+    }>;
+    /**
+     * A new version of the org's own template (ruling P4-12): `{ definition, expectedVersion }` ->
+     * 200 `{ template }`; a stale version -> 409 `agent_template.version_conflict`; a template the
+     * org does not own -> 409 `catalog.not_owned`.
+     */
+    update(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>, body: z.infer<typeof UpdateBody>): Promise<{
+        template: AgentTemplateDetail;
+    }>;
+    /**
+     * What deleting the org's own template does (nothing written): `outcome` `transferred` when it
+     * was shared and another org uses it (`orgs`), else `removed`; `agents` the org's agents whose
+     * roster loses it.
+     */
+    deletePreview(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>): Promise<OwnedSkillDeletePreview>;
+    /**
+     * Deletes the org's own template (the P3 owner rules, ruling P4-12): one it shared that another
+     * org uses becomes the platform's (platform notice `ownership_transferred`). 200 `{ outcome }`.
+     */
+    remove(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>): Promise<{
+        outcome: "transferred" | "removed";
+    }>;
+    /**
+     * Sets 可共享 on the org's own agent template (`{ shareable }` -> 200 `{ id, shareable }`; an org
+     * template, ruling P4-13): a plugin's template or a copy of another owner's platform template
+     * -> 409 `catalog.not_owned`; one the org promoted writes its platform row too (ruling P3-2).
+     */
+    setShareable(principal: Principal, org: OrgContext, params: z.infer<typeof IdParams>, body: z.infer<typeof ShareableBody>): Promise<{
+        id: string;
+        shareable: boolean;
+    }>;
+}
+/**
+ * 另存为模板 (ruling P4-9; `agents.manage`, org admins): `POST
+ * /api/v1/orgs/:orgId/agents/:agentId/save-as-template { name, description }` -> 201
+ * `{ template, omitted }`. `template` is the new org template's detail (version 1, the bare
+ * `name`); `omitted` lists what the template leaves out (`SaveAsOmission`: allowlisted org agents
+ * in the roster, the agent's own skills, connectors and sub-agents no longer usable, entries past
+ * a limit). A name the org can already use as a type -> 409 `agent_template.name_taken` (details
+ * `[{ owner, templateId }]`). Its own controller: the agents controller is the agent CRUD.
+ */
+export declare class AgentSaveAsTemplateController {
+    private readonly orgTemplates;
+    constructor(orgTemplates: OrgAgentTemplates);
+    saveAs(principal: Principal, org: OrgContext, params: z.infer<typeof AgentIdParams>, body: z.infer<typeof SaveAsBody>): Promise<{
+        template: AgentTemplateDetail;
+        omitted: SaveAsOmission[];
+    }>;
 }
+export {};