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

package/dist/agents/agent-lookup.d.ts

@@ -18,9 +18,25 @@ export interface AgentView {
     memberIds: string[] | null;
     /** 负责人离职后被转给组织所有者、等待管理员重新指派。 */
     needsReassignment: boolean;
+    /**
+     * The template the agent was created from (ruling P4-8; set once, never versioned), null for an
+     * agent created otherwise. `name` and `version` are the snapshot taken at create.
+     */
+    createdFrom: AgentProvenance | null;
     createdAt: Date;
     updatedAt: Date;
 }
+/** {@link AgentView.createdFrom}. */
+export interface AgentProvenance {
+    templateId: string;
+    version: number;
+    name: string;
+    /**
+     * The template is still usable in the org (the agent page links it only then). Set on the
+     * agents API's responses only (`AgentsService.withTemplateLinks`), never on internal reads.
+     */
+    available?: boolean;
+}
 /**
  * 可见性判定（`canUse`）的 SQL 条件：agent 未删除、所属组织未删除，且
  * - viewer 为账号：仍是该组织成员（含访客），并且是负责人 / visibility='org' / 在 agent_members 名单中；

package/dist/agents/agent-lookup.js

@@ -136,6 +136,9 @@ let AgentLookup = class AgentLookup {
             "agents.profile_description",
             "agents.profile_quick_actions",
             "agents.profile_updated_at",
+            "agents.created_from_template_id",
+            "agents.created_from_template_version",
+            "agents.created_from_template_name",
             "agent_versions.definition",
         ])
             .where("agents.id", "in", ids)
@@ -158,6 +161,7 @@ let AgentLookup = class AgentLookup {
             const r = byId.get(id);
             if (!r)
                 return [];
+            const fromId = r.created_from_template_id;
             return [
                 {
                     id: r.id,
@@ -176,6 +180,13 @@ let AgentLookup = class AgentLookup {
                         ? memberRows.filter((m) => m.agent_id === id).map((m) => m.account_id)
                         : null,
                     needsReassignment: r.needs_reassignment,
+                    createdFrom: fromId === null
+                        ? null
+                        : {
+                            templateId: fromId,
+                            version: r.created_from_template_version ?? 1,
+                            name: r.created_from_template_name ?? "",
+                        },
                     createdAt: r.created_at,
                     updatedAt: r.updated_at,
                 },

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

@@ -5,6 +5,7 @@ import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { AgentProfileService } from "./agent-profile.service.js";
 import { AgentsService, type AgentVersionSummary, type AgentView, type AgentWarning } from "./agents.service.js";
+import { AgentsFromTemplate, type TemplatePreview } from "./from-template.service.js";
 import { type AgentProfile } from "./profile.js";
 declare const OwnerBody: z.ZodObject<{
     accountId: z.ZodString;
@@ -234,6 +235,28 @@ declare const UpdateBody: 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>>>;
         instructions: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     visibility: z.ZodOptional<z.ZodEnum<{
@@ -244,6 +267,39 @@ declare const UpdateBody: z.ZodObject<{
     memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     expectedVersion: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
+declare const FromTemplatePreviewBody: z.ZodObject<{
+    templateId: z.ZodString;
+}, z.core.$strict>;
+declare const FromTemplateBody: z.ZodObject<{
+    templateId: z.ZodString;
+    name: z.ZodString;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        members: "members";
+        org: "org";
+        private: "private";
+    }>>;
+    members: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    model: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+    }, z.core.$strict>>;
+    avatar: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"preset">;
+        id: z.ZodEnum<{
+            "black-bear": "black-bear";
+            capybara: "capybara";
+            elephant: "elephant";
+            fox: "fox";
+            owl: "owl";
+            panda: "panda";
+            penguin: "penguin";
+            rabbit: "rabbit";
+            turtle: "turtle";
+            whale: "whale";
+        }>;
+    }, z.core.$strict>>;
+    previewHash: z.ZodString;
+}, z.core.$strict>;
 /**
  * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
  * 写用 `agents.create`（member 以上、HUMAN_ONLY），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
@@ -252,7 +308,26 @@ export declare class AgentsController {
     private readonly agents;
     private readonly profiles;
     private readonly attachments;
-    constructor(agents: AgentsService, profiles: AgentProfileService, attachments: AttachmentsService);
+    private readonly fromTemplate;
+    constructor(agents: AgentsService, profiles: AgentProfileService, attachments: AttachmentsService, fromTemplate: AgentsFromTemplate);
+    /** A response's view with its provenance link (`createdFrom.available`, ruling P4-8). */
+    private linked;
+    /**
+     * What creating an agent from a template would carry over (rulings P4-3, P4-5): the items
+     * (carried / pending / unavailable, with reasons), the model the dialog preselects (P4-4), the
+     * template fields with no place in the agent, and the `previewHash` the create must send. A
+     * template not usable in the org → 404 `component.not_found`.
+     */
+    previewFromTemplate(org: OrgContext, body: z.infer<typeof FromTemplatePreviewBody>): Promise<TemplatePreview>;
+    /**
+     * Creates an agent from a template (ruling P4-3): private by default; another visibility without
+     * `agents.manage` → 403 `agent.visibility_forbidden`; a plan that no longer matches the preview →
+     * 409 `agent.template_preview_stale`. The agent records its provenance (P4-8) and carries the
+     * template's missing connectors as `pendingConnectors` (P4-6).
+     */
+    createFromTemplate(principal: Principal, org: OrgContext, body: z.infer<typeof FromTemplateBody>): Promise<{
+        agent: AgentView;
+    }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];

