@capybara-hq/kernel 0.1.0-rc.21 → 0.1.0-rc.23

package/dist/local-devices/policy-summary.js

@@ -0,0 +1,63 @@
+import { isSandboxTier, } from "@capybara-hq/plugin-sdk";
+const KNOWN_FEATURES = ["networkReport", "policyOp", "tiers"];
+/**
+ * The known features in `v` (a hello's `features` or the stored column), in a fixed order and
+ * deduped; anything else (unknown names, a non-array) is dropped.
+ */
+export function deviceFeaturesOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return KNOWN_FEATURES.filter((f) => v.includes(f));
+}
+/**
+ * `v` as a local policy summary (network ask-to-allow spec §5.4), or null when it is absent or not
+ * a valid one. The device is the authority on its policy: the kernel only keeps what it last said,
+ * for the device page and to pick a card's options, never to decide what a command may reach.
+ */
+export function localPolicyOf(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return null;
+    const o = v;
+    if (o.tier !== undefined && !isSandboxTier(o.tier))
+        return null;
+    if (!isSandboxTier(o.effectiveTier))
+        return null;
+    if (o.isolation !== "sandbox" && o.isolation !== "none")
+        return null;
+    if (o.localhost !== "on" && o.localhost !== "off-proxy-detected" && o.localhost !== "off") {
+        return null;
+    }
+    if (o.unixSockets !== "roots" && o.unixSockets !== "all-masked" && o.unixSockets !== "off") {
+        return null;
+    }
+    if (o.remoteGrants !== "owner" && o.remoteGrants !== "off")
+        return null;
+    if (!Array.isArray(o.allowedDomains))
+        return null;
+    if (!o.allowedDomains.every((d) => typeof d === "string"))
+        return null;
+    return {
+        ...(o.tier !== undefined && { tier: o.tier }),
+        effectiveTier: o.effectiveTier,
+        isolation: o.isolation,
+        localhost: o.localhost,
+        unixSockets: o.unixSockets,
+        allowedDomains: [...o.allowedDomains],
+        remoteGrants: o.remoteGrants,
+    };
+}
+/**
+ * The isolation a policy summary states, read from its `isolation` field alone (a hello's raw
+ * `policy` or the stored column), so a summary the kernel cannot otherwise read (a newer program's
+ * new value elsewhere, a broken one) still tells whether commands run without a sandbox: `sandbox`
+ * only when it says exactly that, `none` for any other present summary (fail closed), null when
+ * there is none.
+ */
+export function isolationOf(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v === "object" && !Array.isArray(v)) {
+        return v.isolation === "sandbox" ? "sandbox" : "none";
+    }
+    return "none";
+}

package/dist/orgs/orgs.module.js

@@ -21,7 +21,7 @@ import { MembersService } from "./members.service.js";
 import { Offboarding } from "./offboarding.js";
 import { OrgLockModule } from "./org-lock.js";
 import { OrgsService } from "./orgs.service.js";
-import { OrgSettingsService } from "./settings.service.js";
+import { OrgSettingsModule } from "./settings.service.js";
 /**
  * Organizations: orgs, org settings, members, invitations, offboarding (with its sweep cron) and
  * directory sync (the hourly scan cron, one-off syncs on the maintenance queue).
@@ -35,6 +35,7 @@ OrgsModule = __decorate([
             // offboarding publishes the events it cancelled
             EventLogModule,
             OrgLockModule,
+            OrgSettingsModule,
             ExtensionsModule,
             // offboarding clears credentials and cancels approvals and questions
             ToolsModule,
@@ -49,18 +50,11 @@ OrgsModule = __decorate([
             // the producer side of directory-sync jobs (the maintenance processor consumes them)
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
-        providers: [
-            OrgsService,
-            OrgSettingsService,
-            MembersService,
-            InvitationsService,
-            Offboarding,
-            DirectorySync,
-        ],
+        providers: [OrgsService, MembersService, InvitationsService, Offboarding, DirectorySync],
         exports: [
             OrgLockModule,
+            OrgSettingsModule,
             OrgsService,
-            OrgSettingsService,
             MembersService,
             InvitationsService,
             Offboarding,

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.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 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" | "schedules.use" | "schedules.manage";
 /** 每个动作所需的最低角色。 */
 export declare const ACTION_MIN_ROLE: Record<OrgAction, OrgRole>;
 /** 只允许 user principal 执行的动作：服务令牌即使角色足够也拒绝（除 SERVICE_ALLOWED 外全部）。 */

