@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.14

package/dist/platform/ops/setup.ops.d.ts

@@ -0,0 +1,24 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { SetupChecksService } from "../../setup/setup-checks.service.js";
+import { SetupGuidesService } from "../../setup/setup-guides.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Setup guide operations of the `Platform` tool (spec 2026-11-09-setup-guides-v2-design.md §12),
+ * the `setup` domain: the guides a person may see, one guide rendered as Markdown, the cached check
+ * states of a guide and running one check. All are reads (a check never writes anywhere; its cost
+ * is bounded by the cache, the cooldown and the org's concurrency cap) and use the routes'
+ * services, so a guide carries no secret (§6.3) and check results only the fixed, redacted fields.
+ * Entering a secret, OAuth consent and the guide ack stay with the person on the web (`human-only`
+ * and `secret` exclusions); no setup operation takes a value.
+ */
+export declare class SetupOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly checks;
+    private readonly guides;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, checks: SetupChecksService, guides: SetupGuidesService, kdb: KernelDb);
+    /** The actor as the routes see a caller: the org, their role there now and their account. */
+    private caller;
+    onModuleInit(): void;
+}

package/dist/platform/ops/setup.ops.js

@@ -0,0 +1,212 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { CatalogGuidePathParams, CatalogGuideQuery } from "../../catalog/org-catalog.schemas.js";
+import { ApiError } from "../../errors.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { SetupCheckPathParams, SetupCheckRunBody, SetupChecksQuery, SetupGuidePathParams, } from "../../setup/setup-checks.schemas.js";
+import { SetupChecksService } from "../../setup/setup-checks.service.js";
+import { SetupGuidesQuery } from "../../setup/setup-guides.schemas.js";
+import { SetupGuidesService } from "../../setup/setup-guides.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { roleOf } from "./role.js";
+const ITEM = "00000000-0000-4000-8000-000000000000";
+const CONNECTION = "00000000-0000-4000-8000-000000000001";
+/**
+ * Setup guide operations of the `Platform` tool (spec 2026-11-09-setup-guides-v2-design.md §12),
+ * the `setup` domain: the guides a person may see, one guide rendered as Markdown, the cached check
+ * states of a guide and running one check. All are reads (a check never writes anywhere; its cost
+ * is bounded by the cache, the cooldown and the org's concurrency cap) and use the routes'
+ * services, so a guide carries no secret (§6.3) and check results only the fixed, redacted fields.
+ * Entering a secret, OAuth consent and the guide ack stay with the person on the web (`human-only`
+ * and `secret` exclusions); no setup operation takes a value.
+ */
+let SetupOperations = class SetupOperations {
+    registry;
+    checks;
+    guides;
+    kdb;
+    constructor(registry, checks, guides, kdb) {
+        this.registry = registry;
+        this.checks = checks;
+        this.guides = guides;
+        this.kdb = kdb;
+    }
+    /** The actor as the routes see a caller: the org, their role there now and their account. */
+    async caller(ctx) {
+        const role = await roleOf(this.kdb.db, ctx.orgId, ctx.actorAccountId);
+        if (role === null)
+            throw new ApiError("forbidden", "Insufficient organization role");
+        return { orgId: ctx.orgId, role, accountId: ctx.actorAccountId };
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "setup.guides",
+                description: "List the plugin setup guides this person may help with in the org: per guide its targets (channel connections, connectors made from a template, templates switched on without a connector yet), whether the guide changed since a target was set up (drift), a count of the cached check states and the web page where the person does the setup. Org admins get the admin guides; members get the guides for connecting their own account. Read a guide with setup.read.",
+                input: SetupGuidesQuery,
+                example: {},
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/setup-guides"],
+                confirm: "read",
+                run: async (input, ctx) => ({
+                    guides: await this.guides.list(await this.caller(ctx), input),
+                }),
+            }),
+            defineOperation({
+                id: "setup.read",
+                description: "Read one plugin setup guide rendered for a target as a Markdown document: the steps, the app manifest and URLs to paste at the third-party platform, and the checks as '- [check <id>] <label>' lines (run them with setup.check), with the modes, the variables that have no value yet and why, and the web page of the target. Explain the step the person is on. Secrets are never in the guide: ask the person to paste each token or secret into its field on the returned webPath, never into the conversation.",
+                input: CatalogGuidePathParams.extend(CatalogGuideQuery.shape).strict(),
+                example: { itemId: ITEM, guideId: "slack-app", connectionId: CONNECTION },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; list the guides with setup.guides.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; list the guides with setup.guides.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Pass a mode and audience the guide has (setup.guides lists the audience) and the target of its place: connectionId for a channel guide, connectorId for a connector template guide.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins read the admin guides; members read the member section of a connector template guide (audience member).",
+                        },
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, ...q } = input;
+                    return { guide: await this.guides.read(await this.caller(ctx), itemId, guideId, q) };
+                },
+            }),
+            defineOperation({
+                id: "setup.status",
+                description: "Read the cached state of every check of a plugin's setup guide for one target (a channel connection or a connector made from a template), by check id: ok, failing, unknown, running or not_run, with the reason and fix to show the person. Runs nothing; run a check with setup.check.",
+                input: SetupGuidePathParams.extend(SetupChecksQuery.shape).strict(),
+                example: { itemId: ITEM, guideId: "slack-app", connectionId: CONNECTION },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; check the item id on the plugin's page.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; read the guide id from the connection or connector page.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Checks need a saved target: pass connectionId for a channel guide or connectorId for a connector template guide, and a mode and audience the guide has.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins run the admin checks of a guide; members run the member checks (audience member).",
+                        },
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, ...q } = input;
+                    return { results: await this.checks.states(await this.caller(ctx), itemId, guideId, q) };
+                },
+            }),
+            defineOperation({
+                id: "setup.check",
+                description: "Run one check of a plugin's setup guide for one target (a channel connection or a connector made from a template) and return its state: ok, failing (with a reason and a fix to explain), unknown, or running (try again in a moment). A fresh cached result is returned as is; force reruns it, at most once per 10 seconds per check and target. A check only reads; run it after the person says they finished a step.",
+                input: SetupCheckPathParams.extend(SetupCheckRunBody.shape).strict(),
+                example: {
+                    itemId: ITEM,
+                    guideId: "slack-app",
+                    checkId: "bot-token",
+                    connectionId: CONNECTION,
+                },
+                authz: { orgAction: "catalog.read" },
+                mirrors: ["POST /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId/checks/:checkId/run"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "catalog.item_not_found",
+                        next: "The plugin is not in this org's catalog; check the item id on the plugin's page.",
+                    },
+                    {
+                        code: "catalog.guide_not_found",
+                        next: "The plugin has no setup guide with that id; read the guide id from the connection or connector page.",
+                    },
+                    {
+                        code: "channel.not_found",
+                        next: "No channel connection with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "connector.not_found",
+                        next: "No connector made from this guide's template with that id in this org; list the targets with setup.guides.",
+                    },
+                    {
+                        code: "validation_failed",
+                        next: "Checks need a saved target: pass connectionId for a channel guide or connectorId for a connector template guide, and a mode and audience the guide has.",
+                    },
+                    {
+                        code: "forbidden",
+                        next: {
+                            member: "Only org admins run the admin checks of a guide; members run the member checks (audience member).",
+                        },
+                    },
+                    {
+                        code: "catalog.check_not_found",
+                        next: "That check is not in the guide for this mode and audience; read the check ids with setup.status.",
+                    },
+                    {
+                        code: "rate_limited",
+                        next: "This person ran 30 checks in the last minute; wait a minute before running another, and read the cached states with setup.status meanwhile.",
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const { itemId, guideId, checkId, ...body } = input;
+                    return {
+                        result: await this.checks.run(await this.caller(ctx), itemId, guideId, checkId, body),
+                    };
+                },
+            }),
+        ]);
+    }
+};
+SetupOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(SetupChecksService)),
+    __param(2, Inject(SetupGuidesService)),
+    __param(3, Inject(KernelDb))
+], SetupOperations);
+export { SetupOperations };

