@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

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

@@ -0,0 +1,122 @@
+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, quick actions): display data stored beside the agent, never
+ * model-visible, so a change creates no agent version. The description is part of the definition
+ * (run context spec §3.5). 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, ...auditDetail }`: `api` for a personal access
+     * token, `agent` for a write through the `Platform` tool (`auditDetail` given), 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, auditDetail) {
+        if (patch.avatar?.kind === "upload") {
+            await this.attachments.prepareAgentAvatar(orgId, actorAccountId, patch.avatar.uploadId, agentId);
+        }
+        return this.updateIn(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId, auditDetail);
+    }
+    async updateIn(orgId, agentId, actorAccountId, patch, expectedUpdatedAt, actorTokenId, auditDetail) {
+        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", "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.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" : auditDetail !== undefined ? "agent" : "web",
+                ...auditDetail,
+            },
+        });
+        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,176 +1,24 @@
+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 { type AgentsService, type AgentVersionSummary, type AgentView, type AgentWarning } from "./agents.service.js";
+import { AgentProfileService } from "./agent-profile.service.js";
+import { AgentCreateBody, AgentFromTemplateBody, AgentFromTemplatePreviewBody, AgentProfileBody, AgentUpdateBody } from "./agents.schemas.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>;
-declare const CreateBody: z.ZodObject<{
-    definition: 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]>>>;
-        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>>;
-        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>>>;
-    }, z.core.$strip>;
-    visibility: z.ZodEnum<{
-        members: "members";
-        org: "org";
-        private: "private";
+declare const AvatarUploadBody: z.ZodObject<{
+    name: z.ZodString;
+    contentType: z.ZodEnum<{
+        "image/jpeg": "image/jpeg";
+        "image/png": "image/png";
+        "image/webp": "image/webp";
     }>;
-    memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, 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>;
-        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>>;
-    visibility: z.ZodOptional<z.ZodEnum<{
-        members: "members";
-        org: "org";
-        private: "private";
-    }>>;
-    memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    expectedVersion: z.ZodOptional<z.ZodNumber>;
+    size: z.ZodNumber;
 }, z.core.$strict>;
 /**
  * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
@@ -178,8 +26,29 @@ declare const UpdateBody: z.ZodObject<{
  */
 export declare class AgentsController {
     private readonly agents;
-    constructor(agents: AgentsService);
-    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
+    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 AgentFromTemplatePreviewBody>): 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 AgentFromTemplateBody>): Promise<{
+        agent: AgentView;
+    }>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof AgentCreateBody>): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];
     }>;
@@ -189,10 +58,26 @@ export declare class AgentsController {
     get(principal: Principal, org: OrgContext, agentId: string): Promise<{
         agent: AgentView;
     }>;
-    update(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof UpdateBody>): Promise<{
+    update(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof AgentUpdateBody>): Promise<{
         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 AgentProfileBody>): 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<{

package/dist/agents/agents.controller.js

@@ -7,49 +7,93 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, } from "@nestjs/common";
+import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, Res } from "@nestjs/common";
 import { z } from "zod";
-import { AGENTS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
+import { AGENT_AVATAR_CONTENT_TYPES, AGENT_AVATAR_DOWNLOAD_TTL_SECONDS, AGENT_AVATAR_MAX_BYTES, AttachmentsService, } from "../conversations/attachments.service.js";
+import { ApiError } from "../errors.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
-import { AGENT_VISIBILITIES, } from "./agents.service.js";
-import { AgentDefinitionSchema, AgentToolRef, DEFAULT_AGENT_TOOLS } from "./definition.js";
-const MemberIds = z.array(z.string().min(1).max(100)).max(1000);
+import { AgentProfileService } from "./agent-profile.service.js";
+import { AgentCreateBody, AgentFromTemplateBody, AgentFromTemplatePreviewBody, AgentProfileBody, AgentUpdateBody, } from "./agents.schemas.js";
+import { AgentsService, } from "./agents.service.js";
+import { AgentsFromTemplate } from "./from-template.service.js";
 const OwnerBody = z.object({ accountId: z.string().min(1).max(100) }).strict();
-/** 创建时未给 `tools` → 默认工具（Ruling P7）；修改请求不注入默认值，版本里总是存显式的 tools。 */
-const CreateDefinition = AgentDefinitionSchema.extend({
-    tools: z.array(AgentToolRef).default(() => structuredClone(DEFAULT_AGENT_TOOLS)),
-});
-const CreateBody = z
+const AvatarUploadBody = z
     .object({
-    definition: CreateDefinition,
-    visibility: z.enum(AGENT_VISIBILITIES),
-    memberIds: MemberIds.optional(),
-})
-    .strict();
-const UpdateBody = z
-    .object({
-    definition: AgentDefinitionSchema.optional(),
-    visibility: z.enum(AGENT_VISIBILITIES).optional(),
-    memberIds: MemberIds.optional(),
-    /**
-     * 乐观并发：编辑页打开时读到的 `currentVersion`。给出且与当前版本不同（别人已保存过）→ 409
-     * `agent.version_conflict`，不覆盖别人的改动。不给时不检查（旧客户端）。
-     */
-    expectedVersion: z.number().int().positive().optional(),
+    name: z
+        .string()
+        .min(1)
+        .max(MEDIA_NAME_MAX_CHARS)
+        .refine((s) => !hasControlChars(s), "name must not contain control characters"),
+    contentType: z.enum(AGENT_AVATAR_CONTENT_TYPES),
+    size: z.number().int().min(1).max(AGENT_AVATAR_MAX_BYTES),
 })
     .strict();
 /** 服务令牌没有账号：以 null 作为 viewer，只看到 visibility='org' 的 agent。 */
 const viewerOf = (p) => (p.kind === "user" ? p.account.id : null);
+class AgentCreateBodyDto extends createZodDto(AgentCreateBody, "AgentCreateBody") {
+}
+class AgentUpdateBodyDto extends createZodDto(AgentUpdateBody, "AgentUpdateBody") {
+}
+class AgentProfileBodyDto extends createZodDto(AgentProfileBody, "AgentProfileBody") {
+}
+class AgentAvatarUploadBodyDto extends createZodDto(AvatarUploadBody, "AgentAvatarUploadBody") {
+}
+class AgentOwnerBodyDto extends createZodDto(OwnerBody, "AgentOwnerBody") {
+}
+class AgentFromTemplatePreviewBodyDto extends createZodDto(AgentFromTemplatePreviewBody, "AgentFromTemplatePreviewBody") {
+}
+class AgentFromTemplateBodyDto extends createZodDto(AgentFromTemplateBody, "AgentFromTemplateBody") {
+}
 /**
  * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
  * 写用 `agents.create`（member 以上、HUMAN_ONLY），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
  */
 let AgentsController = class AgentsController {
     agents;
-    constructor(agents) {
+    profiles;
+    attachments;
+    fromTemplate;
+    constructor(agents, profiles, attachments, fromTemplate) {
         this.agents = agents;
+        this.profiles = profiles;
+        this.attachments = attachments;
+        this.fromTemplate = fromTemplate;
+    }
+    /** A response's view with its provenance link (`createdFrom.available`, ruling P4-8). */
+    async linked(orgId, view) {
+        return (await this.agents.withTemplateLinks(orgId, [view]))[0];
+    }
+    /**
+     * 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`.
+     */
+    async previewFromTemplate(org, body) {
+        return this.fromTemplate.preview(org.orgId, body.templateId);
+    }
+    /**
+     * 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).
+     */
+    async createFromTemplate(principal, org, body) {
+        const p = requireUser(principal);
+        const { agent } = await this.fromTemplate.create(org.orgId, p.account.id, {
+            templateId: body.templateId,
+            name: body.name,
+            previewHash: body.previewHash,
+            ...(body.visibility !== undefined && { visibility: body.visibility }),
+            ...(body.members !== undefined && { members: body.members }),
+            ...(body.model !== undefined && { model: body.model }),
+            ...(body.avatar !== undefined && { avatar: body.avatar }),
+        }, patTokenId(p));
+        return { agent: await this.linked(org.orgId, agent) };
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
@@ -57,17 +101,68 @@ let AgentsController = class AgentsController {
             definition: body.definition,
             visibility: body.visibility,
             ...(body.memberIds !== undefined && { memberIds: body.memberIds }),
+            ...(body.profile !== undefined && { profile: body.profile }),
         }, patTokenId(p));
     }
     async list(principal, org) {
-        return { agents: await this.agents.listVisible(org.orgId, viewerOf(principal)) };
+        const agents = await this.agents.listVisible(org.orgId, viewerOf(principal));
+        return { agents: await this.agents.withTemplateLinks(org.orgId, agents) };
     }
     async get(principal, org, agentId) {
-        return { agent: await this.agents.get(org.orgId, agentId, viewerOf(principal)) };
+        return {
+            agent: await this.linked(org.orgId, await this.agents.get(org.orgId, agentId, viewerOf(principal))),
+        };
     }
     async update(principal, org, agentId, body) {
         const p = requireUser(principal);
-        return this.agents.update(org.orgId, agentId, p.account.id, body, patTokenId(p));
+        const r = await this.agents.update(org.orgId, agentId, p.account.id, body, patTokenId(p));
+        return { ...r, agent: await this.linked(org.orgId, r.agent) };
+    }
+    /** Display data only: no agent version. Same permission as `PATCH :agentId`. */
+    async updateProfile(principal, org, agentId, body) {
+        const p = requireUser(principal);
+        const { expectedUpdatedAt, ...patch } = body;
+        return {
+            profile: await this.profiles.update(org.orgId, agentId, p.account.id, patch, expectedUpdatedAt, patTokenId(p)),
+        };
+    }
+    /**
+     * 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.
+     */
+    async createAvatarUpload(principal, org, agentId, body) {
+        const p = requireUser(principal);
+        // the agent must exist and be visible to the caller (writing is checked when it is saved)
+        await this.agents.get(org.orgId, agentId, viewerOf(p));
+        return this.attachments.create(org.orgId, p.account.id, body, "agent-avatar");
+    }
+    /**
+     * 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.
+     */
+    async avatar(principal, org, agentId, reply) {
+        const view = await this.agents.get(org.orgId, agentId, viewerOf(principal));
+        const avatar = view.profile.avatar;
+        let location = null;
+        if (avatar?.kind === "upload") {
+            location = await this.attachments.agentAvatarUrl(org.orgId, agentId, avatar.uploadId);
+        }
+        else if (avatar?.kind === "external") {
+            try {
+                if (new URL(avatar.url).protocol === "https:")
+                    location = avatar.url;
+            }
+            catch {
+                // a malformed migrated URL: no image
+            }
+        }
+        if (location === null)
+            throw new ApiError("agent.not_found", "The agent has no avatar image");
+        await reply
+            .header("cache-control", `private, max-age=${Math.floor(AGENT_AVATAR_DOWNLOAD_TTL_SECONDS / 5)}`)
+            .redirect(location, 302);
     }
     async remove(principal, org, agentId) {
         const p = requireUser(principal);
@@ -76,21 +171,34 @@ let AgentsController = class AgentsController {
     /** 重新指派负责人（admin，如负责人离职后）；清除 `needsReassignment`。 */
     async reassign(principal, org, agentId, body) {
         const p = requireUser(principal);
-        return {
-            agent: await this.agents.reassignOwner(org.orgId, agentId, body.accountId, p.account.id, patTokenId(p)),
-        };
+        const agent = await this.agents.reassignOwner(org.orgId, agentId, body.accountId, p.account.id, patTokenId(p));
+        return { agent: await this.linked(org.orgId, agent) };
     }
     async versions(principal, org, agentId) {
         await this.agents.get(org.orgId, agentId, viewerOf(principal));
         return { versions: await this.agents.listVersions(agentId) };
     }
 };
+__decorate([
+    Post("from-template/preview"),
+    HttpCode(200),
+    OrgAction("agents.create"),
+    __param(0, CurrentOrg()),
+    __param(1, ZBody(AgentFromTemplatePreviewBodyDto))
+], AgentsController.prototype, "previewFromTemplate", null);
+__decorate([
+    Post("from-template"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(AgentFromTemplateBodyDto))
+], AgentsController.prototype, "createFromTemplate", null);
 __decorate([
     Post(),
     OrgAction("agents.create"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(CreateBody)))
+    __param(2, ZBody(AgentCreateBodyDto))
 ], AgentsController.prototype, "create", null);
 __decorate([
     Get(),
@@ -111,8 +219,32 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("agentId")),
-    __param(3, Body(new ZodPipe(UpdateBody)))
+    __param(3, ZBody(AgentUpdateBodyDto))
 ], AgentsController.prototype, "update", null);
