@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.1

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

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type AgentsService, type AgentVersionSummary, type AgentView, type AgentWarning } from "./agents.service.js";
+declare const OwnerBody: z.ZodObject<{
+    accountId: z.ZodString;
+}, z.core.$strict>;
+declare const CreateBody: z.ZodObject<{
+    definition: z.ZodObject<{
+        name: z.ZodString;
+        avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
+        instructions: z.ZodDefault<z.ZodString>;
+        model: z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strip>;
+        fallback: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strip>>>;
+        modelParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        fallbackParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        toolPolicies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            ask: "ask";
+            deny: "deny";
+        }>>>;
+        skills: z.ZodOptional<z.ZodObject<{
+            orgSkills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            writePolicy: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        subagents: z.ZodOptional<z.ZodObject<{
+            general: z.ZodOptional<z.ZodBoolean>;
+            templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inline: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                instructions: z.ZodString;
+                tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                toolPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                    ask: "ask";
+                    deny: "deny";
+                }>>>;
+                model: z.ZodOptional<z.ZodEnum<{
+                    capable: "capable";
+                    fast: "fast";
+                    inherit: "inherit";
+                    standard: "standard";
+                }>>;
+                effort: z.ZodOptional<z.ZodEnum<{
+                    high: "high";
+                    low: "low";
+                    max: "max";
+                    medium: "medium";
+                    xhigh: "xhigh";
+                }>>;
+                maxSteps: z.ZodOptional<z.ZodNumber>;
+                skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                agentId: z.ZodString;
+                as: z.ZodString;
+                description: z.ZodString;
+            }, z.core.$strict>>>;
+            dispatchable: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"builtin">;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"plugin">;
+            plugin: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"connector">;
+            connectorId: z.ZodString;
+            tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+        }, z.core.$strict>], "kind">, unknown>>>;
+    }, z.core.$strip>;
+    visibility: z.ZodEnum<{
+        members: "members";
+        org: "org";
+        private: "private";
+    }>;
+    memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const UpdateBody: z.ZodObject<{
+    definition: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
+        instructions: z.ZodDefault<z.ZodString>;
+        model: z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strip>;
+        fallback: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            provider: z.ZodString;
+            model: z.ZodString;
+        }, z.core.$strip>>>;
+        modelParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        fallbackParams: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        tools: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"builtin">;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"plugin">;
+            plugin: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"connector">;
+            connectorId: z.ZodString;
+            tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+        }, z.core.$strict>], "kind">, unknown>>>;
+        toolPolicies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+            ask: "ask";
+            deny: "deny";
+        }>>>;
+        skills: z.ZodOptional<z.ZodObject<{
+            orgSkills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            writePolicy: z.ZodOptional<z.ZodEnum<{
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        subagents: z.ZodOptional<z.ZodObject<{
+            general: z.ZodOptional<z.ZodBoolean>;
+            templates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            inline: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                description: z.ZodString;
+                instructions: z.ZodString;
+                tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                toolPolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                    ask: "ask";
+                    deny: "deny";
+                }>>>;
+                model: z.ZodOptional<z.ZodEnum<{
+                    capable: "capable";
+                    fast: "fast";
+                    inherit: "inherit";
+                    standard: "standard";
+                }>>;
+                effort: z.ZodOptional<z.ZodEnum<{
+                    high: "high";
+                    low: "low";
+                    max: "max";
+                    medium: "medium";
+                    xhigh: "xhigh";
+                }>>;
+                maxSteps: z.ZodOptional<z.ZodNumber>;
+                skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>>;
+            agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                agentId: z.ZodString;
+                as: z.ZodString;
+                description: z.ZodString;
+            }, z.core.$strict>>>;
+            dispatchable: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strip>>;
+    visibility: z.ZodOptional<z.ZodEnum<{
+        members: "members";
+        org: "org";
+        private: "private";
+    }>>;
+    memberIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
+ * 写用 `agents.create`（member 以上、HUMAN_ONLY），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
+ */
+export declare class AgentsController {
+    private readonly agents;
+    constructor(agents: AgentsService);
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
+        agent: AgentView;
+        warnings: AgentWarning[];
+    }>;
+    list(principal: Principal, org: OrgContext): Promise<{
+        agents: AgentView[];
+    }>;
+    get(principal: Principal, org: OrgContext, agentId: string): Promise<{
+        agent: AgentView;
+    }>;
+    update(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof UpdateBody>): Promise<{
+        agent: AgentView;
+        warnings: AgentWarning[];
+    }>;
+    remove(principal: Principal, org: OrgContext, agentId: string): Promise<void>;
+    /** 重新指派负责人（admin，如负责人离职后）；清除 `needsReassignment`。 */
+    reassign(principal: Principal, org: OrgContext, agentId: string, body: z.infer<typeof OwnerBody>): Promise<{
+        agent: AgentView;
+    }>;
+    versions(principal: Principal, org: OrgContext, agentId: string): Promise<{
+        versions: AgentVersionSummary[];
+    }>;
+}
+export {};

