@capybara-hq/kernel 0.1.0-rc.2 → 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

@@ -24,13 +24,22 @@ import { ProviderRegistry } from "../runtime/providers.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
 import { SkillChangesService } from "../skills/changes.service.js";
 import { assertOrgSkills, assertPinnedSkills } from "../skills/skills.service.js";
+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) {
@@ -67,8 +76,13 @@ export async function assertSubagents(t, a) {
     if (sub === undefined)
         return;
     const details = [];
-    const add = (reason, path, value) => {
-        details.push({ reason, path, ...(value !== undefined && { value }) });
+    const add = (reason, path, value, message) => {
+        details.push({
+            reason,
+            path,
+            ...(value !== undefined && { value }),
+            ...(message !== undefined && { message }),
+        });
     };
     const types = new Set(sub.general === false ? [] : ["general-purpose"]);
     const claim = (type, path) => {
@@ -123,8 +137,11 @@ export async function assertSubagents(t, a) {
         const base = `subagents.inline.${i}`;
         name(x.name, `${base}.name`);
         const tool = (key, path) => {
-            if (!a.toolKeys.has(key))
-                add("tool_not_selected", path, key);
+            if (a.toolKeys.has(key))
+                return;
+            // an rc key names its current key(s) (tool naming spec §8.3)
+            const renamed = legacyKeySaveText(key, a.toolKeys);
+            add("tool_not_selected", path, key, renamed ?? undefined);
         };
         for (const [j, key] of (x.tools ?? []).entries())
             tool(key, `${base}.tools.${j}`);
@@ -167,7 +184,9 @@ export async function assertSubagents(t, a) {
     if (count > SUBAGENT_ROSTER_MAX)
         add("too_many", "subagents");
     if (details.length > 0) {
-        throw new ApiError("agent.subagents_invalid", `Invalid sub-agents: ${details.map((d) => `${d.path} (${d.reason})`).join(", ")}`, details);
+        throw new ApiError("agent.subagents_invalid", `Invalid sub-agents: ${details
+            .map((d) => `${d.path} (${d.reason}${d.message === undefined ? "" : `: ${d.message}`})`)
+            .join(", ")}`, details);
     }
 }
 /**
@@ -220,9 +239,11 @@ let AgentsService = class AgentsService {
         const details = [...issues];
         for (const key of Object.keys(def.toolPolicies)) {
             if (!keys.has(key)) {
+                // an rc key (tool naming spec §8.3): saving writes current keys only, so name them
+                const renamed = legacyKeySaveText(key, keys);
                 details.push({
                     path: `toolPolicies.${key}`,
-                    message: `"${key}" is not a tool of this agent`,
+                    message: renamed ?? `"${key}" is not a tool of this agent`,
                 });
             }
         }
@@ -279,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 };
     }
@@ -313,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
@@ -370,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);
@@ -394,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();
@@ -460,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

@@ -1,5 +1,6 @@
 import { type ModelParameter } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { type LegacyScope } from "../tools/legacy-keys.js";
 /** 模型引用：供应商插件名 + 模型 id。 */
 export declare const ModelRef: z.ZodObject<{
     provider: z.ZodString;
@@ -34,11 +35,7 @@ export declare const AgentToolRef: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.Zo
     tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
 }, z.core.$strict>], "kind">, unknown>;
 export type AgentToolRef = z.output<typeof AgentToolRef>;
-/**
- * 新建 agent 未给 `tools` 时的默认工具（`tool_search` 由注册表按组织设置自动加入，不进定义）。
- * 只用于创建请求；修改与读出旧版本都不注入默认值。
- */
-export declare const DEFAULT_AGENT_TOOLS: AgentToolRef[];
+export { DEFAULT_AGENT_TOOLS } from "../tools/builtin-names.js";
 /** Roster names of inline templates and allowlisted org agents (the template name rule). */
 export declare const SUBAGENT_NAME_RE: RegExp;
 /**
@@ -75,7 +72,7 @@ export declare const InlineAgentTemplate: z.ZodObject<{
 }, z.core.$strict>;
 export type InlineAgentTemplate = z.infer<typeof InlineAgentTemplate>;
 /**
- * Sub-agents this agent may dispatch with the builtin `agent` tool (phase C, spec §5.2). No
+ * Sub-agents this agent may dispatch with the builtin `Agent` tool (phase C, spec §5.2). No
  * default: definitions without it are unchanged and gain no version.
  */
 export declare const SubagentsSchema: z.ZodObject<{
@@ -120,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;
@@ -192,11 +193,37 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
+/** The connectors and extensions a definition's own tool refs name (to read an ambiguous rc key). */
+interface OwnRefs {
+    connectors: ReadonlySet<string>;
+    extensions: ReadonlySet<string>;
+}
+/**
+ * Release-candidate tool keys in a stored definition, read as current keys (tool naming spec
+ * §8.3), the way {@link normalizeToolRef} reads the app -> connector rename: builtin refs in
+ * `tools`, the keys of `toolPolicies`, and the `tools` / `disallowedTools` / `toolPolicies` of a
+ * template, the agent's inline sub-agent templates included. Works on an agent definition and on
+ * an agent template alike. Old builtin names map without `scope`; an rc `<x>__<tool>` key maps
+ * only with one (the org's connector slugs and their ids, the deployment's extension names). When
+ * `x` is both a slug and an extension name, the definition's own tool refs decide; when they
+ * cannot, a policy or a deny list keeps the restriction on both candidate keys (a deny is never
+ * lost) and an allowlist keeps the old key (inert). An unknown key stays as it is. Keys in the
+ * current format are never touched. Returns the same object when nothing changes. Saving never
+ * goes through this: a new definition with an old key is refused (`AgentsService`).
+ */
+export declare function normalizeToolKeys(definition: unknown, scope?: LegacyScope, inherited?: OwnRefs): unknown;
+/**
+ * Does a stored definition or template hold an rc `<x>__<tool>` key, which only a
+ * {@link LegacyScope} can map? (Callers load the scope only then.)
+ */
+export declare function needsLegacyScope(definition: unknown): boolean;
 /**
  * 库里读出的定义（`agent_versions.definition`，不经 zod 解析）：把改名前的 `{ kind: "app" }` 工具引用规范化为
- * connector 形（C27）。其余字段原样保留；没有旧形引用时返回原对象。
+ * connector 形（C27），and rc tool keys to current keys ({@link normalizeToolKeys}: builtins
+ * always, `<x>__<tool>` keys with `scope`). Other fields are kept; without old forms the same
+ * object is returned.
  */
-export declare function normalizeStoredDefinition(def: unknown): AgentDefinition;
+export declare function normalizeStoredDefinition(def: unknown, scope?: LegacyScope): AgentDefinition;
 /** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
 export declare function paramIssues(field: string, decl: ModelParameter[], params: Record<string, unknown>): {
     path: string;