@zhin.js/adapter-sandbox 5.0.4 → 5.0.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhin.js/adapter-sandbox",
-  "version": "5.0.4",
-  "description": "Zhin.js adapter for local testing and development",
+  "version": "5.0.6",
+  "description": "Zhin.js Sandbox adapter for Plugin Runtime (WebSocket /sandbox)",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -13,11 +13,14 @@
     }
   },
   "files": [
+    "adapters",
+    "pages",
+    "plugin.ts",
+    "schema.json",
     "src",
     "lib",
-    "client",
     "dist",
-    "skills",
+    "agent",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -43,35 +46,34 @@
     "directory": "plugins/adapters/sandbox"
   },
   "dependencies": {
-    "lucide-react": "^1.22.0"
+    "react": "^19.1.0",
+    "@zhin.js/console-contract": "1.0.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/logger": "1.0.75",
+    "@zhin.js/page": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "devDependencies": {
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
+    "@types/ws": "^8.18.1",
     "typescript": "^6.0.3",
-    "@zhin.js/cli": "1.0.92",
-    "@zhin.js/contract": "1.0.2",
-    "@zhin.js/client": "2.0.4",
-    "@zhin.js/core": "1.3.3",
-    "@zhin.js/host-api": "2.0.4",
-    "@zhin.js/host-router": "2.0.2",
-    "zhin.js": "4.1.1"
+    "vitest": "^4.1.10",
+    "ws": "^8.21.0",
+    "@zhin.js/pagemanager": "2.0.4",
+    "@zhin.js/runtime": "1.0.1"
   },
   "peerDependencies": {
-    "@zhin.js/core": "1.3.3",
-    "@zhin.js/client": "2.0.4",
-    "@zhin.js/host-router": "2.0.2",
-    "@zhin.js/host-api": "2.0.4",
-    "@zhin.js/contract": "1.0.2"
+    "react": "^19.0.0",
+    "@zhin.js/adapter": "1.0.1",
+    "@zhin.js/console-contract": "1.0.0",
+    "@zhin.js/core": "1.3.5",
+    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/page": "1.0.1",
+    "@zhin.js/plugin-runtime": "1.0.1"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/host-router": {
-      "optional": true
-    },
-    "@zhin.js/host-api": {
-      "optional": true
-    },
-    "@zhin.js/client": {
+    "react": {
       "optional": true
     }
   },
@@ -82,8 +84,27 @@
   "engines": {
     "node": "^20.19.0 || >=22.12.0"
   },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.ts",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/adapter",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
   "scripts": {
-    "build": "zhin build",
-    "clean": "rimraf lib"
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/sandbox/tests"
   }
 }

package/pages/sandbox.tsx

