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

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

@@ -1,4 +1,4 @@
-import type { DeviceHello, DeviceStopArgs, ExtensionContext } from "@capybara-hq/plugin-sdk";
+import type { DeviceFeature, DeviceHello, DeviceLocalPolicySummary, DeviceStopArgs, ExtensionContext } 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";
@@ -23,6 +23,10 @@ export interface ActiveMachine {
     programVersion: string | null;
     lastSeenAt: Date | null;
     createdAt: Date;
+    /** The features its program reported in its last hello (known ones only). */
+    features: DeviceFeature[];
+    /** Its local network policy as last reported (hello or `policy` op); null when unknown. */
+    localPolicy: DeviceLocalPolicySummary | null;
 }
 /**
  * Connected machines and their credentials (environments spec §13.2). One active machine per
@@ -83,9 +87,32 @@ export declare class MachinesService {
      * {@link issue} already counted the reset) but serves another directory or mode (other roots,
      * ruling R23), the device's files are other files: `fs_resets` moves on (maintainer
      * decision 2026-11-08), so conversations get the files-reset notice. A previous machine that
-     * never said hello has no known roots: nothing to compare.
+     * never said hello has no known roots: nothing to compare. The reported features (known ones
+     * only) and local policy summary (null when absent or malformed) replace the stored ones, so a
+     * program downgraded to one without them is no longer sent what it cannot do. A summary the
+     * kernel cannot read (`hello.policy` dropped by the frame parser) is kept as its isolation
+     * alone, read from `rawPolicy` (the frame's raw `policy`; {@link isolationOf}: anything but
+     * `sandbox` is `none`), so it never hides that commands run without a sandbox. A reported
+     * isolation that differs from the stored one (none stored counts as `sandbox`) is audited
+     * `device.isolation_reported` (sandbox dev tiers spec §10.4), once per change.
      */
-    recordHello(machineId: string, hello: DeviceHello): Promise<void>;
+    recordHello(machineId: string, hello: DeviceHello, rawPolicy?: unknown): Promise<void>;
+    /**
+     * Stores the local policy summary a connected program pushed after its hello (a `policy` frame:
+     * its policy file changed on the machine, its localhost proxy guard flipped, a new tier
+     * ceiling), read and audited as the hello's ({@link recordHello}): an unreadable summary keeps
+     * its isolation alone (`rawPolicy`), a changed isolation is audited `device.isolation_reported`.
+     * The next sandbox call then records a new `device_paths` event when the facts the model is told
+     * changed. A revoked machine is left alone.
+     */
+    recordPolicy(machineId: string, summary: DeviceLocalPolicySummary | undefined, rawPolicy?: unknown): Promise<void>;
+    /**
+     * The summary to store for one a program reported (hello or `policy` frame): the parsed one,
+     * else its raw isolation alone, else null. Audits `device.isolation_reported` when the isolation
+     * differs from the stored one (none stored counts as `sandbox`). Runs in the caller's
+     * transaction, with the machine's row locked.
+     */
+    private reportedPolicy;
     /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
     touch(machineId: string): Promise<void>;
     /**

package/dist/local-devices/machines.js

@@ -20,6 +20,7 @@ import { KERNEL_BUS, KERNEL_LOGGER } from "../infra/tokens.js";
 import { LOCAL_PROVIDER } from "../sandbox/providers.js";
 import { deviceNotFound } from "../sandbox/sandbox.service.js";
 import { deviceRevokedTopic } from "./keys.js";
+import { deviceFeaturesOf, isolationOf, localPolicyOf } from "./policy-summary.js";
 import { LocalDeviceRelay } from "./relay.js";
 /** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
 export const MACHINE_CREDENTIAL_PREFIX = "cap_dev_";
@@ -154,12 +155,29 @@ let MachinesService = class MachinesService {
      * {@link issue} already counted the reset) but serves another directory or mode (other roots,
      * ruling R23), the device's files are other files: `fs_resets` moves on (maintainer
      * decision 2026-11-08), so conversations get the files-reset notice. A previous machine that
-     * never said hello has no known roots: nothing to compare.
+     * never said hello has no known roots: nothing to compare. The reported features (known ones
+     * only) and local policy summary (null when absent or malformed) replace the stored ones, so a
+     * program downgraded to one without them is no longer sent what it cannot do. A summary the
+     * kernel cannot read (`hello.policy` dropped by the frame parser) is kept as its isolation
+     * alone, read from `rawPolicy` (the frame's raw `policy`; {@link isolationOf}: anything but
+     * `sandbox` is `none`), so it never hides that commands run without a sandbox. A reported
+     * isolation that differs from the stored one (none stored counts as `sandbox`) is audited
+     * `device.isolation_reported` (sandbox dev tiers spec §10.4), once per change.
      */
