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

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

@@ -0,0 +1,142 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { AdminModule } from "../admin/admin.module.js";
+import { AgentsModule } from "../agents/agents.module.js";
+import { BackgroundModule } from "../background/background.module.js";
+import { AppearanceModule } from "../catalog/appearance.service.js";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { ChannelsModule } from "../channels/channels.module.js";
+import { ConversationsModule } from "../conversations/conversations.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";
+import { IdentityModule } from "../identity/identity.module.js";
+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";
+import { AccountsOperations } from "./ops/accounts.ops.js";
+import { AdminOperations } from "./ops/admin.ops.js";
+import { AdminItemsOperations } from "./ops/admin-items.ops.js";
+import { AgentSkillsOperations } from "./ops/agent-skills.ops.js";
+import { AgentTemplatesOperations } from "./ops/agent-templates.ops.js";
+import { AgentsOperations } from "./ops/agents.ops.js";
+import { ApprovalsOperations } from "./ops/approvals.ops.js";
+import { BackgroundOperations } from "./ops/background.ops.js";
+import { CatalogAdminOperations } from "./ops/catalog-admin.ops.js";
+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 { 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";
+import { InboxOperations } from "./ops/inbox.ops.js";
+import { MarketplacesOperations } from "./ops/marketplaces.ops.js";
+import { ModelsOperations } from "./ops/models.ops.js";
+import { OrgPluginsOperations } from "./ops/org-plugins.ops.js";
+import { OrgSettingsOperations } from "./ops/org-settings.ops.js";
+import { OrgsOperations } from "./ops/orgs.ops.js";
+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:
+ * the parity test in `tools/checks` builds the operations from it without a Nest app.
+ */
+export const PLATFORM_OPERATION_PROVIDERS = [
+    PlatformOperationsProvider,
+    SkillsOperations,
+    AgentsOperations,
+    AgentTemplatesOperations,
+    PluginsOperations,
+    MarketplacesOperations,
+    RequestsOperations,
+    ConnectorsOperations,
+    ExtensionsOperations,
+    ConversationsOperations,
+    ComponentsOperations,
+    // Task 7: admin accounts and orgs
+    AccountsOperations,
+    OrgsOperations,
+    AdminOperations,
+    // Task 8: admin catalog, extensions, marketplaces, models, org uploads
+    CatalogAdminOperations,
+    OrgPluginsOperations,
+    ExtensionsAdminOperations,
+    ModelsOperations,
+    // Task 9: inbox and pending reads
+    InboxOperations,
+    ApprovalsOperations,
+    // Task 10: channels, org settings
+    ChannelsOperations,
+    OrgSettingsOperations,
+    // Task 11: evals, background tasks, file previewers
+    EvalsOperations,
+    BackgroundOperations,
+    PreviewersOperations,
+    // 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,
+    // every org's agents and connectors, the conversation org's through the tool (spec §4.5)
+    AdminItemsOperations,
+];
+/**
+ * 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
+ * `PlatformModule` itself must not.
+ */
+let PlatformOpsModule = class PlatformOpsModule {
+};
+PlatformOpsModule = __decorate([
+    Module({
+        imports: [
+            PlatformModule,
+            AdminModule,
+            SkillsModule,
+            AgentsModule,
+            OrgsModule,
+            CatalogModule,
+            AppearanceModule,
+            ExtensionsModule,
+            ToolsModule,
+            ConversationsModule,
+            IdentityModule,
+            ModelsModule,
+            ProvidersModule,
+            InboxModule,
+            ChannelsModule,
+            EvalsModule,
+            DevicesModule,
+            BackgroundModule,
+            FilesModule,
+            ThemesModule,
+            SetupModule,
+        ],
+        providers: [...PLATFORM_OPERATION_PROVIDERS],
+    })
+], PlatformOpsModule);
+export { PlatformOpsModule };

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

@@ -0,0 +1,8 @@
+/**
+ * The `Platform` tool's core (Platform tool spec §3, §6, §7): the operation registry, the actor
+ * facts and the agent docs. It imports no domain module (ruling P2), so `ToolsModule` can import it without a
+ * cycle; domain providers register their operations into `PlatformOperations` from
+ * `onModuleInit`.
+ */
+export declare class PlatformModule {
+}

package/dist/platform/platform.module.js

@@ -0,0 +1,25 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { PlatformActor } from "./actor.js";
+import { AgentDocs } from "./agent-docs.js";
+import { PlatformOperations } from "./registry.js";
+/**
+ * The `Platform` tool's core (Platform tool spec §3, §6, §7): the operation registry, the actor
+ * facts and the agent docs. It imports no domain module (ruling P2), so `ToolsModule` can import it without a
+ * cycle; domain providers register their operations into `PlatformOperations` from
+ * `onModuleInit`.
+ */
+let PlatformModule = class PlatformModule {
+};
+PlatformModule = __decorate([
+    Module({
+        providers: [PlatformOperations, PlatformActor, AgentDocs],
+        exports: [PlatformOperations, PlatformActor, AgentDocs],
+    })
+], PlatformModule);
+export { PlatformModule };

package/dist/platform/registry.d.ts

@@ -0,0 +1,30 @@
+import { type PlatformOperation } from "./operation.js";
+/**
+ * The `Platform` tool's operations (spec §7). Domain providers add theirs with {@link register}
+ * from `onModuleInit` (ruling P2: this module imports no domain module); a bad batch throws and
+ * registers nothing, so a mistake fails the kernel's start.
+ */
+export declare class PlatformOperations {
+    private readonly ops;
+    /**
+     * Adds `ops`. Throws on an id not shaped `<domain>.<verb>`, a domain outside
+     * {@link PLATFORM_DOMAINS}, a duplicate id (in the batch or already registered), or a write
+     * (`confirm` other than `read`) without `summary`.
+     */
+    register(ops: readonly PlatformOperation[]): void;
+    domains(): readonly {
+        id: string;
+        description: string;
+    }[];
+    /** The domain's operations, sorted by id. */
+    inDomain(domain: string): PlatformOperation[];
+    get(id: string): PlatformOperation | null;
+    /** Every operation, sorted by id. */
+    all(): PlatformOperation[];
+    /**
+     * Keyword search (deterministic, like ToolSearch's): per distinct query term,
+     * `idf × (ID_WEIGHT if in the id + 1 if in the description)`; a term also matches a word it is a
+     * prefix of. Zero scores are dropped; ties go by id.
+     */
+    search(query: string, limit: number): PlatformOperation[];
+}

package/dist/platform/registry.js

@@ -0,0 +1,111 @@
+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;
+};
+import { Injectable } from "@nestjs/common";
+import { tokenize } from "../tools/builtins/tool-search.js";
+import { OPERATION_ID, operationDomain, PLATFORM_DOMAINS, } from "./operation.js";
+/** A word of an operation id weighs more than a word of its description (like ToolSearch). */
+const ID_WEIGHT = 2;
+/** The shortest query term that also matches as a word's prefix (`skill` → `skills`). */
+const MIN_PREFIX = 3;
+const DOMAIN_IDS = new Set(PLATFORM_DOMAINS.map((d) => d.id));
+const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+/** A query term matches a word when equal, or as its prefix when long enough. */
+const matches = (words, term) => {
+    if (words.has(term))
+        return true;
+    if (term.length < MIN_PREFIX)
+        return false;
+    for (const w of words)
+        if (w.startsWith(term))
+            return true;
+    return false;
+};
+/**
+ * The `Platform` tool's operations (spec §7). Domain providers add theirs with {@link register}
+ * from `onModuleInit` (ruling P2: this module imports no domain module); a bad batch throws and
+ * registers nothing, so a mistake fails the kernel's start.
+ */
+let PlatformOperations = class PlatformOperations {
+    ops = new Map();
+    /**
+     * Adds `ops`. Throws on an id not shaped `<domain>.<verb>`, a domain outside
+     * {@link PLATFORM_DOMAINS}, a duplicate id (in the batch or already registered), or a write
+     * (`confirm` other than `read`) without `summary`.
+     */
+    register(ops) {
+        const seen = new Set();
+        for (const op of ops) {
+            if (!OPERATION_ID.test(op.id)) {
+                throw new Error(`Platform operation id "${op.id}" is not shaped <domain>.<verb>`);
+            }
+            if (!DOMAIN_IDS.has(operationDomain(op.id))) {
+                throw new Error(`Platform operation "${op.id}" names an unknown domain`);
+            }
+            if (seen.has(op.id) || this.ops.has(op.id)) {
+                throw new Error(`duplicate Platform operation "${op.id}"`);
+            }
+            if (op.confirm !== "read" && op.summary === undefined) {
+                throw new Error(`Platform operation "${op.id}" is a write without a summary`);
+            }
+            seen.add(op.id);
+        }
+        for (const op of ops)
+            this.ops.set(op.id, op);
+    }
+    domains() {
+        return PLATFORM_DOMAINS;
+    }
+    /** The domain's operations, sorted by id. */
+    inDomain(domain) {
+        return this.all().filter((op) => operationDomain(op.id) === domain);
+    }
+    get(id) {
+        return this.ops.get(id) ?? null;
+    }
+    /** Every operation, sorted by id. */
+    all() {
+        return [...this.ops.values()].sort(byId);
+    }
+    /**
+     * Keyword search (deterministic, like ToolSearch's): per distinct query term,
+     * `idf × (ID_WEIGHT if in the id + 1 if in the description)`; a term also matches a word it is a
+     * prefix of. Zero scores are dropped; ties go by id.
+     */
+    search(query, limit) {
+        const terms = [...new Set(tokenize(query))];
+        if (terms.length === 0)
+            return [];
+        const docs = this.all().map((op) => ({
+            op,
+            id: new Set(tokenize(op.id)),
+            desc: new Set(tokenize(op.description)),
+        }));
+        const n = docs.length;
+        const idf = new Map();
+        for (const term of terms) {
+            const df = docs.filter((d) => matches(d.id, term) || matches(d.desc, term)).length;
+            idf.set(term, df === 0 ? 0 : Math.log(1 + n / df));
+        }
+        return docs
+            .map((d) => {
+            let score = 0;
+            for (const term of terms) {
+                const w = (matches(d.id, term) ? ID_WEIGHT : 0) + (matches(d.desc, term) ? 1 : 0);
+                score += w * (idf.get(term) ?? 0);
+            }
+            return { op: d.op, score };
+        })
+            .filter((x) => x.score > 0)
+            .sort((a, b) => (b.score !== a.score ? b.score - a.score : byId(a.op, b.op)))
+            .slice(0, limit)
+            .map((x) => x.op);
+    }
+};
+PlatformOperations = __decorate([
+    Injectable()
+], PlatformOperations);
+export { PlatformOperations };

