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

package/dist/platform/method.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The method of the `Platform` tool (spec §5.2): the rules the root `browse` result carries, after
+ * the domains. Model-visible English; a tool result, never part of the tool definition, so
+ * changing it changes no definition fingerprint.
+ */
+export declare const PLATFORM_METHOD: string;

package/dist/platform/method.js

@@ -0,0 +1,15 @@
+/**
+ * The method of the `Platform` tool (spec §5.2): the rules the root `browse` result carries, after
+ * the domains. Model-visible English; a tool result, never part of the tool definition, so
+ * changing it changes no definition fingerprint.
+ */
+export const PLATFORM_METHOD = [
+    "How to work with the platform:",
+    "1. Read before you write: list or get what you are about to change.",
+    "2. Before a write, tell the person in one sentence what you will do and why; the platform then asks them to confirm.",
+    "3. A declined confirmation means stop; do not retry the same change another way.",
+    "4. An operation you may not call is not a dead end: its reason says who can (an org admin, the super admin) and whether a request operation exists; offer that.",
+    "5. Errors say what to do next; follow them.",
+    '6. When unsure how the platform works, use action "read" for the docs before acting.',
+    'Find an operation with "browse" (a domain) or "search", then "describe" it before you "call" it; never guess parameters.',
+].join("\n");

package/dist/platform/operation.d.ts

@@ -0,0 +1,92 @@
+import type { z } from "zod";
+import type { OrgAction } from "../orgs/roles.js";
+/**
+ * How an operation is confirmed (spec §6.2): `read` runs; `personal` asks each time and may be
+ * remembered; `org` / `platform` ask each time and are never remembered.
+ */
+export type ConfirmClass = "read" | "personal" | "org" | "platform";
+/** Who may call an operation: the org action of the route it mirrors, or the super admin. */
+export type OperationAuthz = {
+    orgAction: OrgAction;
+} | {
+    superAdmin: true;
+};
+/** What an operation's handler gets besides its input: the actor and where the call happens. */
+export interface OperationContext {
+    orgId: string;
+    /** The run's trigger account (spec §6.1), the principal the handler acts as. */
+    actorAccountId: string;
+    agentId: string;
+    conversationId: string;
+    runId: string | null;
+    signal: AbortSignal;
+}
+/** One operation of the `Platform` tool (spec §7), defined next to its domain. */
+export interface PlatformOperation<I = unknown> {
+    /** `<domain>.<verb>`, matching {@link OPERATION_ID}; the domain is one of {@link PLATFORM_DOMAINS}. */
+    id: string;
+    /** English, one paragraph; the first sentence is the line `browse` and `search` show. */
+    description: string;
+    /** Every string bounded; `describe` shows its JSON Schema. */
+    input: z.ZodType<I>;
+    example: I;
+    /** The route's authorization, or the role the service enforces (spec §9). */
+    authz: OperationAuthz;
+    /**
+     * `"service-enforced"`: the service enforces a higher role than the mirrored route's decorator,
+     * so `authz` may name a stricter action (`check:platform-ops` requires its role to be at least
+     * the route's).
+     */
+    authzNote?: "service-enforced";
+    /** The HTTP routes it corresponds to, e.g. `POST /api/v1/orgs/:orgId/skills`; [] when synthetic. */
+    mirrors: readonly string[];
+    confirm: ConfirmClass;
+    /**
+     * The class of one call when it depends on the target (read at confirmation time): e.g.
+     * `agents.update` is `personal` only on a private agent the actor owns and `org` otherwise, so a
+     * remembered grant never carries over to a shared agent. Only for writes, never returns `read`;
+     * absent: `confirm`. The tool treats a throw as not remembered.
+     */
+    confirmFor?(input: I, ctx: OperationContext): Promise<ConfirmClass>;
+    /**
+     * The notable error codes of the operation and what to do next (model-visible English), shown
+     * by `describe` (spec §3).
+     */
+    errors?: readonly {
+        code: string;
+        next: string;
+    }[];
+    /**
+     * The bilingual card summary of a write, rendered from the input and kernel reads (names of
+     * the targets, preview counts), never from model text; required unless `confirm` is `read`.
+     * May read PG; the tool falls back to the operation id when it throws. Method syntax so an
+     * operation of any input type is a `PlatformOperation` (the registry's element type).
+     */
+    summary?(input: I, ctx: OperationContext): {
+        zh: string;
+        en: string;
+    } | Promise<{
+        zh: string;
+        en: string;
+    }>;
+    run(input: I, ctx: OperationContext): Promise<unknown>;
+}
+/** Identity helper that types an operation's handler and summary from its input schema. */
+export declare function defineOperation<I>(op: PlatformOperation<I>): PlatformOperation<I>;
+/** The shape of an operation id: `<domain>.<verb>`, lower case words joined by `-`. */
+export declare const OPERATION_ID: RegExp;
+/** The domain part of an operation id (`skills` of `skills.list`). */
+export declare const operationDomain: (id: string) => string;
+/** The phase 1 domains (spec §7), in the order `browse` lists them; model-visible English. */
+export declare const PLATFORM_DOMAINS: readonly {
+    id: string;
+    description: string;
+}[];
+/**
+ * Something that contributes operations (a domain's provider). Kept as a type only: providers
+ * call `PlatformOperations.register` from their `onModuleInit` (ruling P2), so `PlatformModule`
+ * imports no domain module.
+ */
+export interface OperationProvider {
+    operations(): readonly PlatformOperation[];
+}

