@zhin.js/adapter-sandbox 1.0.69 → 1.1.0

package/README.md

@@ -1,10 +1,10 @@
 # @zhin.js/adapter-sandbox
 
-Zhin.js Sandbox 适配器，基于 WebSocket 的本地测试适配器，配合 Web 控制台提供浏览器端聊天窗口进行调试。
+Zhin.js Sandbox 适配器，基于 WebSocket 的本地测试适配器；浏览器端聊天 UI 在 **[Remote Console](https://console.zhin.dev)**（Host 仅 Console API）中打开 Sandbox 窗口调试。
 
 ## 功能特性
 
-- 基于 WebSocket 实时通信
+- **Node Host**：WebSocket `/sandbox`
 - 浏览器端 React 聊天 UI
 - 支持多客户端同时连接
 - 无需第三方平台账号，即开即用
@@ -16,55 +16,65 @@ Zhin.js Sandbox 适配器，基于 WebSocket 的本地测试适配器，配合 W
 pnpm add @zhin.js/adapter-sandbox
 ```
 
+## 前置条件
+
+Sandbox 不需要外部账号。只需由 `zhin runtime start` 装配 HTTP Host，并确保浏览器能访问启动日志中的 Host 地址。
+
 ## 依赖
 
-Sandbox 适配器需要以下服务插件：
+### Plugin Runtime（新，`zhin runtime start`）
+
+- `@zhin.js/adapter` — 约定式 `adapters/sandbox.ts`
+- `@zhin.js/host-http` — Root 提供的 `httpHostToken`（WebSocket `/sandbox` + Console HTTP）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/page` + `pages/index.tsx` — ADR 0046 约定页（`definePage`；路由 `/sandbox`）
+
+Root 在 `zhin runtime start` 时装载 `@zhin.js/host-http`、`ConsoleRuntime` 与
+`ClientBuildModuleRuntime`。打开 `http://<host>:<port>/console` 可浏览页面；Sandbox 页
+（路由 `/sandbox`，与 WebSocket `/sandbox` 同 path：GET 开页、Upgrade 走 WS）内置聊天壳。
+
+旧 `client/`（`register(api)` / `pageManager.addEntry`）仅保留给 legacy Host 栈参考，
+**不是** Plugin Runtime 生产入口。
 
-- `@zhin.js/http` — HTTP 服务（提供 Router 和 WebSocket）
-- `@zhin.js/console` — Web 控制台（提供前端 UI）
-- `@zhin.js/client` — 控制台客户端框架
+### 旧 Host 栈（已删除）
+
+原 legacy 插件包 `@zhin.js/host-router`（HTTP 服务）与 `@zhin.js/host-api`（Host 侧 Console API，`addEntry` 注册 Sandbox 扩展）已删除；`zhin dev` 现由 `@zhin.js/cli` 自动装配 Console/HTTP Host（`@zhin.js/host-http` + `@zhin.js/pagemanager`），无需安装任何 Host 插件。
+
+- `@zhin.js/client` — Remote Console 客户端 SDK（UI 在 zhin-console 仓库）
+
+出站 wire 只做 JSON 封装；旧 `segment-mapper`（canonical segments）归一化上移到 gateway/core 渲染链。
 
 ## 配置
 
-```yaml
-# zhin.config.yml
-bots:
-  - context: sandbox
-    name: sandbox-bot
+**推荐（与 [minimal-bot](../../../examples/minimal-bot/) 一致）**：`plugins.sandbox.endpoints: []`，在 Remote Console 打开「沙盒」页时经 `/sandbox` WebSocket **自动创建** bot（如 `sandbox-xxxx`），无需在 yaml 里写 `context: sandbox`。
 
+```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - adapter-sandbox
-  - http
-  - console
+  sandbox:
+    endpoints: []
 ```
 
-或使用 TypeScript 配置：
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  bots: [
-    {
-      context: 'sandbox',
-      name: 'sandbox-bot',
-    }
-  ],
-  plugins: [
-    'adapter-sandbox',
-    'http',
-    'console',
-  ]
-})
+可选：若需在启动时即在 bot 列表显示**固定名称**的离线占位 bot，可显式配置：
+
+```yaml
+plugins:
+  sandbox:
+    endpoints:
+      - name: sandbox-bot
+        context: sandbox
+        owner: sandbox-user
 ```
 
 ## 使用方式
 
-1. 启动机器人：`pnpm dev`
-2. 打开浏览器访问 Web 控制台（默认 `http://localhost:8086`）
-3. 在控制台的 Sandbox 聊天窗口中发送消息进行测试
+1. 启动 Zhin 实例：`pnpm dev`（终端会打印 Host 地址，一般为 `http://127.0.0.1:8086`）
+2. 打开 **[Remote Console](https://console.zhin.dev)**，API Base 与 Host 地址一致，Token 与 `http.token` / `HTTP_TOKEN` 一致
+3. 在 Console **沙盒** 页连接后发送消息进行测试
 
-每个浏览器客户端通过 WebSocket 连接后会自动创建一个 Sandbox Bot 实例，消息通过 JSON 格式在 WebSocket 上传输。
+每个浏览器客户端连接后创建 Sandbox Bot（无 yaml 固定名时为 `sandbox-xxxx`）。
+
+通过 `Router.ws("/sandbox")`（插件 `useContext("router")` 自动挂载）建立连接。
 
 ## 消息格式
 
@@ -85,6 +95,20 @@ Sandbox 使用 JSON 消息格式：
 - 测试命令和 AI 工具调用
 - 不依赖外部平台的功能验证
 
+## AI 工具
+
+技能说明见 `agent/skills/sandbox.md`（本地沙箱调试约束）。
+
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| Console 无法连接 | 以启动日志中的 Host、端口和 token 为准 |
+| Sandbox 页面空白 | 检查 HTTP Host 是否因端口占用软降级，以及鉴权/CORS 错误 |
+| 刷新后没有历史消息 | 核对 Endpoint 与频道，并检查 history RPC 与 recovery gap 日志 |
+| 命令或工具未生效 | 在运行时能力页确认它已进入当前 generation |
+
 ## 许可证
 
 MIT License

package/adapters/sandbox.js

@@ -0,0 +1,25 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/sandbox.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { SandboxWsEndpoint } from "../lib/endpoint.js";
+import { resolveSandboxEndpoint, } from "../lib/protocol.js";
+export { SandboxWsEndpoint } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // Console UI 直连 URL 媒体、直接渲染 base64 内联媒体；path 由端点读盘
+    // 物化为 base64 内联（sandbox 无平台上传通道）。交互段由 Console 原生承载。
+    segments: {
+        outboundMedia: ['url', 'base64', 'path'],
+        interactive: 'native',
+    },
+    create(context) {
+        return new SandboxWsEndpoint({
+            id: context.id,
+            http: context.use(httpHostToken),
+            defaults: resolveSandboxEndpoint(context.config),
+        });
+    },
+});

