@capybara-hq/kernel 0.1.0-rc.22 → 0.1.0-rc.24

package/dist/sandbox/platform-tiers.d.ts

@@ -0,0 +1,86 @@
+import { type SandboxTier } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import type { KernelConfig } from "../config/schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelLogger } from "../log.js";
+/**
+ * The platform's sandbox tiers (sandbox dev tiers spec §4.1): `max`, `default` and
+ * `allowUnsandboxed`. Each field is read env > config file (or Nacos) > the super admin's choice in
+ * the admin console (deployment setting {@link PLATFORM_TIERS_SETTING}) > {@link PLATFORM_TIER_DEFAULTS}.
+ * A field set in the startup config is read-only in the admin console. Read live from PG at every
+ * use, so a change applies on every replica at once.
+ */
+/** The `deployment_settings` key of the super admin's choice. */
+export declare const PLATFORM_TIERS_SETTING = "sandboxTiers";
+/** The fields, in display order. */
+export declare const PLATFORM_TIER_FIELDS: readonly ["max", "default", "allowUnsandboxed"];
+export type PlatformTierField = (typeof PLATFORM_TIER_FIELDS)[number];
+/** The stored choice: each field absent follows the default. */
+export declare const PlatformTiersStoredSchema: 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 PlatformTiersStored = z.infer<typeof PlatformTiersStoredSchema>;
+/**
+ * A change of the stored choice (`PUT /api/v1/admin/settings` `sandboxTiers`): each given field
+ * replaces the stored one, null clears it (back to the default); at least one field.
+ */
+export declare const PLATFORM_TIERS_PATCH: z.ZodObject<{
+    max: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>>;
+    default: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        dev: "dev";
+        open: "open";
+        strict: "strict";
+    }>>>;
+    allowUnsandboxed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strict>;
+export type PlatformTiersPatch = z.infer<typeof PLATFORM_TIERS_PATCH>;
+/** The platform's effective tiers. */
+export interface PlatformTiers {
+    max: SandboxTier;
+    /** At most {@link max}. */
+    default: SandboxTier;
+    allowUnsandboxed: boolean;
+}
+/** What a field falls back to when neither the startup config nor the admin console sets it. */
+export declare const PLATFORM_TIER_DEFAULTS: Readonly<PlatformTiers>;
+/** Where a field's effective value comes from. */
+export type PlatformTierSource = "env" | "file" | "nacos" | "db" | "default";
+/** The admin console's view: the effective values and where each comes from. */
+export interface PlatformTiersView extends PlatformTiers {
+    sources: Record<PlatformTierField, PlatformTierSource>;
+}
+/** The startup config's `sandbox.tiers` (each field undefined when not set there). */
+export type ConfigTiers = KernelConfig["sandbox"]["tiers"];
+/**
+ * Parses the stored choice: missing -> `{}`; invalid -> `{ max: "strict" }`, narrower, never
+ * wider (the same rule an org's invalid `sandboxTier` follows), with a warning on `log`.
+ */
+export declare function parseStoredPlatformTiers(value: unknown, log?: Pick<KernelLogger, "warn">): PlatformTiersStored;
+/** The default the layers choose before it is cut to the max. */
+export declare const chosenPlatformDefault: (config: ConfigTiers, stored: PlatformTiersStored) => SandboxTier;
+/** The effective tiers of the startup config over the stored choice; the default is cut to the max. */
+export declare function resolvePlatformTiers(config: ConfigTiers, stored: PlatformTiersStored): PlatformTiers;
+/** Whether `next` reaches further than `prev` anywhere: a higher max or default, or unsandboxed allowed. */
+export declare function platformTiersWiden(prev: PlatformTiers, next: PlatformTiers): boolean;
+/** The stored choice with `patch` applied (null clears a field). */
+export declare function applyPlatformTiersPatch(stored: PlatformTiersStored, patch: PlatformTiersPatch): PlatformTiersStored;
+/** The stored choice, read live (in the caller's transaction when there is one). */
+export declare function readStoredPlatformTiers(db: KernelSchemaDb, log?: Pick<KernelLogger, "warn">): Promise<PlatformTiersStored>;
+/** The platform's effective tiers, read live: see {@link resolvePlatformTiers}. */
+export declare function readPlatformTiers(db: KernelSchemaDb, config: {
+    get(): Pick<KernelConfig, "sandbox">;
+}, log?: Pick<KernelLogger, "warn">): Promise<PlatformTiers>;