package/dist/platform/operation.js

@@ -0,0 +1,35 @@
+/** Identity helper that types an operation's handler and summary from its input schema. */
+export function defineOperation(op) {
+    return op;
+}
+/** The shape of an operation id: `<domain>.<verb>`, lower case words joined by `-`. */
+export const OPERATION_ID = /^[a-z][a-z-]*\.[a-z][a-z-]*$/;
+/** The domain part of an operation id (`skills` of `skills.list`). */
+export const operationDomain = (id) => id.slice(0, id.indexOf("."));
+/** The phase 1 domains (spec §7), in the order `browse` lists them; model-visible English. */
+export const PLATFORM_DOMAINS = [
+    {
+        id: "platform",
+        description: "What this platform is, its tool families, and what you and this agent can do.",
+    },
+    { id: "skills", description: "The org's skill library: list, read, create, switch on or off." },
+    {
+        id: "agents",
+        description: "Agents in the org: list, read, create private ones, update those you may edit.",
+    },
+    {
+        id: "agent-templates",
+        description: "Agent templates: list, read, save an agent as a template.",
+    },
+    {
+        id: "plugins",
+        description: "Plugins in the org and on the platform: list, read, enable, disable, update.",
+    },
+    {
+        id: "marketplaces",
+        description: "Marketplace sources and their entries: list, browse, add, request a plugin.",
+    },
+    { id: "requests", description: "Requests to admins: list yours, create one." },
+    { id: "connectors", description: "Connectors and connector templates: list and read." },
+    { id: "extensions", description: "Extensions in the org (state only) and extension points." },
+];

package/dist/platform/ops/agent-templates.ops.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { AgentsService } from "../../agents/agents.service.js";
+import { OrgAgentTemplates } from "../../agents/org-templates.js";
+import { AgentTemplatesService } from "../../agents/templates.js";
+import { PlatformOperations } from "../registry.js";
+/** Agent template operations of the `Platform` tool (spec §7). */
+export declare class AgentTemplatesOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly templates;
+    private readonly orgTemplates;
+    private readonly agents;
+    constructor(registry: PlatformOperations, templates: AgentTemplatesService, orgTemplates: OrgAgentTemplates, agents: AgentsService);
+    onModuleInit(): void;
+}

package/dist/platform/ops/agent-templates.ops.js

