@zhin.js/adapter-sandbox 1.0.70 → 1.1.0

package/src/index.ts

@@ -1,238 +1,26 @@
-import { EventEmitter } from "events";
-import {
-  Bot,
-  Adapter,
-  usePlugin,
-  Message,
-  SendOptions,
-  segment,
-  SendContent,
-  MessageType,
-  MessageElement,
-  Plugin,
-} from "zhin.js";
-import type { WebSocket } from "ws";
-import { Router } from "@zhin.js/http";
-import path from "path";
-
-export interface SandboxConfig {
-  context: "sandbox";
-  ws: WebSocket;
-  name: string;
-  /** 发言者即为 owner（沙箱模式） */
-  owner?: string;
-}
-
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      router: Router;
-      web: any;
-    }
-  }
-
-  interface Adapters {
-    sandbox: SandboxAdapter;
-  }
-}
-
-const plugin = usePlugin();
-const logger = plugin.logger;
-
-interface WebSocketMessage {
-  type: MessageType;
-  id: string;
-  content: MessageElement[] | string;
-  timestamp: number;
-}
-
-export class SandboxBot extends EventEmitter implements Bot<SandboxConfig, { content: MessageElement[]; ts: number }> {
-  $connected: boolean = false;
-
-  get $id() {
-    return this.$config.name;
-  }
-
-  private logger = logger;
-
-  constructor(public adapter: SandboxAdapter, public $config: SandboxConfig) {
-    super();
-    this.$config.ws.on("message", (data) => {
-      const message = JSON.parse(data.toString()) as WebSocketMessage;
-      // 确保 content 是 MessageElement[] 格式
-      const content: MessageElement[] = typeof message.content === 'string' 
-        ? [{ type: 'text', data: { text: message.content } }]
-        : message.content;
-      this.logger.debug(`${this.$config.name} recv  ${message.type}(${message.id}):${segment.raw(content)}`);
-      const formattedMessage = this.$formatMessage({ content: content, type: message.type, id: message.id, ts: message.timestamp });
-      this.adapter.emit("message.receive", formattedMessage);
-    });
-
-    this.$config.ws.on("close", () => {
-      this.logger.debug(`Sandbox bot ${this.$config.name} disconnected`);
-      this.$connected = false;
-      // 从 adapter 中移除 bot
-      this.adapter.bots.delete(this.$id);
-    });
-  }
-
-  async $connect(): Promise<void> {
-    this.$connected = true;
-  }
-
-  async $disconnect(): Promise<void> {
-    this.$config.ws.close();
-    this.$connected = false;
-  }
-
-  $formatMessage({ content, type, id, ts }: { content: MessageElement[]; id: string; type: MessageType; ts: number }) {
-    // 沙箱模式：发言者即为 owner
-    if (!this.$config.owner) this.$config.owner = id;
-    const message = Message.from(
-      { content, ts },
-      {
-        $id: `${ts}`,
-        $adapter: "sandbox" as const,
-        $bot: `${this.$config.name}`,
-        $sender: {
-          id: `${id}`,
-          name: `mock`,
-        },
-        $channel: {
-          id: `${id}`,
-          type: type,
-        },
-        $content: content,
-        $raw: segment.raw(content),
-        $timestamp: ts,
-        $recall: async () => {
-          await this.$recallMessage(message.$id);
-        },
-        $reply: async (content: SendContent, quote?: boolean | string): Promise<string> => {
-          if (!Array.isArray(content)) content = [content];
-          if (quote) content.unshift({ type: "reply", data: { id: typeof quote === "boolean" ? message.$id : quote } });
-          return await this.adapter.sendMessage({
-            ...message.$channel,
-            context: "sandbox",
-            bot: `${this.$config.name}`,
-            content,
-          });
-        },
-      }
-    );
-    return message;
-  }
-
-  async $sendMessage(options: SendOptions): Promise<string> {
-    if (!this.$connected) return "";
-    this.logger.debug(`${this.$config.name} send ${options.type}(${options.id}):${segment.raw(options.content)}`);
-    options.bot = this.$config.name;
-    options.context = "sandbox";
-    this.$config.ws.send(
-      JSON.stringify({
-        ...options,
-        content: options.content, // 发送消息段数组
-        timestamp: Date.now(),
-      })
-    );
-    return "";
-  }
-
-  async $recallMessage(id: string): Promise<void> {
-    // 沙盒不支持撤回消息
-  }
-}
-
-class SandboxAdapter extends Adapter<SandboxBot> {
-  wss?: ReturnType<Router["ws"]>;
-
-  constructor(plugin: Plugin) {
-    super(plugin, "sandbox", []);
-  }
-
-  createBot(config: SandboxConfig): SandboxBot {
-    const bot = new SandboxBot(this, config);
-    // 将 bot 添加到 bots Map 中
-    this.bots.set(bot.$id, bot);
-    return bot;
-  }
-
-  async start(): Promise<void> {
-    // start 方法会在 mounted 时被调用
-    // WebSocket server 的创建在 useContext("router") 中处理
-  }
-
-  async setupWebSocket(router: Router): Promise<void> {
-    if (this.wss) return; // 已经设置过了
-    // 创建 WebSocket server
-    this.wss = router.ws("/sandbox");
-
-    this.wss.on("connection", (ws: WebSocket, req) => {
-      // 为每个连接创建一个唯一的 bot 名称
-      const botName = `sandbox-${Math.random().toString(36).slice(2, 9)}`;
-      logger.debug(`New sandbox connection: ${botName} from ${req.socket.remoteAddress}`);
-
-      // 创建 bot 配置
-      const config: SandboxConfig = {
-        context: "sandbox",
-        ws,
-        name: botName,
-      };
-
-      // 创建并连接 bot
-      const bot = this.createBot(config);
-      bot.$connect();
-
-      // WebSocket 关闭时清理
-      ws.on("close", () => {
-        logger.debug(`Sandbox connection closed: ${botName}`);
-        this.bots.delete(bot.$id);
-      });
-
-      ws.on("error", (error) => {
-        logger.error(`Sandbox WebSocket error for ${botName}:`, error);
-      });
-    });
-
-    logger.debug("Sandbox WebSocket server started at /sandbox");
-  }
-}
-
-const { provide } = usePlugin();
-
-provide({
-  name: "sandbox",
-  description: "Sandbox Adapter",
-  mounted: async (p: Plugin) => {
-    const adapter = new SandboxAdapter(p);
-    await adapter.start();
-    return adapter;
-  },
-  dispose: async (adapter: SandboxAdapter) => {
-    // 关闭所有 bot 连接
-    for (const bot of adapter.bots.values()) {
-      await bot.$disconnect();
-    }
-    // 关闭 WebSocket server
-    adapter.wss?.close();
-    await adapter.stop();
-  },
-});
-
-// 使用 router 上下文创建 WebSocket server
-plugin.useContext("router", async (router: Router) => {
-  // 等待 sandbox adapter 就绪
-  plugin.useContext("sandbox", async (adapter: SandboxAdapter) => {
-    await adapter.setupWebSocket(router);
-  });
-});
-
-// 使用 web 上下文注册客户端入口
-plugin.useContext("web", (web: any) => {
-  // 注册 Sandbox 适配器的客户端入口文件
-  const dispose = web.addEntry({
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-  });
-  return dispose;
-});
+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/src/protocol.ts