package/dist/orgs/roles.js

@@ -47,6 +47,10 @@ export const ACTION_MIN_ROLE = {
     "catalog.decide": "admin",
     // An org admin uploads a plugin package the org owns (spec §14.1 item 1, ruling P3-7)
     "catalog.upload": "admin",
+    // Scheduled tasks (spec 2026-11-11 §10): create, edit, pause, resume, run and delete one's own
+    "schedules.use": "member",
+    // list every task of the org, pause, resume and delete any (never edit another person's)
+    "schedules.manage": "admin",
 };
 /** 服务令牌也可执行的动作：只读的 org.read、org.members.read，以及使用 agent 的 agents.use。 */
 const SERVICE_ALLOWED = new Set([

package/dist/orgs/settings.controller.js

@@ -23,15 +23,16 @@ let OrgSettingsController = class OrgSettingsController {
     async get(org) {
         return {
             settings: await this.settings.get(org.orgId),
-            deployment: this.settings.deployment(),
+            deployment: await this.settings.deployment(),
             sandboxLimits: await this.settings.sandboxLimits(org.orgId),
         };
     }
     async update(principal, org, body) {
         const p = requireUser(principal);
         return {
-            settings: await this.settings.update(org.orgId, body, p.account.id, patTokenId(p)),
-            deployment: this.settings.deployment(),
+            // an API token may narrow the sandbox, never widen it (sandbox dev tiers spec §2)
+            settings: await this.settings.update(org.orgId, body, p.account.id, patTokenId(p), undefined, { onlyNarrows: patTokenId(p) !== undefined }),
+            deployment: await this.settings.deployment(),
             sandboxLimits: await this.settings.sandboxLimits(org.orgId),
         };
     }

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

@@ -1,9 +1,12 @@
-import { type SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { type SandboxLimits, type SandboxTier } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
 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 type { KernelLogger } from "../log.js";
+import { type PlatformTiers } from "../sandbox/platform-tiers.js";
+import { type EffectiveSandboxPolicy } from "../sandbox/tiers.js";
 import { OrgLock } from "./org-lock.js";
 /**
  * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
@@ -14,7 +17,10 @@ import { OrgLock } from "./org-lock.js";
  *   `Read` / `Glob` / `Grep` 外都需要审批（执行时实时读取）。
  * - `wakeOnBackgroundTask`：组织对 `runtime.wakeOnBackgroundTask` 的覆盖（缺省跟随部署），见 {@link effectiveWakeOnBackgroundTask}。
  * - `sandboxEgress`：组织的沙箱出站（Ruling M19 / D6），缺省跟随部署的 `sandbox.limits.egress` + `allowHosts`。
- *   见 {@link effectiveSandboxEgress}。存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ *   See `baseSandboxEgress` (sandbox/tiers.ts). 存量值非法时按 `none` 读（宁可断网，不悄悄放宽到部署默认）。
+ * - `sandboxTier`: the org's sandbox tier ceiling, default and unsandboxed switch (sandbox dev tiers
+ *   spec §4.1), each absent = follow the platform (`sandbox.tiers`); never above the platform. An
+ *   invalid stored value reads as `{ max: "strict" }` (narrower, never wider).
  * - `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
@@ -38,6 +44,25 @@ export declare const SandboxEgressSettingSchema: z.ZodObject<{
     allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export type SandboxEgressSetting = z.infer<typeof SandboxEgressSettingSchema>;
+/**
+ * The org's sandbox tier setting (sandbox dev tiers spec §4.1): `max` the highest tier its devices
+ * may reach, `default` the tier of a device that chose none, `allowUnsandboxed` false forbids
+ * unsandboxed local devices. Each absent = follow the platform's `sandbox.tiers`.
+ */
+export declare const SandboxTierSettingSchema: z.ZodObject<{
+    max: z.ZodOptional<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>;
+    default: z.ZodOptional<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>;
+    allowUnsandboxed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type SandboxTierSetting = z.infer<typeof SandboxTierSettingSchema>;
 /**
  * The org's theme setting (themes spec §7): `id` a theme on in the org (a `platform_themes` id),
  * null = follow the platform's default; `personal: "locked"` hides the personal picker in the org
@@ -53,6 +78,45 @@ export declare const OrgThemeSettingSchema: z.ZodObject<{
 export type OrgThemeSetting = z.infer<typeof OrgThemeSettingSchema>;
 /** The theme setting of an org that has none: follow the platform, personal picks allowed. */
 export declare const DEFAULT_ORG_THEME: OrgThemeSetting;
+/**
+ * Org settings of scheduled tasks (spec §9); every field reads leniently (invalid = default,
+ * except `forbiddenTools`, which keeps its valid entries).
+ */
+export declare const ScheduledTasksSettingsSchema: z.ZodObject<{
+    enabled: z.ZodCatch<z.ZodDefault<z.ZodBoolean>>;
+    minIntervalMinutes: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    maxTasksPerMember: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    maxTasksPerOrg: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    maxRunsPerHour: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    defaultExpiryDays: z.ZodCatch<z.ZodDefault<z.ZodNullable<z.ZodNumber>>>;
+    catchUpWindowMinutes: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    unattendedAsk: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+        fail: "fail";
+        wait: "wait";
+    }>>>;
+    pauseAfterFailures: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+    forbiddenTools: z.ZodCatch<z.ZodPreprocess<z.ZodDefault<z.ZodArray<z.ZodString>>, unknown>>;
+}, z.core.$strip>;
+export type ScheduledTasksSettings = z.infer<typeof ScheduledTasksSettingsSchema>;
+/**
+ * The PATCH form: a partial merge into the group (fields left out keep their stored value; see
+ * `OrgSettingsService.update`). A field given replaces that field whole, `forbiddenTools` too.
+ */
+export declare const ScheduledTasksPatchSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    minIntervalMinutes: z.ZodOptional<z.ZodNumber>;
+    maxTasksPerMember: z.ZodOptional<z.ZodNumber>;
+    maxTasksPerOrg: z.ZodOptional<z.ZodNumber>;
+    maxRunsPerHour: z.ZodOptional<z.ZodNumber>;
+    defaultExpiryDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    catchUpWindowMinutes: z.ZodOptional<z.ZodNumber>;
+    unattendedAsk: z.ZodOptional<z.ZodEnum<{
+        fail: "fail";
+        wait: "wait";
+    }>>;
+    pauseAfterFailures: z.ZodOptional<z.ZodNumber>;
+    forbiddenTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
 export declare const OrgSettingsSchema: z.ZodObject<{
     toolSearch: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
         off: "off";
@@ -78,6 +142,19 @@ export declare const OrgSettingsSchema: z.ZodObject<{
         }>;
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
+    sandboxTier: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        max: z.ZodOptional<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>;
+        default: z.ZodOptional<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>;
+        allowUnsandboxed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
     wakeOnBackgroundTask: z.ZodCatch<z.ZodOptional<z.ZodBoolean>>;
     timeZone: z.ZodCatch<z.ZodOptional<z.ZodString>>;
     theme: z.ZodCatch<z.ZodOptional<z.ZodObject<{
@@ -88,6 +165,21 @@ export declare const OrgSettingsSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>>>;
     uiArrangement: z.ZodCatch<z.ZodOptional<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry>>, unknown>>>>;
+    scheduledTasks: z.ZodCatch<z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodCatch<z.ZodDefault<z.ZodBoolean>>;
+        minIntervalMinutes: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+        maxTasksPerMember: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+        maxTasksPerOrg: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+        maxRunsPerHour: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+        defaultExpiryDays: z.ZodCatch<z.ZodDefault<z.ZodNullable<z.ZodNumber>>>;
+        catchUpWindowMinutes: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+        unattendedAsk: z.ZodCatch<z.ZodDefault<z.ZodEnum<{
+            fail: "fail";
+            wait: "wait";
+        }>>>;
+        pauseAfterFailures: z.ZodCatch<z.ZodDefault<z.ZodNumber>>;
+        forbiddenTools: z.ZodCatch<z.ZodPreprocess<z.ZodDefault<z.ZodArray<z.ZodString>>, unknown>>;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type OrgSettings = z.infer<typeof OrgSettingsSchema>;
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
@@ -117,6 +209,19 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
         }>;
         allowHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>>;
+    sandboxTier: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        max: z.ZodOptional<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>;
+        default: z.ZodOptional<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>;
+        allowUnsandboxed: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
     timeZone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     theme: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         id: z.ZodNullable<z.ZodString>;
@@ -126,15 +231,23 @@ export declare const OrgSettingsPatchSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>>>;
     uiArrangement: z.ZodOptional<z.ZodType<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown, z.core.$ZodTypeInternals<Partial<Record<"agent.detail.section" | "conversation.composer.frame" | "conversation.empty" | "conversation.panel" | "conversation.properties.section" | "conversation.tool-result.card" | "file.preview" | "org.page" | "org.settings.section" | "platform.page" | "shell.brand" | "shell.overlay", import("../ui/arrangement.js").UiArrangementEntry | null>>, unknown>>>;
+    scheduledTasks: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodOptional<z.ZodBoolean>;
+        minIntervalMinutes: z.ZodOptional<z.ZodNumber>;
+        maxTasksPerMember: z.ZodOptional<z.ZodNumber>;
+        maxTasksPerOrg: z.ZodOptional<z.ZodNumber>;
+        maxRunsPerHour: z.ZodOptional<z.ZodNumber>;
+        defaultExpiryDays: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        catchUpWindowMinutes: z.ZodOptional<z.ZodNumber>;
+        unattendedAsk: z.ZodOptional<z.ZodEnum<{
+            fail: "fail";
+            wait: "wait";
+        }>>;
+        pauseAfterFailures: z.ZodOptional<z.ZodNumber>;
+        forbiddenTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type OrgSettingsPatch = z.infer<typeof OrgSettingsPatchSchema>;
-/** 部署的沙箱出站（`sandbox.limits.egress` + `allowHosts`）。 */
-export type DeploymentEgress = Pick<SandboxLimits, "egress" | "allowHosts">;
-/**
- * 组织实际生效的沙箱出站：没有组织设置 → 部署默认；`none` → 只有回环；`allowlist` → 组织的白名单
- * （省略时用部署的），但部署是 `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;
 /**
@@ -154,14 +267,23 @@ export interface OrgSandboxLimits {
 /** 设置页展示用的部署默认值（`GET` 一并返回）。 */
 export interface OrgSettingsDeployment {
     sandboxEgress: {
-        mode: SandboxLimits["egress"];
+        mode: "none" | "allowlist";
         allowHosts: string[];
     };
+    /** The platform's tiers (`sandbox.tiers`) and the dev hosts the dev tier adds. */
+    sandboxTiers: {
+        max: SandboxTier;
+        default: SandboxTier;
+        allowUnsandboxed: boolean;
+        devHosts: string[];
+    };
 }
 /** 把存储的 jsonb 解析为设置（宽松，见 {@link OrgSettingsSchema}）。 */
 export declare function parseOrgSettings(raw: unknown): OrgSettings;
 /** 读组织设置（每次实时读 PG，多副本下改动立即生效）；组织不存在或已删除按默认值。 */
 export declare function readOrgSettings(db: KernelSchemaDb, orgId: string): Promise<OrgSettings>;
+/** Whether a stored settings object holds a `sandboxTier` this version reads as `{ max: "strict" }`. */
+export declare function invalidStoredSandboxTier(raw: unknown): boolean;
 /** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
 export declare class OrgSettingsService {
     private readonly db;
@@ -169,18 +291,54 @@ export declare class OrgSettingsService {
     private readonly orgLock;
     /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
     private readonly config;
+    private readonly log?;
     constructor(db: KernelDb, txHost: TransactionHost, orgLock: OrgLock, 
     /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
-    config: Pick<KernelConfigService, "get">);
+    config: Pick<KernelConfigService, "get">, log?: KernelLogger | undefined);
+    /** Parses stored settings, warning when an invalid `sandboxTier` narrows to `{ max: "strict" }`. */
+    private parseStored;
+    /** The platform's effective sandbox tiers (the startup config over the admin console's choice). */
+    platformTiers(): Promise<PlatformTiers>;
     /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
-    deployment(): OrgSettingsDeployment;
+    deployment(): Promise<OrgSettingsDeployment>;
     /** 组织实际生效的沙箱 cpu / 内存（只读；由超级管理员在部署设置里覆盖）。 */
     sandboxLimits(orgId: string): Promise<OrgSandboxLimits>;
     get(orgId: string): Promise<OrgSettings>;
     /** The refusals of {@link update} that need no read of the org (the Platform tool's precheck). */
-    check(patch: OrgSettingsPatch): void;
+    check(patch: OrgSettingsPatch): Promise<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>;
+    auditDetail?: Record<string, unknown>, 
+    /**
+     * `onlyNarrows` (the Platform tool, API tokens): refuse a `sandboxTier` or `sandboxEgress`
+     * change that widens (see {@link assertOnlyNarrows}); only a person in a session widens.
+     */
+    opts?: {
+        onlyNarrows?: boolean;
+    }): Promise<OrgSettings>;
+    /**
+     * The effective sandbox policy for the org's settings and a device's own tier (null = none);
+     * `tiers`: the platform's tiers when the caller already read them.
+     */
+    sandboxPolicy(settings: OrgSettings, deviceTier: SandboxTier | null, tiers?: PlatformTiers): Promise<EffectiveSandboxPolicy>;
+    /**
+     * Refuses a patch that widens the org's sandbox (sandbox dev tiers spec §2, §7.2: only a person
+     * widens it, never the Platform tool or an API token):
+     * - `sandboxTier`: the effective ceiling, default or unsandboxed switch rises, or a stored cap
+     *   loosens (an absent `max` / `default` follows the platform, so it ranks above every tier and
+     *   clearing a cap that equals today's platform value is a widening; an explicit
+     *   `allowUnsandboxed: false` stays false). A cleared `default` under a new `max` no higher than
+     *   the old default is no loosening: the default never exceeds the ceiling. The value is
+     *   replaced whole, so the refusal names the fields the patch would clear;
+     * - `sandboxEgress`: the base list grows: from none to anything else, or to hosts (the
+     *   deployment's when the org gives none) not all in the current list.
+     */
+    assertOnlyNarrows(before: OrgSettings, patch: OrgSettingsPatch): Promise<void>;
     private updateIn;
 }
+/**
+ * The one {@link OrgSettingsService}: the orgs module re-exports it, and the catalog imports it
+ * directly (approving a network request writes `sandboxEgress`) without a cycle through OrgsModule.
+ */
+export declare class OrgSettingsModule {
+}