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

package/dist/agents/agents.service.js

@@ -16,23 +16,39 @@ 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 { KERNEL_LOGGER } from "../infra/tokens.js";
 import { rejectAnonymousGuest } from "../orgs/members.service.js";
 import { OrgLock } from "../orgs/org-lock.js";
-import { roleAtLeast } from "../orgs/roles.js";
+import { can, roleAtLeast } from "../orgs/roles.js";
 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 { PendingConnectorRequests } from "./pending-connector-requests.js";
+import { randomPreset } from "./profile.js";
+import { loadTemplates, templateTypeOf } from "./templates.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");
+/** A per-operation policy key of the `Platform` tool (Platform tool spec §6.2). */
+const PLATFORM_POLICY_KEY = /^Platform:[a-z][a-z-]*\.[a-z][a-z-]*$/;
+/**
+ * May `toolPolicies` hold this key: one of the agent's tool keys, or `Platform:<operation>` when
+ * `Platform` is among them (an unknown operation id is kept: a removed operation's policy is
+ * harmless).
+ */
+function isToolPolicyKey(key, toolKeys) {
+    return toolKeys.has(key) || (toolKeys.has("Platform") && PLATFORM_POLICY_KEY.test(key));
+}
 /** 键排序后的 JSON：jsonb 不保留键顺序，比较定义是否变化时用。 */
 function canonical(v) {
     if (Array.isArray(v))
@@ -45,12 +61,39 @@ function canonical(v) {
     }
     return JSON.stringify(v);
 }
+/**
+ * The pending connectors of a saved definition (ruling P4-6): absent from the request = the current
+ * version's (an editor that does not know them never drops them); given = a subset of the current
+ * ones, unchanged (only creating from a template adds them, only binding resolves them); `[]`
+ * removes them all. Another entry → 400 `validation_failed` at `pendingConnectors.<i>`.
+ */
+export function keepPendingConnectors(definition, given, current) {
+    const { pendingConnectors: _given, ...rest } = definition;
+    const next = given ?? current ?? [];
+    if (given !== undefined) {
+        const known = new Map((current ?? []).map((c) => [c.key, canonical(c)]));
+        const details = given.flatMap((c, i) => known.get(c.key) === canonical(c)
+            ? []
+            : [
+                {
+                    path: `pendingConnectors.${i}`,
+                    message: "pending connectors come only from a template; keep or remove them",
+                },
+            ]);
+        if (details.length > 0) {
+            throw new ApiError("validation_failed", "Invalid pending connectors", details);
+        }
+    }
+    return next.length > 0 ? { ...rest, pendingConnectors: [...next] } : rest;
+}
 /**
  * Checks `subagents` of an agent definition in the caller's transaction (spec §5.2); throws 400
  * `agent.subagents_invalid` with one detail per problem (`{ reason, path, value? }`):
- * - `not_found`: a template id that is not a live agent template of the org;
+ * - `not_found`: a template id that is not a usable agent template of the org (its own, a linked
+ *   copy, or a platform template on in the org);
  * - `invalid_name`: an inline name or `agents[].as` outside {@link SUBAGENT_NAME_RE}, or
- *   `general-purpose`; `duplicate`: a roster type listed twice (a template id twice included);
+ *   `general-purpose`; `duplicate`: a roster type listed twice (a template id twice included, a
+ *   bare template type equal to an inline name, a template typed `general-purpose`);
  * - `tool_not_selected`: an inline template's `tools`, `disallowedTools` or `toolPolicies` key that
  *   is not a tool key of this agent (`toolKeys`, from `ToolRegistry.checkRefs`);
  * - `skill_not_selected`: an inline skill id that is neither in `skills.orgSkills` nor a live
@@ -92,24 +135,44 @@ export async function assertSubagents(t, a) {
     const templates = sub.templates ?? [];
     const keptTemplates = new Set(a.kept?.templates ?? []);
     const ids = [...new Set(templates)];
-    // every listed template, deleted ones included (a kept one may have been uninstalled since)
-    const rows = new Map(ids.length === 0
-        ? []
-        : (await t
-            .selectFrom("agent_templates")
-            .select(["id", "name", "plugin_name", "deleted_at"])
-            .where("org_id", "=", a.orgId)
-            .where("id", "in", ids)
-            .execute()).map((r) => [r.id, r]));
+    // usable templates (the org's, linked copies, platform templates on in the org) by id
+    const usable = await loadTemplates(t, a.orgId, ids);
+    // kept ids that are no longer usable: their type from the stored row, deleted or off included
+    const gone = ids.filter((id) => !usable.has(id) && keptTemplates.has(id));
+    const goneTypes = new Map();
+    if (gone.length > 0) {
+        const [orgRows, platformRows] = await Promise.all([
+            t
+                .selectFrom("agent_templates")
+                .select(["id", "name", "plugin_name"])
+                .where("org_id", "=", a.orgId)
+                .where("id", "in", gone)
+                .execute(),
+            t
+                .selectFrom("platform_agent_templates")
+                .select(["id", "name", "plugin_name"])
+                .where("id", "in", gone)
+                .execute(),
+        ]);
+        for (const r of [...platformRows, ...orgRows]) {
+            goneTypes.set(r.id, templateTypeOf(r.plugin_name, r.name));
+        }
+    }
     templates.forEach((id, i) => {
         const path = `subagents.templates.${i}`;
-        const row = rows.get(id);
-        if (!keptTemplates.has(id) && (row === undefined || row.deleted_at !== null)) {
+        const row = usable.get(id);
+        if (!keptTemplates.has(id) && row === undefined) {
             add("not_found", path, id);
             return;
         }
-        // claimed by its roster type (`<plugin>:<name>`, roster.ts templateType), so nothing shadows it
-        claim(row === undefined ? `template:${id}` : `${row.plugin_name}:${row.name}`, path);
+        // claimed by its roster type (`<plugin>:<name>`, or a bare `<name>` without a plugin;
+        // roster.ts templateType), so nothing shadows it; `general-purpose` is reserved
+        const type = row === undefined
+            ? (goneTypes.get(id) ?? `template:${id}`)
+            : templateTypeOf(row.plugin, row.name);
+        if (type === "general-purpose" && sub.general === false)
+            add("duplicate", path, type);
+        claim(type, path);
     });
     const inline = sub.inline ?? [];
     const selected = new Set(a.definition.skills?.orgSkills ?? []);
@@ -140,8 +203,10 @@ export async function assertSubagents(t, a) {
         for (const [j, key] of (x.disallowedTools ?? []).entries()) {
             tool(key, `${base}.disallowedTools.${j}`);
         }
-        for (const key of Object.keys(x.toolPolicies ?? {}))
-            tool(key, `${base}.toolPolicies.${key}`);
+        for (const key of Object.keys(x.toolPolicies ?? {})) {
+            if (!isToolPolicyKey(key, a.toolKeys))
+                tool(key, `${base}.toolPolicies.${key}`);
+        }
         (x.skills ?? []).forEach((id, j) => {
             if (!selected.has(id) && !own.has(id))
                 add("skill_not_selected", `${base}.skills.${j}`, id);
@@ -192,34 +257,29 @@ let AgentsService = class AgentsService {
     skillChanges;
     orgLock;
     providers;
-    sandboxJobs;
-    log;
     txHost;
     evalBudget;
+    setupRequests;
     constructor(db, lookup, tools, 
     /** 删除 agent 时取消它待处理的技能改动（T15）。 */
     skillChanges, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock, 
     /** Resolves the agent's models (and their parameter declarations) when it is saved. */
