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

package/dist/lifecycle/kernel-lifecycle.js

@@ -120,6 +120,8 @@ let KernelLifecycle = class KernelLifecycle {
     unwatchConfig;
     /** What the first bootstrap pass did, carried into the second one. */
     bootstrapCarry;
+    /** The packages the first bootstrap pass obtained, so the second downloads nothing again. */
+    bootstrapPackages;
     constructor(accounts, configService, log, options, 
     // biome-ignore lint/suspicious/noExplicitAny: the pool carries no schema types
     pool, redis, kdb, shutdown, host, registry, installs, blobs, extensionLifecycle, replicaStatus, bootstrap, marketplaces, pluginImport, bus, 
@@ -303,7 +305,9 @@ let KernelLifecycle = class KernelLifecycle {
      * kernel never serves without a required plugin. A failed optional entry is logged and returns
      * true: the start runs the step once more after the extensions loaded (a declarative entry's
      * catalog files need the object store, which on a fresh deployment is itself a bootstrap plugin),
-     * and the next start tries again while it stays incomplete.
+     * and the next start tries again while it stays incomplete. The first pass skips the `builtin`
+     * entries (they may ship skills and templates, which need the object store) and returns true for
+     * them too; the final pass imports them, and one that fails is logged like an optional entry.
      */
     async runBootstrap(dir, final = false) {
         const manifest = this.options.bootstrapManifest ?? (await readBootstrapManifest());
@@ -318,17 +322,25 @@ let KernelLifecycle = class KernelLifecycle {
                 ...(dir !== undefined && { dir }),
                 signal: this.shutdown.signal,
                 ...(this.bootstrapCarry !== undefined && { carry: this.bootstrapCarry }),
+                ...(this.bootstrapPackages !== undefined && { packages: this.bootstrapPackages }),
+                deferBuiltin: !final,
             });
             return false;
         }
         catch (e) {
             if (e instanceof BootstrapFailedError && !e.requiredFailed) {
                 this.bootstrapCarry = e.results;
-                if (final) {
-                    this.log.error("bootstrap: optional plugins could not be installed; retried on the next start", { failures: e.failures });
+                this.bootstrapPackages = e.packages;
+                if (e.failures.length === 0) {
+                    this.log.info("bootstrap: builtin plugins are installed once the extensions have loaded", {
+                        deferred: e.deferred,
+                    });
+                }
+                else if (final) {
+                    this.log.error("bootstrap: optional or builtin plugins could not be installed; retried on the next start", { failures: e.failures });
                 }
                 else {
-                    this.log.warn("bootstrap: optional plugins could not be installed yet; retried once the extensions have loaded", { failures: e.failures });
+                    this.log.warn("bootstrap: optional or builtin plugins could not be installed yet; retried once the extensions have loaded", { failures: e.failures });
                 }
                 return true;
             }

package/dist/local-devices/device-policy.service.d.ts

@@ -0,0 +1,65 @@
+import { type DeviceFeature, type DeviceLocalPolicySummary, type DevicePolicyArgs } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { MachinesService } from "./machines.js";
+import { LocalDeviceRelay } from "./relay.js";
+/** How long the machine may take to apply a policy change. */
+export declare const POLICY_DEADLINE_MS = 30000;
+/** What became of a policy change. */
+export type PolicyChangeOutcome = {
+    applied: true;
+    policy: DeviceLocalPolicySummary;
+} | {
+    applied: false;
+    reason: "offline" | "refused" | "unsupported";
+    message: string;
+};
+/**
+ * Changes a local device's policy on its machine (network ask-to-allow spec §5.2; sandbox dev
+ * tiers spec §7.3: its hosts, its `tier`, and `isolation` back to `sandbox`): the kernel→device
+ * `policy` op over the {@link LocalDeviceRelay}. The machine is the authority: it
+ * refuses widening unless its owner allows remote grants, validates every host and answers with
+ * the policy as written, which the kernel then keeps on the active machine's row (§5.4) and
+ * audits as `device.policy_changed`.
+ *
+ * The op is sent outside any transaction (a decision records its outcome afterwards, in its own
+ * transaction); only the summary write and the audit row are transactional. Callers decide who
+ * may change a device's policy (the device owner, in a signed-in session); this service checks
+ * only that the device is a live device of the org.
+ */
+export declare class DevicePolicyService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly relay;
+    private readonly machines;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, relay: Pick<LocalDeviceRelay, "call" | "holderLive">, machines: Pick<MachinesService, "activeFor">, log: Pick<KernelLogger, "warn">);
+    /**
+     * Sends the `policy` op (no transaction may be open), stores the returned summary and audits
+     * `device.policy_changed`. Never throws for an offline machine, a refusal or a program without
+     * the `policyOp` feature (nothing is sent to it); a device that is not a live device of `orgId`
+     * is `device.not_found`.
+     */
+    apply(input: {
+        orgId: string;
+        deviceId: string;
+        change: Omit<DevicePolicyArgs, "source">;
+        source: DevicePolicyArgs["source"];
+        actorTokenId?: string;
+    }): Promise<PolicyChangeOutcome>;
+    /** The active machine's features and policy summary (null when no machine is connected). */
+    summary(deviceId: string): Promise<{
+        features: DeviceFeature[];
+        policy: DeviceLocalPolicySummary | null;
+    } | null>;
+    /**
+     * Keeps the policy the machine wrote on its row and audits the change (`confirmed`); with no
+     * policy (the answer never came) only audits the attempt, unconfirmed. The detail's `isolation`
+     * is the one asked for, or the one the machine now reports when it changed (a tier change turns
+     * the sandbox back on).
+     */
+    private record;
+    /** The outcome of a failed op: offline, or the machine's refusal; a deleted device is thrown. */
+    private notApplied;
+}

package/dist/local-devices/device-policy.service.js

@@ -0,0 +1,217 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { ToolError, validateAllowHost, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { currentStore, TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { deviceNotFound } from "../sandbox/sandbox.service.js";
+import { MachinesService } from "./machines.js";
+import { isolationOf } from "./policy-summary.js";
+import { LocalDeviceRelay, ON_MACHINE_PREFIX } from "./relay.js";
+/** How long the machine may take to apply a policy change. */
+export const POLICY_DEADLINE_MS = 30_000;
+/** The prefix the relay puts before a machine's `policy`-kind refusal. */
+const REFUSED_PREFIX = "Refused by the machine's local policy: ";
+const OFFLINE_MESSAGE = "The device's machine is offline, so its policy was not changed. Start capybara-device on it.";
+const UNSUPPORTED_MESSAGE = "The device's capybara-device program cannot change its policy from the platform. Update capybara-device on the machine.";
+const errMsg = (e) => (e instanceof Error ? e.message : String(e));
+/**
+ * Changes a local device's policy on its machine (network ask-to-allow spec §5.2; sandbox dev
+ * tiers spec §7.3: its hosts, its `tier`, and `isolation` back to `sandbox`): the kernel→device
+ * `policy` op over the {@link LocalDeviceRelay}. The machine is the authority: it
+ * refuses widening unless its owner allows remote grants, validates every host and answers with
+ * the policy as written, which the kernel then keeps on the active machine's row (§5.4) and
+ * audits as `device.policy_changed`.
+ *
+ * The op is sent outside any transaction (a decision records its outcome afterwards, in its own
+ * transaction); only the summary write and the audit row are transactional. Callers decide who
+ * may change a device's policy (the device owner, in a signed-in session); this service checks
+ * only that the device is a live device of the org.
+ */
+let DevicePolicyService = class DevicePolicyService {
+    db;
+    txHost;
+    relay;
+    machines;
+    log;
+    constructor(db, txHost, relay, machines, log) {
+        this.db = db;
+        this.txHost = txHost;
+        this.relay = relay;
+        this.machines = machines;
+        this.log = log;
+    }
+    /**
+     * Sends the `policy` op (no transaction may be open), stores the returned summary and audits
+     * `device.policy_changed`. Never throws for an offline machine, a refusal or a program without
+     * the `policyOp` feature (nothing is sent to it); a device that is not a live device of `orgId`
+     * is `device.not_found`.
+     */
+    async apply(input) {
+        if (currentStore()) {
+            throw new Error("DevicePolicyService.apply() must not run inside a transaction: send the policy op " +
+                "first, then record the decision in a transaction.");
+        }
+        assertHosts(input.change, input.source.approvalId !== undefined);
+        const device = await this.db
+            .selectFrom("devices as e")
+            .innerJoin("orgs as o", "o.id", "e.org_id")
+            .select("e.source")
+            .where("e.id", "=", input.deviceId)
+            .where("e.org_id", "=", input.orgId)
+            .where("e.deleted_at", "is", null)
+            .where("o.deleted_at", "is", null)
+            .executeTakeFirst();
+        if (!device)
+            throw deviceNotFound();
+        if (device.source !== "local") {
+            return { applied: false, reason: "unsupported", message: UNSUPPORTED_MESSAGE };
+        }
+        const machine = await this.machines.activeFor(input.deviceId);
+        if (machine === null)
+            return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
+        if (!machine.features.includes("policyOp")) {
+            return { applied: false, reason: "unsupported", message: UNSUPPORTED_MESSAGE };
+        }
+        // not connected: nothing is sent (a queued op would wait for a reconnect nobody watches)
+        if (!(await this.relay.holderLive(input.deviceId))) {
+            return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
+        }
+        const args = { ...input.change, source: input.source };
+        let policy;
+        try {
+            ({ policy } = await this.relay.call(input.deviceId, "policy", args, {
+                deadlineMs: POLICY_DEADLINE_MS,
+                // the relay gives up by itself (deadline plus the reconnect grace)
+                signal: new AbortController().signal,
+            }));
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.code === "device.offline") {
+                // the op was sent and the wait ran out: the machine may still apply it, so the attempt is
+                // audited unconfirmed; its next hello reports the policy as it is
+                await this.record({ ...input, machineId: machine.id, policy: null });
+            }
+            return this.notApplied(input.deviceId, e);
+        }
+        await this.record({ ...input, machineId: machine.id, policy });
+        return { applied: true, policy };
+    }
+    /** The active machine's features and policy summary (null when no machine is connected). */
+    async summary(deviceId) {
+        const m = await this.machines.activeFor(deviceId);
+        return m === null ? null : { features: m.features, policy: m.localPolicy };
+    }
+    /**
+     * Keeps the policy the machine wrote on its row and audits the change (`confirmed`); with no
+     * policy (the answer never came) only audits the attempt, unconfirmed. The detail's `isolation`
+     * is the one asked for, or the one the machine now reports when it changed (a tier change turns
+     * the sandbox back on).
+     */
+    async record(input) {
+        // the isolation the machine reports now, when it differs from the stored one: a tier change
+        // turns an unsandboxed device's sandbox back on without asking for it (spec §5.4, §10.4)
+        let isolationNow;
+        if (input.policy !== null) {
+            const prev = await this.db
+                .selectFrom("device_machines")
+                .select("local_policy")
+                .where("id", "=", input.machineId)
+                .where("revoked_at", "is", null)
+                .forUpdate()
+                .executeTakeFirst();
+            const before = isolationOf(prev?.local_policy) ?? "sandbox";
+            if (input.policy.isolation !== before)
+                isolationNow = input.policy.isolation;
+            await this.db
+                .updateTable("device_machines")
+                .set({ local_policy: JSON.stringify(input.policy) })
+                .where("id", "=", input.machineId)
+                .where("revoked_at", "is", null)
+                .execute();
+        }
+        const { change, source } = input;
+        await audit(this.db.db, {
+            actorAccountId: source.accountId,
+            ...(input.actorTokenId !== undefined && { actorTokenId: input.actorTokenId }),
+            orgId: input.orgId,
+            action: "device.policy_changed",
+            target: input.deviceId,
+            detail: {
+                add: change.add ?? [],
+                remove: change.remove ?? [],
+                // only when set (null: follow the org's default); the device page lists the change
+                ...(change.tier !== undefined && { tier: change.tier }),
+                ...((isolationNow ?? change.isolation) !== undefined && {
+                    isolation: isolationNow ?? change.isolation,
+                }),
+                by: source.accountId,
+                via: source.via,
+                approvalId: source.approvalId ?? null,
+                confirmed: input.policy !== null,
+            },
+        });
+    }
+    /** The outcome of a failed op: offline, or the machine's refusal; a deleted device is thrown. */
+    notApplied(deviceId, e) {
+        if (e instanceof ApiError) {
+            if (e.code === "device.not_found")
+                throw e;
+            // device.offline, or device.forbidden (the machine was disconnected meanwhile)
+            return { applied: false, reason: "offline", message: OFFLINE_MESSAGE };
+        }
+        if (e instanceof ToolError && e.message.startsWith(REFUSED_PREFIX)) {
+            return { applied: false, reason: "refused", message: e.message.slice(REFUSED_PREFIX.length) };
+        }
+        // anything else the machine answered (its own error, an invalid result): not applied
+        this.log.warn("a device policy change failed on the machine", { deviceId, error: errMsg(e) });
+        const message = errMsg(e);
+        return {
+            applied: false,
+            reason: "refused",
+            message: message.startsWith(ON_MACHINE_PREFIX)
+                ? message.slice(ON_MACHINE_PREFIX.length)
+                : message,
+        };
+    }
+};
+__decorate([
+    Transactional()
+], DevicePolicyService.prototype, "record", null);
+DevicePolicyService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(LocalDeviceRelay)),
+    __param(3, Inject(MachinesService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], DevicePolicyService);
+export { DevicePolicyService };
+/**
+ * Hosts the platform may send: an approval's `add` takes exact hosts only (a card never grants a
+ * wildcard); the owner's own change on the device page (no approval) may add a wildcard (spec §7);
+ * `remove` takes any valid entry (narrowing, a wildcard too).
+ */
+function assertHosts(change, fromApproval) {
+    const bad = (h) => typeof h !== "string" || validateAllowHost(h).length > 0;
+    for (const h of change.add ?? []) {
+        if (bad(h) || (fromApproval && h.startsWith("*."))) {
+            throw new Error(`not an exact host to add to a device policy: ${JSON.stringify(h)}`);
+        }
+    }
+    for (const h of change.remove ?? []) {
+        if (bad(h))
+            throw new Error(`not a host to remove from a device policy: ${JSON.stringify(h)}`);
+    }
+}

package/dist/local-devices/local-device-gateway.js

@@ -177,7 +177,10 @@ class DeviceConnection {
             if (!(await this.claim()))
                 return;
             try {
-                await this.gw.machines.recordHello(this.identity.machineId, frame);
+                // the raw summary too: the frame parser drops one it cannot read whole, and its
+                // isolation must still reach the kernel
+                const rawPolicy = JSON.parse(text).policy;
+                await this.gw.machines.recordHello(this.identity.machineId, frame, rawPolicy);
             }
             catch (e) {
                 this.gw.log.warn("could not record a device hello", {

package/dist/local-devices/local-device-provider.d.ts

@@ -1,6 +1,8 @@
-import type { ExecResult, FileSystemHandle, SandboxHandle, SandboxLimits, SandboxProvider, SandboxRoots } from "@capybara-hq/plugin-sdk";
+import { type ExecResult, type FileSystemHandle, type SandboxHandle, type SandboxLimits, type SandboxProvider, type SandboxRoots } from "@capybara-hq/plugin-sdk";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import type { KernelLogger } from "../log.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
+import { NetworkGrants } from "./network-grants.js";
 import { LocalDeviceRelay } from "./relay.js";
 import { DeviceTargets } from "./targets.js";
 /** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
@@ -15,6 +17,11 @@ export declare const OP_DEADLINE_MS = 30000;
 export declare const FRAME_ENVELOPE_BYTES: number;
 /** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
 export declare const maxReadBytes: (maxFrameBytes: number) => number;
+/**
+ * The tool error of a device that runs commands without a sandbox the org does not allow (§4.3);
+ * also what a machine answers when it refuses such a command itself.
+ */
+export declare const UNSANDBOXED_NOT_ALLOWED_ERROR = "This device runs commands without a sandbox, which your organization does not allow. Its owner can turn the sandbox back on with `capybara-device policy set isolation sandbox`.";
 /**
  * The handle of an instance on a machine: the device id (ruling R1: the relay is keyed by
  * device), the roots the machine reported at `create`, and the org's effective limits at
@@ -42,9 +49,11 @@ export declare class LocalDeviceProvider implements SandboxProvider {
     private readonly targets;
     private readonly sandbox;
     private readonly config;
+    private readonly grants;
+    private readonly log;
     readonly concurrentExec: true;
     readonly sessionIsolation = false;
-    constructor(relay: LocalDeviceRelay, targets: Pick<DeviceTargets, "orgOf" | "machineRoots">, sandbox: Pick<SandboxService, "orgLimits">, config: Pick<KernelConfigService, "get">);
+    constructor(relay: LocalDeviceRelay, targets: Pick<DeviceTargets, "orgOf" | "machineRoots">, sandbox: Pick<SandboxService, "devicePolicy" | "deviceLimits">, config: Pick<KernelConfigService, "get">, grants: Pick<NetworkGrants, "forExec" | "unattendedTier" | "unsandboxed" | "recordMissing">, log: Pick<KernelLogger, "warn">);
     createFileSystem(args: {
         name: string;
         limits: SandboxLimits;
@@ -71,6 +80,23 @@ export declare class LocalDeviceProvider implements SandboxProvider {
     destroyByName(_name: string, signal: AbortSignal): Promise<void>;
     killAll(h: SandboxHandle, signal: AbortSignal): Promise<void>;
     killTagged(h: SandboxHandle, tags: string[], signal: AbortSignal): Promise<void>;
+    /**
+     * Runs the command on the machine with the org's limits now (ruling R27) and, for a command of a
+     * run, the hosts the kernel allows that run on this device beyond the local policy (network
+     * ask-to-allow spec §6.3; only those the org's limits admit, sent only when there are some). The device's report of refused hosts is re-layered
+     * against the limits this exec carried: the kernel never takes the device's word that the org
+     * allows a host (spec §4.1).
+     *
+     * The limits are the device's **ceiling** (sandbox dev tiers spec §4.2): `limits.tier` is the
+     * highest tier the org allows, its network that tier's, `defaultTier` the org's default (the
+     * device runs at `min(local tier ?? defaultTier, tier)`) and `devHosts` the dev hosts. A run of
+     * a scheduled task without a person and without the task's `tier:open` grant is capped at `dev`
+     * (spec §11.4). Before relaying, a machine that last reported running commands without a sandbox
+     * is refused when the org does not allow it, or for such a run (`device.unsandboxed_not_allowed`,
+     * spec §4.3). The kernel knows the local policy only from the last hello or policy op, so the
+     * same decision also travels in `limits.allowUnsandboxed` and the machine enforces it itself;
+     * its refusal ({@link UNSANDBOXED_NOT_ALLOWED_MESSAGE}) becomes the same error.
+     */
     exec(h: SandboxHandle, args: Parameters<SandboxProvider["exec"]>[1]): Promise<ExecResult>;
     readFile(h: SandboxHandle, path: string, opts: {
         maxBytes: number;
@@ -84,6 +110,17 @@ export declare class LocalDeviceProvider implements SandboxProvider {
         size: number;
         isDir: boolean;
     } | null>;
-    /** The org's effective limits now (ruling R27); a deleted device is not found. */
+    /**
+     * The device's org and the limits of one exec now (ruling R27): the ceiling, capped at `dev` for
+     * an unattended run without the `tier:open` grant (`cap`, set only when the platform and the org
+     * would otherwise allow an unsandboxed command); `allowUnsandboxed` whether this command may run
+     * without a sandbox. A deleted device is not found. Refuses an unsandboxed machine the org does
+     * not allow (or such a run), see {@link exec}.
+     */
     private currentLimits;
+    /**
+     * The `device.unsandboxed_not_allowed` error (spec §4.3); for an unattended run refused only for
+     * its missing `tier:open` grant, the run's text, with the missing grant recorded on the task run.
+     */
+    private unsandboxedRefusal;
 }

package/dist/local-devices/local-device-provider.js

@@ -7,9 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+import { minTier, ToolError, UNSANDBOXED_NOT_ALLOWED_MESSAGE, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
+import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { deviceNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { TIER_OPEN_GRANT_KEY, UNATTENDED_UNSANDBOXED_ERROR } from "../schedules/unattended.js";
+import { grantsWithin, NetworkGrants, relayer } from "./network-grants.js";
 import { deviceOffline, LocalDeviceRelay } from "./relay.js";
 import { DeviceTargets, sameRoots } from "./targets.js";
 /** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
@@ -25,6 +30,16 @@ export const FRAME_ENVELOPE_BYTES = 64 * 1024;
 /** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
 export const maxReadBytes = (maxFrameBytes) => Math.max(0, Math.floor((maxFrameBytes - FRAME_ENVELOPE_BYTES) / 4) * 3);
 const NAME_PREFIX = "cap-device-";
+/**
+ * The tool error of a device that runs commands without a sandbox the org does not allow (§4.3);
+ * also what a machine answers when it refuses such a command itself.
+ */
+export const UNSANDBOXED_NOT_ALLOWED_ERROR = UNSANDBOXED_NOT_ALLOWED_MESSAGE;
+/**
+ * The relay's error for a machine that refused a command with {@link UNSANDBOXED_NOT_ALLOWED_MESSAGE}
+ * (a `policy` error: the relay prefixes the machine's message, `relay.ts`).
+ */
+const MACHINE_UNSANDBOXED_REFUSAL = `Refused by the machine's local policy: ${UNSANDBOXED_NOT_ALLOWED_MESSAGE}`;
 /** The device id of a `cap-device-<deviceId>` name; undefined for any other name. */
 export const deviceIdOfName = (name) => name.startsWith(NAME_PREFIX) && name.length > NAME_PREFIX.length
     ? name.slice(NAME_PREFIX.length)
@@ -46,13 +61,17 @@ let LocalDeviceProvider = class LocalDeviceProvider {
     targets;
     sandbox;
     config;
+    grants;
+    log;
     concurrentExec = true;
     sessionIsolation = false;
-    constructor(relay, targets, sandbox, config) {
+    constructor(relay, targets, sandbox, config, grants, log) {
         this.relay = relay;
         this.targets = targets;
         this.sandbox = sandbox;
         this.config = config;
+        this.grants = grants;
+        this.log = log;
     }
     async createFileSystem(args) {
         args.signal.throwIfAborted();
@@ -103,13 +122,36 @@ let LocalDeviceProvider = class LocalDeviceProvider {
     async killTagged(h, tags, signal) {
         await this.relay.call(h.id, "killTagged", { tags }, { deadlineMs: OP_DEADLINE_MS, signal });
     }
+    /**
+     * Runs the command on the machine with the org's limits now (ruling R27) and, for a command of a
+     * run, the hosts the kernel allows that run on this device beyond the local policy (network
+     * ask-to-allow spec §6.3; only those the org's limits admit, sent only when there are some). The device's report of refused hosts is re-layered
+     * against the limits this exec carried: the kernel never takes the device's word that the org
+     * allows a host (spec §4.1).
+     *
+     * The limits are the device's **ceiling** (sandbox dev tiers spec §4.2): `limits.tier` is the
+     * highest tier the org allows, its network that tier's, `defaultTier` the org's default (the
+     * device runs at `min(local tier ?? defaultTier, tier)`) and `devHosts` the dev hosts. A run of
+     * a scheduled task without a person and without the task's `tier:open` grant is capped at `dev`
+     * (spec §11.4). Before relaying, a machine that last reported running commands without a sandbox
+     * is refused when the org does not allow it, or for such a run (`device.unsandboxed_not_allowed`,
+     * spec §4.3). The kernel knows the local policy only from the last hello or policy op, so the
+     * same decision also travels in `limits.allowUnsandboxed` and the machine enforces it itself;
+     * its refusal ({@link UNSANDBOXED_NOT_ALLOWED_MESSAGE}) becomes the same error.
+     */
     async exec(h, args) {
         const { signal, ...rest } = args;
         signal.throwIfAborted();
-        const limits = await this.currentLimits(h.id);
+        const runId = rest.actor?.runId;
+        const { orgId, limits, cap } = await this.currentLimits(h.id, runId);
+        // the run's grants for this device, cut to what the org allows now
+        const grants = runId !== undefined
+            ? grantsWithin(await this.grants.forExec({ orgId, runId, deviceId: h.id }), limits)
+            : undefined;
         signal.throwIfAborted();
+        let result;
         try {
-            return await this.relay.call(h.id, "exec", { ...rest, limits }, { deadlineMs: args.timeoutMs + EXEC_DEADLINE_MARGIN_MS, signal });
+            result = await this.relay.call(h.id, "exec", { ...rest, limits, ...(grants !== undefined && { grants }) }, { deadlineMs: args.timeoutMs + EXEC_DEADLINE_MARGIN_MS, signal });
         }
         catch (e) {
             // the contract: an exec aborted after it was sent resolves with exitCode null (the relay
@@ -117,8 +159,19 @@ let LocalDeviceProvider = class LocalDeviceProvider {
             if (signal.aborted && e === signal.reason) {
                 return { exitCode: null, stdout: "", stderr: "", truncated: false, timedOut: false };
             }
+            // the machine refused to run it unsandboxed (its local policy changed since it reported)
+            if (e instanceof ToolError && e.message === MACHINE_UNSANDBOXED_REFUSAL) {
+                this.log.warn("the machine refused a command without a sandbox", {
+                    deviceId: h.id,
+                    reason: cap !== undefined ? "unattended" : "not_allowed",
+                });
+                throw await this.unsandboxedRefusal(h.id, cap);
+            }
             throw e;
         }
+        if (result.network?.blocked === undefined)
+            return result;
+        return { ...result, network: { blocked: relayer(result.network.blocked, limits) } };
     }
     async readFile(h, path, opts) {
         // the answer must fit one frame: a larger file comes back truncated (Deliver: too large)
@@ -133,12 +186,59 @@ let LocalDeviceProvider = class LocalDeviceProvider {
     async stat(h, path, signal) {
         return this.relay.call(h.id, "stat", { path }, { deadlineMs: OP_DEADLINE_MS, signal });
     }
-    /** The org's effective limits now (ruling R27); a deleted device is not found. */
-    async currentLimits(deviceId) {
+    /**
+     * The device's org and the limits of one exec now (ruling R27): the ceiling, capped at `dev` for
+     * an unattended run without the `tier:open` grant (`cap`, set only when the platform and the org
+     * would otherwise allow an unsandboxed command); `allowUnsandboxed` whether this command may run
+     * without a sandbox. A deleted device is not found. Refuses an unsandboxed machine the org does
+     * not allow (or such a run), see {@link exec}.
+     */
+    async currentLimits(deviceId, runId) {
         const orgId = await this.targets.orgOf(deviceId);
         if (orgId === null)
             throw deviceNotFound();
-        return this.sandbox.orgLimits(orgId);
+        const [policy, unattended, unsandboxed] = await Promise.all([
+            this.sandbox.devicePolicy({ orgId, deviceId }),
+            runId === undefined ? null : this.grants.unattendedTier({ runId, deviceId }),
+            this.grants.unsandboxed(deviceId),
+        ]);
+        const capped = unattended !== null && !unattended.openGranted;
+        // what an unsandboxed refusal reports: the run's missing grant only when it alone refused
+        const cap = capped && policy.allowUnsandboxed ? { taskRunId: unattended.taskRunId } : undefined;
+        if (unsandboxed && (!policy.allowUnsandboxed || capped)) {
+            this.log.warn("command refused on a device that runs without a sandbox", {
+                deviceId,
+                reason: policy.allowUnsandboxed ? "unattended" : "not_allowed",
+            });
+            throw await this.unsandboxedRefusal(deviceId, cap);
+        }
+        const tier = capped ? minTier(policy.ceiling, "dev") : policy.ceiling;
+        const limits = await this.sandbox.deviceLimits({ orgId, deviceId }, { policy, tier });
+        return {
+            orgId,
+            limits: {
+                ...limits,
+                defaultTier: minTier(policy.defaultTier, tier),
+                // the platform and the org allow it (which needs an open ceiling) and no cap applies
+                allowUnsandboxed: policy.allowUnsandboxed && !capped,
+            },
+            cap,
+        };
+    }
+    /**
+     * The `device.unsandboxed_not_allowed` error (spec §4.3); for an unattended run refused only for
+     * its missing `tier:open` grant, the run's text, with the missing grant recorded on the task run.
+     */
+    async unsandboxedRefusal(deviceId, cap) {
+        if (cap === undefined) {
+            return new ApiError("device.unsandboxed_not_allowed", UNSANDBOXED_NOT_ALLOWED_ERROR);
+        }
+        await this.grants
+            .recordMissing(cap.taskRunId, TIER_OPEN_GRANT_KEY)
+            .catch((err) => this.log.warn("cannot record a missing task grant", { deviceId, err }));
+        return new ApiError("device.unsandboxed_not_allowed", UNATTENDED_UNSANDBOXED_ERROR, [
+            { reason: "unattended" },
+        ]);
     }
 };
 LocalDeviceProvider = __decorate([
@@ -146,6 +246,8 @@ LocalDeviceProvider = __decorate([
     __param(0, Inject(LocalDeviceRelay)),
     __param(1, Inject(DeviceTargets)),
     __param(2, Inject(SandboxService)),
-    __param(3, Inject(KernelConfigService))
+    __param(3, Inject(KernelConfigService)),
+    __param(4, Inject(NetworkGrants)),
+    __param(5, Inject(KERNEL_LOGGER))
 ], LocalDeviceProvider);
 export { LocalDeviceProvider };

package/dist/local-devices/local-devices.module.d.ts

@@ -4,7 +4,8 @@ import { LocalDeviceProvider } from "./local-device-provider.js";
 /**
  * Connected machines (environments spec §6, §13): the caller side of the device relay and the
  * kernel-internal `@local` sandbox provider, registered with {@link SandboxProviders} on init, and
- * the machines and their credentials ({@link MachinesService}).
+ * the machines and their credentials ({@link MachinesService}), changes to a device's network
+ * policy ({@link DevicePolicyService}) and the run grants sent with each exec ({@link NetworkGrants}).
  * Imported on every role: any replica may run a sandbox operation on a local device
  * (the socket itself is held by the gateway role).
  */

package/dist/local-devices/local-devices.module.js

@@ -10,14 +10,17 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Module } from "@nestjs/common";
 import { LOCAL_PROVIDER, SandboxProviders } from "../sandbox/providers.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { DevicePolicyService } from "./device-policy.service.js";
 import { LocalDeviceProvider } from "./local-device-provider.js";
 import { MachinesService } from "./machines.js";
+import { NetworkGrants } from "./network-grants.js";
 import { LocalDeviceRelay } from "./relay.js";
 import { DeviceTargets } from "./targets.js";
 /**
  * Connected machines (environments spec §6, §13): the caller side of the device relay and the
  * kernel-internal `@local` sandbox provider, registered with {@link SandboxProviders} on init, and
- * the machines and their credentials ({@link MachinesService}).
+ * the machines and their credentials ({@link MachinesService}), changes to a device's network
+ * policy ({@link DevicePolicyService}) and the run grants sent with each exec ({@link NetworkGrants}).
  * Imported on every role: any replica may run a sandbox operation on a local device
  * (the socket itself is held by the gateway role).
  */
@@ -35,8 +38,21 @@ let LocalDevicesModule = class LocalDevicesModule {
 LocalDevicesModule = __decorate([
     Module({
         imports: [SandboxModule],
-        providers: [DeviceTargets, LocalDeviceRelay, LocalDeviceProvider, MachinesService],
-        exports: [LocalDeviceRelay, LocalDeviceProvider, MachinesService],
+        providers: [
+            DeviceTargets,
+            LocalDeviceRelay,
+            LocalDeviceProvider,
+            MachinesService,
+            DevicePolicyService,
+            NetworkGrants,
+        ],
+        exports: [
+            LocalDeviceRelay,
+            LocalDeviceProvider,
+            MachinesService,
+            DevicePolicyService,
+            NetworkGrants,
+        ],
     }),
     __param(0, Inject(SandboxProviders)),
     __param(1, Inject(LocalDeviceProvider))