package/dist/platform/ops/ui.ops.d.ts

@@ -0,0 +1,8 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { PlatformOperations } from "../registry.js";
+/** UI operations of the `Platform` tool (UI slots spec §3): the slot catalog. */
+export declare class UiOperations implements OnModuleInit {
+    private readonly registry;
+    constructor(registry: PlatformOperations);
+    onModuleInit(): void;
+}

package/dist/platform/ops/ui.ops.js

@@ -0,0 +1,41 @@
+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 { UI_SLOTS } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { z } from "zod";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+/** UI operations of the `Platform` tool (UI slots spec §3): the slot catalog. */
+let UiOperations = class UiOperations {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "ui.slots",
+                description: "List the UI slots an extension can contribute to (id, version, where it is, scope and args, accepted kinds view / embed, minimum role, anchors). Use a slot id as a ui contribution's `slot` in a plugin manifest.",
+                input: z.object({}).strict(),
+                example: {},
+                // any signed-in person may call the route; every run's actor is a member of this org
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/ui/slots"],
+                confirm: "read",
+                run: async () => ({ slots: UI_SLOTS }),
+            }),
+        ]);
+    }
+};
+UiOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations))
+], UiOperations);
+export { UiOperations };

package/dist/platform/platform-ops.module.d.ts

