@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

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

@@ -1,10 +1,14 @@
-import { type Transaction } from "kysely";
-import type { KernelDatabase, KernelDb } from "../db/kernel-schema.js";
+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 type { ApiTokenService } from "../identity/api-tokens.js";
-import type { SettingsService } from "../identity/settings.js";
+import { ApiTokenService } from "../identity/api-tokens.js";
+import { SettingsService } from "../identity/settings.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OrgLock } from "./org-lock.js";
 import type { OrgRole } from "./roles.js";
-type Trx = Transaction<KernelDatabase>;
 export type Org = {
     id: string;
     slug: string;
@@ -15,47 +19,69 @@ export type Org = {
 export declare const SLUG_RE: RegExp;
 /** 由名字生成 slug：转小写、非字母数字换 `-`、去首尾 `-`；为空则 `org-<6 位随机>`。 */
 export declare function slugFromName(name: string): string;
-/** 组织服务：创建、查询、修改与软删除。框架无关，由调用方注入依赖。 */
+/**
+ * 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;
+    readonly txHost: TransactionHost;
     private readonly settings;
     private readonly apiTokens;
-    private readonly hooks;
-    constructor(db: KernelDb, settings: SettingsService, apiTokens: ApiTokenService, hooks?: {
-        /** 软删除提交之后（内核传：给该组织的渠道连接广播 `channel.changed`，长连接立即断开）。 */
-        afterDelete?: (orgId: string) => Promise<void>;
-    });
+    private readonly orgLock;
+    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">, 
+    /** 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">);
     /**
-     * 建组织，创建者为 owner。传入 `opts.trx` 时在调用方的事务内执行（初始化向导与建账号同一事务）；
-     * 此时 slug 冲突同样转成 `org.slug_taken`，但该事务已中止，调用方只能回滚。
+     * 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
+     * a caller's transaction is then aborted and can only roll back.
      */
     create(input: {
         name: string;
         slug?: string | undefined;
     }, actor: Account, opts?: {
-        trx?: Trx | undefined;
         actorTokenId?: string | undefined;
     }): Promise<Org>;
+    private createIn;
     /** 账号所属的（未软删除的）组织及其角色，按创建时间升序。 */
     listForAccount(accountId: string): Promise<(Org & {
         role: OrgRole;
     })[]>;
-    /** 全部（未软删除的）组织及成员数（企业管理员用）。 */
+    /** 全部（未软删除的）组织及成员数（超级管理员用）。 */
     listAll(): Promise<(Org & {
         memberCount: number;
     })[]>;
     /** 未软删除的组织；不存在或已软删除为 undefined。 */
     get(orgId: string): Promise<Org | undefined>;
-    /** 改名 / slug（需 admin，锁内实时判定）。 */
+    /** Renames / re-slugs (needs admin, decided live under the org lock). */
     update(orgId: string, patch: {
         name?: string | undefined;
         slug?: string | undefined;
-    }, actor: Account, actorTokenId?: string): Promise<Org>;
+    }, actor: Account, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<Org>;
+    private updateIn;
     /**
-     * 软删除（需 owner，锁内实时判定）：同一事务吊销该组织的服务令牌、取消在执行的评测运行与挂着的目录申请、清空指向它的
-     * 会话当前组织；
-     * 提交后调用 `afterDelete`（渠道连接随组织失效：运行时读连接行时 join 组织过滤已删除的）。
+     * 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, 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;
 }
-export {};

package/dist/orgs/orgs.service.js

@@ -1,10 +1,29 @@
+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 { 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 { cancelEvalRuns } from "../evals/budget.js";
+import { EvalBudget } from "../evals/budget.js";
+import { ApiTokenService } from "../identity/api-tokens.js";
 import { audit } from "../identity/audit.js";
-import { lockOrgAndAuthorize } from "./org-lock.js";
+import { SettingsService } from "../identity/settings.js";
+import { afterCommit } from "../infra/database/after-commit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OrgLock } from "./org-lock.js";
 /** 组织 slug：小写字母数字与 `-`，首尾不能是 `-`，1–40 个字符。 */
 export const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
 const MAX_SLUG = 40;
@@ -52,53 +71,74 @@ async function slugGuard(p) {
         throw e;
     }
 }