-    providers, 
-    /**
-     * The sandbox destruction after a delete (内核投递一次性维护任务 `sandbox-destroy-for`，worker
-     * 在锁内逐个销毁，幂等).
-     */
-    sandboxJobs, log, txHost, 
+    providers, txHost, 
     /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
-    evalBudget) {
+    evalBudget, 
+    /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
+    setupRequests) {
         this.db = db;
         this.lookup = lookup;
         this.tools = tools;
         this.skillChanges = skillChanges;
         this.orgLock = orgLock;
         this.providers = providers;
-        this.sandboxJobs = sandboxJobs;
-        this.log = log;
         this.txHost = txHost;
         this.evalBudget = evalBudget;
+        this.setupRequests = setupRequests;
     }
     /**
      * 校验工具引用与工具策略：引用的内置 / 插件 / 连接器工具必须存在（见 `ToolRegistry.checkRefs`）；
@@ -230,7 +290,7 @@ let AgentsService = class AgentsService {
         const { keys, issues } = await this.tools.checkRefs(orgId, def.tools);
         const details = [...issues];
         for (const key of Object.keys(def.toolPolicies)) {
-            if (!keys.has(key)) {
+            if (!isToolPolicyKey(key, keys)) {
                 // an rc key (tool naming spec §8.3): saving writes current keys only, so name them
                 const renamed = legacyKeySaveText(key, keys);
                 details.push({
@@ -292,19 +352,39 @@ 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, auditDetail) {
+        const { agent, warnings } = await this.createChecked(orgId, actorAccountId, request, null, actorTokenId, auditDetail);
+        return { agent, warnings };
+    }
+    /**
+     * Creates an agent from a planned template definition (rulings P4-3, P4-8): {@link create}'s
+     * checks, plus, under the org row lock, 403 `agent.visibility_forbidden` when the visibility is
+     * not `private` and the creator lacks `agents.manage`; the provenance columns are written once.
+     * Returns the creator's role read under the lock (the caller decides on the pending connector
+     * request after the commit).
+     */
+    createFromTemplate(orgId, actorAccountId, request, template, actorTokenId, auditDetail) {
+        return this.createChecked(orgId, actorAccountId, request, template, actorTokenId, auditDetail);
+    }
+    async createChecked(orgId, actorAccountId, request, template, actorTokenId, auditDetail) {
+        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'");
         }