@@ -0,0 +1,398 @@
+/** Sandbox WebSocket wire protocol helpers (no legacy Adapter/Endpoint). */
+
+import { readFileSync } from 'node:fs';
+import { isMediaRef } from '@zhin.js/core';
+import type { ConversationKind, ConversationRef } from '@zhin.js/im-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  normalizeSandboxAgentRunConfig,
+  type SandboxAgentRunConfig,
+} from './run-config.js';
+
+const logger = getLogger('sandbox');
+
+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 id: string;
+  readonly owner: string;
+  readonly randomNamePerConnection: boolean;
+};
+
+export interface SandboxAdapterConfig {
+  /** Runtime expands `endpoints[i]` onto the top level — prefer these. */
+  readonly context?: string;
+  readonly id?: string;
+  readonly owner?: string;
+  /** Legacy shape: endpoint entries nested under `endpoints[]`. */
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly id?: string;
+    readonly owner?: string;
+  }>;
+}
+
+export function resolveSandboxEndpoint(
+  appConfig: SandboxAdapterConfig,
+): ResolvedSandboxBot {
+  const entry = appConfig.endpoints?.find((item) => item.context === 'sandbox');
+  const fixedName = typeof appConfig.id === 'string' && appConfig.id
+    ? appConfig.id
+    : typeof entry?.id === 'string' && entry.id
+      ? entry.id
+      : undefined;
+  const id = fixedName || process.env.SANDBOX_BOT_NAME || 'sandbox-bot';
+  const owner = (typeof appConfig.owner === 'string' && appConfig.owner)
+    || (typeof entry?.owner === 'string' && entry.owner)
+    || process.env.SANDBOX_BOT_OWNER
+    || 'sandbox-user';
+  return {
+    context: 'sandbox',
+    id,
+    owner,
+    // The endpoint id participates in the Agent session key. Keep it stable
+    // across browser reconnects and Host restarts so a persisted playground
+    // session resumes the same Agent context.
+    randomNamePerConnection: false,
+  };
+}
+
+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;
+  messageId?: string;
+  content: MessageElement[];
+  timestamp: number;
+  text: string;
+  action?: { id: string; payload: string };
+  agentRun?: SandboxAgentRunConfig;
+} {
+  let payload: {
+    type?: MessageType;
+    id?: string;
+    content?: MessageElement[] | string;
+    text?: string;
+    timestamp?: number;
+    messageId?: unknown;
+    agentRun?: unknown;
+  };
+  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;
+  }
+  const agentRun = normalizeSandboxAgentRunConfig(payload.agentRun);
+  const rawMessageId = typeof payload.messageId === 'string' ? payload.messageId.trim() : '';
+  const messageId = /^[A-Za-z0-9._:-]{1,160}$/u.test(rawMessageId) ? rawMessageId : undefined;
+  return {
+    type,
+    id,
+    ...(messageId ? { messageId } : {}),
+    content,
+    timestamp: payload.timestamp ?? Date.now(),
+    text,
+    action,
+    ...(agentRun ? { agentRun } : {}),
+  };
+}
+
+/**
+ * 入站归一化 → ConversationRef。sandbox 无平台社交图谱：
+ * `private`/`group`/`channel` 直映射；`direct`（私聊）归 'private'；
+ * `guild`（频道容器语义）归 'channel'。无 guild/temp 容器信息，不产生 parent。
+ */
+export function sandboxInboundConversation(
+  endpointKey: string,
+  msg: { readonly type: MessageType; readonly id: string },
+): ConversationRef {
+  const kind: ConversationKind = msg.type === 'direct'
+    ? 'private'
+    : msg.type === 'guild'
+      ? 'channel'
+      : msg.type;
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind,
+    id: msg.id,
+  };
+}
+
+export type SandboxOutboundChannel = {
+  readonly type?: string;
+  readonly id?: string;
+  readonly bot?: string;
+  readonly endpoint?: string;
+  readonly messageId?: string;
+};
+
+const MEDIA_SEGMENT_TYPES = new Set(['image', 'audio', 'video', 'file']);
+
+/**
+ * base64 内联值：Console UI 的 resolveMediaSrc 只识别 data: / base64://
+ * 前缀；裸 base64 补前缀（有 mime_type 时拼成可直转 data: URL 的形状）。
+ */
+function toInlineBase64Value(value: string, mimeType?: string): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('base64://') || trimmed.startsWith('data:')) return trimmed;
+  return mimeType
+    ? `base64://${mimeType};base64,${trimmed}`
+    : `base64://${trimmed}`;
+}
+
+/**
+ * 出站媒体段归一（canonical MediaRef 唯一来源，不读 legacy url/file/base64/src）：
+ * - kind=url → 浏览器直连 URL，原样透传；
+ * - kind=base64 → 内联直发（补 base64:// 前缀供 Console UI 解析）；
+ * - kind=path → 读盘物化为 base64 内联（sandbox 无平台上传通道）；
+ * - kind=file → sandbox 无不透明引用通道，丢弃。
+ * 无 canonical `data.media` 的媒体段一律 warn + 丢弃。
+ */
+function normalizeMediaSegment(segment: MessageElement): MessageElement | null {
+  const data = segment.data ?? {};
+  const media = data.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'sandbox_outbound_media_dropped',
+      type: segment.type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
+  }
+  if (media.kind === 'url') return { type: segment.type, data };
+  if (media.kind === 'base64') {
+    return {
+      type: segment.type,
+      data: {
+        ...data,
+        media: { ...media, value: toInlineBase64Value(media.value, media.mime_type) },
+      },
+    };
+  }
+  if (media.kind === 'path') {
+    try {
+      const base64 = readFileSync(media.value).toString('base64');
+      return {
+        type: segment.type,
+        data: {
+          ...data,
+          media: {
+            ...media,
+            kind: 'base64',
+            value: toInlineBase64Value(base64, media.mime_type),
+          },
+        },
+      };
+    } catch (err) {
+      logger.warn(formatCompact({
+        op: 'sandbox_outbound_media_dropped',
+        type: segment.type,
+        reason: 'path_read_failed',
+        error: err instanceof Error ? err.message : String(err),
+      }));
+      return null;
+    }
+  }
+  logger.warn(formatCompact({
+    op: 'sandbox_outbound_media_dropped',
+    type: segment.type,
+    reason: 'unsupported_media_kind',
+  }));
+  return null;
+}
+
+/** 出站段数组归一：媒体段走 MediaRef-only 归一，其余段原样透传。 */
+export function normalizeSandboxOutboundSegments(segments: readonly unknown[]): unknown[] {
+  const out: unknown[] = [];
+  for (const item of segments) {
+    if (
+      item
+      && typeof item === 'object'
+      && !Array.isArray(item)
+      && MEDIA_SEGMENT_TYPES.has(String((item as MessageElement).type))
+    ) {
+      const normalized = normalizeMediaSegment(item as MessageElement);
+      if (normalized) out.push(normalized);
+      continue;
+    }
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * 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: normalizeSandboxOutboundSegments(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,
+      ...(Array.isArray(envelope.content)
+        ? { content: normalizeSandboxOutboundSegments(envelope.content) }
+        : {}),
+      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/src/run-config.ts

@@ -0,0 +1,41 @@
+export type SandboxSafetyMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+export type SandboxApprovalMode = 'ask' | 'deny' | 'allow';
+
+export interface SandboxAgentRunConfig {
+  readonly workingDirectory: string;
+  readonly safetyMode: SandboxSafetyMode;
+  readonly approvalMode: SandboxApprovalMode;
+  readonly networkAccess: boolean;
+}
+
+export const DEFAULT_SANDBOX_AGENT_RUN_CONFIG: SandboxAgentRunConfig = Object.freeze({
+  workingDirectory: '',
+  safetyMode: 'workspace-write',
+  approvalMode: 'ask',
+  networkAccess: false,
+});
+
+const SAFETY_MODES = new Set<SandboxSafetyMode>(['read-only', 'workspace-write', 'danger-full-access']);
+const APPROVAL_MODES = new Set<SandboxApprovalMode>(['ask', 'deny', 'allow']);
+
+export function normalizeSandboxAgentRunConfig(value: unknown): SandboxAgentRunConfig | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined;
+  const input = value as Record<string, unknown>;
+  const workingDirectory = typeof input.workingDirectory === 'string'
+    ? input.workingDirectory.trim().slice(0, 4096)
+    : '';
+  const safetyMode = SAFETY_MODES.has(input.safetyMode as SandboxSafetyMode)
+    ? input.safetyMode as SandboxSafetyMode
+    : DEFAULT_SANDBOX_AGENT_RUN_CONFIG.safetyMode;
+  const approvalMode = APPROVAL_MODES.has(input.approvalMode as SandboxApprovalMode)
+    ? input.approvalMode as SandboxApprovalMode
+    : DEFAULT_SANDBOX_AGENT_RUN_CONFIG.approvalMode;
+  return Object.freeze({
+    workingDirectory,
+    safetyMode,
+    approvalMode,
+    // Full host access cannot be combined with a portable network namespace.
+    // Keep the contract honest: danger mode includes network authority.
+    networkAccess: safetyMode === 'danger-full-access' || input.networkAccess === true,
+  });
+}