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

package/dist/orgs/org.guard.d.ts

@@ -1,5 +1,7 @@
 import { type CanActivate, type ExecutionContext } from "@nestjs/common";
 import { Reflector } from "@nestjs/core";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { type Principal } from "../identity/principal.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { type OrgAction as Action, type OrgRole } from "./roles.js";
 /** OrgGuard 放在请求上的组织上下文。 */
@@ -21,6 +23,14 @@ export declare const ORG_ACTION_KEY = "capybara:org:action";
 export declare function OrgAction(action: Action): MethodDecorator & ClassDecorator;
 /** 参数装饰器：取 OrgGuard 放在 `req.org` 上的 `{ orgId, role }`。 */
 export declare const CurrentOrg: () => ParameterDecorator;
+/**
+ * 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 declare function authorizeOrgAction(db: Pick<KernelSchemaDb, "selectFrom">, p: Principal, orgId: string, action: Action): Promise<OrgRole>;
 /**
  * 组织守卫：每个请求实时从 PG 读组织与成员角色（不缓存）。
  * - 组织不存在、已软删除、或调用者不是成员 → 404 `org.not_found`（不泄露组织是否存在）。

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

@@ -12,8 +12,11 @@ import { OrgLock } from "./org-lock.js";
  * - `locale`：组织默认语言（`zh` / `en`，默认 en），机器人在 IM 里说的固定话术按它选择。
  * - `sandboxToolPolicy`：沙箱工具的默认策略（M5 T8，默认 allow）。为 `ask` 时除只读的
  *   `Read` / `Glob` / `Grep` 外都需要审批（执行时实时读取）。
+ * - `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;
@@ -42,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";
@@ -49,6 +57,7 @@ export declare const OrgSettingsSchema: z.ZodObject<{
         }>;
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
+    wakeOnBackgroundTask: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -65,6 +74,12 @@ 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<{
             allowlist: "allowlist";
@@ -81,15 +96,17 @@ export type DeploymentEgress = Pick<SandboxLimits, "egress" | "allowHosts">;
  * （省略时用部署的），但部署是 `none` 时仍为 `none`（组织永远不比部署放得更开，部署改成 none 后存量设置也随之收紧）。
  */
 export declare function effectiveSandboxEgress(deployment: DeploymentEgress, org: SandboxEgressSetting | undefined): DeploymentEgress;
+/** 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;
@@ -118,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

@@ -25,8 +25,11 @@ import { OrgLock } from "./org-lock.js";
  * - `locale`：组织默认语言（`zh` / `en`，默认 en），机器人在 IM 里说的固定话术按它选择。
  * - `sandboxToolPolicy`：沙箱工具的默认策略（M5 T8，默认 allow）。为 `ask` 时除只读的
  *   `Read` / `Glob` / `Grep` 外都需要审批（执行时实时读取）。
+ * - `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;
@@ -57,7 +60,10 @@ 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),
 });
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
 export const OrgSettingsPatchSchema = z
@@ -65,6 +71,9 @@ 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 清除（恢复跟随部署默认）。 */
     sandboxEgress: SandboxEgressSettingSchema.nullable().optional(),
 })
@@ -80,8 +89,12 @@ export function effectiveSandboxEgress(deployment, org) {
         return { egress: "none", allowHosts: [] };
     return { egress: "allowlist", allowHosts: [...(org.allowHosts ?? deployment.allowHosts)] };
 }
+/** Whether a finished background task wakes an idle conversation: the org's setting, else the deployment's. */
+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) {
@@ -130,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);
@@ -169,15 +182,17 @@ let OrgSettingsService = class OrgSettingsService {
         const before = parseOrgSettings(stored);
         const changes = Object.fromEntries(Object.entries(patch)
             .filter(([, v]) => v !== undefined)
-            // null 清除 sandboxEgress：恢复跟随部署默认
+            // null clears sandboxEgress / wakeOnBackgroundTask: follow the deployment default again
             .map(([k, v]) => [k, v === null ? undefined : v]));
         const after = { ...before, ...changes };
         if (after.sandboxEgress === undefined)
             delete after.sandboxEgress;
+        if (after.wakeOnBackgroundTask === undefined)
+            delete after.wakeOnBackgroundTask;
         if (sameSettings(before, after))
             return before;
         // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
-        const { sandboxEgress: _old, ...rest } = stored;
+        const { sandboxEgress: _old, wakeOnBackgroundTask: _oldWake, ...rest } = stored;
         await this.db
             .updateTable("orgs")
             .set({ settings: JSON.stringify({ ...rest, ...after }) })

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>;
+}