@@ -0,0 +1,92 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { AgentsService } from "../../agents/agents.service.js";
+import { OrgAgentTemplates } from "../../agents/org-templates.js";
+import { AgentTemplatesService } from "../../agents/templates.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { asToolError, viaAgent } from "./errors.js";
+import { named, orElse } from "./summary.js";
+/** Agent template operations of the `Platform` tool (spec §7). */
+let AgentTemplatesOperations = class AgentTemplatesOperations {
+    registry;
+    templates;
+    orgTemplates;
+    agents;
+    constructor(registry, templates, orgTemplates, agents) {
+        this.registry = registry;
+        this.templates = templates;
+        this.orgTemplates = orgTemplates;
+        this.agents = agents;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "agent-templates.list",
+                description: "List the agent templates usable in the org, the org's own and platform templates switched on in it. Each entry has an id, name, description and version; create an agent from one with agents.create-from-template.",
+                input: z.object({}).strict(),
+                example: {},
+                authz: { orgAction: "agents.create" },
+                mirrors: ["GET /api/v1/orgs/:orgId/agent-templates"],
+                confirm: "read",
+                run: async (_input, ctx) => ({ templates: await this.templates.listForOrg(ctx.orgId) }),
+            }),
+            defineOperation({
+                id: "agent-templates.get",
+                description: "Read one agent template with its definition (model tier, tools, skills, connectors it needs). Takes the template id from agent-templates.list.",
+                input: z.object({ templateId: z.string().min(1).max(100) }).strict(),
+                example: { templateId: "5d0c7a52-3a0e-4f0a-bd0a-0f8c3d2a9e10" },
+                authz: { orgAction: "agents.create" },
+                mirrors: ["GET /api/v1/orgs/:orgId/agent-templates/:id"],
+                confirm: "read",
+                run: async (input, ctx) => asToolError(async () => ({
+                    template: await this.orgTemplates.detail(ctx.orgId, input.templateId),
+                })),
+            }),
+            defineOperation({
+                id: "agent-templates.save",
+                description: "Save an agent of the org as an org agent template under a new name, so members can create their own copy from it. Credentials and per-person settings are not carried over; the result lists what was omitted.",
+                input: z
+                    .object({
+                    agentId: z.string().min(1).max(100),
+                    name: z.string().min(1).max(80),
+                    description: z.string().min(1).max(1024),
+                })
+                    .strict(),
+                example: {
+                    agentId: "7c1a5b0e-9a53-4c6b-8d64-2f5a1b0c3e77",
+                    name: "support-triage",
+                    description: "Triages incoming support requests and drafts a first reply.",
+                },
+                authz: { orgAction: "agents.manage" },
+                mirrors: ["POST /api/v1/orgs/:orgId/agents/:agentId/save-as-template"],
+                confirm: "org",
+                summary: async (i, ctx) => {
+                    const source = named(await orElse(async () => (await this.agents.get(ctx.orgId, i.agentId, ctx.actorAccountId)).definition.name, i.agentId));
+                    return {
+                        zh: `把智能体「${source}」另存为组织模板「${named(i.name)}」`,
+                        en: `Save agent "${source}" as org template "${named(i.name)}"`,
+                    };
+                },
+                run: async (input, ctx) => asToolError(() => this.orgTemplates.saveAs(ctx.orgId, ctx.actorAccountId, input.agentId, { name: input.name, description: input.description }, undefined, viaAgent("agent-templates.save", ctx))),
+            }),
+        ]);
+    }
+};
+AgentTemplatesOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(AgentTemplatesService)),
+    __param(2, Inject(OrgAgentTemplates)),
+    __param(3, Inject(AgentsService))
+], AgentTemplatesOperations);
+export { AgentTemplatesOperations };

package/dist/platform/ops/agents.ops.d.ts

@@ -0,0 +1,19 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { AgentsService } from "../../agents/agents.service.js";
+import { AgentsFromTemplate } from "../../agents/from-template.service.js";
+import { OrgAgentTemplates } from "../../agents/org-templates.js";
+import { PlatformOperations } from "../registry.js";
+/** Agent operations of the `Platform` tool (spec §7); visibility is the person's own agents. */
+export declare class AgentsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly agents;
+    private readonly fromTemplate;
+    private readonly orgTemplates;
+    constructor(registry: PlatformOperations, agents: AgentsService, fromTemplate: AgentsFromTemplate, orgTemplates: OrgAgentTemplates);
+    /**
+     * `agents.update`'s class (spec §13): `personal` (may be remembered) only on a private agent the
+     * actor owns; any other agent the actor may edit is shared, so each change is confirmed.
+     */
+    private updateClass;
+    onModuleInit(): void;
+}

package/dist/platform/ops/agents.ops.js

