@co0ontty/wand 0.2.0 → 0.3.0

package/README.md

@@ -1,13 +1,33 @@
 # wand
 
-wand 是一个通过浏览器访问的本地终端工具，支持 Claude 等命令行工具。
+通过浏览器访问本地终端，支持 Claude 等命令行工具。
 
-A browser-accessible local terminal for running CLI tools like Claude.
+## 功能
 
-## 启动 / Start
+- Web 终端 / Chat 模式双视图
+- 会话持久化与恢复
+- Claude Code 集成
+- 文件浏览器
+- HTTPS 安全连接
+
+## 快速开始
 
 ```bash
-npm install @co0ontty/wand && node dist/cli.js init && node dist/cli.js web
+npm install -g @co0ontty/wand
+wand init
+wand web
 ```
 
-配置文件 / Config: `~/.wand/config.json`
+配置文件：`~/.wand/config.json`
+
+## 开发
+
+```bash
+npm install
+npm run build
+npm run dev
+```
+
+## License
+
+MIT

package/dist/acp-protocol.d.ts

@@ -0,0 +1,67 @@
+/**
+ * ACP (Agent Communication Protocol) implementation
+ * Inspired by Happy's unified agent communication format
+ */
+import type { ACPMessage, ACPTextMessage, ACPReasoningMessage, ACPToolCallMessage, ACPToolResultMessage, ACPFileEditMessage, ACPTerminalOutputMessage, ACPPermissionRequestMessage, ACPSessionStartMessage, ACPSessionEndMessage, ACPErrorMessage, ConversationTurn } from "./types.js";
+/**
+ * Create a text message
+ */
+export declare function createTextMessage(sessionId: string, role: "user" | "assistant" | "system", content: string): ACPTextMessage;
+/**
+ * Create a reasoning message
+ */
+export declare function createReasoningMessage(sessionId: string, content: string, isStreaming?: boolean): ACPReasoningMessage;
+/**
+ * Create a tool call message
+ */
+export declare function createToolCallMessage(sessionId: string, toolCallId: string, name: string, input: Record<string, unknown>, description?: string): ACPToolCallMessage;
+/**
+ * Create a tool result message
+ */
+export declare function createToolResultMessage(sessionId: string, toolCallId: string, output: string | Array<{
+    type: string;
+    [key: string]: unknown;
+}>, isError?: boolean): ACPToolResultMessage;
+/**
+ * Create a file edit message
+ */
+export declare function createFileEditMessage(sessionId: string, filePath: string, description: string, options?: {
+    oldContent?: string;
+    newContent?: string;
+    diff?: string;
+}): ACPFileEditMessage;
+/**
+ * Create a terminal output message
+ */
+export declare function createTerminalOutputMessage(sessionId: string, data: string, toolCallId?: string): ACPTerminalOutputMessage;
+/**
+ * Create a permission request message
+ */
+export declare function createPermissionRequestMessage(sessionId: string, permissionId: string, toolName: string, description: string): ACPPermissionRequestMessage;
+/**
+ * Create a session start message
+ */
+export declare function createSessionStartMessage(sessionId: string, workingDirectory: string, agent?: string): ACPSessionStartMessage;
+/**
+ * Create a session end message
+ */
+export declare function createSessionEndMessage(sessionId: string, exitCode: number | null): ACPSessionEndMessage;
+/**
+ * Create an error message
+ */
+export declare function createErrorMessage(sessionId: string, error: string, details?: string): ACPErrorMessage;
+/**
+ * Convert ConversationTurn to ACP messages
+ */
+export declare function conversationTurnToACP(sessionId: string, turn: ConversationTurn): ACPMessage[];
+/**
+ * Convert ACP messages to ConversationTurn
+ */
+export declare function acpToConversationTurns(messages: ACPMessage[]): ConversationTurn[];
+/**
+ * Parse Claude stream-json event to ACP message
+ */
+export declare function parseClaudeStreamEvent(sessionId: string, event: {
+    type?: string;
+    [key: string]: unknown;
+}): ACPMessage | null;

package/dist/acp-protocol.js