-    async recordHello(machineId, hello) {
+    async recordHello(machineId, hello, rawPolicy = hello.policy) {
         const self = await this.db
             .selectFrom("device_machines")
-            .select(["device_id", "name", "os", "arch", "roots", "created_at"])
+            .select([
+            "device_id",
+            "org_id",
+            "account_id",
+            "name",
+            "os",
+            "arch",
+            "roots",
+            "created_at",
+            "local_policy",
+        ])
             .where("id", "=", machineId)
             .where("revoked_at", "is", null)
             .forUpdate()
@@ -189,6 +207,7 @@ let MachinesService = class MachinesService {
                     .execute();
             }
         }
+        const policy = await this.reportedPolicy(machineId, self, hello.policy, rawPolicy);
         await this.db
             .updateTable("device_machines")
             .set({
@@ -198,12 +217,61 @@ let MachinesService = class MachinesService {
             mode: hello.mode,
             roots: JSON.stringify(hello.roots),
             session_isolation: hello.sessionIsolation,
+            features: deviceFeaturesOf(hello.features),
+            local_policy: jsonOrNull(policy),
             last_seen_at: sql `now()`,
         })
             .where("id", "=", machineId)
             .where("revoked_at", "is", null)
             .execute();
     }
+    /**
+     * Stores the local policy summary a connected program pushed after its hello (a `policy` frame:
+     * its policy file changed on the machine, its localhost proxy guard flipped, a new tier
+     * ceiling), read and audited as the hello's ({@link recordHello}): an unreadable summary keeps
+     * its isolation alone (`rawPolicy`), a changed isolation is audited `device.isolation_reported`.
+     * The next sandbox call then records a new `device_paths` event when the facts the model is told
+     * changed. A revoked machine is left alone.
+     */
+    async recordPolicy(machineId, summary, rawPolicy = summary) {
+        const self = await this.db
+            .selectFrom("device_machines")
+            .select(["device_id", "org_id", "account_id", "local_policy"])
+            .where("id", "=", machineId)
+            .where("revoked_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (self === undefined)
+            return;
+        const policy = await this.reportedPolicy(machineId, self, summary, rawPolicy);
+        await this.db
+            .updateTable("device_machines")
+            .set({ local_policy: jsonOrNull(policy), last_seen_at: sql `now()` })
+            .where("id", "=", machineId)
+            .where("revoked_at", "is", null)
+            .execute();
+    }
+    /**
+     * The summary to store for one a program reported (hello or `policy` frame): the parsed one,
+     * else its raw isolation alone, else null. Audits `device.isolation_reported` when the isolation
+     * differs from the stored one (none stored counts as `sandbox`). Runs in the caller's
+     * transaction, with the machine's row locked.
+     */
+    async reportedPolicy(machineId, self, reported, rawPolicy) {
+        const summary = localPolicyOf(reported);
+        const isolation = summary?.isolation ?? isolationOf(rawPolicy);
+        const before = isolationOf(self.local_policy) ?? "sandbox";
+        if (isolation !== null && isolation !== before) {
+            await audit(this.db.db, {
+                actorAccountId: self.account_id,
+                orgId: self.org_id,
+                action: "device.isolation_reported",
+                target: self.device_id,
+                detail: { machineId, isolation, previous: before },
+            });
+        }
+        return summary ?? (isolation === null ? null : { isolation });
+    }
     /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
     async touch(machineId) {
         await this.db
@@ -302,6 +370,8 @@ let MachinesService = class MachinesService {
             "program_version",
             "last_seen_at",
             "created_at",
+            "features",
+            "local_policy",
         ])
             .where("device_id", "=", deviceId)
             .where("revoked_at", "is", null)
@@ -317,6 +387,8 @@ let MachinesService = class MachinesService {
                 programVersion: r.program_version,
                 lastSeenAt: r.last_seen_at,
                 createdAt: r.created_at,
+                features: deviceFeaturesOf(r.features),
+                localPolicy: localPolicyOf(r.local_policy),
             }
             : null;
     }
@@ -348,6 +420,9 @@ __decorate([
 __decorate([
     Transactional()
 ], MachinesService.prototype, "recordHello", null);
+__decorate([
+    Transactional()
+], MachinesService.prototype, "recordPolicy", null);
 __decorate([
     Transactional()
 ], MachinesService.prototype, "revoke", null);
@@ -360,6 +435,7 @@ MachinesService = __decorate([
     __param(4, Inject(KERNEL_LOGGER))
 ], MachinesService);
 export { MachinesService };
+const jsonOrNull = (v) => (v === null ? null : JSON.stringify(v));
 /** Two machine rows (or a login) name the same machine: same name, OS and arch. */
 function sameMachine(a, b) {
     return a.name === b.name && a.os === b.os && a.arch === b.arch;

package/dist/local-devices/network-grants.d.ts

@@ -0,0 +1,104 @@
+import { type DeviceExecGrants, type NetworkBlockedHost, type SandboxLimits } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+/** The most hosts one exec's grants carry (the device protocol's limit). */
+export declare const MAX_GRANT_HOSTS = 100;
+/** What a run tree's network asks add up to (network ask-to-allow spec §6.8). */
+export interface NetworkRunState {
+    /** Hosts allowed for the rest of the run tree (「这次允许」). */
+    granted: Set<string>;
+    /** Hosts refused in the run tree (denied, expired, skipped, cancelled, or unchecked): never asked again. */
+    refused: Set<string>;
+    /** Network asks of this run (the per-run cap counts them). */
+    asks: number;
+    /** A network ask of the run tree is still pending (at most one at a time). */
+    pending: boolean;
+    /**
+     * Hosts the scheduled task the run serves approves on this device (spec §8.1; unattended runs
+     * only, read only with a `deviceId`): never asked about nor recorded as missing. Absent: none.
+     */
+    taskGranted?: Set<string>;
+}
+/**
+ * Network hosts the kernel allows a run beyond a device's local policy (network ask-to-allow spec
+ * §6.3): the hosts of the run tree's approved `network` asks with scope `once` (「这次允许」), read
+ * from PG for every exec, so a grant decided on one replica reaches a command on any other. A run
+ * tree is the runs of one budget window (`runs.budget_run_id` lineage): a sub-agent's run sees the
+ * root's grants, another run tree never does. The hosts a decision allowed are its
+ * `detail.grantedHosts`; a decision without them grants nothing. In an unattended run of a
+ * scheduled task, the task's `network:<host>` grants (spec §8.1) join them.
+ */
+export declare class NetworkGrants {
+    private readonly db;
+    constructor(db: KernelDb);
+    /**
+     * Hosts allowed for this exec on `deviceId`: the run tree's once-approved network asks in
+     * `orgId` about that device, while the tree's root run has not ended (a grant ends with its run;
+     * a later run of the same budget window does not inherit it), with the root run as their source
+     * and the latest decider as its account; and in an unattended run of a scheduled task, the
+     * task's network grants (spec §8.1) when the device is its creator's, with the task as their
+     * source and the creator as its account. Both together are one grant: the hosts of both, the
+     * task as the source. Undefined when none. The device applies them only when its owner allows
+     * remote grants and only within the org's limits.
+     */
+    forExec(input: {
+        orgId: string;
+        runId: string;
+        deviceId: string;
+    }): Promise<DeviceExecGrants | undefined>;
+    /**
+     * The run tree's network asks (spec §6.8): what was granted and refused, the run's asks, a
+     * pending ask. With `deviceId`, granted and refused count only the asks about that device (a
+     * host allowed on one device is not allowed on another); the cap and the pending ask count all.
+     */
+    runState(runId: string, deviceId?: string): Promise<NetworkRunState>;
+    /** The run tree's once-approved hosts as exec grants (source: the root run). */
+    private runGrants;
+    /**
+     * A scheduled task's network grants for an unattended run (spec §8.1): the task's
+     * `network:<host>` grants when the run serves a task run that is no trial run and no person
+     * joined (`taskGrantsRunOf`, inherited by its sub-agents), the task is of `orgId` (when given)
+     * and `deviceId` is a live device of the task's org owned by the task's creator (a creator
+     * approves domains for their own devices only). Exact valid hosts only.
+     */
+    private taskGrants;
+    /**
+     * The tier rule of an unattended run on `deviceId` (sandbox dev tiers spec §11.4), read fresh:
+     * null for an attended run; otherwise the task run and whether the task grants `tier:open` on
+     * this device (`unattendedTierOf`).
+     */
+    unattendedTier(input: {
+        runId: string;
+        deviceId: string;
+    }): Promise<{
+        taskRunId: string;
+        openGranted: boolean;
+    } | null>;
+    /** Records `key` in the task run's `missing_grants` (once). */
+    recordMissing(taskRunId: string, key: string): Promise<void>;
+    /**
+     * Whether the device's active machine runs commands without a sandbox
+     * (`device_machines.local_policy.isolation`, read fresh at each exec, spec §4.3), read from the
+     * stored JSON's isolation field alone ({@link isolationOf}). Fails closed for a program that
+     * applies tiers (feature `tiers`, which always sends a summary): no summary or any isolation but
+     * `sandbox` counts as unsandboxed. False without a machine, or for an older program without
+     * tiers (it has no unsandboxed mode).
+     */
+    unsandboxed(deviceId: string): Promise<boolean>;
+    /** The runs of the tree whose budget run is `root`. */
+    private treeOf;
+}
+/** Whether the org's effective egress lets a command reach `host`. */
+export declare function orgAllows(host: string, limits: Pick<SandboxLimits, "egress" | "allowHosts">): boolean;
+/**
+ * The kernel's own layer for a device's report (spec §4.1 item 3): it trusts the device's word that
+ * a host was refused, never its word that the org allows it. A host the device calls `device` that
+ * the org's effective egress (`limits`, read for this exec) does not allow becomes `org`; one that
+ * is no valid host name becomes `address`. Other layers are kept.
+ */
+export declare function relayer(blocked: NetworkBlockedHost[], limits: Pick<SandboxLimits, "egress" | "allowHosts">): NetworkBlockedHost[];
+/**
+ * `grants` cut to the hosts the org's effective egress (`limits`, read for this exec) admits, or
+ * undefined when none is left. The device intersects them with the limits too; the kernel does
+ * it first so a grant never reaches a device beyond what the org allows.
+ */
+export declare function grantsWithin(grants: DeviceExecGrants | undefined, limits: Pick<SandboxLimits, "egress" | "allowHosts">): DeviceExecGrants | undefined;

package/dist/local-devices/network-grants.js

@@ -0,0 +1,288 @@
+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 { validateAllowHost, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { budgetRunOf } from "../runtime/subagents/limits.js";
+import { appendMissingGrant, taskGrantsRunOf, unattendedTierOf } from "../schedules/unattended.js";
+import { deviceFeaturesOf, isolationOf } from "./policy-summary.js";
+/** The most hosts one exec's grants carry (the device protocol's limit). */
+export const MAX_GRANT_HOSTS = 100;
+/** The key prefix of a scheduled task's network grant (`schedules/grant-rules.ts`). */
+const NETWORK_KEY_PREFIX = "network:";
+/** The statuses of a run that has not ended: its run grants still apply. */
+const LIVE_RUN = ["queued", "running", "waiting"];
+/** The statuses of a network ask that refuse its hosts for the rest of the run tree (§6.8). */
+const REFUSING = new Set(["denied", "expired", "skipped", "cancelled"]);
+/** An exact host a grant may carry: no wildcard, valid. */
+const exactHost = (h) => typeof h === "string" && !h.startsWith("*.") && validateAllowHost(h).length === 0;
+/** `detail.deviceId` of a network ask: the device it asked about. */
+function deviceOf(detail) {
+    const d = detail?.deviceId;
+    return typeof d === "string" ? d : undefined;
+}
+/** `detail.grantedHosts` of a decided network ask: what the decision allowed (absent: none). */
+function grantedOf(detail) {
+    const g = detail?.grantedHosts;
+    return Array.isArray(g) ? g.filter(exactHost) : [];
+}
+/** `detail.hosts[].host` of a network ask: what it asked about. */
+function askedOf(detail) {
+    const hs = detail?.hosts;
+    if (!Array.isArray(hs))
+        return [];
+    return hs.flatMap((h) => {
+        const host = h?.host;
+        return typeof host === "string" ? [host] : [];
+    });
+}
+/**
+ * Network hosts the kernel allows a run beyond a device's local policy (network ask-to-allow spec
+ * §6.3): the hosts of the run tree's approved `network` asks with scope `once` (「这次允许」), read
+ * from PG for every exec, so a grant decided on one replica reaches a command on any other. A run
+ * tree is the runs of one budget window (`runs.budget_run_id` lineage): a sub-agent's run sees the
+ * root's grants, another run tree never does. The hosts a decision allowed are its
+ * `detail.grantedHosts`; a decision without them grants nothing. In an unattended run of a
+ * scheduled task, the task's `network:<host>` grants (spec §8.1) join them.
+ */
+let NetworkGrants = class NetworkGrants {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Hosts allowed for this exec on `deviceId`: the run tree's once-approved network asks in
+     * `orgId` about that device, while the tree's root run has not ended (a grant ends with its run;
+     * a later run of the same budget window does not inherit it), with the root run as their source
+     * and the latest decider as its account; and in an unattended run of a scheduled task, the
+     * task's network grants (spec §8.1) when the device is its creator's, with the task as their
+     * source and the creator as its account. Both together are one grant: the hosts of both, the
+     * task as the source. Undefined when none. The device applies them only when its owner allows
+     * remote grants and only within the org's limits.
+     */
+    async forExec(input) {
+        const run = await this.runGrants(input);
+        const task = await this.taskGrants(input);
+        if (task === undefined)
+            return run;
+        if (run === undefined)
+            return task;
+        // one exec frame carries one source: the task's, the standing approval behind an unattended
+        // run (the run grants of an unattended run come from asks only in `wait` mode); the device
+        // logs it with the command, and the kernel's approvals keep the per-host record
+        const hosts = [...new Set([...task.hosts, ...run.hosts])].slice(0, MAX_GRANT_HOSTS);
+        return { hosts, source: task.source };
+    }
+    /**
+     * The run tree's network asks (spec §6.8): what was granted and refused, the run's asks, a
+     * pending ask. With `deviceId`, granted and refused count only the asks about that device (a
+     * host allowed on one device is not allowed on another); the cap and the pending ask count all.
+     */
+    async runState(runId, deviceId) {
+        const task = deviceId === undefined ? undefined : await this.taskGrants({ runId, deviceId });
+        const root = await budgetRunOf(this.db.db, runId);
+        const rows = await this.db
+            .selectFrom("approvals")
+            .select(["run_id", "status", "scope", "detail"])
+            .where("kind", "=", "network")
+            .where("run_id", "in", this.treeOf(root))
+            .execute();
+        const state = {
+            granted: new Set(),
+            refused: new Set(),
+            asks: 0,
+            pending: false,
+        };
+        for (const r of rows) {
+            if (r.run_id === runId)
+                state.asks++;
+            if (r.status === "pending") {
+                state.pending = true;
+            }
+            else if (deviceId !== undefined && deviceOf(r.detail) !== deviceId) {
+                // another device's decision says nothing about this one
+            }
+            else if (r.status === "approved") {
+                const granted = grantedOf(r.detail);
+                if (r.scope === "once")
+                    for (const h of granted)
+                        state.granted.add(h);
+                // the hosts left unchecked in a partial decision count as denied (P-D5)
+                for (const h of askedOf(r.detail))
+                    if (!granted.includes(h))
+                        state.refused.add(h);
+            }
+            else if (REFUSING.has(r.status)) {
+                for (const h of askedOf(r.detail))
+                    state.refused.add(h);
+            }
+        }
+        if (task !== undefined)
+            state.taskGranted = new Set(task.hosts);
+        return state;
+    }
+    /** The run tree's once-approved hosts as exec grants (source: the root run). */
+    async runGrants(input) {
+        const root = await budgetRunOf(this.db.db, input.runId);
+        const live = await this.db
+            .selectFrom("runs")
+            .select("id")
+            .where("id", "=", root)
+            .where("status", "in", LIVE_RUN)
+            .executeTakeFirst();
+        if (live === undefined)
+            return undefined;
+        const rows = await this.db
+            .selectFrom("approvals")
+            .select(["decided_by", "detail"])
+            .where("kind", "=", "network")
+            .where("org_id", "=", input.orgId)
+            .where("status", "=", "approved")
+            .where("scope", "=", "once")
+            .where("decided_by", "is not", null)
+            .where(sql `detail->>'deviceId'`, "=", input.deviceId)
+            .where("run_id", "in", this.treeOf(root))
+            .orderBy("decided_at", "desc")
+            .orderBy("id", "desc")
+            .execute();
+        const hosts = [...new Set(rows.flatMap((r) => grantedOf(r.detail)))].slice(0, MAX_GRANT_HOSTS);
+        const latest = rows.find((r) => grantedOf(r.detail).length > 0);
+        if (hosts.length === 0 || latest?.decided_by == null)
+            return undefined;
+        return { hosts, source: { kind: "run", id: root, accountId: latest.decided_by } };
+    }
+    /**
+     * A scheduled task's network grants for an unattended run (spec §8.1): the task's
+     * `network:<host>` grants when the run serves a task run that is no trial run and no person
+     * joined (`taskGrantsRunOf`, inherited by its sub-agents), the task is of `orgId` (when given)
+     * and `deviceId` is a live device of the task's org owned by the task's creator (a creator
+     * approves domains for their own devices only). Exact valid hosts only.
+     */
+    async taskGrants(input) {
+        const task = await taskGrantsRunOf(this.db.db, input.runId);
+        if (task === null || (input.orgId !== undefined && task.orgId !== input.orgId)) {
+            return undefined;
+        }
+        const device = await this.db
+            .selectFrom("devices")
+            .select("id")
+            .where("id", "=", input.deviceId)
+            .where("org_id", "=", task.orgId)
+            .where("owner_account_id", "=", task.accountId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (device === undefined)
+            return undefined;
+        const rows = await this.db
+            .selectFrom("scheduled_task_grants")
+            .select("tool_key")
+            .where("task_id", "=", task.taskId)
+            .where("tool_key", "like", `${NETWORK_KEY_PREFIX}%`)
+            .orderBy("tool_key")
+            .execute();
+        const hosts = rows
+            .map((r) => r.tool_key.slice(NETWORK_KEY_PREFIX.length))
+            .filter(exactHost)
+            .slice(0, MAX_GRANT_HOSTS);
+        if (hosts.length === 0)
+            return undefined;
+        return { hosts, source: { kind: "task", id: task.taskId, accountId: task.accountId } };
+    }
+    /**
+     * The tier rule of an unattended run on `deviceId` (sandbox dev tiers spec §11.4), read fresh:
+     * null for an attended run; otherwise the task run and whether the task grants `tier:open` on
+     * this device (`unattendedTierOf`).
+     */
+    async unattendedTier(input) {
+        return await unattendedTierOf(this.db.db, input.runId, input.deviceId);
+    }
+    /** Records `key` in the task run's `missing_grants` (once). */
+    async recordMissing(taskRunId, key) {
+        await appendMissingGrant(this.db.db, taskRunId, key);
+    }
+    /**
+     * Whether the device's active machine runs commands without a sandbox
+     * (`device_machines.local_policy.isolation`, read fresh at each exec, spec §4.3), read from the
+     * stored JSON's isolation field alone ({@link isolationOf}). Fails closed for a program that
+     * applies tiers (feature `tiers`, which always sends a summary): no summary or any isolation but
+     * `sandbox` counts as unsandboxed. False without a machine, or for an older program without
+     * tiers (it has no unsandboxed mode).
+     */
+    async unsandboxed(deviceId) {
+        const row = await this.db
+            .selectFrom("device_machines")
+            .select(["local_policy", "features"])
+            .where("device_id", "=", deviceId)
+            .where("revoked_at", "is", null)
+            .executeTakeFirst();
+        if (row === undefined)
+            return false;
+        const isolation = isolationOf(row.local_policy);
+        if (isolation !== null)
+            return isolation === "none";
+        return deviceFeaturesOf(row.features).includes("tiers");
+    }
+    /** The runs of the tree whose budget run is `root`. */
+    treeOf(root) {
+        return this.db
+            .selectFrom("runs")
+            .select("id")
+            .where((eb) => eb.or([eb("id", "=", root), eb("budget_run_id", "=", root)]));
+    }
+};
+NetworkGrants = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], NetworkGrants);
+export { NetworkGrants };
+const normalize = (host) => {
+    const h = host.toLowerCase();
+    return h.endsWith(".") ? h.slice(0, -1) : h;
+};
+/** Whether the allowlist entry `pattern` admits `host` (`*.x.com`: subdomains, never the apex). */
+const covers = (pattern, host) => pattern === host || (pattern.startsWith("*.") && host.endsWith(pattern.slice(1)));
+/** Whether the org's effective egress lets a command reach `host`. */
+export function orgAllows(host, limits) {
+    if (limits.egress === "none")
+        return false;
+    if (limits.egress === "open")
+        return true;
+    const h = normalize(host);
+    return limits.allowHosts.some((p) => covers(p.toLowerCase(), h));
+}
+/**
+ * The kernel's own layer for a device's report (spec §4.1 item 3): it trusts the device's word that
+ * a host was refused, never its word that the org allows it. A host the device calls `device` that
+ * the org's effective egress (`limits`, read for this exec) does not allow becomes `org`; one that
+ * is no valid host name becomes `address`. Other layers are kept.
+ */
+export function relayer(blocked, limits) {
+    return blocked.map((b) => {
+        if (b.layer !== "device")
+            return b;
+        const h = normalize(b.host);
+        if (validateAllowHost(h).length > 0 || h.startsWith("*.")) {
+            return { ...b, layer: "address" };
+        }
+        return orgAllows(b.host, limits) ? b : { ...b, layer: "org" };
+    });
+}
+/**
+ * `grants` cut to the hosts the org's effective egress (`limits`, read for this exec) admits, or
+ * undefined when none is left. The device intersects them with the limits too; the kernel does
+ * it first so a grant never reaches a device beyond what the org allows.
+ */
+export function grantsWithin(grants, limits) {
+    if (grants === undefined)
+        return undefined;
+    const hosts = grants.hosts.filter((h) => orgAllows(h, limits));
+    return hosts.length === 0 ? undefined : { ...grants, hosts };
+}

package/dist/local-devices/policy-summary.d.ts

@@ -0,0 +1,20 @@
+import { type DeviceFeature, type DeviceLocalPolicySummary } from "@capybara-hq/plugin-sdk";
+/**
+ * The known features in `v` (a hello's `features` or the stored column), in a fixed order and
+ * deduped; anything else (unknown names, a non-array) is dropped.
+ */
+export declare function deviceFeaturesOf(v: unknown): DeviceFeature[];
+/**
+ * `v` as a local policy summary (network ask-to-allow spec §5.4), or null when it is absent or not
+ * a valid one. The device is the authority on its policy: the kernel only keeps what it last said,
+ * for the device page and to pick a card's options, never to decide what a command may reach.
+ */
+export declare function localPolicyOf(v: unknown): DeviceLocalPolicySummary | null;
+/**
+ * The isolation a policy summary states, read from its `isolation` field alone (a hello's raw
+ * `policy` or the stored column), so a summary the kernel cannot otherwise read (a newer program's
+ * new value elsewhere, a broken one) still tells whether commands run without a sandbox: `sandbox`
+ * only when it says exactly that, `none` for any other present summary (fail closed), null when
+ * there is none.
+ */
+export declare function isolationOf(v: unknown): "sandbox" | "none" | null;