@@ -10,7 +10,7 @@ import { ChannelsOperations } from "./ops/channels.ops.js";
 import { ComponentsOperations } from "./ops/components.ops.js";
 import { ConnectorsOperations } from "./ops/connectors.ops.js";
 import { ConversationsOperations } from "./ops/conversations.ops.js";
-import { EnvironmentsOperations } from "./ops/environments.ops.js";
+import { DevicesOperations } from "./ops/devices.ops.js";
 import { EvalsOperations } from "./ops/evals.ops.js";
 import { ExtensionsOperations } from "./ops/extensions.ops.js";
 import { ExtensionsAdminOperations } from "./ops/extensions-admin.ops.js";
@@ -24,13 +24,15 @@ import { PlatformOperationsProvider } from "./ops/platform.ops.js";
 import { PluginsOperations } from "./ops/plugins.ops.js";
 import { PreviewersOperations } from "./ops/previewers.ops.js";
 import { RequestsOperations } from "./ops/requests.ops.js";
+import { SetupOperations } from "./ops/setup.ops.js";
 import { SkillsOperations } from "./ops/skills.ops.js";
 import { ThemesOperations } from "./ops/themes.ops.js";
+import { UiOperations } from "./ops/ui.ops.js";
 /**
  * One provider per domain, each taking `PlatformOperations` as its first constructor argument:
  * the parity test in `tools/checks` builds the operations from it without a Nest app.
  */