@@ -0,0 +1,291 @@
+/**
+ * ACP (Agent Communication Protocol) implementation
+ * Inspired by Happy's unified agent communication format
+ */
+/**
+ * Generate a unique message ID
+ */
+function generateId() {
+    return `acp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+}
+/**
+ * Create a text message
+ */
+export function createTextMessage(sessionId, role, content) {
+    return {
+        id: generateId(),
+        type: "message",
+        timestamp: Date.now(),
+        sessionId,
+        role,
+        content,
+    };
+}
+/**
+ * Create a reasoning message
+ */
+export function createReasoningMessage(sessionId, content, isStreaming = false) {
+    return {
+        id: generateId(),
+        type: "reasoning",
+        timestamp: Date.now(),
+        sessionId,
+        content,
+        isStreaming,
+    };
+}
+/**
+ * Create a tool call message
+ */
+export function createToolCallMessage(sessionId, toolCallId, name, input, description) {
+    return {
+        id: generateId(),
+        type: "tool-call",
+        timestamp: Date.now(),
+        sessionId,
+        toolCallId,
+        name,
+        input,
+        description,
+    };
+}
+/**
+ * Create a tool result message
+ */
+export function createToolResultMessage(sessionId, toolCallId, output, isError = false) {
+    return {
+        id: generateId(),
+        type: "tool-result",
+        timestamp: Date.now(),
+        sessionId,
+        toolCallId,
+        output,
+        isError,
+    };
+}
+/**
+ * Create a file edit message
+ */
+export function createFileEditMessage(sessionId, filePath, description, options = {}) {
+    return {
+        id: generateId(),
+        type: "file-edit",
+        timestamp: Date.now(),
+        sessionId,
+        filePath,
+        description,
+        ...options,
+    };
+}
+/**
+ * Create a terminal output message
+ */
+export function createTerminalOutputMessage(sessionId, data, toolCallId) {
+    return {
+        id: generateId(),
+        type: "terminal-output",
+        timestamp: Date.now(),
+        sessionId,
+        data,
+        toolCallId,
+    };
+}
+/**
+ * Create a permission request message
+ */
+export function createPermissionRequestMessage(sessionId, permissionId, toolName, description) {
+    return {
+        id: generateId(),
+        type: "permission-request",
+        timestamp: Date.now(),
+        sessionId,
+        permissionId,
+        toolName,
+        description,
+    };
+}
+/**
+ * Create a session start message
+ */
+export function createSessionStartMessage(sessionId, workingDirectory, agent) {
+    return {
+        id: generateId(),
+        type: "session-start",
+        timestamp: Date.now(),
+        sessionId,
+        workingDirectory,
+        agent,
+    };
+}
+/**
+ * Create a session end message
+ */
+export function createSessionEndMessage(sessionId, exitCode) {
+    return {
+        id: generateId(),
+        type: "session-end",
+        timestamp: Date.now(),
+        sessionId,
+        exitCode,
+    };
+}
+/**
+ * Create an error message
+ */
+export function createErrorMessage(sessionId, error, details) {
+    return {
+        id: generateId(),
+        type: "error",
+        timestamp: Date.now(),
+        sessionId,
+        error,
+        details,
+    };
+}
+/**
+ * Convert ConversationTurn to ACP messages
+ */
+export function conversationTurnToACP(sessionId, turn) {
+    const messages = [];
+    for (const block of turn.content) {
+        switch (block.type) {
+            case "text":
+                messages.push(createTextMessage(sessionId, turn.role, block.text));
+                break;
+            case "thinking":
+                messages.push(createReasoningMessage(sessionId, block.thinking));
+                break;
+            case "tool_use":
+                messages.push(createToolCallMessage(sessionId, block.id, block.name, block.input, block.description));
+                break;
+            case "tool_result":
+                messages.push(createToolResultMessage(sessionId, block.tool_use_id, block.content, block.is_error ?? false));
+                break;
+        }
+    }
+    return messages;
+}
+/**
+ * Convert ACP messages to ConversationTurn
+ */
+export function acpToConversationTurns(messages) {
+    const turns = [];
+    let currentTurn = null;
+    for (const msg of messages) {
+        switch (msg.type) {
+            case "message":
+                if (msg.role === "user") {
+                    // Start a new user turn
+                    if (currentTurn) {
+                        turns.push(currentTurn);
+                    }
+                    currentTurn = {
+                        role: "user",
+                        content: [{ type: "text", text: msg.content }],
+                    };
+                }
+                else if (msg.role === "assistant") {
+                    if (currentTurn?.role === "assistant") {
+                        // Add to existing assistant turn
+                        currentTurn.content.push({ type: "text", text: msg.content });
+                    }
+                    else {
+                        // Start new assistant turn
+                        if (currentTurn) {
+                            turns.push(currentTurn);
+                        }
+                        currentTurn = {
+                            role: "assistant",
+                            content: [{ type: "text", text: msg.content }],
+                        };
+                    }
+                }
+                break;
+            case "reasoning":
+                if (currentTurn?.role === "assistant") {
+                    currentTurn.content.push({ type: "thinking", thinking: msg.content });
+                }
+                break;
+            case "tool-call":
+                if (currentTurn?.role === "assistant") {
+                    currentTurn.content.push({
+                        type: "tool_use",
+                        id: msg.toolCallId,
+                        name: msg.name,
+                        input: msg.input,
+                        description: msg.description,
+                    });
+                }
+                break;
+            case "tool-result":
+                if (currentTurn?.role === "assistant") {
+                    currentTurn.content.push({
+                        type: "tool_result",
+                        tool_use_id: msg.toolCallId,
+                        content: msg.output,
+                        is_error: msg.isError,
+                    });
+                }
+                break;
+        }
+    }
+    if (currentTurn) {
+        turns.push(currentTurn);
+    }
+    return turns;
+}
+/**
+ * Parse Claude stream-json event to ACP message
+ */
+export function parseClaudeStreamEvent(sessionId, event) {
+    switch (event.type) {
+        case "content_block_start": {
+            const block = event.content_block;
+            if (!block)
+                return null;
+            if (block.type === "text") {
+                return createTextMessage(sessionId, "assistant", "");
+            }
+            if (block.type === "thinking") {
+                return createReasoningMessage(sessionId, "", true);
+            }
+            if (block.type === "tool_use") {
+                return createToolCallMessage(sessionId, block.id ?? "", block.name ?? "", block.input ?? {});
+            }
+            return null;
+        }
+        case "content_block_delta": {
+            const delta = event.delta;
+            if (!delta)
+                return null;
+            if (delta.type === "text_delta" && delta.text) {
+                return createTextMessage(sessionId, "assistant", delta.text);
+            }
+            if (delta.type === "thinking_delta" && delta.thinking) {
+                return createReasoningMessage(sessionId, delta.thinking, true);
+            }
+            return null;
+        }
+        case "content_block_stop": {
+            // Block completed - could emit a completion event
+            return null;
+        }
+        case "message_start": {
+            const message = event.message;
+            if (message?.role === "assistant") {
+                return createTextMessage(sessionId, "assistant", "");
+            }
+            return null;
+        }
+        case "message_stop": {
+            // Message completed
+            return null;
+        }
+        case "error": {
+            const error = event.error;
+            return createErrorMessage(sessionId, error?.message ?? "Unknown error");
+        }
+        default:
+            return null;
+    }
+}

package/dist/claude-pty-bridge.d.ts

@@ -0,0 +1,139 @@
+/**
+ * ClaudePtyBridge - PTY output parsing and event bridge
+ *
+ * Transforms raw PTY output into structured events for WebSocket broadcast.
+ * Maintains two parallel output streams:
+ * 1. Raw output for terminal view (passthrough)
+ * 2. Structured messages for chat view (parsed)
+ */
+import { EventEmitter } from "node:events";
+import type { ApprovalPolicy, ConversationTurn, EscalationScope, TaskData } from "./types.js";
+interface PermissionState {
+    /** Rolling window for prompt detection */
+    window: string;
+    /** Currently blocked */
+    isBlocked: boolean;
+    /** Last detected prompt text */
+    lastPrompt: string | null;
+    /** Last detected scope */
+    lastScope: EscalationScope | null;
+    /** Last detected target */
+    lastTarget: string | null;
+    /** Timestamp of last auto-confirm to prevent rapid repeats */
+    lastAutoConfirmAt: number;
+}
+/** Permission resolution result */
+export type PermissionResolution = "approve_once" | "approve_turn" | "deny";
+export interface ClaudePtyBridgeOptions {
+    sessionId: string;
+    /** Initial messages from storage (for restart recovery) */
+    initialMessages?: ConversationTurn[];
+    /** Initial raw output from storage */
+    initialOutput?: string;
+    /** Whether this is a Claude CLI command (enables permission detection) */
+    isClaudeCommand?: boolean;
+    /** Whether to auto-approve permission prompts */
+    autoApprove?: boolean;
+    /** Approval policy for permission handling */
+    approvalPolicy?: ApprovalPolicy;
+    /** PTY write function for sending approval input */
+    ptyWrite?: (input: string) => void;
+}
+/**
+ * ClaudePtyBridge transforms raw PTY output into structured events.
+ *
+ * Events emitted:
+ * - "output.raw" - Raw PTY output for terminal view
+ * - "output.chat" - Structured chat content update
+ * - "chat.turn" - Conversation turn completed
+ * - "permission.prompt" - Permission request detected
+ * - "permission.resolved" - Permission resolved
+ * - "session.id" - Claude session ID captured
+ * - "task" - Task info update
+ * - "ended" - Session ended
+ */
+export declare class ClaudePtyBridge extends EventEmitter {
+    readonly sessionId: string;
+    private rawOutput;
+    private messages;
+    private chatState;
+    private permissionState;
+    private sessionIdWindow;
+    private claudeSessionId;
+    private currentTask;
+    private taskDebounceTimer;
+    private lastEmittedTask;
+    private isClaudeCommand;
+    private autoApprove;
+    private approvalPolicy;
+    private ptyWrite;
+    /** Set to true once onExit() has been called; guards against post-exit method calls */
+    private _exited;
+    private rememberedScopes;
+    private rememberedTargets;
+    constructor(options: ClaudePtyBridgeOptions);
+    /**
+     * Process a raw PTY chunk.
+     * Emits events via EventEmitter.
+     */
+    processChunk(chunk: string): void;
+    /**
+     * Called when user sends input.
+     * Starts tracking a new assistant response.
+     */
+    onUserInput(input: string): void;
+    /**
+     * Called when PTY process exits.
+     * Finalizes any pending response.
+     */
+    onExit(exitCode: number | null): void;
+    getMessages(): ConversationTurn[];
+    getRawOutput(): string;
+    getClaudeSessionId(): string | null;
+    isPermissionBlocked(): boolean;
+    getPermissionState(): PermissionState;
+    getCurrentTask(): TaskData | null;
+    /**
+     * Set the PTY write function for sending approval input.
+     */
+    setPtyWrite(fn: (input: string) => void): void;
+    /**
+     * Resolve the current permission prompt.
+     * @param resolution - How to resolve the permission
+     */
+    resolvePermission(resolution: PermissionResolution): void;
+    /**
+     * Check if a permission scope/target should be auto-approved based on remembered decisions.
+     */
+    shouldAutoApprove(scope: EscalationScope, target?: string): boolean;
+    /**
+     * Clear remembered permissions (call at the start of a new turn).
+     */
+    clearRememberedPermissions(): void;
+    /**
+     * Clear permission blocked state (called when permission is resolved externally).
+     */
+    clearPermissionBlocked(): void;
+    private emitEvent;
+    private isRealChatInput;
+    private captureSessionId;
+    private detectPermission;
+    private isPermissionPromptDetected;
+    private extractPromptText;
+    private extractPermissionTarget;
+    private inferScope;
+    private parseChatResponse;
+    private detectCompletion;
+    private updateAssistantContent;
+    private finalizeResponse;
+    private stripAnsi;
+    /**
+     * Find the end index of the echoed user input in the PTY buffer.
+     * The echo may contain ANSI codes between characters.
+     * Returns the index after the last character of the echo.
+     */
+    private findEchoEndIndex;
+    private isStatusLine;
+    private cleanForChat;
+}
+export {};