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

package/dist/admin/setup.controller.js

@@ -56,7 +56,7 @@ let SetupController = class SetupController {
         return this.setup.status();
     }
     /**
-     * 建首个企业管理员（可选同时建组织），成功后直接登录（设会话 Cookie）。
+     * 建首个超级管理员（可选同时建组织），成功后直接登录（设会话 Cookie）。
      * 配置了 `auth.setupToken` 时 body 中的 `setupToken` 必须与之相等，否则 `setup.token_invalid`；
      * 核对前先占用限流额度，超限 → 429 `auth.rate_limited`，核对通过后退还。
      */

package/dist/admin/setup.service.d.ts

@@ -4,8 +4,8 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { type Org, OrgsService } from "../orgs/orgs.service.js";
 import { SetupLock } from "./setup-lock.js";
 /**
- * The setup wizard. The CLI's enterprise admin creation (`createEnterpriseAdmin`,
- * `createEnterpriseAdminIfNone`) is on `AccountsService`, under the same {@link SetupLock}.
+ * The setup wizard. The CLI's super admin creation (`createSuperAdmin`,
+ * `createSuperAdminIfNone`) is on `AccountsService`, under the same {@link SetupLock}.
  */
 export declare class SetupService {
     private readonly db;
@@ -14,13 +14,13 @@ export declare class SetupService {
     private readonly accounts;
     private readonly orgs;
     constructor(db: KernelDb, txHost: TransactionHost, setupLock: SetupLock, accounts: AccountsService, orgs: OrgsService);
-    /** 不存在活跃企业管理员即需要初始化（每次实时查 PG，不缓存）。 */
+    /** 不存在活跃超级管理员即需要初始化（每次实时查 PG，不缓存）。 */
     status(): Promise<{
         needsSetup: boolean;
     }>;
     /**
      * Completes the setup in one transaction: {@link SetupLock} serializes concurrent setups, and
-     * under it there must still be no active enterprise admin; then creates the enterprise admin
+     * under it there must still be no active super admin; then creates the super admin
      * and (with `orgName`) an org it owns. Any failure rolls everything back. `inTx` runs last in the
      * same transaction (the wizard creates the session there), its result is `extra`; its failure
      * rolls back too.

package/dist/admin/setup.service.js

@@ -18,8 +18,8 @@ import { OrgsService } from "../orgs/orgs.service.js";
 import { SetupLock } from "./setup-lock.js";
 const alreadyCompleted = () => new ApiError("setup.already_completed", "Deployment is already set up");
 /**
- * The setup wizard. The CLI's enterprise admin creation (`createEnterpriseAdmin`,
- * `createEnterpriseAdminIfNone`) is on `AccountsService`, under the same {@link SetupLock}.
+ * The setup wizard. The CLI's super admin creation (`createSuperAdmin`,
+ * `createSuperAdminIfNone`) is on `AccountsService`, under the same {@link SetupLock}.
  */
 let SetupService = class SetupService {
     db;
@@ -34,13 +34,13 @@ let SetupService = class SetupService {
         this.accounts = accounts;
         this.orgs = orgs;
     }
-    /** 不存在活跃企业管理员即需要初始化（每次实时查 PG，不缓存）。 */
+    /** 不存在活跃超级管理员即需要初始化（每次实时查 PG，不缓存）。 */
     async status() {
-        return { needsSetup: (await this.accounts.countEnterpriseAdmins()) === 0 };
+        return { needsSetup: (await this.accounts.countSuperAdmins()) === 0 };
     }
     /**
      * Completes the setup in one transaction: {@link SetupLock} serializes concurrent setups, and
-     * under it there must still be no active enterprise admin; then creates the enterprise admin
+     * under it there must still be no active super admin; then creates the super admin
      * and (with `orgName`) an org it owns. Any failure rolls everything back. `inTx` runs last in the
      * same transaction (the wizard creates the session there), its result is `extra`; its failure
      * rolls back too.
@@ -48,20 +48,20 @@ let SetupService = class SetupService {
     async complete(input, inTx) {
         // A cheap pre-check first (a set-up deployment does not run scrypt for nothing), then the hash
         // before BEGIN: no scrypt inside the transaction holding the lock; the check runs again under it
-        if ((await this.accounts.countEnterpriseAdmins()) > 0)
+        if ((await this.accounts.countSuperAdmins()) > 0)
             throw alreadyCompleted();
         const passwordHash = await this.accounts.hashNewPassword(input.password);
         return this.completeIn(input, passwordHash, inTx);
     }
     async completeIn(input, passwordHash, inTx) {
         await this.setupLock.lock();
-        if ((await this.accounts.countEnterpriseAdmins()) > 0)
+        if ((await this.accounts.countSuperAdmins()) > 0)
             throw alreadyCompleted();
         const account = await this.accounts.createLocal({
             login: input.login,
             password: input.password,
             displayName: input.displayName,
-            enterpriseAdmin: true,
+            superAdmin: true,
         }, passwordHash);
         const org = input.orgName !== undefined
             ? await this.orgs.create({ name: input.orgName }, account)

package/dist/agents/agent-lookup.d.ts

@@ -2,6 +2,7 @@ import { type ExpressionBuilder } from "kysely";
 import type { KernelDatabase, KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { type AgentDefinition } from "./definition.js";
+import type { AgentProfile } from "./profile.js";
 export declare const AGENT_VISIBILITIES: readonly ["private", "org", "members"];
 export type AgentVisibility = (typeof AGENT_VISIBILITIES)[number];
 /** 对外的 agent 视图：当前版本的定义 + 元数据；`memberIds` 只在 visibility='members' 时为数组。 */
@@ -12,12 +13,30 @@ export interface AgentView {
     visibility: AgentVisibility;
     currentVersion: number;
     definition: AgentDefinition;
+    /** Display data outside the versions (never model-visible). */
+    profile: AgentProfile;
     memberIds: string[] | null;
     /** 负责人离职后被转给组织所有者、等待管理员重新指派。 */
     needsReassignment: boolean;
+    /**
+     * The template the agent was created from (ruling P4-8; set once, never versioned), null for an
+     * agent created otherwise. `name` and `version` are the snapshot taken at create.
+     */
+    createdFrom: AgentProvenance | null;
     createdAt: Date;
     updatedAt: Date;
 }
+/** {@link AgentView.createdFrom}. */
+export interface AgentProvenance {
+    templateId: string;
+    version: number;
+    name: string;
+    /**
+     * The template is still usable in the org (the agent page links it only then). Set on the
+     * agents API's responses only (`AgentsService.withTemplateLinks`), never on internal reads.
+     */
+    available?: boolean;
+}
 /**
  * 可见性判定（`canUse`）的 SQL 条件：agent 未删除、所属组织未删除，且
  * - viewer 为账号：仍是该组织成员（含访客），并且是负责人 / visibility='org' / 在 agent_members 名单中；

package/dist/agents/agent-lookup.js

@@ -132,6 +132,13 @@ let AgentLookup = class AgentLookup {
             "agents.needs_reassignment",
             "agents.created_at",
             "agents.updated_at",
+            "agents.profile_avatar",
+            "agents.profile_description",
+            "agents.profile_quick_actions",
+            "agents.profile_updated_at",
+            "agents.created_from_template_id",
+            "agents.created_from_template_version",
+            "agents.created_from_template_name",
             "agent_versions.definition",
         ])
             .where("agents.id", "in", ids)
@@ -154,6 +161,7 @@ let AgentLookup = class AgentLookup {
             const r = byId.get(id);
             if (!r)
                 return [];
+            const fromId = r.created_from_template_id;
             return [
                 {
                     id: r.id,
@@ -162,10 +170,23 @@ let AgentLookup = class AgentLookup {
                     visibility: r.visibility,
                     currentVersion: r.current_version,
                     definition: normalizeStoredDefinition(r.definition, scopes.get(r.org_id)),
+                    profile: {
+                        avatar: r.profile_avatar,
+                        description: r.profile_description,
+                        quickActions: r.profile_quick_actions,
+                        updatedAt: r.profile_updated_at.toISOString(),
+                    },
                     memberIds: r.visibility === "members"
                         ? memberRows.filter((m) => m.agent_id === id).map((m) => m.account_id)
                         : null,
                     needsReassignment: r.needs_reassignment,
+                    createdFrom: fromId === null
+                        ? null
+                        : {
+                            templateId: fromId,
+                            version: r.created_from_template_version ?? 1,
+                            name: r.created_from_template_name ?? "",
+                        },
                     createdAt: r.created_at,
                     updatedAt: r.updated_at,
                 },

package/dist/agents/agent-profile.service.d.ts

@@ -0,0 +1,29 @@
+import { AttachmentsService } from "../conversations/attachments.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { AgentLookup } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.js";
+import type { AgentProfile, ProfileInput } from "./profile.js";
+/**
+ * Writes an agent's profile (avatar, description, quick actions): display data stored beside the
+ * agent, never model-visible, so a change creates no agent version. The permission is the one of
+ * `AgentsService.update` (owner or org admin, checked under the org row lock).
+ */
+export declare class AgentProfileService {
+    private readonly db;
+    private readonly lookup;
+    private readonly agents;
+    private readonly attachments;
+    readonly txHost: TransactionHost;
+    constructor(db: KernelDb, lookup: AgentLookup, agents: Pick<AgentsService, "lockForWrite">, attachments: Pick<AttachmentsService, "prepareAgentAvatar" | "consumeAgentAvatar">, txHost: TransactionHost);
+    /**
+     * Applies `patch` (only the given fields) when `expectedUpdatedAt` is still the profile's
+     * `updatedAt`, else 409 `agent.profile_conflict` (never a silent overwrite). Audit
+     * `agent.profile_updated` `{ fields, channel }`: `api` for a personal access token, else `web`.
+     * An `upload` avatar must be the actor's own upload that no other agent uses (else 404
+     * `attachment.not_found`): it is finalized first (outside the transaction, it reads the object
+     * store; 503 `storage.unavailable` without one) and bound to the agent inside it.
+     */
+    update(orgId: string, agentId: string, actorAccountId: string, patch: ProfileInput, expectedUpdatedAt: string, actorTokenId?: string): Promise<AgentProfile>;
+    private updateIn;
+}

package/dist/agents/agent-profile.service.js

@@ -0,0 +1,117 @@
+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 { sql } from "kysely";
+import { AttachmentsService } from "../conversations/attachments.service.js";
+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 { AgentLookup } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.js";
+/**
+ * Writes an agent's profile (avatar, description, quick actions): display data stored beside the
+ * agent, never model-visible, so a change creates no agent version. The permission is the one of
+ * `AgentsService.update` (owner or org admin, checked under the org row lock).
+ */
+let AgentProfileService = class AgentProfileService {
+    db;
+    lookup;
+    agents;
+    attachments;
+    txHost;
+    constructor(db, lookup, agents, attachments, txHost) {
+        this.db = db;
+        this.lookup = lookup;
+        this.agents = agents;
+        this.attachments = attachments;
+        this.txHost = txHost;
+    }
+    /**
+     * Applies `patch` (only the given fields) when `expectedUpdatedAt` is still the profile's
+     * `updatedAt`, else 409 `agent.profile_conflict` (never a silent overwrite). Audit
+     * `agent.profile_updated` `{ fields, channel }`: `api` for a personal access token, else `web`.
+     * An `upload` avatar must be the actor's own upload that no other agent uses (else 404
+     * `attachment.not_found`): it is finalized first (outside the transaction, it reads the object
+     * store; 503 `storage.unavailable` without one) and bound to the agent inside it.
+     */
+    async update(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId) {
+        if (patch.avatar?.kind === "upload") {
+            await this.attachments.prepareAgentAvatar(orgId, actorAccountId, patch.avatar.uploadId, agentId);
+        }
+        return this.updateIn(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId);
+    }
+    async updateIn(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId) {
+        const t = this.db.db;
+        await this.agents.lockForWrite(orgId, agentId, actorAccountId);
+        const current = await t
+            .selectFrom("agents")
+            .select(sql `to_char(profile_updated_at at time zone 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`.as("at"))
+            .where("id", "=", agentId)
+            .executeTakeFirstOrThrow();
+        if (current.at !== expectedUpdatedAt) {
+            throw new ApiError("agent.profile_conflict", "The profile was changed by someone else; reload it and apply your changes again");
+        }
+        if (patch.avatar?.kind === "upload") {
+            await this.attachments.consumeAgentAvatar(orgId, actorAccountId, patch.avatar.uploadId, agentId);
+        }
+        const fields = ["avatar", "description", "quickActions"].filter((f) => patch[f] !== undefined);
+        // nothing to write: no timestamp bump, no audit row
+        if (fields.length === 0)
+            return (await this.lookup.view(agentId)).profile;
+        await t
+            .updateTable("agents")
+            .set({
+            ...(patch.avatar !== undefined && {
+                profile_avatar: patch.avatar === null ? sql `null` : JSON.stringify(patch.avatar),
+            }),
+            ...(patch.description !== undefined && { profile_description: patch.description }),
+            ...(patch.quickActions !== undefined && {
+                profile_quick_actions: JSON.stringify(patch.quickActions),
+            }),
+            profile_updated_at: sql `greatest(date_trunc('milliseconds', now()), profile_updated_at + interval '1 millisecond')`,
+        })
+            .where("id", "=", agentId)
+            .execute();
+        if (patch.avatar !== undefined) {
+            // the avatar changed: every other upload bound to this agent is garbage; the cleanup job
+            // deletes it (and its object) once expired. Re-saving the same upload keeps it.
+            await t
+                .updateTable("attachments")
+                .set({ expires_at: sql `now()` })
+                .where("agent_id", "=", agentId)
+                .where("purpose", "=", "agent-avatar")
+                .$if(patch.avatar?.kind === "upload", (q) => q.where("id", "<>", patch.avatar.uploadId))
+                .execute();
+        }
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "agent.profile_updated",
+            target: agentId,
+            detail: { fields, channel: actorTokenId !== undefined ? "api" : "web" },
+        });
+        return (await this.lookup.view(agentId)).profile;
+    }
+};
+__decorate([
+    Transactional()
+], AgentProfileService.prototype, "updateIn", null);
+AgentProfileService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentLookup)),
+    __param(2, Inject(AgentsService)),
+    __param(3, Inject(AttachmentsService)),
+    __param(4, Inject(TransactionHost))
+], AgentProfileService);
+export { AgentProfileService };

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

