@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

package/dist/agents/agents.service.js

@@ -1,22 +1,62 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 import { randomUUID } from "node:crypto";
-import { validateParams } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
-import { cancelEvalRuns } from "../evals/budget.js";
+import { EvalBudget } from "../evals/budget.js";
 import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
 import { rejectAnonymousGuest } from "../orgs/members.service.js";
-import { lockOrgAndAuthorize } from "../orgs/org-lock.js";
-import { roleAtLeast } from "../orgs/roles.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { can, roleAtLeast } from "../orgs/roles.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { SkillChangesService } from "../skills/changes.service.js";
 import { assertOrgSkills, assertPinnedSkills } from "../skills/skills.service.js";
-import { normalizeStoredDefinition, SUBAGENT_NAME_RE } from "./definition.js";
-export const AGENT_VISIBILITIES = ["private", "org", "members"];
-/** 删除 agent 时每个销毁任务带的对话数。 */
-const SANDBOX_DESTROY_BATCH = 500;
+import { legacyKeySaveText } from "../tools/legacy-keys.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { AgentLookup, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
+import { canonicalDisabledTools, 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";
+/**
+ * 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");
-/** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
-export function paramIssues(field, decl, params) {
-    const r = validateParams(decl, params);
-    return r.ok ? [] : r.issues.map((i) => ({ path: `${field}.${i.key}`, message: i.message }));
+/** 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) {
@@ -31,65 +71,42 @@ function canonical(v) {
     return JSON.stringify(v);
 }
 /**
- * 可见性判定（`canUse`）的 SQL 条件：agent 未删除、所属组织未删除，且
- * - viewer 为账号：仍是该组织成员（含访客），并且是负责人 / visibility='org' / 在 agent_members 名单中；
- * - viewer 为 null（该组织的服务令牌）：只认 visibility='org'。
+ * 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 visibleTo(viewerAccountId) {
-    return (eb) => {
-        const orgLive = eb.exists(eb
-            .selectFrom("orgs")
-            .select(sql `1`.as("one"))
-            .whereRef("orgs.id", "=", "agents.org_id")
-            .where("orgs.deleted_at", "is", null));
-        if (viewerAccountId === null) {
-            return eb.and([orgLive, eb("agents.visibility", "=", "org")]);
+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 eb.and([
-            orgLive,
-            eb.exists(eb
-                .selectFrom("memberships")
-                .select(sql `1`.as("one"))
-                .whereRef("memberships.org_id", "=", "agents.org_id")
-                .where("memberships.account_id", "=", viewerAccountId)),
-            eb.or([
-                eb("agents.owner_account_id", "=", viewerAccountId),
-                eb("agents.visibility", "=", "org"),
-                eb.and([
-                    eb("agents.visibility", "=", "members"),
-                    eb.exists(eb
-                        .selectFrom("agent_members")
-                        .select(sql `1`.as("one"))
-                        .whereRef("agent_members.agent_id", "=", "agents.id")
-                        .where("agent_members.account_id", "=", viewerAccountId)),
-                ]),
-            ]),
-        ]);
-    };
+    }
+    return next.length > 0 ? { ...rest, pendingConnectors: [...next] } : rest;
 }
-/**
- * Whether the live agent `agentId` is visible to `accountId` under the normal visibility rule
- * ({@link visibleTo}: owner, `visibility = 'org'`, or listed in `agent_members`, while a member of
- * the live org). Deleted agents are never visible.
- */
-export async function isAgentVisibleTo(db, agentId, accountId) {
-    const row = await db
-        .selectFrom("agents")
-        .select("id")
-        .where("id", "=", agentId)
-        .where("deleted_at", "is", null)
-        .where(visibleTo(accountId))
-        .executeTakeFirst();
-    return row !== undefined;
+/** `definition` with `disabledTools` in its canonical form (tools default-on spec §2). */
+function withCanonicalTools(definition) {
+    return { ...definition, disabledTools: canonicalDisabledTools(definition.disabledTools ?? []) };
 }
-/** Roster entries an agent may list (spec §4.3), general-purpose included. */
-export const SUBAGENT_ROSTER_MAX = 20;
 /**
  * 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
@@ -107,8 +124,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) => {
@@ -126,24 +148,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 ?? []);
@@ -163,16 +205,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);
@@ -207,48 +254,69 @@ 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);
     }
 }
 /**
  * Agent 定义、版本与可见范围。写操作都在组织行锁内实时复核发起人角色（spec 3.6 R5）；
  * 服务只接收发起人账号 id。不可见的 agent 一律 `agent.not_found`。
  */
-export class AgentsService {
+let AgentsService = class AgentsService {
     db;
-    registry;
+    lookup;
     tools;
     skillChanges;
-    sandboxes;
-    log;
-    constructor(db, registry, tools, 
+    orgLock;
+    providers;
+    txHost;
+    evalBudget;
+    setupRequests;
+    constructor(db, lookup, tools, 
     /** 删除 agent 时取消它待处理的技能改动（T15）。 */
     skillChanges, 
-    /**
-     * 删除 agent 后销毁它各对话的沙箱（内核投递一次性维护任务 `sandbox-destroy-for`，worker 在锁内逐个销毁，
-     * 幂等）。不给时留给不活跃销毁扫描。
-     */
-    sandboxes, log) {
+    /** 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, txHost, 
+    /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
+    evalBudget, 
+    /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
+    setupRequests) {
         this.db = db;
-        this.registry = registry;
+        this.lookup = lookup;
         this.tools = tools;
         this.skillChanges = skillChanges;
-        this.sandboxes = sandboxes;
-        this.log = log;
+        this.orgLock = orgLock;
+        this.providers = providers;
+        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];
+        if (def.subagentTools !== undefined) {
+            details.push({
+                path: "subagentTools",
+                message: "subagentTools is set only on a sub-agent's definition at dispatch",
+            });
+        }
         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({
                     path: `toolPolicies.${key}`,
-                    message: `"${key}" is not a tool of this agent`,
+                    message: renamed ?? `"${key}" is not a tool of this agent`,
                 });
             }
         }
@@ -258,12 +326,32 @@ export 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) {
-        const main = await this.registry.resolve(def.model);
-        const fallback = def.fallback === null ? null : await this.registry.resolve(def.fallback);
+    async checkModels(orgId, def) {
+        const registry = this.providers;
+        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),
@@ -300,128 +388,111 @@ export class AgentsService {
                 .execute();
         }
     }
-    async view(db, agentId) {
-        const views = await this.views(db, [agentId]);
-        const v = views[0];
-        if (!v)
-            throw notFound();
-        return v;
-    }
-    /** 按给定 id 顺序组装视图（调用方已完成可见性判定）。 */
-    async views(db, ids) {
-        if (ids.length === 0)
-            return [];
-        const rows = await db
-            .selectFrom("agents")
-            .innerJoin("agent_versions", (j) => j
-            .onRef("agent_versions.agent_id", "=", "agents.id")
-            .onRef("agent_versions.version", "=", "agents.current_version"))
-            .select([
-            "agents.id",
-            "agents.org_id",
-            "agents.owner_account_id",
-            "agents.visibility",
-            "agents.current_version",
-            "agents.needs_reassignment",
-            "agents.created_at",
-            "agents.updated_at",
-            "agent_versions.definition",
-        ])
-            .where("agents.id", "in", ids)
-            .execute();
-        const memberRows = await db
-            .selectFrom("agent_members")
-            .select(["agent_id", "account_id"])
-            .where("agent_id", "in", ids)
-            .orderBy("account_id")
-            .execute();
-        const byId = new Map(rows.map((r) => [r.id, r]));
-        return ids.flatMap((id) => {
-            const r = byId.get(id);
-            if (!r)
-                return [];
-            return [
-                {
-                    id: r.id,
-                    orgId: r.org_id,
-                    ownerAccountId: r.owner_account_id,
-                    visibility: r.visibility,
-                    currentVersion: r.current_version,
-                    definition: normalizeStoredDefinition(r.definition),
-                    memberIds: r.visibility === "members"
-                        ? memberRows.filter((m) => m.agent_id === id).map((m) => m.account_id)
-                        : null,
-                    needsReassignment: r.needs_reassignment,
-                    createdAt: r.created_at,
-                    updatedAt: r.updated_at,
-                },
-            ];
-        });
-    }
     /**
      * 新建 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,
+            // run context spec §3.5: version 1 carries the description (the profile's when the
+            // definition gives none)
+            definition: withCanonicalTools(withDescription(deriveInstructions(request.definition, null), request.definition.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.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, orgId, actorAccountId, "agents.create");
-            await assertOrgSkills(t, orgId, input.definition.skills?.orgSkills ?? []);
-            await assertPinnedSkills(t, orgId, null, input.definition.skills);
-            await assertSubagents(t, {
-                orgId,
-                agentId: null,
-                actorAccountId,
-                definition: input.definition,
-                toolKeys,
-            });
-            const memberIds = input.visibility === "members"
-                ? await this.checkMembers(t, orgId, input.memberIds ?? [])
-                : [];
-            const id = randomUUID();
-            await t
-                .insertInto("agents")
-                .values({
-                id,
-                org_id: orgId,
-                owner_account_id: actorAccountId,
-                visibility: input.visibility,
-                current_version: 1,
-            })
-                .execute();
-            await t
-                .insertInto("agent_versions")
-                .values({
-                agent_id: id,
+        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, template, actorTokenId, auditDetail) {
+        const t = this.db.db;
+        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, {
+            orgId,
+            agentId: null,
+            actorAccountId,
+            definition: input.definition,
+            toolKeys,
+        });
+        const memberIds = input.visibility === "members"
+            ? await this.checkMembers(t, orgId, input.memberIds ?? [])
+            : [];
+        const id = randomUUID();
+        await t
+            .insertInto("agents")
+            .values({
+            id,
+            org_id: orgId,
+            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
+            .insertInto("agent_versions")
+            .values({
+            agent_id: id,
+            version: 1,
+            definition: JSON.stringify(input.definition),
+            created_by: actorAccountId,
+        })
+            .execute();
+        await this.setMembers(t, id, memberIds);
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "agent.created",
+            target: id,
+            detail: {
                 version: 1,
-                definition: JSON.stringify(input.definition),
-                created_by: actorAccountId,
-            })
-                .execute();
-            await this.setMembers(t, id, memberIds);
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "agent.created",
-                target: id,
-                detail: { version: 1, visibility: input.visibility },
-            });
-            return this.view(t, id);
+                visibility: input.visibility,
+                ...(template !== null && { template: { id: template.id, version: template.version } }),
+                ...auditDetail,
+            },
         });
-        return { agent, warnings };
+        return { agent: await this.lookup.view(id), role };
     }
     /**
      * 锁组织行并复核发起人，再锁 agent 行：发起人须仍具备 `agents.create`（member 以上），且是负责人或组织管理员以上；
      * 对发起人不可见的 agent（非管理员）→ `agent.not_found`，可见但无权 → `forbidden`。
      */
-    async lockForWrite(t, orgId, agentId, actorAccountId) {
-        const { role } = await lockOrgAndAuthorize(t, orgId, actorAccountId, "agents.create");
+    async lockForWrite(orgId, agentId, actorAccountId) {
+        const t = this.db.db;
+        const { role } = await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.create");
         // 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
@@ -450,124 +521,151 @@ export class AgentsService {
      * 修改 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.db.transaction().execute(async (t) => {
-            const before = await this.lockForWrite(t, orgId, agentId, actorAccountId);
-            if (patch.expectedVersion !== undefined && patch.expectedVersion !== before.current_version) {
-                throw new ApiError("agent.version_conflict", `The agent was changed by someone else (now version ${before.current_version}, expected ${patch.expectedVersion}); reload it and apply your changes again`);
-            }
-            const visibility = patch.visibility ?? before.visibility;
-            if (visibility !== "members" && (patch.memberIds?.length ?? 0) > 0) {
-                throw new ApiError("validation_failed", "memberIds requires visibility 'members'");
-            }
-            let toVersion = before.current_version;
-            if (patch.definition) {
-                const current = await t
-                    .selectFrom("agent_versions")
-                    .select("definition")
-                    .where("agent_id", "=", agentId)
-                    .where("version", "=", before.current_version)
-                    .executeTakeFirstOrThrow();
-                // 当前版本已有的技能引用保存时合法，不再核对（被删的技能不挡住其他改动）；新加的照常核对
-                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 assertSubagents(t, {
-                    orgId,
-                    agentId,
-                    actorAccountId,
-                    definition: patch.definition,
-                    toolKeys: toolKeys ?? new Set(),
-                    kept: current.definition.subagents,
-                });
-                if (canonical(current.definition) !== canonical(patch.definition)) {
-                    toVersion = before.current_version + 1;
-                    await t
-                        .insertInto("agent_versions")
-                        .values({
-                        agent_id: agentId,
-                        version: toVersion,
-                        definition: JSON.stringify(patch.definition),
-                        created_by: actorAccountId,
-                    })
-                        .execute();
-                }
-            }
-            if (visibility !== "members") {
-                await this.setMembers(t, agentId, []);
-            }
-            else if (patch.memberIds !== undefined) {
-                await this.setMembers(t, agentId, await this.checkMembers(t, orgId, patch.memberIds));
+    async update(orgId, agentId, actorAccountId, request, actorTokenId, auditDetail) {
+        const patch = request;
+        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, auditDetail) {
+        const t = this.db.db;
+        const before = await this.lockForWrite(orgId, agentId, actorAccountId);
+        if (patch.expectedVersion !== undefined && patch.expectedVersion !== before.current_version) {
+            throw new ApiError("agent.version_conflict", `The agent was changed by someone else (now version ${before.current_version}, expected ${patch.expectedVersion}); reload it and apply your changes again`);
+        }
+        const visibility = patch.visibility ?? before.visibility;
+        if (visibility !== "members" && (patch.memberIds?.length ?? 0) > 0) {
+            throw new ApiError("validation_failed", "memberIds requires visibility 'members'");
+        }
+        let toVersion = before.current_version;
+        if (patch.definition) {
+            const current = await t
+                .selectFrom("agent_versions")
+                .select("definition")
+                .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();
             }
-            await t
-                .updateTable("agents")
-                .set({ visibility, current_version: toVersion, updated_at: sql `now()` })
-                .where("id", "=", agentId)
-                .execute();
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
+            // 当前版本已有的技能引用保存时合法，不再核对（被删的技能不挡住其他改动）；新加的照常核对
+            const kept = new Set(current.definition.skills?.orgSkills ?? []);
+            await assertOrgSkills(t, orgId, definition.skills?.orgSkills ?? [], kept);
+            await assertPinnedSkills(t, orgId, agentId, definition.skills, current.definition.skills?.pinned ?? []);
+            await assertSubagents(t, {
                 orgId,
-                action: "agent.updated",
-                target: agentId,
-                detail: {
-                    fromVersion: before.current_version,
-                    toVersion,
-                    ...(visibility !== before.visibility && {
-                        visibility: { from: before.visibility, to: visibility },
-                    }),
-                },
+                agentId,
+                actorAccountId,
+                definition,
+                toolKeys: toolKeys ?? new Set(),
+                kept: current.definition.subagents,
             });
-            return this.view(t, agentId);
+            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(definition),
+                    created_by: actorAccountId,
+                })
+                    .execute();
+            }
+        }
+        if (visibility !== "members") {
+            await this.setMembers(t, agentId, []);
+        }
+        else if (patch.memberIds !== undefined) {
+            await this.setMembers(t, agentId, await this.checkMembers(t, orgId, patch.memberIds));
+        }
+        await t
+            .updateTable("agents")
+            .set({ visibility, current_version: toVersion, updated_at: sql `now()` })
+            .where("id", "=", agentId)
+            .execute();
+        await audit(t, {
+            actorAccountId,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "agent.updated",
+            target: agentId,
+            detail: {
+                fromVersion: before.current_version,
+                toVersion,
+                ...(visibility !== before.visibility && {
+                    visibility: { from: before.visibility, to: visibility },
+                }),
+                ...auditDetail,
+            },
         });
-        return { agent, warnings };
+        return this.lookup.view(agentId);
     }
     /** 软删除：权限同 update。待处理的技能改动与该 agent 评测集在执行的评测运行一并取消，提交后删除草稿（T15）。 */
-    async softDelete(orgId, agentId, actorAccountId, actorTokenId) {
-        const cancelled = await this.db.transaction().execute(async (t) => {
-            await this.lockForWrite(t, orgId, agentId, actorAccountId);
-            await t
-                .updateTable("agents")
-                .set({ deleted_at: sql `now()`, updated_at: sql `now()` })
-                .where("id", "=", agentId)
-                .execute();
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "agent.deleted",
-                target: agentId,
-            });
-            // 评测集的 agent 删除后其评测运行不再花钱：显式取消（审计带原因）
-            await cancelEvalRuns(t, { orgId, agentId }, { accountId: actorAccountId, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, "agent_deleted");
-            return this.skillChanges.cancelPendingForAgent(t, orgId, agentId, actorAccountId, "agent_deleted", 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);
     }
-    /** 提交后尽力而为：投递销毁这个 agent 各对话还没销毁的沙箱（失败只记日志，留给不活跃销毁扫描）。 */
-    async destroySandboxes(orgId, agentId) {
-        if (!this.sandboxes)
-            return;
-        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.sandboxes.destroy(ids.slice(i, i + SANDBOX_DESTROY_BATCH));
-            }
-        }
-        catch (err) {
-            this.log?.warn("cannot schedule sandbox destruction for a deleted agent", { agentId, err });
-        }
+    async softDeleteIn(orgId, agentId, actorAccountId, actorTokenId, auditDetail) {
+        const t = this.db.db;
+        await this.lockForWrite(orgId, agentId, actorAccountId);
+        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);
     }
     /**
      * 重新指派负责人（`agents.manage`，admin）：在组织行锁内授权；agent 不存在 / 已删除 → `agent.not_found`；
@@ -575,73 +673,73 @@ export class AgentsService {
      * 清除 `needs_reassignment`，审计 `agent.owner_changed`。
      */
     async reassignOwner(orgId, agentId, newOwnerId, actorAccountId, actorTokenId) {
-        return this.db.transaction().execute(async (t) => {
-            await lockOrgAndAuthorize(t, 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 member = await t
-                .selectFrom("memberships")
-                .select("role")
-                .where("org_id", "=", orgId)
-                .where("account_id", "=", newOwnerId)
-                .executeTakeFirst();
-            if (!member)
-                throw new ApiError("member.not_found", "Member not found");
-            await rejectAnonymousGuest(t, newOwnerId);
-            await t
-                .updateTable("agents")
-                .set({ owner_account_id: newOwnerId, needs_reassignment: false, updated_at: sql `now()` })
-                .where("id", "=", agentId)
-                .execute();
-            await audit(t, {
-                actorAccountId,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "agent.owner_changed",
-                target: agentId,
-                detail: {
-                    from: agent.owner_account_id,
-                    to: newOwnerId,
-                    neededReassignment: agent.needs_reassignment,
-                },
-            });
-            return this.view(t, agentId);
-        });
-    }
-    /** 取对 viewer 可见的 agent；`viewerAccountId = null` 表示该组织的服务令牌。不可见 → `agent.not_found`。 */
-    async get(orgId, agentId, viewerAccountId) {
-        const row = await this.db
+        const t = this.db.db;
+        await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "agents.manage");
+        const agent = await t
             .selectFrom("agents")
-            .select("id")
+            .select(["owner_account_id", "needs_reassignment"])
             .where("id", "=", agentId)
             .where("org_id", "=", orgId)
             .where("deleted_at", "is", null)
-            .where(visibleTo(viewerAccountId))
+            .forUpdate()
             .executeTakeFirst();
-        if (!row)
+        if (!agent)
             throw notFound();
-        return this.view(this.db, agentId);
-    }
-    /** 组织内对 viewer 可见的全部 agent（按创建时间）。 */
-    async listVisible(orgId, viewerAccountId) {
-        const rows = await this.db
-            .selectFrom("agents")
-            .select("id")
+        const member = await t
+            .selectFrom("memberships")
+            .select("role")
             .where("org_id", "=", orgId)
-            .where("deleted_at", "is", null)
-            .where(visibleTo(viewerAccountId))
-            .orderBy("created_at")
-            .orderBy("id")
+            .where("account_id", "=", newOwnerId)
+            .executeTakeFirst();
+        if (!member)
+            throw new ApiError("member.not_found", "Member not found");
+        await rejectAnonymousGuest(t, newOwnerId);
+        await t
+            .updateTable("agents")
+            .set({ owner_account_id: newOwnerId, needs_reassignment: false, updated_at: sql `now()` })
+            .where("id", "=", agentId)
             .execute();
-        return this.views(this.db, rows.map((r) => r.id));
+        // 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 }),
+            orgId,
+            action: "agent.owner_changed",
+            target: agentId,
+            detail: {
+                from: agent.owner_account_id,
+                to: newOwnerId,
+                neededReassignment: agent.needs_reassignment,
+            },
+        });
+        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);
+    }
+    /** 组织内对 viewer 可见的全部 agent（按创建时间）。 */
+    listVisible(orgId, viewerAccountId) {
+        return this.lookup.listVisible(orgId, viewerAccountId);
     }
     /** 读某个版本（不做可见性判定，调用方负责）；不存在 → `agent.not_found`。 */
     async getVersion(agentId, version) {
@@ -674,4 +772,32 @@ export class AgentsService {
             createdAt: r.created_at,
         }));
     }
-}
+};
+__decorate([
+    Transactional()
+], AgentsService.prototype, "createIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], AgentsService.prototype, "lockForWrite", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "updateIn", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "softDeleteIn", null);
+__decorate([
+    Transactional()
+], AgentsService.prototype, "reassignOwner", null);
+AgentsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(AgentLookup)),
+    __param(2, Inject(ToolRegistry)),
+    __param(3, Inject(SkillChangesService)),
+    __param(4, Inject(OrgLock)),
+    __param(5, Inject(ProviderRegistry)),
+    __param(6, Inject(TransactionHost)),
+    __param(7, Inject(EvalBudget)),
+    __param(8, Inject(PendingConnectorRequests))
+], AgentsService);
+export { AgentsService };