package/adapters/sandbox.ts

@@ -0,0 +1,30 @@
+/**
+ * Convention entry: discover `adapters/sandbox.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { SandboxWsEndpoint } from '../src/endpoint.js';
+import {
+  resolveSandboxEndpoint,
+  type SandboxAdapterConfig,
+} from '../src/protocol.js';
+
+export { SandboxWsEndpoint } from '../src/endpoint.js';
+export type { SandboxEndpointOptions } from '../src/endpoint.js';
+
+export default defineAdapter<SandboxAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  // Console UI 直连 URL 媒体、直接渲染 base64 内联媒体；path 由端点读盘
+  // 物化为 base64 内联（sandbox 无平台上传通道）。交互段由 Console 原生承载。
+  segments: {
+    outboundMedia: ['url', 'base64', 'path'],
+    interactive: 'native',
+  },
+  create(context) {
+    return new SandboxWsEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      defaults: resolveSandboxEndpoint(context.config),
+    });
+  },
+});

package/agent/skills/sandbox.md

@@ -0,0 +1,33 @@
+---
+name: sandbox
+platforms:
+  - sandbox
+description: >-
+  沙箱测试适配器：基于 WebSocket 的本地测试环境，提供浏览器内聊天 UI，
+  无需第三方平台即可调试插件和命令。开发调试专用，无额外 AI 工具。
+keywords:
+  - sandbox
+  - adapter:sandbox
+  - test
+  - 测试
+  - 沙箱
+  - development
+  - 开发
+  - debug
+  - 调试
+tags:
+  - sandbox
+  - testing
+  - development
+tools: []
+---
+
+# 沙箱测试适配器
+
+本地开发调试专用。通过浏览器 Web UI 模拟聊天，无需第三方平台凭据。无 AI 工具可调用。
+
+## 使用场景
+
+- 开发新插件时在本地模拟消息收发
+- 调试命令路由和中间件逻辑
+- 依赖 HTTP 服务和 Console 插件提供 Web 界面

package/lib/client.d.ts

@@ -0,0 +1,27 @@
+import type { SandboxWsSocket } from './protocol.js';
+export interface SandboxClientConnection {
+    readonly target: string;
+    readonly owner: string;
+    readonly socket: SandboxWsSocket;
+    readonly placeholder: boolean;
+}
+/** Direct view of the live Sandbox protocol clients owned by one Endpoint. */
+export declare class SandboxClient {
+    private readonly resolvePath;
+    private readonly resolveConnections;
+    constructor(resolvePath: () => string, resolveConnections: () => Iterable<SandboxClientConnection>);
+    get path(): string;
+    connections(): readonly SandboxClientConnection[];
+    connection(target: string): SandboxClientConnection | undefined;
+    send(target: string, payload: string): void;
+}
+export type SandboxClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly sandbox: {
+            readonly client: SandboxClient;
+            readonly events: SandboxClientEventMap;
+        };
+    }
+}
+export declare const sandboxClient: import("@zhin.js/adapter").EndpointClientToken<SandboxClient, SandboxClientEventMap>;

