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

package/dist/agents/agents.service.js

@@ -8,6 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
+import { parseToolKey } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
@@ -16,22 +17,48 @@ 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 { canonicalDisabledTools, normalizeStoredDefinition, paramIssues, SUBAGENT_NAME_RE, SUBAGENT_ROSTER_MAX, withoutRemovedBuiltinPolicies, } 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;
+/**
+ * The definition with its description (run context spec §3.5): `given` when the save gives one
+ * (trimmed; empty removes it), else `kept` (the current version's).
+ */
+function withDescription(definition, given, kept) {
+    const { description: _drop, ...rest } = definition;
+    const next = given !== undefined ? given.trim() : kept;
+    return next === undefined || next === "" ? rest : { ...rest, description: next };
+}
+/** 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))
@@ -44,12 +71,43 @@ 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;
+}
+/** `definition` with `disabledTools` in its canonical form (tools default-on spec §2). */
+function withCanonicalTools(definition) {
+    return { ...definition, disabledTools: canonicalDisabledTools(definition.disabledTools ?? []) };
+}
 /**
  * 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
@@ -67,8 +125,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) => {
@@ -86,24 +149,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 ?? []);
@@ -123,16 +206,21 @@ 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}`);
         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);
@@ -167,7 +255,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);
     }
 }
 /**
@@ -181,48 +271,65 @@ let AgentsService = class AgentsService {
     skillChanges;
     orgLock;
     providers;
-    sandboxJobs;
-    log;
     txHost;
     evalBudget;
+    setupRequests;
     constructor(db, lookup, tools, 
-    /** 删除 agent 时取消它待处理的技能改动（T15）。 */
+    /**
+     * Cancels the agent's pending skill requests: all of them when it is deleted, share requests
+     * when its owner changes.
+     */
     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`）；
-     * `toolPolicies` 的键必须是这些引用产生的工具 key（取值只能收紧，已由 schema 保证）。
-     * 不合法 → `validation_failed`，path 为 `tools.<i>` / `toolPolicies.<key>`。
+     * Checks the turned-off tools and the policies (tools default-on spec §2): `disabledTools` must
+     * name existing builtins, extensions and connectors (`ToolRegistry.checkDisabled`); `toolPolicies`
+     * keys must be tools the agent could have, on or off (values only tighten, by the schema); a
+     * sub-agent's key filter is never saved. Invalid → `validation_failed` at `disabledTools.<i>` /
+     * `toolPolicies.<key>` / `subagentTools`. The list is stored in canonical form.
      */
-    async checkTools(orgId, def) {
-        const { keys, issues } = await this.tools.checkRefs(orgId, def.tools);
+    async checkTools(orgId, def, kept = []) {
+        const { keys, issues } = await this.tools.checkDisabled(orgId, def.disabledTools ?? [], kept);
         const details = [...issues];
-        for (const key of Object.keys(def.toolPolicies)) {
-            if (!keys.has(key)) {
+        if (def.subagentTools !== undefined) {
+            details.push({
+                path: "subagentTools",
+                message: "subagentTools is set only on a sub-agent's definition at dispatch",
+            });
+        }
+        for (const [key, policy] of Object.entries(def.toolPolicies)) {
+            // `allow` counts only for a connector tool (decision 2026-11-09): elsewhere a policy only
+            // tightens, so an `allow` there is refused rather than kept as a no-op
+            if (policy === "allow" && parseToolKey(key)?.kind !== "connector") {
+                details.push({
+                    path: `toolPolicies.${key}`,
+                    message: `"allow" applies only to a connector's tools; "${key}" can only be tightened (ask or deny)`,
+                });
+                continue;
+            }
+            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({
                     path: `toolPolicies.${key}`,
-                    message: `"${key}" is not a tool of this agent`,
+                    message: renamed ?? `"${key}" is not a tool of this agent`,
                 });
             }
         }