-/** 组织服务：创建、查询、修改与软删除。框架无关，由调用方注入依赖。 */
-export class OrgsService {
+/**
+ * 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;
+    txHost;
     settings;
     apiTokens;
-    hooks;
-    constructor(db, settings, apiTokens, hooks = {}) {
+    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, 
+    /** 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;
         this.apiTokens = apiTokens;
-        this.hooks = hooks;
+        this.orgLock = orgLock;
+        this.events = events;
+        this.evalBudget = evalBudget;
+        this.scopeSync = scopeSync;
+        this.ownedItems = ownedItems;
     }
     /**
-     * 建组织，创建者为 owner。传入 `opts.trx` 时在调用方的事务内执行（初始化向导与建账号同一事务）；
-     * 此时 slug 冲突同样转成 `org.slug_taken`，但该事务已中止，调用方只能回滚。
+     * 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
+     * a caller's transaction is then aborted and can only roll back.
      */
     async create(input, actor, opts = {}) {
-        const { trx, actorTokenId } = opts;
-        // 在调用方事务内读设置：调用方已占着一个连接时再向池要第二个，并发下可能把池耗尽
-        const { orgCreation } = await this.settings.get(trx);
-        if (orgCreation === "enterprise_admin" && !actor.isEnterpriseAdmin) {
-            throw new ApiError("org.creation_disabled", "Only enterprise admins can create organizations");
+        return slugGuard(this.createIn(input, actor, opts.actorTokenId));
+    }
+    async createIn(input, actor, actorTokenId) {
+        // 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 === "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);
         checkSlug(slug);
-        const run = async (t) => {
-            const row = await t
-                .insertInto("orgs")
-                .values({ id: randomUUID(), slug, name, created_by: actor.id })
-                .returning(["id", "slug", "name", "created_at"])
-                .executeTakeFirstOrThrow();
-            await t
-                .insertInto("memberships")
-                .values({ org_id: row.id, account_id: actor.id, role: "owner" })
-                .execute();
-            await audit(t, {
-                actorAccountId: actor.id,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId: row.id,
-                action: "org.created",
-                target: row.id,
-                detail: { slug, name },
-            });
-            return toOrg(row);
-        };
-        return slugGuard(trx ? run(trx) : this.db.transaction().execute(run));
+        const row = await this.db
+            .insertInto("orgs")
+            .values({ id: randomUUID(), slug, name, created_by: actor.id })
+            .returning(["id", "slug", "name", "created_at"])
+            .executeTakeFirstOrThrow();
+        await this.db
+            .insertInto("memberships")
+            .values({ org_id: row.id, account_id: actor.id, role: "owner" })
+            .execute();
+        await audit(this.db.db, {
+            actorAccountId: actor.id,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId: row.id,
+            action: "org.created",
+            target: row.id,
+            detail: { slug, name },
+        });
+        afterCommit(() => this.scopeSync.enqueueOrg(row.id));
+        return toOrg(row);
     }
     /** 账号所属的（未软删除的）组织及其角色，按创建时间升序。 */
     async listForAccount(accountId) {
@@ -113,7 +153,7 @@ export class OrgsService {
             .execute();
         return rows.map((r) => ({ ...toOrg(r), role: r.role }));
     }
-    /** 全部（未软删除的）组织及成员数（企业管理员用）。 */
+    /** 全部（未软删除的）组织及成员数（超级管理员用）。 */
     async listAll() {
         const rows = await this.db
             .selectFrom("orgs")
@@ -137,8 +177,10 @@ export class OrgsService {
             .executeTakeFirst();
         return row && toOrg(row);
     }
-    /** 改名 / slug（需 admin，锁内实时判定）。 */
-    async update(orgId, patch, actor, actorTokenId) {
+    /** Renames / re-slugs (needs admin, decided live under the org lock). */
+    async update(orgId, patch, actor, actorTokenId, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail) {
         const values = {};
         if (patch.name !== undefined)
             values.name = checkName(patch.name);
@@ -146,64 +188,97 @@ export class OrgsService {
             checkSlug(patch.slug);
             values.slug = patch.slug;
         }
-        return slugGuard(this.db.transaction().execute(async (trx) => {
-            const { org: before } = await lockOrgAndAuthorize(trx, orgId, actor.id, "org.update");
-            if (Object.keys(values).length === 0) {
-                const row = await trx
-                    .selectFrom("orgs")
-                    .select(["id", "slug", "name", "created_at"])
-                    .where("id", "=", orgId)
-                    .executeTakeFirstOrThrow();
-                return toOrg(row);
-            }
-            const row = await trx
-                .updateTable("orgs")
-                .set(values)
+        return slugGuard(this.updateIn(orgId, values, actor, actorTokenId, auditDetail));
+    }
+    async updateIn(orgId, values, actor, actorTokenId, auditDetail) {
+        const { org: before } = await this.orgLock.lockAndAuthorize(orgId, actor.id, "org.update");
+        if (Object.keys(values).length === 0) {
+            const row = await this.db
+                .selectFrom("orgs")
+                .select(["id", "slug", "name", "created_at"])
                 .where("id", "=", orgId)
-                .returning(["id", "slug", "name", "created_at"])
                 .executeTakeFirstOrThrow();
-            await audit(trx, {
-                actorAccountId: actor.id,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "org.updated",
-                target: orgId,
-                detail: { before, after: values },
-            });
             return toOrg(row);
-        }));
+        }
+        const row = await this.db
+            .updateTable("orgs")
+            .set(values)
+            .where("id", "=", orgId)
+            .returning(["id", "slug", "name", "created_at"])
+            .executeTakeFirstOrThrow();
+        await audit(this.db.db, {
+            actorAccountId: actor.id,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "org.updated",
+            target: orgId,
+            detail: { before, after: values, ...auditDetail },
+        });
+        return toOrg(row);
     }
     /**
-     * 软删除（需 owner，锁内实时判定）：同一事务吊销该组织的服务令牌、取消在执行的评测运行与挂着的目录申请、清空指向它的
-     * 会话当前组织；
-     * 提交后调用 `afterDelete`（渠道连接随组织失效：运行时读连接行时 join 组织过滤已删除的）。
+     * 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, 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.db.transaction().execute(async (trx) => {
-            await lockOrgAndAuthorize(trx, orgId, actor.id, "org.delete");
-            await trx
-                .updateTable("orgs")
-                .set({ deleted_at: sql `now()` })
-                .where("id", "=", orgId)
-                .execute();
-            await this.apiTokens.revokeAllForOrg(orgId, trx);
-            // 组织删除后评测运行不再花钱：显式取消（审计带原因）
-            await cancelEvalRuns(trx, { orgId }, { accountId: actor.id, ...(actorTokenId !== undefined && { tokenId: actorTokenId }) }, "org_deleted");
-            // 挂着的目录申请（含已交企业管理员的）一并取消
-            await cancelPendingRequests(trx, { orgId }, actor.id, "org_deleted", actorTokenId !== undefined ? { actorTokenId } : {});
-            await trx
-                .updateTable("sessions")
-                .set({ current_org_id: null })
-                .where("current_org_id", "=", orgId)
-                .execute();
-            await audit(trx, {
-                actorAccountId: actor.id,
-                ...(actorTokenId !== undefined && { actorTokenId }),
-                orgId,
-                action: "org.deleted",
-                target: orgId,
-            });
+        await this.softDeleteIn(orgId, actor, actorTokenId);
+    }
+    async softDeleteIn(orgId, actor, actorTokenId) {
+        await this.orgLock.lockAndAuthorize(orgId, actor.id, "org.delete");
+        await this.db
+            .updateTable("orgs")
+            .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 super admins) are cancelled too
+        await cancelPendingRequests(this.db.db, { orgId }, actor.id, "org_deleted", actorTokenId !== undefined ? { actorTokenId } : {});
+        await this.db
+            .updateTable("sessions")
+            .set({ current_org_id: null })
+            .where("current_org_id", "=", orgId)
+            .execute();
+        await audit(this.db.db, {
+            actorAccountId: actor.id,
+            ...(actorTokenId !== undefined && { actorTokenId }),
+            orgId,
+            action: "org.deleted",
+            target: orgId,
         });
-        await this.hooks.afterDelete?.(orgId);
+        // channel connections follow the org after the root commit (none after a rollback)
+        afterCommit(() => this.events.emit("org.deleted", { orgId }));
     }
-}
+};
+__decorate([
+    Transactional()
+], OrgsService.prototype, "createIn", null);
+__decorate([
+    Transactional()
+], OrgsService.prototype, "updateIn", null);
+__decorate([
+    Transactional()
+], OrgsService.prototype, "softDeleteIn", null);
+OrgsService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(SettingsService)),
+    __param(3, Inject(ApiTokenService)),
+    __param(4, Inject(OrgLock)),
+    __param(5, Inject(KernelEvents)),
+    __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

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

package/dist/orgs/settings.controller.js

@@ -7,12 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { Body, Controller, Get, Inject, Patch } from "@nestjs/common";
-import { ORG_SETTINGS } from "../http/tokens.js";
-import { ZodPipe } from "../http/zod.pipe.js";
+import { Controller, Get, Inject, Patch } from "@nestjs/common";
 import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "./org.guard.js";
-import { OrgSettingsPatchSchema, } from "./settings.service.js";
+import { OrgSettingsPatchSchema, OrgSettingsService, } from "./settings.service.js";
+class OrgSettingsPatchBody extends createZodDto(OrgSettingsPatchSchema, "OrgSettingsPatch") {
+}
 let OrgSettingsController = class OrgSettingsController {
     settings;
     constructor(settings) {
@@ -44,10 +46,10 @@ __decorate([
     OrgAction("org.update"),
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
-    __param(2, Body(new ZodPipe(OrgSettingsPatchSchema)))
+    __param(2, ZBody(OrgSettingsPatchBody))
 ], OrgSettingsController.prototype, "update", null);
 OrgSettingsController = __decorate([
     Controller("api/v1/orgs/:orgId/settings"),
-    __param(0, Inject(ORG_SETTINGS))
+    __param(0, Inject(OrgSettingsService))
 ], OrgSettingsController);
 export { OrgSettingsController };

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

@@ -1,16 +1,24 @@
 import { type SandboxLimits } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { OrgLock } from "./org-lock.js";
 /**
  * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
  * （更新时与存量合并），新版本加字段不需要迁移。
- * - `toolSearch`：工具超过阈值时是否改用目录 + `tool_search`（D11，默认 on）。
+ * - `toolSearch`：工具超过阈值时是否改用目录 + `ToolSearch`（D11，默认 on）。
  * - `locale`：组织默认语言（`zh` / `en`，默认 en），机器人在 IM 里说的固定话术按它选择。
  * - `sandboxToolPolicy`：沙箱工具的默认策略（M5 T8，默认 allow）。为 `ask` 时除只读的
- *   `sandbox_read` / `sandbox_glob` / `sandbox_grep` 外都需要审批（执行时实时读取）。
+ *   `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`).
+ * - `timeZone`: the org's default time zone (IANA; absent = UTC) for senders without one of their
+ *   own (run context spec §3.3); an invalid stored value reads as absent.
  */
 /** 组织沙箱出站白名单的主机数上限。 */
 export declare const ORG_SANDBOX_ALLOW_HOSTS_MAX = 200;
@@ -39,6 +47,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";
@@ -46,6 +59,8 @@ export declare const OrgSettingsSchema: z.ZodObject<{
         }>;
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
+    wakeOnBackgroundTask: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
+    timeZone: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -62,6 +77,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";
@@ -69,6 +90,7 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
         }>;
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
+    timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
 export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
 /** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */
@@ -78,15 +100,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;
@@ -102,19 +126,26 @@ export interface OrgSettingsDeployment {
 /** 把存储的 jsonb 解析为设置（宽松，见 {@link OrgSettingsSchema}）。 */
 export declare function parseOrgSettings(raw: unknown): OrgSettings;
 /** 读组织设置（每次实时读 PG，多副本下改动立即生效）；组织不存在或已删除按默认值。 */
-export declare function readOrgSettings(db: KernelDb, orgId: string): Promise<OrgSettings>;
+export declare function readOrgSettings(db: KernelSchemaDb, orgId: string): Promise<OrgSettings>;
 /** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
 export declare class OrgSettingsService {
     private readonly db;
-    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
-    private readonly config?;
-    constructor(db: KernelDb, 
-    /** 部署配置（校验 `sandboxEgress` 不超出部署）；省略视为部署出站 `allowlist` + 空白名单。 */
-    config?: (() => Pick<KernelConfig, "sandbox">) | undefined);
+    readonly txHost: TransactionHost;
+    private readonly orgLock;
+    /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
+    private readonly config;
+    constructor(db: KernelDb, txHost: TransactionHost, orgLock: OrgLock, 
+    /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
+    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>;
+    /** The refusals of {@link update} that need no read of the org (the Platform tool's precheck). */
+    check(patch: OrgSettingsPatch): void;
+    update(orgId: string, patch: OrgSettingsPatch, actorAccountId: string, actorTokenId?: string, 
+    /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
+    auditDetail?: Record<string, unknown>): Promise<OrgSettings>;
+    private updateIn;
 }