@@ -0,0 +1,95 @@
+import { definePage } from '@zhin.js/console-contract';
+import { useEffect, useRef, useState, type FormEvent } from 'react';
+
+export const meta = definePage({
+  title: 'Sandbox',
+  icon: 'Box',
+  order: 10,
+});
+
+/**
+ * Convention page (ADR 0046). Plugin Runtime Host also serves a vanilla WS shell
+ * for this localName so local smoke does not depend on a CDN React graph.
+ */
+export default function SandboxPage() {
+  const [connected, setConnected] = useState(false);
+  const [input, setInput] = useState('');
+  const [lines, setLines] = useState<readonly { readonly kind: 'in' | 'out'; readonly text: string }[]>([]);
+  const wsRef = useRef<WebSocket | null>(null);
+
+  useEffect(() => {
+    const url = new URL('/sandbox', window.location.href);
+    url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const ws = new WebSocket(url);
+    wsRef.current = ws;
+    ws.addEventListener('open', () => setConnected(true));
+    ws.addEventListener('close', () => setConnected(false));
+    ws.addEventListener('message', (event) => {
+      let text = String(event.data);
+      try {
+        const data = JSON.parse(text) as {
+          content?: Array<{ data?: { text?: string } }> | string;
+        };
+        text = Array.isArray(data.content)
+          ? data.content.map((segment) => segment?.data?.text ?? '').filter(Boolean).join('\n')
+          : typeof data.content === 'string'
+            ? data.content
+            : text;
+      } catch {
+        /* keep raw */
+      }
+      setLines((previous) => [...previous, { kind: 'in', text }]);
+    });
+    return () => {
+      ws.close();
+      wsRef.current = null;
+    };
+  }, []);
+
+  const onSubmit = (event: FormEvent) => {
+    event.preventDefault();
+    const text = input.trim();
+    const ws = wsRef.current;
+    if (!text || !ws || ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify({ text, timestamp: Date.now() }));
+    setLines((previous) => [...previous, { kind: 'out', text }]);
+    setInput('');
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: 'calc(100vh - 3rem)', maxWidth: 720, margin: '0 auto' }}>
+      <p style={{ padding: '0.75rem 1rem', margin: 0, color: '#71717a' }}>
+        {connected ? 'WebSocket /sandbox connected' : 'connecting…'}
+      </p>
+      <div style={{ flex: 1, overflow: 'auto', padding: '1rem', display: 'flex', flexDirection: 'column', gap: 8 }}>
+        {lines.map((line, index) => (
+          <div
+            key={`${line.kind}-${index}-${line.text.slice(0, 12)}`}
+            style={{
+              alignSelf: line.kind === 'out' ? 'flex-end' : 'flex-start',
+              background: line.kind === 'out' ? '#ccfbf1' : '#fff',
+              border: '1px solid #e4e4e7',
+              borderRadius: 10,
+              padding: '0.6rem 0.8rem',
+              maxWidth: '85%',
+              whiteSpace: 'pre-wrap',
+            }}
+          >
+            {line.text}
+          </div>
+        ))}
+      </div>
+      <form onSubmit={onSubmit} style={{ display: 'flex', gap: 8, padding: 12, borderTop: '1px solid #e4e4e7' }}>
+        <input
+          value={input}
+          onChange={(event) => setInput(event.target.value)}
+          placeholder="发送到 /sandbox …"
+          style={{ flex: 1, padding: '0.55rem 0.75rem', borderRadius: 8, border: '1px solid #d4d4d8' }}
+        />
+        <button type="submit" style={{ padding: '0.55rem 0.9rem', border: 0, borderRadius: 8, background: '#0f766e', color: '#fff' }}>
+          发送
+        </button>
+      </form>
+    </div>
+  );
+}

package/plugin.ts

@@ -0,0 +1,8 @@
+import { definePlugin } from '@zhin.js/plugin-runtime';
+
+export default definePlugin({
+  name: 'sandbox',
+  metadata: {
+    displayName: 'Sandbox Adapter',
+  },
+});

package/schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "endpoints": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "context": { "type": "string" },
+          "name": { "type": "string" },
+          "owner": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/src/endpoint.ts

