@zhin.js/adapter-sandbox 7.0.12 → 7.0.15

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @zhin.js/adapter-process
 
+## 7.0.15
+
+### Patch Changes
+
+- bcc4c87: Probe Docker readiness asynchronously so Sandbox WebSocket permissions and messages are never blocked by the informational ready frame.
+
+## 7.0.14
+
+### Patch Changes
+
+- 9e609f4: Stabilize Sandbox WebSocket regressions by waiting for the server-side connection registration and verifying the demo-scope gate independently from the informational ready frame.
+
+## 7.0.13
+
+### Patch Changes
+
+- 974772e: Replace the user-facing `Prompt` vocabulary with the `UserInteraction` authoring surface for input, confirmation, and selection. Commands and handlers now expose `interaction`; IM Runtime exposes `createInteraction`; schema-driven endpoint collection is named `SchemaInteraction`. The old prompt-named interaction types and properties are removed rather than aliased. User interactions render through one canonical Markdown and keyboard/list presentation module shared by commands and Agent `ask_user` turns.
+
+  Extract the transport-neutral interaction contract into `@zhin.js/interaction`. A discriminated `ask()` API supports text, number, confirmation, single-select, multi-select, and typed lists with structured `title`, `description`, and `tip` content. Typed `sequence()` interactions return one result object keyed by step id, render progress, and retry invalid replies without leaking invalid values to callers.
+
+  Preserve AI Markdown and card command actions through outbound publishing. QQ delivers Markdown with native command buttons; KOOK, Discord, Telegram, DingTalk, and Lark/Feishu now declare and encode their native Markdown dialects while retaining each adapter's interaction policy. Correct QQ callback button action encoding and button style mapping.
+
+- 5969c5b: Add SideEventGateway so adapters forward notice/request/system into HandlerIndex. HandlerContext now exposes only generation-safe capabilities and prompt ports; live Endpoint escape hatches are removed.
+- Updated dependencies [5969c5b]
+- Updated dependencies [d336a3f]
+- Updated dependencies [5969c5b]
+- Updated dependencies [5969c5b]
+- Updated dependencies [974772e]
+- Updated dependencies [5969c5b]
+- Updated dependencies [2f786bd]
+- Updated dependencies [1312ca0]
+- Updated dependencies [985fa22]
+  - @zhin.js/im-contract@1.0.4
+  - @zhin.js/core@1.5.12
+  - @zhin.js/adapter@1.1.11
+  - @zhin.js/host-http@1.0.11
+  - @zhin.js/client@2.1.10
+  - zhin.js@6.0.12
+  - @zhin.js/page@1.0.12
+
 ## 7.0.12
 
 ### Patch Changes

package/adapters/sandbox.js

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

package/lib/endpoint.d.ts

@@ -1,11 +1,26 @@
 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 } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type ResolvedSandboxBot } from './protocol.js';
+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 declare function createSandboxReadinessGate(probe: ShellIsolationProbe): Readonly<{
+    afterProbe: (deliver: (status: ShellIsolationStatus) => void) => void;
+}>;
 export interface SandboxEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
+    readonly sideEvents?: SideEventGateway;
     readonly http: HttpHost;
     readonly defaults: ResolvedSandboxBot;
 }
@@ -22,5 +37,6 @@ export declare class SandboxWsEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): void;
-    send({ conversation, payload }: EndpointSendRequest): unknown;
+    send({ conversation, payload }: EndpointSendRequest): string;
 }
+export {};

package/lib/endpoint.js

@@ -2,6 +2,7 @@
  * SandboxWsEndpoint — WebSocket lifecycle and MessageGateway 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';
 /**
@@ -38,6 +39,30 @@ function claimSandboxWsPath(http, name) {
         },
     };
 }
+/**
+ * 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) {
+    let inFlight;
+    const acquire = () => {
+        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);
+        },
+    });
+}
 /**
  * Sandbox 是本地开发/测试面，无平台社交图谱（好友/群/频道），
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
@@ -46,6 +71,7 @@ export class SandboxWsEndpoint {
     #logger;
     #options;
     #connections = new Map();
+    #readiness = createSandboxReadinessGate(probeShellIsolation);
     #wsHandleRelease;
     #wsPathRelease;
     #wsPath = '/sandbox';
@@ -105,7 +131,7 @@ export class SandboxWsEndpoint {
     }
     send({ conversation, payload }) {
         if (!this.#open)
-            return undefined;
+            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)
@@ -115,14 +141,14 @@ export class SandboxWsEndpoint {
                 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, {
@@ -137,7 +163,7 @@ export class SandboxWsEndpoint {
             channelType: conversation.kind,
             channelId: conversation.id,
         }));
-        return payload;
+        return randomUUID();
     }
     /** Prefer a real (non-placeholder) socket when reply target key is wrong/stale. */
     #findLiveConnection() {
