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

package/dist/orgs/settings.service.js

@@ -7,8 +7,8 @@ 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 { validateAllowHost } from "@capybara-hq/plugin-sdk";
-import { Inject, Injectable } from "@nestjs/common";
+import { SANDBOX_TIERS, tierAtMost, validateAllowHost, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable, Module, Optional } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
@@ -17,10 +17,13 @@ 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 { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { readPlatformTiers } from "../sandbox/platform-tiers.js";
+import { effectiveSandboxPolicy } from "../sandbox/tiers.js";
 import { assertThemeOnIn } from "../themes/theme-state.js";
 import { IanaTimeZone } from "../time-zone.js";
 import { mergeArrangement, OrgUiArrangementPatchSchema, UiArrangementSchema, } from "../ui/arrangement.js";
-import { OrgLock } from "./org-lock.js";
+import { OrgLock, OrgLockModule } from "./org-lock.js";
 /**
  * 组织设置（`capybara.orgs.settings` jsonb）。读取宽松：缺失或非法的字段按默认值，未知键保留不动
  * （更新时与存量合并），新版本加字段不需要迁移。
@@ -30,7 +33,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
@@ -65,6 +71,19 @@ export const SandboxEgressSettingSchema = z
         .optional(),
 })
     .strict();
+const TierSchema = z.enum(["strict", "dev", "open"]);
+/**
+ * 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 const SandboxTierSettingSchema = z
+    .object({
+    max: TierSchema.optional(),
+    default: TierSchema.optional(),
+    allowUnsandboxed: z.boolean().optional(),
+})
+    .strict();
 /**
  * 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
@@ -78,12 +97,56 @@ export const OrgThemeSettingSchema = z
     .strict();
 /** The theme setting of an org that has none: follow the platform, personal picks allowed. */
 export const DEFAULT_ORG_THEME = { id: null, personal: "allowed" };
+const posInt = (max, def) => z.number().int().min(1).max(max).default(def).catch(def);
+/** A stored `forbiddenTools` entry worth keeping: a tool key of the length the PATCH accepts. */
+const isForbiddenToolEntry = (v) => typeof v === "string" && v.length >= 1 && v.length <= 200;
+/**
+ * Org settings of scheduled tasks (spec §9); every field reads leniently (invalid = default,
+ * except `forbiddenTools`, which keeps its valid entries).
+ */
+export const ScheduledTasksSettingsSchema = z.object({
+    enabled: z.boolean().default(true).catch(true),
+    minIntervalMinutes: posInt(1_000_000, 60),
+    maxTasksPerMember: posInt(1_000_000, 20),
+    maxTasksPerOrg: posInt(1_000_000, 200),
+    maxRunsPerHour: posInt(1_000_000, 60),
+    defaultExpiryDays: z.number().int().min(1).max(36_500).nullable().default(null).catch(null),
+    catchUpWindowMinutes: posInt(1_000_000, 60),
+    unattendedAsk: z.enum(["fail", "wait"]).default("fail").catch("fail"),
+    pauseAfterFailures: posInt(1000, 5),
+    // fail-safe: an invalid entry is dropped, the valid ones stay forbidden (never reset to []);
+    // past the PATCH's 500 the list is truncated
+    forbiddenTools: z
+        .preprocess((v) => (Array.isArray(v) ? v.filter(isForbiddenToolEntry).slice(0, 500) : v), z.array(z.string()).max(500).default([]))
+        .catch([]),
+});
+/**
+ * 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 const ScheduledTasksPatchSchema = z
+    .object({
+    enabled: z.boolean(),
+    minIntervalMinutes: z.number().int().min(1).max(1_000_000),
+    maxTasksPerMember: z.number().int().min(1).max(1_000_000),
+    maxTasksPerOrg: z.number().int().min(1).max(1_000_000),
+    maxRunsPerHour: z.number().int().min(1).max(1_000_000),
+    defaultExpiryDays: z.number().int().min(1).max(36_500).nullable(),
+    catchUpWindowMinutes: z.number().int().min(1).max(1_000_000),
+    unattendedAsk: z.enum(["fail", "wait"]),
+    pauseAfterFailures: z.number().int().min(1).max(1000),
+    forbiddenTools: z.array(z.string().min(1).max(200)).max(500),
+})
+    .partial()
+    .strict();
 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" }),
+    /** The org's sandbox tiers (sandbox dev tiers spec §4.1); absent follows the platform. */
+    sandboxTier: SandboxTierSettingSchema.optional().catch({ max: "strict" }),
     /** Overrides `runtime.wakeOnBackgroundTask`; absent follows the deployment. */
     wakeOnBackgroundTask: z.boolean().optional().catch(undefined),
     /** The org's default time zone (run context spec §3.3); absent = UTC. */
@@ -92,6 +155,8 @@ export const OrgSettingsSchema = z.object({
     theme: OrgThemeSettingSchema.optional().catch(undefined),
     /** Hidden and ordered extension contributions per slot; absent = follow the platform. */
     uiArrangement: UiArrangementSchema.optional().catch(undefined),
+    /** Scheduled tasks (spec §9); the platform bounds clamp it, see `effectiveScheduleSettings`. */
+    scheduledTasks: ScheduledTasksSettingsSchema.prefault({}).catch(ScheduledTasksSettingsSchema.parse({})),
 });
 /** PATCH 体：只改给出的字段；未知字段 → 400。 */
 export const OrgSettingsPatchSchema = z
@@ -104,6 +169,11 @@ export const OrgSettingsPatchSchema = z
     wakeOnBackgroundTask: z.boolean().nullable().optional(),
     /** null 清除（恢复跟随部署默认）。 */
     sandboxEgress: SandboxEgressSettingSchema.nullable().optional(),
+    /**
+     * The org's sandbox tiers, replaced whole (fields left out follow the platform); never above
+     * the platform (`org.sandbox_tier_not_allowed`). null clears it.
+     */
+    sandboxTier: SandboxTierSettingSchema.nullable().optional(),
     /** The org's default time zone (IANA); null clears it (UTC). */
     timeZone: IanaTimeZone.nullable().optional(),
     /**
@@ -116,19 +186,10 @@ export const OrgSettingsPatchSchema = z
      * null removes a slot's entry (it follows the platform again). `platform.page` is refused.
      */
     uiArrangement: OrgUiArrangementPatchSchema.optional(),
+    /** Fields to change in the scheduled-tasks group; the rest keep their value. */
+    scheduledTasks: ScheduledTasksPatchSchema.optional(),
 })
     .strict();