@@ -0,0 +1,188 @@
+/**
+ * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway bridge for /sandbox.
+ */
+import { randomUUID } from 'node:crypto';
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost, WsConnection } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import {
+  bindSandboxWsSocket,
+  formatSandboxOutbound,
+  parseSandboxWsPayload,
+  whenWsOpen,
+  type ResolvedSandboxBot,
+  type SandboxWsSocket,
+} from './protocol.js';
+
+const logger = getLogger('sandbox');
+
+interface SandboxConnection {
+  readonly target: string;
+  readonly owner: string;
+  readonly socket: SandboxWsSocket;
+  readonly release: () => void;
+  /** true = 占位连接（尚无真实 WS 客户端），send 命中时按 miss 处理。 */
+  readonly placeholder?: boolean;
+}
+
+export interface SandboxEndpointOptions {
+  readonly id: CapabilityId;
+  readonly gateway: MessageGateway;
+  readonly http: HttpHost;
+  readonly defaults: ResolvedSandboxBot;
+}
+
+export class SandboxWsEndpoint implements EndpointInstance {
+  readonly #options: SandboxEndpointOptions;
+  readonly #connections = new Map<string, SandboxConnection>();
+  #wsHandleRelease?: () => void;
+  #open = false;
+  #started = false;
+
+  constructor(options: SandboxEndpointOptions) {
+    this.#options = options;
+  }
+
+  /** Live endpoint name (config `name`) — Console endpoint.list/resolve uses it. */
+  get name(): string {
+    return this.#options.defaults.name;
+  }
+
+  start(): void {
+    if (this.#started) return;
+    this.#started = true;
+    const handle = this.#options.http.ws('/sandbox');
+    this.#wsHandleRelease = handle.onConnection((connection) => {
+      this.#acceptConnection(connection);
+    });
+    if (!this.#options.defaults.randomNamePerConnection) {
+      this.#ensurePlaceholder(this.#options.defaults.name, this.#options.defaults.owner);
+    }
+    logger.info(formatCompact({
+      op: 'sandbox_ws_mounted',
+      path: '/sandbox',
+      endpoint: this.#options.defaults.name,
+    }));
+  }
+
+  open(): void {
+    this.#open = true;
+  }
+
+  close(): void {
+    this.#open = false;
+  }
+
+  stop(): void {
+    this.#open = false;
+    this.#wsHandleRelease?.();
+    this.#wsHandleRelease = undefined;
+    for (const connection of this.#connections.values()) connection.release();
+    this.#connections.clear();
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'sandbox_stopped' }));
+  }
+
+  send({ target, payload }: { readonly target: string; readonly payload: unknown }): unknown {
+    if (!this.#open) return undefined;
+    const connection = this.#connections.get(target);
+    if (!connection) {
+      logger.debug(formatCompact({ op: 'sandbox_send_miss', target }));
+      return undefined;
+    }
+    if (connection.placeholder) {
+      logger.debug(formatCompact({ op: 'sandbox_send_placeholder', target }));
+      return undefined;
+    }
+    connection.socket.send(formatSandboxOutbound(payload));
+    logger.debug(formatCompact({ op: 'sandbox_send', target }));
+    return payload;
+  }
+
+  #acceptConnection(connection: WsConnection): void {
+    const target = this.#options.defaults.randomNamePerConnection
+      ? `sandbox-${randomUUID().slice(0, 8)}`
+      : this.#options.defaults.name;
+    const owner = this.#options.defaults.owner;
+    const socket = connection.socket as SandboxWsSocket;
+    if (this.#connections.has(target)) {
+      this.#connections.get(target)?.release();
+      this.#connections.delete(target);
+    }
+    const release = bindSandboxWsSocket(socket, {
+      onMessage: (raw) => {
+        if (!this.#open) return;
+        const parsed = parseSandboxWsPayload(raw);
+        logger.debug(formatCompact({
+          op: 'sandbox_recv',
+          target,
+          sender: parsed.id || owner,
+          text: parsed.text.slice(0, 80),
+        }));
+        void this.#options.gateway.receive({
+          adapter: this.#options.id,
+          target,
+          content: parsed.text,
+          sender: parsed.id || owner,
+          metadata: Object.freeze({
+            type: parsed.type,
+            elements: parsed.content,
+            timestamp: parsed.timestamp,
+            ...(parsed.action ? { action: parsed.action } : {}),
+          }),
+        }).catch((err) => {
+          logger.warn(formatCompact({
+            op: 'sandbox_gateway_receive_failed',
+            target,
+            error: err instanceof Error ? err.message : String(err),
+          }));
+        });
+      },
+      onClose: () => {
+        this.#connections.delete(target);
+        logger.debug(formatCompact({ op: 'sandbox_ws_closed', target }));
+      },
+      onError: (err) => {
+        logger.warn(formatCompact({
+          op: 'sandbox_ws_error',
+          target,
+          error: err instanceof Error ? err.message : String(err),
+        }));
+      },
+    });
+    this.#connections.set(target, Object.freeze({ target, owner, socket, release }));
+    logger.debug(formatCompact({ op: 'sandbox_ws_connected', target, owner }));
+    if (!this.#options.defaults.randomNamePerConnection) {
+      const readyPayload = JSON.stringify({
+        type: 'ready',
+        id: owner,
+        endpoint: target,
+        content: [{
+          type: 'text',
+          data: {
+            text: [
+              `已连接 Sandbox「${target}」`,
+              '与 Node Host 控制台沙盒协议一致（/sandbox）',
+              '命令: help · ping · zt · status',
+            ].join('\n'),
+          },
+        }],
+        timestamp: Date.now(),
+      });
+      whenWsOpen(socket, () => socket.send(readyPayload));
+    }
+  }
+
+  #ensurePlaceholder(name: string, owner: string): void {
+    if (this.#connections.has(name)) return;
+    this.#connections.set(name, Object.freeze({
+      target: name,
+      owner,
+      socket: { send: () => undefined, close: () => undefined },
+      release: () => undefined,
+      placeholder: true,
+    }));
+  }
+}

