@zhin.js/adapter-sandbox 8.0.0 → 8.0.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @zhin.js/adapter-process
 
+## 8.0.2
+
+### Patch Changes
+
+- Updated dependencies [a5ee497]
+- Updated dependencies [ba7e17a]
+- Updated dependencies [7108d0b]
+  - @zhin.js/host-http@1.0.14
+  - @zhin.js/core@1.5.15
+  - zhin.js@6.0.15
+
+## 8.0.1
+
+### Patch Changes
+
+- e9c6a73: Preserve WebSocket path ownership when a previous hot-reload generation stops after its replacement starts.
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [4e8117c]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+  - @zhin.js/page@1.0.13
+  - @zhin.js/client@2.1.12
+
 ## 8.0.0
 
 ### Patch Changes

package/README.md

@@ -16,13 +16,17 @@ Zhin.js Sandbox 适配器，基于 WebSocket 的本地测试适配器；浏览
 pnpm add @zhin.js/adapter-sandbox
 ```
 
+## 前置条件
+
+Sandbox 不需要外部账号。只需由 `zhin runtime start` 装配 HTTP Host，并确保浏览器能访问启动日志中的 Host 地址。
+
 ## 依赖
 
 ### Plugin Runtime（新，`zhin runtime start`）
 
 - `@zhin.js/adapter` — 约定式 `adapters/sandbox.ts`
 - `@zhin.js/host-http` — Root 提供的 `httpHostToken`（WebSocket `/sandbox` + Console HTTP）
-- `@zhin.js/core` — `messageGatewayToken` / ImRuntime 入站出站
+- `@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` 与
@@ -96,6 +100,15 @@ Sandbox 使用 JSON 消息格式：
 技能说明见 `agent/skills/sandbox.md`（本地沙箱调试约束）。
 
 
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| Console 无法连接 | 以启动日志中的 Host、端口和 token 为准 |
+| Sandbox 页面空白 | 检查 HTTP Host 是否因端口占用软降级，以及鉴权/CORS 错误 |
+| 刷新后没有历史消息 | 核对 Endpoint 与频道，并检查 history RPC 与 recovery gap 日志 |
+| 命令或工具未生效 | 在运行时能力页确认它已进入当前 generation |
+
 ## 许可证
 
 MIT License

package/adapters/sandbox.js

@@ -3,7 +3,6 @@
  * Convention entry: discover `adapters/sandbox.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { SandboxWsEndpoint } from "../lib/endpoint.js";
 import { resolveSandboxEndpoint, } from "../lib/protocol.js";