package/dist/platform/route-schemas.d.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+/**
+ * The zod schemas one HTTP route validates (spec §14.5 item 3), as its controller uses them:
+ * `route` is the `check:platform-ops` key (`POST /api/v1/orgs/:orgId/skills`), `params` its path
+ * params but `:orgId` (the conversation's org, never an operation field).
+ */
+export interface RouteSchemas {
+    route: string;
+    body?: z.ZodType;
+    query?: z.ZodType;
+    params?: z.ZodType;
+}
+/**
+ * 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
+ * test in `tools/checks` compares the two. A route mirrored by a new operation adds its entry here.
+ */
+export declare const ROUTE_SCHEMAS: readonly RouteSchemas[];

package/dist/platform/route-schemas.js

@@ -0,0 +1,85 @@
+import { ADMIN_ROUTES } from "../admin/admin.schemas.js";
+import { ADMIN_ITEM_ROUTES } from "../admin/admin-items.schemas.js";
+import { AUDIT_ROUTES } from "../admin/audit.schemas.js";
+import { ADMIN_EXTENSION_ROUTES } from "../admin/extensions.schemas.js";
+import { OVERVIEW_ROUTES } from "../admin/overview.schemas.js";
+import { AGENT_ROUTES } from "../agents/agents.schemas.js";
+import { AGENT_TEMPLATE_ROUTES } from "../agents/templates.schemas.js";
+import { BACKGROUND_ROUTES } from "../background/background.schemas.js";
+import { ADMIN_CATALOG_ROUTES } from "../catalog/admin-catalog.schemas.js";
+import { APPEARANCE_ROUTES } from "../catalog/appearance.schemas.js";
+import { COMPONENT_SCOPE_ROUTES } from "../catalog/component-scope.schemas.js";
+import { MARKETPLACE_ROUTES } from "../catalog/marketplaces.schemas.js";
+import { ORG_CATALOG_ROUTES } from "../catalog/org-catalog.schemas.js";
+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 { 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";
+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
+ * test in `tools/checks` compares the two. A route mirrored by a new operation adds its entry here.
+ */
+export const ROUTE_SCHEMAS = [
+    ...SKILL_ROUTES,
+    ...AGENT_ROUTES,
+    ...AGENT_TEMPLATE_ROUTES,
+    ...ORG_CATALOG_ROUTES,
+    ...ADMIN_CATALOG_ROUTES,
+    ...MARKETPLACE_ROUTES,
+    ...CONNECTOR_ROUTES,
+    ...COMPONENT_SCOPE_ROUTES,
+    ...ORG_EXTENSION_ROUTES,
+    ...CONVERSATION_ROUTES,
+    // Task 7: admin accounts, orgs, deployment settings, platform models
+    ...ADMIN_ROUTES,
+    ...ORG_ROUTES,
+    // Task 8: admin catalog, extensions, marketplaces, models, org uploads
+    ...ADMIN_EXTENSION_ROUTES,
+    ...ORG_PLUGIN_UPLOAD_ROUTES,
+    ...EXTENSION_POINT_ROUTES,
+    ...ORG_MODEL_ROUTES,
+    // Task 9: inbox and pending reads
+    ...INBOX_ROUTES,
+    ...APPROVAL_ROUTES,
+    // Task 10: channels, org settings
+    ...CHANNEL_ROUTES,
+    ...ORG_SETTINGS_ROUTES,
+    // Task 11: evals, background tasks, file previewers
+    ...EVAL_ROUTES,
+    ...BACKGROUND_ROUTES,
+    ...FILE_PREVIEWER_ROUTES,
+    // Task 11b: devices
+    ...DEVICE_ROUTES,
+    // personal preferences (run context spec §3.4)
+    ...ME_ROUTES,
+    // themes (themes spec §9)
+    ...THEME_ROUTES,
+    // a plugin's suggested appearance (client extensions spec §6.5)
+    ...APPEARANCE_ROUTES,
+    // setup guide checks (setup guides v2 §10.3, §12)
+    ...SETUP_CHECK_ROUTES,
+    ...SETUP_GUIDE_ROUTES,
+    // UI slots (UI slots spec §3)
+    ...UI_ROUTES,
+    // every org's agents and connectors (admin agents and connectors spec §4)
+    ...ADMIN_ITEM_ROUTES,
+    // the admin overview and the platform-level audit log (admin overview spec §5.2)
+    ...OVERVIEW_ROUTES,
+    ...AUDIT_ROUTES,
+];

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

@@ -4,10 +4,12 @@ import { ChannelWebhooks } from "../channels/webhook.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). Provided
+ * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation), and the
+ * 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 {
@@ -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,18 +26,30 @@ 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: LocalDeviceGateway);
+    /**
+     * 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).
      * `checkpoint` throws when a stop began meanwhile.
      */
     start(checkpoint: () => void): Promise<void>;
+    /** The channel long connections this process holds (replica presence). */
+    channelsHeld(): number;
+    /** The device sockets open on this process (replica presence). */
+    devicesConnected(): number;
     /** Stops watching extension instance changes (the stop's first step). */
     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

@@ -14,10 +14,12 @@ import { ChannelWebhooks } from "../channels/webhook.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). Provided
+ * inbound (its raw Fastify route, {@link routes}, and its runtime cache's invalidation), and the
+ * 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 {
@@ -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.devices.local.maxFrameBytes,
+            },
         };
     }
     /**
@@ -70,6 +82,14 @@ let GatewayRole = class GatewayRole {
         this.unwatchWebhooks = this.host.onChange(() => webhooks.invalidateAll());
         checkpoint();
     }
+    /** The channel long connections this process holds (replica presence). */
+    channelsHeld() {
+        return this.supervisor.heldCount();
+    }
+    /** The device sockets open on this process (replica presence). */
+    devicesConnected() {
+        return this.devices.connectionCount();
+    }
     /** Stops watching extension instance changes (the stop's first step). */
     unwatch() {
         this.unwatchPlugins?.();
@@ -79,6 +99,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 +120,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(LocalDeviceGateway))
 ], 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 LocalDeviceGateway}, `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

@@ -9,19 +9,22 @@ import { ChannelsModule } from "../channels/channels.module.js";
 import { ChannelSupervisor } from "../channels/supervisor.js";
 import { ChannelWebhooks } from "../channels/webhook.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`) and {@link GatewayRole}, which `KernelLifecycle` drives. It runs