@@ -0,0 +1,294 @@
+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 { ToolError } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { AgentsService } from "../../agents/agents.service.js";
+import { AgentDefinitionSchema, DEFAULT_AGENT_TOOLS, SubagentsSchema, } from "../../agents/definition.js";
+import { AgentsFromTemplate } from "../../agents/from-template.service.js";
+import { OrgAgentTemplates } from "../../agents/org-templates.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { asToolError, viaAgent } from "./errors.js";
+import { named, orElse } from "./summary.js";
+const Id = z.string().min(1).max(100);
+const Short = z.string().min(1).max(200);
+const Model = z.object({ provider: Short, model: Short }).strict();
+const ToolRef = z.union([
+    z.object({ kind: z.literal("builtin"), name: Short }).strict(),
+    z.object({ kind: z.literal("plugin"), plugin: Short, name: Short }).strict(),
+    z
+        .object({
+        kind: z.literal("connector"),
+        connectorId: Short,
+        tools: z.union([z.literal("all"), z.array(Short).min(1).max(200)]),
+    })
+        .strict(),
+]);
+const ToolPolicies = z.record(Short, z.enum(["ask", "deny"]));
+const Skills = z
+    .object({
+    orgSkills: z.array(Id).max(100),
+    pinned: z.array(Id).max(100).optional(),
+})
+    .strict();
+/** The definition fields an agent can set through the tool; the rest keep the web's defaults. */
+const Fields = {
+    instructions: z.string().max(100_000),
+    model: Model,
+    tools: z.array(ToolRef).max(200),
+    toolPolicies: ToolPolicies,
+    skills: Skills,
+    subagents: SubagentsSchema,
+};
+const WEB_ONLY = "Agents created with the Platform tool are private, and no agent's visibility can be changed with it; sharing an agent with the org or with members is done on the agents page of the web app.";
+const brief = (a) => ({
+    id: a.id,
+    name: a.definition.name,
+    description: a.profile.description,
+    visibility: a.visibility,
+    ownerAccountId: a.ownerAccountId,
+    currentVersion: a.currentVersion,
+    model: a.definition.model,
+    createdFromTemplate: a.createdFrom?.templateId ?? null,
+    updatedAt: a.updatedAt,
+});
+/** Agent operations of the `Platform` tool (spec §7); visibility is the person's own agents. */
+let AgentsOperations = class AgentsOperations {
+    registry;
+    agents;
+    fromTemplate;
+    orgTemplates;
+    constructor(registry, agents, fromTemplate, orgTemplates) {
+        this.registry = registry;
+        this.agents = agents;
+        this.fromTemplate = fromTemplate;
+        this.orgTemplates = orgTemplates;
+    }
+    /**
+     * `agents.update`'s class (spec §13): `personal` (may be remembered) only on a private agent the
+     * actor owns; any other agent the actor may edit is shared, so each change is confirmed.
+     */
+    async updateClass(agentId, ctx) {
+        const a = await this.agents.get(ctx.orgId, agentId, ctx.actorAccountId);
+        return a.visibility === "private" && a.ownerAccountId === ctx.actorAccountId
+            ? "personal"
+            : "org";
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "agents.list",
+                description: "List the agents you can see in the org: your own and those shared with the org or with you. Each entry has an id, name, visibility, owner, version and model.",
+                input: z.object({}).strict(),
+                example: {},
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/agents"],
+                confirm: "read",
+                run: async (_input, ctx) => ({
+                    agents: (await this.agents.listVisible(ctx.orgId, ctx.actorAccountId)).map(brief),
+                }),
+            }),
+            defineOperation({
+                id: "agents.get",
+                description: "Read one agent you can see with its full definition: instructions, model, tools, skills and sub-agents. Takes the agent id from agents.list.",
+                input: z.object({ agentId: Id }).strict(),
+                example: { agentId: "7c1a5b0e-9a53-4c6b-8d64-2f5a1b0c3e77" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/agents/:agentId"],
+                confirm: "read",
+                run: async (input, ctx) => asToolError(async () => ({
+                    agent: await this.agents.get(ctx.orgId, input.agentId, ctx.actorAccountId),
+                })),
+            }),
+            defineOperation({
+                id: "agents.create",
+                description: "Create a new private agent owned by you, with a name, a model and optionally instructions, tools, skills and sub-agents. Without tools it gets the default ones. Agents created with the Platform tool are private; sharing an agent with the org or with members is done on the agents page of the web app.",
+                input: z
+                    .object({
+                    definition: z
+                        .object({
+                        name: z.string().min(1).max(80),
+                        instructions: Fields.instructions.optional(),
+                        model: Fields.model,
+                        tools: Fields.tools.optional(),
+                        toolPolicies: Fields.toolPolicies.optional(),
+                        skills: Fields.skills.optional(),
+                        subagents: Fields.subagents.optional(),
+                    })
+                        .strict(),
+                    visibility: z.string().max(40).optional(),
+                })
+                    .strict(),
+                example: {
+                    definition: {
+                        name: "Report writer",
+                        instructions: "Write clear weekly reports from the notes you are given.",
+                        model: { provider: "anthropic", model: "claude-sonnet-4-5" },
+                    },
+                },
+                authz: { orgAction: "agents.create" },
+                mirrors: ["POST /api/v1/orgs/:orgId/agents"],
+                confirm: "personal",
+                summary: (i) => ({
+                    zh: `新建私有智能体「${i.definition.name}」`,
+                    en: `Create private agent "${i.definition.name}"`,
+                }),
+                run: async (input, ctx) => {
+                    if (input.visibility !== undefined && input.visibility !== "private") {
+                        throw new ToolError(WEB_ONLY);
+                    }
+                    const d = input.definition;
+                    const parsed = AgentDefinitionSchema.omit({ pendingConnectors: true }).parse({
+                        name: d.name,
+                        model: d.model,
+                        tools: d.tools ?? structuredClone(DEFAULT_AGENT_TOOLS),
+                        ...(d.toolPolicies !== undefined && { toolPolicies: d.toolPolicies }),
+                        ...(d.skills !== undefined && { skills: d.skills }),
+                        ...(d.subagents !== undefined && { subagents: d.subagents }),
+                    });
+                    return asToolError(() => this.agents.create(ctx.orgId, ctx.actorAccountId, {
+                        definition: { ...parsed, instructions: d.instructions },
+                        visibility: "private",
+                    }, undefined, viaAgent("agents.create", ctx)));
+                },
+            }),
+            defineOperation({
+                id: "agents.update",
+                description: "Change an agent you may edit: your own, private or shared, and as an org admin any agent of the org. Send the version you read from agents.get and only the fields to change; the others keep their value. A version that is no longer current is refused, so read the agent again first. The visibility cannot be changed here (that is done on the agents page of the web app). A change to your own private agent may be remembered by the person; a change to a shared agent is confirmed every time.",
+                input: z
+                    .object({
+                    agentId: Id,
+                    version: z.number().int().positive(),
+                    name: z.string().min(1).max(80).optional(),
+                    instructions: Fields.instructions.optional(),
+                    model: Fields.model.optional(),
+                    tools: Fields.tools.optional(),
+                    toolPolicies: Fields.toolPolicies.optional(),
+                    skills: Fields.skills.optional(),
+                    subagents: Fields.subagents.optional(),
+                })
+                    .strict(),
+                example: {
+                    agentId: "7c1a5b0e-9a53-4c6b-8d64-2f5a1b0c3e77",
+                    version: 3,
+                    instructions: "Write short weekly reports, three bullets at most.",
+                },
+                authz: { orgAction: "agents.create" },
+                mirrors: ["PATCH /api/v1/orgs/:orgId/agents/:agentId"],
+                confirm: "personal",
+                errors: [
+                    {
+                        code: "agent.version_conflict",
+                        next: "The agent changed since you read it: read it again with agents.get, then send its current version.",
+                    },
+                ],
+                confirmFor: (i, ctx) => this.updateClass(i.agentId, ctx),
+                summary: async (i, ctx) => {
+                    const a = await this.agents.get(ctx.orgId, i.agentId, ctx.actorAccountId);
+                    const name = named(a.definition.name);
+                    return a.visibility === "private"
+                        ? {
+                            zh: `修改私有智能体「${name}」（版本 ${i.version}）`,
+                            en: `Update private agent "${name}" (version ${i.version})`,
+                        }
+                        : {
+                            zh: `修改共享智能体「${name}」（版本 ${i.version}）`,
+                            en: `Update shared agent "${name}" (version ${i.version})`,
+                        };
+                },
+                run: async (input, ctx) => asToolError(async () => {
+                    const { agentId, version, ...patch } = input;
+                    const current = (await this.agents.get(ctx.orgId, agentId, ctx.actorAccountId))
+                        .definition;
+                    // the files are the authoring form of the prompt: a new prompt replaces them
+                    const { instructionFiles, ...base } = current;
+                    const definition = {
+                        ...(patch.instructions === undefined && instructionFiles !== undefined
+                            ? { ...base, instructionFiles }
+                            : base),
+                        ...(patch.name !== undefined && { name: patch.name }),
+                        ...(patch.instructions !== undefined && { instructions: patch.instructions }),
+                        ...(patch.model !== undefined && { model: patch.model }),
+                        ...(patch.tools !== undefined && { tools: patch.tools }),
+                        ...(patch.toolPolicies !== undefined && { toolPolicies: patch.toolPolicies }),
+                        ...(patch.skills !== undefined && { skills: patch.skills }),
+                        ...(patch.subagents !== undefined && { subagents: patch.subagents }),
+                    };
+                    return this.agents.update(ctx.orgId, agentId, ctx.actorAccountId, { definition, expectedVersion: version }, undefined, viaAgent("agents.update", ctx));
+                }),
+            }),
+            defineOperation({
+                id: "agents.preview-from-template",
+                description: "Preview creating an agent from an agent template: what carries over, what is pending (connectors the org has not set up) or unavailable, the model that would be used, and a previewHash. agents.create-from-template needs that hash.",
+                input: z.object({ templateId: Id }).strict(),
+                example: { templateId: "5d0c7a52-3a0e-4f0a-bd0a-0f8c3d2a9e10" },
+                authz: { orgAction: "agents.create" },
+                mirrors: ["POST /api/v1/orgs/:orgId/agents/from-template/preview"],
+                confirm: "read",
+                run: async (input, ctx) => asToolError(() => this.fromTemplate.preview(ctx.orgId, input.templateId)),
+            }),
+            defineOperation({
+                id: "agents.create-from-template",
+                description: "Create a private agent from an agent template, with the previewHash of agents.preview-from-template; a changed template or org makes the hash stale and the preview must be redone. Connectors the template needs that the org lacks become pending entries and a setup request goes to the org admins. Agents created with the Platform tool are private; sharing an agent with the org or with members is done on the agents page of the web app.",
+                input: z
+                    .object({
+                    templateId: Id,
+                    name: z.string().min(1).max(80),
+                    previewHash: z.string().min(1).max(100),
+                    model: Model.optional(),
+                    visibility: z.string().max(40).optional(),
+                })
+                    .strict(),
+                example: {
+                    templateId: "5d0c7a52-3a0e-4f0a-bd0a-0f8c3d2a9e10",
+                    name: "My triage agent",
+                    previewHash: `${"0".repeat(64)}.${"0".repeat(16)}`,
+                },
+                authz: { orgAction: "agents.create" },
+                mirrors: ["POST /api/v1/orgs/:orgId/agents/from-template"],
+                confirm: "personal",
+                errors: [
+                    {
+                        code: "agent.template_preview_stale",
+                        next: "Call agents.preview-from-template again and use its new previewHash.",
+                    },
+                ],
+                summary: async (i, ctx) => {
+                    const t = named(await orElse(async () => (await this.orgTemplates.detail(ctx.orgId, i.templateId)).name, i.templateId));
+                    return {
+                        zh: `从模板「${t}」新建私有智能体「${named(i.name)}」`,
+                        en: `Create private agent "${named(i.name)}" from template "${t}"`,
+                    };
+                },
+                run: async (input, ctx) => {
+                    if (input.visibility !== undefined && input.visibility !== "private") {
+                        throw new ToolError(WEB_ONLY);
+                    }
+                    return asToolError(() => this.fromTemplate.create(ctx.orgId, ctx.actorAccountId, {
+                        templateId: input.templateId,
+                        name: input.name,
+                        previewHash: input.previewHash,
+                        visibility: "private",
+                        ...(input.model !== undefined && { model: input.model }),
+                    }, undefined, viaAgent("agents.create-from-template", ctx)));
+                },
+            }),
+        ]);
+    }
+};
+AgentsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(AgentsFromTemplate)),
+    __param(3, Inject(OrgAgentTemplates))
+], AgentsOperations);
+export { AgentsOperations };

package/dist/platform/ops/connectors.ops.d.ts

@@ -0,0 +1,15 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { ComponentScopeService } from "../../catalog/component-scope.service.js";
+import { ConnectorsService } from "../../tools/connectors.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Connector operations of the `Platform` tool (spec §7): read only. Creating a connector or
+ * entering a credential stays on the web (a person types credentials, spec §6.4).
+ */
+export declare class ConnectorsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly connectors;
+    private readonly components;
+    constructor(registry: PlatformOperations, connectors: ConnectorsService, components: ComponentScopeService);
+    onModuleInit(): void;
+}