-        const agent = await this.createIn(orgId, actorAccountId, input, toolKeys, actorTokenId);
-        return { agent, warnings };
+        assertProfileWritable(input.profile);
+        const { agent, role } = await this.createIn(orgId, actorAccountId, input, toolKeys, template, actorTokenId, auditDetail);
+        return { agent, warnings, role };
     }
-    async createIn(orgId, actorAccountId, input, toolKeys, actorTokenId) {
+    async createIn(orgId, actorAccountId, input, toolKeys, template, actorTokenId, auditDetail) {
         const t = this.db.db;
-        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.create");
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.create");
+        // ruling P4-3: a member creates a template agent for themself; sharing it is an admin's call
+        if (template !== null && input.visibility !== "private" && !can(role, "agents.manage")) {
+            throw new ApiError("agent.visibility_forbidden", "Only an organization admin can create an agent from a template for others; create it private");
+        }
         await assertOrgSkills(t, orgId, input.definition.skills?.orgSkills ?? []);
         await assertPinnedSkills(t, orgId, null, input.definition.skills);
         await assertSubagents(t, {
@@ -326,6 +406,14 @@ 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 ?? []),
+            ...(template !== null && {
+                created_from_template_id: template.id,
+                created_from_template_version: template.version,
+                created_from_template_name: template.name,
+            }),
         })
             .execute();
         await t
@@ -344,9 +432,14 @@ let AgentsService = class AgentsService {
             orgId,
             action: "agent.created",
             target: id,
-            detail: { version: 1, visibility: input.visibility },
+            detail: {
+                version: 1,
+                visibility: input.visibility,
+                ...(template !== null && { template: { id: template.id, version: template.version } }),
+                ...auditDetail,
+            },
         });
