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

package/dist/orgs/org.guard.js

@@ -24,6 +24,48 @@ export function OrgAction(action) {
 /** 参数装饰器：取 OrgGuard 放在 `req.org` 上的 `{ orgId, role }`。 */
 export const CurrentOrg = createParamDecorator((_data, ctx) => ctx.switchToHttp().getRequest().org);
 const notFound = () => new ApiError("org.not_found", "Organization not found");
+/**
+ * The org role check of {@link OrgGuard}, read live from PG: the caller's role in `orgId` (a
+ * person's membership, a service token's own org and role) allows `action`, else 404
+ * `org.not_found` (missing, soft-deleted, not a member: existence is not disclosed) or 403
+ * `forbidden` (HUMAN_ONLY for a service token, role too low). Also run before the body of an org
+ * package upload is read (ruling P3-29).
+ */
+export async function authorizeOrgAction(db, p, orgId, action) {
+    let role;
+    if (p.kind === "service") {
+        if (p.orgId !== orgId)
+            throw notFound();
+        const live = await db
+            .selectFrom("orgs")
+            .select("id")
+            .where("id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!live)
+            throw notFound();
+        if (HUMAN_ONLY.has(action)) {
+            throw new ApiError("forbidden", "Service tokens cannot perform this action");
+        }
+        role = p.role;
+    }
+    else {
+        const m = await db
+            .selectFrom("memberships")
+            .innerJoin("orgs", "orgs.id", "memberships.org_id")
+            .select("memberships.role")
+            .where("memberships.org_id", "=", orgId)
+            .where("memberships.account_id", "=", p.account.id)
+            .where("orgs.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!m)
+            throw notFound();
+        role = m.role;
+    }
+    if (!can(role, action))
+        throw new ApiError("forbidden", "Insufficient organization role");
+    return role;
+}
 /**
  * 组织守卫：每个请求实时从 PG 读组织与成员角色（不缓存）。
  * - 组织不存在、已软删除、或调用者不是成员 → 404 `org.not_found`（不泄露组织是否存在）。
@@ -51,38 +93,7 @@ let OrgGuard = class OrgGuard {
         const orgId = req.params.orgId;
         if (!orgId)
             throw new Error("OrgGuard: route has no :orgId parameter");
-        let role;
-        if (p.kind === "service") {
-            if (p.orgId !== orgId)
-                throw notFound();
-            const live = await this.db
-                .selectFrom("orgs")
-                .select("id")
-                .where("id", "=", orgId)
-                .where("deleted_at", "is", null)
-                .executeTakeFirst();
-            if (!live)
-                throw notFound();
-            if (HUMAN_ONLY.has(action)) {
-                throw new ApiError("forbidden", "Service tokens cannot perform this action");
-            }
-            role = p.role;
-        }
-        else {
-            const m = await this.db
-                .selectFrom("memberships")
-                .innerJoin("orgs", "orgs.id", "memberships.org_id")
-                .select("memberships.role")
-                .where("memberships.org_id", "=", orgId)
-                .where("memberships.account_id", "=", p.account.id)
-                .where("orgs.deleted_at", "is", null)
-                .executeTakeFirst();
-            if (!m)
-                throw notFound();
-            role = m.role;
-        }
-        if (!can(role, action))
-            throw new ApiError("forbidden", "Insufficient organization role");
+        const role = await authorizeOrgAction(this.db.db, p, orgId, action);
         req.org = { orgId, role };
         return true;
     }

package/dist/orgs/orgs.module.js

@@ -5,6 +5,7 @@ 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 { CatalogModule } from "../catalog/catalog.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
 import { EvalBudgetModule } from "../evals/budget.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
@@ -43,6 +44,8 @@ OrgsModule = __decorate([
             SandboxModule,
             // cancels the deleted org's eval runs
             EvalBudgetModule,
+            // a new org's plugin scope sync (the producer; the worker role consumes it)
+            CatalogModule,
             // the producer side of directory-sync jobs (the maintenance processor consumes them)
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],

package/dist/orgs/orgs.service.d.ts

@@ -1,3 +1,5 @@
+import { OwnedItems } from "../catalog/owned-items.js";
+import { PluginScopeSync } from "../catalog/scope-sync.js";
 import { EvalBudget } from "../evals/budget.js";
 import type { Account } from "../identity/accounts.js";
 import { ApiTokenService } from "../identity/api-tokens.js";
@@ -18,8 +20,8 @@ export declare const SLUG_RE: RegExp;
 /** 由名字生成 slug：转小写、非字母数字换 `-`、去首尾 `-`；为空则 `org-<6 位随机>`。 */
 export declare function slugFromName(name: string): string;
 /**
- * Organizations: create, read, update and soft delete. A soft delete emits `org.deleted` on
- * {@link KernelEvents} after the commit.
+ * Organizations: create, read, update and soft delete. A new org's plugin scope sync is enqueued
+ * after the commit; a soft delete emits `org.deleted` on {@link KernelEvents} after the commit.
  */
 export declare class OrgsService {
     private readonly db;
@@ -30,9 +32,17 @@ export declare class OrgsService {
     private readonly events;
     /** Cancels the deleted org's running eval runs (in the delete's transaction). */
     private readonly evalBudget;
+    /** A new org gets the plugins its scope offers it (the scope sync, after the commit). */
+    private readonly scopeSync;
+    /** What the deleted org owns is transferred or removed in the delete's transaction (P3-20). */
+    private readonly ownedItems;
     constructor(db: KernelDb, txHost: TransactionHost, settings: SettingsService, apiTokens: ApiTokenService, orgLock: OrgLock, events: KernelEvents, 
     /** Cancels the deleted org's running eval runs (in the delete's transaction). */
-    evalBudget: Pick<EvalBudget, "cancelRuns">);
+    evalBudget: Pick<EvalBudget, "cancelRuns">, 
+    /** A new org gets the plugins its scope offers it (the scope sync, after the commit). */
+    scopeSync: Pick<PluginScopeSync, "enqueueOrg">, 
+    /** What the deleted org owns is transferred or removed in the delete's transaction (P3-20). */
+    ownedItems: Pick<OwnedItems, "onOrgDeleted">);
     /**
      * Creates an org with the actor as owner, in the caller's transaction when there is one (the
      * setup wizard creates it with the account); a slug conflict is `org.slug_taken` either way, but
@@ -49,7 +59,7 @@ export declare class OrgsService {
     listForAccount(accountId: string): Promise<(Org & {
         role: OrgRole;
     })[]>;
-    /** 全部（未软删除的）组织及成员数（企业管理员用）。 */
+    /** 全部（未软删除的）组织及成员数（超级管理员用）。 */
     listAll(): Promise<(Org & {
         memberCount: number;
     })[]>;
@@ -63,9 +73,12 @@ export declare class OrgsService {
     private updateIn;
     /**
      * Soft delete (needs owner, decided live under the org lock): in the same transaction revokes
-     * the org's service tokens, cancels its running eval runs and pending catalog requests, and
-     * clears sessions' current org pointing at it; after the commit emits `org.deleted` (channel
-     * connections go with the org: the runtime's connection reads filter deleted orgs).
+     * the org's service tokens, cancels its running eval runs and pending catalog requests, clears
+     * sessions' current org pointing at it, and transfers or removes the plugins and promoted
+     * components it owns ({@link OwnedItems.onOrgDeleted}, P3-20: shared ones become the platform's,
+     * the others are removed, a removed plugin's extension taken out by its cleanup job after the
+     * commit); after the commit emits `org.deleted` (channel connections go with the org: the
+     * runtime's connection reads filter deleted orgs).
      */
     softDelete(orgId: string, actor: Account, actorTokenId?: string): Promise<void>;
     private softDeleteIn;

package/dist/orgs/orgs.service.js

@@ -10,7 +10,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { randomBytes, randomUUID } from "node:crypto";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { cancelPendingRequests } from "../catalog/requests.service.js";
+import { OwnedItems } from "../catalog/owned-items.js";
+import { cancelPendingRequests } from "../catalog/request-rules.js";
+import { PluginScopeSync } from "../catalog/scope-sync.js";
 import { ApiError } from "../errors.js";
 import { EvalBudget } from "../evals/budget.js";
 import { ApiTokenService } from "../identity/api-tokens.js";
@@ -70,8 +72,8 @@ async function slugGuard(p) {
     }
 }
 /**
- * Organizations: create, read, update and soft delete. A soft delete emits `org.deleted` on
- * {@link KernelEvents} after the commit.
+ * Organizations: create, read, update and soft delete. A new org's plugin scope sync is enqueued
+ * after the commit; a soft delete emits `org.deleted` on {@link KernelEvents} after the commit.
  */
 let OrgsService = class OrgsService {
     db;
@@ -81,9 +83,15 @@ let OrgsService = class OrgsService {
     orgLock;
     events;
     evalBudget;
+    scopeSync;
+    ownedItems;
     constructor(db, txHost, settings, apiTokens, orgLock, events, 
     /** Cancels the deleted org's running eval runs (in the delete's transaction). */
-    evalBudget) {
+    evalBudget, 
+    /** A new org gets the plugins its scope offers it (the scope sync, after the commit). */
+    scopeSync, 
+    /** What the deleted org owns is transferred or removed in the delete's transaction (P3-20). */
+    ownedItems) {
         this.db = db;
         this.txHost = txHost;
         this.settings = settings;
@@ -91,6 +99,8 @@ let OrgsService = class OrgsService {
         this.orgLock = orgLock;
         this.events = events;
         this.evalBudget = evalBudget;
+        this.scopeSync = scopeSync;
+        this.ownedItems = ownedItems;
     }
     /**
      * Creates an org with the actor as owner, in the caller's transaction when there is one (the
@@ -104,8 +114,8 @@ let OrgsService = class OrgsService {
         // read in the context's transaction: a caller holding a connection asking the pool for a
         // second one could exhaust it under load
         const { orgCreation } = await this.settings.get();
-        if (orgCreation === "enterprise_admin" && !actor.isEnterpriseAdmin) {
-            throw new ApiError("org.creation_disabled", "Only enterprise admins can create organizations");
+        if (orgCreation === "super_admin" && !actor.isSuperAdmin) {
+            throw new ApiError("org.creation_disabled", "Only super admins can create organizations");
         }
         const name = checkName(input.name);
         const slug = input.slug ?? slugFromName(name);
@@ -127,6 +137,7 @@ let OrgsService = class OrgsService {
             target: row.id,
             detail: { slug, name },
         });
+        afterCommit(() => this.scopeSync.enqueueOrg(row.id));
         return toOrg(row);
     }
     /** 账号所属的（未软删除的）组织及其角色，按创建时间升序。 */
@@ -142,7 +153,7 @@ let OrgsService = class OrgsService {
             .execute();
         return rows.map((r) => ({ ...toOrg(r), role: r.role }));
     }
-    /** 全部（未软删除的）组织及成员数（企业管理员用）。 */
+    /** 全部（未软删除的）组织及成员数（超级管理员用）。 */
     async listAll() {
         const rows = await this.db
             .selectFrom("orgs")
@@ -205,9 +216,12 @@ let OrgsService = class OrgsService {
     }
     /**
      * Soft delete (needs owner, decided live under the org lock): in the same transaction revokes
-     * the org's service tokens, cancels its running eval runs and pending catalog requests, and
-     * clears sessions' current org pointing at it; after the commit emits `org.deleted` (channel
-     * connections go with the org: the runtime's connection reads filter deleted orgs).
+     * the org's service tokens, cancels its running eval runs and pending catalog requests, clears
+     * sessions' current org pointing at it, and transfers or removes the plugins and promoted
+     * components it owns ({@link OwnedItems.onOrgDeleted}, P3-20: shared ones become the platform's,
+     * the others are removed, a removed plugin's extension taken out by its cleanup job after the
+     * commit); after the commit emits `org.deleted` (channel connections go with the org: the
+     * runtime's connection reads filter deleted orgs).
      */
     async softDelete(orgId, actor, actorTokenId) {
         await this.softDeleteIn(orgId, actor, actorTokenId);
@@ -219,10 +233,14 @@ let OrgsService = class OrgsService {
             .set({ deleted_at: sql `now()` })
             .where("id", "=", orgId)
             .execute();
+        // after the org is marked deleted, so it counts as no user of what it shared (P3-18)
+        await this.ownedItems.onOrgDeleted(orgId, actor.id, {
+            ...(actorTokenId !== undefined && { actorTokenId }),
+        });
         await this.apiTokens.revokeAllForOrg(orgId);
         // eval runs of a deleted org stop spending: cancelled explicitly (audited with the reason)
         await this.evalBudget.cancelRuns({ orgId }, { accountId: actor.id, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, "org_deleted");
-        // pending catalog requests (including those passed to enterprise admins) are cancelled too
+        // pending catalog requests (including those passed to super admins) are cancelled too
         await cancelPendingRequests(this.db.db, { orgId }, actor.id, "org_deleted", actorTokenId !== undefined ? { actorTokenId } : {});
         await this.db
             .updateTable("sessions")
@@ -257,6 +275,8 @@ OrgsService = __decorate([
     __param(3, Inject(ApiTokenService)),
     __param(4, Inject(OrgLock)),
     __param(5, Inject(KernelEvents)),
-    __param(6, Inject(EvalBudget))
+    __param(6, Inject(EvalBudget)),
+    __param(7, Inject(PluginScopeSync)),
+    __param(8, Inject(OwnedItems))
 ], OrgsService);
 export { OrgsService };

package/dist/orgs/roles.d.ts

@@ -4,7 +4,7 @@ export type OrgRole = (typeof ORG_ROLES)[number];
 /** `role` 是否不低于 `min`。 */
 export declare function roleAtLeast(role: OrgRole, min: OrgRole): boolean;
 /** 组织级动作；路由用 `@OrgAction(action)` 声明所需动作。 */
-export type OrgAction = "org.read" | "org.update" | "org.delete" | "org.transfer" | "org.members.read" | "org.members.manage" | "org.invitations.manage" | "org.tokens.manage" | "org.extensions.manage" | "agents.create" | "agents.use" | "agents.manage" | "connectors.manage" | "connectors.use" | "approvals.decide" | "channels.manage" | "skills.read" | "skills.manage" | "ui.use" | "trajectories.read" | "evals.manage" | "org.models.manage" | "catalog.read" | "catalog.request" | "catalog.decide";
+export type OrgAction = "org.read" | "org.update" | "org.delete" | "org.transfer" | "org.members.read" | "org.members.manage" | "org.invitations.manage" | "org.tokens.manage" | "org.extensions.read" | "org.extensions.manage" | "agents.create" | "agents.use" | "agents.manage" | "connectors.manage" | "connectors.use" | "approvals.decide" | "channels.manage" | "skills.read" | "skills.manage" | "ui.use" | "trajectories.read" | "evals.manage" | "org.models.manage" | "catalog.read" | "catalog.request" | "catalog.decide" | "catalog.upload";
 /** 每个动作所需的最低角色。 */
 export declare const ACTION_MIN_ROLE: Record<OrgAction, OrgRole>;
 /** 只允许 user principal 执行的动作：服务令牌即使角色足够也拒绝（除 SERVICE_ALLOWED 外全部）。 */

package/dist/orgs/roles.js

@@ -12,6 +12,8 @@ export const ACTION_MIN_ROLE = {
     "org.members.manage": "admin",
     "org.invitations.manage": "admin",
     "org.tokens.manage": "admin",
+    // the 扩展 page for members: state only, no config / secrets / schema (the list projects by role)
+    "org.extensions.read": "member",
     "org.extensions.manage": "admin",
     "org.delete": "owner",
     "org.transfer": "owner",
@@ -38,11 +40,13 @@ export const ACTION_MIN_ROLE = {
     "evals.manage": "admin",
     // 本组织的模型用途映射（覆盖部署默认，如评委用途 eval）
     "org.models.manage": "admin",
-    // 企业目录（组织视角）：成员浏览（看不到 disabled）与申请；组织管理员决定成员申请（F-AF）。
+    // 平台目录（组织视角）：成员浏览（看不到 disabled）与申请；组织管理员决定成员申请（F-AF）。
     // 安装另按条目种类要求 skills.manage / connectors.manage / org.extensions.manage（服务里在组织行锁内复核）
     "catalog.read": "member",
     "catalog.request": "member",
     "catalog.decide": "admin",
+    // An org admin uploads a plugin package the org owns (spec §14.1 item 1, ruling P3-7)
+    "catalog.upload": "admin",
 };
 /** 服务令牌也可执行的动作：只读的 org.read、org.members.read，以及使用 agent 的 agents.use。 */
 const SERVICE_ALLOWED = new Set([

package/dist/orgs/settings.controller.d.ts

@@ -4,7 +4,7 @@ import { type OrgSandboxLimits, type OrgSettings, type OrgSettingsDeployment, ty
 /**
  * 组织设置（`/api/v1/orgs/:orgId/settings`）：成员可读，修改需 `org.update`（admin）。
  * 响应带 `deployment`（部署默认值，如沙箱出站），设置页据此展示「跟随部署」时的实际取值；
- * 以及只读的 `sandboxLimits`（组织实际生效的沙箱 cpu / 内存与来源，企业管理员在部署设置里覆盖，C19）。
+ * 以及只读的 `sandboxLimits`（组织实际生效的沙箱 cpu / 内存与来源，超级管理员在部署设置里覆盖，C19）。
  */
 type SettingsResponse = {
     settings: OrgSettings;

package/dist/orgs/settings.service.d.ts

@@ -15,6 +15,8 @@ import { OrgLock } from "./org-lock.js";
  * - `wakeOnBackgroundTask`：组织对 `runtime.wakeOnBackgroundTask` 的覆盖（缺省跟随部署），见 {@link effectiveWakeOnBackgroundTask}。
  * - `sandboxEgress`：组织的沙箱出站（Ruling M19 / D6），缺省跟随部署的 `sandbox.limits.egress` + `allowHosts`。
  *   见 {@link effectiveSandboxEgress}。存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ * - `platformTool`: the `Platform` builtin for the whole org (Platform tool spec §3): `on`,
+ *   `read-only` (writes listed as unavailable) or `off` (default `on`).
  */
 /** 组织沙箱出站白名单的主机数上限。 */
 export declare const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
@@ -43,6 +45,11 @@ export declare const OrgSettingsSchema: z.ZodObject<{
         allow: "allow";
         ask: "ask";
     }>>>;
+    platformTool: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+        off: "off";
+        on: "on";
+        "read-only": "read-only";
+    }>>>;
     sandboxEgress: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<{
             allowlist: "allowlist";
@@ -67,6 +74,11 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
         allow: "allow";
         ask: "ask";
     }>>;
+    platformTool: z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        on: "on";
+        "read-only": "read-only";
+    }>>;
     wakeOnBackgroundTask: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
     sandboxEgress: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         mode: z.ZodEnum<{
@@ -87,14 +99,14 @@ export declare function effectiveSandboxEgress(deployment: DeploymentEgress, org
 /** Whether a finished background task wakes an idle conversation: the org's setting, else the deployment's. */
 export declare function effectiveWakeOnBackgroundTask(deployment: boolean, org: OrgSettings["wakeOnBackgroundTask"]): boolean;
 /**
- * 组织实际生效的沙箱限额（C19 / Ruling M16）：企业管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
+ * 组织实际生效的沙箱限额（C19 / Ruling M16）：超级管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
  * 给出的 cpu / memoryMb 替换部署默认，未给的项、disk 与出站沿用 `deployment`。只在创建沙箱时读取。
  */
 export declare function effectiveSandboxLimits(deployment: SandboxLimits, override: {
     cpu?: number | undefined;
     memoryMb?: number | undefined;
 } | undefined): SandboxLimits;
-/** 组织设置 GET 带回的只读沙箱限额：实际生效值与来源（有企业管理员的覆盖为 `override`）。 */
+/** 组织设置 GET 带回的只读沙箱限额：实际生效值与来源（有超级管理员的覆盖为 `override`）。 */
 export interface OrgSandboxLimits {
     cpu: number;
     memoryMb: number;
@@ -123,7 +135,7 @@ export declare class OrgSettingsService {
     config: Pick<KernelConfigService, "get">);
     /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
     deployment(): OrgSettingsDeployment;
-    /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
+    /** 组织实际生效的沙箱 cpu / 内存（只读；由超级管理员在部署设置里覆盖）。 */
     sandboxLimits(orgId: string): Promise<OrgSandboxLimits>;
     get(orgId: string): Promise<OrgSettings>;
     update(orgId: string, patch: OrgSettingsPatch, actorAccountId: string, actorTokenId?: string): Promise<OrgSettings>;

package/dist/orgs/settings.service.js

@@ -28,6 +28,8 @@ import { OrgLock } from "./org-lock.js";
  * - `wakeOnBackgroundTask`：组织对 `runtime.wakeOnBackgroundTask` 的覆盖（缺省跟随部署），见 {@link effectiveWakeOnBackgroundTask}。
  * - `sandboxEgress`：组织的沙箱出站（Ruling M19 / D6），缺省跟随部署的 `sandbox.limits.egress` + `allowHosts`。
  *   见 {@link effectiveSandboxEgress}。存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ * - `platformTool`: the `Platform` builtin for the whole org (Platform tool spec §3): `on`,
+ *   `read-only` (writes listed as unavailable) or `off` (default `on`).
  */
 /** 组织沙箱出站白名单的主机数上限。 */
 export const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
@@ -58,6 +60,7 @@ export const OrgSettingsSchema = z.object({
     toolSearch: z.enum(["on", "off"]).default("on").catch("on"),
     locale: z.enum(["zh", "en"]).default("en").catch("en"),
     sandboxToolPolicy: z.enum(["allow", "ask"]).default("allow").catch("allow"),
+    platformTool: z.enum(["on", "read-only", "off"]).default("on").catch("on"),
     sandboxEgress: SandboxEgressSettingSchema.optional().catch({ mode: "none" }),
     /** Overrides `runtime.wakeOnBackgroundTask`; absent follows the deployment. */
     wakeOnBackgroundTask: z.boolean().optional().catch(undefined),
@@ -68,6 +71,7 @@ export const OrgSettingsPatchSchema = z
     toolSearch: z.enum(["on", "off"]).optional(),
     locale: z.enum(["zh", "en"]).optional(),
     sandboxToolPolicy: z.enum(["allow", "ask"]).optional(),
+    platformTool: z.enum(["on", "read-only", "off"]).optional(),
     /** null clears (follow the deployment again). */
     wakeOnBackgroundTask: z.boolean().nullable().optional(),
     /** null 清除（恢复跟随部署默认）。 */
@@ -90,7 +94,7 @@ export function effectiveWakeOnBackgroundTask(deployment, org) {
     return org ?? deployment;
 }
 /**
- * 组织实际生效的沙箱限额（C19 / Ruling M16）：企业管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
+ * 组织实际生效的沙箱限额（C19 / Ruling M16）：超级管理员的覆盖（部署设置 `sandboxLimitOverrides[orgId]`）
  * 给出的 cpu / memoryMb 替换部署默认，未给的项、disk 与出站沿用 `deployment`。只在创建沙箱时读取。
  */
 export function effectiveSandboxLimits(deployment, override) {
@@ -139,7 +143,7 @@ let OrgSettingsService = class OrgSettingsService {
             sandboxEgress: { mode: lim.egress, allowHosts: [...lim.allowHosts] },
         };
     }
-    /** 组织实际生效的沙箱 cpu / 内存（只读；由企业管理员在部署设置里覆盖）。 */
+    /** 组织实际生效的沙箱 cpu / 内存（只读；由超级管理员在部署设置里覆盖）。 */
     async sandboxLimits(orgId) {
         const lim = this.config.get().sandbox.limits;
         const override = await readSandboxLimitOverride(this.db.db, orgId);

package/dist/overrides.d.ts

@@ -8,6 +8,7 @@ import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
 import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
 import { AGENT_LOOP_FACTORY, type AgentLoopFactory } from "./runtime/run-steps.js";
 import { RUN_HOOKS, type RunHooks } from "./runtime/run-worker.js";
+import { SUBAGENT_MESSAGES_HOOKS, type SubagentMessagesHooks } from "./runtime/subagents/messages.js";
 import { USAGE_REPORT_RETRY, type UsageReportRetry } from "./runtime/usage-report.js";
 import { SANDBOX_LEASE_TIMINGS, type SandboxLeaseTimings } from "./sandbox/leases.js";
 import { TOOL_PIPELINE_HOOKS, type ToolPipelineHooks } from "./tools/pipeline.js";
@@ -20,6 +21,7 @@ import { EMBED_TOKEN_CLOCK } from "./ui/embed-token.js";
  * - `RUN_HOOKS`: the run worker's hooks;
  * - `EVAL_REPLAY_HOOKS`: the hooks of the eval full-run replay and the judge;
  * - `TOOL_PIPELINE_HOOKS`: the tool pipeline's hooks and policy decision;
+ * - `SUBAGENT_MESSAGES_HOOKS`: the sub-agent message tools' hooks (a send raced by a run's end);
  * - `BOOTSTRAP_LOCK_TTL`, `FILE_PREVIEW_TIMEOUT`, `LIST_MODELS_TIMEOUT`, `USAGE_REPORT_RETRY`,
  *   `SANDBOX_LEASE_TIMINGS`, `CHANNEL_WEBHOOK_TIMINGS`: shorter timings;
  * - `EMBED_TOKEN_CLOCK`: the clock embed tokens are issued and checked with;
@@ -30,6 +32,7 @@ interface KernelSeams {
     [RUN_HOOKS]: RunHooks;
     [EVAL_REPLAY_HOOKS]: EvalReplayHooks;
     [TOOL_PIPELINE_HOOKS]: ToolPipelineHooks;
+    [SUBAGENT_MESSAGES_HOOKS]: SubagentMessagesHooks;
     [BOOTSTRAP_LOCK_TTL]: number;
     [FILE_PREVIEW_TIMEOUT]: number;
     [LIST_MODELS_TIMEOUT]: number;

package/dist/overrides.js

@@ -6,6 +6,7 @@ import { FILE_PREVIEW_TIMEOUT } from "./files/previewers.js";
 import { LIST_MODELS_TIMEOUT } from "./runtime/providers.js";
 import { AGENT_LOOP_FACTORY } from "./runtime/run-steps.js";
 import { RUN_HOOKS } from "./runtime/run-worker.js";
+import { SUBAGENT_MESSAGES_HOOKS, } from "./runtime/subagents/messages.js";
 import { USAGE_REPORT_RETRY } from "./runtime/usage-report.js";
 import { SANDBOX_LEASE_TIMINGS } from "./sandbox/leases.js";
 import { TOOL_PIPELINE_HOOKS } from "./tools/pipeline.js";
@@ -15,6 +16,7 @@ const SEAM_TOKENS = [
     RUN_HOOKS,
     EVAL_REPLAY_HOOKS,
     TOOL_PIPELINE_HOOKS,
+    SUBAGENT_MESSAGES_HOOKS,
     BOOTSTRAP_LOCK_TTL,
     FILE_PREVIEW_TIMEOUT,
     LIST_MODELS_TIMEOUT,

package/dist/platform/actor.d.ts

@@ -0,0 +1,48 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { type OrgSettings } from "../orgs/settings.service.js";
+/** What `availability()` (./availability.ts) decides on, read live for each call (spec §6.1). */
+export interface ActorFacts {
+    /**
+     * The actor's role in the org; null: not a member any more, or the account is disabled (the HTTP
+     * auth refuses a disabled account on every request).
+     */
+    role: OrgRole | null;
+    isSuperAdmin: boolean;
+    /** A person who can see and answer a confirmation is behind this run. */
+    personPresent: boolean;
+    /** The root conversation's agent is `private` and its owner is the actor. */
+    agentPrivateToActor: boolean;
+    /** The org setting `platformTool`. */
+    setting: OrgSettings["platformTool"];
+}
+/**
+ * Reads the facts about the actor of a `Platform` call: the run's trigger account (spec §6.1),
+ * re-read on every call, as the HTTP guards would.
+ *
+ * A person is present when all of these hold:
+ * - there is a run, it belongs to the conversation and its trigger account is the actor;
+ * - the root conversation of the tree (a sub-agent's is followed up through its parents) is a
+ *   `chat` (an `eval` conversation replays, nobody watches it);
+ * - the actor is an active member of the org, and not the org's anonymous guest account (a channel
+ *   message from an unlinked user under the `anonymous` policy runs as that account).
+ *
+ * The agent is private to the actor when the root conversation's agent is `private` and owned by
+ * the actor (a sub-agent's own agent does not count; Platform tool spec §6.1).
+ *
+ * Service tokens cannot start runs (posting a message requires a user principal), so no run is
+ * token-started; a wake run (`budget_run_id` set) runs as the person whose run it continues and
+ * counts as present. No new run column is needed to tell the origins apart.
+ */
+export declare class PlatformActor {
+    private readonly db;
+    constructor(db: KernelDb);
+    facts(ctx: {
+        orgId: string;
+        accountId: string;
+        /** The calling agent (from the runtime, never from the model's input). */
+        agentId: string;
+        conversationId: string;
+        runId?: string | null;
+    }): Promise<ActorFacts>;
+}

package/dist/platform/actor.js

@@ -0,0 +1,100 @@
+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 { KernelDb } from "../infra/database/kernel-db.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
+/**
+ * Reads the facts about the actor of a `Platform` call: the run's trigger account (spec §6.1),
+ * re-read on every call, as the HTTP guards would.
+ *
+ * A person is present when all of these hold:
+ * - there is a run, it belongs to the conversation and its trigger account is the actor;
+ * - the root conversation of the tree (a sub-agent's is followed up through its parents) is a
+ *   `chat` (an `eval` conversation replays, nobody watches it);
+ * - the actor is an active member of the org, and not the org's anonymous guest account (a channel
+ *   message from an unlinked user under the `anonymous` policy runs as that account).
+ *
+ * The agent is private to the actor when the root conversation's agent is `private` and owned by
+ * the actor (a sub-agent's own agent does not count; Platform tool spec §6.1).
+ *
+ * Service tokens cannot start runs (posting a message requires a user principal), so no run is
+ * token-started; a wake run (`budget_run_id` set) runs as the person whose run it continues and
+ * counts as present. No new run column is needed to tell the origins apart.
+ */
+let PlatformActor = class PlatformActor {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async facts(ctx) {
+        const rootId = await rootConversationOf(this.db.db, ctx.conversationId);
+        const [account, settings, root, anonymous, run] = await Promise.all([
+            this.db
+                .selectFrom("accounts")
+                .leftJoin("memberships", (j) => j
+                .onRef("memberships.account_id", "=", "accounts.id")
+                .on("memberships.org_id", "=", ctx.orgId))
+                .select(["accounts.is_super_admin", "accounts.status", "memberships.role"])
+                .where("accounts.id", "=", ctx.accountId)
+                .executeTakeFirst(),
+            readOrgSettings(this.db.db, ctx.orgId),
+            this.db
+                .selectFrom("conversations")
+                .select(["kind", "agent_id"])
+                .where("id", "=", rootId)
+                .where("org_id", "=", ctx.orgId)
+                .executeTakeFirst(),
+            this.db
+                .selectFrom("org_anonymous_accounts")
+                .select("account_id")
+                .where("org_id", "=", ctx.orgId)
+                .where("account_id", "=", ctx.accountId)
+                .executeTakeFirst(),
+            ctx.runId == null
+                ? undefined
+                : this.db
+                    .selectFrom("runs")
+                    .select("trigger_account_id")
+                    .where("id", "=", ctx.runId)
+                    .where("conversation_id", "=", ctx.conversationId)
+                    .executeTakeFirst(),
+        ]);
+        // the super admin's "own private agent" is the tree's root agent: a sub-agent (a template or
+        // general-purpose child) of a shared agent's conversation never counts as private
+        const agentId = rootId === ctx.conversationId ? ctx.agentId : root?.agent_id;
+        const agent = agentId == null
+            ? undefined
+            : await this.db
+                .selectFrom("agents")
+                .select(["owner_account_id", "visibility"])
+                .where("id", "=", agentId)
+                .where("org_id", "=", ctx.orgId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+        const activeMember = account?.role != null && account.status === "active";
+        return {
+            role: activeMember ? (account?.role ?? null) : null,
+            isSuperAdmin: account?.is_super_admin === true && account.status === "active",
+            // the run is the actor's, in this conversation, and its tree's root is a `chat`
+            personPresent: activeMember &&
+                anonymous === undefined &&
+                run?.trigger_account_id === ctx.accountId &&
+                root?.kind === "chat",
+            agentPrivateToActor: agent?.visibility === "private" && agent.owner_account_id === ctx.accountId,
+            setting: settings.platformTool,
+        };
+    }
+};
+PlatformActor = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], PlatformActor);
+export { PlatformActor };

package/dist/platform/agent-docs.d.ts

@@ -0,0 +1,18 @@
+export interface AgentDocTopic {
+    id: string;
+    title: string;
+}
+/**
+ * The documentation topics the `Platform` tool's `read` action serves (Platform tool spec §8):
+ * the Markdown files of the SDK's `agent-docs` directory, versioned with the contracts they
+ * describe. The files are immutable within a version, so one read per process is a cache of
+ * package files, not shared state.
+ */
+export declare class AgentDocs {
+    private cache;
+    private load;
+    /** Topic ids (path without `.md`, e.g. `extension-points/channel`) with their titles. */
+    topics(): AgentDocTopic[];
+    /** The Markdown of a topic, or null when there is none. */
+    read(id: string): string | null;
+}