package/dist/agents/agents.controller.js

@@ -0,0 +1,144 @@
+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 { Body, Controller, Delete, Get, HttpCode, Inject, Param, Patch, Post, } from "@nestjs/common";
+import { z } from "zod";
+import { AGENTS } from "../http/tokens.js";
+import { ZodPipe } from "../http/zod.pipe.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AGENT_VISIBILITIES, } from "./agents.service.js";
+import { AgentDefinitionSchema, AgentToolRef, DEFAULT_AGENT_TOOLS } from "./definition.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({
+    tools: z.array(AgentToolRef).default(() => structuredClone(DEFAULT_AGENT_TOOLS)),
+});
+const CreateBody = z
+    .object({
+    definition: CreateDefinition,
+    visibility: z.enum(AGENT_VISIBILITIES),
+    memberIds: MemberIds.optional(),
+})
+    .strict();
+const UpdateBody = z
+    .object({
+    definition: AgentDefinitionSchema.optional(),
+    visibility: z.enum(AGENT_VISIBILITIES).optional(),
+    memberIds: MemberIds.optional(),
+    /**
+     * 乐观并发：编辑页打开时读到的 `currentVersion`。给出且与当前版本不同（别人已保存过）→ 409
+     * `agent.version_conflict`，不覆盖别人的改动。不给时不检查（旧客户端）。
+     */
+    expectedVersion: z.number().int().positive().optional(),
+})
+    .strict();
+/** 服务令牌没有账号：以 null 作为 viewer，只看到 visibility='org' 的 agent。 */
+const viewerOf = (p) => (p.kind === "user" ? p.account.id : null);
+/**
+ * Agent 定义（`/api/v1/orgs/:orgId/agents`）。读用 `agents.use`（访客与服务令牌可用），
+ * 写用 `agents.create`（member 以上、HUMAN_ONLY），修改 / 删除的负责人或管理员判定在服务的组织行锁内完成。
+ */
+let AgentsController = class AgentsController {
+    agents;
+    constructor(agents) {
+        this.agents = agents;
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        return this.agents.create(org.orgId, p.account.id, {
+            definition: body.definition,
+            visibility: body.visibility,
+            ...(body.memberIds !== undefined && { memberIds: body.memberIds }),
+        }, patTokenId(p));
+    }
+    async list(principal, org) {
+        return { agents: await this.agents.listVisible(org.orgId, viewerOf(principal)) };
+    }
+    async get(principal, org, agentId) {
+        return { agent: 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));
+    }
+    async remove(principal, org, agentId) {
+        const p = requireUser(principal);
+        await this.agents.softDelete(org.orgId, agentId, p.account.id, patTokenId(p));
+    }
+    /** 重新指派负责人（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)),
+        };
+    }
+    async versions(principal, org, agentId) {
+        await this.agents.get(org.orgId, agentId, viewerOf(principal));
+        return { versions: await this.agents.listVersions(agentId) };
+    }
+};
+__decorate([
+    Post(),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Body(new ZodPipe(CreateBody)))
+], AgentsController.prototype, "create", null);
+__decorate([
+    Get(),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], AgentsController.prototype, "list", null);
+__decorate([
+    Get(":agentId"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId"))
+], AgentsController.prototype, "get", null);
+__decorate([
+    Patch(":agentId"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Body(new ZodPipe(UpdateBody)))
+], AgentsController.prototype, "update", null);
+__decorate([
+    Delete(":agentId"),
+    HttpCode(204),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId"))
+], AgentsController.prototype, "remove", null);
+__decorate([
+    Post(":agentId/owner"),
+    HttpCode(200),
+    OrgAction("agents.manage"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Body(new ZodPipe(OwnerBody)))
+], AgentsController.prototype, "reassign", null);
+__decorate([
+    Get(":agentId/versions"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId"))
+], AgentsController.prototype, "versions", null);
+AgentsController = __decorate([
+    Controller("api/v1/orgs/:orgId/agents"),
+    __param(0, Inject(AGENTS))
+], AgentsController);
+export { AgentsController };

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

@@ -0,0 +1,177 @@
+import { type Logger, type ModelParameter } from "@capybara-hq/plugin-sdk";
+import { type ExpressionBuilder, type Transaction } from "kysely";
+import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+import type { ProviderRegistry } from "../runtime/providers.js";
+import type { SkillChangesService } from "../skills/changes.service.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import { type AgentDefinition } from "./definition.js";
+type Trx = Transaction<KernelDatabase>;
+export declare const AGENT_VISIBILITIES: readonly ["private", "org", "members"];
+export type AgentVisibility = (typeof AGENT_VISIBILITIES)[number];
+/** 对外的 agent 视图：当前版本的定义 + 元数据；`memberIds` 只在 visibility='members' 时为数组。 */
+export interface AgentView {
+    id: string;
+    orgId: string;
+    ownerAccountId: string;
+    visibility: AgentVisibility;
+    currentVersion: number;
+    definition: AgentDefinition;
+    memberIds: string[] | null;
+    /** 负责人离职后被转给组织所有者、等待管理员重新指派。 */
+    needsReassignment: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface AgentVersion {
+    version: number;
+    definition: AgentDefinition;
+    createdBy: string;
+    createdAt: Date;
+}
+export type AgentVersionSummary = Omit<AgentVersion, "definition">;
+/** 创建 / 修改的提示（不拒绝）：`fallback_same_provider` = 兜底与主模型同一供应商（spec 4.5）。 */
+export type AgentWarning = "fallback_same_provider";
+/** 按模型声明严格校验一组参数，返回 `{ path: "<field>.<key>", message }[]`（评测候选也用它）。 */
+export declare function paramIssues(field: string, decl: ModelParameter[], params: Record<string, unknown>): {
+    path: string;
+    message: string;
+}[];
+/**
+ * 可见性判定（`canUse`）的 SQL 条件：agent 未删除、所属组织未删除，且
+ * - viewer 为账号：仍是该组织成员（含访客），并且是负责人 / visibility='org' / 在 agent_members 名单中；
+ * - viewer 为 null（该组织的服务令牌）：只认 visibility='org'。
+ */
+export declare function visibleTo(viewerAccountId: string | null): (eb: ExpressionBuilder<KernelDatabase, "agents">) => import("kysely").ExpressionWrapper<KernelDatabase, "agents", import("kysely").SqlBool>;
+/**
+ * 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 declare function isAgentVisibleTo(db: KernelDb | Trx, agentId: string, accountId: string): Promise<boolean>;
+/** 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";
+/** Roster entries an agent may list (spec §4.3), general-purpose included. */
+export declare 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;
+ * - `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);
+ * - `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
+ *   skill of this agent;
+ * - `self`: this agent allowlisted; `agent_not_available`: an allowlisted agent that is not a live
+ *   agent of the org visible to the person saving with `subagents.dispatchable: true` in its
+ *   current version;
+ * - `too_many`: more than {@link SUBAGENT_ROSTER_MAX} roster entries.
+ * Template ids and allowlisted agents already in the current version (`kept`) are not re-checked
+ * for `not_found` / `agent_not_available`: a template uninstalled or an agent switched off later
+ * does not block other edits (the dispatch refuses it at run time).
+ */
+export declare function assertSubagents(t: Trx, a: {
+    orgId: string;
+    agentId: string | null;
+    actorAccountId: string;
+    definition: AgentDefinition;
+    toolKeys: ReadonlySet<string>;
+    kept?: AgentDefinition["subagents"];
+}): Promise<void>;
+/**
+ * Agent 定义、版本与可见范围。写操作都在组织行锁内实时复核发起人角色（spec 3.6 R5）；
+ * 服务只接收发起人账号 id。不可见的 agent 一律 `agent.not_found`。
+ */
+export declare class AgentsService {
+    private readonly db;
+    private readonly registry;
+    private readonly tools;
+    /** 删除 agent 时取消它待处理的技能改动（T15）。 */
+    private readonly skillChanges;
+    /**
+     * 删除 agent 后销毁它各对话的沙箱（内核投递一次性维护任务 `sandbox-destroy-for`，worker 在锁内逐个销毁，
+     * 幂等）。不给时留给不活跃销毁扫描。
+     */
+    private readonly sandboxes?;
+    private readonly log?;
+    constructor(db: KernelDb, registry: ProviderRegistry, tools: Pick<ToolRegistry, "checkRefs">, 
+    /** 删除 agent 时取消它待处理的技能改动（T15）。 */
+    skillChanges: Pick<SkillChangesService, "cancelPendingForAgent" | "finishCancel">, 
+    /**
+     * 删除 agent 后销毁它各对话的沙箱（内核投递一次性维护任务 `sandbox-destroy-for`，worker 在锁内逐个销毁，
+     * 幂等）。不给时留给不活跃销毁扫描。
+     */
+    sandboxes?: {
+        destroy(conversationIds: string[]): Promise<void>;
+    } | undefined, log?: Pick<Logger, "warn"> | undefined);
+    /**
+     * 校验工具引用与工具策略：引用的内置 / 插件 / 连接器工具必须存在（见 `ToolRegistry.checkRefs`）；
+     * `toolPolicies` 的键必须是这些引用产生的工具 key（取值只能收紧，已由 schema 保证）。
+     * 不合法 → `validation_failed`，path 为 `tools.<i>` / `toolPolicies.<key>`。
+     */
+    private checkTools;
+    /**
+     * 校验主模型与兜底都可解析，并用各自模型的参数声明严格校验 `modelParams` / `fallbackParams`
+     * （没有兜底时 `fallbackParams` 必须为空）；不合法 → `validation_failed`，details 逐键点名。返回提示。
+     */
+    private checkModels;
+    /** 名单里的账号必须都是该组织当前成员，否则 `member.not_found`；返回去重后的 id。 */
+    private checkMembers;
+    private setMembers;
+    private view;
+    /** 按给定 id 顺序组装视图（调用方已完成可见性判定）。 */
+    private views;
+    /**
+     * 新建 agent（版本 1）：在组织行锁内授权 `agents.create`；主模型与兜底都必须可解析
+     * （`agent.model_unavailable`）；兜底与主模型同一供应商只提示 `fallback_same_provider`。
+     */
+    create(orgId: string, actorAccountId: string, input: {
+        definition: AgentDefinition;
+        visibility: AgentVisibility;
+        memberIds?: string[];
+    }, actorTokenId?: string): Promise<{
+        agent: AgentView;
+        warnings: AgentWarning[];
+    }>;
+    /**
+     * 锁组织行并复核发起人，再锁 agent 行：发起人须仍具备 `agents.create`（member 以上），且是负责人或组织管理员以上；
+     * 对发起人不可见的 agent（非管理员）→ `agent.not_found`，可见但无权 → `forbidden`。
+     */
+    private lockForWrite;
+    /**
+     * 修改 agent：`definition` 变化时写新版本（`current_version + 1`），只改 visibility / memberIds 不产生新版本。
+     * 只有负责人或组织管理员以上可改，在组织行锁内复核。
+     */
+    update(orgId: string, agentId: string, actorAccountId: string, patch: {
+        definition?: AgentDefinition | undefined;
+        visibility?: AgentVisibility | undefined;
+        memberIds?: string[] | undefined;
+        /**
+         * 给出且不等于当前版本 → `agent.version_conflict`（409），在锁内判定。只比定义版本：只改可见范围 / 成员
+         * 不产生新版本，所以检测不到别人只改了可见范围（之后的保存会按本次给出的 visibility 覆盖）。
+         */
+        expectedVersion?: number | undefined;
+    }, actorTokenId?: string): Promise<{
+        agent: AgentView;
+        warnings: AgentWarning[];
+    }>;
+    /** 软删除：权限同 update。待处理的技能改动与该 agent 评测集在执行的评测运行一并取消，提交后删除草稿（T15）。 */
+    softDelete(orgId: string, agentId: string, actorAccountId: string, actorTokenId?: string): Promise<void>;
+    /** 提交后尽力而为：投递销毁这个 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>;
+    /** 取对 viewer 可见的 agent；`viewerAccountId = null` 表示该组织的服务令牌。不可见 → `agent.not_found`。 */
+    get(orgId: string, agentId: string, viewerAccountId: string | null): Promise<AgentView>;
+    /** 组织内对 viewer 可见的全部 agent（按创建时间）。 */
+    listVisible(orgId: string, viewerAccountId: string | null): Promise<AgentView[]>;
+    /** 读某个版本（不做可见性判定，调用方负责）；不存在 → `agent.not_found`。 */
+    getVersion(agentId: string, version: number): Promise<AgentVersion>;
+    /** 版本列表，新的在前（不做可见性判定，调用方负责）。 */
+    listVersions(agentId: string): Promise<AgentVersionSummary[]>;
+}
+export {};