@@ -232,13 +339,32 @@ let AgentsService = class AgentsService {
         return keys;
     }
     /**
-     * 校验主模型与兜底都可解析，并用各自模型的参数声明严格校验 `modelParams` / `fallbackParams`
+     * The current version's `disabledTools` (empty for an agent that is not there: the update's own
+     * checks report that): entries kept from it are not re-checked, so a connector deleted or an
+     * extension uninstalled later never blocks other edits.
+     */
+    async keptDisabled(orgId, agentId) {
+        const row = await this.db.db
+            .selectFrom("agents")
+            .innerJoin("agent_versions", (j) => j
+            .onRef("agent_versions.agent_id", "=", "agents.id")
+            .onRef("agent_versions.version", "=", "agents.current_version"))
+            .select("agent_versions.definition")
+            .where("agents.id", "=", agentId)
+            .where("agents.org_id", "=", orgId)
+            .executeTakeFirst();
+        return row === undefined ? [] : (normalizeStoredDefinition(row.definition).disabledTools ?? []);
+    }
+    /**
+     * 校验主模型与兜底都可解析：enabled `chat` models in the org (`resolve`'s default kind; a model the
+     * platform or the org disabled, or an embedding model → 400 `agent.model_unavailable`, spec B
+     * §5.3），并用各自模型的参数声明严格校验 `modelParams` / `fallbackParams`
      * （没有兜底时 `fallbackParams` 必须为空）；不合法 → `validation_failed`，details 逐键点名。返回提示。
      */