@@ -152,6 +178,7 @@ export class SandboxWsEndpoint {
             ? `sandbox-${randomUUID().slice(0, 8)}`
             : this.#options.defaults.id;
         const owner = this.#options.defaults.owner;
+        const canExecute = connection.authScope === 'full';
         const socket = connection.socket;
         // Fixed-name mode reuses `target`; dropping the prior entry without
         // closing its socket leaves a zombie browser tab that still looks
@@ -171,26 +198,37 @@ export class SandboxWsEndpoint {
         }
         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,
@@ -199,6 +237,7 @@ export class SandboxWsEndpoint {
                         elements: parsed.content,
                         timestamp: parsed.timestamp,
                         ...(parsed.action ? { action: parsed.action } : {}),
+                        ...(parsed.agentRun ? { sandboxAgentRun: parsed.agentRun } : {}),
                     }),
                 }).catch((err) => {
                     this.#logger.warn(formatCompact({
@@ -227,25 +266,31 @@ export class SandboxWsEndpoint {
         });
         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, owner) {
         if (this.#connections.has(name))
@@ -259,3 +304,32 @@ export class SandboxWsEndpoint {
         });
     }
 }
+function probeShellIsolation() {
+    return new Promise((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',
+        message: 'Docker is unavailable',
+    }));
+}

package/lib/protocol.d.ts

@@ -1,5 +1,6 @@
 /** Sandbox WebSocket wire protocol helpers (no legacy Adapter/Endpoint). */
 import type { ConversationRef } from '@zhin.js/im-contract';