-export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof EnvironmentsOperations, typeof AgentSkillsOperations, typeof ThemesOperations];
+export declare const PLATFORM_OPERATION_PROVIDERS: readonly [typeof PlatformOperationsProvider, typeof SkillsOperations, typeof AgentsOperations, typeof AgentTemplatesOperations, typeof PluginsOperations, typeof MarketplacesOperations, typeof RequestsOperations, typeof ConnectorsOperations, typeof ExtensionsOperations, typeof ConversationsOperations, typeof ComponentsOperations, typeof AccountsOperations, typeof OrgsOperations, typeof AdminOperations, typeof CatalogAdminOperations, typeof OrgPluginsOperations, typeof ExtensionsAdminOperations, typeof ModelsOperations, typeof InboxOperations, typeof ApprovalsOperations, typeof ChannelsOperations, typeof OrgSettingsOperations, typeof EvalsOperations, typeof BackgroundOperations, typeof PreviewersOperations, typeof DevicesOperations, typeof AgentSkillsOperations, typeof ThemesOperations, typeof SetupOperations, typeof UiOperations];
 /**
  * The `Platform` tool's operations (ruling P2): one provider per domain, each registering its
  * operations into `PlatformOperations` from `onModuleInit`. It imports the domain modules, which

package/dist/platform/platform-ops.module.js

@@ -10,7 +10,7 @@ import { BackgroundModule } from "../background/background.module.js";
 import { CatalogModule } from "../catalog/catalog.module.js";
 import { ChannelsModule } from "../channels/channels.module.js";
 import { ConversationsModule } from "../conversations/conversations.module.js";
-import { EnvironmentsModule } from "../environments/environments.module.js";
+import { DevicesModule } from "../devices/devices.module.js";
 import { EvalsModule } from "../evals/evals.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { FilesModule } from "../files/files.module.js";
@@ -19,6 +19,7 @@ import { InboxModule } from "../inbox/inbox.module.js";
 import { ModelsModule } from "../models/models.module.js";
 import { OrgsModule } from "../orgs/orgs.module.js";
 import { ProvidersModule } from "../runtime/providers.js";
+import { SetupModule } from "../setup/setup.module.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { ThemesModule } from "../themes/themes.module.js";
 import { ToolsModule } from "../tools/tools.module.js";
@@ -34,7 +35,7 @@ import { ChannelsOperations } from "./ops/channels.ops.js";
 import { ComponentsOperations } from "./ops/components.ops.js";
 import { ConnectorsOperations } from "./ops/connectors.ops.js";
 import { ConversationsOperations } from "./ops/conversations.ops.js";
-import { EnvironmentsOperations } from "./ops/environments.ops.js";
+import { DevicesOperations } from "./ops/devices.ops.js";
 import { EvalsOperations } from "./ops/evals.ops.js";
 import { ExtensionsOperations } from "./ops/extensions.ops.js";
 import { ExtensionsAdminOperations } from "./ops/extensions-admin.ops.js";
@@ -48,8 +49,10 @@ import { PlatformOperationsProvider } from "./ops/platform.ops.js";
 import { PluginsOperations } from "./ops/plugins.ops.js";
 import { PreviewersOperations } from "./ops/previewers.ops.js";
 import { RequestsOperations } from "./ops/requests.ops.js";
+import { SetupOperations } from "./ops/setup.ops.js";
 import { SkillsOperations } from "./ops/skills.ops.js";
 import { ThemesOperations } from "./ops/themes.ops.js";
+import { UiOperations } from "./ops/ui.ops.js";
 import { PlatformModule } from "./platform.module.js";
 /**
  * One provider per domain, each taking `PlatformOperations` as its first constructor argument:
@@ -86,11 +89,15 @@ export const PLATFORM_OPERATION_PROVIDERS = [
     EvalsOperations,
     BackgroundOperations,
     PreviewersOperations,
-    // Task 11b: environments, agent skills
-    EnvironmentsOperations,
+    // Task 11b: devices, agent skills
+    DevicesOperations,
     AgentSkillsOperations,
     // themes (themes spec §9)
     ThemesOperations,
+    // setup guide checks (setup guides v2 §12; plan task 13 adds the rest of the domain)
+    SetupOperations,
+    // UI slot catalog (UI slots spec §3)
+    UiOperations,
 ];
 /**
  * The `Platform` tool's operations (ruling P2): one provider per domain, each registering its
@@ -116,10 +123,11 @@ PlatformOpsModule = __decorate([
             InboxModule,
             ChannelsModule,
             EvalsModule,
-            EnvironmentsModule,
+            DevicesModule,
             BackgroundModule,
             FilesModule,
             ThemesModule,
+            SetupModule,
         ],
         providers: [...PLATFORM_OPERATION_PROVIDERS],
     })

package/dist/platform/route-schemas.js

@@ -11,7 +11,7 @@ import { ORG_EXTENSION_ROUTES } from "../catalog/org-extension.schemas.js";
 import { ORG_PLUGIN_UPLOAD_ROUTES } from "../catalog/org-plugin-uploads.schemas.js";
 import { CHANNEL_ROUTES } from "../channels/channels.schemas.js";
 import { CONVERSATION_ROUTES } from "../conversations/conversations.schemas.js";
-import { ENVIRONMENT_ROUTES } from "../environments/environments.schemas.js";
+import { DEVICE_ROUTES } from "../devices/devices.schemas.js";
 import { EVAL_ROUTES } from "../evals/evals.schemas.js";
 import { EXTENSION_POINT_ROUTES } from "../extensions/point-defaults.schemas.js";
 import { FILE_PREVIEWER_ROUTES } from "../files/previewers.schemas.js";
@@ -19,10 +19,13 @@ import { ME_ROUTES } from "../identity/me.schemas.js";
 import { INBOX_ROUTES } from "../inbox/inbox.schemas.js";
 import { ORG_MODEL_ROUTES } from "../models/org-models.schemas.js";
 import { ORG_ROUTES, ORG_SETTINGS_ROUTES } from "../orgs/orgs.schemas.js";
+import { SETUP_CHECK_ROUTES } from "../setup/setup-checks.schemas.js";
+import { SETUP_GUIDE_ROUTES } from "../setup/setup-guides.schemas.js";
 import { SKILL_ROUTES } from "../skills/skills.schemas.js";
 import { THEME_ROUTES } from "../themes/themes.schemas.js";
 import { APPROVAL_ROUTES } from "../tools/approvals.schemas.js";
 import { CONNECTOR_ROUTES } from "../tools/connectors.schemas.js";
+import { UI_ROUTES } from "../ui/ui.schemas.js";
 /**
  * Every route a Platform operation mirrors, from the exported `<domain>.schemas.ts` next to each
  * controller. An operation builds its input from these (`pick` / `omit` / `extend`); the parity
@@ -57,10 +60,15 @@ export const ROUTE_SCHEMAS = [
     ...EVAL_ROUTES,
     ...BACKGROUND_ROUTES,
     ...FILE_PREVIEWER_ROUTES,
-    // Task 11b: environments
-    ...ENVIRONMENT_ROUTES,
+    // Task 11b: devices
+    ...DEVICE_ROUTES,
     // personal preferences (run context spec §3.4)
     ...ME_ROUTES,
     // themes (themes spec §9)
     ...THEME_ROUTES,
+    // setup guide checks (setup guides v2 §10.3, §12)
+    ...SETUP_CHECK_ROUTES,
+    ...SETUP_GUIDE_ROUTES,
+    // UI slots (UI slots spec §3)
+    ...UI_ROUTES,
 ];

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

@@ -1,15 +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";
+import { LocalDeviceGateway } from "../local-devices/local-device-gateway.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), and the
- * device connections ({@link DeviceGateway}, `GET /device/connect`). Provided
+ * device connections ({@link LocalDeviceGateway}, `GET /device/connect`). Provided
  * only by `GatewayModule`, so a process without the gateway role has none of them.
  */
 export declare class GatewayRole {
@@ -26,7 +26,7 @@ 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, devices: DeviceGateway);
+    constructor(config: KernelConfigService, host: ExtensionHost, bus: Pick<ExtensionContext["bus"], "subscribe">, supervisor: ChannelSupervisor, webhooks: ChannelWebhooks, devices: LocalDeviceGateway);
     /**
      * The gateway role's HTTP routes (the channel webhook, the device connection), registered when
      * the app is built.

package/dist/roles/gateway-role.js

@@ -11,15 +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";
+import { LocalDeviceGateway } from "../local-devices/local-device-gateway.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), and the
- * device connections ({@link DeviceGateway}, `GET /device/connect`). Provided
+ * device connections ({@link LocalDeviceGateway}, `GET /device/connect`). Provided
  * only by `GatewayModule`, so a process without the gateway role has none of them.
  */
 let GatewayRole = class GatewayRole {
@@ -55,7 +55,7 @@ let GatewayRole = class GatewayRole {
             webhookMaxBodyBytes: config.channels.webhookMaxBodyBytes,
             devices: {
                 gateway: this.devices,
-                maxFrameBytes: config.environments.device.maxFrameBytes,
+                maxFrameBytes: config.devices.local.maxFrameBytes,
             },
         };
     }
