@zhin.js/adapter-sandbox 7.0.12 → 7.0.15

package/src/endpoint.ts

@@ -2,8 +2,9 @@
  * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway 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 } from '@zhin.js/core/runtime';
+import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, WsConnection } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from 'zhin.js';
@@ -66,9 +67,43 @@ interface SandboxConnection {
   readonly placeholder?: boolean;
 }
 
+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 function createSandboxReadinessGate(probe: ShellIsolationProbe): Readonly<{
+  afterProbe: (deliver: (status: ShellIsolationStatus) => void) => void;
+}> {
+  let inFlight: Promise<ShellIsolationStatus> | undefined;
+  const acquire = (): Promise<ShellIsolationStatus> => {
+    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);
+    },
+  });
+}
+
 export interface SandboxEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
+  readonly sideEvents?: SideEventGateway;
   readonly http: HttpHost;
   readonly defaults: ResolvedSandboxBot;
 }
@@ -82,6 +117,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
 
   readonly #options: SandboxEndpointOptions;
   readonly #connections = new Map<string, SandboxConnection>();
+  readonly #readiness = createSandboxReadinessGate(probeShellIsolation);
   #wsHandleRelease?: () => void;
   #wsPathRelease?: () => void;
   #wsPath = '/sandbox';
@@ -144,8 +180,8 @@ export class SandboxWsEndpoint implements EndpointInstance {
     this.#logger.debug(formatCompact({ op: 'sandbox_stopped' }));
   }
 
-  send({ conversation, payload }: EndpointSendRequest): unknown {
-    if (!this.#open) return undefined;
+  send({ conversation, payload }: EndpointSendRequest): string {
+    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)
@@ -155,14 +191,14 @@ export class SandboxWsEndpoint implements EndpointInstance {
         op: 'sandbox_send_miss',
         target: `${conversation.kind}:${conversation.id}`,
       }));
-      return undefined;
+      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}`,
       }));
-      return undefined;
+      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, {
@@ -177,7 +213,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
       channelType: conversation.kind,
       channelId: conversation.id,
     }));
-    return payload;
+    return randomUUID();
   }
 
   /** Prefer a real (non-placeholder) socket when reply target key is wrong/stale. */
@@ -193,6 +229,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
       ? `sandbox-${randomUUID().slice(0, 8)}`
       : this.#options.defaults.id;
     const owner = this.#options.defaults.owner;
+    const canExecute = connection.authScope === 'full';
     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
@@ -211,26 +248,37 @@ export class SandboxWsEndpoint implements EndpointInstance {
     }
     const release = bindSandboxWsSocket(socket, {
       onMessage: (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 sender = parsed.id || owner;
+        const sceneId = parsed.id || owner;
         const conversation = sandboxInboundConversation(String(this.#options.id), {
           type: parsed.type,
-          id: sender,
+          id: sceneId,
         });
         this.#logger.debug(formatCompact({
           op: 'sandbox_recv',
           target,
-          sender,
+          sender: owner,
           channelType: parsed.type,
-          channelId: sender,
+          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.#options.gateway.receive({
           conversation,
+          ...(parsed.messageId ? { message: { conversation, id: parsed.messageId } } : {}),
           content: parsed.text,
-          sender: { id: sender },
+          sender: { id: owner },
           endpointId: target,
           metadata: Object.freeze({
             type: parsed.type,
@@ -239,6 +287,7 @@ export class SandboxWsEndpoint implements EndpointInstance {
             elements: parsed.content,
             timestamp: parsed.timestamp,
             ...(parsed.action ? { action: parsed.action } : {}),
+            ...(parsed.agentRun ? { sandboxAgentRun: parsed.agentRun } : {}),
           }),
         }).catch((err) => {
           this.#logger.warn(formatCompact({
@@ -267,25 +316,30 @@ export class SandboxWsEndpoint implements EndpointInstance {
     });
     this.#connections.set(target, { target, owner, socket, release });
     this.#logger.debug(formatCompact({ op: 'sandbox_ws_connected', target, owner }));
-    if (!this.#options.defaults.randomNamePerConnection) {
+    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}）`,
-              '命令: help · ping · zt · status',
+              'Agent 试验台会话已启用持久化运行配置。',
             ].join('\n'),
           },
         }],
         timestamp: Date.now(),
       });
       whenWsOpen(socket, () => socket.send(readyPayload));
-    }
+    });
   }
 
   #ensurePlaceholder(name: string, owner: string): void {
@@ -299,3 +353,33 @@ export class SandboxWsEndpoint implements EndpointInstance {
     });
   }
 }
+
+function probeShellIsolation(): Promise<ShellIsolationStatus> {
+  return new Promise<ShellIsolationStatus>((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' as const,
+    message: 'Docker is unavailable',
+  }));
+}

package/src/protocol.ts

@@ -4,6 +4,10 @@ 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');
 
@@ -70,7 +74,10 @@ export function resolveSandboxEndpoint(
     context: 'sandbox',
     id,
     owner,
-    randomNamePerConnection: !fixedName,
+    // 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,
   };
 }
 
@@ -124,10 +131,12 @@ export function bindSandboxWsSocket(
 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;
@@ -135,6 +144,8 @@ export function parseSandboxWsPayload(raw: string): {
     content?: MessageElement[] | string;
     text?: string;
     timestamp?: number;
+    messageId?: unknown;
+    agentRun?: unknown;
   };
   try {
     payload = JSON.parse(raw) as typeof payload;
@@ -175,7 +186,19 @@ export function parseSandboxWsPayload(raw: string): {
       ? payload.text
       : action?.payload ?? raw;
   }
-  return { type, id, content, timestamp: payload.timestamp ?? Date.now(), text, action };
+  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 } : {}),
+  };
 }
 
 /**

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,
+  });
+}