package/src/index.ts

@@ -1,106 +1,17 @@
-import path from "node:path";
-import { usePlugin, type Plugin } from "zhin.js";
-import type { WebSocket } from "ws";
-import {
-  SandboxWsHostAdapter,
-  resolveSandboxEndpoint,
-  type SandboxWsSocket,
-} from "./sandbox-ws.js";
-import { PageManager } from "@zhin.js/host-api";
-
-type SandboxRouter = {
-  ws: (path: string) => NonNullable<SandboxAdapter["wss"]>;
-};
-
-declare module "zhin.js" {
-  interface Adapters {
-    sandbox: SandboxAdapter;
-  }
-}
-
-const plugin = usePlugin();
-const logger = plugin.logger;
-
-/** Node：`Router.ws` */
-export class SandboxAdapter extends SandboxWsHostAdapter {
-  wss?: { on: (ev: string, fn: (...args: unknown[]) => void) => void; close: () => void };
-
-  constructor(plugin: ReturnType<typeof usePlugin>) {
-    const appConfig = (plugin.inject("config")?.getPrimary() ?? {}) as Record<string, unknown>;
-    super(plugin, resolveSandboxEndpoint(appConfig));
-  }
-
-  override async start(): Promise<void> {
-    await super.start();
-    this.registerConfiguredPlaceholder();
-    logger.debug(
-      `Sandbox placeholder: ${this.defaults.name} (offline until /sandbox WS)`,
-    );
-  }
-
-  async setupWebSocket(router: SandboxRouter): Promise<void> {
-    if (this.wss) return;
-    this.wss = router.ws("/sandbox");
-
-    this.wss.on("connection", (...args: unknown[]) => {
-      const ws = args[0] as WebSocket;
-      const req = args[1] as { socket?: { remoteAddress?: string } };
-      logger.debug(
-        `New sandbox connection from ${req.socket?.remoteAddress ?? "unknown"}`,
-      );
-      const endpoint = this.acceptWebSocket(ws as SandboxWsSocket);
-      ws.on("close", () => {
-        logger.debug(`Sandbox connection closed: ${endpoint.$config.name}`);
-        this.endpoints.delete(endpoint.$id);
-      });
-      ws.on("error", (error) => {
-        logger.error(`Sandbox WebSocket error for ${endpoint.$config.name}:`, error);
-      });
-    });
-
-    logger.debug("Sandbox WebSocket server started at /sandbox (Node Router.ws)");
-  }
-}
-
-const { provide } = usePlugin();
-
-provide({
-  name: "sandbox",
-  description: "Sandbox Adapter — Node Router.ws",
-  mounted: async (p: Plugin) => {
-    const adapter = new SandboxAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: SandboxAdapter) => {
-    for (const endpoint of adapter.endpoints.values()) {
-      await endpoint.$disconnect();
-    }
-    adapter.wss?.close();
-    await adapter.stop();
-  },
-} as never);
-
-plugin.useContext("router",'sandbox', async (router: SandboxRouter,adapter: SandboxAdapter) => {
-  await adapter.setupWebSocket(router);
-});
-
-plugin.useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "sandbox",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "Sandbox" },
-  });
-});
-
 export {
-  SandboxWsEndpoint,
-  SandboxWsHostAdapter,
-  resolveSandboxEndpoint,
   bindSandboxWsSocket,
+  formatSandboxOutbound,
   parseSandboxWsPayload,
+  resolveSandboxEndpoint,
+  whenWsOpen,
+  type MessageElement,
+  type MessageType,
   type ResolvedSandboxBot,
-  type SandboxWsConfig,
+  type SandboxAdapterConfig,
   type SandboxWsSocket,
-} from "./sandbox-ws.js";
+} from './protocol.js';
+
+export {
+  SandboxWsEndpoint,
+  type SandboxEndpointOptions,
+} from './endpoint.js';