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

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;

package/dist/local-devices/policy-summary.js

@@ -0,0 +1,63 @@
+import { isSandboxTier, } from "@capybara-hq/plugin-sdk";
+const KNOWN_FEATURES = ["networkReport", "policyOp", "tiers"];
+/**
+ * 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 function deviceFeaturesOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return KNOWN_FEATURES.filter((f) => v.includes(f));
+}
+/**
+ * `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 function localPolicyOf(v) {
+    if (typeof v !== "object" || v === null || Array.isArray(v))
+        return null;
+    const o = v;
+    if (o.tier !== undefined && !isSandboxTier(o.tier))
+        return null;
+    if (!isSandboxTier(o.effectiveTier))
+        return null;
+    if (o.isolation !== "sandbox" && o.isolation !== "none")
+        return null;
+    if (o.localhost !== "on" && o.localhost !== "off-proxy-detected" && o.localhost !== "off") {
+        return null;
+    }
+    if (o.unixSockets !== "roots" && o.unixSockets !== "all-masked" && o.unixSockets !== "off") {
+        return null;
+    }
+    if (o.remoteGrants !== "owner" && o.remoteGrants !== "off")
+        return null;
+    if (!Array.isArray(o.allowedDomains))
+        return null;
+    if (!o.allowedDomains.every((d) => typeof d === "string"))
+        return null;
+    return {
+        ...(o.tier !== undefined && { tier: o.tier }),
+        effectiveTier: o.effectiveTier,
+        isolation: o.isolation,
+        localhost: o.localhost,
+        unixSockets: o.unixSockets,
+        allowedDomains: [...o.allowedDomains],
+        remoteGrants: o.remoteGrants,
+    };
+}
+/**
+ * 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 function isolationOf(v) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v === "object" && !Array.isArray(v)) {
+        return v.isolation === "sandbox" ? "sandbox" : "none";
+    }
+    return "none";
+}

package/dist/orgs/orgs.module.js

@@ -21,7 +21,7 @@ import { MembersService } from "./members.service.js";
 import { Offboarding } from "./offboarding.js";
 import { OrgLockModule } from "./org-lock.js";
 import { OrgsService } from "./orgs.service.js";
-import { OrgSettingsService } from "./settings.service.js";
+import { OrgSettingsModule } from "./settings.service.js";
 /**
  * Organizations: orgs, org settings, members, invitations, offboarding (with its sweep cron) and
  * directory sync (the hourly scan cron, one-off syncs on the maintenance queue).
@@ -35,6 +35,7 @@ OrgsModule = __decorate([
             // offboarding publishes the events it cancelled
             EventLogModule,
             OrgLockModule,
+            OrgSettingsModule,
             ExtensionsModule,
             // offboarding clears credentials and cancels approvals and questions
             ToolsModule,
@@ -49,18 +50,11 @@ OrgsModule = __decorate([
             // the producer side of directory-sync jobs (the maintenance processor consumes them)
             QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
         ],
-        providers: [
-            OrgsService,
-            OrgSettingsService,
-            MembersService,
-            InvitationsService,
-            Offboarding,
-            DirectorySync,
-        ],
+        providers: [OrgsService, MembersService, InvitationsService, Offboarding, DirectorySync],
         exports: [
             OrgLockModule,
+            OrgSettingsModule,
             OrgsService,
-            OrgSettingsService,
             MembersService,
             InvitationsService,
             Offboarding,

package/dist/orgs/roles.d.ts

@@ -4,7 +4,7 @@ export type OrgRole = (typeof ORG_ROLES)[number];
 /** `role` 是否不低于 `min`。 */
 export declare function roleAtLeast(role: OrgRole, min: OrgRole): boolean;
 /** 组织级动作；路由用 `@OrgAction(action)` 声明所需动作。 */
-export type OrgAction = "org.read" | "org.update" | "org.delete" | "org.transfer" | "org.members.read" | "org.members.manage" | "org.invitations.manage" | "org.tokens.manage" | "org.extensions.read" | "org.extensions.manage" | "agents.create" | "agents.use" | "agents.manage" | "connectors.manage" | "connectors.use" | "approvals.decide" | "channels.manage" | "skills.read" | "skills.manage" | "ui.use" | "trajectories.read" | "evals.manage" | "org.models.manage" | "catalog.read" | "catalog.request" | "catalog.decide" | "catalog.upload";
+export type OrgAction = "org.read" | "org.update" | "org.delete" | "org.transfer" | "org.members.read" | "org.members.manage" | "org.invitations.manage" | "org.tokens.manage" | "org.extensions.read" | "org.extensions.manage" | "agents.create" | "agents.use" | "agents.manage" | "connectors.manage" | "connectors.use" | "approvals.decide" | "channels.manage" | "skills.read" | "skills.manage" | "ui.use" | "trajectories.read" | "evals.manage" | "org.models.manage" | "catalog.read" | "catalog.request" | "catalog.decide" | "catalog.upload" | "schedules.use" | "schedules.manage";
 /** 每个动作所需的最低角色。 */
 export declare const ACTION_MIN_ROLE: Record<OrgAction, OrgRole>;
 /** 只允许 user principal 执行的动作：服务令牌即使角色足够也拒绝（除 SERVICE_ALLOWED 外全部）。 */

package/dist/orgs/roles.js

@@ -47,6 +47,10 @@ export const ACTION_MIN_ROLE = {
     "catalog.decide": "admin",
     // An org admin uploads a plugin package the org owns (spec §14.1 item 1, ruling P3-7)
     "catalog.upload": "admin",
+    // Scheduled tasks (spec 2026-11-11 §10): create, edit, pause, resume, run and delete one's own
+    "schedules.use": "member",
+    // list every task of the org, pause, resume and delete any (never edit another person's)
+    "schedules.manage": "admin",
 };
 /** 服务令牌也可执行的动作：只读的 org.read、org.members.read，以及使用 agent 的 agents.use。 */
 const SERVICE_ALLOWED = new Set([

package/dist/orgs/settings.controller.js

@@ -30,7 +30,8 @@ let OrgSettingsController = class OrgSettingsController {
     async update(principal, org, body) {
         const p = requireUser(principal);
         return {
-            settings: await this.settings.update(org.orgId, body, p.account.id, patTokenId(p)),
+            // an API token may narrow the sandbox, never widen it (sandbox dev tiers spec §2)
+            settings: await this.settings.update(org.orgId, body, p.account.id, patTokenId(p), undefined, { onlyNarrows: patTokenId(p) !== undefined }),
             deployment: this.settings.deployment(),
             sandboxLimits: await this.settings.sandboxLimits(org.orgId),
         };