package/lib/client.js

@@ -0,0 +1,27 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Direct view of the live Sandbox protocol clients owned by one Endpoint. */
+export class SandboxClient {
+    resolvePath;
+    resolveConnections;
+    constructor(resolvePath, resolveConnections) {
+        this.resolvePath = resolvePath;
+        this.resolveConnections = resolveConnections;
+    }
+    get path() {
+        return this.resolvePath();
+    }
+    connections() {
+        return Object.freeze([...this.resolveConnections()]);
+    }
+    connection(target) {
+        return this.connections().find((connection) => connection.target === target);
+    }
+    send(target, payload) {
+        const connection = this.connection(target);
+        if (!connection || connection.placeholder) {
+            throw new Error(`Sandbox client ${target} is not connected`);
+        }
+        connection.socket.send(payload);
+    }
+}
+export const sandboxClient = defineEndpointClient('sandbox');

package/lib/endpoint.d.ts

@@ -0,0 +1,42 @@
+import { Endpoint } from 'zhin.js/adapter';
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type ResolvedSandboxBot } from './protocol.js';
+import { SandboxClient } from './client.js';
+type ShellIsolationStatus = Readonly<{
+    available: boolean;
+    provider: 'docker';
+    message: string;
+}>;
+type ShellIsolationProbe = () => Promise<ShellIsolationStatus>;
+/**
+ * Share an in-flight readiness probe across reconnects while still allowing a
+ * later connection to refresh the informational status after it settles.
+ * Kept internal to this module's package surface; tests import it directly.
+ */
+export declare function createSandboxReadinessGate(probe: ShellIsolationProbe): Readonly<{
+    afterProbe: (deliver: (status: ShellIsolationStatus) => void) => void;
+}>;
+export interface SandboxEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly defaults: ResolvedSandboxBot;
+}
+/**
+ * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export declare class SandboxWsEndpoint extends Endpoint<SandboxClient> {
+    #private;
+    readonly client: SandboxClient;
+    constructor(options: SandboxEndpointOptions);
+    /** Live endpoint id (config `id`) — Console endpoint.list/resolve uses it. */
+    get name(): string;
+    start(): void;
+    open(): void;
+    close(): void;
+    stop(): void;
+    send({ conversation, payload }: EndpointSendRequest): string;
+}
+export {};

