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

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

@@ -1,4 +1,4 @@
-import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider, type SandboxRoots } from "@capybara-hq/plugin-sdk";
+import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLimits, type SandboxProvider, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
@@ -10,6 +10,7 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxLeases, type SandboxPathLease } from "./leases.js";
 import { SandboxProviders } from "./providers.js";
+import { type AppliedLimits, type EffectiveSandboxPolicy } from "./tiers.js";
 export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
 /** The third argument of the `withSandbox` callback. */
 export interface SandboxUseInfo {
@@ -84,6 +85,17 @@ export type IfRunningResult<T> = {
  | {
     kind: "other_instance";
 };
+/** {@link SandboxService.limitsState}: the limits of a device's instance, for its page. */
+export interface DeviceLimitsState {
+    /** The tier and egress mode the instance (or its file system) runs with; null = unknown. */
+    applied: AppliedLimits | null;
+    /** The tier and egress mode it should run with now (the device's effective policy). */
+    effective: AppliedLimits;
+    /** A cloud instance differs: its next use updates or recreates it, files kept. */
+    pendingNextUse: boolean;
+    /** Only a file reset applies the effective limits (`limitsApplyAt: "fileSystem"`). */
+    pendingFilesReset: boolean;
+}
 /** The provider-side name of a device's file system and instance. */
 export declare const deviceResourceName: (deviceId: string) => string;
 /** The device is missing, deleted, or not in the caller's org (404; ids cannot be probed). */
@@ -103,8 +115,8 @@ export declare const isInstance: (row: Pick<Row, "handle" | "created_at">, gone:
  * Sandbox config problems to tell operators at startup (English log lines):
  * - `runtime.maxRunSeconds` below `sandbox.limits.maxCommandSeconds`: long commands are cut by the
  *   run time limit (Ruling M20);
- * - `sandbox.limits.egress` is open but the current provider plugin has no `allowOpenEgress`: every
- *   instance creation is refused.
+ * - `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.
  */
@@ -212,12 +224,66 @@ export declare class SandboxService {
     /** Concurrent holders of one device (`sandbox.maxConcurrentCommands`, read at every use). */
     private get cap();
     /**
-     * The org's effective sandbox limits (spec §8.4): the deployment's `sandbox.limits`, egress
-     * narrowed by the org setting `sandboxEgress` (Ruling M19), cpu / memory per the super admin's
-     * org override (C19 / Ruling M16). Instances are created with them; phase 1 devices use
-     * them unchanged.
-     */
-    orgLimits(orgId: string): Promise<SandboxLimits>;
+     * The effective sandbox policy of a device (sandbox dev tiers spec §4.2): the platform's and
+     * the org's tiers and network with the device's own tier (`devices.tier`, read fresh; a local
+     * device and a missing one have none). Without `deviceId`: a device that follows the org's
+     * default.
+     */
+    devicePolicy(device: {
+        orgId: string;
+        deviceId?: string;
+    }): Promise<EffectiveSandboxPolicy>;
+    /** The device's own tier (`devices.tier`); null when it follows the org or is not there. */
+    private deviceTier;
+    /**
+     * The device's effective sandbox limits (spec §8.4; sandbox dev tiers spec §4.2): the
+     * deployment's `sandbox.limits`, cpu / memory per the super admin's org override (C19 / Ruling
+     * M16), and the network of the effective tier ({@link devicePolicy}): egress narrowed by the
+     * org setting `sandboxEgress` (Ruling M19), widened by the tier. `opts.policy`: a policy the
+     * caller already read; `opts.tier`: limits for that tier instead (a local device's ceiling, an
+     * unattended run's cap). Cloud instances are created with them.
+     */
+    deviceLimits(device: {
+        orgId: string;
+        deviceId?: string;
+    }, opts?: {
+        policy?: EffectiveSandboxPolicy;
+        tier?: SandboxTier;
+    }): Promise<SandboxLimits>;
+    /**
+     * The limits of the org's ceiling (its highest tier, {@link deviceLimits} at `ceiling`): what a
+     * local device's exec may reach at most, so what a network grant or approval is checked
+     * against.
+     */
+    ceilingLimits(orgId: string): Promise<SandboxLimits>;
+    /**
+     * The limits state of a device's instance for its page (sandbox dev tiers spec §7.1, §11.1),
+     * read without a lease: `applied` is what the instance or file system was made with or updated
+     * to (null: unknown, or no instance yet), `effective` what it should run with now.
+     * `pendingNextUse`: a cloud instance exists and differs; its next use applies the new limits
+     * (files kept). `pendingFilesReset`: the provider fixes limits at its file system
+     * (`limitsApplyAt: "fileSystem"`) and cannot `update` them, so only a file reset applies them.
+     * A local device (its machine applies the tier at each command) is never pending, and its
+     * `applied` is null. `opts.policy`: the device's effective policy when the caller already read
+     * it ({@link devicePolicy}).
+     */
+    limitsState(device: {
+        orgId: string;
+        deviceId: string;
+    }, opts?: {
+        policy?: EffectiveSandboxPolicy;
+    }): Promise<DeviceLimitsState>;
+    /**
+     * Whether a provider whose limits are fixed at its file system cannot apply `effective`
+     * without a file reset: it has no `update`, or its `update` already answered `recreate` for it.
+     */
+    private fsBound;
+    /**
+     * Whether the running instance of `row` must get `want` before use (spec §7.1): a cloud
+     * instance whose recorded tier or egress mode differs, unless only a file reset could apply it
+     * ({@link fsBound}). `want` null: a local device (the tier travels with each command).
+     */
+    private mustApply;
     /**
      * The device's instance state as shown to people (read only, no lease): `running` /
      * `suspended` and the last use. No instance, a destroyed one, or one stuck in `creating` (being
@@ -274,6 +340,25 @@ export declare class SandboxService {
      *   meanwhile), `info.restarted` is true, so it learns its processes are gone (final review m5).
      */
     withSandbox<T>(ctx: SandboxUseContext, fn: (h: SandboxHandle, p: HeldProvider, info: SandboxUseInfo, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<T>;
+    /**
+     * The limits a cloud device's instance must run with for this use (sandbox dev tiers spec
+     * §7.1), read fresh; null for a local device (its machine gets the tier with each command).
+     * `row`: the instance row read under the exclusive lease (read here when absent).
+     *
+     * A scheduled run without a person on a cloud device that may run in the open tier, without the
+     * task's `tier:open` grant, is refused (`device.tier_not_granted`, recorded in the task run's
+     * `missing_grants`): the tier belongs to the shared instance, so it is not switched under the
+     * device's attended sessions (spec §11.4). The tier it may run in is the effective one, or for a
+     * provider whose limits are fixed at its file system the higher of that and the recorded one
+     * (a NULL record there counts as open: nothing says the file system is narrower).
+     */
+    private wantedLimits;
+    /**
+     * Whether the device's instance may run in the open tier during this use (see
+     * {@link wantedLimits}): the effective tier is open, or the provider fixes limits at its file
+     * system and the recorded tier is open or unknown.
+     */
+    private mayRunOpen;
     /**
      * Ruling R24: an operation on the held instance `e` found its file system gone. Records
      * `fs_status = 'lost'` while the row still records that instance on its file system (the
@@ -298,7 +383,9 @@ export declare class SandboxService {
      * Becomes a holder: loops until it has a shared lease on a running instance, or `sandbox.busy`.
      * An instance recorded `running` (with the current provider, not the `gone` instance) is used
      * under a shared lease; otherwise the exclusive lease (with intent) makes it run and is
-     * downgraded. One token serves both, so the waiter passes its own intent.
+     * downgraded. One token serves both, so the waiter passes its own intent. `wantNow` reads the
+     * limits this use wants ({@link wantedLimits}), again after each wait, so a tier narrowed
+     * during the wait is never used with the old, wider limits.
      */
     private enter;
     private clearIntent;
@@ -411,6 +498,29 @@ export declare class SandboxService {
      * new instance is destroyed (best effort) before {@link SandboxLockLostError} is thrown.
      */
     private create;
+    /**
+     * Under the exclusive lease, on the running instance `handle` of `row` whose tier or egress
+     * mode differs from `want` (sandbox dev tiers spec §7.1): the provider's `update` when it has
+     * one; `updated` records `want`. Otherwise (`recreate`, no `update`, or the instance found gone
+     * by `update`) the instance is destroyed and created again on the kept files, which records
+     * `want` and is returned (the caller reports a restart). A provider whose limits are fixed at
+     * its file system is not recreated (that would not apply them): `want` is recorded as
+     * `unapplied` and the instance keeps running as is until a file reset.
+     *
+     * An `update` that fails otherwise never records `want`: a provider whose limits apply at
+     * instance create is recreated (warned); after an abort, or for a provider bound to its file
+     * system, the instance is suspended ({@link quarantine}) and the error thrown, so the next use
+     * resumes it and tries again.
+     */
+    private applyLimits;
+    /**
+     * After a failed `update` that cannot be repaired by a recreate: best effort, with fresh short
+     * signals (the use's own may be aborted), suspends the instance (or kills its commands) and
+     * records it suspended (fenced: a lost lease leaves the record to the new holder).
+     */
+    private quarantine;
+    /** Runs `call` with its own short signal; a failure is warned and returns false. */
+    private bestEffort;
     /**
      * Destroys the file system another provider may have made under the device's name without
      * the kernel recording it (`destroyFileSystemByName`; not there is success). That provider not