@@ -1,7 +1,12 @@
+import type { FastifyReply } from "fastify";
 import { z } from "zod";
+import { AttachmentsService, type CreatedAttachment } from "../conversations/attachments.service.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
+import { AgentProfileService } from "./agent-profile.service.js";
 import { AgentsService, type AgentVersionSummary, type AgentView, type AgentWarning } from "./agents.service.js";
+import { AgentsFromTemplate, type TemplatePreview } from "./from-template.service.js";
+import { type AgentProfile } from "./profile.js";
 declare const OwnerBody: z.ZodObject<{
     accountId: z.ZodString;
 }, z.core.$strict>;
@@ -9,7 +14,10 @@ declare const CreateBody: z.ZodObject<{
     definition: z.ZodObject<{
         name: z.ZodString;
         avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
-        instructions: z.ZodDefault<z.ZodString>;
+        instructionFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strict>>>;
         model: z.ZodObject<{
             provider: z.ZodString;
             model: z.ZodString;
@@ -68,6 +76,7 @@ declare const CreateBody: z.ZodObject<{
             }, z.core.$strict>>>;
             dispatchable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
+        instructions: z.ZodOptional<z.ZodString>;
         tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
             kind: z.ZodLiteral<"builtin">;
             name: z.ZodString;
@@ -87,12 +96,75 @@ declare const CreateBody: z.ZodObject<{
         private: "private";
     }>;
     memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    profile: z.ZodOptional<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>>;
+}, z.core.$strict>;
+declare const ProfileBody: 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>>>;
+    expectedUpdatedAt: z.ZodString;
+}, z.core.$strict>;
+declare const AvatarUploadBody: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodEnum<{
+        "image/jpeg": "image/jpeg";
+        "image/png": "image/png";
+        "image/webp": "image/webp";
+    }>;
+    size: z.ZodNumber;
 }, z.core.$strict>;
 declare const UpdateBody: z.ZodObject<{
     definition: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
-        instructions: z.ZodDefault<z.ZodString>;
+        instructionFiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            content: z.ZodString;
+        }, z.core.$strict>>>;
         model: z.ZodObject<{
             provider: z.ZodString;
             model: z.ZodString;
@@ -163,6 +235,29 @@ declare const UpdateBody: z.ZodObject<{
             }, z.core.$strict>>>;
             dispatchable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
+        pendingConnectors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            source: z.ZodUnion<readonly [z.ZodObject<{
+                template: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                needs: z.ZodObject<{
+                    protocol: z.ZodEnum<{
+                        mcp: "mcp";
+                        openapi: "openapi";
+                    }>;
+                    endpoint: z.ZodString;
+                    tools: z.ZodArray<z.ZodString>;
+                    label: z.ZodString;
+                }, z.core.$strict>;
+            }, z.core.$strict>]>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            policies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                ask: "ask";
+                deny: "deny";
+            }>>>;
+        }, z.core.$strict>>>;
+        instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     visibility: z.ZodOptional<z.ZodEnum<{
         members: "members";
@@ -172,13 +267,67 @@ declare const UpdateBody: z.ZodObject<{
     memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     expectedVersion: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
+declare const FromTemplatePreviewBody: z.ZodObject<{
+    templateId: z.ZodString;
+}, z.core.$strict>;
+declare const FromTemplateBody: z.ZodObject<{
+    templateId: z.ZodString;
+    name: z.ZodString;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        members: "members";
+        org: "org";
+        private: "private";
+    }>>;
+    members: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    model: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>;
+    avatar: z.ZodOptional<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>>;
+    previewHash: z.ZodString;
+}, z.core.$strict>;
 /**
  * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
  * 写用 `agents.create`（member 以上、HUMAN_ONLY），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
  */
 export declare class AgentsController {
     private readonly agents;
-    constructor(agents: AgentsService);
+    private readonly profiles;
+    private readonly attachments;
+    private readonly fromTemplate;
+    constructor(agents: AgentsService, profiles: AgentProfileService, attachments: AttachmentsService, fromTemplate: AgentsFromTemplate);
+    /** A response's view with its provenance link (`createdFrom.available`, ruling P4-8). */
+    private linked;
+    /**
+     * What creating an agent from a template would carry over (rulings P4-3, P4-5): the items
+     * (carried / pending / unavailable, with reasons), the model the dialog preselects (P4-4), the
+     * template fields with no place in the agent, and the `previewHash` the create must send. A
+     * template not usable in the org → 404 `component.not_found`.
+     */
+    previewFromTemplate(org: OrgContext, body: z.infer<typeof FromTemplatePreviewBody>): Promise<TemplatePreview>;
+    /**
+     * Creates an agent from a template (ruling P4-3): private by default; another visibility without
+     * `agents.manage` → 403 `agent.visibility_forbidden`; a plan that no longer matches the preview →
+     * 409 `agent.template_preview_stale`. The agent records its provenance (P4-8) and carries the
+     * template's missing connectors as `pendingConnectors` (P4-6).
+     */
+    createFromTemplate(principal: Principal, org: OrgContext, body: z.infer<typeof FromTemplateBody>): Promise<{
+        agent: AgentView;
+    }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];
@@ -193,6 +342,22 @@ export declare class AgentsController {
         agent: AgentView;
         warnings: AgentWarning[];
     }>;
+    /** Display data only: no agent version. Same permission as `PATCH :agentId`. */
+    updateProfile(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof ProfileBody>): Promise<{
+        profile: AgentProfile;
+    }>;
+    /**
+     * Registers an avatar image upload (presigned, like chat attachments and skill packages): the
+     * browser uploads straight to the object store, then saves `{ kind: "upload", uploadId }` with
+     * the profile PATCH, which finalizes it. 503 `storage.unavailable` without an object store.
+     */
+    createAvatarUpload(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof AvatarUploadBody>): Promise<CreatedAttachment>;
+    /**
+     * The avatar image: 302 to a short-lived presigned URL for an upload avatar, or to the stored
+     * URL of an external avatar when it is https; 404 for presets, no avatar, or an agent the
+     * reader cannot see.
+     */
+    avatar(principal: Principal, org: OrgContext, agentId: string, reply: FastifyReply): Promise<void>;
     remove(principal: Principal, org: OrgContext, agentId: string): Promise<void>;
     /** 重新指派负责人（admin，如负责人离职后）；清除 `needsReassignment`。 */
     reassign(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof OwnerBody>): Promise<{