package/lib/endpoint.js

@@ -0,0 +1,357 @@
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * SandboxWsEndpoint — WebSocket lifecycle and OutboundMessageService bridge for /sandbox.
+ */
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { bindSandboxWsSocket, formatSandboxOutbound, parseSandboxWsPayload, sandboxInboundConversation, whenWsOpen, } from './protocol.js';
+import { SandboxClient } from './client.js';
+const claimedWsPaths = new WeakMap();
+function claimSandboxWsPath(http, name) {
+    let claims = claimedWsPaths.get(http);
+    if (!claims) {
+        claims = new Map();
+        claimedWsPaths.set(http, claims);
+    }
+    const candidates = ['/sandbox', `/sandbox/${encodeURIComponent(name)}`];
+    let path = candidates.find((candidate) => !claims.has(candidate) || claims.get(candidate)?.name === name);
+    if (!path) {
+        let index = 2;
+        path = `/sandbox/${encodeURIComponent(name)}-${index}`;
+        while (claims.has(path)) {
+            index += 1;
+            path = `/sandbox/${encodeURIComponent(name)}-${index}`;
+        }
+    }
+    const owner = Symbol(name);
+    const claim = claims.get(path) ?? { name, owners: new Set() };
+    claim.owners.add(owner);
+    claims.set(path, claim);
+    const claimed = path;
+    const registry = claims;
+    return {
+        path: claimed,
+        release: () => {
+            claim.owners.delete(owner);
+            if (claim.owners.size === 0 && registry.get(claimed) === claim) {
+                registry.delete(claimed);
+            }
+        },
+    };
+}
+/**
+ * Share an in-flight readiness probe across reconnects while still allowing a
+ * later connection to refresh the informational status after it settles.
+ * Kept internal to this module's package surface; tests import it directly.
+ */
+export function createSandboxReadinessGate(probe) {
+    let inFlight;
+    const acquire = () => {
+        if (inFlight)
+            return inFlight;
+        const pending = probe();
+        const shared = pending.finally(() => {
+            if (inFlight === shared)
+                inFlight = undefined;
+        });
+        inFlight = shared;
+        return shared;
+    };
+    return Object.freeze({
+        afterProbe: (deliver) => {
+            void acquire().then(deliver);
+        },
+    });
+}
+/**
+ * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class SandboxWsEndpoint extends Endpoint {
+    client;
+    #logger;
+    #options;
+    #connections = new Map();
+    #readiness = createSandboxReadinessGate(probeShellIsolation);
+    #wsHandleRelease;
+    #wsPathRelease;
+    #wsPath = '/sandbox';
+    #open = false;
+    #started = false;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('sandbox', options.defaults.id);
+        this.#options = options;
+        this.client = new SandboxClient(() => this.#wsPath, () => [...this.#connections.values()].map((connection) => ({
+            target: connection.target,
+            owner: connection.owner,
+            socket: connection.socket,
+            placeholder: connection.placeholder === true,
+        })));
+    }
+    /** Live endpoint id (config `id`) — Console endpoint.list/resolve uses it. */
+    get name() {
+        return this.#options.defaults.id;
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        // 多 endpoint 同 path 会被全部回调（入站重复、出站互窜），按名隔离。
+        const claim = claimSandboxWsPath(this.#options.http, this.#options.defaults.id);
+        this.#wsPathRelease = claim.release;
+        this.#wsPath = claim.path;
+        const handle = this.#options.http.ws(claim.path);
+        this.#wsHandleRelease = handle.onConnection((connection) => {
+            this.#acceptConnection(connection);
+        });
+        if (!this.#options.defaults.randomNamePerConnection) {
+            this.#ensurePlaceholder(this.#options.defaults.id, this.#options.defaults.owner);
+        }
+        this.#logger.info(`ws mounted ${claim.path}`);
+    }
+    open() {
+        this.#open = true;
+    }
+    close() {
+        this.#open = false;
+    }
+    stop() {
+        this.#open = false;
+        this.#wsHandleRelease?.();
+        this.#wsHandleRelease = undefined;
+        this.#wsPathRelease?.();
+        this.#wsPathRelease = undefined;
+        for (const connection of this.#connections.values()) {
+            connection.release();
+            if (!connection.placeholder) {
+                try {
+                    connection.socket.close(1001, 'sandbox endpoint stopped');
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+        }
+        this.#connections.clear();
+        this.#started = false;
+        this.#logger.debug(formatCompact({ op: 'sandbox_stopped' }));
+    }
+    send({ conversation, payload }) {
+        if (!this.#open)
+            throw new Error('Sandbox Endpoint is not open');
+        // Reply targets this endpoint's own live socket (fixed bot name, or the
+        // only live random-name connection); conversation carries kind/id stamp.
+        const connection = this.#connections.get(this.#options.defaults.id)
+            ?? this.#findLiveConnection();
+        if (!connection) {
+            this.#logger.debug(formatCompact({
+                op: 'sandbox_send_miss',
+                target: `${conversation.kind}:${conversation.id}`,
+            }));
+            throw new Error('Sandbox Endpoint has no live connection');
+        }
+        if (connection.placeholder) {
+            this.#logger.debug(formatCompact({
+                op: 'sandbox_send_placeholder',
+                target: `${conversation.kind}:${conversation.id}`,
+            }));
+            throw new Error('Sandbox Endpoint has no live connection');
+        }
+        // Console UI filters by type+id; stamp the conversation onto outbound wire.
+        connection.socket.send(formatSandboxOutbound(payload, {
+            type: conversation.kind,
+            id: conversation.id,
+            bot: this.#options.defaults.id,
+            endpoint: connection.target,
+        }));
+        this.#logger.debug(formatCompact({
+            op: 'sandbox_send',
+            target: connection.target,
+            channelType: conversation.kind,
+            channelId: conversation.id,
+        }));
+        return randomUUID();
+    }
+    /** Prefer a real (non-placeholder) socket when reply target key is wrong/stale. */
+    #findLiveConnection() {
+        for (const connection of this.#connections.values()) {
+            if (!connection.placeholder)
+                return connection;
+        }
+        return undefined;
+    }
+    #acceptConnection(connection) {
+        const target = this.#options.defaults.randomNamePerConnection
+            ? `sandbox-${randomUUID().slice(0, 8)}`
+            : this.#options.defaults.id;
+        const owner = this.#options.defaults.owner;
+        const canExecute = connection.authScope === 'full';
+        const socket = connection.socket;
+        // Fixed-name mode reuses `target`; dropping the prior entry without
+        // closing its socket leaves a zombie browser tab that still looks
+        // connected but never receives outbound traffic.
+        const previous = this.#connections.get(target);
+        if (previous) {
+            previous.release();
+            if (!previous.placeholder) {
+                try {
+                    previous.socket.close(4000, 'replaced by new sandbox client');
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+            this.#connections.delete(target);
+        }
+        const release = bindSandboxWsSocket(socket, {
+            onMessage: (raw) => {
+                void this.#emitPlatformEvent('message', raw);
+                if (!canExecute) {
+                    socket.send(JSON.stringify({
+                        type: 'error',
+                        id: owner,
+                        endpoint: target,
+                        content: [{ type: 'text', data: { text: '当前连接是只读演示权限，不能运行 Agent 任务。' } }],
+                        timestamp: Date.now(),
+                    }));
+                    return;
+                }
+                const parsed = parseSandboxWsPayload(raw);
+                const sceneId = parsed.id || owner;
+                const conversation = sandboxInboundConversation(String(this.#options.id), {
+                    type: parsed.type,
+                    id: sceneId,
+                });
+                this.#logger.debug(formatCompact({
+                    op: 'sandbox_recv',
+                    target,
+                    sender: owner,
+                    channelType: parsed.type,
+                    channelId: sceneId,
+                    text: parsed.text.slice(0, 80),
+                }));
+                // Don't gate on #open — inbound must always reach the gateway so
+                // Command/AI dispatch and outbound replies work.
+                void this.emit('message.receive', {
+                    conversation,
+                    ...(parsed.messageId ? { message: { conversation, id: parsed.messageId } } : {}),
+                    content: parsed.text,
+                    sender: { id: owner },
+                    endpointId: target,
+                    metadata: Object.freeze({
+                        type: parsed.type,
+                        channelType: parsed.type,
+                        channelId: parsed.id || owner,
+                        elements: parsed.content,
+                        timestamp: parsed.timestamp,
+                        ...(parsed.action ? { action: parsed.action } : {}),
+                        ...(parsed.agentRun ? { sandboxAgentRun: parsed.agentRun } : {}),
+                    }),
+                }).catch((err) => {
+                    this.#logger.warn(formatCompact({
+                        op: 'sandbox_gateway_receive_failed',
+                        target,
+                        error: err instanceof Error ? err.message : String(err),
+                    }));
+                });
+            },
+            onClose: () => {
+                void this.#emitPlatformEvent('connection.close', { target, owner });
+                // Only drop the map entry if we still own this socket — a replace
+                // may have already swapped in a newer connection for the same target.
+                const current = this.#connections.get(target);
+                if (current && current.socket === socket) {
+                    this.#connections.delete(target);
+                    this.#logger.debug(formatCompact({ op: 'sandbox_ws_closed', target }));
+                }
+            },
+            onError: (err) => {
+                void this.#emitPlatformEvent('connection.error', { target, owner, error: err });
+                this.#logger.warn(formatCompact({
+                    op: 'sandbox_ws_error',
+                    target,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
+            },
+        });
+        this.#connections.set(target, { target, owner, socket, release });
+        void this.#emitPlatformEvent('connection.open', { target, owner, socket });
+        this.#logger.debug(formatCompact({ op: 'sandbox_ws_connected', target, owner }));
+        this.#readiness.afterProbe((shellIsolation) => {
+            const current = this.#connections.get(target);
+            if (!current || current.socket !== socket)
+                return;
+            const readyPayload = JSON.stringify({
+                type: 'ready',
+                id: owner,
+                endpoint: target,
+                workingDirectory: process.cwd(),
+                canExecute,
+                shellIsolation,
+                content: [{
+                        type: 'text',
+                        data: {
+                            text: [
+                                `已连接 Sandbox「${target}」`,
+                                `与 Node Host 控制台沙盒协议一致（${this.#wsPath}）`,
+                                'Agent 试验台会话已启用持久化运行配置。',
+                            ].join('\n'),
+                        },
+                    }],
+                timestamp: Date.now(),
+            });
+            whenWsOpen(socket, () => socket.send(readyPayload));
+        });
+    }
+    #ensurePlaceholder(name, owner) {
+        if (this.#connections.has(name))
+            return;
+        this.#connections.set(name, {
+            target: name,
+            owner,
+            socket: { send: () => undefined, close: () => undefined },
+            release: () => undefined,
+            placeholder: true,
+        });
+    }
+    async #emitPlatformEvent(name, event) {
+        await this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'sandbox_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+}
+function probeShellIsolation() {
+    return new Promise((resolve) => {
+        execFile('docker', ['info', '--format', '{{.ServerVersion}}'], {
+            encoding: 'utf8',
+            timeout: 500,
+        }, (error, stdout) => {
+            if (!error) {
+                const version = stdout.trim();
+                resolve(Object.freeze({
+                    available: true,
+                    provider: 'docker',
+                    message: version ? `Docker ${version}` : 'Docker ready',
+                }));
+                return;
+            }
+            resolve(Object.freeze({
+                available: false,
+                provider: 'docker',
+                message: error.killed || error.code === 'ETIMEDOUT'
+                    ? 'Docker readiness check timed out'
+                    : 'Docker daemon is unavailable',
+            }));
+        });
+    }).catch(() => Object.freeze({
+        available: false,
+        provider: 'docker',
+        message: 'Docker is unavailable',
+    }));
+}