-    async checkModels(def) {
+    async checkModels(orgId, def) {
         const registry = this.providers;
-        const main = await registry.resolve(def.model);
-        const fallback = def.fallback === null ? null : await registry.resolve(def.fallback);
+        const main = await registry.resolve(orgId, def.model);
+        const fallback = def.fallback === null ? null : await registry.resolve(orgId, def.fallback);
         const details = [
             ...paramIssues("modelParams", main.info.parameters, def.modelParams),
             ...paramIssues("fallbackParams", fallback?.info.parameters ?? [], def.fallbackParams),
@@ -279,19 +405,46 @@ 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) {
+        // a policy key of a removed builtin (e.g. copied from a template) is dropped, never refused
+        const given = withoutRemovedBuiltinPolicies(request.definition);
+        const input = {
+            ...request,
+            // run context spec §3.5: version 1 carries the description (the profile's when the
+            // definition gives none)
+            definition: withCanonicalTools(withDescription(deriveInstructions(given, null), given.description ?? request.profile?.description, undefined)),
+        };
         // 先解析模型（可能访问供应商），不在持有组织行锁时做
-        const warnings = await this.checkModels(input.definition);
+        const warnings = await this.checkModels(orgId, 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, {
@@ -313,6 +466,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.definition.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
@@ -331,9 +492,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 以上），且是负责人或组织管理员以上；
@@ -342,11 +508,29 @@ let AgentsService = class AgentsService {
     async lockForWrite(orgId, agentId, actorAccountId) {
         const t = this.db.db;
         const { role } = await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.create");
+        const agent = await this.lockAgentRow(orgId, agentId);
+        if (agent.owner_account_id === actorAccountId || roleAtLeast(role, "admin"))
+            return agent;
+        const visible = await t
+            .selectFrom("agents")
+            .select("id")
+            .where("id", "=", agentId)
+            .where(visibleTo(actorAccountId))
+            .executeTakeFirst();
+        if (!visible)
+            throw notFound();
+        throw new ApiError("forbidden", "Only the agent owner or an organization admin can modify it");
+    }
+    /**
+     * Locks the live agent row of `orgId` (the caller holds the org row lock); missing or deleted →
+     * `agent.not_found`.
+     */
+    async lockAgentRow(orgId, agentId) {
         // NO KEY UPDATE: a soft delete then appends revert snapshots to conversations; FOR UPDATE would
         // block the agent foreign key check of an append already holding one of them (40P01)
-        const agent = await t
+        const agent = await this.db.db
             .selectFrom("agents")
-            .select(["owner_account_id", "visibility", "current_version"])
+            .select(["owner_account_id", "needs_reassignment", "visibility", "current_version"])
             .where("id", "=", agentId)
             .where("org_id", "=", orgId)
             .where("deleted_at", "is", null)
@@ -354,29 +538,44 @@ let AgentsService = class AgentsService {
             .executeTakeFirst();
         if (!agent)
             throw notFound();
-        if (agent.owner_account_id === actorAccountId || roleAtLeast(role, "admin"))
-            return agent;
-        const visible = await t
+        return agent;
+    }
+    /**
+     * The platform path's lock (a super admin who need not be a member of the org): finds the live
+     * agent's org, locks the org row, then the agent row. A missing or deleted agent, or one of a
+     * deleted org → `agent.not_found`. The super admin check is the caller's (`@SuperAdmin()`).
+     */
+    async lockForPlatform(agentId) {
+        const found = await this.db.db
             .selectFrom("agents")
-            .select("id")
+            .select("org_id")
             .where("id", "=", agentId)
-            .where(visibleTo(actorAccountId))
+            .where("deleted_at", "is", null)
             .executeTakeFirst();
-        if (!visible)
+        if (!found)
             throw notFound();
-        throw new ApiError("forbidden", "Only the agent owner or an organization admin can modify it");
+        const orgId = found.org_id;
+        if (!(await this.orgLock.tryLock(orgId)))
+            throw notFound();
+        return { orgId, agent: await this.lockAgentRow(orgId, agentId) };
     }
     /**
      * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
      * 只有负责人或组织管理员以上可改，在组织行锁内复核。
      */
-    async update(orgId, agentId, actorAccountId, patch, actorTokenId) {
-        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);
+    async update(orgId, agentId, actorAccountId, request, actorTokenId, auditDetail) {
+        // a policy key of a removed builtin (stored before it went) is dropped, never refused
+        const patch = request.definition === undefined
+            ? request
+            : { ...request, definition: withoutRemovedBuiltinPolicies(request.definition) };
+        const warnings = patch.definition ? await this.checkModels(orgId, patch.definition) : [];
+        const toolKeys = patch.definition
+            ? await this.checkTools(orgId, patch.definition, await this.keptDisabled(orgId, agentId))
+            : null;
+        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) {
@@ -394,26 +593,50 @@ 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 = withCanonicalTools(withDescription(keepPendingConnectors(deriveInstructions(patch.definition, currentDefinition), patch.definition.pendingConnectors, currentDefinition.pendingConnectors), patch.definition.description, currentDefinition.description));
+            // the display copy follows every description the save gives (run context spec §3.5)
+            if (patch.definition.description !== undefined) {
+                await t
+                    .updateTable("agents")
+                    .set({ profile_description: definition.description ?? "" })
+                    .where("id", "=", agentId)
+                    .execute();
+            }
             // 当前版本已有的技能引用保存时合法，不再核对（被删的技能不挡住其他改动）；新加的照常核对
             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();
@@ -442,74 +665,100 @@ let AgentsService = class AgentsService {
                 ...(visibility !== before.visibility && {
                     visibility: { from: before.visibility, to: visibility },
                 }),
+                ...auditDetail,
             },
         });
         return this.lookup.view(agentId);
     }
     /** 软删除：权限同 update。待处理的技能改动与该 agent 评测集在执行的评测运行一并取消，提交后删除草稿（T15）。 */
-    async softDelete(orgId, agentId, actorAccountId, actorTokenId) {
-        const cancelled = await this.softDeleteIn(orgId, agentId, actorAccountId, actorTokenId);
+    async softDelete(orgId, agentId, actorAccountId, actorTokenId, auditDetail) {
+        const cancelled = await this.softDeleteIn(orgId, agentId, actorAccountId, actorTokenId, auditDetail);
         await this.skillChanges.finishCancel(orgId, cancelled);
-        await this.destroySandboxes(orgId, agentId);
     }
-    async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId) {
-        const t = this.db.db;
+    async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId, auditDetail) {
         await this.lockForWrite(orgId, agentId, actorAccountId);
+        return this.softDeleteLocked(orgId, agentId, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, auditDetail);
+    }
+    /**
+     * The platform's delete (a super admin who need not be a member of the agent's org): the same
+     * effects as {@link softDelete}, under the org row lock, audited `agent.deleted` with
+     * `detail.via = "platform"`. A missing or deleted agent, or one of a deleted org →
+     * `agent.not_found`. `auditDetail` (a Platform tool write's `viaAgent`) is merged into the
+     * detail; `via` stays `"platform"`.
+     */
+    async softDeleteAsPlatform(agentId, actor, auditDetail) {
+        const { orgId, cancelled } = await this.softDeleteAsPlatformIn(agentId, actor, auditDetail);
+        await this.skillChanges.finishCancel(orgId, cancelled);
+    }
+    async softDeleteAsPlatformIn(agentId, actor, auditDetail) {
+        const { orgId } = await this.lockForPlatform(agentId);
+        const cancelled = await this.softDeleteLocked(orgId, agentId, actor, {
+            ...auditDetail,
+            via: "platform",
+        });
+        return { orgId, cancelled };
+    }
+    /** The delete itself; the caller holds the org row and agent row locks. */
+    async softDeleteLocked(orgId, agentId, actor, auditDetail) {
+        const t = this.db.db;
+        const { accountId: actorAccountId, tokenId: actorTokenId } = actor;
         await t
             .updateTable("agents")
             .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 }),
             orgId,
             action: "agent.deleted",
             target: agentId,
+            ...(auditDetail !== undefined && { detail: auditDetail }),
+        });
+        // 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`。
      * 清除 `needs_reassignment`，审计 `agent.owner_changed`。
      */
     async reassignOwner(orgId, agentId, newOwnerId, actorAccountId, actorTokenId) {
-        const t = this.db.db;
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.manage");
-        const agent = await t
-            .selectFrom("agents")
-            .select(["owner_account_id", "needs_reassignment"])
-            .where("id", "=", agentId)
-            .where("org_id", "=", orgId)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
-        if (!agent)
-            throw notFound();
+        const agent = await this.lockAgentRow(orgId, agentId);
+        return this.reassignOwnerLocked(orgId, agentId, agent, newOwnerId, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, undefined);
+    }
+    /**
+     * The platform's owner transfer (a super admin who need not be a member of the agent's org):
+     * the same checks and effects as {@link reassignOwner} (the new owner is a member of the agent's
+     * org and not its anonymous guest), audited with `detail.via = "platform"`. A missing or deleted
+     * agent, or one of a deleted org → `agent.not_found`.
+     */
+    async reassignOwnerAsPlatform(agentId, newOwnerId, actor) {
+        const { orgId, agent } = await this.lockForPlatform(agentId);
+        return this.reassignOwnerLocked(orgId, agentId, agent, newOwnerId, actor, { via: "platform" });
+    }
+    /** The owner transfer itself; the caller holds the org row and agent row locks. */
+    async reassignOwnerLocked(orgId, agentId, agent, newOwnerId, actor, auditDetail) {
+        const t = this.db.db;
         const member = await t
             .selectFrom("memberships")
             .select("role")
@@ -524,9 +773,14 @@ 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);
+        // the previous owner's asks to share the agent's skills lapse (the new owner did not ask);
+        // a share request has no draft or trial, so nothing is left to clean up after the commit
+        await this.skillChanges.cancelPendingForAgent(orgId, agentId, actor.accountId, "owner_changed", actor.tokenId, ["share"]);
         await audit(t, {
-            actorAccountId,
-            ...(actorTokenId !== undefined && { actorTokenId }),
+            actorAccountId: actor.accountId,
+            ...(actor.tokenId !== undefined && { actorTokenId: actor.tokenId }),
             orgId,
             action: "agent.owner_changed",
             target: agentId,
@@ -534,10 +788,29 @@ let AgentsService = class AgentsService {
                 from: agent.owner_account_id,
                 to: newOwnerId,
                 neededReassignment: agent.needs_reassignment,
+                ...auditDetail,
             },
         });
         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);
@@ -584,15 +857,33 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], AgentsService.prototype, "lockForWrite", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "lockAgentRow", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "lockForPlatform", null);
 __decorate([
     Transactional()
 ], AgentsService.prototype, "updateIn", null);
 __decorate([
     Transactional()
 ], AgentsService.prototype, "softDeleteIn", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "softDeleteAsPlatformIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "softDeleteLocked", null);
 __decorate([
     Transactional()
 ], AgentsService.prototype, "reassignOwner", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "reassignOwnerAsPlatform", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "reassignOwnerLocked", null);
 AgentsService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
@@ -601,9 +892,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 };