+__decorate([
+    Patch(":agentId/profile"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, ZBody(AgentProfileBodyDto))
+], AgentsController.prototype, "updateProfile", null);
+__decorate([
+    Post(":agentId/avatar/uploads"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, ZBody(AgentAvatarUploadBodyDto))
+], AgentsController.prototype, "createAvatarUpload", null);
+__decorate([
+    Get(":agentId/avatar"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Res())
+], AgentsController.prototype, "avatar", null);
 __decorate([
     Delete(":agentId"),
     HttpCode(204),
@@ -128,7 +260,7 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, Param("agentId")),
-    __param(3, Body(new ZodPipe(OwnerBody)))
+    __param(3, ZBody(AgentOwnerBodyDto))
 ], AgentsController.prototype, "reassign", null);
 __decorate([
     Get(":agentId/versions"),
@@ -139,6 +271,9 @@ __decorate([
 ], AgentsController.prototype, "versions", null);
 AgentsController = __decorate([
     Controller("api/v1/orgs/:orgId/agents"),
-    __param(0, Inject(AGENTS))
+    __param(0, Inject(AgentsService)),
+    __param(1, Inject(AgentProfileService)),
+    __param(2, Inject(AttachmentsService)),
+    __param(3, Inject(AgentsFromTemplate))
 ], AgentsController);
 export { AgentsController };

package/dist/agents/agents.module.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agents: the one {@link AgentsService} (definitions, versions, visibility; writes under the org
+ * row lock), the agent templates (the plugin ones, and the org's own: `OrgAgentTemplates`),
+ * creating agents from templates (`AgentsFromTemplate`) with its pending connector request seam
+ * (`PendingConnectorRequests`, ruling P4-7), and binding pending connectors
+ * (`PendingConnectorsService`, P4-6). Reads for a viewer are {@link AgentLookupModule}'s
+ * (re-exported), which the conversations and the skill invoker use without this module.
+ */
+export declare class AgentsModule {
+}