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

package/dist/agents/agents.controller.js

@@ -7,30 +7,59 @@ 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 { 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 { 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 { AgentProfileService } from "./agent-profile.service.js";
 import { AGENT_VISIBILITIES, AgentsService, } from "./agents.service.js";
 import { AgentDefinitionSchema, AgentToolRef, DEFAULT_AGENT_TOOLS } from "./definition.js";
+import { ProfileInputSchema } from "./profile.js";
 const MemberIds = z.array(z.string().min(1).max(100)).max(1000);
 const OwnerBody = z.object({ accountId: z.string().min(1).max(100) }).strict();
 /** 创建时未给 `tools` → 默认工具（Ruling P7）；修改请求不注入默认值，版本里总是存显式的 tools。 */
+/**
+ * `instructions` has no default in a request: with `instructionFiles` the kernel derives it, and a
+ * new agent given neither gets the `AGENTS.md` starter (`deriveInstructions`).
+ */
+const RequestInstructions = z.string().max(100_000).optional();
 const CreateDefinition = AgentDefinitionSchema.extend({
+    instructions: RequestInstructions,
     tools: z.array(AgentToolRef).default(() => structuredClone(DEFAULT_AGENT_TOOLS)),
 });
+const UpdateDefinition = AgentDefinitionSchema.extend({ instructions: RequestInstructions });
 const CreateBody = z
     .object({
     definition: CreateDefinition,
     visibility: z.enum(AGENT_VISIBILITIES),
     memberIds: MemberIds.optional(),
+    /** Without an avatar the agent gets a random preset. */
+    profile: ProfileInputSchema.optional(),
+})
+    .strict();
+const ProfileBody = ProfileInputSchema.extend({
+    /** The `profile.updatedAt` the client read; a different one → 409 `agent.profile_conflict`. */
+    expectedUpdatedAt: z.string().min(1).max(40),
+}).strict();
+const AvatarUploadBody = z
+    .object({
+    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();
 const UpdateBody = z
     .object({
-    definition: AgentDefinitionSchema.optional(),
+    definition: UpdateDefinition.optional(),
     visibility: z.enum(AGENT_VISIBILITIES).optional(),
     memberIds: MemberIds.optional(),
     /**
@@ -46,6 +75,10 @@ class AgentCreateBodyDto extends createZodDto(CreateBody, "AgentCreateBody") {
 }
 class AgentUpdateBodyDto extends createZodDto(UpdateBody, "AgentUpdateBody") {
 }
+class AgentProfileBodyDto extends createZodDto(ProfileBody, "AgentProfileBody") {
+}
+class AgentAvatarUploadBodyDto extends createZodDto(AvatarUploadBody, "AgentAvatarUploadBody") {
+}
 class AgentOwnerBodyDto extends createZodDto(OwnerBody, "AgentOwnerBody") {
 }
 /**
@@ -54,8 +87,12 @@ class AgentOwnerBodyDto extends createZodDto(OwnerBody, "AgentOwnerBody") {
  */
 let AgentsController = class AgentsController {
     agents;
-    constructor(agents) {
+    profiles;
+    attachments;
+    constructor(agents, profiles, attachments) {
         this.agents = agents;
+        this.profiles = profiles;
+        this.attachments = attachments;
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
@@ -63,6 +100,7 @@ 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) {
@@ -75,6 +113,52 @@ let AgentsController = class AgentsController {
         const p = requireUser(principal);
         return this.agents.update(org.orgId, agentId, p.account.id, body, patTokenId(p));
     }
+    /** 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);
         await this.agents.softDelete(org.orgId, agentId, p.account.id, patTokenId(p));
@@ -119,6 +203,30 @@ __decorate([
     __param(2, Param("agentId")),
     __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),
@@ -145,6 +253,8 @@ __decorate([
 ], AgentsController.prototype, "versions", null);
 AgentsController = __decorate([
     Controller("api/v1/orgs/:orgId/agents"),
-    __param(0, Inject(AgentsService))
+    __param(0, Inject(AgentsService)),
+    __param(1, Inject(AgentProfileService)),
+    __param(2, Inject(AttachmentsService))
 ], AgentsController);
 export { AgentsController };

package/dist/agents/agents.module.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EvalBudgetModule } from "../evals/budget.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { ProvidersModule } from "../runtime/providers.js";
@@ -12,6 +13,7 @@ import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { AgentLookupModule } from "./agent-lookup.js";
+import { AgentProfileService } from "./agent-profile.service.js";
 import { AgentsService } from "./agents.service.js";
 import { AgentTemplatesService } from "./templates.js";
 /**
@@ -25,6 +27,8 @@ AgentsModule = __decorate([
     Module({
         imports: [
             AgentLookupModule,
+            // avatar uploads
+            AttachmentsModule,
             OrgLockModule,
             ProvidersModule,
             SkillsModule,
@@ -34,8 +38,8 @@ AgentsModule = __decorate([
             // cancels the deleted agent's eval runs
             EvalBudgetModule,
         ],
-        providers: [AgentsService, AgentTemplatesService],
-        exports: [AgentLookupModule, AgentsService, AgentTemplatesService],
+        providers: [AgentsService, AgentProfileService, AgentTemplatesService],
+        exports: [AgentLookupModule, AgentsService, AgentProfileService, AgentTemplatesService],
     })
 ], AgentsModule);
 export { AgentsModule };

package/dist/agents/agents.service.d.ts

@@ -10,6 +10,8 @@ import { SkillChangesService } from "../skills/changes.service.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { AgentLookup, type AgentView, type AgentVisibility } from "./agent-lookup.js";
 import { type AgentDefinition } from "./definition.js";
+import { type AgentDefinitionInput } from "./instruction-files.js";
+import { type ProfileInput } from "./profile.js";
 export { AGENT_VISIBILITIES, type AgentView, type AgentVisibility, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
 export { paramIssues, SUBAGENT_ROSTER_MAX } from "./definition.js";
 export interface AgentVersion {
@@ -21,6 +23,8 @@ export interface AgentVersion {
 export type AgentVersionSummary = Omit<AgentVersion, "definition">;
 /** 创建 / 修改的提示（不拒绝）：`fallback_same_provider` = 兜底与主模型同一供应商（spec 4.5）。 */
 export type AgentWarning = "fallback_same_provider";
+/** A new agent has no id to bind an upload to yet: a client can only choose a preset on create. */
+export declare function assertProfileWritable(profile: ProfileInput | undefined): void;
 /** Why a `subagents` block is refused (`agent.subagents_invalid` details). */
 export type SubagentsProblem = "not_found" | "invalid_name" | "duplicate" | "tool_not_selected" | "skill_not_selected" | "agent_not_available" | "self" | "too_many";
 /**
@@ -104,10 +108,11 @@ export declare class AgentsService {
      * 新建 agent（版本 1）：在组织行锁内授权 `agents.create`；主模型与兜底都必须可解析
      * （`agent.model_unavailable`）；兜底与主模型同一供应商只提示 `fallback_same_provider`。
      */
-    create(orgId: string, actorAccountId: string, input: {
-        definition: AgentDefinition;
+    create(orgId: string, actorAccountId: string, request: {
+        definition: AgentDefinitionInput;
         visibility: AgentVisibility;
         memberIds?: string[];
+        profile?: ProfileInput;
     }, actorTokenId?: string): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];
@@ -117,13 +122,16 @@ export declare class AgentsService {
      * 锁组织行并复核发起人，再锁 agent 行：发起人须仍具备 `agents.create`（member 以上），且是负责人或组织管理员以上；
      * 对发起人不可见的 agent（非管理员）→ `agent.not_found`，可见但无权 → `forbidden`。
      */
-    private lockForWrite;
+    lockForWrite(orgId: string, agentId: string, actorAccountId: string): Promise<{
+        visibility: AgentVisibility;
+        current_version: number;
+    }>;
     /**
      * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
      * 只有负责人或组织管理员以上可改，在组织行锁内复核。
      */
-    update(orgId: string, agentId: string, actorAccountId: string, patch: {
-        definition?: AgentDefinition | undefined;
+    update(orgId: string, agentId: string, actorAccountId: string, request: {
+        definition?: AgentDefinitionInput | undefined;
         visibility?: AgentVisibility | undefined;
         memberIds?: string[] | undefined;
         /**

package/dist/agents/agents.service.js

@@ -28,10 +28,18 @@ import { legacyKeySaveText } from "../tools/legacy-keys.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { AgentLookup, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
 import { normalizeStoredDefinition, paramIssues, SUBAGENT_NAME_RE, SUBAGENT_ROSTER_MAX, } from "./definition.js";
+import { deriveInstructions } from "./instruction-files.js";
+import { randomPreset } from "./profile.js";
 export { AGENT_VISIBILITIES, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
 export { paramIssues, SUBAGENT_ROSTER_MAX } from "./definition.js";
 /** 删除 agent 时每个销毁任务带的对话数。 */
 const SANDBOX_DESTROY_BATCH = 500;
+/** A new agent has no id to bind an upload to yet: a client can only choose a preset on create. */
+export function assertProfileWritable(profile) {
+    if (profile?.avatar?.kind === "upload") {
+        throw new ApiError("validation_failed", "Choose a preset avatar when creating an agent; upload one afterwards", [{ path: "avatar.kind", message: "upload is not supported on create" }]);
+    }
+}
 const notFound = () => new ApiError("agent.not_found", "Agent not found");
 /** 键排序后的 JSON：jsonb 不保留键顺序，比较定义是否变化时用。 */
 function canonical(v) {
@@ -292,13 +300,15 @@ let AgentsService = class AgentsService {
      * 新建 agent（版本 1）：在组织行锁内授权 `agents.create`；主模型与兜底都必须可解析
      * （`agent.model_unavailable`）；兜底与主模型同一供应商只提示 `fallback_same_provider`。
      */
-    async create(orgId, actorAccountId, input, actorTokenId) {
+    async create(orgId, actorAccountId, request, actorTokenId) {
+        const input = { ...request, definition: deriveInstructions(request.definition, null) };
         // 先解析模型（可能访问供应商），不在持有组织行锁时做
         const warnings = await this.checkModels(input.definition);
         const toolKeys = await this.checkTools(orgId, input.definition);
         if (input.visibility !== "members" && (input.memberIds?.length ?? 0) > 0) {
             throw new ApiError("validation_failed", "memberIds requires visibility 'members'");
         }
+        assertProfileWritable(input.profile);
         const agent = await this.createIn(orgId, actorAccountId, input, toolKeys, actorTokenId);
         return { agent, warnings };
     }
@@ -326,6 +336,9 @@ let AgentsService = class AgentsService {
             owner_account_id: actorAccountId,
             visibility: input.visibility,
             current_version: 1,
+            profile_avatar: JSON.stringify(input.profile?.avatar ?? { kind: "preset", id: randomPreset() }),
+            profile_description: input.profile?.description ?? "",
+            profile_quick_actions: JSON.stringify(input.profile?.quickActions ?? []),
         })
             .execute();
         await t
@@ -383,7 +396,8 @@ let AgentsService = class AgentsService {
      * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
      * 只有负责人或组织管理员以上可改，在组织行锁内复核。
      */
-    async update(orgId, agentId, actorAccountId, patch, actorTokenId) {
+    async update(orgId, agentId, actorAccountId, request, actorTokenId) {
+        const patch = request;
         const warnings = patch.definition ? await this.checkModels(patch.definition) : [];
         const toolKeys = patch.definition ? await this.checkTools(orgId, patch.definition) : null;
         const agent = await this.updateIn(orgId, agentId, actorAccountId, patch, toolKeys, actorTokenId);
@@ -407,26 +421,28 @@ let AgentsService = class AgentsService {
                 .where("agent_id", "=", agentId)
                 .where("version", "=", before.current_version)
                 .executeTakeFirstOrThrow();
+            // the prompt: instructionFiles give instructions; a save given neither keeps the current one
+            const definition = deriveInstructions(patch.definition, normalizeStoredDefinition(current.definition));
             // 当前版本已有的技能引用保存时合法，不再核对（被删的技能不挡住其他改动）；新加的照常核对
             const kept = new Set(current.definition.skills?.orgSkills ?? []);
-            await assertOrgSkills(t, orgId, patch.definition.skills?.orgSkills ?? [], kept);
-            await assertPinnedSkills(t, orgId, agentId, patch.definition.skills, current.definition.skills?.pinned ?? []);
+            await assertOrgSkills(t, orgId, definition.skills?.orgSkills ?? [], kept);
+            await assertPinnedSkills(t, orgId, agentId, definition.skills, current.definition.skills?.pinned ?? []);
             await assertSubagents(t, {
                 orgId,
                 agentId,
                 actorAccountId,
-                definition: patch.definition,
+                definition,
                 toolKeys: toolKeys ?? new Set(),
                 kept: current.definition.subagents,
             });
-            if (canonical(current.definition) !== canonical(patch.definition)) {
+            if (canonical(current.definition) !== canonical(definition)) {
                 toVersion = before.current_version + 1;
                 await t
                     .insertInto("agent_versions")
                     .values({
                     agent_id: agentId,
                     version: toVersion,
-                    definition: JSON.stringify(patch.definition),
+                    definition: JSON.stringify(definition),
                     created_by: actorAccountId,
                 })
                     .execute();
@@ -473,6 +489,13 @@ let AgentsService = class AgentsService {
             .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
             .where("id", "=", agentId)
             .execute();
+        // the avatar upload is garbage now: the cleanup job deletes it (and its object) once expired
+        await t
+            .updateTable("attachments")
+            .set({ expires_at: sql `now()` })
+            .where("agent_id", "=", agentId)
+            .where("purpose", "=", "agent-avatar")
+            .execute();
         await audit(t, {
             actorAccountId,
             ...(actorTokenId !== undefined && { actorTokenId }),

package/dist/agents/definition.d.ts

@@ -117,6 +117,10 @@ export declare const AgentDefinitionSchema: 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;

package/dist/agents/definition.js

@@ -1,6 +1,7 @@
 import { validateParams } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 import { isLegacyBuiltinKey, isLegacyPrefixedKey, legacyToolKey, } from "../tools/legacy-keys.js";
+import { InstructionFilesSchema } from "./instruction-files.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
 export const ModelRef = z.object({ provider: z.string(), model: z.string() });
 /**
@@ -94,7 +95,16 @@ export const SubagentsSchema = z
 export const AgentDefinitionSchema = z.object({
     name: z.string().min(1).max(80),
     avatarUrl: z.url().nullable().default(null),
+    /**
+     * The model-visible system prompt. Derived on save from `instructionFiles` when they are given
+     * (`deriveInstructions`); every reader (build.ts, the sub-agent copy, evals, replay) reads this.
+     */
     instructions: z.string().max(100_000).default(""),
+    /**
+     * The prompt files, the authoring form of `instructions` (spec 2026-11-04 §3.3). No default:
+     * definitions without it (every older version) read as one `AGENTS.md` and gain no version.
+     */
+    instructionFiles: InstructionFilesSchema.optional(),
     model: ModelRef,
     fallback: ModelRef.nullable().default(null),
     /** 主模型的参数（按主模型的声明校验）。 */

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

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

package/dist/agents/instruction-files.js

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

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

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

package/dist/agents/models.controller.js

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