package/dist/sandbox/platform-tiers.js

@@ -0,0 +1,97 @@
+import { minTier, tierAtMost } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+/**
+ * The platform's sandbox tiers (sandbox dev tiers spec §4.1): `max`, `default` and
+ * `allowUnsandboxed`. Each field is read env > config file (or Nacos) > the super admin's choice in
+ * the admin console (deployment setting {@link PLATFORM_TIERS_SETTING}) > {@link PLATFORM_TIER_DEFAULTS}.
+ * A field set in the startup config is read-only in the admin console. Read live from PG at every
+ * use, so a change applies on every replica at once.
+ */
+/** The `deployment_settings` key of the super admin's choice. */
+export const PLATFORM_TIERS_SETTING = "sandboxTiers";
+/** The fields, in display order. */
+export const PLATFORM_TIER_FIELDS = ["max", "default", "allowUnsandboxed"];
+const Tier = z.enum(["strict", "dev", "open"]);
+/** The stored choice: each field absent follows the default. */
+export const PlatformTiersStoredSchema = z
+    .object({
+    max: Tier.optional(),
+    default: Tier.optional(),
+    allowUnsandboxed: z.boolean().optional(),
+})
+    .strict();
+/**
+ * A change of the stored choice (`PUT /api/v1/admin/settings` `sandboxTiers`): each given field
+ * replaces the stored one, null clears it (back to the default); at least one field.
+ */
+export const PLATFORM_TIERS_PATCH = z
+    .object({
+    max: Tier.nullable().optional(),
+    default: Tier.nullable().optional(),
+    allowUnsandboxed: z.boolean().nullable().optional(),
+})
+    .strict()
+    .refine((o) => Object.values(o).some((v) => v !== undefined), {
+    message: "give max, default, allowUnsandboxed or several",
+});
+/** What a field falls back to when neither the startup config nor the admin console sets it. */
+export const PLATFORM_TIER_DEFAULTS = Object.freeze({
+    max: "dev",
+    default: "dev",
+    allowUnsandboxed: true,
+});
+/**
+ * Parses the stored choice: missing -> `{}`; invalid -> `{ max: "strict" }`, narrower, never
+ * wider (the same rule an org's invalid `sandboxTier` follows), with a warning on `log`.
+ */
+export function parseStoredPlatformTiers(value, log) {
+    if (value === undefined)
+        return {};
+    const parsed = PlatformTiersStoredSchema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    log?.warn("invalid deployment setting; it reads as max strict", { key: PLATFORM_TIERS_SETTING });
+    return { max: "strict" };
+}
+/** The default the layers choose before it is cut to the max. */
+export const chosenPlatformDefault = (config, stored) => config.default ?? stored.default ?? PLATFORM_TIER_DEFAULTS.default;
+/** The effective tiers of the startup config over the stored choice; the default is cut to the max. */
+export function resolvePlatformTiers(config, stored) {
+    const max = config.max ?? stored.max ?? PLATFORM_TIER_DEFAULTS.max;
+    return {
+        max,
+        default: minTier(chosenPlatformDefault(config, stored), max),
+        allowUnsandboxed: config.allowUnsandboxed ?? stored.allowUnsandboxed ?? PLATFORM_TIER_DEFAULTS.allowUnsandboxed,
+    };
+}
+/** Whether `next` reaches further than `prev` anywhere: a higher max or default, or unsandboxed allowed. */
+export function platformTiersWiden(prev, next) {
+    return (!tierAtMost(next.max, prev.max) ||
+        !tierAtMost(next.default, prev.default) ||
+        (next.allowUnsandboxed && !prev.allowUnsandboxed));
+}
+/** The stored choice with `patch` applied (null clears a field). */
+export function applyPlatformTiersPatch(stored, patch) {
+    const out = { ...stored };
+    for (const f of PLATFORM_TIER_FIELDS) {
+        const v = patch[f];
+        if (v === null)
+            delete out[f];
+        else if (v !== undefined)
+            out[f] = v;
+    }
+    return out;
+}
+/** The stored choice, read live (in the caller's transaction when there is one). */
+export async function readStoredPlatformTiers(db, log) {
+    const row = await db
+        .selectFrom("deployment_settings")
+        .select("value")
+        .where("key", "=", PLATFORM_TIERS_SETTING)
+        .executeTakeFirst();
+    return parseStoredPlatformTiers(row?.value, log);
+}
+/** The platform's effective tiers, read live: see {@link resolvePlatformTiers}. */
+export async function readPlatformTiers(db, config, log) {
+    return resolvePlatformTiers(config.get().sandbox.tiers, await readStoredPlatformTiers(db, log));
+}

