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

package/dist/inbox/inbox.service.d.ts

@@ -1,5 +1,6 @@
 import { CatalogRequestsService, type CatalogRequestView } from "../catalog/requests.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
+import { type ScheduleAttention, ScheduledTasksService } from "../schedules/scheduled-tasks.service.js";
 import { SkillChangesService, type SkillChangeView } from "../skills/changes.service.js";
 import { ApprovalsService, type ApprovalView } from "../tools/approvals.service.js";
 import type { OrgNoticeDetails } from "./org-notices.js";
@@ -40,11 +41,16 @@ export declare const INBOX_MAX_ITEMS = 100;
  * - `tool_approval`：当前用户能处理的待处理工具调用审批（与 `GET /approvals?status=pending` 同一视图）；
  * - `skill_change`: pending skill share requests and proposed versions of shared skills, when the
  *   current user is an org admin (`skillChange.kind`; spec §5.4, §5.5);
- * - `catalog_request`: pending `enable` requests from members and pending `connector_setup`
- *   requests (`request.kind`; `request.agent` and `request.connectors` set, `item` null; ruling
- *   P4-T6-5), when the current user is an org admin (M6 T26, C22; plugin scope spec §5.1);
+ * - `catalog_request`: pending `enable` and `network_allowlist` requests from members and pending
+ *   `connector_setup` requests (`request.kind`; for `connector_setup` `request.agent` and
+ *   `request.connectors` set, `item` null, ruling P4-T6-5; for `network_allowlist`
+ *   `request.network` set, network ask-to-allow spec §5.3), when the current user is an org admin
+ *   (M6 T26, C22; plugin scope spec §5.1);
  * - `catalog_request_decided`: the current user's own requests in this org that were approved or
  *   rejected (with the reason), until dismissed (`POST catalog-requests/:id/dismiss`);