package/dist/agents/agents.controller.js

@@ -18,8 +18,9 @@ import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { AgentProfileService } from "./agent-profile.service.js";
 import { AGENT_VISIBILITIES, AgentsService, } from "./agents.service.js";
-import { AgentDefinitionSchema, AgentToolRef, DEFAULT_AGENT_TOOLS } from "./definition.js";
-import { ProfileInputSchema } from "./profile.js";
+import { AgentDefinitionSchema, AgentToolRef, DEFAULT_AGENT_TOOLS, ModelRef, } from "./definition.js";
+import { AgentsFromTemplate } from "./from-template.service.js";
+import { PRESET_IDS, ProfileInputSchema } from "./profile.js";
 const MemberIds = z.array(z.string().min(1).max(100)).max(1000);
 const OwnerBody = z.object({ accountId: z.string().min(1).max(100) }).strict();
 /** 创建时未给 `tools` → 默认工具（Ruling P7）；修改请求不注入默认值，版本里总是存显式的 tools。 */
@@ -28,7 +29,8 @@ const OwnerBody = z.object({ accountId: z.string().min(1).max(100) }).strict();
  * new agent given neither gets the `AGENTS.md` starter (`deriveInstructions`).
  */
 const RequestInstructions = z.string().max(100_000).optional();
-const CreateDefinition = AgentDefinitionSchema.extend({
+/** Pending connectors come only from a template (ruling P4-6): a create request's are dropped. */
+const CreateDefinition = AgentDefinitionSchema.omit({ pendingConnectors: true }).extend({
     instructions: RequestInstructions,
     tools: z.array(AgentToolRef).default(() => structuredClone(DEFAULT_AGENT_TOOLS)),
 });
@@ -69,6 +71,27 @@ const UpdateBody = z
     expectedVersion: z.number().int().positive().optional(),
 })
     .strict();
+const TemplateId = z.string().min(1).max(100);
+const FromTemplatePreviewBody = z.object({ templateId: TemplateId }).strict();
+const FromTemplateBody = z
+    .object({
+    templateId: TemplateId,
+    name: z.string().min(1).max(80),
+    /** Default `private`; anything else needs `agents.manage` (ruling P4-3). */
+    visibility: z.enum(AGENT_VISIBILITIES).optional(),
+    /** The accounts of a `members` agent. */
+    members: MemberIds.optional(),
+    /** The person's choice; absent = the template's model resolution (P4-4). */
+    model: ModelRef.strict().optional(),
+    /** A preset avatar; absent = a random one. */
+    avatar: z
+        .object({ kind: z.literal("preset"), id: z.enum(PRESET_IDS) })
+        .strict()
+        .optional(),
+    /** The preview's `previewHash`; another one → 409 `agent.template_preview_stale`. */
+    previewHash: z.string().regex(/^[0-9a-f]{64}\.[0-9a-f]{16}$/),
+})
+    .strict();
 /** 服务令牌没有账号：以 null 作为 viewer，只看到 visibility='org' 的 agent。 */
 const viewerOf = (p) => (p.kind === "user" ? p.account.id : null);
 class AgentCreateBodyDto extends createZodDto(CreateBody, "AgentCreateBody") {
@@ -81,6 +104,10 @@ class AgentAvatarUploadBodyDto extends createZodDto(AvatarUploadBody, "AgentAvat
 }
 class AgentOwnerBodyDto extends createZodDto(OwnerBody, "AgentOwnerBody") {
 }
+class AgentFromTemplatePreviewBodyDto extends createZodDto(FromTemplatePreviewBody, "AgentFromTemplatePreviewBody") {
+}
+class AgentFromTemplateBodyDto extends createZodDto(FromTemplateBody, "AgentFromTemplateBody") {
+}
 /**
  * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
  * 写用 `agents.create`（member 以上、HUMAN_ONLY），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
@@ -89,10 +116,44 @@ let AgentsController = class AgentsController {
     agents;
     profiles;
     attachments;
-    constructor(agents, profiles, attachments) {
+    fromTemplate;
+    constructor(agents, profiles, attachments, fromTemplate) {
         this.agents = agents;
         this.profiles = profiles;
         this.attachments = attachments;
+        this.fromTemplate = fromTemplate;
+    }
+    /** A response's view with its provenance link (`createdFrom.available`, ruling P4-8). */
+    async linked(orgId, view) {
+        return (await this.agents.withTemplateLinks(orgId, [view]))[0];
+    }
+    /**
+     * What creating an agent from a template would carry over (rulings P4-3, P4-5): the items
+     * (carried / pending / unavailable, with reasons), the model the dialog preselects (P4-4), the
+     * template fields with no place in the agent, and the `previewHash` the create must send. A
+     * template not usable in the org → 404 `component.not_found`.
+     */
+    async previewFromTemplate(org, body) {
+        return this.fromTemplate.preview(org.orgId, body.templateId);
+    }
+    /**
+     * Creates an agent from a template (ruling P4-3): private by default; another visibility without
+     * `agents.manage` → 403 `agent.visibility_forbidden`; a plan that no longer matches the preview →
+     * 409 `agent.template_preview_stale`. The agent records its provenance (P4-8) and carries the
+     * template's missing connectors as `pendingConnectors` (P4-6).
+     */
+    async createFromTemplate(principal, org, body) {
+        const p = requireUser(principal);
+        const { agent } = await this.fromTemplate.create(org.orgId, p.account.id, {
+            templateId: body.templateId,
+            name: body.name,
+            previewHash: body.previewHash,
+            ...(body.visibility !== undefined && { visibility: body.visibility }),
+            ...(body.members !== undefined && { members: body.members }),
+            ...(body.model !== undefined && { model: body.model }),
+            ...(body.avatar !== undefined && { avatar: body.avatar }),
+        }, patTokenId(p));
+        return { agent: await this.linked(org.orgId, agent) };
     }
     async create(principal, org, body) {
         const p = requireUser(principal);
@@ -104,14 +165,18 @@ let AgentsController = class AgentsController {
         }, patTokenId(p));
     }
     async list(principal, org) {
-        return { agents: await this.agents.listVisible(org.orgId, viewerOf(principal)) };
+        const agents = await this.agents.listVisible(org.orgId, viewerOf(principal));
+        return { agents: await this.agents.withTemplateLinks(org.orgId, agents) };
     }
     async get(principal, org, agentId) {
-        return { agent: await this.agents.get(org.orgId, agentId, viewerOf(principal)) };
+        return {
+            agent: await this.linked(org.orgId, await this.agents.get(org.orgId, agentId, viewerOf(principal))),
+        };
     }
     async update(principal, org, agentId, body) {
         const p = requireUser(principal);
-        return this.agents.update(org.orgId, agentId, p.account.id, body, patTokenId(p));
+        const r = await this.agents.update(org.orgId, agentId, p.account.id, body, patTokenId(p));
+        return { ...r, agent: await this.linked(org.orgId, r.agent) };
     }
     /** Display data only: no agent version. Same permission as `PATCH :agentId`. */
     async updateProfile(principal, org, agentId, body) {
@@ -166,15 +231,28 @@ let AgentsController = class AgentsController {
     /** 重新指派负责人（admin，如负责人离职后）；清除 `needsReassignment`。 */
     async reassign(principal, org, agentId, body) {
         const p = requireUser(principal);
-        return {
-            agent: await this.agents.reassignOwner(org.orgId, agentId, body.accountId, p.account.id, patTokenId(p)),
-        };
+        const agent = await this.agents.reassignOwner(org.orgId, agentId, body.accountId, p.account.id, patTokenId(p));
+        return { agent: await this.linked(org.orgId, agent) };
     }
     async versions(principal, org, agentId) {
         await this.agents.get(org.orgId, agentId, viewerOf(principal));
         return { versions: await this.agents.listVersions(agentId) };
     }
 };
+__decorate([
+    Post("from-template/preview"),
+    HttpCode(200),
+    OrgAction("agents.create"),
+    __param(0, CurrentOrg()),
+    __param(1, ZBody(AgentFromTemplatePreviewBodyDto))
+], AgentsController.prototype, "previewFromTemplate", null);
+__decorate([
+    Post("from-template"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(AgentFromTemplateBodyDto))
+], AgentsController.prototype, "createFromTemplate", null);
 __decorate([
     Post(),
     OrgAction("agents.create"),
@@ -255,6 +333,7 @@ AgentsController = __decorate([
     Controller("api/v1/orgs/:orgId/agents"),
     __param(0, Inject(AgentsService)),
     __param(1, Inject(AgentProfileService)),
-    __param(2, Inject(AttachmentsService))
+    __param(2, Inject(AttachmentsService)),
+    __param(3, Inject(AgentsFromTemplate))
 ], AgentsController);
 export { AgentsController };

package/dist/agents/agents.module.d.ts

@@ -1,6 +1,9 @@
 /**
  * Agents: the one {@link AgentsService} (definitions, versions, visibility; writes under the org
- * row lock) and the plugin agent templates. Reads for a viewer are {@link AgentLookupModule}'s
+ * row lock), the agent templates (the plugin ones, and the org's own: `OrgAgentTemplates`),
+ * creating agents from templates (`AgentsFromTemplate`) with its pending connector request seam
+ * (`PendingConnectorRequests`, ruling P4-7), and binding pending connectors
+ * (`PendingConnectorsService`, P4-6). Reads for a viewer are {@link AgentLookupModule}'s
  * (re-exported), which the conversations and the skill invoker use without this module.
  */
 export declare class AgentsModule {

package/dist/agents/agents.module.js

@@ -7,18 +7,26 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Module } from "@nestjs/common";
 import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EvalBudgetModule } from "../evals/budget.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { ModelsModule } from "../models/models.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
 import { ProvidersModule } from "../runtime/providers.js";
-import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
 import { AgentLookupModule } from "./agent-lookup.js";
 import { AgentProfileService } from "./agent-profile.service.js";
 import { AgentsService } from "./agents.service.js";
+import { AgentsFromTemplate } from "./from-template.service.js";
+import { OrgAgentTemplates } from "./org-templates.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+import { PendingConnectorsService } from "./pending-connectors.service.js";
 import { AgentTemplatesService } from "./templates.js";
 /**
  * Agents: the one {@link AgentsService} (definitions, versions, visibility; writes under the org
- * row lock) and the plugin agent templates. Reads for a viewer are {@link AgentLookupModule}'s
+ * row lock), the agent templates (the plugin ones, and the org's own: `OrgAgentTemplates`),
+ * creating agents from templates (`AgentsFromTemplate`) with its pending connector request seam
+ * (`PendingConnectorRequests`, ruling P4-7), and binding pending connectors
+ * (`PendingConnectorsService`, P4-6). Reads for a viewer are {@link AgentLookupModule}'s
  * (re-exported), which the conversations and the skill invoker use without this module.
  */
 let AgentsModule = class AgentsModule {
@@ -33,13 +41,31 @@ AgentsModule = __decorate([
             ProvidersModule,
             SkillsModule,
             ToolsModule,
-            // the producer of sandbox-destroy-for jobs after a delete
-            SandboxModule,
             // cancels the deleted agent's eval runs
             EvalBudgetModule,
+            // creating from a template: the extension tools and the tier purposes (rulings P4-4, P4-5)
+            ExtensionsModule,
+            ModelsModule,
+        ],
+        providers: [
+            AgentsService,
+            AgentProfileService,
+            AgentTemplatesService,
+            OrgAgentTemplates,
+            AgentsFromTemplate,
+            PendingConnectorRequests,
+            PendingConnectorsService,
+        ],
+        exports: [
+            AgentLookupModule,
+            AgentsService,
+            AgentProfileService,
+            AgentTemplatesService,
+            OrgAgentTemplates,
+            AgentsFromTemplate,
+            PendingConnectorRequests,
+            PendingConnectorsService,
         ],
-        providers: [AgentsService, AgentProfileService, AgentTemplatesService],
-        exports: [AgentLookupModule, AgentsService, AgentProfileService, AgentTemplatesService],
     })
 ], AgentsModule);
 export { AgentsModule };

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

@@ -2,15 +2,15 @@ import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { EvalBudget } from "../evals/budget.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
-import type { KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import { type OrgRole } from "../orgs/roles.js";
 import { ProviderRegistry } from "../runtime/providers.js";
-import { SandboxJobs } from "../sandbox/jobs.js";
 import { SkillChangesService } from "../skills/changes.service.js";
 import { ToolRegistry } from "../tools/registry.js";
 import { AgentLookup, type AgentView, type AgentVisibility } from "./agent-lookup.js";
-import { type AgentDefinition } from "./definition.js";
+import { type AgentDefinition, type PendingConnector } from "./definition.js";
 import { type AgentDefinitionInput } from "./instruction-files.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
 import { type ProfileInput } from "./profile.js";
 export { AGENT_VISIBILITIES, type AgentView, type AgentVisibility, isAgentVisibleTo, visibleTo, } from "./agent-lookup.js";
 export { paramIssues, SUBAGENT_ROSTER_MAX } from "./definition.js";
@@ -25,14 +25,29 @@ export type AgentVersionSummary = Omit<AgentVersion, "definition">;
 export type AgentWarning = "fallback_same_provider";
 /** A new agent has no id to bind an upload to yet: a client can only choose a preset on create. */
 export declare function assertProfileWritable(profile: ProfileInput | undefined): void;
+/**
+ * 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 declare function keepPendingConnectors(definition: AgentDefinition, given: readonly PendingConnector[] | undefined, current: readonly PendingConnector[] | undefined): AgentDefinition;
+/** Where an agent created from a template came from (ruling P4-8; set once, never versioned). */
+export interface TemplateProvenance {
+    id: string;
+    version: number;
+    name: string;
+}
 /** Why a `subagents` block is refused (`agent.subagents_invalid` details). */
 export type SubagentsProblem = "not_found" | "invalid_name" | "duplicate" | "tool_not_selected" | "skill_not_selected" | "agent_not_available" | "self" | "too_many";
 /**
  * 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,29 +82,22 @@ export declare class AgentsService {
     private readonly orgLock;
     /** Resolves the agent's models (and their parameter declarations) when it is saved. */
     private readonly providers;
-    /**
-     * The sandbox destruction after a delete (内核投递一次性维护任务 `sandbox-destroy-for`，worker
-     * 在锁内逐个销毁，幂等).
-     */
-    private readonly sandboxJobs;
-    private readonly log;
     readonly txHost: TransactionHost;
     /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
     private readonly evalBudget;
+    /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
+    private readonly setupRequests;
     constructor(db: KernelDb, lookup: AgentLookup, tools: Pick<ToolRegistry, "checkRefs">, 
     /** 删除 agent 时取消它待处理的技能改动（T15）。 */
     skillChanges: Pick<SkillChangesService, "cancelPendingForAgent" | "finishCancel">, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock: Pick<OrgLock, "lockAndAuthorize">, 
     /** Resolves the agent's models (and their parameter declarations) when it is saved. */
-    providers: Pick<ProviderRegistry, "resolve">, 
-    /**
-     * The sandbox destruction after a delete (内核投递一次性维护任务 `sandbox-destroy-for`，worker
-     * 在锁内逐个销毁，幂等).
-     */
-    sandboxJobs: Pick<SandboxJobs, "destroy">, log: Pick<KernelLogger, "warn">, txHost: TransactionHost, 
+    providers: Pick<ProviderRegistry, "resolve">, txHost: TransactionHost, 
     /** Cancels the deleted agent's running eval runs (in the delete's transaction). */
-    evalBudget: Pick<EvalBudget, "cancelRuns">);
+    evalBudget: Pick<EvalBudget, "cancelRuns">, 
+    /** Settles the agent's connector setup request when its pending connectors change (P4-7). */
+    setupRequests: Pick<PendingConnectorRequests, "settleIn" | "retargetIn">);
     /**
      * 校验工具引用与工具策略：引用的内置 / 插件 / 连接器工具必须存在（见 `ToolRegistry.checkRefs`）；
      * `toolPolicies` 的键必须是这些引用产生的工具 key（取值只能收紧，已由 schema 保证）。
@@ -113,10 +121,28 @@ export declare class AgentsService {
         visibility: AgentVisibility;
         memberIds?: string[];
         profile?: ProfileInput;
-    }, actorTokenId?: string): Promise<{
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];
     }>;
+    /**
+     * 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: string, actorAccountId: string, request: {
+        definition: AgentDefinitionInput;
+        visibility: AgentVisibility;
+        memberIds?: string[];
+        profile?: ProfileInput;
+    }, template: TemplateProvenance, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
+        agent: AgentView;
+        warnings: AgentWarning[];
+        role: OrgRole;
+    }>;
+    private createChecked;
     private createIn;
     /**
      * 锁组织行并复核发起人，再锁 agent 行：发起人须仍具备 `agents.create`（member 以上），且是负责人或组织管理员以上；
@@ -139,7 +165,7 @@ export declare class AgentsService {
          * 不产生新版本，所以检测不到别人只改了可见范围（之后的保存会按本次给出的 visibility 覆盖）。
          */
         expectedVersion?: number | undefined;
