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

package/dist/agents/agents.controller.js

@@ -7,30 +7,61 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post } from "@nestjs/common";
+import { hasControlChars, MEDIA_NAME_MAX_CHARS } from "@capybara-hq/plugin-sdk";
+import { Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, Res } from "@nestjs/common";
 import { z } from "zod";
+import { AGENT_AVATAR_CONTENT_TYPES, AGENT_AVATAR_DOWNLOAD_TTL_SECONDS, AGENT_AVATAR_MAX_BYTES, AttachmentsService, } from "../conversations/attachments.service.js";
+import { ApiError } from "../errors.js";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AgentProfileService } from "./agent-profile.service.js";
 import { AGENT_VISIBILITIES, AgentsService, } from "./agents.service.js";
-import { AgentDefinitionSchema, AgentToolRef, DEFAULT_AGENT_TOOLS } from "./definition.js";
+import { 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。 */
-const CreateDefinition = AgentDefinitionSchema.extend({
+/**
+ * `instructions` has no default in a request: with `instructionFiles` the kernel derives it, and a
+ * new agent given neither gets the `AGENTS.md` starter (`deriveInstructions`).
+ */
+const RequestInstructions = z.string().max(100_000).optional();
+/** 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)),
 });
+const UpdateDefinition = AgentDefinitionSchema.extend({ instructions: RequestInstructions });
 const CreateBody = z
     .object({
     definition: CreateDefinition,
     visibility: z.enum(AGENT_VISIBILITIES),
     memberIds: MemberIds.optional(),
+    /** Without an avatar the agent gets a random preset. */
+    profile: ProfileInputSchema.optional(),
+})
+    .strict();
+const ProfileBody = ProfileInputSchema.extend({
+    /** The `profile.updatedAt` the client read; a different one → 409 `agent.profile_conflict`. */
+    expectedUpdatedAt: z.string().min(1).max(40),
+}).strict();
+const AvatarUploadBody = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .max(MEDIA_NAME_MAX_CHARS)
+        .refine((s) => !hasControlChars(s), "name must not contain control characters"),
+    contentType: z.enum(AGENT_AVATAR_CONTENT_TYPES),
+    size: z.number().int().min(1).max(AGENT_AVATAR_MAX_BYTES),
 })
     .strict();
 const UpdateBody = z
     .object({
-    definition: AgentDefinitionSchema.optional(),
+    definition: UpdateDefinition.optional(),
     visibility: z.enum(AGENT_VISIBILITIES).optional(),
     memberIds: MemberIds.optional(),
     /**
@@ -40,22 +71,89 @@ 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") {
 }
 class AgentUpdateBodyDto extends createZodDto(UpdateBody, "AgentUpdateBody") {
 }
+class AgentProfileBodyDto extends createZodDto(ProfileBody, "AgentProfileBody") {
+}
+class AgentAvatarUploadBodyDto extends createZodDto(AvatarUploadBody, "AgentAvatarUploadBody") {
+}
 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），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
  */
 let AgentsController = class AgentsController {
     agents;
-    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);
@@ -63,17 +161,68 @@ let AgentsController = class AgentsController {
             definition: body.definition,
             visibility: body.visibility,
             ...(body.memberIds !== undefined && { memberIds: body.memberIds }),
+            ...(body.profile !== undefined && { profile: body.profile }),
         }, patTokenId(p));
     }
     async list(principal, org) {
-        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) {
+        const p = requireUser(principal);
+        const { expectedUpdatedAt, ...patch } = body;
+        return {
+            profile: await this.profiles.update(org.orgId, agentId, p.account.id, patch, expectedUpdatedAt, patTokenId(p)),
+        };
+    }
+    /**
+     * Registers an avatar image upload (presigned, like chat attachments and skill packages): the
+     * browser uploads straight to the object store, then saves `{ kind: "upload", uploadId }` with
+     * the profile PATCH, which finalizes it. 503 `storage.unavailable` without an object store.
+     */
+    async createAvatarUpload(principal, org, agentId, body) {
+        const p = requireUser(principal);
+        // the agent must exist and be visible to the caller (writing is checked when it is saved)
+        await this.agents.get(org.orgId, agentId, viewerOf(p));
+        return this.attachments.create(org.orgId, p.account.id, body, "agent-avatar");
+    }
+    /**
+     * The avatar image: 302 to a short-lived presigned URL for an upload avatar, or to the stored
+     * URL of an external avatar when it is https; 404 for presets, no avatar, or an agent the
+     * reader cannot see.
+     */
+    async avatar(principal, org, agentId, reply) {
+        const view = await this.agents.get(org.orgId, agentId, viewerOf(principal));
+        const avatar = view.profile.avatar;
+        let location = null;
+        if (avatar?.kind === "upload") {
+            location = await this.attachments.agentAvatarUrl(org.orgId, agentId, avatar.uploadId);
+        }
+        else if (avatar?.kind === "external") {
+            try {
+                if (new URL(avatar.url).protocol === "https:")
+                    location = avatar.url;
+            }
+            catch {
+                // a malformed migrated URL: no image
+            }
+        }
+        if (location === null)
+            throw new ApiError("agent.not_found", "The agent has no avatar image");
+        await reply
+            .header("cache-control", `private, max-age=${Math.floor(AGENT_AVATAR_DOWNLOAD_TTL_SECONDS / 5)}`)
+            .redirect(location, 302);
     }
     async remove(principal, org, agentId) {
         const p = requireUser(principal);
@@ -82,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"),
@@ -119,6 +281,30 @@ __decorate([
     __param(2, Param("agentId")),
     __param(3, ZBody(AgentUpdateBodyDto))
 ], AgentsController.prototype, "update", null);
+__decorate([
+    Patch(":agentId/profile"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, ZBody(AgentProfileBodyDto))
+], AgentsController.prototype, "updateProfile", null);
+__decorate([
+    Post(":agentId/avatar/uploads"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, ZBody(AgentAvatarUploadBodyDto))
+], AgentsController.prototype, "createAvatarUpload", null);
+__decorate([
+    Get(":agentId/avatar"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Res())
+], AgentsController.prototype, "avatar", null);
 __decorate([
     Delete(":agentId"),
     HttpCode(204),
@@ -145,6 +331,9 @@ __decorate([
 ], AgentsController.prototype, "versions", null);
 AgentsController = __decorate([
     Controller("api/v1/orgs/:orgId/agents"),
-    __param(0, Inject(AgentsService))
+    __param(0, Inject(AgentsService)),
+    __param(1, Inject(AgentProfileService)),
+    __param(2, Inject(AttachmentsService)),
+    __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

@@ -5,18 +5,28 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { Module } from "@nestjs/common";
+import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { EvalBudgetModule } from "../evals/budget.js";
+import { 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 {
@@ -25,17 +35,37 @@ AgentsModule = __decorate([
     Module({
         imports: [
             AgentLookupModule,
+            // avatar uploads
+            AttachmentsModule,
             OrgLockModule,
             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, AgentTemplatesService],
-        exports: [AgentLookupModule, AgentsService, AgentTemplatesService],
     })
 ], AgentsModule);
 export { AgentsModule };

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

@@ -2,14 +2,16 @@ 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";
 export interface AgentVersion {
@@ -21,14 +23,31 @@ export interface AgentVersion {
 export type AgentVersionSummary = Omit<AgentVersion, "definition">;
 /** 创建 / 修改的提示（不拒绝）：`fallback_same_provider` = 兜底与主模型同一供应商（spec 4.5）。 */
 export type AgentWarning = "fallback_same_provider";
+/** A new agent has no id to bind an upload to yet: a client can only choose a preset on create. */
+export declare function assertProfileWritable(profile: ProfileInput | undefined): void;
+/**
+ * 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
@@ -63,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 保证）。
@@ -104,26 +116,48 @@ export declare class AgentsService {
      * 新建 agent（版本 1）：在组织行锁内授权 `agents.create`；主模型与兜底都必须可解析
      * （`agent.model_unavailable`）；兜底与主模型同一供应商只提示 `fallback_same_provider`。
      */
-    create(orgId: string, actorAccountId: string, input: {
-        definition: AgentDefinition;
+    create(orgId: string, actorAccountId: string, request: {
+        definition: AgentDefinitionInput;
         visibility: AgentVisibility;
         memberIds?: string[];
-    }, actorTokenId?: string): Promise<{
+        profile?: ProfileInput;
+    }, 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 以上），且是负责人或组织管理员以上；
      * 对发起人不可见的 agent（非管理员）→ `agent.not_found`，可见但无权 → `forbidden`。
      */
-    private lockForWrite;
+    lockForWrite(orgId: string, agentId: string, actorAccountId: string): Promise<{
+        visibility: AgentVisibility;
+        current_version: number;
+    }>;
     /**
      * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
      * 只有负责人或组织管理员以上可改，在组织行锁内复核。
      */
-    update(orgId: string, agentId: string, actorAccountId: string, patch: {
-        definition?: AgentDefinition | undefined;
+    update(orgId: string, agentId: string, actorAccountId: string, request: {
+        definition?: AgentDefinitionInput | undefined;
         visibility?: AgentVisibility | undefined;
         memberIds?: string[] | undefined;
         /**
@@ -131,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[];
     }>;
@@ -139,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（按创建时间）。 */