@@ -113,6 +113,6 @@ GatewayRole = __decorate([
     __param(2, Inject(KERNEL_BUS)),
     __param(3, Inject(ChannelSupervisor)),
     __param(4, Inject(ChannelWebhooks)),
-    __param(5, Inject(DeviceGateway))
+    __param(5, Inject(LocalDeviceGateway))
 ], GatewayRole);
 export { GatewayRole };

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

@@ -1,7 +1,7 @@
 /**
  * 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`), the device connections ({@link DeviceGateway}, `GET
+ * route, `http/gateway-routes.ts`), the device connections ({@link LocalDeviceGateway}, `GET
  * /device/connect`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
  * no cron and no queue consumer (those are the worker role's).
  */

package/dist/roles/gateway.module.js

@@ -8,14 +8,14 @@ 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 { LocalDeviceGateway } from "../local-devices/local-device-gateway.js";
+import { LocalDevicesModule } from "../local-devices/local-devices.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`), the device connections ({@link DeviceGateway}, `GET
+ * route, `http/gateway-routes.ts`), the device connections ({@link LocalDeviceGateway}, `GET
  * /device/connect`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
  * no cron and no queue consumer (those are the worker role's).
  */
@@ -23,8 +23,8 @@ let GatewayModule = class GatewayModule {
 };
 GatewayModule = __decorate([
     Module({
-        imports: [ChannelsModule, ExtensionsModule, DevicesModule],
-        providers: [ChannelSupervisor, ChannelWebhooks, DeviceGateway, GatewayRole],
+        imports: [ChannelsModule, ExtensionsModule, LocalDevicesModule],
+        providers: [ChannelSupervisor, ChannelWebhooks, LocalDeviceGateway, GatewayRole],
         exports: [GatewayRole],
     })
 ], GatewayModule);

package/dist/roles/worker.module.js

@@ -18,7 +18,7 @@ import { AttachmentsModule } from "../conversations/attachments.module.js";
 import { AttachmentCleanupJob } from "../conversations/attachments.service.js";
 import { EventLogModule } from "../conversations/event-log.js";
 import { TitlesModule } from "../conversations/titles.js";
-import { LegacySandboxCleanupJob } from "../environments/legacy-cleanup.job.js";
+import { LegacySandboxCleanupJob } from "../devices/legacy-cleanup.job.js";
 import { EvalWorkersModule } from "../evals/evals.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { PluginsReconcileJob } from "../extensions/lifecycle.js";

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

@@ -233,7 +233,7 @@ 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
+ *   `device_paths` (`role: "system"` at its position, `devicePathsText`; 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`) /

package/dist/runtime/context/build.js

@@ -4,7 +4,7 @@ import { renderBackgroundFinished } from "../../background/render.js";
 import { isAbsorbable, } from "../../conversations/events.js";
 import { catalogText, isAlwaysLoaded } from "../../tools/builtins/tool-search.js";
 import { renderSubagentDelivery } from "../subagents/render.js";
-import { environmentPathsAt, environmentPathsText } from "./environment-paths.js";
+import { devicePathsAt, devicePathsText } from "./device-paths.js";
 import { LEGACY_CATALOG_HEADER, LEGACY_SKILL_TEXTS, usesLegacyToolNames } from "./legacy-text.js";
 import { currentRunContext, runContextEvents, runContextFullText, runContextText, senderLines, } from "./run-context.js";
 import { invokedSkillNames, invokedSkillsText, SKILL_TEXTS, skillsCatalogEvents, snapshotChangeText, snapshotCurrentText, snapshotSystemText, systemSkillsCatalog, } from "./skills.js";
@@ -337,7 +337,7 @@ export function summaryText(summary) {
  *   `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
+ *   `device_paths` (`role: "system"` at its position, `devicePathsText`; 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`) /
@@ -552,9 +552,9 @@ export function buildModelRequest(input) {
         }
         // environments spec §13.1: the instance's directories told before the boundary follow the
         // summary again (the model keeps using the real paths)
-        const paths = environmentPathsAt(events, after);
+        const paths = devicePathsAt(events, after);
         if (paths) {
-            messages.push({ role: "system", content: environmentPathsText(paths.payload.roots) });
+            messages.push({ role: "system", content: devicePathsText(paths.payload.roots) });
         }
         // 被摘要覆盖的变更提醒不再发送：摘要时生效的目录与 system 里的不同 → 紧随摘要补上完整的当前目录
         const covered = skillSnaps.filter((e) => e.seq <= after).at(-1);
@@ -631,8 +631,8 @@ export function buildModelRequest(input) {
                 break;
             // the instance's directories (environments spec §13.1): logged during a step's tool call,
             // so rendered after that step's tool results
-            case "environment_paths":
-                messages.push({ role: "system", content: environmentPathsText(e.payload.roots) });
+            case "device_paths":
+                messages.push({ role: "system", content: devicePathsText(e.payload.roots) });
                 break;
             // hook_denied is not model-visible: the model sees only the denied tool call's tool_result
             // (and nothing for a denied model request), so request building skips it

package/dist/runtime/context/compaction.js

@@ -134,7 +134,7 @@ function transcriptLine(e) {
         // phase D: a forked skill's report is user content of the request (build.ts)
         case "skill_fork_result":
             return `User: ${e.payload.text}`;
-        // environment_paths is left out too: the latest one follows the summary (build.ts)
+        // device_paths is left out too: the latest one follows the summary (build.ts)
         // run_context is left out: its current values follow the summary anyway (build.ts), and
         // stale names should not be summarised as current
         case "tool_result":