-        return this.lookup.view(id);
+        return { agent: await this.lookup.view(id), role };
     }
     /**
      * 锁组织行并复核发起人，再锁 agent 行：发起人须仍具备 `agents.create`（member 以上），且是负责人或组织管理员以上；
@@ -383,13 +476,14 @@ 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, auditDetail) {
+        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);
+        const agent = await this.updateIn(orgId, agentId, actorAccountId, patch, toolKeys, actorTokenId, auditDetail);
         return { agent, warnings };
     }
-    async updateIn(orgId, agentId, actorAccountId, patch, toolKeys, actorTokenId) {
+    async updateIn(orgId, agentId, actorAccountId, patch, toolKeys, actorTokenId, auditDetail) {
         const t = this.db.db;
         const before = await this.lockForWrite(orgId, agentId, actorAccountId);
         if (patch.expectedVersion !== undefined && patch.expectedVersion !== before.current_version) {
@@ -407,26 +501,42 @@ 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 currentDefinition = normalizeStoredDefinition(current.definition);
+            const definition = keepPendingConnectors(deriveInstructions(patch.definition, currentDefinition), patch.definition.pendingConnectors, currentDefinition.pendingConnectors);
             // 当前版本已有的技能引用保存时合法，不再核对（被删的技能不挡住其他改动）；新加的照常核对
             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)) {
+                // removing pending connectors in the editor narrows or cancels the setup request (P4-T6-3)
+                const keys = (definition.pendingConnectors ?? []).map((c) => c.key);
+                if (canonical((currentDefinition.pendingConnectors ?? []).map((c) => c.key)) !==
+                    canonical(keys)) {
+                    await this.setupRequests.settleIn({
+                        orgId,
+                        agentId,
+                        keys,
+                        close: "cancelled",
+                        actor: actorAccountId,
+                        actorTokenId,
+                    });
+                }
                 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();
@@ -455,6 +565,7 @@ let AgentsService = class AgentsService {
                 ...(visibility !== before.visibility && {
                     visibility: { from: before.visibility, to: visibility },
                 }),
+                ...auditDetail,
             },
         });
         return this.lookup.view(agentId);
@@ -463,7 +574,6 @@ let AgentsService = class AgentsService {
     async softDelete(orgId, agentId, actorAccountId, actorTokenId) {
         const cancelled = await this.softDeleteIn(orgId, agentId, actorAccountId, actorTokenId);
         await this.skillChanges.finishCancel(orgId, cancelled);
-        await this.destroySandboxes(orgId, agentId);
     }
     async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId) {
         const t = this.db.db;
@@ -473,6 +583,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 }),
@@ -480,31 +597,20 @@ let AgentsService = class AgentsService {
             action: "agent.deleted",
             target: agentId,
         });
+        // the agent row stays (soft delete), so its setup request is closed here (P4-T6-3)
+        await this.setupRequests.settleIn({
+            orgId,
+            agentId,
+            keys: [],
+            close: "cancelled",
+            actor: actorAccountId,
+            actorTokenId,
+        });
         // 评测集的 agent 删除后其评测运行不再花钱：显式取消（审计带原因）
         await this.evalBudget.cancelRuns({ orgId, agentId }, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, "agent_deleted");
         // joins this transaction (mandatory: it relies on the agent row lock taken above)
         return this.skillChanges.cancelPendingForAgent(orgId, agentId, actorAccountId, "agent_deleted", actorTokenId);
     }
-    /** 提交后尽力而为：投递销毁这个 agent 各对话还没销毁的沙箱（失败只记日志，留给不活跃销毁扫描）。 */
-    async destroySandboxes(orgId, agentId) {
-        try {
-            const rows = await this.db
-                .selectFrom("sandboxes as s")
-                .innerJoin("conversations as c", "c.id", "s.conversation_id")
-                .select("s.conversation_id")
-                .where("c.org_id", "=", orgId)
-                .where("c.agent_id", "=", agentId)
-                .where("s.status", "<>", "destroyed")
-                .execute();
-            const ids = rows.map((r) => r.conversation_id);
-            for (let i = 0; i < ids.length; i += SANDBOX_DESTROY_BATCH) {
-                await this.sandboxJobs.destroy(ids.slice(i, i + SANDBOX_DESTROY_BATCH));
-            }
-        }
-        catch (err) {
-            this.log.warn("cannot schedule sandbox destruction for a deleted agent", { agentId, err });
-        }
-    }
     /**
      * 重新指派负责人（`agents.manage`，admin）：在组织行锁内授权；agent 不存在 / 已删除 → `agent.not_found`；
      * 新负责人不是该组织成员 → `member.not_found`；是匿名访客 → `member.anonymous_guest`。
@@ -537,6 +643,8 @@ let AgentsService = class AgentsService {
             .set({ owner_account_id: newOwnerId, needs_reassignment: false, updated_at: sql `now()` })
             .where("id", "=", agentId)
             .execute();
+        // the new owner hears about the agent's connector setup request (P4-T6-4)
+        await this.setupRequests.retargetIn([agentId], newOwnerId);
         await audit(t, {
             actorAccountId,
             ...(actorTokenId !== undefined && { actorTokenId }),
@@ -551,6 +659,24 @@ let AgentsService = class AgentsService {
         });
         return this.lookup.view(agentId);
     }
+    /**
+     * `views` with `createdFrom.available` set (ruling P4-8): whether each recorded template is
+     * still usable in the org. One template read for all of them; only the agents API calls it.
+     */
+    async withTemplateLinks(orgId, views) {
+        const ids = [
+            ...new Set(views.flatMap((v) => (v.createdFrom === null ? [] : [v.createdFrom.templateId]))),
+        ];
+        if (ids.length === 0)
+            return views;
+        const usable = await loadTemplates(this.db.db, orgId, ids);
+        return views.map((v) => v.createdFrom === null
+            ? v
+            : {
+                ...v,
+                createdFrom: { ...v.createdFrom, available: usable.has(v.createdFrom.templateId) },
+            });
+    }
     /** 取对 viewer 可见的 agent；`viewerAccountId = null` 表示该组织的服务令牌。不可见 → `agent.not_found`。 */
     get(orgId, agentId, viewerAccountId) {
         return this.lookup.get(orgId, agentId, viewerAccountId);
@@ -614,9 +740,8 @@ AgentsService = __decorate([
     __param(3, Inject(SkillChangesService)),
     __param(4, Inject(OrgLock)),
     __param(5, Inject(ProviderRegistry)),
-    __param(6, Inject(SandboxJobs)),
-    __param(7, Inject(KERNEL_LOGGER)),
-    __param(8, Inject(TransactionHost)),
-    __param(9, Inject(EvalBudget))
+    __param(6, Inject(TransactionHost)),
+    __param(7, Inject(EvalBudget)),
+    __param(8, Inject(PendingConnectorRequests))
 ], AgentsService);
 export { AgentsService };

package/dist/agents/definition.d.ts

@@ -112,11 +112,42 @@ export declare const SubagentsSchema: z.ZodObject<{
     dispatchable: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type Subagents = z.infer<typeof SubagentsSchema>;
+/** The key rule of a pending connector (`[a-z0-9-]`, URL-safe: it names the bind route). */
+export declare const PENDING_CONNECTOR_KEY_RE: RegExp;
+/** Pending connectors an agent may carry (the template's `connectors` limit). */
+export declare const PENDING_CONNECTORS_MAX = 16;
+export declare const PendingConnectorSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        template: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        needs: z.ZodObject<{
+            protocol: z.ZodEnum<{
+                mcp: "mcp";
+                openapi: "openapi";
+            }>;
+            endpoint: z.ZodString;
+            tools: z.ZodArray<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    policies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        ask: "ask";
+        deny: "deny";
+    }>>>;
+}, z.core.$strict>;
+export type PendingConnector = z.infer<typeof PendingConnectorSchema>;
 /** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
 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;
@@ -187,6 +218,28 @@ export declare const AgentDefinitionSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         dispatchable: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
+    pendingConnectors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        source: z.ZodUnion<readonly [z.ZodObject<{
+            template: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            needs: z.ZodObject<{
+                protocol: z.ZodEnum<{
+                    mcp: "mcp";
+                    openapi: "openapi";
+                }>;
+                endpoint: z.ZodString;
+                tools: z.ZodArray<z.ZodString>;
+                label: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$strict>]>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        policies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            ask: "ask";
+            deny: "deny";
+        }>>>;
+    }, z.core.$strict>>>;
 }, 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). */

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() });
 /**
@@ -90,11 +91,60 @@ export const SubagentsSchema = z
     dispatchable: z.boolean().optional(),
 })
     .strict();
+/** The key rule of a pending connector (`[a-z0-9-]`, URL-safe: it names the bind route). */
+export const PENDING_CONNECTOR_KEY_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** Pending connectors an agent may carry (the template's `connectors` limit). */
+export const PENDING_CONNECTORS_MAX = 16;
+/**
+ * A connector the template the agent was created from needs and the org has not bound yet
+ * (ruling P4-6): `source.template` is the platform connector template's id, `source.needs` a
+ * hand-configured connector described by protocol, endpoint and tools (P4-11). `tools` are the
+ * tool names to enable once bound (absent = all of a template's tools), `policies` the template's
+ * tightened policies by tool name, applied by the bind. Never model-visible: tools are built from
+ * `tools` only, and a pending connector has none. Text limits are twice the template's (which
+ * counts code points) so any parsed template fits (this schema counts UTF-16 units).
+ */
+const PendingToolName = z.string().min(1).max(256);
+export const PendingConnectorSchema = z
+    .object({
+    key: z.string().regex(PENDING_CONNECTOR_KEY_RE),
+    label: z.string().min(1).max(160),
+    source: z.union([
+        z.object({ template: z.string().min(1).max(100) }).strict(),
+        z
+            .object({
+            needs: z
+                .object({
+                protocol: z.enum(["mcp", "openapi"]),
+                endpoint: z.string().min(1).max(4096),
+                tools: z.array(PendingToolName).max(200),
+                label: z.string().min(1).max(160),
+            })
+                .strict(),
+        })
+            .strict(),
+    ]),
+    tools: z.array(PendingToolName).max(200).optional(),
+    policies: z
+        .record(PendingToolName, z.enum(["ask", "deny"]))
+        .refine((p) => Object.keys(p).length <= 200, "at most 200 policies")
+        .optional(),
+})
+    .strict();
 /** Agent 定义：每次变化写一个新版本（`capybara.agent_versions`）。 */
 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),
     /** 主模型的参数（按主模型的声明校验）。 */
@@ -132,6 +182,11 @@ export const AgentDefinitionSchema = z.object({
         .optional(),
     /** Sub-agents (phase C); offered only when the builtin `Agent` tool is in `tools`. */
     subagents: SubagentsSchema.optional(),
+    /**
+     * Connectors still to configure (ruling P4-6), written only by creating from a template. No
+     * default: definitions without it are unchanged. Model-invisible.
+     */
+    pendingConnectors: z.array(PendingConnectorSchema).max(PENDING_CONNECTORS_MAX).optional(),
 });
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /**