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

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

@@ -10,6 +10,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable } from "@nestjs/common";
 import { z } from "zod";
 import { AgentsService } from "../../agents/agents.service.js";
+import { AccountsService } from "../../identity/accounts.js";
+import { PreferencesSchema } from "../../identity/me.schemas.js";
 import { can } from "../../orgs/roles.js";
 import { effectiveSandboxEgress, OrgSettingsService } from "../../orgs/settings.service.js";
 import { SANDBOX_TOOL_NAMES } from "../../tools/builtin-names.js";
@@ -34,19 +36,24 @@ const FAMILIES = [
     "Plugin and connector tools, named plugin__<plugin>__<tool> and mcp__<connector>__<tool>.",
 ];
 const EMPTY = z.object({}).strict();
-/** The `platform` domain: orientation, and what this agent is (spec §7). Synthetic, no route. */
+/**
+ * The `platform` domain: orientation and what this agent is (spec §7, synthetic), and the
+ * person's own preferences (`/me/preferences`).
+ */
 let PlatformOperationsProvider = class PlatformOperationsProvider {
     registry;
     actor;
     agents;
     settings;
     tools;
-    constructor(registry, actor, agents, settings, tools) {
+    accounts;
+    constructor(registry, actor, agents, settings, tools, accounts) {
         this.registry = registry;
         this.actor = actor;
         this.agents = agents;
         this.settings = settings;
         this.tools = tools;
+        this.accounts = accounts;
     }
     /**
      * The agent's tools by the keys the model sees, as the registry resolves them for a run (tools
@@ -143,6 +150,45 @@ let PlatformOperationsProvider = class PlatformOperationsProvider {
                     };
                 },
             }),
+            defineOperation({
+                id: "platform.preferences",
+                description: "Read your own preferences: your time zone (an IANA name such as Asia/Shanghai), or null when it follows the time zone of the browser you send messages from. The run context already tells you the zone in effect for this message.",
+                input: EMPTY,
+                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/me/preferences"],
+                confirm: "read",
+                run: async (_input, ctx) => this.accounts.preferences(ctx.actorAccountId),
+            }),
+            defineOperation({
+                id: "platform.set-preferences",
+                description: "Set your own time zone (an IANA name such as Europe/Berlin), or null to follow the time zone of the browser you send messages from. It applies to the messages you send afterwards, on the web and in IM; the current run keeps its zone.",
+                input: PreferencesSchema,
+                example: { timeZone: "Asia/Shanghai" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["PUT /api/v1/me/preferences"],
+                confirm: "personal",
+                errors: [
+                    {
+                        code: "validation_failed",
+                        next: "Use an IANA time zone name such as Asia/Shanghai or America/New_York, or null.",
+                    },
+                ],
+                summary: async (input, ctx) => {
+                    const now = (await this.accounts.preferences(ctx.actorAccountId)).timeZone;
+                    const from = { zh: now ?? "跟随浏览器", en: now ?? "follow the browser" };
+                    const to = {
+                        zh: input.timeZone ?? "跟随浏览器",
+                        en: input.timeZone ?? "follow the browser",
+                    };
+                    return {
+                        zh: `把你的时区从「${from.zh}」改为「${to.zh}」`,
+                        en: `Change your time zone from "${from.en}" to "${to.en}"`,
+                    };
+                },
+                run: async (input, ctx) => this.accounts.setPreferences(ctx.actorAccountId, { timeZone: input.timeZone }),
+            }),
         ]);
     }
 };
@@ -152,6 +198,7 @@ PlatformOperationsProvider = __decorate([
     __param(1, Inject(PlatformActor)),
     __param(2, Inject(AgentsService)),
     __param(3, Inject(OrgSettingsService)),
-    __param(4, Inject(ToolRegistry))
+    __param(4, Inject(ToolRegistry)),
+    __param(5, Inject(AccountsService))
 ], PlatformOperationsProvider);
 export { PlatformOperationsProvider };

package/dist/platform/route-schemas.js

@@ -15,6 +15,7 @@ import { ENVIRONMENT_ROUTES } from "../environments/environments.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";
@@ -57,4 +58,6 @@ export const ROUTE_SCHEMAS = [
     ...FILE_PREVIEWER_ROUTES,
     // Task 11b: environments
     ...ENVIRONMENT_ROUTES,
+    // personal preferences (run context spec §3.4)
+    ...ME_ROUTES,
 ];

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

package/dist/runtime/context/build.js

@@ -4,6 +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 { 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";
@@ -336,6 +337,8 @@ 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
+ *   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
@@ -547,6 +550,12 @@ export function buildModelRequest(input) {
                 content: runContextFullText(currentRunContext(events, after)),
             });
         }
+        // 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);
+        if (paths) {
+            messages.push({ role: "system", content: environmentPathsText(paths.payload.roots) });
+        }
         // 被摘要覆盖的变更提醒不再发送：摘要时生效的目录与 system 里的不同 → 紧随摘要补上完整的当前目录
         const covered = skillSnaps.filter((e) => e.seq <= after).at(-1);
         // (phase B: plus the current pinned skills and tool-name map when they differ from system's)
@@ -620,6 +629,11 @@ export function buildModelRequest(input) {
             case "run_context":
                 messages.push({ role: "system", content: runContextText(events, e) });
                 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) });
+                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
             case "hook_denied":

package/dist/runtime/context/compaction.js

@@ -134,6 +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)
         // 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":

package/dist/runtime/context/environment-paths.d.ts

@@ -0,0 +1,40 @@
+import type { SandboxRoots } from "@capybara-hq/plugin-sdk";
+import type { ConversationEvent } from "../../conversations/events.js";
+/**
+ * The `environment_paths` event (environments spec §13.1, ruling R22): the first sandbox tool call
+ * of every conversation records the instance's roots (the defaults included), and a later call
+ * records them again whenever they differ from the conversation's latest recorded ones (a
+ * connected machine's real paths, a mode switch back to the defaults). Model-visible: rendered at
+ * its position as a system message; in the log, so it needs no `DriftReason`.
+ */
+/** The system line of an `environment_paths` event (model-visible, English). */
+export declare function environmentPathsText(r: SandboxRoots): string;
+/** Whether two sets of roots are the same paths. */
+export declare const sameRoots: (a: SandboxRoots, b: SandboxRoots) => boolean;
+/**
+ * The idempotency key of an `environment_paths` event for `r` that follows the conversation's
+ * event at `prevSeq` (0: none). Unique per change (A → B → A gets three events), while parallel
+ * calls that saw the same latest event write it once.
+ */
+export declare const environmentPathsIdemKey: (r: SandboxRoots, prevSeq: number) => string;
+/**
+ * The `environment_paths` event to append when a sandbox call holds an instance with `roots` and
+ * the conversation's latest such event is `latest`; null when nothing changed.
+ */
+export declare function environmentPathsChange(latest: {
+    seq: number;
+    payload: {
+        roots: SandboxRoots;
+    };
+} | undefined, roots: SandboxRoots, runId: string | undefined): {
+    type: "environment_paths";
+    runId?: string;
+    idemKey: string;
+    payload: {
+        roots: SandboxRoots;
+    };
+} | null;
+/** The latest `environment_paths` event at or before `seq`; undefined without one. */
+export declare function environmentPathsAt(events: readonly ConversationEvent[], seq: number): Extract<ConversationEvent, {
+    type: "environment_paths";
+}> | undefined;

package/dist/runtime/context/environment-paths.js

@@ -0,0 +1,48 @@
+import { createHash } from "node:crypto";
+/**
+ * The `environment_paths` event (environments spec §13.1, ruling R22): the first sandbox tool call
+ * of every conversation records the instance's roots (the defaults included), and a later call
+ * records them again whenever they differ from the conversation's latest recorded ones (a
+ * connected machine's real paths, a mode switch back to the defaults). Model-visible: rendered at
+ * its position as a system message; in the log, so it needs no `DriftReason`.
+ */
+/** The system line of an `environment_paths` event (model-visible, English). */
+export function environmentPathsText(r) {
+    return `This environment's directories: workspace ${r.workspace}, skills ${r.skills} (read only), temporary files ${r.tmp}. Use these paths in commands and tool calls.`;
+}
+/** Whether two sets of roots are the same paths. */
+export const sameRoots = (a, b) => a.workspace === b.workspace && a.skills === b.skills && a.tmp === b.tmp;
+/**
+ * The idempotency key of an `environment_paths` event for `r` that follows the conversation's
+ * event at `prevSeq` (0: none). Unique per change (A → B → A gets three events), while parallel
+ * calls that saw the same latest event write it once.
+ */
+export const environmentPathsIdemKey = (r, prevSeq) => `environment_paths:${createHash("sha256")
+    .update(JSON.stringify([r.workspace, r.skills, r.tmp]))
+    .digest("hex")
+    .slice(0, 16)}:${prevSeq}`;
+/**
+ * The `environment_paths` event to append when a sandbox call holds an instance with `roots` and
+ * the conversation's latest such event is `latest`; null when nothing changed.
+ */
+export function environmentPathsChange(latest, roots, runId) {
+    if (latest && sameRoots(latest.payload.roots, roots))
+        return null;
+    return {
+        type: "environment_paths",
+        ...(runId !== undefined && { runId }),
+        idemKey: environmentPathsIdemKey(roots, latest?.seq ?? 0),
+        payload: { roots: { workspace: roots.workspace, skills: roots.skills, tmp: roots.tmp } },
+    };
+}
+/** The latest `environment_paths` event at or before `seq`; undefined without one. */
+export function environmentPathsAt(events, seq) {
+    let found;
+    for (const e of events) {
+        if (e.seq > seq)
+            break;
+        if (e.type === "environment_paths")
+            found = e;
+    }
+    return found;
+}

package/dist/runtime/model-call.js

@@ -163,6 +163,8 @@ wrapUpReason) {
             subagents: input.agent.subagents,
             child: input.parent !== undefined || input.parentRunId !== undefined || input.subagent === true,
             forkChild: input.parent?.forSkill === true,
+            sandboxConversationId: input.parent?.rootConversationId ?? input.conversationId,
+            replay: input.conversationKind === "eval",
             skillLoad: skillLoadOffered(events.findLast((e) => e.type === "skills_catalog"), hasInvocation(events)),
         });
         const tools = {

package/dist/sandbox/providers.d.ts

@@ -1,19 +1,41 @@
 import { type SandboxProvider } from "@capybara-hq/plugin-sdk";
 import { ExtensionRegistry } from "../extensions/registry.js";
-/** 当前的 `sandbox@2` 提供方：插件名与实现。 */
+/** The kernel-internal provider of connected machines (`device` environments). */
+export declare const DEVICE_PROVIDER = "@device";
+/**
+ * A kernel-internal provider name: it starts with `@`, which no extension name can
+ * (`EXTENSION_NAME_RE`), so it never collides with a loaded `sandbox@2` plugin.
+ */
+export declare const isInternalProvider: (name: string) => boolean;
+/** A sandbox provider: its name (plugin name, or an internal `@…` name) and implementation. */
 export interface SandboxProviderEntry {
     plugin: string;
     impl: SandboxProvider;
 }
 /**
- * The `sandbox@2` providers of this process, read from the {@link ExtensionRegistry} at every
- * call: providers are ready only after the extension load, and change with installs.
+ * The sandbox providers of this process. The cloud provider is the loaded `sandbox@2` extension,
+ * read from the {@link ExtensionRegistry} at every call (providers are ready only after the
+ * extension load, and change with installs). Kernel-internal providers (`@device`) are registered
+ * by their module on init, in every replica: they are code, not shared state.
  */
 export declare class SandboxProviders {
     private readonly registry;
+    private readonly internal;
     constructor(registry: Pick<ExtensionRegistry, "list">);
-    /** The current provider; undefined without one. */
-    current(): SandboxProviderEntry | undefined;
-    /** A still-loaded provider by plugin name (to destroy an earlier provider's instance). */
-    lookup(plugin: string): SandboxProvider | undefined;
+    /** Registers a kernel-internal provider (an `@…` name); a later registration replaces it. */
+    register(entry: SandboxProviderEntry): void;
+    /** The cloud provider (the loaded `sandbox@2` extension); undefined without one. */
+    cloud(): SandboxProviderEntry | undefined;
+    /**
+     * A provider by name: a registered internal provider, else a still-loaded `sandbox@2` extension
+     * of that plugin name (to destroy an earlier provider's resources).
+     */
+    forName(name: string): SandboxProviderEntry | undefined;
 }
+/**
+ * The provider an environment works with, from its `environments.provider`: an internal one
+ * (`@device`) by that name only, never falling back to the cloud provider; any other environment
+ * is a cloud environment and uses the current cloud provider (files kept by another provider are
+ * refused by the sandbox service, `environment.unavailable`).
+ */
+export declare function providerForEnvironment(providers: Pick<SandboxProviders, "cloud" | "forName">, provider: string | null): SandboxProviderEntry | undefined;

package/dist/sandbox/providers.js

@@ -10,25 +10,49 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { SANDBOX_EXTENSION_POINT } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { ExtensionRegistry } from "../extensions/registry.js";
+/** The kernel-internal provider of connected machines (`device` environments). */
+export const DEVICE_PROVIDER = "@device";
 /**
- * The `sandbox@2` providers of this process, read from the {@link ExtensionRegistry} at every
- * call: providers are ready only after the extension load, and change with installs.
+ * A kernel-internal provider name: it starts with `@`, which no extension name can
+ * (`EXTENSION_NAME_RE`), so it never collides with a loaded `sandbox@2` plugin.
+ */
+export const isInternalProvider = (name) => name.startsWith("@");
+/**
+ * The sandbox providers of this process. The cloud provider is the loaded `sandbox@2` extension,
+ * read from the {@link ExtensionRegistry} at every call (providers are ready only after the
+ * extension load, and change with installs). Kernel-internal providers (`@device`) are registered
+ * by their module on init, in every replica: they are code, not shared state.
  */
 let SandboxProviders = class SandboxProviders {
     registry;
+    internal = new Map();
     constructor(registry) {
         this.registry = registry;
     }
-    /** The current provider; undefined without one. */
-    current() {
+    /** Registers a kernel-internal provider (an `@…` name); a later registration replaces it. */
+    register(entry) {
+        if (!isInternalProvider(entry.plugin)) {
+            throw new Error(`an internal sandbox provider name starts with @: ${entry.plugin}`);
+        }
+        this.internal.set(entry.plugin, entry);
+    }
+    /** The cloud provider (the loaded `sandbox@2` extension); undefined without one. */
+    cloud() {
         const e = this.registry.list("sandbox").find((x) => x.capability === SANDBOX_EXTENSION_POINT);
         return e ? { plugin: e.plugin, impl: e.impl } : undefined;
     }
-    /** A still-loaded provider by plugin name (to destroy an earlier provider's instance). */
-    lookup(plugin) {
-        return this.registry
+    /**
+     * A provider by name: a registered internal provider, else a still-loaded `sandbox@2` extension
+     * of that plugin name (to destroy an earlier provider's resources).
+     */
+    forName(name) {
+        const own = this.internal.get(name);
+        if (own)
+            return own;
+        const e = this.registry
             .list("sandbox")
-            .find((x) => x.capability === SANDBOX_EXTENSION_POINT && x.plugin === plugin)?.impl;
+            .find((x) => x.capability === SANDBOX_EXTENSION_POINT && x.plugin === name);
+        return e ? { plugin: e.plugin, impl: e.impl } : undefined;
     }
 };
 SandboxProviders = __decorate([
@@ -36,3 +60,14 @@ SandboxProviders = __decorate([
     __param(0, Inject(ExtensionRegistry))
 ], SandboxProviders);
 export { SandboxProviders };
+/**
+ * The provider an environment works with, from its `environments.provider`: an internal one
+ * (`@device`) by that name only, never falling back to the cloud provider; any other environment
+ * is a cloud environment and uses the current cloud provider (files kept by another provider are
+ * refused by the sandbox service, `environment.unavailable`).
+ */
+export function providerForEnvironment(providers, provider) {
+    if (provider !== null && isInternalProvider(provider))
+        return providers.forName(provider);
+    return providers.cloud();
+}