+ * 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).
  */
 let GatewayModule = class GatewayModule {
 };
 GatewayModule = __decorate([
     Module({
-        imports: [ChannelsModule, ExtensionsModule],
-        providers: [ChannelSupervisor, ChannelWebhooks, GatewayRole],
+        imports: [ChannelsModule, ExtensionsModule, LocalDevicesModule],
+        providers: [ChannelSupervisor, ChannelWebhooks, LocalDeviceGateway, GatewayRole],
         exports: [GatewayRole],
     })
 ], GatewayModule);

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

@@ -1,3 +1,4 @@
+import { PluginScopeSyncProcessor } from "../catalog/scope-sync.js";
 import { ChannelsProcessor } from "../channels/channels.module.js";
 import { ChannelOutbound } from "../channels/outbound.js";
 import { TitleQueue } from "../conversations/titles.js";
@@ -14,8 +15,8 @@ import { UsageReporter } from "../runtime/usage-report.js";
 /**
  * The worker role's parts, driven by `KernelLifecycle` at fixed points of its start order and stop
  * phases (so they stay ordered after the extension load and before the extension host closes): the
- * queue consumers (runs, sub-agent runs, evals, maintenance, channel deliveries, `usage.report`,
- * titles) and the schedulers of the `@LockedCron` / `@LockedInterval` jobs. Provided only by
+ * queue consumers (runs, sub-agent runs, evals, maintenance, the plugin scope sync, channel
+ * deliveries, `usage.report`, titles) and the schedulers of the `@LockedCron` / `@LockedInterval` jobs. Provided only by
  * `WorkerModule`, so a process without the worker role has none of them.
  */
 export declare class WorkerRole {
@@ -34,13 +35,14 @@ export declare class WorkerRole {
     private readonly channelsProcessor;
     private readonly evalsProcessor;
     private readonly maintenanceProcessor;
+    private readonly scopeProcessor;
     /** The startup config (the roles). */
     private readonly config;
     /** The run worker was started: the runs phase drains it. */
     private runsStarted;
     /** The eval worker was started: the runs phase drains it. */
     private evalsStarted;
-    constructor(config: KernelConfigService, log: KernelLogger, intervals: LockedIntervalScheduler, scheduledRuns: ScheduledRuns, runWorker: RunWorker, evalWorker: EvalWorker, usageReport: UsageReporter, titles: TitleQueue, channelOutbound: ChannelOutbound, runsProcessor: RunsProcessor, subagentRunsProcessor: SubagentRunsProcessor, usageProcessor: UsageReportProcessor, titleProcessor: TitleProcessor, channelsProcessor: ChannelsProcessor, evalsProcessor: EvalsProcessor, maintenanceProcessor: MaintenanceProcessor);
+    constructor(config: KernelConfigService, log: KernelLogger, intervals: LockedIntervalScheduler, scheduledRuns: ScheduledRuns, runWorker: RunWorker, evalWorker: EvalWorker, usageReport: UsageReporter, titles: TitleQueue, channelOutbound: ChannelOutbound, runsProcessor: RunsProcessor, subagentRunsProcessor: SubagentRunsProcessor, usageProcessor: UsageReportProcessor, titleProcessor: TitleProcessor, channelsProcessor: ChannelsProcessor, evalsProcessor: EvalsProcessor, maintenanceProcessor: MaintenanceProcessor, scopeProcessor: PluginScopeSyncProcessor);
     /**
      * Starts the queue consumers (after the extension load), then opens the schedules' start gate:
      * the cron and interval timers were armed at application bootstrap, but every tick before this
@@ -58,6 +60,6 @@ export declare class WorkerRole {
     drainRuns(budgetMs: number): Promise<void> | undefined;
     /** The eval cases in progress stop (undefined: never started). */
     drainEvals(budgetMs: number): Promise<void> | undefined;
-    /** Closes the maintenance queue's worker. */
+    /** Closes the maintenance queue's worker and the plugin scope sync's (it stops between pairs). */
     closeMaintenance(): Promise<void>;
 }