@@ -19,8 +18,6 @@ export default defineAdapter({
     create(context) {
         return new SandboxWsEndpoint({
             id: context.id,
-            gateway: context.use(messageGatewayToken),
-            sideEvents: context.use(sideEventGatewayToken),
             http: context.use(httpHostToken),
             defaults: resolveSandboxEndpoint(context.config),
         });

package/adapters/sandbox.ts

@@ -2,7 +2,6 @@
  * Convention entry: discover `adapters/sandbox.ts` → defineAdapter.
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { SandboxWsEndpoint } from '../src/endpoint.js';
 import {
@@ -24,8 +23,6 @@ export default defineAdapter<SandboxAdapterConfig>({
   create(context) {
     return new SandboxWsEndpoint({
       id: context.id,
-      gateway: context.use(messageGatewayToken),
-      sideEvents: context.use(sideEventGatewayToken),
       http: context.use(httpHostToken),
       defaults: resolveSandboxEndpoint(context.config),
     });

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

@@ -1,8 +1,9 @@
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+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';
@@ -19,8 +20,6 @@ export declare function createSandboxReadinessGate(probe: ShellIsolationProbe):
 }>;
 export interface SandboxEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly defaults: ResolvedSandboxBot;
 }
@@ -28,8 +27,9 @@ export interface SandboxEndpointOptions {
  * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export declare class SandboxWsEndpoint implements EndpointInstance {
+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;

package/lib/endpoint.js

@@ -1,16 +1,12 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway bridge for /sandbox.
+ * 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';
-/**
- * 多 sandbox endpoint 共用同一个 HttpHost 时，同 path 的所有 WS listener
- * 都会被回调（入站重复、出站互窜）。按 endpoint 名隔离挂载路径：
- * 首个占用 `/sandbox`（保持 Console 默认兼容），其余退到 `/sandbox/<name>`。
- * 认领记录按 HttpHost 隔离，endpoint stop() 时必须 release。
- */
+import { SandboxClient } from './client.js';
 const claimedWsPaths = new WeakMap();
 function claimSandboxWsPath(http, name) {
     let claims = claimedWsPaths.get(http);
@@ -19,7 +15,7 @@ function claimSandboxWsPath(http, name) {
         claimedWsPaths.set(http, claims);
     }
     const candidates = ['/sandbox', `/sandbox/${encodeURIComponent(name)}`];
-    let path = candidates.find((candidate) => !claims.has(candidate) || claims.get(candidate) === name);
+    let path = candidates.find((candidate) => !claims.has(candidate) || claims.get(candidate)?.name === name);
     if (!path) {
         let index = 2;
         path = `/sandbox/${encodeURIComponent(name)}-${index}`;
@@ -28,14 +24,19 @@ function claimSandboxWsPath(http, name) {
             path = `/sandbox/${encodeURIComponent(name)}-${index}`;
         }
     }
-    claims.set(path, name);
+    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: () => {
-            if (registry.get(claimed) === name)
+            claim.owners.delete(owner);
+            if (claim.owners.size === 0 && registry.get(claimed) === claim) {
                 registry.delete(claimed);
+            }
         },
     };
 }
@@ -67,7 +68,8 @@ export function createSandboxReadinessGate(probe) {
  * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export class SandboxWsEndpoint {
+export class SandboxWsEndpoint extends Endpoint {
+    client;
     #logger;
     #options;
     #connections = new Map();
@@ -78,8 +80,15 @@ export class SandboxWsEndpoint {
     #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() {
@@ -198,6 +207,7 @@ export class SandboxWsEndpoint {
         }
         const release = bindSandboxWsSocket(socket, {
             onMessage: (raw) => {
+                void this.#emitPlatformEvent('message', raw);
                 if (!canExecute) {
                     socket.send(JSON.stringify({
                         type: 'error',
@@ -224,7 +234,7 @@ export class SandboxWsEndpoint {
                 }));
                 // Don't gate on #open — inbound must always reach the gateway so
                 // Command/AI dispatch and outbound replies work.
-                void this.#options.gateway.receive({
+                void this.emit('message.receive', {
                     conversation,
                     ...(parsed.messageId ? { message: { conversation, id: parsed.messageId } } : {}),
                     content: parsed.text,
@@ -248,6 +258,7 @@ export class SandboxWsEndpoint {
                 });
             },
             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);
@@ -257,6 +268,7 @@ export class SandboxWsEndpoint {
                 }
             },
             onError: (err) => {
+                void this.#emitPlatformEvent('connection.error', { target, owner, error: err });
                 this.#logger.warn(formatCompact({
                     op: 'sandbox_ws_error',
                     target,
@@ -265,6 +277,7 @@ export class SandboxWsEndpoint {
             },
         });
         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);
@@ -303,6 +316,15 @@ export class SandboxWsEndpoint {
             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) => {

package/lib/index.d.ts

@@ -1,2 +1,3 @@
 export { bindSandboxWsSocket, formatSandboxOutbound, normalizeSandboxOutboundSegments, parseSandboxWsPayload, resolveSandboxEndpoint, sandboxInboundConversation, whenWsOpen, type MessageElement, type MessageType, type ResolvedSandboxBot, type SandboxAdapterConfig, type SandboxWsSocket, } from './protocol.js';
+export { SandboxClient, sandboxClient, type SandboxClientEventMap, type SandboxClientConnection, } from './client.js';
 export { SandboxWsEndpoint, type SandboxEndpointOptions, } from './endpoint.js';

package/lib/index.js

@@ -1,2 +1,3 @@
 export { bindSandboxWsSocket, formatSandboxOutbound, normalizeSandboxOutboundSegments, parseSandboxWsPayload, resolveSandboxEndpoint, sandboxInboundConversation, whenWsOpen, } from './protocol.js';
+export { SandboxClient, sandboxClient, } from './client.js';
 export { SandboxWsEndpoint, } from './endpoint.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-sandbox",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "description": "Zhin.js Sandbox adapter for Plugin Runtime (WebSocket /sandbox)",
   "type": "module",
   "main": "./lib/index.js",
@@ -48,14 +48,15 @@
   "dependencies": {
     "lucide-react": "^0.525.0",
     "react": "^19.2.8",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/client": "2.1.11",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/client": "2.1.12",
     "@zhin.js/console-contract": "1.0.1",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
+    "@zhin.js/core": "1.5.15",
+    "@zhin.js/feature-kit": "1.0.13",
+    "@zhin.js/host-http": "1.0.14",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/page": "1.0.12"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/page": "1.0.13"
   },
   "devDependencies": {
     "@types/react": "^19.2.18",
@@ -63,19 +64,19 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "ws": "^8.21.1",
-    "@zhin.js/pagemanager": "2.0.20",
-    "@zhin.js/runtime": "1.0.13",
-    "zhin.js": "6.0.13"
+    "@zhin.js/pagemanager": "2.0.21",
+    "@zhin.js/runtime": "1.0.15",
+    "zhin.js": "6.0.15"
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "@zhin.js/adapter": "1.2.0",
-    "@zhin.js/client": "2.1.11",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/client": "2.1.12",
     "@zhin.js/console-contract": "1.0.1",
-    "@zhin.js/core": "1.5.13",
-    "@zhin.js/host-http": "1.0.12",
-    "@zhin.js/page": "1.0.12",
-    "zhin.js": "6.0.13"
+    "@zhin.js/core": "1.5.15",
+    "@zhin.js/host-http": "1.0.14",
+    "@zhin.js/page": "1.0.13",
+    "zhin.js": "6.0.15"
   },
   "peerDependenciesMeta": {
     "react": {

package/src/client.ts

@@ -0,0 +1,47 @@
+import type { SandboxWsSocket } from './protocol.js';
+import { defineEndpointClient } from 'zhin.js/adapter';
+
+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 class SandboxClient {
+  constructor(
+    private readonly resolvePath: () => string,
+    private readonly resolveConnections: () => Iterable<SandboxClientConnection>,
+  ) {}
+
+  get path(): string {
+    return this.resolvePath();
+  }
+
+  connections(): readonly SandboxClientConnection[] {
+    return Object.freeze([...this.resolveConnections()]);
+  }
+
+  connection(target: string): SandboxClientConnection | undefined {
+    return this.connections().find((connection) => connection.target === target);
+  }
+
+  send(target: string, payload: string): void {
+    const connection = this.connection(target);
+    if (!connection || connection.placeholder) {
+      throw new Error(`Sandbox client ${target} is not connected`);
+    }
+    connection.socket.send(payload);
+  }
+}
+
+export type SandboxClientEventMap = Record<string, unknown>;
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterClientRegistry {
+    readonly sandbox: { readonly client: SandboxClient; readonly events: SandboxClientEventMap };
+  }
+}
+
+export const sandboxClient = defineEndpointClient<SandboxClient, SandboxClientEventMap>('sandbox');

package/src/endpoint.ts

@@ -1,10 +1,10 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway bridge for /sandbox.
+ * SandboxWsEndpoint — WebSocket lifecycle and OutboundMessageService bridge for /sandbox.
  */
 import { randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -17,6 +17,7 @@ import {
   type ResolvedSandboxBot,
   type SandboxWsSocket,
 } from './protocol.js';
+import { SandboxClient, type SandboxClientConnection } from './client.js';
 
 /**
  * 多 sandbox endpoint 共用同一个 HttpHost 时，同 path 的所有 WS listener
@@ -24,7 +25,12 @@ import {
  * 首个占用 `/sandbox`（保持 Console 默认兼容），其余退到 `/sandbox/<name>`。
  * 认领记录按 HttpHost 隔离，endpoint stop() 时必须 release。
  */
-const claimedWsPaths = new WeakMap<HttpHost, Map<string, string>>();
+interface SandboxWsPathClaim {
+  readonly name: string;
+  readonly owners: Set<symbol>;
+}
+
+const claimedWsPaths = new WeakMap<HttpHost, Map<string, SandboxWsPathClaim>>();
 
 function claimSandboxWsPath(
   http: HttpHost,
@@ -37,7 +43,7 @@ function claimSandboxWsPath(
   }
   const candidates = ['/sandbox', `/sandbox/${encodeURIComponent(name)}`];
   let path = candidates.find(
-    (candidate) => !claims!.has(candidate) || claims!.get(candidate) === name,
+    (candidate) => !claims!.has(candidate) || claims!.get(candidate)?.name === name,
   );
   if (!path) {
     let index = 2;
@@ -47,13 +53,19 @@ function claimSandboxWsPath(
       path = `/sandbox/${encodeURIComponent(name)}-${index}`;
     }
   }
-  claims.set(path, name);
+  const owner = Symbol(name);
+  const claim = claims.get(path) ?? { name, owners: new Set<symbol>() };
+  claim.owners.add(owner);
+  claims.set(path, claim);
   const claimed = path;
   const registry = claims;
   return {
     path: claimed,
     release: () => {
-      if (registry.get(claimed) === name) registry.delete(claimed);
+      claim.owners.delete(owner);
+      if (claim.owners.size === 0 && registry.get(claimed) === claim) {
+        registry.delete(claimed);
+      }
     },
   };
 }
@@ -102,8 +114,6 @@ export function createSandboxReadinessGate(probe: ShellIsolationProbe): Readonly
 
 export interface SandboxEndpointOptions {
   readonly id: CapabilityId;
-  readonly gateway: MessageGateway;
-  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly defaults: ResolvedSandboxBot;
 }
@@ -112,7 +122,8 @@ export interface SandboxEndpointOptions {
  * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export class SandboxWsEndpoint implements EndpointInstance {
+export class SandboxWsEndpoint extends Endpoint<SandboxClient> {
+  readonly client: SandboxClient;
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: SandboxEndpointOptions;
@@ -125,8 +136,18 @@ export class SandboxWsEndpoint implements EndpointInstance {
   #started = false;
 
   constructor(options: SandboxEndpointOptions) {
+    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,
+      } satisfies SandboxClientConnection)),
+    );
   }
 
   /** Live endpoint id (config `id`) — Console endpoint.list/resolve uses it. */
@@ -248,6 +269,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
     }
     const release = bindSandboxWsSocket(socket, {
       onMessage: (raw) => {
+        void this.#emitPlatformEvent('message', raw);
         if (!canExecute) {
           socket.send(JSON.stringify({
             type: 'error',
@@ -274,7 +296,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
         }));
         // Don't gate on #open — inbound must always reach the gateway so
         // Command/AI dispatch and outbound replies work.
-        void this.#options.gateway.receive({
+        void this.emit('message.receive', {
           conversation,
           ...(parsed.messageId ? { message: { conversation, id: parsed.messageId } } : {}),
           content: parsed.text,
@@ -298,6 +320,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
         });
       },
       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);
@@ -307,6 +330,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
         }
       },
       onError: (err) => {
+        void this.#emitPlatformEvent('connection.error', { target, owner, error: err });
         this.#logger.warn(formatCompact({
           op: 'sandbox_ws_error',
           target,
@@ -315,6 +339,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
       },
     });
     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);
@@ -352,6 +377,16 @@ export class SandboxWsEndpoint implements EndpointInstance {
       placeholder: true,
     });
   }
+
+  async #emitPlatformEvent(name: string, event: unknown): Promise<void> {
+    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(): Promise<ShellIsolationStatus> {

package/src/index.ts

@@ -13,6 +13,13 @@ export {
   type SandboxWsSocket,
 } from './protocol.js';
 
+export {
+  SandboxClient,
+  sandboxClient,
+  type SandboxClientEventMap,
+  type SandboxClientConnection,
+} from './client.js';
+
 export {
   SandboxWsEndpoint,
   type SandboxEndpointOptions,