+import { type SandboxAgentRunConfig } from './run-config.js';
 export type MessageType = 'private' | 'group' | 'guild' | 'direct' | 'channel';
 export interface MessageElement {
     readonly type: string;
@@ -40,6 +41,7 @@ export declare function bindSandboxWsSocket(ws: SandboxWsSocket, handlers: {
 export declare function parseSandboxWsPayload(raw: string): {
     type: MessageType;
     id: string;
+    messageId?: string;
     content: MessageElement[];
     timestamp: number;
     text: string;
@@ -47,6 +49,7 @@ export declare function parseSandboxWsPayload(raw: string): {
         id: string;
         payload: string;
     };
+    agentRun?: SandboxAgentRunConfig;
 };
 /**
  * 入站归一化 → ConversationRef。sandbox 无平台社交图谱：

package/lib/protocol.js

@@ -2,6 +2,7 @@
 import { readFileSync } from 'node:fs';
 import { isMediaRef } from '@zhin.js/core';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { normalizeSandboxAgentRunConfig, } from './run-config.js';
 const logger = getLogger('sandbox');
 export function resolveSandboxEndpoint(appConfig) {
     const entry = appConfig.endpoints?.find((item) => item.context === 'sandbox');
@@ -19,7 +20,10 @@ export function resolveSandboxEndpoint(appConfig) {
         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,
     };
 }
 export function bindSandboxWsSocket(ws, handlers) {
@@ -105,7 +109,19 @@ export function parseSandboxWsPayload(raw) {
             ? 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 } : {}),
+    };
 }
 /**
  * 入站归一化 → ConversationRef。sandbox 无平台社交图谱：

package/lib/run-config.d.ts

@@ -0,0 +1,10 @@
+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 declare const DEFAULT_SANDBOX_AGENT_RUN_CONFIG: SandboxAgentRunConfig;
+export declare function normalizeSandboxAgentRunConfig(value: unknown): SandboxAgentRunConfig | undefined;

package/lib/run-config.js

@@ -0,0 +1,30 @@
+export const DEFAULT_SANDBOX_AGENT_RUN_CONFIG = Object.freeze({
+    workingDirectory: '',
+    safetyMode: 'workspace-write',
+    approvalMode: 'ask',
+    networkAccess: false,
+});
+const SAFETY_MODES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
+const APPROVAL_MODES = new Set(['ask', 'deny', 'allow']);
+export function normalizeSandboxAgentRunConfig(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const input = value;
+    const workingDirectory = typeof input.workingDirectory === 'string'
+        ? input.workingDirectory.trim().slice(0, 4096)
+        : '';
+    const safetyMode = SAFETY_MODES.has(input.safetyMode)
+        ? input.safetyMode
+        : DEFAULT_SANDBOX_AGENT_RUN_CONFIG.safetyMode;
+    const approvalMode = APPROVAL_MODES.has(input.approvalMode)
+        ? input.approvalMode
+        : 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,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-sandbox",
-  "version": "7.0.12",
+  "version": "7.0.15",
   "description": "Zhin.js Sandbox adapter for Plugin Runtime (WebSocket /sandbox)",
   "type": "module",
   "main": "./lib/index.js",
@@ -48,14 +48,14 @@
   "dependencies": {
     "lucide-react": "^0.525.0",
     "react": "^19.2.8",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/client": "2.1.9",
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/client": "2.1.10",
     "@zhin.js/console-contract": "1.0.1",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76",
-    "@zhin.js/page": "1.0.11"
+    "@zhin.js/page": "1.0.12"
   },
   "devDependencies": {
     "@types/react": "^19.2.18",
@@ -63,19 +63,19 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "ws": "^8.21.1",
-    "@zhin.js/pagemanager": "2.0.18",
-    "@zhin.js/runtime": "1.0.12",
-    "zhin.js": "6.0.11"
+    "@zhin.js/pagemanager": "2.0.19",
+    "@zhin.js/runtime": "1.0.13",
+    "zhin.js": "6.0.12"
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/client": "2.1.9",
+    "@zhin.js/adapter": "1.1.11",
+    "@zhin.js/client": "2.1.10",
     "@zhin.js/console-contract": "1.0.1",
-    "@zhin.js/core": "1.5.11",
-    "@zhin.js/host-http": "1.0.10",
-    "@zhin.js/page": "1.0.11",
-    "zhin.js": "6.0.11"
+    "@zhin.js/core": "1.5.12",
+    "@zhin.js/host-http": "1.0.11",
+    "@zhin.js/page": "1.0.12",
+    "zhin.js": "6.0.12"
   },
   "peerDependenciesMeta": {
     "react": {

package/pages/RichTextEditor.js

@@ -10,14 +10,22 @@ const RichTextEditor = forwardRef(({ placeholder = '输入消息...', onSend, on
             return { text: '', segments: [] };
         let text = '';
         const segments = [];
-        const nodes = Array.from(editorRef.current.childNodes);
-        for (const node of nodes) {
+        const appendText = (value) => {
+            if (!value)
+                return;
+            text += value;
+            const previous = segments.at(-1);
+            if (previous?.type === 'text') {
+                previous.data.text = String(previous.data.text ?? '') + value;
+            }
+            else {
+                segments.push({ type: 'text', data: { text: value } });
+            }
+        };
+        const visit = (node) => {
             if (node.nodeType === Node.TEXT_NODE) {
                 const textContent = node.textContent || '';
-                if (textContent) {
-                    text += textContent;
-                    segments.push({ type: 'text', data: { text: textContent } });
-                }
+                appendText(textContent);
             }
             else if (node.nodeType === Node.ELEMENT_NODE) {
                 const el = node;
@@ -51,10 +59,17 @@ const RichTextEditor = forwardRef(({ placeholder = '输入消息...', onSend, on
                     });
                 }
                 else if (el.tagName === 'BR') {
-                    text += '\n';
+                    appendText('\n');
+                }
+                else {
+                    const isBlock = el.tagName === 'DIV' || el.tagName === 'P';
+                    if (isBlock && text && !text.endsWith('\n'))
+                        appendText('\n');
+                    Array.from(el.childNodes).forEach(visit);
                 }
             }
-        }
+        };
+        Array.from(editorRef.current.childNodes).forEach(visit);
         return { text, segments };
     };
     // 插入表情

package/pages/RichTextEditor.tsx

@@ -37,15 +37,22 @@ const RichTextEditor = forwardRef<RichTextEditorRef, RichTextEditorProps>(
 
             let text = ''
             const segments: MessageSegment[] = []
-            const nodes = Array.from(editorRef.current.childNodes)
 
-            for (const node of nodes) {
+            const appendText = (value: string) => {
+                if (!value) return
+                text += value
+                const previous = segments.at(-1)
+                if (previous?.type === 'text') {
+                    previous.data.text = String(previous.data.text ?? '') + value
+                } else {
+                    segments.push({ type: 'text', data: { text: value } })
+                }
+            }
+
+            const visit = (node: Node) => {
                 if (node.nodeType === Node.TEXT_NODE) {
                     const textContent = node.textContent || ''
-                    if (textContent) {
-                        text += textContent
-                        segments.push({ type: 'text', data: { text: textContent } })
-                    }
+                    appendText(textContent)
                 } else if (node.nodeType === Node.ELEMENT_NODE) {
                     const el = node as HTMLElement
 
@@ -74,11 +81,17 @@ const RichTextEditor = forwardRef<RichTextEditorRef, RichTextEditorProps>(
                             data: id ? { target: id, name } : { target: name, name },
                         })
                     } else if (el.tagName === 'BR') {
-                        text += '\n'
+                        appendText('\n')
+                    } else {
+                        const isBlock = el.tagName === 'DIV' || el.tagName === 'P'
+                        if (isBlock && text && !text.endsWith('\n')) appendText('\n')
+                        Array.from(el.childNodes).forEach(visit)
                     }
                 }
             }
 
+            Array.from(editorRef.current.childNodes).forEach(visit)
+
             return { text, segments }
         }
 
@@ -426,4 +439,3 @@ const RichTextEditor = forwardRef<RichTextEditorRef, RichTextEditorProps>(
 RichTextEditor.displayName = 'RichTextEditor'
 
 export default RichTextEditor
-