@capybara-hq/kernel 0.1.0-rc.8 → 0.1.0-rc.9

package/dist/errors.d.ts

@@ -254,6 +254,30 @@ export declare const ERROR_CODES: {
     readonly "environment.name_taken": 409;
     /** The person already has `environments.maxPersonal` live personal environments. */
     readonly "environment.limit_reached": 409;
+    /**
+     * A connected environment's files are on its machine: they cannot be reset from the platform;
+     * run `capybara-device logout`, then `capybara-device login` into the environment, on the machine
+     * (ruling R24).
+     */
+    readonly "environment.files_on_device": 409;
+    /** The environment's connected machine is not connected now (no replica holds its lease). */
+    readonly "environment.offline": 503;
+    /** The connected machine runs a device program too old for this kernel; update the program. */
+    readonly "environment.program_outdated": 426;
+    /** Device sign-in (RFC 8628 style): the person has not approved the code yet; keep polling. */
+    readonly "device.authorization_pending": 400;
+    /** Device sign-in: the program polls faster than the interval; add 5 seconds and keep polling. */
+    readonly "device.slow_down": 400;
+    /** Device sign-in: the code expired before it was approved; start over. */
+    readonly "device.expired": 400;
+    /** Device sign-in: the person denied the code. */
+    readonly "device.denied": 400;
+    /** Device sign-in: no pending code matches the one given. */
+    readonly "device.code_invalid": 404;
+    /** Device sign-in: the confirmation could not hand the credential to the program; start over. */
+    readonly "device.unavailable": 503;
+    /** The machine credential is unknown or revoked. */
+    readonly "device.credential_invalid": 401;
     readonly "skill.not_found": 404;
     /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
     readonly "skill.invalid_package": 400;

package/dist/errors.js

@@ -254,6 +254,30 @@ export const ERROR_CODES = {
     "environment.name_taken": 409,
     /** The person already has `environments.maxPersonal` live personal environments. */
     "environment.limit_reached": 409,
+    /**
+     * A connected environment's files are on its machine: they cannot be reset from the platform;
+     * run `capybara-device logout`, then `capybara-device login` into the environment, on the machine
+     * (ruling R24).
+     */
+    "environment.files_on_device": 409,
+    /** The environment's connected machine is not connected now (no replica holds its lease). */
+    "environment.offline": 503,
+    /** The connected machine runs a device program too old for this kernel; update the program. */
+    "environment.program_outdated": 426,
+    /** Device sign-in (RFC 8628 style): the person has not approved the code yet; keep polling. */
+    "device.authorization_pending": 400,
+    /** Device sign-in: the program polls faster than the interval; add 5 seconds and keep polling. */
+    "device.slow_down": 400,
+    /** Device sign-in: the code expired before it was approved; start over. */
+    "device.expired": 400,
+    /** Device sign-in: the person denied the code. */
+    "device.denied": 400,
+    /** Device sign-in: no pending code matches the one given. */
+    "device.code_invalid": 404,
+    /** Device sign-in: the confirmation could not hand the credential to the program; start over. */
+    "device.unavailable": 503,
+    /** The machine credential is unknown or revoked. */
+    "device.credential_invalid": 401,
     "skill.not_found": 404,
     /** Also a skill neither the model nor a person could use (phase D: both invocation flags off). */
     "skill.invalid_package": 400,

package/dist/evals/recorded-tools.d.ts

@@ -1,3 +1,4 @@
+import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
 import type { EventLog } from "../conversations/event-log.js";
 import { type LegacyScope } from "../tools/legacy-keys.js";
 import { type ToolPipeline, type ToolStepContext } from "../tools/pipeline.js";
@@ -23,6 +24,14 @@ export interface RecordedCall {
     specHash: string;
     /** The recorded call used release-candidate names; `toolKey` and `inputKey` are already the current ones. */
     legacy?: true;
+    /**
+     * The roots of the latest `environment_paths` event the original run had logged by this call's
+     * step (environments spec §13.1, ruling R22): set on every recorded call from the step where an
+     * event was logged onward. A replay that matches the call writes the event when the eval
+     * conversation's latest one differs, so a candidate whose first sandbox call lands in another
+     * step still gets the line, once.
+     */
+    environmentPaths?: SandboxRoots;
 }
 /**
  * The connectors and extensions an rc `<x>__<tool>` key can name, from positive evidence in the

package/dist/evals/recorded-tools.js

@@ -1,3 +1,4 @@
+import { environmentPathsChange } from "../runtime/context/environment-paths.js";
 import { assistantIdemKey } from "../runtime/model-call.js";
 import { MATCH_IGNORED_FIELDS } from "../tools/builtin-names.js";
 import { isLegacyPrefixedKey, legacyToolInput, legacyToolKey, } from "../tools/legacy-keys.js";
@@ -137,11 +138,29 @@ export function recordedCalls(s) {
                 started.set(p.callId, p.specHash);
         }
     }
+    // an environment_paths event belongs to the step of the assistant message before it, and holds
+    // for that step's calls and every later step's (until the next one)
+    const pathsOf = new Map();
+    const assistants = own.filter((e) => e.type === "assistant_message").map((e) => e.seq);
+    let current;
+    let next = 0;
+    for (const [i, a] of assistants.entries()) {
+        const end = assistants[i + 1] ?? Number.POSITIVE_INFINITY;
+        for (; next < own.length && own[next].seq < end; next++) {
+            const e = own[next];
+            if (e.type === "environment_paths" && e.seq > a) {
+                current = e.payload.roots;
+            }
+        }
+        if (current !== undefined)
+            pathsOf.set(a, current);
+    }
     const scope = legacyScopeOf(s);
     const out = [];
     for (const e of own) {
         if (e.type !== "assistant_message")
             continue;
+        const paths = pathsOf.get(e.seq);
         const content = e.payload.content;
         for (const b of content) {
             if (b.type !== "tool_call")
@@ -160,6 +179,7 @@ export function recordedCalls(s) {
                 ...(r.loadedTools !== undefined && { loadedTools: r.loadedTools }),
                 ...(r.contentTypes !== undefined && { contentTypes: r.contentTypes }),
                 specHash: started.get(call.id) ?? "",
+                ...(paths !== undefined && { environmentPaths: paths }),
             });
         }
     }
@@ -213,7 +233,14 @@ export class RecordedToolPipeline {
             const rec = this.take(call.name, matchKey(call.name, call.input));
             if (!rec)
                 this.misses++;
+            // the original run had told the model the instance's directories by this call: so does the
+            // replay, when the eval conversation's latest record differs (as the sandbox tools write it)
+            const paths = rec?.environmentPaths;
+            const change = paths === undefined
+                ? null
+                : environmentPathsChange(await eventLog.latestOfType(ctx.conversationId, "environment_paths"), paths, ctx.runId);
             await eventLog.append(ctx.conversationId, [
+                ...(change ? [change] : []),
                 {
                     type: "tool_call_started",
                     runId: ctx.runId,

package/dist/http/api.module.js

@@ -30,6 +30,8 @@ import { ChannelConnectionsController } from "../channels/connections.controller
 import { AttachmentsController } from "../conversations/attachments.controller.js";
 import { ConversationsController } from "../conversations/conversations.controller.js";
 import { ConversationsModule } from "../conversations/conversations.module.js";
+import { DeviceAuthController } from "../devices/device-auth.controller.js";
+import { DeviceAuthModule } from "../devices/device-auth.module.js";
 import { EnvironmentsController } from "../environments/environments.controller.js";
 import { EnvironmentsModule } from "../environments/environments.module.js";
 import { EvalsModule } from "../evals/evals.module.js";
@@ -133,6 +135,7 @@ const CONTROLLERS = [
     OrgOwnedPluginsController,
     OrgComponentsController,
     AdminCatalogRequestsController,
+    DeviceAuthController,
 ];
 /**
  * The api role (nest kernel spec §2): the kernel API (`/api/v1/*`), imported by `KernelModule` only
@@ -158,6 +161,7 @@ ApiModule = __decorate([
             ConversationsModule,
             BackgroundModule,
             EnvironmentsModule,
+            DeviceAuthModule,
             RuntimeModule,
             ChannelsModule,
             EvalsModule,

package/dist/http/gateway-routes.d.ts

@@ -1,15 +1,19 @@
 import type { Logger } from "@capybara-hq/plugin-sdk";
 import type { FastifyInstance } from "fastify";
 import type { ChannelWebhooks } from "../channels/webhook.js";
+import { type DeviceRoutesOptions } from "../devices/device-routes.js";
 /** What the gateway role serves over HTTP besides health and plugin routes. */
 export interface GatewayRoutes {
     webhooks: Pick<ChannelWebhooks, "handle">;
     /** `channels.webhookMaxBodyBytes`. */
     webhookMaxBodyBytes: number;
+    /** The device connection route (`GET /device/connect`, environments spec §13.4). */
+    devices: DeviceRoutesOptions;
 }
 /**
- * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
- * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
- * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. These are raw Fastify routes, not a Nest
+ * module, so the API's global guard and CSRF check do not apply (P-4); each route does its own
+ * verification (the channel plugin's signature check, the machine credential).
  */
 export declare function registerGatewayRoutes(fastify: FastifyInstance, routes: GatewayRoutes, log: Pick<Logger, "error">): Promise<void>;

package/dist/http/gateway-routes.js

@@ -1,8 +1,10 @@
 import { registerChannelWebhookRoute } from "../channels/webhook.controller.js";
+import { registerDeviceConnectRoute } from "../devices/device-routes.js";
 /**
- * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): today the
- * channel webhook. These are raw Fastify routes, not a Nest module, so the API's global guard and
- * CSRF check do not apply (P-4); each route does its own (plugin-side) verification.
+ * Registers the gateway role's HTTP routes (`serveGateway = roles.includes("gateway")`): the
+ * channel webhook and the device connection WebSocket. These are raw Fastify routes, not a Nest
+ * module, so the API's global guard and CSRF check do not apply (P-4); each route does its own
+ * verification (the channel plugin's signature check, the machine credential).
  */
 export async function registerGatewayRoutes(fastify, routes, log) {
     await registerChannelWebhookRoute(fastify, {
@@ -10,4 +12,5 @@ export async function registerGatewayRoutes(fastify, routes, log) {
         maxBodyBytes: routes.webhookMaxBodyBytes,
         log,
     });
+    await registerDeviceConnectRoute(fastify, routes.devices);
 }

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

@@ -35,6 +35,8 @@ const HOT_APPLIERS = {
     "sandbox.maxConcurrentCommands": () => { },
     // The environments service reads the personal limit at every create.
     "environments.maxPersonal": () => { },
+    // The device relay reads the reconnect grace at every disconnect and token response.
+    "environments.device.reconnectGraceSeconds": () => { },
     // Sub-agent limits are read at every dispatch, child step and tool resolution.
     "subagents.maxDepth": () => { },
     "subagents.maxConcurrentPerConversation": () => { },

package/dist/infra/throttler/named-throttlers.d.ts

@@ -25,6 +25,11 @@ export interface NamedThrottler {
  * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
  * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes).
  */
 export declare const NAMED_THROTTLERS: readonly NamedThrottler[];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */

package/dist/infra/throttler/named-throttlers.js

@@ -28,6 +28,11 @@ const LOGIN_MSG = "Too many failed login attempts; try again later";
  * | `PUT /api/v1/me/password` | `change-password`, `change-password-ip` |
  * | `POST /api/v1/setup` | `setup-token`, `setup-ip` |
  * | `POST /api/v1/invitations/:token/accept` | `invitation`, `invitation-ip` |
+ * | `GET /api/v1/device/pending/:userCode`, `POST /api/v1/device/confirm`, `POST /api/v1/device/deny` | `device-code-account` |
+ *
+ * `POST /api/v1/device/authorize` and `POST /api/v1/device/token` opt in to `device-authorize-ip`
+ * and `device-token-ip` with `@Throttled` (every request counts; neither checks a guessable
+ * credential: the device code is 32 random bytes).
  */
 export const NAMED_THROTTLERS = [
     // (login, IP): 10; an attacker filling one login from one IP leaves the owner's other IPs alone (R25)
@@ -114,6 +119,39 @@ export const NAMED_THROTTLERS = [
         message: "Too many invitation attempts; try again later",
         getTracker: ip,
     },
+    // device sign-in codes issued per client address (each one holds Redis state for its TTL): 20.
+    // Opted in with @Throttled, which counts every request before the handler: group and onSuccess
+    // are unused (they matter only to CredentialThrottler).
+    {
+        name: "device-authorize-ip",
+        group: "device-authorize",
+        onSuccess: "clear",
+        limit: 20,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in attempts; try again later",
+        getTracker: ip,
+    },
+    // device token polls per client address (@Throttled like device-authorize-ip): 600, one login
+    // polls up to 120 times (600 s / 5 s), so several machines behind one NAT address fit
+    {
+        name: "device-token-ip",
+        group: "device-token",
+        onSuccess: "clear",
+        limit: 600,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device sign-in polls; try again later",
+        getTracker: ip,
+    },
+    // user codes tried per signed-in person (guessing another machine's code): 10, refunded on success
+    {
+        name: "device-code-account",
+        group: "device-code",
+        onSuccess: "refund",
+        limit: 10,
+        ttl: CREDENTIAL_WINDOW_MS,
+        message: "Too many device code attempts; try again later",
+        getTracker: (req) => sha256(principalAccountId(req)),
+    },
 ];
 /** The storage key of a named throttler's counter for a tracker (shared by the guard and success paths). */
 export const throttlerKey = (name, tracker) => sha256(`${name}:${tracker}`);

package/dist/kernel.module.js

@@ -10,6 +10,7 @@ import { APP_INTERCEPTOR } from "@nestjs/core";
 import { CatalogModule } from "./catalog/catalog.module.js";
 import { ChannelsModule } from "./channels/channels.module.js";
 import { TitlesModule } from "./conversations/titles.js";
+import { DevicesModule } from "./devices/devices.module.js";
 import { ExtensionsModule } from "./extensions/extensions.module.js";
 import { ApiModule } from "./http/api.module.js";
 import { ErrorFilterModule } from "./http/error-filter.module.js";
@@ -110,6 +111,8 @@ let KernelModule = KernelModule_1 = class KernelModule {
                 TitlesModule,
                 UsageReportModule,
                 ChannelsModule,
+                // the @device sandbox provider, registered on every role (any replica may relay to a machine)
+                DevicesModule,
                 // the Platform tool's operation registry and actor facts
                 PlatformModule,
                 // its operations (skills, agents, ...), registered at start on every role

package/dist/lifecycle/kernel-lifecycle.js

@@ -62,6 +62,8 @@ export const STOP_BUDGET_MS = {
 };
 /** 停机时留给渠道长连接交还租约的最少时间（与 runs 阶段并行开始，runs 用尽预算时仍保底）。 */
 const CHANNELS_STOP_MIN_MS = 2_000;
+/** The time the device connections get to close and hand their leases back. */
+const DEVICES_STOP_MS = 2_000;
 /** runs 阶段里留给强制关闭 worker 的余量（预算的其余部分用于等运行到达步骤边界）。 */
 const RUNS_FORCE_CLOSE_MS = 500;
 const errMsg = (e) => (e instanceof Error ? e.message : String(e));
@@ -387,6 +389,9 @@ let KernelLifecycle = class KernelLifecycle {
         this.unwatchConfig = undefined;
         gateway?.unwatch();
         await within("webhooks-unsubscribe", (gateway?.unsubscribe() ?? Promise.resolve()).catch(() => { }), 1_000);
+        // Device connections: closed (1001) and their leases handed back before the HTTP server
+        // closes, so the machines reconnect to another gateway replica at once
+        await within("devices", gateway?.stopDevices() ?? Promise.resolve(), DEVICES_STOP_MS);
         // 不再接 reconcile（进行中的那次由宿主关闭收尾）
         await within("plugin-lifecycle", this.extensionLifecycle.stop(), 1_000);
         // http 阶段：等 listen 与关闭 HTTP 共用一个截止时间；listen 卡满预算时关闭只剩 0ms，直接强制断开

package/dist/platform/exclusions.js

@@ -248,6 +248,39 @@ export const PLATFORM_EXCLUSIONS = [
         reason: "Serves sandbox file bytes",
     },
     // environments (personal cloud environments, environments design phase 1)
+    // connected machines (environments design phase 2): device sign-in by the program and on the
+    // confirmation page, and disconnecting a machine. The machine's WebSocket (`GET /device/connect`)
+    // is a raw gateway-role route, not a Nest controller, so it is not listed (like the webhook)
+    {
+        route: "DELETE /api/v1/orgs/:orgId/environments/:id/machine",
+        category: "human-only",
+        reason: "Disconnects a person's own machine (revokes its credential); a trust decision taken on the environment's page",
+    },
+    {
+        route: "POST /api/v1/device/authorize",
+        category: "transport",
+        reason: "Issues a sign-in code pair to the capybara-device program, which has no credential yet",
+    },
+    {
+        route: "POST /api/v1/device/token",
+        category: "transport",
+        reason: "The capybara-device program polls for its machine credential",
+    },
+    {
+        route: "GET /api/v1/device/pending/:userCode",
+        category: "human-only",
+        reason: "Shows the machine behind a code the person read off their own machine",
+    },
+    {
+        route: "POST /api/v1/device/confirm",
+        category: "human-only",
+        reason: "Lets a machine run commands for the person; only the person, signed in on the web, confirms it",
+    },
+    {
+        route: "POST /api/v1/device/deny",
+        category: "human-only",
+        reason: "Refuses a machine's sign-in code on the confirmation page",
+    },
     {
         route: "GET /api/v1/orgs/:orgId/conversations/:id/tools",
         category: "internal",

package/dist/platform/ops/environments.ops.js

@@ -30,6 +30,13 @@ function stateOf(e) {
             next: "Ask an org admin; use another environment meanwhile.",
         };
     }
+    if (e.filesLost && e.source === "device") {
+        return {
+            state: "files_lost",
+            reason: "Its directory is gone from the connected machine.",
+            next: "Ask the person to run capybara-device logout, then capybara-device login into this environment, on that machine.",
+        };
+    }
     if (e.filesLost) {
         return {
             state: "files_lost",
@@ -44,7 +51,14 @@ const row = (e) => ({
     name: labelOf(e),
     ...stateOf(e),
     isDefault: e.isDefault,
+    source: e.source,
     provider: e.provider,
+    online: e.online,
+    machine: e.machine && {
+        name: e.machine.name,
+        os: e.machine.os,
+        lastSeenAt: e.machine.lastSeenAt,
+    },
     lastUsedAt: e.instance?.lastUsedAt ?? null,
 });
 /**
@@ -95,7 +109,7 @@ let EnvironmentsOperations = class EnvironmentsOperations {
         this.registry.register([
             defineOperation({
                 id: "environments.list",
-                description: "List your own cloud environments in this org: one compact row each (name, state, whether it is the default, provider, last use), plus the default and last used ids and whether new cloud environments can be made. The default environment is shown as Personal.",
+                description: "List your own environments in this org: one compact row each (name, state, whether it is the default, source: cloud or device for a connected machine, provider, whether a device one is online and its machine, last use), plus the default and last used ids and whether new cloud environments can be made. The default environment is shown as Personal.",
                 input: z.object({}).strict(),
                 example: {},
                 authz: { orgAction: "agents.use" },
@@ -113,7 +127,7 @@ let EnvironmentsOperations = class EnvironmentsOperations {
             }),
             defineOperation({
                 id: "environments.get",
-                description: "Read one of your environments with its provider, state, instance, limits and creation time. Takes the id from environments.list.",
+                description: "Read one of your environments with its source (cloud or device), provider, state, instance, connected machine and whether it is online, limits and creation time. Takes the id from environments.list.",
                 input: EnvironmentId,
                 example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
                 authz: { orgAction: "agents.use" },
@@ -208,7 +222,7 @@ let EnvironmentsOperations = class EnvironmentsOperations {
             }),
             defineOperation({
                 id: "environments.reset-files",
-                description: "Wipe one of your environments' files so it starts empty: ALL its files are destroyed (after running commands finish) and cannot be recovered; the next use creates a fresh workspace. Use it when an environment reports its files are lost. The person confirms every reset; it is never remembered. The environment this conversation works in cannot be wiped. Takes the id from environments.list.",
+                description: "Wipe one of your environments' files so it starts empty: ALL its files are destroyed (after running commands finish) and cannot be recovered; the next use creates a fresh workspace. Use it when an environment reports its files are lost (not for a connected machine's environment: its files are on the machine). The person confirms every reset; it is never remembered. The environment this conversation works in cannot be wiped. Takes the id from environments.list.",
                 input: EnvironmentId,
                 example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
                 authz: { orgAction: "agents.use" },
@@ -225,6 +239,10 @@ let EnvironmentsOperations = class EnvironmentsOperations {
                         code: "environment.current",
                         next: "This conversation works in it: ask the person to wipe it on the web, or wipe a different one.",
                     },
+                    {
+                        code: "environment.files_on_device",
+                        next: "Its files are on its connected machine: ask the person to run capybara-device logout, then capybara-device login into this environment, on that machine.",
+                    },
                     {
                         code: "environment.unavailable",
                         next: {

package/dist/roles/gateway-role.d.ts

@@ -1,13 +1,15 @@
 import type { ExtensionContext } from "@capybara-hq/plugin-sdk";
 import { ChannelSupervisor } from "../channels/supervisor.js";
 import { ChannelWebhooks } from "../channels/webhook.js";
+import { DeviceGateway } from "../devices/device-gateway.js";
 import { ExtensionHost } from "../extensions/host.js";
 import type { GatewayRoutes } from "../http/gateway-routes.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 /**
  * The gateway role's parts, driven by `KernelLifecycle` at fixed points of its start order and
  * stop phases: the channel long-connection supervisor (leader election and share) and the webhook
- * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation). Provided
+ * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation), and the
+ * device connections ({@link DeviceGateway}, `GET /device/connect`). Provided
  * only by `GatewayModule`, so a process without the gateway role has none of them.
  */
 export declare class GatewayRole {
@@ -16,6 +18,7 @@ export declare class GatewayRole {
     private readonly bus;
     private readonly supervisor;
     private readonly webhooks;
+    private readonly devices;
     /** The supervisor's subscription to extension instance changes. */
     private unwatchPlugins;
     private unwatchWebhooks;
@@ -23,8 +26,11 @@ export declare class GatewayRole {
     private unsubscribeWebhooks;
     /** The supervisor was started: the runs phase stops it. */
     private supervisorStarted;
-    constructor(config: KernelConfigService, host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "subscribe">, supervisor: ChannelSupervisor, webhooks: ChannelWebhooks);
-    /** The gateway role's HTTP routes (the channel webhook), registered when the app is built. */
+    constructor(config: KernelConfigService, host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "subscribe">, supervisor: ChannelSupervisor, webhooks: ChannelWebhooks, devices: DeviceGateway);
+    /**
+     * The gateway role's HTTP routes (the channel webhook, the device connection), registered when
+     * the app is built.
+     */
     routes(): GatewayRoutes;
     /**
      * Starts the supervisor and the webhook cache invalidation (after the extension load).
@@ -35,6 +41,11 @@ export declare class GatewayRole {
     unwatch(): void;
     /** Ends the webhook cache's `channel.changed` subscription. */
     unsubscribe(): Promise<void>;
+    /**
+     * Closes the device connections (1001) and hands their leases back, before the HTTP server
+     * closes (the machines reconnect to another gateway replica).
+     */
+    stopDevices(): Promise<void>;
     /**
      * The runs phase: the supervisor aborts its connects and hands back its leases (undefined: never
      * started).

package/dist/roles/gateway-role.js

@@ -11,13 +11,15 @@ import { Inject, Injectable } from "@nestjs/common";
 import { CHANNEL_CHANGED_TOPIC } from "../channels/connections.service.js";
 import { ChannelSupervisor } from "../channels/supervisor.js";
 import { ChannelWebhooks } from "../channels/webhook.js";
+import { DeviceGateway } from "../devices/device-gateway.js";
 import { ExtensionHost } from "../extensions/host.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KERNEL_BUS } from "../infra/tokens.js";
 /**
  * The gateway role's parts, driven by `KernelLifecycle` at fixed points of its start order and
  * stop phases: the channel long-connection supervisor (leader election and share) and the webhook
- * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation). Provided
+ * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation), and the
+ * device connections ({@link DeviceGateway}, `GET /device/connect`). Provided
  * only by `GatewayModule`, so a process without the gateway role has none of them.
  */
 let GatewayRole = class GatewayRole {
@@ -26,6 +28,7 @@ let GatewayRole = class GatewayRole {
     bus;
     supervisor;
     webhooks;
+    devices;
     /** The supervisor's subscription to extension instance changes. */
     unwatchPlugins;
     unwatchWebhooks;
@@ -33,18 +36,27 @@ let GatewayRole = class GatewayRole {
     unsubscribeWebhooks;
     /** The supervisor was started: the runs phase stops it. */
     supervisorStarted = false;
-    constructor(config, host, bus, supervisor, webhooks) {
+    constructor(config, host, bus, supervisor, webhooks, devices) {
         this.config = config;
         this.host = host;
         this.bus = bus;
         this.supervisor = supervisor;
         this.webhooks = webhooks;
+        this.devices = devices;
     }
-    /** The gateway role's HTTP routes (the channel webhook), registered when the app is built. */
+    /**
+     * The gateway role's HTTP routes (the channel webhook, the device connection), registered when
+     * the app is built.
+     */
     routes() {
+        const config = this.config.get();
         return {
             webhooks: this.webhooks,
-            webhookMaxBodyBytes: this.config.get().channels.webhookMaxBodyBytes,
+            webhookMaxBodyBytes: config.channels.webhookMaxBodyBytes,
+            devices: {
+                gateway: this.devices,
+                maxFrameBytes: config.environments.device.maxFrameBytes,
+            },
         };
     }
     /**
@@ -79,6 +91,13 @@ let GatewayRole = class GatewayRole {
     unsubscribe() {
         return this.unsubscribeWebhooks?.() ?? Promise.resolve();
     }
+    /**
+     * Closes the device connections (1001) and hands their leases back, before the HTTP server
+     * closes (the machines reconnect to another gateway replica).
+     */
+    stopDevices() {
+        return this.devices.stop();
+    }
     /**
      * The runs phase: the supervisor aborts its connects and hands back its leases (undefined: never
      * started).
@@ -93,6 +112,7 @@ GatewayRole = __decorate([
     __param(1, Inject(ExtensionHost)),
     __param(2, Inject(KERNEL_BUS)),
     __param(3, Inject(ChannelSupervisor)),
-    __param(4, Inject(ChannelWebhooks))
+    __param(4, Inject(ChannelWebhooks)),
+    __param(5, Inject(DeviceGateway))
 ], GatewayRole);
 export { GatewayRole };

package/dist/roles/gateway.module.d.ts

@@ -1,7 +1,8 @@
 /**
  * The gateway role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
  * `gateway`: the channel long-connection supervisor, the webhook inbound (served as a raw Fastify
- * route, `http/gateway-routes.ts`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
+ * route, `http/gateway-routes.ts`), the device connections ({@link DeviceGateway}, `GET
+ * /device/connect`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
  * no cron and no queue consumer (those are the worker role's).
  */
 export declare class GatewayModule {

package/dist/roles/gateway.module.js

@@ -8,20 +8,23 @@ import { Module } from "@nestjs/common";
 import { ChannelsModule } from "../channels/channels.module.js";
 import { ChannelSupervisor } from "../channels/supervisor.js";
 import { ChannelWebhooks } from "../channels/webhook.js";
+import { DeviceGateway } from "../devices/device-gateway.js";
+import { DevicesModule } from "../devices/devices.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { GatewayRole } from "./gateway-role.js";
 /**
  * The gateway role (nest kernel spec §2), imported by `KernelModule` only when `roles` includes
  * `gateway`: the channel long-connection supervisor, the webhook inbound (served as a raw Fastify
- * route, `http/gateway-routes.ts`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
+ * route, `http/gateway-routes.ts`), the device connections ({@link DeviceGateway}, `GET
+ * /device/connect`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
  * no cron and no queue consumer (those are the worker role's).
  */
 let GatewayModule = class GatewayModule {
 };
 GatewayModule = __decorate([
     Module({
-        imports: [ChannelsModule, ExtensionsModule],
-        providers: [ChannelSupervisor, ChannelWebhooks, GatewayRole],
+        imports: [ChannelsModule, ExtensionsModule, DevicesModule],
+        providers: [ChannelSupervisor, ChannelWebhooks, DeviceGateway, GatewayRole],
         exports: [GatewayRole],
     })
 ], GatewayModule);

package/dist/runtime/context/build.d.ts

@@ -233,6 +233,8 @@ export declare function summaryText(summary: string): string;
  *   `user_message` / `assistant_message`（content 原样，含 opaque；aborted 的也回放；媒体引用按
  *   {@link resolveMedia} 换成 base64 或文字占位）/ `reminder`
  *   （`role: "system"`，放在它所在的位置）/ `tools_changed` (`role: "system"`, the text of {@link toolsChangedText}, at its position) /
+ *   `environment_paths` (`role: "system"` at its position, `environmentPathsText`; covered by the
+ *   summary: the latest one follows the summary) /
  *   `run_context` (`role: "system"` at its position, `runContextText`; covered by the summary: the
  *   current context follows the summary whole; a user message's sender line by `senderLines`) /
  *   `background_task_finished`（`role: "system"`, the text of