wave-agent-sdk 1.1.5 → 1.3.0

package/dist/stdio/stdioAgent.d.ts

@@ -0,0 +1,229 @@
+/**
+ * StdioAgent — host-side typed wrapper around a JSON-RPC client that mirrors
+ * the Agent API (shared by the VS Code extension and the desktop app).
+ *
+ * In the single-shared-process architecture, all sessions share one transport
+ * client. The NotificationRouter dispatches incoming notifications to the
+ * appropriate StdioAgent via `handleNotification()`. The agent no longer
+ * subscribes directly to the client.
+ *
+ * All session-scoped requests carry `this.sessionId` on the JSON-RPC envelope
+ * so the server can route them to the right Agent.
+ *
+ * `destroy()` only unregisters from the router and sends the destroy request;
+ * it does NOT dispose the shared client.
+ *
+ * The client dependency is the structural `RpcClient` surface (request/notify/
+ * onNotification) so both hosts keep their own transports: vscode's
+ * `StdioClient` (spawn + hostLog) and desktop's `JsonRpcClient` subclasses
+ * (StdioClient / SocketClient).
+ */
+import type { Message, Task, BackgroundTaskSummary, SerializableWorkflowRun, QueuedMessage, McpServerStatus, PermissionMode, PermissionDecision, ToolPermissionContext, ToolBlockUpdateCallbackParams, SlashCommand, McpServerConfig, SubagentConfiguration, SkillMetadata } from "../types/index.js";
+import type { RpcClient } from "./rpcClient.js";
+import type { NotificationRouter } from "./notificationRouter.js";
+export interface InitializeParams {
+    workdir?: string;
+    restoreSessionId?: string;
+    apiKey?: string;
+    baseURL?: string;
+    serverUrl?: string;
+    defaultHeaders?: Record<string, string>;
+    model?: string;
+    fastModel?: string;
+    permissionMode?: PermissionMode;
+    tools?: string[];
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    pluginDirs?: string[];
+    mcpServers?: Record<string, McpServerConfig>;
+    worktreeName?: string;
+    isNewWorktree?: boolean;
+}
+export interface InitializeResult {
+    sessionId: string;
+    workingDirectory: string;
+    permissionMode: PermissionMode;
+    latestTotalTokens: number;
+}
+/**
+ * Session-level overrides only. 用户偏好（语言 / 上下文长度 / 自动记忆开关与频率）
+ * **不得**经本层下发——它们写用户级 `~/.wave/settings.json` 并由实时重载生效；
+ * 覆盖层优先级高于 settings.json，会把实时值永久遮蔽（docs/specs/core/agent-config.md
+ * 「分层职责」）。
+ */
+export interface UpdateConfigParams {
+    apiKey?: string;
+    baseURL?: string;
+    serverUrl?: string;
+    defaultHeaders?: Record<string, string>;
+    model?: string;
+    fastModel?: string;
+}
+export interface StdioAgentCallbacks {
+    onUserMessageAdded?: (message: Message) => void;
+    onAssistantMessageAdded?: (message: Message) => void;
+    onAssistantContentUpdated?: (params: {
+        messageId: string;
+        chunk: string;
+        stage: "streaming" | "end";
+    }) => void;
+    onAssistantReasoningUpdated?: (params: {
+        messageId: string;
+        chunk: string;
+        stage: "streaming" | "end";
+    }) => void;
+    onToolBlockUpdated?: (params: ToolBlockUpdateCallbackParams) => void;
+    onErrorBlockAdded?: (error: string) => void;
+    onCompactBlockAdded?: (content: string) => void;
+    onCompactionStateChange?: (isCompacting: boolean) => void;
+    onCompactionContentUpdate?: (content: string) => void;
+    /** Full plan-file content after the model writes it (spec: 计划文件更新后刷新计划面板). */
+    onPlanFileUpdated?: (content: string) => void;
+    onLoadingChange?: (loading: boolean) => void;
+    onContextUsage?: (percent: number) => void;
+    onCommandRunningChange?: (running: boolean) => void;
+    onQueuedMessagesChange?: (messages: QueuedMessage[]) => void;
+    onTasksChange?: (tasks: Task[]) => void;
+    onBackgroundTasksChange?: (tasks: BackgroundTaskSummary[]) => void;
+    onSessionIdChange?: (sessionId: string) => void;
+    onPermissionModeChange?: (mode: PermissionMode) => void;
+    onMcpServersChange?: (servers: McpServerStatus[]) => void;
+    onWorkdirChange?: (workdir: string) => void;
+    onNotificationMessageAdded?: (params: {
+        taskId: string;
+        taskType: string;
+        status: string;
+        summary: string;
+        message?: Message;
+    }) => void;
+    onPermissionRequest?: (requestId: string, context: ToolPermissionContext) => void;
+    onBtwContent?: (params: {
+        question: string;
+        content: string;
+        type: "thinking" | "content";
+    }) => void;
+}
+export declare class StdioAgent {
+    sessionId: string | undefined;
+    workingDirectory: string | undefined;
+    /**
+     * Initialize-time cwd — the session's stable root. Unlike
+     * `workingDirectory` it is never overwritten by the workdirChange
+     * notification (bash cd), so @file search and the /status workdir stay
+     * anchored to the project root.
+     */
+    sessionCwd: string | undefined;
+    latestTotalTokens: number;
+    /**
+     * Context-usage percentage reported with the most recent getMessages pull.
+     * A host whose webview was re-created long after the last token change gets
+     * no contextUsage notification, so it replays this on webviewReady instead.
+     */
+    contextUsagePercent: number | undefined;
+    permissionMode: PermissionMode | undefined;
+    messages: Message[];
+    queuedMessages: QueuedMessage[];
+    tasks: Task[];
+    backgroundTasks: BackgroundTaskSummary[];
+    isStreaming: boolean;
+    isCommandRunning: boolean;
+    isCompacting: boolean;
+    private client;
+    private router;
+    private callbacks;
+    constructor(client: RpcClient, router: NotificationRouter, callbacks: StdioAgentCallbacks);
+    initialize(params: InitializeParams): Promise<InitializeResult>;
+    destroy(): Promise<void>;
+    restoreSession(sessionId: string): Promise<void>;
+    /**
+     * Set this session's custom title (spec session-management.md「会话自定义标题
+     * （重命名）」). The title is appended to the session's own JSONL file as a
+     * reserved `custom-title` entry, so every host reading that file sees it.
+     */
+    renameSession(title: string): Promise<void>;
+    updateConfig(params: UpdateConfigParams): Promise<{
+        sessionId: string;
+    }>;
+    sendMessage(text: string, images?: Array<{
+        path: string;
+        mimeType: string;
+    }>, force?: boolean): Promise<void>;
+    bang(command: string): Promise<void>;
+    abortMessage(): Promise<void>;
+    clearMessages(): Promise<void>;
+    compact(customInstructions?: string): Promise<void>;
+    rewindToMessage(messageId: string): Promise<{
+        inputContent: string;
+    }>;
+    askBtw(question: string): Promise<string>;
+    removeQueuedMessage(index: number): Promise<void>;
+    updateQueuedMessageById(id: string, patch: {
+        content?: string;
+        images?: Array<{
+            path: string;
+            mimeType: string;
+        }>;
+        type?: "message" | "bang";
+    }): Promise<boolean>;
+    removeQueuedMessageById(id: string): Promise<void>;
+    getFullMessageThread(): Promise<{
+        messages: Message[];
+        sessionIds: string[];
+    }>;
+    getMessages(): Promise<Message[]>;
+    listRewindCheckpoints(): Promise<{
+        checkpoints: Array<{
+            id: string;
+            content: string;
+        }>;
+    }>;
+    getConfiguredModels(): Promise<{
+        models: string[];
+        currentModel: string | undefined;
+    }>;
+    setModel(model: string): Promise<void>;
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    /** Returns cached permission mode (updated via notification). */
+    getPermissionMode(): PermissionMode | undefined;
+    /**
+     * Reads the session's current plan file (path + contents). Used by the
+     * /plan command to display the plan when already in plan mode; the CLI side
+     * awaits the path if it is still being generated after setPermissionMode.
+     */
+    getPlanFile(): Promise<{
+        path: string | null;
+        content: string | null;
+    }>;
+    sendPermissionResponse(requestId: string, decision: PermissionDecision): void;
+    getBackgroundTaskOutput(taskId: string): Promise<{
+        stdout: string;
+        stderr: string;
+        status: string;
+        outputPath?: string;
+        type: string;
+        exitCode?: number;
+    } | null>;
+    stopBackgroundTask(taskId: string): Promise<boolean>;
+    backgroundCurrentTask(): Promise<void>;
+    getWorkflowRuns(): Promise<SerializableWorkflowRun[]>;
+    stopWorkflowRun(runId: string): Promise<boolean>;
+    getMcpServers(): Promise<McpServerStatus[]>;
+    connectMcpServer(serverName: string): Promise<boolean>;
+    disconnectMcpServer(serverName: string): Promise<boolean>;
+    getMcpConfigPaths(): Promise<{
+        userPath: string | null;
+        projectPath: string | null;
+    }>;
+    removeMcpServer(scope: "user" | "project", serverName: string): Promise<boolean>;
+    deleteSkill(name: string): Promise<boolean>;
+    deleteSubagent(name: string): Promise<boolean>;
+    getHooksByScope(scope: "user" | "project" | "plugin"): Promise<{
+        hooks: Partial<Record<string, unknown[]>>;
+        configPath: string | null;
+    }>;
+    deleteHook(scope: "user" | "project", hookName: string): Promise<void>;
+    getSlashCommands(): Promise<SlashCommand[]>;
+    getSubagentConfigurations(): Promise<SubagentConfiguration[]>;
+    getSkillMetadata(): Promise<SkillMetadata[]>;
+    handleNotification(method: string, params: unknown): void;
+}