-    }, actorTokenId?: string): Promise<{
+    }, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<{
         agent: AgentView;
         warnings: AgentWarning[];
     }>;
@@ -147,14 +173,17 @@ export declare class AgentsService {
     /** 软删除：权限同 update。待处理的技能改动与该 agent 评测集在执行的评测运行一并取消，提交后删除草稿（T15）。 */
     softDelete(orgId: string, agentId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
     private softDeleteIn;
-    /** 提交后尽力而为：投递销毁这个 agent 各对话还没销毁的沙箱（失败只记日志，留给不活跃销毁扫描）。 */
-    private destroySandboxes;
     /**
      * 重新指派负责人（`agents.manage`，admin）：在组织行锁内授权；agent 不存在 / 已删除 → `agent.not_found`；
      * 新负责人不是该组织成员 → `member.not_found`；是匿名访客 → `member.anonymous_guest`。
      * 清除 `needs_reassignment`，审计 `agent.owner_changed`。
      */
     reassignOwner(orgId: string, agentId: string, newOwnerId: string, actorAccountId: string, actorTokenId?: string): Promise<AgentView>;
+    /**
+     * `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.
+     */
+    withTemplateLinks<T extends AgentView>(orgId: string, views: T[]): Promise<T[]>;
     /** 取对 viewer 可见的 agent；`viewerAccountId = null` 表示该组织的服务令牌。不可见 → `agent.not_found`。 */
     get(orgId: string, agentId: string, viewerAccountId: string | null): Promise<AgentView>;
     /** 组织内对 viewer 可见的全部 agent（按创建时间）。 */