-/**
- * 组织实际生效的沙箱出站：没有组织设置 → 部署默认；`none` → 只有回环；`allowlist` → 组织的白名单
- * （省略时用部署的），但部署是 `none` 时仍为 `none`（组织永远不比部署放得更开，部署改成 none 后存量设置也随之收紧）。
- */
-export function effectiveSandboxEgress(deployment, org) {
-    if (org === undefined)
-        return { egress: deployment.egress, allowHosts: [...deployment.allowHosts] };
-    if (org.mode === "none" || deployment.egress === "none")
-        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;
@@ -162,25 +223,55 @@ export async function readOrgSettings(db, orgId) {
         .executeTakeFirst();
     return parseOrgSettings(row?.settings);
 }
+const sandboxTierNotAllowed = (message) => new ApiError("org.sandbox_tier_not_allowed", message);
+/** Whether a stored settings object holds a `sandboxTier` this version reads as `{ max: "strict" }`. */
+export function invalidStoredSandboxTier(raw) {
+    const v = asObject(raw).sandboxTier;
+    return v !== undefined && !SandboxTierSettingSchema.safeParse(v).success;
+}
+/** A setting's tier for intent comparison: absent (follow the platform) ranks above every tier. */
+const intentRank = (t) => t === undefined ? SANDBOX_TIERS.length : SANDBOX_TIERS.indexOf(t);
 /** 组织设置服务：读取与修改（修改需 `org.update`，锁内实时复核角色，写审计）。 */
 let OrgSettingsService = class OrgSettingsService {
     db;
     txHost;
     orgLock;
     config;
+    log;
     constructor(db, txHost, orgLock, 
     /** The deployment config (`sandboxEgress` may not exceed the deployment's). */
-    config) {
+    config, log) {
         this.db = db;
         this.txHost = txHost;
         this.orgLock = orgLock;
         this.config = config;
+        this.log = log;
+    }
+    /** Parses stored settings, warning when an invalid `sandboxTier` narrows to `{ max: "strict" }`. */
+    parseStored(orgId, raw) {
+        if (invalidStoredSandboxTier(raw)) {
+            this.log?.warn("org settings: stored sandboxTier is invalid; it reads as max strict", {
+                orgId,
+            });
+        }
+        return parseOrgSettings(raw);
+    }
+    /** The platform's effective sandbox tiers (the startup config over the admin console's choice). */
+    platformTiers() {
+        return readPlatformTiers(this.db.db, this.config, this.log);
     }
     /** 部署默认值（设置页展示「跟随部署」时的实际取值）。 */
-    deployment() {
+    async deployment() {
         const lim = this.config.get().sandbox.limits;
+        const tiers = await this.platformTiers();
         return {
             sandboxEgress: { mode: lim.egress, allowHosts: [...lim.allowHosts] },
+            sandboxTiers: {
+                max: tiers.max,
+                default: tiers.default,
+                allowUnsandboxed: tiers.allowUnsandboxed,
+                devHosts: [...lim.devHosts],
+            },
         };
     }
     /** 组织实际生效的沙箱 cpu / 内存（只读；由超级管理员在部署设置里覆盖）。 */
@@ -202,22 +293,99 @@ let OrgSettingsService = class OrgSettingsService {
             .executeTakeFirst();
         if (!row)
             throw new ApiError("org.not_found", "Organization not found");
-        return parseOrgSettings(row.settings);
+        return this.parseStored(orgId, row.settings);
     }
     /** The refusals of {@link update} that need no read of the org (the Platform tool's precheck). */
-    check(patch) {
+    async check(patch) {
         if (patch.sandboxEgress?.mode === "allowlist" &&
-            this.deployment().sandboxEgress.mode === "none") {
+            this.config.get().sandbox.limits.egress === "none") {
             throw new ApiError("org.sandbox_egress_not_allowed", "This deployment disables sandbox network access (sandbox.limits.egress is none); an organization can only set sandboxEgress to none");
         }
+        const t = patch.sandboxTier;
+        if (t != null) {
+            const platform = await this.platformTiers();
+            if (t.max !== undefined && !tierAtMost(t.max, platform.max)) {
+                throw sandboxTierNotAllowed(`The platform allows sandbox tiers up to ${platform.max}; sandboxTier.max cannot be ${t.max}`);
+            }
+            const max = t.max ?? platform.max;
+            if (t.default !== undefined && !tierAtMost(t.default, max)) {
+                throw sandboxTierNotAllowed(`sandboxTier.default (${t.default}) cannot be above the organization's highest tier (${max})`);
+            }
+            if (t.allowUnsandboxed === true && !platform.allowUnsandboxed) {
+                throw sandboxTierNotAllowed("The platform does not allow unsandboxed devices (sandbox.tiers.allowUnsandboxed is false); sandboxTier.allowUnsandboxed cannot be true");
+            }
+        }
     }
     async update(orgId, patch, actorAccountId, actorTokenId, 
     /** Merged into the audit detail (the Platform tool's `via: "agent"`). */
-    auditDetail) {
-        this.check(patch);
-        return this.updateIn(orgId, patch, actorAccountId, actorTokenId, auditDetail);
+    auditDetail, 
+    /**
+     * `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) {
+        await this.check(patch);
+        return this.updateIn(orgId, patch, actorAccountId, actorTokenId, auditDetail, opts);
+    }
+    /**
+     * 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.
+     */
+    async sandboxPolicy(settings, deviceTier, tiers) {
+        const deployment = {
+            limits: this.config.get().sandbox.limits,
+            tiers: tiers ?? (await this.platformTiers()),
+        };
+        return effectiveSandboxPolicy(deployment, settings, deviceTier);
+    }
+    /**
+     * 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.
+     */
+    async assertOnlyNarrows(before, patch) {
+        if (patch.sandboxTier !== undefined) {
+            const next = patch.sandboxTier ?? undefined;
+            const prev = before.sandboxTier;
+            const tiers = await this.platformTiers();
+            const b = await this.sandboxPolicy(before, null, tiers);
+            const a = await this.sandboxPolicy({ ...before, sandboxTier: next }, null, tiers);
+            // a cleared default follows the platform, capped by the ceiling: `max` bounds it then
+            const nextDefault = next?.default === undefined && next?.max !== undefined ? next.max : next?.default;
+            if (!tierAtMost(a.ceiling, b.ceiling) ||
+                !tierAtMost(a.defaultTier, b.defaultTier) ||
+                (a.allowUnsandboxed && !b.allowUnsandboxed) ||
+                intentRank(next?.max) > intentRank(prev?.max) ||
+                intentRank(nextDefault) > intentRank(prev?.default) ||
+                (prev?.allowUnsandboxed === false && next?.allowUnsandboxed !== false)) {
+                const cleared = ["max", "default", "allowUnsandboxed"].filter((f) => prev?.[f] !== undefined && next?.[f] === undefined);
+                throw sandboxTierNotAllowed("Raising the sandbox level needs a person in the organization settings." +
+                    (cleared.length === 0
+                        ? ""
+                        : ` sandboxTier is replaced whole: this change clears ${cleared.join(", ")}` +
+                            " (which would then follow the platform); give the values to keep again."));
+            }
+        }
+        if (patch.sandboxEgress !== undefined) {
+            const deploymentHosts = this.config.get().sandbox.limits.allowHosts;
+            const prev = before.sandboxEgress;
+            const next = patch.sandboxEgress ?? undefined;
+            const hostsOf = (e) => e?.allowHosts ?? deploymentHosts;
+            const widens = next?.mode !== "none" &&
+                (prev?.mode === "none" || !hostsOf(next).every((h) => hostsOf(prev).includes(h)));
+            if (widens) {
+                throw new ApiError("org.sandbox_egress_not_allowed", "Widening the sandbox network needs a person in the organization settings.");
+            }
+        }
     }
-    async updateIn(orgId, patch, actorAccountId, actorTokenId, auditDetail) {
+    async updateIn(orgId, patch, actorAccountId, actorTokenId, auditDetail, opts) {
         await this.orgLock.lockAndAuthorize(orgId, actorAccountId, "org.update");
         const row = await this.db
             .selectFrom("orgs")
@@ -225,14 +393,26 @@ let OrgSettingsService = class OrgSettingsService {
             .where("id", "=", orgId)
             .executeTakeFirstOrThrow();
         const stored = asObject(row.settings);
-        const before = parseOrgSettings(stored);
+        const before = this.parseStored(orgId, stored);
+        // again under the org lock: a hot config reload may have lowered the platform since
+        await this.check(patch);
+        // under the org lock, so the comparison is with the value the write replaces
+        if (opts?.onlyNarrows)
+            await this.assertOnlyNarrows(before, patch);
         const changes = Object.fromEntries(Object.entries(patch)
             .filter(([, v]) => v !== undefined)
             // null clears sandboxEgress / wakeOnBackgroundTask: follow the deployment default again
             .map(([k, v]) => [k, v === null ? undefined : v]));
         const arrangementPatch = patch.uiArrangement;
         delete changes.uiArrangement;
+        delete changes.scheduledTasks;
         const after = { ...before, ...changes };
+        if (patch.scheduledTasks !== undefined) {
+            after.scheduledTasks = ScheduledTasksSettingsSchema.parse({
+                ...before.scheduledTasks,
+                ...Object.fromEntries(Object.entries(patch.scheduledTasks).filter(([, v]) => v !== undefined)),
+            });
+        }
         if (arrangementPatch !== undefined) {
             after.uiArrangement = mergeArrangement(before.uiArrangement, arrangementPatch);
             if (Object.keys(after.uiArrangement).length === 0)
@@ -240,6 +420,12 @@ let OrgSettingsService = class OrgSettingsService {
         }
         if (after.sandboxEgress === undefined)
             delete after.sandboxEgress;
+        // an empty sandboxTier is the same as none: follow the platform
+        if (after.sandboxTier !== undefined && Object.keys(after.sandboxTier).length === 0) {
+            delete after.sandboxTier;
+        }
+        if (after.sandboxTier === undefined)
+            delete after.sandboxTier;
         if (after.wakeOnBackgroundTask === undefined)
             delete after.wakeOnBackgroundTask;
         if (after.timeZone === undefined)
@@ -256,7 +442,7 @@ let OrgSettingsService = class OrgSettingsService {
             await assertThemeOnIn(this.db.db, orgId, patch.theme.id);
         }
         // 与存量合并：保留本版本不认识的键（清除的 sandboxEgress 不留在存量里）
-        const { sandboxEgress: _old, wakeOnBackgroundTask: _oldWake, timeZone: _oldZone, theme: _oldTheme, uiArrangement: _oldArrangement, ...rest } = stored;
+        const { sandboxEgress: _old, sandboxTier: _oldTier, wakeOnBackgroundTask: _oldWake, timeZone: _oldZone, theme: _oldTheme, uiArrangement: _oldArrangement, scheduledTasks: _oldScheduled, ...rest } = stored;
         await this.db
             .updateTable("orgs")
             .set({ settings: JSON.stringify({ ...rest, ...after }) })
@@ -281,6 +467,22 @@ OrgSettingsService = __decorate([
     __param(0, Inject(KernelDb)),
     __param(1, Inject(TransactionHost)),
     __param(2, Inject(OrgLock)),
-    __param(3, Inject(KernelConfigService))
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Optional()),
+    __param(4, Inject(KERNEL_LOGGER))
 ], OrgSettingsService);
 export { OrgSettingsService };
+/**
+ * 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.
+ */
+let OrgSettingsModule = class OrgSettingsModule {
+};
+OrgSettingsModule = __decorate([
+    Module({
+        imports: [OrgLockModule],
+        providers: [OrgSettingsService],
+        exports: [OrgSettingsService],
+    })
+], OrgSettingsModule);
+export { OrgSettingsModule };

package/dist/platform/exclusions.js

@@ -153,6 +153,11 @@ export const PLATFORM_EXCLUSIONS = [
         category: "secret",
         reason: "Body carries connector credentials and client secrets entered by a person",
     },
+    {
+        route: "POST /api/v1/orgs/:orgId/catalog-requests/network",
+        category: "human-only",
+        reason: "A member asks org admins to allow a domain from a blocked command's card; agents never file network requests",
+    },
     {
         route: "POST /api/v1/orgs/:orgId/catalog-requests/:id/decide",
         category: "human-only",
@@ -281,6 +286,11 @@ export const PLATFORM_EXCLUSIONS = [
         category: "human-only",
         reason: "Disconnects a person's own machine (revokes its credential); a trust decision taken on the device's page",
     },
+    {
+        route: "POST /api/v1/orgs/:orgId/devices/:id/policy",
+        category: "human-only",
+        reason: "A person changes their own machine's network policy; agents never widen a device's network",
+    },
     {
         route: "POST /api/v1/device/authorize",
         category: "transport",
@@ -560,7 +570,7 @@ export const PLATFORM_EXCLUSIONS = [
     {
         route: "POST /api/v1/orgs/:orgId/approvals/:id/decision",
         category: "human-only",
-        reason: "Decides a tool permission approval; only the person decides (spec §6.4); reading what waits is approvals.waiting / approvals.get",
+        reason: "Decides a tool permission approval or a network ask; only the person decides (spec §6.4); a person must decide network access on their own device; reading what waits is approvals.waiting / approvals.get",
     },
     {
         route: "GET /api/v1/orgs/:orgId/me/tool-grants",

package/dist/platform/operation.js

@@ -87,6 +87,10 @@ export const PLATFORM_DOMAINS = [
         id: "devices",
         description: "Your own cloud devices (the workspaces your conversations run in): list, read, create, rename, delete, wipe the files.",
     },
+    {
+        id: "schedules",
+        description: "Your scheduled tasks (an agent runs a prompt on a schedule, as you, unattended): list, read, create, edit, pause, resume, delete, run now or as a trial, run history, and the tools approved for a task.",
+    },
     {
         id: "setup",
         description: "Plugin setup guides: list the guides you may help with, read one as Markdown, the state of its checks for a channel connection or a connector, and running one check. Entering secrets, connecting an account and confirming the app was updated stay with the person on the web; read the docs topic `setup` first.",

package/dist/platform/ops/admin-items.ops.js

@@ -96,7 +96,7 @@ let AdminItemsOperations = class AdminItemsOperations {
             }),
             defineOperation({
                 id: "admin.agent-get",
-                description: "Read one agent of this org as the admin console shows it (super admin): its definition with the instructions in full, members, profile with quick action labels, versions count, the skills and connectors it uses by name. Never its conversations or credentials.",
+                description: "Read one agent of this org as the admin console shows it (super admin): its definition with the instructions in full, members, profile with quick action labels, versions count, the skills and connectors it has by name, and how many of the org's skills it turns off (skillsOff). Never its conversations or credentials.",
                 input: AgentIdInput,
                 example: { agentId: "7c1a5b0e-9a53-4c6b-8d64-2f5a1b0c3e77" },
                 authz: { superAdmin: true },

package/dist/platform/ops/admin.ops.js

@@ -43,6 +43,7 @@ const SettingsInput = DEPLOYMENT_SETTINGS_PATCH.pick({
     uiTheme: true,
     uiArrangement: true,
     clientExtensions: true,
+    sandboxTiers: true,
 }).strict();
 const ProviderId = ModelProviderParams.shape.provider.describe("The model provider (models.platform-list), e.g. the plugin name of its extension.");
 /** `provider/model` of a purpose target, or null. */
@@ -182,17 +183,17 @@ let AdminOperations = class AdminOperations {
             }),
             defineOperation({
                 id: "admin.settings",
-                description: "Read the deployment settings (super admin): who may create orgs (orgCreation), the price currency, whether orgs may create their own connectors and skills, whether org admins may browse the marketplaces, and the per-org limit overrides keyed by org id (orgs.get reads one org's).",
+                description: "Read the deployment settings (super admin): who may create orgs (orgCreation), the price currency, whether orgs may create their own connectors and skills, whether org admins may browse the marketplaces, the per-org limit overrides keyed by org id (orgs.get reads one org's), and the platform's sandbox levels in effect (sandboxTiers: max, default, allowUnsandboxed, with sources: env, file or nacos are set in the startup config and read-only, db chosen in the admin console, default).",
                 input: z.object({}).strict(),
                 example: {},
                 authz: { superAdmin: true },
                 mirrors: ["GET /api/v1/admin/settings"],
                 confirm: "read",
-                run: () => this.settings.get(),
+                run: () => this.settings.view(),
             }),
             defineOperation({
                 id: "admin.update-settings",
-                description: "Change deployment settings (super admin); give only the keys to change: orgCreation (anyone or super_admin), priceCurrency (ISO 4217 code), customConnectors / customSkills (allow or deny: whether orgs may create their own instead of installing from the catalog), orgMarketplaceBrowse (true or false), uiTheme ({ id }: the platform default theme, a platform theme whose scope is all, or null for the built-in theme; it is what every org falls back to and what the sign-in pages show), uiArrangement ({ <slot>: { hidden, order } } for a list slot, { <slot>: { use } } for a single slot: the platform default arrangement of UI slots, with contribution keys <extension>/<contribution>; hidden ones are not listed but still open by URL; use names the contribution that replaces the built-in, null for the built-in; null for a slot removes its entry), clientExtensions ({ enabled?, disabled? }: the kill switch of plugin client code; enabled false stops every plugin's interface code in every browser, disabled is the whole list of plugins whose interface code alone is stopped while their tools keep working; read the current list from admin.settings first). Per-org limits are orgs.set-limits.",
+                description: "Change deployment settings (super admin); give only the keys to change: orgCreation (anyone or super_admin), priceCurrency (ISO 4217 code), customConnectors / customSkills (allow or deny: whether orgs may create their own instead of installing from the catalog), orgMarketplaceBrowse (true or false), uiTheme ({ id }: the platform default theme, a platform theme whose scope is all, or null for the built-in theme; it is what every org falls back to and what the sign-in pages show), uiArrangement ({ <slot>: { hidden, order } } for a list slot, { <slot>: { use } } for a single slot: the platform default arrangement of UI slots, with contribution keys <extension>/<contribution>; hidden ones are not listed but still open by URL; use names the contribution that replaces the built-in, null for the built-in; null for a slot removes its entry), clientExtensions ({ enabled?, disabled? }: the kill switch of plugin client code; enabled false stops every plugin's interface code in every browser, disabled is the whole list of plugins whose interface code alone is stopped while their tools keep working; read the current list from admin.settings first), sandboxTiers ({ max?, default?, allowUnsandboxed? }: the platform's sandbox levels strict < dev < open; null clears a field back to its default; through this tool they may only be lowered, never raised, and fields set in the startup config are read-only). Per-org limits are orgs.set-limits.",
                 input: SettingsInput.refine((b) => Object.keys(b).length > 0, {
                     message: "at least one setting is required",
                 }),
@@ -207,6 +208,14 @@ let AdminOperations = class AdminOperations {
                         code: "validation_failed",
                         next: "Fix the values as the message says (admin.settings shows the current ones).",
                     },
+                    {
+                        code: "deployment.sandbox_tier_not_allowed",
+                        next: "Through this tool the platform's sandbox levels may only be lowered; to raise them, ask a super admin to change them in the admin console settings on the web.",
+                    },
+                    {
+                        code: "deployment.setting_readonly",
+                        next: "That sandbox level is set in the deployment's startup config (environment, file or Nacos; admin.settings shows the source); it can only be changed there, by the operator.",
+                    },
                     {
                         code: "theme.not_available",
                         next: "The platform default must be a platform theme whose scope is all, not disabled, and on in every organization. When the details list orgs, the theme is off in those organizations: tell the person their names, then choose another theme (plugins.components with kind theme lists them) or have it switched on in those organizations first; { id: null } sets the built-in theme.",
@@ -214,13 +223,27 @@ let AdminOperations = class AdminOperations {
                 ],
                 precheck: async (i) => {
                     const r = DeploymentSettingsBody.safeParse(i);
-                    return r.success
+                    if (!r.success) {
+                        return {
+                            ok: false,
+                            code: "validation_failed",
+                            message: r.error.issues[0]?.message ?? "",
+                        };
+                    }
+                    const tiers = i.sandboxTiers;
+                    return tiers === undefined
                         ? { ok: true }
-                        : { ok: false, code: "validation_failed", message: r.error.issues[0]?.message ?? "" };
+                        : precheckBy(() => this.settings.checkSandboxTiers(tiers, { onlyNarrows: true }));
                 },
                 summary: async (i) => {
-                    const { uiTheme, uiArrangement, clientExtensions, ...rest } = i;
+                    const { uiTheme, uiArrangement, clientExtensions, sandboxTiers, ...rest } = i;
                     const parts = Object.entries(rest).map(([k, v]) => `${k}=${String(v)}`);
+                    if (sandboxTiers !== undefined) {
+                        parts.push(`sandboxTiers=${Object.entries(sandboxTiers)
+                            .filter(([, v]) => v !== undefined)
+                            .map(([k, v]) => `${k}:${String(v)}`)
+                            .join(" ")}`);
+                    }
                     const zh = [...parts];
                     const en = [...parts];
                     if (uiTheme !== undefined) {
@@ -253,7 +276,9 @@ let AdminOperations = class AdminOperations {
                         en: `Change the deployment settings: ${en.join(", ")}`,
                     };
                 },
-                run: (input, ctx) => this.settings.update(input, ctx.actorAccountId, undefined, viaAgent("admin.update-settings", ctx)),
+                run: (input, ctx) => this.settings.update(input, ctx.actorAccountId, undefined, viaAgent("admin.update-settings", ctx), 
+                // a person raises the platform's sandbox levels, never an agent (dev tiers spec §2)
+                { onlyNarrows: true }),
             }),
             defineOperation({
                 id: "models.platform-list",

package/dist/platform/ops/agent-skills.ops.js

@@ -38,7 +38,7 @@ const SHARE_FILES_SHOWN = 10;
 /** The model-facing result line of `agents.share-skill`. */
 function sharedText(o, name) {
     return o.kind === "shared"
-        ? `Shared skill "${name}" with the organization: it is now an org skill (the person maintains it) that any agent of the org can select; this agent keeps using it.`
+        ? `Shared skill "${name}" with the organization: it is now an org skill (the person maintains it) that every agent of the org has unless it turns it off; this agent keeps using it.`
         : `Asked the org admins to share skill "${name}" with the organization; it waits for their decision in the inbox. Until then it stays this agent's own skill.`;
 }
 /** The model-facing result line of `agents.register-skill`. */
@@ -367,7 +367,7 @@ let AgentSkillsOperations = class AgentSkillsOperations {
             }),
             defineOperation({
                 id: "agents.share-skill",
-                description: "Share one of an agent's own skills with the organization, so any agent of the org can select it; the agent keeps using it and the person becomes its maintainer (later versions they register on their agents are proposed to the org admins). An org admin shares at once; anyone else's ask waits for an org admin's decision in the inbox. Only the agent's owner can; takes the agent id from agents.list and the skill id from agents.skills.",
+                description: "Share one of an agent's own skills with the organization, so every agent of the org has it unless it turns it off; the agent keeps using it and the person becomes its maintainer (later versions they register on their agents are proposed to the org admins). An org admin shares at once; anyone else's ask waits for an org admin's decision in the inbox. Only the agent's owner can; takes the agent id from agents.list and the skill id from agents.skills.",
                 input: z.object({ agentId: AgentId, skillId: AgentSkillPathParams.shape.skillId }).strict(),
                 example: {
                     agentId: "7c1a5b0e-9a53-4c6b-8d64-2f5a1b0c3e77",

package/dist/platform/ops/agent-templates.ops.js

@@ -50,7 +50,7 @@ let AgentTemplatesOperations = class AgentTemplatesOperations {
             }),
             defineOperation({
                 id: "agent-templates.get",
-                description: "Read one agent template with its definition (model tier, tools, skills, connectors it needs). Takes the template id from agent-templates.list.",
+                description: "Read one agent template with its definition (model tier, tools, the skills an agent made from it loads first, the skills it turns off (disallowedSkills), connectors it needs). Takes the template id from agent-templates.list.",
                 input: z.object({ templateId: AgentTemplateIdParams.shape.id }).strict(),
                 example: { templateId: "5d0c7a52-3a0e-4f0a-bd0a-0f8c3d2a9e10" },
                 authz: { orgAction: "agents.create" },
@@ -63,7 +63,7 @@ let AgentTemplatesOperations = class AgentTemplatesOperations {
             }),
             defineOperation({
                 id: "agent-templates.save",
-                description: "Save an agent of the org as an org agent template under a new name, so members can create their own copy from it. Credentials and per-person settings are not carried over; the result lists what was omitted.",
+                description: "Save an agent of the org as an org agent template under a new name, so members can create their own copy from it. The skills the agent turns off are saved as the template's disallowedSkills. Credentials and per-person settings are not carried over; the result lists what was omitted.",
                 input: SaveAsAgentIdParams.extend({
                     name: SaveAsTemplateBody.shape.name.min(1).max(80),
                     description: SaveAsTemplateBody.shape.description.max(1024),