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

package/dist/conversations/queue.service.d.ts

@@ -1,6 +1,6 @@
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
-import { ConversationsService, type RunControl } from "./conversations.service.js";
+import { ConversationsService, type InternalMessageOptions, type RunControl } from "./conversations.service.js";
 import { EventLog } from "./event-log.js";
 import type { ConversationEvent } from "./events.js";
 import { type QueueInput, type QueueItem, type QueuePauseReason } from "./queue.js";
@@ -15,7 +15,7 @@ export declare class ConversationQueue {
     /** Starts the conversation's next run (`ensureRun`). */
     private readonly runs;
     readonly txHost: TransactionHost;
-    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill" | "skipQuestionsIn" | "announceSkipped">, 
+    constructor(db: KernelDb, eventLog: Pick<EventLog, "appendIn" | "notify" | "publishChanged" | "findByIdem">, conversations: Pick<ConversationsService, "get" | "writable" | "resolveExtra" | "bindIn" | "checkPick" | "prepareQueuedSkill" | "skipWaitsIn" | "announceSkipped">, 
     /** Starts the conversation's next run (`ensureRun`). */
     runs: Pick<RunControl, "ensureRun" | "wakeHeldTree">, txHost: TransactionHost);
     list(orgId: string, conversationId: string, accountId: string): Promise<{
@@ -29,9 +29,11 @@ export declare class ConversationQueue {
      * item, and uploaded files are bound to the conversation now, so sending later needs nobody's
      * credentials. The same `clientMessageId` again returns the queued item (`created: false`), or,
      * when it was already sent, the sent `user_message` with `item: null`. Then `ensureRun`: on an
-     * idle conversation the item goes out at once.
+     * idle conversation the item goes out at once. `internal` (kernel callers only, never HTTP): a
+     * scheduled task's marker and zone, stored with the item and written with its `user_message`
+     * (scheduled tasks spec §6).
      */
-    add(orgId: string, conversationId: string, accountId: string, input: QueueInput): Promise<{
+    add(orgId: string, conversationId: string, accountId: string, input: QueueInput, internal?: InternalMessageOptions): Promise<{
         item: QueueItem | null;
         event?: ConversationEvent;
         created: boolean;
@@ -39,7 +41,9 @@ export declare class ConversationQueue {
     private addIn;
     /**
      * Changes a queued item's text (its resources and files stay as queued). A skill invocation's
-     * text is its arguments: the skill is rendered again with them now.
+     * text is its arguments: the skill is rendered again with them now. A scheduled task's item
+     * becomes the person's message: its schedule marker (and the task's zone) is dropped, so the run
+     * it triggers is attended (scheduled tasks spec §7).
      */
     edit(orgId: string, conversationId: string, accountId: string, itemId: string, text: string): Promise<QueueItem>;
     private editIn;
@@ -48,7 +52,9 @@ export declare class ConversationQueue {
     /**
      * Sends a queued item now: it leaves the queue and is posted as a user message in the same
      * transaction (an interjection when a run is active; the items before it keep their place).
-     * Racing the dispatcher, exactly one of them takes the item; the loser sees it gone (404).
+     * Racing the dispatcher, exactly one of them takes the item; the loser sees it gone (404). A
+     * scheduled task's item is sent as the person's message, without its schedule marker
+     * (scheduled tasks spec §7).
      */
     sendNow(orgId: string, conversationId: string, accountId: string, itemId: string): Promise<ConversationEvent>;
     private sendNowIn;

package/dist/conversations/queue.service.js

@@ -14,8 +14,9 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { RunControl as RunControlService } from "../runtime/run-control.js";
+import { releaseQueuedTaskRunIn } from "../schedules/run-tracker.js";
 import { notInvocable } from "../skills/invoke.js";
-import { ConversationsService, } from "./conversations.service.js";
+import { ConversationsService, NO_REPLY_SKIPS, } from "./conversations.service.js";
 import { EventLog, payloadJson } from "./event-log.js";
 import { userMessageIdemKey } from "./idem-keys.js";
 import { alreadySent, appendQueuedIn, COLUMNS, checkText, itemNotFound, noNul, QUEUE_MAX_ITEMS, queuedSkillBlocked, queueFull, storedSkill, toItem, unpauseIfEmpty, } from "./queue.js";
@@ -67,9 +68,11 @@ let ConversationQueue = class ConversationQueue {
      * item, and uploaded files are bound to the conversation now, so sending later needs nobody's
      * credentials. The same `clientMessageId` again returns the queued item (`created: false`), or,
      * when it was already sent, the sent `user_message` with `item: null`. Then `ensureRun`: on an
-     * idle conversation the item goes out at once.
+     * idle conversation the item goes out at once. `internal` (kernel callers only, never HTTP): a
+     * scheduled task's marker and zone, stored with the item and written with its `user_message`
+     * (scheduled tasks spec §6).
      */
-    async add(orgId, conversationId, accountId, input) {
+    async add(orgId, conversationId, accountId, input, internal = {}) {
         const conv = await this.conversations.writable(orgId, conversationId, accountId);
         const files = input.files ?? [];
         checkText(input.text, files.length, input.attachments?.length ?? 0, input.skill !== undefined);
@@ -92,7 +95,7 @@ let ConversationQueue = class ConversationQueue {
         const skill = invoked === undefined || input.skill === undefined
             ? undefined
             : storedSkill(input.skill.name, invoked);
-        const out = await this.addIn(orgId, conversationId, accountId, input, files, skill, extra);
+        const out = await this.addIn(orgId, conversationId, accountId, input, files, skill, extra, internal);
         if (out === null) {
             return ((await this.prior(conversationId, input.clientMessageId)) ?? { item: null, created: false });
         }
@@ -103,7 +106,7 @@ let ConversationQueue = class ConversationQueue {
         return { item: toItem(out.row), created: out.created };
     }
     // its own transaction: the caller notifies and publishes after the commit
-    async addIn(orgId, conversationId, accountId, input, files, skill, extra) {
+    async addIn(orgId, conversationId, accountId, input, files, skill, extra, internal) {
         const t = this.db.db;
         await t
             .selectFrom("conversations")
@@ -154,6 +157,14 @@ let ConversationQueue = class ConversationQueue {
             model: input.model === undefined ? null : JSON.stringify(input.model),
             effort: input.effort ?? null,
             skill: skill?.skill ?? null,
+            schedule: internal.schedule === undefined
+                ? null
+                : JSON.stringify({
+                    ...internal.schedule,
+                    ...(internal.timeZoneOverride !== undefined && {
+                        timeZone: internal.timeZoneOverride,
+                    }),
+                }),
         })
             .returning(COLUMNS)
             .executeTakeFirstOrThrow();
@@ -161,7 +172,9 @@ let ConversationQueue = class ConversationQueue {
     }
     /**
      * Changes a queued item's text (its resources and files stay as queued). A skill invocation's
-     * text is its arguments: the skill is rendered again with them now.
+     * text is its arguments: the skill is rendered again with them now. A scheduled task's item
+     * becomes the person's message: its schedule marker (and the task's zone) is dropped, so the run
+     * it triggers is attended (scheduled tasks spec §7).
      */
     async edit(orgId, conversationId, accountId, itemId, text) {
         const conv = await this.conversations.writable(orgId, conversationId, accountId);
@@ -189,13 +202,15 @@ let ConversationQueue = class ConversationQueue {
         const t = this.db.db;
         const cur = await t
             .selectFrom("conversation_queue")
-            .select(["attachments", "files", "content", "skill"])
+            .select(["attachments", "files", "content", "skill", "schedule"])
             .where("id", "=", itemId)
             .where("conversation_id", "=", conversationId)
             .forUpdate()
             .executeTakeFirst();
         if (!cur)
             throw itemNotFound();
+        // a person's words now: the task's run for this item will not happen (scheduled tasks §6)
+        await releaseQueuedTaskRunIn(t, cur.schedule);
         const skill = cur.skill;
         checkText(text, cur.files.length, cur.attachments.length, skill !== null);
         // an invocation's first block is its rendered text: replace it and the record
@@ -204,6 +219,8 @@ let ConversationQueue = class ConversationQueue {
             .updateTable("conversation_queue")
             .set({
             text: noNul(text),
+            // edited by a person: no longer the task's message
+            schedule: null,
             updated_at: sql `now()`,
             ...(stored !== undefined && {
                 skill: stored.skill,
@@ -229,16 +246,20 @@ let ConversationQueue = class ConversationQueue {
             .deleteFrom("conversation_queue")
             .where("id", "=", itemId)
             .where("conversation_id", "=", conversationId)
-            .returning("id")
+            .returning(["id", "schedule"])
             .executeTakeFirst();
         if (!gone)
             throw itemNotFound();
+        // a task's queued message deleted by a person: its run is skipped (scheduled tasks §6)
+        await releaseQueuedTaskRunIn(t, gone.schedule);
         await unpauseIfEmpty(t, conversationId);
     }
     /**
      * Sends a queued item now: it leaves the queue and is posted as a user message in the same
      * transaction (an interjection when a run is active; the items before it keep their place).
-     * Racing the dispatcher, exactly one of them takes the item; the loser sees it gone (404).
+     * Racing the dispatcher, exactly one of them takes the item; the loser sees it gone (404). A
+     * scheduled task's item is sent as the person's message, without its schedule marker
+     * (scheduled tasks spec §7).
      */
     async sendNow(orgId, conversationId, accountId, itemId) {
         await this.conversations.writable(orgId, conversationId, accountId);
@@ -283,17 +304,19 @@ let ConversationQueue = class ConversationQueue {
         if (!row)
             throw itemNotFound();
         const sent = await alreadySent(t, conversationId, row.client_message_id);
-        const out = await appendQueuedIn(t, this.eventLog, conversationId, row);
+        // sent by a person: their message, not the task's, whose run is skipped
+        await releaseQueuedTaskRunIn(t, row.schedule);
+        const out = await appendQueuedIn(t, this.eventLog, conversationId, { ...row, schedule: null });
         await unpauseIfEmpty(t, conversationId);
         // sent during the run, the item is the author's message like a direct send: it skips the
         // pending questions they may answer (reply-while-question spec §4.2)
         const skips = sent
-            ? { records: [], toSeq: null }
-            : await this.conversations.skipQuestionsIn(conversationId, row.account_id, out.event.seq);
+            ? { skipped: NO_REPLY_SKIPS, toSeq: null }
+            : await this.conversations.skipWaitsIn(conversationId, row.account_id, out.event.seq);
         return {
             ...out,
             fresh: !sent,
-            skipped: skips.records,
+            skipped: skips.skipped,
             toSeq: Math.max(out.event.seq, skips.toSeq ?? 0),
         };
     }

package/dist/db/kernel-schema.d.ts

@@ -1,5 +1,7 @@
-import type { FileSystemHandle, ParsedTheme, SkillInvocation } from "@capybara-hq/plugin-sdk";
+import type { FileSystemHandle, ParsedTheme, SandboxTier, SkillInvocation } from "@capybara-hq/plugin-sdk";
 import type { ColumnType, Generated, Kysely } from "kysely";
+import type { ModelRef } from "../agents/definition.js";
+import type { ScheduleChat, ScheduleMarker, ScheduleMode, SchedulePauseReason, ScheduleStatus, ScheduleTrigger, TaskRunSkipReason, TaskRunStatus } from "../schedules/types.js";
 /** 带默认值的时间戳列：插入可省略，读出为 Date。 */
 type Ts = ColumnType<Date, Date | string | undefined, Date | string>;
 type TsNullable = ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
@@ -259,6 +261,8 @@ export interface ConversationsTable {
     subagent_depth: ColumnType<number, number | undefined, number>;
     /** 0088, renamed in 0105: the device the conversation runs in; null = not chosen yet. */
     device_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0113: the scheduled task that created it (`new` mode); null otherwise. */
+    scheduled_task_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0060: an org's order of file-preview@1 previewers (UI refresh B Task 11). */
 export interface FilePreviewersTable {
@@ -297,6 +301,13 @@ export interface ConversationQueueTable {
     effort: ColumnType<string | null, string | null | undefined, string | null>;
     /** 0062: the `user_message.skill` record of a queued skill invocation, or null. */
     skill: ColumnType<unknown, string | null | undefined, string | null>;
+    /**
+     * 0113: the schedule marker of a scheduled task's message, plus the task's zone (`timeZone`, the
+     * message's zone override; not copied into the logged marker); null for a person's message.
+     */
+    schedule: ColumnType<(ScheduleMarker & {
+        timeZone?: string;
+    }) | null, string | null | undefined, string | null>;
     created_at: Ts;
     updated_at: Ts;
 }
@@ -342,6 +353,11 @@ export interface RunsTable {
      * and its descendants' tokens, agent map spec §6); null = the run is its own budget run.
      */
     budget_run_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * 0113: the scheduled task run this run serves (set on the run the task's message triggers and
+     * inherited by its unattended descendants); null = a person's run.
+     */
+    scheduled_task_run_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0053: one row per sub-agent dispatch (an `Agent` call of a parent run). */
 export interface SubagentDispatchesTable {
@@ -488,7 +504,7 @@ export interface ApprovalsTable {
     input: Json<unknown>;
     requested_for: string | null;
     approver_role: string | null;
-    status: Generated<"pending" | "approved" | "denied" | "expired" | "cancelled">;
+    status: Generated<"pending" | "approved" | "denied" | "expired" | "cancelled" | "skipped">;
     scope: "once" | "session" | "always" | null;
     decided_by: string | null;
     decided_at: TsNullable;
@@ -509,6 +525,10 @@ export interface ApprovalsTable {
     } | null, string | null | undefined, string | null>;
     /** 0086: the scopes the person may choose (null: derived, see `approvals.service.ts`). */
     scopes: ColumnType<("once" | "session" | "always")[] | null, ("once" | "session" | "always")[] | null | undefined, ("once" | "session" | "always")[] | null>;
+    /** 0114: what is asked: a tool call ('tool') or a refused network domain ('network'). */
+    kind: Generated<"tool" | "network">;
+    /** 0114: a network ask's hosts, command, kept result and outcome (null for tool approvals). */
+    detail: ColumnType<unknown | null, string | null | undefined, string | null>;
 }
 /** 0010_tools.sql：AskUserQuestion 提问。 */
 export interface QuestionsTable {
@@ -628,6 +648,11 @@ export interface ChannelDeliveriesTable {
     fail_seq: ColumnType<string | null, number | string | null | undefined, number | string | null>;
     fail_count: Generated<number>;
     updated_at: Ts;
+    /**
+     * 0113: a scheduled group run's thread is still to bind; the account its thread row gets when
+     * outbound has the run's first post (thread key = that message's id). Null otherwise.
+     */
+    pending_thread_account_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0018_channels.sql：出站投递发出的审批 / 提问卡片对应的 IM 消息（Task 11，用于更新卡片状态）。 */
 export interface ChannelCardMessagesTable {
@@ -850,6 +875,8 @@ export interface DevicesTable {
     provider: ColumnType<string | null, string | null | undefined, string | null>;
     /** 0096: the provider a demoted default was demoted from; null for every other device. */
     demoted_from_provider: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0117: a cloud device's own sandbox tier; null follows the org's default. */
+    tier: ColumnType<SandboxTier | null, SandboxTier | null | undefined, SandboxTier | null>;
     created_at: Ts;
     updated_at: Ts;
     deleted_at: TsNullable;
@@ -879,6 +906,12 @@ export interface DeviceInstancesTable {
     prev_provider: ColumnType<string | null, string | null | undefined, string | null>;
     prev_handle: InstanceHandle;
     sweep_failed_at: TsNullable;
+    /**
+     * 0117: the limits in force on the instance, `{ tier, egress }`, plus `unapplied` when the
+     * provider could not apply a newer value without a file reset; null = unknown (made before
+     * 0117). Read with `readInstanceLimits` (`sandbox/tiers.ts`).
+     */
+    instance_limits: ColumnType<unknown | null, string | null | undefined, string | null>;
 }
 /**
  * 0093_connected_environments.sql, renamed in 0105: the machine of a local device. At most one
@@ -902,6 +935,10 @@ export interface DeviceMachinesTable {
     last_seen_at: TsNullable;
     created_at: Ts;
     revoked_at: TsNullable;
+    /** 0114: the features the program reported in its hello (`networkReport`, `policyOp`). */
+    features: ColumnType<string[], string[] | undefined, string[]>;
+    /** 0114: the program's local network policy summary (hello, refreshed by each `policy` op). */
+    local_policy: ColumnType<unknown | null, string | null | undefined, string | null>;
 }
 /** 0088_environments.sql, renamed in 0105: the device a member's new conversations use by default. */
 export interface DeviceDefaultsTable {
@@ -1147,6 +1184,61 @@ export interface ModelUsageTable {
     /** Set when the row's `usage.report` job gave up after its last attempt (the sweep skips it). */
     report_failed_at: TsNullable;
 }
+type NullableText = ColumnType<string | null, string | null | undefined, string | null>;
+type NullableTs = ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
+/** 0113: a scheduled task (scheduled tasks spec §4). */
+export interface ScheduledTasksTable {
+    id: string;
+    org_id: string;
+    account_id: string;
+    agent_id: string;
+    name: string;
+    prompt: string;
+    trigger: ColumnType<ScheduleTrigger, string, string>;
+    mode: ScheduleMode;
+    conversation_id: NullableText;
+    chat: ColumnType<ScheduleChat | null, string | null | undefined, string | null>;
+    model: ColumnType<ModelRef | null, string | null | undefined, string | null>;
+    effort: NullableText;
+    device_id: NullableText;
+    status: ColumnType<ScheduleStatus, ScheduleStatus | undefined, ScheduleStatus>;
+    pause_reason: ColumnType<SchedulePauseReason | null, SchedulePauseReason | null | undefined, SchedulePauseReason | null>;
+    paused_by: NullableText;
+    next_run_at: NullableTs;
+    jitter_seconds: ColumnType<number, number | undefined, number>;
+    expires_at: NullableTs;
+    consecutive_failures: ColumnType<number, number | undefined, number>;
+    created_at: Ts;
+    updated_at: Ts;
+    deleted_at: NullableTs;
+}
+/** 0113: one tick (or trial run) of a scheduled task; unique per (task, tick) when not trial. */
+export interface ScheduledTaskRunsTable {
+    id: string;
+    task_id: string;
+    org_id: string;
+    scheduled_for: Date | string;
+    fired_at: NullableTs;
+    trial: ColumnType<boolean, boolean | undefined, boolean>;
+    /** A person's "run now" (trial or not): runs even while the task is paused. */
+    manual: ColumnType<boolean, boolean | undefined, boolean>;
+    conversation_id: NullableText;
+    run_id: NullableText;
+    status: ColumnType<TaskRunStatus, TaskRunStatus | undefined, TaskRunStatus>;
+    skip_reason: ColumnType<TaskRunSkipReason | null, TaskRunSkipReason | null | undefined, TaskRunSkipReason | null>;
+    error: NullableText;
+    missing_grants: ColumnType<string[], string | undefined, string>;
+    /** When the scanner's repair last found this started run still in flight. */
+    rechecked_at: NullableTs;
+}
+/** 0113: a scheduled task's remembered grants (same shape as `conversation_tool_grants`). */
+export interface ScheduledTaskGrantsTable {
+    task_id: string;
+    tool_key: string;
+    spec_hash: string;
+    connector_id: string | null;
+    created_at: Ts;
+}
 export interface KernelDatabase {
     accounts: AccountsTable;
     account_initial_passwords: AccountInitialPasswordsTable;
@@ -1200,6 +1292,9 @@ export interface KernelDatabase {
     device_defaults: DeviceDefaultsTable;
     device_machines: DeviceMachinesTable;
     background_tasks: BackgroundTasksTable;
+    scheduled_tasks: ScheduledTasksTable;
+    scheduled_task_runs: ScheduledTaskRunsTable;
+    scheduled_task_grants: ScheduledTaskGrantsTable;
     skills: SkillsTable;
     skill_versions: SkillVersionsTable;
     skill_change_requests: SkillChangeRequestsTable;
@@ -1669,6 +1764,8 @@ export interface PluginImportStagingTable {
     expires_at: ColumnType<Date, Date | string, Date | string>;
 }
 type NullableCol<T> = ColumnType<T | null, T | null | undefined, T | null>;
+/** 0077 / 0085 / 0115: the kinds of a catalog request. */
+type CatalogRequestKindCol = "access" | "import" | "enable" | "connector_setup" | "network_allowlist";
 /**
  * 0037, renamed in 0042, kinds since 0077: an org's catalog requests. `stage` (org / deployment) is
  * still written (`enable` -> org, else deployment) but no longer read.
@@ -1680,7 +1777,12 @@ export interface CatalogRequestsTable {
     item_id: NullableCol<string>;
     version: NullableCol<string>;
     /** 0077: what the request asks for (spec §5.1). */
-    kind: ColumnType<"access" | "import" | "enable" | "connector_setup", "access" | "import" | "enable" | "connector_setup" | undefined, "access" | "import" | "enable" | "connector_setup">;
+    kind: ColumnType<CatalogRequestKindCol, CatalogRequestKindCol | undefined, CatalogRequestKindCol>;
+    /**
+     * 0115: what a `network_allowlist` request asks for (`{ hosts, conversationId, agentId }`); null
+     * for other kinds.
+     */
+    detail: ColumnType<unknown | null, string | null | undefined, string | null>;
     /** 0085: the agent of a `connector_setup` request (cascades with the agent). */
     agent_id: NullableCol<string>;
     /** 0085: the template connector keys a `connector_setup` request still waits for. */

package/dist/devices/conversation-devices.d.ts

@@ -1,6 +1,7 @@
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { DeviceSandboxLevel } from "../runtime/context/device-paths.js";
 import { SandboxProviders } from "../sandbox/providers.js";
 import { DeviceAccess } from "./access.js";
 import { DevicesService } from "./devices.service.js";
@@ -29,7 +30,13 @@ export declare class ConversationDevices {
     private readonly providers;
     private readonly access;
     private readonly devices;
-    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "cloud"> & Partial<Pick<SandboxProviders, "forName">>, access: Pick<DeviceAccess, "usable">, devices: Pick<DevicesService, "ensureDefault">);
+    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "cloud"> & Partial<Pick<SandboxProviders, "forName">>, access: Pick<DeviceAccess, "usable">, devices: Pick<DevicesService, "ensureDefault" | "sandboxLevel">);
+    /**
+     * The sandbox level a call in the device runs at now ({@link DevicesService.sandboxLevel}),
+     * recorded for the model in `device_paths` (sandbox dev tiers spec §11.5); `runId`: the calling
+     * run, whose scheduled-run cap applies.
+     */
+    sandboxLevel(orgId: string, deviceId: string, runId?: string): Promise<DeviceSandboxLevel | null>;
     /**
      * The device a new conversation of `accountId` is bound to: the chosen one when it is
      * usable by the person (else `device.not_found` / `device.unavailable`, and nothing

package/dist/devices/conversation-devices.js

@@ -41,6 +41,14 @@ let ConversationDevices = class ConversationDevices {
         this.access = access;
         this.devices = devices;
     }
+    /**
+     * The sandbox level a call in the device runs at now ({@link DevicesService.sandboxLevel}),
+     * recorded for the model in `device_paths` (sandbox dev tiers spec §11.5); `runId`: the calling
+     * run, whose scheduled-run cap applies.
+     */
+    sandboxLevel(orgId, deviceId, runId) {
+        return this.devices.sandboxLevel(orgId, deviceId, runId);
+    }
     /**
      * The device a new conversation of `accountId` is bound to: the chosen one when it is
      * usable by the person (else `device.not_found` / `device.unavailable`, and nothing

package/dist/devices/devices.controller.d.ts

@@ -1,8 +1,9 @@
+import type { DeviceLocalPolicySummary } from "@capybara-hq/plugin-sdk";
 import type { z } from "zod";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { type DeviceList, DevicesService, type DeviceView } from "./devices.service.js";
-import { type DeviceNameBody, type DeviceParams } from "./dto.js";
+import { type DeviceNameBody, type DeviceParams, type DevicePatchBody, type DevicePolicyBody } from "./dto.js";
 /**
  * A person's devices in an org (`/api/v1/orgs/:orgId/devices`, spec
  * 2026-11-07-environments-design §9; `agents.use`, human users only: a service token gets 403).
@@ -10,12 +11,25 @@ import { type DeviceNameBody, type DeviceParams } from "./dto.js";
  * gets 404 `device.not_found`.
  * - `GET /` → `{ items, defaultId, lastUsedId, cloudAvailable }` (`cloudAvailable`: there is a
  *   current sandbox provider; ruling R4);
- * - `POST / { name }` → 201 `{ device }`; `GET /:id`, `PATCH /:id { name }` → `{ device }`;
+ * - `POST / { name }` → 201 `{ device }`; `GET /:id` → `{ device }`;
+ * - `PATCH /:id { name?, tier? }` → `{ device }`: renames it and, for a cloud device, sets its
+ *   sandbox tier (sandbox dev tiers spec §7.2; null follows the org's default). The tier is set in
+ *   a web session only (an API token → 403 `auth.session_required`); above the org's or the
+ *   platform's ceiling → 400 `device.tier_not_allowed`; a local device → 409
+ *   `device.tier_on_device` (its tier is its machine's: `POST /:id/policy { tier }`). Audited
+ *   `device.tier_changed`;
  * - `DELETE /:id` → 202 (destroyed by a job after the response);
  * - `POST /:id/files/reset` → 202 (the reset is enqueued: a worker empties the files, the next use
  *   starts empty);
  * - `DELETE /:id/machine` → 204: a local device's machine is disconnected (its credential
- *   revoked; it must sign in again).
+ *   revoked; it must sign in again);
+ * - `POST /:id/policy { add?, remove?, tier?, isolation? }` → `{ policy }`: the owner changes the
+ *   local device's policy on its machine (network ask-to-allow spec §7, sandbox dev tiers spec
+ *   §7.3; `isolation` is only ever `sandbox`). Web session only
+ *   (`@SessionOnly`: a personal access token → 403 `auth.session_required`, a service token → 403):
+ *   a person changes their own machine's network policy, nothing model-driven does. Widening needs
+ *   the machine's `remoteGrants: "owner"` (409 `device.policy_refused`); offline → 503
+ *   `device.offline`; cloud or an older program → 409 `device.policy_unsupported`.
  */
 export declare class DevicesController {
     private readonly devices;
@@ -27,10 +41,13 @@ export declare class DevicesController {
     get(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<{
         device: DeviceView;
     }>;
-    rename(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>, body: z.infer<typeof DeviceNameBody>): Promise<{
+    update(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>, body: z.infer<typeof DevicePatchBody>): Promise<{
         device: DeviceView;
     }>;
     remove(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<void>;
     resetFiles(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<void>;
     revokeMachine(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>): Promise<void>;
+    changePolicy(principal: Principal, org: OrgContext, params: z.infer<typeof DeviceParams>, body: z.infer<typeof DevicePolicyBody>): Promise<{
+        policy: DeviceLocalPolicySummary;
+    }>;
 }

package/dist/devices/devices.controller.js

@@ -8,11 +8,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Controller, Delete, Get, HttpCode, Inject, Patch, Post } from "@nestjs/common";
-import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { ApiError } from "../errors.js";
+import { CurrentPrincipal, patTokenId, requireUser, SessionOnly, } from "../identity/principal.js";
 import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { DevicesService } from "./devices.service.js";
-import { DeviceCreateBodyDto, DeviceParamsDto, DeviceRenameBodyDto, } from "./dto.js";
+import { DeviceCreateBodyDto, DeviceParamsDto, DevicePatchBodyDto, DevicePolicyBodyDto, } from "./dto.js";
 /**
  * A person's devices in an org (`/api/v1/orgs/:orgId/devices`, spec
  * 2026-11-07-environments-design §9; `agents.use`, human users only: a service token gets 403).
@@ -20,12 +21,25 @@ import { DeviceCreateBodyDto, DeviceParamsDto, DeviceRenameBodyDto, } from "./dt
  * gets 404 `device.not_found`.
  * - `GET /` → `{ items, defaultId, lastUsedId, cloudAvailable }` (`cloudAvailable`: there is a
  *   current sandbox provider; ruling R4);
- * - `POST / { name }` → 201 `{ device }`; `GET /:id`, `PATCH /:id { name }` → `{ device }`;
+ * - `POST / { name }` → 201 `{ device }`; `GET /:id` → `{ device }`;
+ * - `PATCH /:id { name?, tier? }` → `{ device }`: renames it and, for a cloud device, sets its
+ *   sandbox tier (sandbox dev tiers spec §7.2; null follows the org's default). The tier is set in
+ *   a web session only (an API token → 403 `auth.session_required`); above the org's or the
+ *   platform's ceiling → 400 `device.tier_not_allowed`; a local device → 409
+ *   `device.tier_on_device` (its tier is its machine's: `POST /:id/policy { tier }`). Audited
+ *   `device.tier_changed`;
  * - `DELETE /:id` → 202 (destroyed by a job after the response);
  * - `POST /:id/files/reset` → 202 (the reset is enqueued: a worker empties the files, the next use
  *   starts empty);
  * - `DELETE /:id/machine` → 204: a local device's machine is disconnected (its credential
- *   revoked; it must sign in again).
+ *   revoked; it must sign in again);
+ * - `POST /:id/policy { add?, remove?, tier?, isolation? }` → `{ policy }`: the owner changes the
+ *   local device's policy on its machine (network ask-to-allow spec §7, sandbox dev tiers spec
+ *   §7.3; `isolation` is only ever `sandbox`). Web session only
+ *   (`@SessionOnly`: a personal access token → 403 `auth.session_required`, a service token → 403):
+ *   a person changes their own machine's network policy, nothing model-driven does. Widening needs
+ *   the machine's `remoteGrants: "owner"` (409 `device.policy_refused`); offline → 503
+ *   `device.offline`; cloud or an older program → 409 `device.policy_unsupported`.
  */
 let DevicesController = class DevicesController {
     devices;
@@ -46,10 +60,18 @@ let DevicesController = class DevicesController {
         const p = requireUser(principal);
         return { device: await this.devices.get(org.orgId, p.account.id, params.id) };
     }
-    async rename(principal, org, params, body) {
+    async update(principal, org, params, body) {
         const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        // a person decides their device's sandbox level, in a session (spec §7.2)
+        if (body.tier !== undefined && tokenId !== undefined) {
+            throw new ApiError("auth.session_required", "A device's sandbox level is set by its owner on the web, not with an API token");
+        }
         return {
-            device: await this.devices.rename(org.orgId, p.account.id, params.id, body.name, patTokenId(p)),
+            device: await this.devices.update(org.orgId, p.account.id, params.id, {
+                ...(body.name !== undefined && { name: body.name }),
+                ...(body.tier !== undefined && { tier: body.tier }),
+            }, tokenId),
         };
     }
     async remove(principal, org, params) {
@@ -64,6 +86,12 @@ let DevicesController = class DevicesController {
         const p = requireUser(principal);
         await this.devices.revokeMachine(org.orgId, p.account.id, params.id, patTokenId(p));
     }
+    async changePolicy(principal, org, params, body) {
+        const p = requireUser(principal);
+        return {
+            policy: await this.devices.changePolicy(org.orgId, p.account, params.id, body),
+        };
+    }
 };
 __decorate([
     Get(),
@@ -91,8 +119,8 @@ __decorate([
     __param(0, CurrentPrincipal()),
     __param(1, CurrentOrg()),
     __param(2, ZParam(DeviceParamsDto)),
-    __param(3, ZBody(DeviceRenameBodyDto))
-], DevicesController.prototype, "rename", null);
+    __param(3, ZBody(DevicePatchBodyDto))
+], DevicesController.prototype, "update", null);
 __decorate([
     Delete(":id"),
     HttpCode(202),
@@ -117,6 +145,16 @@ __decorate([
     __param(1, CurrentOrg()),
     __param(2, ZParam(DeviceParamsDto))
 ], DevicesController.prototype, "revokeMachine", null);
+__decorate([
+    Post(":id/policy"),
+    HttpCode(200),
+    SessionOnly(),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(DeviceParamsDto)),
+    __param(3, ZBody(DevicePolicyBodyDto))
+], DevicesController.prototype, "changePolicy", null);
 DevicesController = __decorate([
     Controller("api/v1/orgs/:orgId/devices"),
     __param(0, Inject(DevicesService))

package/dist/devices/devices.schemas.d.ts

@@ -1,3 +1,11 @@
 import type { RouteSchemas } from "../platform/route-schemas.js";
-/** The devices routes the Platform operations mirror (`check:platform-ops` keys). */
+/** The body of the excluded `POST /devices/:id/policy` route (human-only). */
+export { DevicePolicyBody } from "./dto.js";
+/**
+ * The devices routes the Platform operations mirror (`check:platform-ops` keys). Changing a
+ * device's network policy (`POST /devices/:id/policy`, body {@link DevicePolicyBody}) is a person's
+ * act on their own machine and stays excluded, so it has no entry here. `PATCH /devices/:id` takes
+ * a cloud device's `tier` too ({@link DevicePatchBody}); `devices.rename` omits it: a person decides
+ * their device's sandbox level.
+ */
 export declare const DEVICE_ROUTES: readonly RouteSchemas[];

package/dist/devices/devices.schemas.js

@@ -1,5 +1,13 @@
-import { DeviceNameBody, DeviceParams } from "./dto.js";
-/** The devices routes the Platform operations mirror (`check:platform-ops` keys). */
+import { DeviceNameBody, DeviceParams, DevicePatchBody } from "./dto.js";
+/** The body of the excluded `POST /devices/:id/policy` route (human-only). */
+export { DevicePolicyBody } from "./dto.js";
+/**
+ * The devices routes the Platform operations mirror (`check:platform-ops` keys). Changing a
+ * device's network policy (`POST /devices/:id/policy`, body {@link DevicePolicyBody}) is a person's
+ * act on their own machine and stays excluded, so it has no entry here. `PATCH /devices/:id` takes
+ * a cloud device's `tier` too ({@link DevicePatchBody}); `devices.rename` omits it: a person decides
+ * their device's sandbox level.
+ */
 export const DEVICE_ROUTES = [
     { route: "GET /api/v1/orgs/:orgId/devices" },
     { route: "POST /api/v1/orgs/:orgId/devices", body: DeviceNameBody },
@@ -7,7 +15,7 @@ export const DEVICE_ROUTES = [
     {
         route: "PATCH /api/v1/orgs/:orgId/devices/:id",
         params: DeviceParams,
-        body: DeviceNameBody,
+        body: DevicePatchBody,
     },
     { route: "DELETE /api/v1/orgs/:orgId/devices/:id", params: DeviceParams },
     { route: "POST /api/v1/orgs/:orgId/devices/:id/files/reset", params: DeviceParams },