+ * - `schedule_attention`: the current user's own scheduled task that needs them (spec §8): paused
+ *   for any reason but their own pause, its latest run failed, or its latest run was refused tools
+ *   or connections; derived live, gone once the task is resumed or runs clean;
  * - the org notices (`skill_renamed`, `item_shared`, `shared_item_updated`, `upload_confirmed`,
  *   `upload_rejected`; `type` = the notice's kind): for org admins, until one dismisses it
  *   (`POST inbox/notices/:id/dismiss`).
@@ -70,12 +76,20 @@ export type InboxItem = {
     /** When it was decided. */
     createdAt: string;
     request: CatalogRequestView;
+} | {
+    type: "schedule_attention";
+    /** `<taskId>:paused`, `<taskId>:failed` or `<taskId>:grants`. */
+    id: string;
+    createdAt: string;
+    attention: ScheduleAttentionView;
 } | {
     type: OrgNoticeView["kind"];
     id: string;
     createdAt: string;
     notice: OrgNoticeView;
 };
+/** A scheduled task that needs its creator ({@link ScheduleAttention}, dates as ISO strings). */
+export type ScheduleAttentionView = Omit<ScheduleAttention, "at">;
 /** `GET /inbox` 的结果：新的在前，最多 {@link INBOX_MAX_ITEMS} 项；`truncated` 为 true 表示还有更多。 */
 export interface InboxView {
     items: InboxItem[];
@@ -87,7 +101,8 @@ export declare class InboxService {
     private readonly skillChanges;
     private readonly kdb;
     private readonly catalogRequests;
-    constructor(approvals: Pick<ApprovalsService, "list">, skillChanges: Pick<SkillChangesService, "listPending">, kdb: KernelDb, catalogRequests: Pick<CatalogRequestsService, "listForOrgAdmin" | "listDecidedForRequester">);
+    private readonly schedules;
+    constructor(approvals: Pick<ApprovalsService, "list">, skillChanges: Pick<SkillChangesService, "listPending">, kdb: KernelDb, catalogRequests: Pick<CatalogRequestsService, "listForOrgAdmin" | "listDecidedForRequester">, schedules: Pick<ScheduledTasksService, "attentionFor">);
     list(orgId: string, accountId: string): Promise<InboxView>;
     /** The org's open notices when the account is an org admin (else none), newest first. */
     private notices;

package/dist/inbox/inbox.service.js

@@ -13,6 +13,7 @@ import { CATALOG_REQUESTS_LIST_MAX, CatalogRequestsService, } from "../catalog/r
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { roleAtLeast } from "../orgs/roles.js";
+import { ScheduledTasksService, } from "../schedules/scheduled-tasks.service.js";
 import { SKILL_CHANGES_LIST_MAX, SkillChangesService, } from "../skills/changes.service.js";
 import { APPROVALS_LIST_MAX, ApprovalsService, } from "../tools/approvals.service.js";
 /** The most open org notices one inbox read returns. */
@@ -25,19 +26,22 @@ let InboxService = class InboxService {
     skillChanges;
     kdb;
     catalogRequests;
-    constructor(approvals, skillChanges, kdb, catalogRequests) {
+    schedules;
+    constructor(approvals, skillChanges, kdb, catalogRequests, schedules) {
         this.approvals = approvals;
         this.skillChanges = skillChanges;
         this.kdb = kdb;
         this.catalogRequests = catalogRequests;
+        this.schedules = schedules;
     }
     async list(orgId, accountId) {
-        const [approvals, changes, requests, decided, notices] = await Promise.all([
+        const [approvals, changes, requests, decided, notices, attention] = await Promise.all([
             this.approvals.list(orgId, accountId, "pending"),
             this.skillChanges.listPending(orgId, accountId),
             this.catalogRequests.listForOrgAdmin(orgId, accountId),
             this.catalogRequests.listDecidedForRequester(orgId, accountId),
             this.notices(orgId, accountId),
+            this.schedules.attentionFor(orgId, accountId),
         ]);
         const all = [
             ...approvals.map((a) => ({
@@ -64,6 +68,12 @@ let InboxService = class InboxService {
                 createdAt: r.decidedAt ?? r.createdAt,
                 request: r,
             })),
+            ...attention.map(({ at, ...view }) => ({
+                type: "schedule_attention",
+                id: `${view.taskId}:${view.reason === "missing_grants" ? "grants" : view.reason === "failed" ? "failed" : "paused"}`,
+                createdAt: at.toISOString(),
+                attention: view,
+            })),
             ...notices.map((n) => ({ type: n.kind, id: n.id, createdAt: n.createdAt, notice: n })),
         ];
         // 新的在前；同一时刻按 id 定序（结果稳定）
@@ -142,7 +152,8 @@ InboxService = __decorate([
     __param(0, Inject(ApprovalsService)),
     __param(1, Inject(SkillChangesService)),
     __param(2, Inject(KernelDb)),
-    __param(3, Inject(CatalogRequestsService))
+    __param(3, Inject(CatalogRequestsService)),
+    __param(4, Inject(ScheduledTasksService))
 ], InboxService);
 export { InboxService };
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

package/dist/infra/config/kernel-config.service.js

@@ -33,6 +33,10 @@ const HOT_APPLIERS = {
     "models.embedTimeoutMs": () => { },
     // SandboxService reads the shared-lease cap at every acquisition.
     "sandbox.maxConcurrentCommands": () => { },
+    // Sandbox tiers are read at every device use, org settings read and Platform call.
+    "sandbox.tiers.max": () => { },
+    "sandbox.tiers.default": () => { },
+    "sandbox.tiers.allowUnsandboxed": () => { },
     // The devices service reads the personal limit at every create.
     "devices.maxPersonal": () => { },
     // The local device relay reads the reconnect grace at every disconnect and token response.
@@ -48,6 +52,13 @@ const HOT_APPLIERS = {
     "web.fetch.maxAnswerTokens": () => { },
     "web.fetch.cacheSeconds": () => { },
     "web.fetch.timeoutMs": () => { },
+    // Scheduled-task settings are clamped to these bounds on every read.
+    "schedules.minIntervalFloorMinutes": () => { },
+    "schedules.maxTasksPerMemberCap": () => { },
+    "schedules.maxTasksPerOrgCap": () => { },
+    "schedules.maxRunsPerHourCap": () => { },
+    // Run start reads the skills catalog budget when it records a snapshot.
+    "skills.catalogBudgetChars": () => { },
 };
 /**
  * Environment variables of renamed config keys, with their replacements: warned about once when

package/dist/infra/events/kernel-events.d.ts

@@ -31,7 +31,8 @@ export interface KernelEventMap {
         orgId: string;
         conversationId: string;
         runId: string;
-        status: "approved" | "denied";
+        /** `skipped`: a network ask closed by the run's starter's message (network ask-to-allow §6.7). */
+        status: "approved" | "denied" | "skipped";
     };
     /**
      * A person answered a tool call's input request, or skipped it with a message (after the commit,

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;
 }