@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/admin/admin.controller.d.ts

@@ -1,7 +1,8 @@
-import type { Logger } from "@capybara-hq/plugin-sdk";
+import type { LocalizedName, Logger } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { CatalogRequestsService } from "../catalog/requests.service.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { type Account, AccountsService } from "../identity/accounts.js";
 import { type Principal } from "../identity/principal.js";
 import { SessionService } from "../identity/sessions.js";
@@ -82,7 +83,8 @@ export declare class AdminController {
     private readonly plugins;
     private readonly registry;
     private readonly catalogRequests;
-    constructor(accounts: AccountsService, sessions: SessionService, log: Logger, orgs: OrgsService, settings: SettingsService, prices: PricesService, purposes: ModelPurposesService, plugins: ExtensionAdmin, registry: ProviderRegistry, catalogRequests: CatalogRequestsService);
+    private readonly displayNames;
+    constructor(accounts: AccountsService, sessions: SessionService, log: Logger, orgs: OrgsService, settings: SettingsService, prices: PricesService, purposes: ModelPurposesService, plugins: ExtensionAdmin, registry: ProviderRegistry, catalogRequests: CatalogRequestsService, displayNames: ExtensionDisplayNames);
     /** 后台概览的四个数字（只读计数，不含任何对话内容）。 */
     overview(): Promise<AdminOverview>;
     /**
@@ -110,10 +112,13 @@ export declare class AdminController {
     putSettings(principal: Principal, body: z.infer<typeof SettingsSchema>): Promise<DeploymentSettings>;
     /**
      * 模型供应商与模型（后台「模型」页）：每个供应商带状态，列模型失败的标 `error`，不影响其他供应商；
-     * 一并返回价格表与币种（改价仍走 `PUT /admin/model-prices`）。
+     * 一并返回价格表与币种（改价仍走 `PUT /admin/model-prices`）。Each provider carries its extension's
+     * display name (null when it has none).
      */
     getModels(): Promise<{
-        providers: ProviderStatus[];
+        providers: (ProviderStatus & {
+            displayName: LocalizedName | null;
+        })[];
         prices: ModelPrice[];
         currency: string;
     }>;

package/dist/admin/admin.controller.js

@@ -11,6 +11,7 @@ import { Controller, Get, HttpCode, Inject, Param, Patch, Post, Put } from "@nes
 import { z } from "zod";
 import { CatalogRequestsService } from "../catalog/requests.service.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
+import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { extensionNeedsAction } from "../extensions/permission-view.js";
 import { AccountsService } from "../identity/accounts.js";
 import { MAX_PASSWORD_LENGTH } from "../identity/login.js";
@@ -70,7 +71,8 @@ let AdminController = class AdminController {
     plugins;
     registry;
     catalogRequests;
-    constructor(accounts, sessions, log, orgs, settings, prices, purposes, plugins, registry, catalogRequests) {
+    displayNames;
+    constructor(accounts, sessions, log, orgs, settings, prices, purposes, plugins, registry, catalogRequests, displayNames) {
         this.accounts = accounts;
         this.sessions = sessions;
         this.log = log;
@@ -81,6 +83,7 @@ let AdminController = class AdminController {
         this.plugins = plugins;
         this.registry = registry;
         this.catalogRequests = catalogRequests;
+        this.displayNames = displayNames;
     }
     /** 后台概览的四个数字（只读计数，不含任何对话内容）。 */
     async overview() {
@@ -156,14 +159,19 @@ let AdminController = class AdminController {
     }
     /**
      * 模型供应商与模型（后台「模型」页）：每个供应商带状态，列模型失败的标 `error`，不影响其他供应商；
-     * 一并返回价格表与币种（改价仍走 `PUT /admin/model-prices`）。
+     * 一并返回价格表与币种（改价仍走 `PUT /admin/model-prices`）。Each provider carries its extension's
+     * display name (null when it has none).
      */
     async getModels() {
         const [providers, prices] = await Promise.all([
             this.registry.listWithStatus(),
             this.getModelPrices(),
         ]);
-        return { providers, ...prices };
+        const names = await this.displayNames.many(providers.map((p) => p.plugin));
+        return {
+            providers: providers.map((p) => ({ ...p, displayName: names.get(p.plugin) ?? null })),
+            ...prices,
+        };
     }
     /** 模型价格表（每百万 token）与币种（部署设置 `priceCurrency`）。 */
     async getModelPrices() {
@@ -250,6 +258,7 @@ AdminController = __decorate([
     __param(6, Inject(ModelPurposesService)),
     __param(7, Inject(ExtensionAdmin)),
     __param(8, Inject(ProviderRegistry)),
-    __param(9, Inject(CatalogRequestsService))
+    __param(9, Inject(CatalogRequestsService)),
+    __param(10, Inject(ExtensionDisplayNames))
 ], AdminController);
 export { AdminController };

package/dist/admin/extensions.controller.d.ts

@@ -15,6 +15,12 @@ declare const InstallSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const ConfigSchema: z.ZodObject<{
     values: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    secretEntries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        key: z.ZodString;
+        value: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        renameFrom: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
 }, z.core.$strip>;
 declare const NpmSchema: z.ZodObject<{
     package: z.ZodString;
@@ -57,7 +63,8 @@ export declare class AdminExtensionsController {
      * (a value from the startup config) does not block the PUT: it saves anyway, the extension stays
      * pending configuration and the startup config has to change. Every replica re-reads after saving:
      * hot fields are replaced in place, other fields reload the extension, and a pending extension
-     * loads (no restart).
+     * loads (no restart). `secretEntries` set, rename or remove single keys of a secret record a
+     * config UI hint draws per item (a path no hint names -> 400 `validation_failed`).
      */
     putConfig(principal: Principal, name: string, body: z.infer<typeof ConfigSchema>): Promise<DeploymentConfigView>;
     /**

package/dist/admin/extensions.controller.js

@@ -30,9 +30,28 @@ const InstallSchema = z.object({
     /** 包存储里的包（上传 / npm 导入返回的 sha256）。 */
     sha256: z.string().regex(/^[0-9a-f]{64}$/),
 });
+const SecretEntrySchema = z
+    .object({
+    /** A secret record field some `x-ui.secrets[].path` names. */
+    path: z.string().min(1).max(256),
+    key: z.string().min(1).max(256),
+    /** A string sets the key, `null` removes it. */
+    value: z.string().max(65_536).nullable().optional(),
+    /** Moves the value at this key to `key` first. */
+    renameFrom: z.string().min(1).max(256).optional(),
+})
+    .strict()
+    .refine((e) => e.value !== undefined || e.renameFrom !== undefined, {
+    message: "an entry needs value or renameFrom",
+})
+    .refine((e) => e.key !== "__proto__" && e.renameFrom !== "__proto__", {
+    message: "__proto__ is not a valid key",
+});
 const ConfigSchema = z.object({
     /** 字段点路径 → 新值（`null` 清除）。 */
     values: z.record(z.string().min(1).max(256), z.unknown()),
+    /** Single keys of hinted secret records (extension config forms spec §4.3), applied in order. */
+    secretEntries: z.array(SecretEntrySchema).max(200).optional(),
 });
 const NpmSchema = z.object({
     package: z.string().min(1).max(214),
@@ -97,11 +116,12 @@ let AdminExtensionsController = class AdminExtensionsController {
      * (a value from the startup config) does not block the PUT: it saves anyway, the extension stays
      * pending configuration and the startup config has to change. Every replica re-reads after saving:
      * hot fields are replaced in place, other fields reload the extension, and a pending extension
-     * loads (no restart).
+     * loads (no restart). `secretEntries` set, rename or remove single keys of a secret record a
+     * config UI hint draws per item (a path no hint names -> 400 `validation_failed`).
      */
     putConfig(principal, name, body) {
         const actor = requireUser(principal);
-        return this.deploymentConfigs.put(name, body.values, actor.account.id, patTokenId(actor));
+        return this.deploymentConfigs.put(name, body.values, actor.account.id, patTokenId(actor), body.secretEntries);
     }
     /**
      * Web approval: writes the snapshot (source web), audits `extension.permissions_approved` and

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,6 +13,8 @@ export interface AgentView {
     visibility: AgentVisibility;
     currentVersion: number;
     definition: AgentDefinition;
+    /** Display data outside the versions (never model-visible). */
+    profile: AgentProfile;
     memberIds: string[] | null;
     /** 负责人离职后被转给组织所有者、等待管理员重新指派。 */
     needsReassignment: boolean;

package/dist/agents/agent-lookup.js

@@ -11,7 +11,8 @@ import { Inject, Injectable, Module } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
-import { normalizeStoredDefinition } from "./definition.js";
+import { loadLegacyScope } from "../tools/legacy-data.js";
+import { needsLegacyScope, normalizeStoredDefinition } from "./definition.js";
 export const AGENT_VISIBILITIES = ["private", "org", "members"];
 const notFound = () => new ApiError("agent.not_found", "Agent not found");
 /**
@@ -131,6 +132,10 @@ 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",
             "agent_versions.definition",
         ])
             .where("agents.id", "in", ids)
@@ -142,6 +147,13 @@ let AgentLookup = class AgentLookup {
             .orderBy("account_id")
             .execute();
         const byId = new Map(rows.map((r) => [r.id, r]));
+        // rc `<x>__<tool>` keys read with their org's scope, loaded once per org that needs it
+        const scopes = new Map();
+        for (const r of rows) {
+            if (!scopes.has(r.org_id) && needsLegacyScope(r.definition)) {
+                scopes.set(r.org_id, await loadLegacyScope(this.db.db, r.org_id));
+            }
+        }
         return ids.flatMap((id) => {
             const r = byId.get(id);
             if (!r)
@@ -153,7 +165,13 @@ let AgentLookup = class AgentLookup {
                     ownerAccountId: r.owner_account_id,
                     visibility: r.visibility,
                     currentVersion: r.current_version,
-                    definition: normalizeStoredDefinition(r.definition),
+                    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,

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,11 @@
+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 { type AgentProfile } from "./profile.js";
 declare const OwnerBody: z.ZodObject<{
     accountId: z.ZodString;
 }, z.core.$strict>;
@@ -9,7 +13,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 +75,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 +95,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 +234,7 @@ declare const UpdateBody: z.ZodObject<{
             }, z.core.$strict>>>;
             dispatchable: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
+        instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     visibility: z.ZodOptional<z.ZodEnum<{
         members: "members";
@@ -178,7 +250,9 @@ declare const UpdateBody: z.ZodObject<{
  */
 export declare class AgentsController {
     private readonly agents;
-    constructor(agents: AgentsService);
+    private readonly profiles;
+    private readonly attachments;
+    constructor(agents: AgentsService, profiles: AgentProfileService, attachments: AttachmentsService);
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];
@@ -193,6 +267,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<{