package/dist/sandbox/sandbox.service.d.ts

@@ -2,7 +2,7 @@ import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLim
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
-import { type KernelConfig } from "../config/schema.js";
+import type { KernelConfig } from "../config/schema.js";
 import type { DeviceInstancesTable } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -106,6 +106,19 @@ export declare const deviceNotFound: () => ApiError;
  * owner's: `capybara-device logout`, then `login` into the device, recreates it (ruling R24).
  */
 export declare const deviceFilesLost: (local?: boolean) => ApiError;
+/**
+ * A cloud sandbox provider refused to make (or move) an instance with open egress, the open tier
+ * (409; sandbox dev tiers spec §5.3): above all a provider set to refuse it (sandbox-docker /
+ * sandbox-e2b `openEgress: "off"`). Details `[{ tier }]`. The provider's own error goes only to
+ * the log: it may name the provider's settings.
+ */
+export declare const sandboxTierRefused: (tier: SandboxTier) => ApiError;
+/**
+ * A cloud sandbox provider failed to make a device's file system or instance for another reason
+ * (502): often its deployment config (image, runtime, network), sometimes a passing fault. The
+ * provider's own error goes only to the log.
+ */
+export declare const sandboxCreateFailed: () => ApiError;
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -117,11 +130,11 @@ export declare const isInstance: (row: Pick<Row, "handle" | "created_at">, gone:
  *   run time limit (Ruling M20);
  * - `sandbox.tiers.max` is open but the current provider plugin sets `openEgress: "off"`: every
  *   creation of an open-tier instance is refused.
- * With both time limits at their defaults (900 < 7200, a known trade-off) it is only info; warn
- * when an operator changed one and they still disagree.
+ * No run duration limit (`runtime.maxRunSeconds` 0, the default) cuts no command, so there is
+ * nothing to tell.
  */
 export declare function sandboxConfigWarnings(cfg: Pick<KernelConfig, "runtime" | "sandbox" | "extensionConfig">, providerPlugin?: string): {
-    level: "info" | "warn";
+    level: "warn";
     message: string;
 }[];
 /** No sandbox provider (503). */
@@ -465,7 +478,7 @@ export declare class SandboxService {
     /**
      * Under the exclusive lease, right after a resume or a (re)build: kills the sessions of the
      * background tasks marked lost while their process may live on (`kill_pending`), in one exec of
-     * `pkill -KILL -s <sid>`, then clears their flags. Tasks of another instance have no process
+     * `pkill -KILL -s <sid>` (`-g` on macOS), then clears their flags. Tasks of another instance have no process
      * here and are only cleared. A gone instance and an abort are thrown; another failure is warned
      * and leaves the flags of this instance's tasks for the next resume.
      */

package/dist/sandbox/sandbox.service.js

@@ -11,8 +11,8 @@ import { randomUUID } from "node:crypto";
 import { compareTiers, isFileSystemGoneError, isSandboxGoneError, rootsOf, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql, } from "kysely";
+import { SESSION_MODE_SCRIPT } from "../background/launch.js";
 import { BackgroundTaskStore } from "../background/store.js";
-import { DEFAULT_MAX_COMMAND_SECONDS, DEFAULT_MAX_RUN_SECONDS, } from "../config/schema.js";
 import { ApiError } from "../errors.js";
 import { readSandboxLimitOverride } from "../identity/settings.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -22,8 +22,9 @@ import { effectiveSandboxLimits, readOrgSettings } from "../orgs/settings.servic
 import { appendMissingGrant, TIER_OPEN_GRANT_KEY, UNATTENDED_OPEN_TIER_ERROR, unattendedTierOf, } from "../schedules/unattended.js";
 import { canonicalJson } from "../tools/canonical-json.js";
 import { SandboxLeases, SandboxLockLostError, sandboxBusy, } from "./leases.js";
-import { LOCAL_PROVIDER, providerForDevice, SandboxProviders, } from "./providers.js";
-import { appliedOf, effectiveSandboxPolicy, instanceLimitsJson, limitsForTier, readInstanceLimits, sameApplied, } from "./tiers.js";
+import { isInternalProvider, LOCAL_PROVIDER, providerForDevice, SandboxProviders, } from "./providers.js";
+import { appliedOf, effectiveSandboxPolicy, instanceLimitsJson, limitsForTier, readDeploymentSandboxPolicy, readInstanceLimits, sameApplied, } from "./tiers.js";
+import { SandboxProviderUnreachableError } from "./unreachable.js";
 // Moved to leases.ts (phase C); re-exported for existing importers
 export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
 /** Margin (ms) of a holder record's TTL beyond the longest command: by then the in-sandbox limit has ended its commands. */
@@ -57,6 +58,46 @@ export const deviceNotFound = () => new ApiError("device.not_found", "This devic
 export const deviceFilesLost = (local = false) => local
     ? new ApiError("device.files_lost", "The local device's directory is gone from its machine; run capybara-device logout, then capybara-device login into this device, on that machine to recreate it.", [{ source: "local" }])
     : new ApiError("device.files_lost", "The device's files are gone; reset its files from the devices page to start with an empty workspace.");
+/**
+ * A cloud sandbox provider refused to make (or move) an instance with open egress, the open tier
+ * (409; sandbox dev tiers spec §5.3): above all a provider set to refuse it (sandbox-docker /
+ * sandbox-e2b `openEgress: "off"`). Details `[{ tier }]`. The provider's own error goes only to
+ * the log: it may name the provider's settings.
+ */
+export const sandboxTierRefused = (tier) => new ApiError("sandbox.tier_refused", `The cloud sandbox can't run this device at the ${tier} tier: the sandbox provider refused to create it there. An org admin can lower the tier on the device page or in the org's sandbox settings, or a super admin can allow it in the sandbox extension's settings.`, [{ tier }]);
+/**
+ * A cloud sandbox provider failed to make a device's file system or instance for another reason
+ * (502): often its deployment config (image, runtime, network), sometimes a passing fault. The
+ * provider's own error goes only to the log.
+ */
+export const sandboxCreateFailed = () => new ApiError("sandbox.create_failed", "The cloud sandbox provider could not create this device's sandbox. Retry; if it keeps failing, a super admin should check the sandbox extension's settings.");
+/**
+ * What a failed `createFileSystem` / `create` / `update` of a cloud provider becomes: an abort,
+ * a gone error, an unreachable provider and a kernel error stay as they are (their callers and the
+ * tools handle them); any other error is logged (warn, redacted) and replaced by
+ * {@link sandboxTierRefused} when `limits` ask for open egress (the only egress a provider's
+ * config refuses), else (a create) by {@link sandboxCreateFailed}; a failed `update` below open
+ * stays as it is. A kernel-internal provider (`@local`) keeps its own errors.
+ */
+function providerRefusal(log, err, facts, limits, signal) {
+    if (signal.aborted ||
+        isInternalProvider(facts.provider) ||
+        isSandboxGoneError(err) ||
+        isFileSystemGoneError(err) ||
+        err instanceof SandboxProviderUnreachableError ||
+        err instanceof ApiError) {
+        return err;
+    }
+    if (limits.egress === "open") {
+        // spec §5.3: a provider set to refuse open egress (`openEgress: "off"`) fails here
+        log.warn("the sandbox provider refused an instance in the open tier; check its openEgress setting or lower sandbox.tiers.max", { ...facts, tier: limits.tier, err });
+        return sandboxTierRefused(limits.tier);
+    }
+    if (facts.op === "update")
+        return err;
+    log.warn("the sandbox provider failed to create a device's sandbox", { ...facts, err });
+    return sandboxCreateFailed();
+}
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -86,8 +127,8 @@ function tagged(impl, tag, actor, before) {
  *   run time limit (Ruling M20);
  * - `sandbox.tiers.max` is open but the current provider plugin sets `openEgress: "off"`: every
  *   creation of an open-tier instance is refused.
- * With both time limits at their defaults (900 < 7200, a known trade-off) it is only info; warn
- * when an operator changed one and they still disagree.
+ * No run duration limit (`runtime.maxRunSeconds` 0, the default) cuts no command, so there is
+ * nothing to tell.
  */
 export function sandboxConfigWarnings(cfg, providerPlugin) {
     const out = [];
@@ -103,10 +144,9 @@ export function sandboxConfigWarnings(cfg, providerPlugin) {
     }
     const run = cfg.runtime.maxRunSeconds;
     const cmd = cfg.sandbox.limits.maxCommandSeconds;
-    if (run < cmd) {
-        const defaults = run === DEFAULT_MAX_RUN_SECONDS && cmd === DEFAULT_MAX_COMMAND_SECONDS;
+    if (run > 0 && run < cmd) {
         out.push({
-            level: defaults ? "info" : "warn",
+            level: "warn",
             message: `runtime.maxRunSeconds (${run}) is less than sandbox.limits.maxCommandSeconds (${cmd}): sandbox commands are limited to the time left in the run, so commands longer than about ${run} seconds cannot finish; raise runtime.maxRunSeconds to at least ${cmd} if agents need long commands`,
         });
     }
@@ -278,12 +318,12 @@ let SandboxService = class SandboxService {
      * default.
      */
     async devicePolicy(device) {
-        const cfg = this.config.get().sandbox;
-        const [settings, tier] = await Promise.all([
+        const [deployment, settings, tier] = await Promise.all([
+            readDeploymentSandboxPolicy(this.db.db, this.config),
             readOrgSettings(this.db.db, device.orgId),
             device.deviceId === undefined ? null : this.deviceTier(device.orgId, device.deviceId),
         ]);
-        return effectiveSandboxPolicy(cfg, settings, tier);
+        return effectiveSandboxPolicy(deployment, settings, tier);
     }
     /** The device's own tier (`devices.tier`); null when it follows the org or is not there. */
     async deviceTier(orgId, deviceId) {
@@ -701,6 +741,17 @@ let SandboxService = class SandboxService {
                         if (intent)
                             await this.clearIntent(env, token);
                         intent = false;
+                        // after a wait, the limits again under the lease: a tier narrowed just before the
+                        // holder we waited for let go is applied now (asShared checks `ready` with them)
+                        if (waited) {
+                            try {
+                                want = await wantNow();
+                            }
+                            catch (err) {
+                                await lease.release();
+                                throw err;
+                            }
+                        }
                         const e = await this.asShared(ctx, p, lease, ready, signal);
                         if (e)
                             return e;
@@ -1088,7 +1139,7 @@ let SandboxService = class SandboxService {
     /**
      * Under the exclusive lease, right after a resume or a (re)build: kills the sessions of the
      * background tasks marked lost while their process may live on (`kill_pending`), in one exec of
-     * `pkill -KILL -s <sid>`, then clears their flags. Tasks of another instance have no process
+     * `pkill -KILL -s <sid>` (`-g` on macOS), then clears their flags. Tasks of another instance have no process
      * here and are only cleared. A gone instance and an abort are thrown; another failure is warned
      * and leaves the flags of this instance's tasks for the next resume.
      */
@@ -1100,10 +1151,12 @@ let SandboxService = class SandboxService {
         let cleared = rows;
         if (mine.length > 0) {
             // pkill exits 1 when the session has no process left: only a higher status is a failure
-            const command = `rc=0; for sid in ${mine.map((r) => r.sid).join(" ")}; do pkill -KILL -s "$sid"; c=$?; [ "$c" -le 1 ] || rc=$c; done; exit $rc`;
+            const command = `${SESSION_MODE_SCRIPT}\nrc=0; for sid in ${mine.map((r) => r.sid).join(" ")}; do tk_kill KILL "$sid"; c=$?; [ "$c" -le 1 ] || rc=$c; done; exit $rc`;
             try {
                 const r = await p.impl.exec(handle, {
                     command,
+                    // tk_kill's control files are relative to the workspace root (macOS devices)
+                    cwd: rootsOf(handle).workspace,
                     timeoutMs: PENDING_KILL_TIMEOUT_MS,
                     maxOutputBytes: 4096,
                     signal,
@@ -1366,7 +1419,12 @@ let SandboxService = class SandboxService {
             ? row.fs_handle
             : null;
         if (fs === null) {
-            fs = await p.impl.createFileSystem({ name, limits, signal });
+            try {
+                fs = await p.impl.createFileSystem({ name, limits, signal });
+            }
+            catch (err) {
+                throw providerRefusal(this.log, err, { deviceId: id, provider: p.plugin, op: "createFileSystem" }, limits, signal);
+            }
             // A lost lease fails this write and leaves the file system alone: createFileSystem returns
             // the existing one for a name, so the new holder may already use it, files and all.
             await this.fenced(held, id, fence, {
@@ -1389,11 +1447,7 @@ let SandboxService = class SandboxService {
         }
         catch (err) {
             if (!isFileSystemGoneError(err)) {
-                if (limits.egress === "open" && !signal.aborted) {
-                    // spec §5.3: a provider set to refuse open egress (`openEgress: "off"`) fails here
-                    this.log.warn("the sandbox provider did not create an instance in the open tier; check its openEgress setting or lower sandbox.tiers.max", { deviceId: id, provider: p.plugin, err });
-                }
-                throw err;
+                throw providerRefusal(this.log, err, { deviceId: id, provider: p.plugin, op: "create" }, limits, signal);
             }
             this.log.warn("device file system is gone at the provider; its files are lost", {
                 deviceId: id,
@@ -1465,7 +1519,8 @@ let SandboxService = class SandboxService {
                     // the instance may run with half-applied limits and cannot be recreated here: stop it,
                     // so the next use resumes it and applies them again
                     await this.quarantine(held, id, handle, p, fence);
-                    throw err;
+                    // a provider bound to its file system that refuses the new tier (E2B, `openEgress: "off"`)
+                    throw providerRefusal(this.log, err, { deviceId: id, provider: p.plugin, op: "update" }, want, signal);
                 }
                 else {
                     // a new instance gets the limits at create: recreate rather than trust a failed update

package/dist/sandbox/tiers.d.ts

@@ -1,16 +1,28 @@
 import { type SandboxTier } from "@capybara-hq/plugin-sdk";
 import type { KernelConfig } from "../config/schema.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import type { OrgSettings } from "../orgs/settings.service.js";
+import { type PlatformTiers } from "./platform-tiers.js";
 /**
  * Sandbox tiers (sandbox dev tiers spec §4): who may reach which tier, and the network each tier
  * gets. One function, {@link effectiveSandboxPolicy}, combines the platform's ceiling and default
  * (`sandbox.tiers`), the org's (`sandboxTier`) and the device's own choice.
  */
-/** The deployment config the policy reads (`sandbox.limits` network fields and `sandbox.tiers`). */
+/**
+ * What the policy reads of the platform: the `sandbox.limits` network fields and the effective
+ * platform tiers (`readPlatformTiers`: the startup config over the admin console's choice).
+ */
 export interface DeploymentSandboxPolicy {
     limits: Pick<KernelConfig["sandbox"]["limits"], "egress" | "allowHosts" | "devHosts">;
-    tiers: KernelConfig["sandbox"]["tiers"];
+    tiers: PlatformTiers;
 }
+/**
+ * The platform side of the policy, read live: the `sandbox.limits` network fields of the config
+ * and the effective platform tiers (in the caller's transaction when there is one).
+ */
+export declare function readDeploymentSandboxPolicy(db: KernelSchemaDb, config: {
+    get(): Pick<KernelConfig, "sandbox">;
+}): Promise<DeploymentSandboxPolicy>;
 /** The org settings the policy reads. */
 export type OrgSandboxSettings = Pick<OrgSettings, "sandboxEgress" | "sandboxTier">;
 /**

package/dist/sandbox/tiers.js

@@ -1,4 +1,12 @@
 import { isSandboxTier, minTier, tierAtMost } from "@capybara-hq/plugin-sdk";
+import { readPlatformTiers } from "./platform-tiers.js";
+/**
+ * The platform side of the policy, read live: the `sandbox.limits` network fields of the config
+ * and the effective platform tiers (in the caller's transaction when there is one).
+ */
+export async function readDeploymentSandboxPolicy(db, config) {
+    return { limits: config.get().sandbox.limits, tiers: await readPlatformTiers(db, config) };
+}
 /** The org's base list `L`: see {@link BaseSandboxEgress}. */
 export function baseSandboxEgress(deployment, org) {
     if (deployment.egress === "none" || org?.mode === "none")

package/dist/schedules/calendar.d.ts

@@ -0,0 +1,134 @@
+import type { ScheduledTask, ScheduleMode, SchedulePauseReason, ScheduleStatus, ScheduleTrigger, TaskRun, TaskRunSkipReason, TaskRunStatus } from "./types.js";
+/** Planned occurrences reach this far ahead of now (spec §5.2, "about six weeks"). */
+export declare const CALENDAR_HORIZON_DAYS = 42;
+/** The longest range one request may ask for: a 6-week month grid plus a DST hour (§5.1). */
+export declare const CALENDAR_RANGE_DAYS = 43;
+/** The longest range with `taskId` (the panel's one-day list, §5.4). */
+export declare const CALENDAR_TASK_RANGE_DAYS = 2;
+/** A task-day with more items than this is collapsed into one summary (§5.4). */
+export declare const CALENDAR_COLLAPSE_OVER = 6;
+/**
+ * Ticks taken per request after the first local day, across all tasks (§5.5). One tick costs
+ * about 150-340 µs (cron's `getNextDateFrom`, measured 2026-11-12 with a ticker built once per
+ * task), so 3,000 keeps a worst-case request near one second.
+ */
+export declare const CALENDAR_TICK_BUDGET = 3000;
+/** Entries (`items` + `collapsed`) per request after the first local day (§5.5). */
+export declare const CALENDAR_ITEM_CAP = 3000;
+/** Run rows read per request after the first local day (§5.5). */
+export declare const CALENDAR_RUN_ROW_CAP = 20000;
+/**
+ * The first requested local day is always returned whole, outside the limits above; only these
+ * safety caps stop it (then nothing is returned, `truncated`, `horizon` = `from`).
+ */
+export declare const CALENDAR_FIRST_DAY_TICK_CAP = 10000;
+export declare const CALENDAR_FIRST_DAY_RUN_CAP = 20000;
+/** The limits of one assembly; tests lower them. */
+export interface CalendarLimits {
+    horizonDays: number;
+    collapseOver: number;
+    /**
+     * Ticks taken (planned ticks in the range, the due tick included), after the first day. Not
+     * counted: each stream's one lookahead evaluation past its `until` and the doubling search of
+     * `scanStep` for a task already due, at most about 2 × tasks evaluations more.
+     */
+    tickBudget: number;
+    itemCap: number;
+    runRowCap: number;
+    firstDayTickCap: number;
+    firstDayRunCap: number;
+}
+export declare const CALENDAR_LIMITS: CalendarLimits;
+/** How many run rows the service reads: enough to tell where either run cap cuts. */
+export declare const calendarRunReadLimit: (limits: CalendarLimits) => number;
+/** A task an entry of the answer names. */
+export interface CalendarTask {
+    id: string;
+    name: string;
+    agentId: string;
+    accountId: string;
+    status: ScheduleStatus;
+    pauseReason: SchedulePauseReason | null;
+    trigger: ScheduleTrigger;
+    mode: ScheduleMode;
+    jitterSeconds: number;
+    nextRunAt: string | null;
+}
+export type CalendarItem = {
+    kind: "run";
+    taskId: string;
+    /** The task run's id. */
+    id: string;
+    scheduledFor: string;
+    firedAt: string | null;
+    status: TaskRunStatus;
+    skipReason: TaskRunSkipReason | null;
+    trial: boolean;
+    manual: boolean;
+    /** Null for another member's run (admin `all`, spec §15 Q3), as `error` and `missingGrants`. */
+    conversationId: string | null;
+    error: string | null;
+    missingGrants: number | null;
+} | {
+    kind: "occurrence";
+    taskId: string;
+    /** The tick, before jitter. */
+    scheduledFor: string;
+    /** When it fires: the tick plus the task's jitter. */
+    at: string;
+};
+/** A task's items of one local day, summarized (§5.4). */
+export interface CalendarCollapsed {
+    taskId: string;
+    /** YYYY-MM-DD in the request's `timeZone`. */
+    day: string;
+    count: number;
+    upcoming: number;
+    running: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    /** The earliest and latest `scheduledFor` of the day's items. */
+    first: string;
+    last: string;
+}
+export interface CalendarAnswer {
+    tasks: CalendarTask[];
+    items: CalendarItem[];
+    collapsed: CalendarCollapsed[];
+    /** Nothing is returned after it: 42 days ahead, or the cut. */
+    horizon: string;
+    /** A limit cut the range at a whole local day. */
+    truncated: boolean;
+}
+export interface CalendarInput {
+    /** The live tasks the viewer may see in this request. */
+    tasks: readonly ScheduledTask[];
+    /**
+     * Their runs with `scheduledFor` in `[from, to)`, trial included, ordered by `scheduledFor`, at
+     * most {@link calendarRunReadLimit} (rows past it are not read; the range is cut before them).
+     */
+    runs: readonly TaskRun[];
+    /** The viewer: another creator's runs lose `conversationId`, `error` and `missingGrants`. */
+    viewerAccountId: string;
+    from: Date;
+    to: Date;
+    /** The viewer's zone: local days for the collapse and the cut. */
+    timeZone: string;
+    now: Date;
+    /** False when the org turned scheduled tasks off: nothing would fire, so nothing is planned. */
+    plan: boolean;
+    /** The org's catch-up window, as the scanner reads it. */
+    catchUpWindowMinutes: number;
+    /** False for a `taskId` read: every item, never collapsed. */
+    collapse: boolean;
+}
+/** The calendar answer from the rows (spec §5.2–§5.5). */
+export declare function assembleCalendar(input: CalendarInput, limits?: CalendarLimits): CalendarAnswer;
+/** YYYY-MM-DD of the instant (epoch ms) in `timeZone`. */
+export declare function dayKey(ms: number, timeZone: string): string;
+/**
+ * The first instant (epoch ms) of the local day of `ms` in `timeZone`: midnight, or the end of a
+ * DST gap that swallows it. A day is at most 25 hours long, so 27 hours back is an earlier day.
+ */
+export declare function startOfLocalDay(ms: number, timeZone: string): number;