@zhin.js/adapter-sandbox 5.0.5 → 6.0.0

package/src/endpoint.ts

@@ -0,0 +1,261 @@
+/**
+ * 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 SandboxChannel {
+  readonly type: string;
+  readonly id: string;
+}
+
+interface SandboxConnection {
+  readonly target: string;
+  readonly owner: string;
+  readonly socket: SandboxWsSocket;
+  readonly release: () => void;
+  /** true = 占位连接（尚无真实 WS 客户端），send 命中时按 miss 处理。 */
+  readonly placeholder?: boolean;
+  /**
+   * 最近一条入站频道（Console UI 按 type+id 过滤气泡）。
+   * 出站必须带回，否则回复石沉大海。
+   */
+  lastChannel?: SandboxChannel;
+}
+
+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();
+      if (!connection.placeholder) {
+        try {
+          connection.socket.close(1001, 'sandbox endpoint stopped');
+        } catch {
+          /* already closed */
+        }
+      }
+    }
+    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;
+    // Reply target is the connection key (bot name / sandbox-uuid), not private:channelId.
+    const connection = this.#connections.get(target)
+      ?? this.#findLiveConnection();
+    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;
+    }
+    // Console UI filters by type+id; stamp last inbound channel onto outbound wire.
+    const channel = connection.lastChannel ?? {
+      type: 'private',
+      id: connection.owner,
+    };
+    connection.socket.send(formatSandboxOutbound(payload, {
+      type: channel.type,
+      id: channel.id,
+      bot: this.#options.defaults.name,
+      endpoint: connection.target,
+    }));
+    logger.debug(formatCompact({
+      op: 'sandbox_send',
+      target: connection.target,
+      channelType: channel.type,
+      channelId: channel.id,
+    }));
+    return payload;
+  }
+
+  /** Prefer a real (non-placeholder) socket when reply target key is wrong/stale. */
+  #findLiveConnection(): SandboxConnection | undefined {
+    for (const connection of this.#connections.values()) {
+      if (!connection.placeholder) return connection;
+    }
+    return undefined;
+  }
+
+  #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;
+    // 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) => {
+        const parsed = parseSandboxWsPayload(raw);
+        const conn = this.#connections.get(target);
+        if (conn && !conn.placeholder) {
+          conn.lastChannel = {
+            type: parsed.type,
+            id: parsed.id || owner,
+          };
+        }
+        logger.debug(formatCompact({
+          op: 'sandbox_recv',
+          target,
+          sender: parsed.id || owner,
+          channelType: parsed.type,
+          channelId: parsed.id || owner,
+          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.#options.gateway.receive({
+          adapter: this.#options.id,
+          target,
+          content: parsed.text,
+          sender: parsed.id || owner,
+          metadata: Object.freeze({
+            type: parsed.type,
+            channelType: parsed.type,
+            channelId: parsed.id || owner,
+            endpoint: target,
+            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: () => {
+        // 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);
+          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, { 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, {
+      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';

package/src/protocol.ts

@@ -0,0 +1,240 @@
+/** Sandbox WebSocket wire protocol helpers (no legacy Adapter/Endpoint). */
+
+export type MessageType = 'private' | 'group' | 'guild' | 'direct' | 'channel';
+
+export interface MessageElement {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface SandboxWsSocket {
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  on?(event: 'message' | 'close' | 'error', listener: (...args: unknown[]) => void): void;
+  off?(
+    event: 'message' | 'close' | 'error',
+    listener: (...args: unknown[]) => void,
+  ): void;
+  addEventListener?(
+    type: 'message' | 'close' | 'error',
+    listener: (ev: Event | MessageEvent | CloseEvent) => void,
+  ): void;
+  removeEventListener?(
+    type: 'message' | 'close' | 'error',
+    listener: (ev: Event | MessageEvent | CloseEvent) => void,
+  ): void;
+}
+
+export type ResolvedSandboxBot = {
+  readonly context: 'sandbox';
+  readonly name: string;
+  readonly owner: string;
+  readonly randomNamePerConnection: boolean;
+};
+
+export interface SandboxAdapterConfig {
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly name?: string;
+    readonly owner?: string;
+  }>;
+}
+
+export function resolveSandboxEndpoint(
+  appConfig: SandboxAdapterConfig,
+): ResolvedSandboxBot {
+  const entry = appConfig.endpoints?.find((item) => item.context === 'sandbox');
+  const fixedName = typeof entry?.name === 'string' ? entry.name : undefined;
+  const name = fixedName || process.env.SANDBOX_BOT_NAME || 'sandbox-bot';
+  const owner = (typeof entry?.owner === 'string' && entry.owner)
+    || process.env.SANDBOX_BOT_OWNER
+    || 'sandbox-user';
+  return {
+    context: 'sandbox',
+    name,
+    owner,
+    randomNamePerConnection: !fixedName,
+  };
+}
+
+export function bindSandboxWsSocket(
+  ws: SandboxWsSocket,
+  handlers: {
+    onMessage: (raw: string) => void;
+    onClose: () => void;
+    onError?: (err: unknown) => void;
+  },
+): () => void {
+  if (typeof ws.on === 'function') {
+    const onMessage = (...args: unknown[]) => {
+      const data = args[0];
+      const raw = typeof data === 'string'
+        ? data
+        : data instanceof ArrayBuffer
+          ? new TextDecoder().decode(data)
+          : Buffer.isBuffer(data)
+            ? data.toString()
+            : String(data ?? '');
+      handlers.onMessage(raw);
+    };
+    ws.on('message', onMessage);
+    ws.on('close', handlers.onClose);
+    if (handlers.onError) ws.on('error', handlers.onError);
+    return () => {
+      ws.off?.('message', onMessage);
+      ws.off?.('close', handlers.onClose);
+      if (handlers.onError) ws.off?.('error', handlers.onError);
+    };
+  }
+  const onMessage = (ev: Event) => {
+    const data = (ev as MessageEvent).data;
+    handlers.onMessage(typeof data === 'string' ? data : '');
+  };
+  const onClose = () => handlers.onClose();
+  const onError = handlers.onError
+    ? () => handlers.onError?.(new Error('WebSocket error'))
+    : undefined;
+  ws.addEventListener!('message', onMessage);
+  ws.addEventListener!('close', onClose);
+  if (onError) ws.addEventListener!('error', onError);
+  return () => {
+    ws.removeEventListener!('message', onMessage);
+    ws.removeEventListener!('close', onClose);
+    if (onError) ws.removeEventListener!('error', onError);
+  };
+}
+
+export function parseSandboxWsPayload(raw: string): {
+  type: MessageType;
+  id: string;
+  content: MessageElement[];
+  timestamp: number;
+  text: string;
+  action?: { id: string; payload: string };
+} {
+  let payload: {
+    type?: MessageType;
+    id?: string;
+    content?: MessageElement[] | string;
+    text?: string;
+    timestamp?: number;
+  };
+  try {
+    payload = JSON.parse(raw) as typeof payload;
+  } catch {
+    payload = { text: raw };
+  }
+  const type = payload.type ?? 'private';
+  const id = payload.id ?? 'sandbox-user';
+  const content: MessageElement[] = typeof payload.content === 'string'
+    ? [{ type: 'text', data: { text: payload.content } }]
+    : Array.isArray(payload.content)
+      ? payload.content
+      : [{ type: 'text', data: { text: payload.text ?? raw } }];
+
+  const actionSegment = content.find((segment) => segment.type === 'action');
+  let action: { id: string; payload: string } | undefined;
+  if (actionSegment?.data) {
+    const actionPayload = typeof actionSegment.data.payload === 'string'
+      ? actionSegment.data.payload
+      : typeof actionSegment.data.id === 'string'
+        ? actionSegment.data.id
+        : '';
+    const actionId = typeof actionSegment.data.id === 'string'
+      ? actionSegment.data.id
+      : actionPayload;
+    if (actionId || actionPayload) {
+      action = { id: actionId || actionPayload, payload: actionPayload || actionId };
+    }
+  }
+
+  let text = content
+    .flatMap((segment) => (segment.type === 'text' && typeof segment.data?.text === 'string'
+      ? [segment.data.text]
+      : []))
+    .join('\n');
+  if (!text.trim()) {
+    text = (typeof payload.text === 'string' && payload.text.trim())
+      ? payload.text
+      : action?.payload ?? raw;
+  }
+  return { type, id, content, timestamp: payload.timestamp ?? Date.now(), text, action };
+}
+
+export type SandboxOutboundChannel = {
+  readonly type?: string;
+  readonly id?: string;
+  readonly bot?: string;
+  readonly endpoint?: string;
+  readonly messageId?: string;
+};
+
+/**
+ * Wire-encode an already-rendered outbound payload.
+ * Stamps `channel` so Console SandboxChat can filter by type+id (otherwise
+ * replies look like they disappeared).
+ */
+export function formatSandboxOutbound(
+  payload: unknown,
+  channel: SandboxOutboundChannel = {},
+): string {
+  const stamp: Record<string, unknown> = {};
+  if (channel.type) stamp.type = channel.type;
+  if (channel.id) stamp.id = channel.id;
+  if (channel.bot) stamp.bot = channel.bot;
+  if (channel.endpoint) stamp.endpoint = channel.endpoint;
+  if (channel.messageId) stamp.messageId = channel.messageId;
+
+  if (typeof payload === 'string') {
+    return JSON.stringify({
+      ...stamp,
+      content: [{ type: 'text', data: { text: payload } }],
+      timestamp: Date.now(),
+    });
+  }
+  if (Array.isArray(payload)) {
+    return JSON.stringify({
+      ...stamp,
+      content: payload,
+      timestamp: Date.now(),
+    });
+  }
+  // Already a wire envelope ({ content, type, … }) — pass through so the
+  // Console UI can read `content` / `type` without an extra nesting layer.
+  // Bare segment objects ({ type: 'text', data: … }) still need wrapping.
+  if (
+    payload
+    && typeof payload === 'object'
+    && !Array.isArray(payload)
+    && (
+      'content' in (payload as object)
+      || 'type' in (payload as object) && 'timestamp' in (payload as object)
+    )
+  ) {
+    const envelope = payload as Record<string, unknown>;
+    return JSON.stringify({
+      ...stamp,
+      ...envelope,
+      type: envelope.type ?? stamp.type,
+      id: envelope.id ?? stamp.id,
+      timestamp: typeof envelope.timestamp === 'number' ? envelope.timestamp : Date.now(),
+    });
+  }
+  return JSON.stringify({ ...stamp, content: payload, timestamp: Date.now() });
+}
+
+/** WebSocket.OPEN 常量值；Node <22 无全局 WebSocket，不能用 WebSocket.OPEN。 */
+const WS_OPEN = 1;
+
+export function whenWsOpen(ws: SandboxWsSocket, fn: () => void): void {
+  const std = ws as WebSocket;
+  if (typeof std.readyState === 'number') {
+    if (std.readyState === WS_OPEN) {
+      fn();
+      return;
+    }
+    std.addEventListener('open', fn, { once: true });
+    return;
+  }
+  fn();
+}

package/client/index.tsx

@@ -1,11 +0,0 @@
-import type { PluginRegisterHostApi } from '@zhin.js/contract'
-import Sandbox from './Sandbox'
-
-export function register(api: PluginRegisterHostApi) {
-  api.addRoute({
-    path: '/console/sandbox',
-    name: '沙盒',
-    element: api.React.createElement(Sandbox, { hostReact: api.React }),
-  })
-  api.addTool({ id: 'sandbox', name: '沙盒', path: '/console/sandbox' })
-}

package/client/sandboxTransport.ts

@@ -1,28 +0,0 @@
-export function getSandboxApiBase(): string {
-  const stored = localStorage.getItem("zhin_api_base")?.trim();
-  return (stored ? stored.replace(/\/$/, "") : null) ?? window.location.origin;
-}
-
-export function getSandboxBearerToken(): string {
-  return (
-    localStorage.getItem("zhin_api_token")?.trim() ||
-    localStorage.getItem("HTTP_TOKEN")?.trim() ||
-    localStorage.getItem("zhin_http_token")?.trim() ||
-    ""
-  );
-}
-
-export function getSandboxAuthHeaders(): Record<string, string> {
-  const token = getSandboxBearerToken();
-  return token ? { Authorization: `Bearer ${token}` } : {};
-}
-
-/** Browser WebSocket cannot set Authorization reliably; pass token in query when needed. */
-export function buildSandboxWebSocketUrl(base?: string): string {
-  const apiBase = (base ?? getSandboxApiBase()).replace(/\/$/, "");
-  const wsUrl = new URL("/sandbox", `${apiBase}/`);
-  wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
-  const token = getSandboxBearerToken();
-  if (token) wsUrl.searchParams.set("token", token);
-  return wsUrl.href;
-}

package/client/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../node_modules/@zhin.js/host-api/browser.tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../dist"
-  },
-  "include": ["./**/*"]
-}