package/dist/stdio/stdioAgent.js

@@ -0,0 +1,360 @@
+/**
+ * StdioAgent — host-side typed wrapper around a JSON-RPC client that mirrors
+ * the Agent API (shared by the VS Code extension and the desktop app).
+ *
+ * In the single-shared-process architecture, all sessions share one transport
+ * client. The NotificationRouter dispatches incoming notifications to the
+ * appropriate StdioAgent via `handleNotification()`. The agent no longer
+ * subscribes directly to the client.
+ *
+ * All session-scoped requests carry `this.sessionId` on the JSON-RPC envelope
+ * so the server can route them to the right Agent.
+ *
+ * `destroy()` only unregisters from the router and sends the destroy request;
+ * it does NOT dispose the shared client.
+ *
+ * The client dependency is the structural `RpcClient` surface (request/notify/
+ * onNotification) so both hosts keep their own transports: vscode's
+ * `StdioClient` (spawn + hostLog) and desktop's `JsonRpcClient` subclasses
+ * (StdioClient / SocketClient).
+ */
+// ── StdioAgent ───────────────────────────────────────────────────
+export class StdioAgent {
+    constructor(client, router, callbacks) {
+        this.latestTotalTokens = 0;
+        this.messages = [];
+        this.queuedMessages = [];
+        this.tasks = [];
+        this.backgroundTasks = [];
+        this.isStreaming = false;
+        this.isCommandRunning = false;
+        this.isCompacting = false;
+        this.client = client;
+        this.router = router;
+        this.callbacks = callbacks;
+    }
+    // ── Lifecycle ─────────────────────────────────────────────────
+    async initialize(params) {
+        const result = (await this.client.request("initialize", params));
+        this.sessionId = result.sessionId;
+        this.workingDirectory = result.workingDirectory;
+        this.sessionCwd = result.workingDirectory;
+        this.permissionMode = result.permissionMode;
+        this.latestTotalTokens = result.latestTotalTokens;
+        // A fresh session has no usage yet; don't let a previous session's
+        // percentage survive into this agent.
+        this.contextUsagePercent = undefined;
+        // Register with the router so subsequent notifications are routed here
+        this.router.register(this.sessionId, this);
+        return result;
+    }
+    async destroy() {
+        if (this.sessionId) {
+            this.router.unregister(this.sessionId);
+        }
+        try {
+            await this.client.request("destroy", undefined, this.sessionId);
+        }
+        catch {
+            // Process may have already exited; best-effort
+        }
+        // NOTE: do NOT dispose the shared client — other sessions may still use it
+    }
+    async restoreSession(sessionId) {
+        await this.client.request("restoreSession", { sessionId }, this.sessionId);
+    }
+    /**
+     * Set this session's custom title (spec session-management.md「会话自定义标题
+     * （重命名）」). The title is appended to the session's own JSONL file as a
+     * reserved `custom-title` entry, so every host reading that file sees it.
+     */
+    async renameSession(title) {
+        await this.client.request("renameSession", {
+            sessionId: this.sessionId,
+            // The session file lives under the session root; a cwd drifted by `cd`
+            // inside a turn must not address it (see sessionCwd).
+            workdir: this.sessionCwd ?? this.workingDirectory,
+            title,
+        }, this.sessionId);
+    }
+    async updateConfig(params) {
+        const oldSessionId = this.sessionId;
+        const result = (await this.client.request("updateConfig", params, this.sessionId));
+        // If sessionId changed, re-register with the router
+        if (oldSessionId && result.sessionId !== oldSessionId) {
+            this.router.unregister(oldSessionId);
+            this.sessionId = result.sessionId;
+            this.router.register(this.sessionId, this);
+            // Sync the host session state: the bridge may have downgraded to a
+            // fresh session (session file missing on recreate). Without this the
+            // host keeps the destroyed sessionId and every later request fails
+            // with "Session not found".
+            this.callbacks.onSessionIdChange?.(this.sessionId);
+        }
+        return result;
+    }
+    // ── Messages ──────────────────────────────────────────────────
+    async sendMessage(text, images, force) {
+        await this.client.request("sendMessage", { text, images, force }, this.sessionId);
+    }
+    async bang(command) {
+        await this.client.request("bang", { command }, this.sessionId);
+    }
+    async abortMessage() {
+        await this.client.request("abortMessage", undefined, this.sessionId);
+    }
+    async clearMessages() {
+        await this.client.request("clearMessages", undefined, this.sessionId);
+    }
+    async compact(customInstructions) {
+        await this.client.request("compact", { customInstructions }, this.sessionId);
+    }
+    async rewindToMessage(messageId) {
+        return (await this.client.request("rewindToMessage", { messageId }, this.sessionId));
+    }
+    async askBtw(question) {
+        return (await this.client.request("askBtw", { question }, this.sessionId));
+    }
+    async removeQueuedMessage(index) {
+        await this.client.request("deleteQueuedMessage", { index }, this.sessionId);
+    }
+    async updateQueuedMessageById(id, patch) {
+        const result = (await this.client.request("updateQueuedMessage", { id, text: patch.content, images: patch.images }, this.sessionId));
+        return result?.ok ?? false;
+    }
+    async removeQueuedMessageById(id) {
+        await this.client.request("deleteQueuedMessageById", { id }, this.sessionId);
+    }
+    async getFullMessageThread() {
+        return (await this.client.request("getFullMessageThread", undefined, this.sessionId));
+    }
+    async getMessages() {
+        const result = (await this.client.request("getMessages", undefined, this.sessionId));
+        this.messages = result.messages;
+        this.contextUsagePercent = result.contextUsagePercent;
+        return result.messages;
+    }
+    async listRewindCheckpoints() {
+        return (await this.client.request("listRewindCheckpoints", undefined, this.sessionId));
+    }
+    async getConfiguredModels() {
+        return (await this.client.request("getConfiguredModels", undefined, this.sessionId));
+    }
+    async setModel(model) {
+        await this.client.request("setModel", { model }, this.sessionId);
+    }
+    // ── Permissions ───────────────────────────────────────────────
+    async setPermissionMode(mode) {
+        await this.client.request("setPermissionMode", { mode }, this.sessionId);
+    }
+    /** Returns cached permission mode (updated via notification). */
+    getPermissionMode() {
+        return this.permissionMode;
+    }
+    /**
+     * Reads the session's current plan file (path + contents). Used by the
+     * /plan command to display the plan when already in plan mode; the CLI side
+     * awaits the path if it is still being generated after setPermissionMode.
+     */
+    async getPlanFile() {
+        return (await this.client.request("getPlanFile", undefined, this.sessionId));
+    }
+    sendPermissionResponse(requestId, decision) {
+        this.client.notify("permissionResponse", { requestId, decision }, this.sessionId);
+    }
+    async getBackgroundTaskOutput(taskId) {
+        const result = (await this.client.request("getBackgroundTaskOutput", { taskId }, this.sessionId));
+        return result.output;
+    }
+    async stopBackgroundTask(taskId) {
+        const result = (await this.client.request("stopBackgroundTask", { taskId }, this.sessionId));
+        return result.success;
+    }
+    async backgroundCurrentTask() {
+        await this.client.request("backgroundCurrentTask", undefined, this.sessionId);
+    }
+    async getWorkflowRuns() {
+        const result = (await this.client.request("getWorkflowRuns", undefined, this.sessionId));
+        return result?.runs ?? [];
+    }
+    async stopWorkflowRun(runId) {
+        const result = (await this.client.request("stopWorkflowRun", { runId }, this.sessionId));
+        return result?.success ?? false;
+    }
+    // ── MCP ───────────────────────────────────────────────────────
+    async getMcpServers() {
+        const result = (await this.client.request("getMcpServers", undefined, this.sessionId));
+        return result.servers;
+    }
+    async connectMcpServer(serverName) {
+        const result = (await this.client.request("connectMcpServer", { serverName }, this.sessionId));
+        return result.success;
+    }
+    async disconnectMcpServer(serverName) {
+        const result = (await this.client.request("disconnectMcpServer", { serverName }, this.sessionId));
+        return result.success;
+    }
+    async getMcpConfigPaths() {
+        const result = (await this.client.request("getMcpConfigPaths", undefined, this.sessionId));
+        return result;
+    }
+    async removeMcpServer(scope, serverName) {
+        const result = (await this.client.request("removeMcpServer", { scope, serverName }, this.sessionId));
+        return result.success;
+    }
+    async deleteSkill(name) {
+        const result = (await this.client.request("deleteSkill", { name }, this.sessionId));
+        return result.success;
+    }
+    async deleteSubagent(name) {
+        const result = (await this.client.request("deleteSubagent", { name }, this.sessionId));
+        return result.success;
+    }
+    async getHooksByScope(scope) {
+        const result = (await this.client.request("getHooksByScope", { scope }, this.sessionId));
+        return result;
+    }
+    async deleteHook(scope, hookName) {
+        await this.client.request("deleteHook", { scope, hookName }, this.sessionId);
+    }
+    // ── Commands ──────────────────────────────────────────────────
+    async getSlashCommands() {
+        const result = (await this.client.request("getSlashCommands", undefined, this.sessionId));
+        return result.commands;
+    }
+    async getSubagentConfigurations() {
+        const result = (await this.client.request("getSubagentConfigurations", undefined, this.sessionId));
+        return result.configurations;
+    }
+    async getSkillMetadata() {
+        const result = (await this.client.request("getSkillMetadata", undefined, this.sessionId));
+        return result.skills;
+    }
+    // ── Notification dispatch (called by NotificationRouter) ──────
+    handleNotification(method, params) {
+        switch (method) {
+            case "userMessageAdded": {
+                const p = params;
+                if (p.message)
+                    this.callbacks.onUserMessageAdded?.(p.message);
+                break;
+            }
+            case "assistantMessageAdded": {
+                const p = params;
+                if (p.message)
+                    this.callbacks.onAssistantMessageAdded?.(p.message);
+                break;
+            }
+            case "assistantContentUpdated":
+                this.callbacks.onAssistantContentUpdated?.(params);
+                break;
+            case "assistantReasoningUpdated":
+                this.callbacks.onAssistantReasoningUpdated?.(params);
+                break;
+            case "toolBlockUpdated":
+                this.callbacks.onToolBlockUpdated?.(params);
+                break;
+            case "errorBlockAdded": {
+                const p = params;
+                this.callbacks.onErrorBlockAdded?.(p.error);
+                break;
+            }
+            case "compactBlockAdded": {
+                const p = params;
+                this.callbacks.onCompactBlockAdded?.(p.content);
+                break;
+            }
+            case "compactionStateChange": {
+                const p = params;
+                this.isCompacting = p.isCompacting;
+                this.callbacks.onCompactionStateChange?.(p.isCompacting);
+                break;
+            }
+            case "compactionContentUpdate": {
+                const p = params;
+                this.callbacks.onCompactionContentUpdate?.(p.content);
+                break;
+            }
+            case "planFileUpdated": {
+                const p = params;
+                this.callbacks.onPlanFileUpdated?.(p.content);
+                break;
+            }
+            case "loadingChange": {
+                const p = params;
+                if (p.latestTotalTokens !== undefined) {
+                    this.latestTotalTokens = p.latestTotalTokens;
+                }
+                this.isStreaming = p.loading;
+                this.callbacks.onLoadingChange?.(p.loading);
+                break;
+            }
+            case "contextUsage": {
+                const p = params;
+                this.callbacks.onContextUsage?.(p.percent);
+                break;
+            }
+            case "commandRunningChange": {
+                const p = params;
+                this.isCommandRunning = p.running;
+                this.callbacks.onCommandRunningChange?.(p.running);
+                break;
+            }
+            case "queuedMessagesChange": {
+                const p = params;
+                this.queuedMessages = p.messages;
+                this.callbacks.onQueuedMessagesChange?.(p.messages);
+                break;
+            }
+            case "tasksChange": {
+                const p = params;
+                this.tasks = p.tasks;
+                this.callbacks.onTasksChange?.(p.tasks);
+                break;
+            }
+            case "backgroundTasksChange": {
+                const p = params;
+                this.backgroundTasks = p.tasks;
+                this.callbacks.onBackgroundTasksChange?.(p.tasks);
+                break;
+            }
+            case "sessionIdChange": {
+                const p = params;
+                this.sessionId = p.sessionId;
+                this.callbacks.onSessionIdChange?.(p.sessionId);
+                break;
+            }
+            case "permissionModeChange": {
+                const p = params;
+                this.permissionMode = p.mode;
+                this.callbacks.onPermissionModeChange?.(p.mode);
+                break;
+            }
+            case "mcpServersChange": {
+                const p = params;
+                this.callbacks.onMcpServersChange?.(p.servers);
+                break;
+            }
+            case "workdirChange": {
+                const p = params;
+                this.workingDirectory = p.workdir;
+                this.callbacks.onWorkdirChange?.(p.workdir);
+                break;
+            }
+            case "notificationMessageAdded":
+                this.callbacks.onNotificationMessageAdded?.(params);
+                break;
+            case "permissionRequest": {
+                const p = params;
+                this.callbacks.onPermissionRequest?.(p.requestId, p.context);
+                break;
+            }
+            case "btwContent": {
+                const p = params;
+                if (p)
+                    this.callbacks.onBtwContent?.(p);
+                break;
+            }
+        }
+    }
+}