wave-code 0.19.9 → 1.0.1

package/dist/print-cli.js

@@ -1,4 +1,4 @@
-import { Agent, hasUncommittedChanges, hasNewCommits, getDefaultRemoteBranch, } from "wave-agent-sdk";
+import { Agent, hasUncommittedChanges, hasNewCommits, getDefaultRemoteBranch, validateWorktreeRemovalPath, } from "wave-agent-sdk";
 import { displayUsageSummary } from "./utils/usageSummary.js";
 import { removeWorktree } from "./utils/worktree.js";
 function displayTimingInfo(startTime, showStats) {
@@ -129,21 +129,35 @@ export async function startPrintCli(options) {
         }
         // Display timing information
         displayTimingInfo(startTime, showStats);
-        // Destroy agent and exit after sendMessage completes
-        await agent.destroy();
-        // Handle worktree cleanup for print mode
+        // Trigger WorktreeRemove hook (before destroy — it needs a live agent) and
+        // decide whether the worktree is clean enough to remove
+        let cleanWorktree = false;
         if (worktreeSession) {
             const cwd = workdir || worktreeSession.path;
             const baseBranch = getDefaultRemoteBranch(cwd);
             const hasChanges = hasUncommittedChanges(cwd);
             const hasCommits = hasNewCommits(cwd, baseBranch);
-            if (!hasChanges && !hasCommits) {
-                await removeWorktree(worktreeSession);
+            cleanWorktree = !hasChanges && !hasCommits;
+            if (cleanWorktree) {
+                await agent.triggerWorktreeRemoveHook(worktreeSession.path);
             }
             else {
                 process.stdout.write(`\n⚠️ Worktree '${worktreeSession.name}' has changes or commits. Keeping it at: ${worktreeSession.path}\n`);
             }
         }
+        // Destroy agent and exit after sendMessage completes
+        await agent.destroy();
+        // Handle worktree cleanup for print mode (git removal stays after destroy)
+        if (worktreeSession && cleanWorktree) {
+            try {
+                validateWorktreeRemovalPath(worktreeSession.path, worktreeSession.repoRoot);
+                await removeWorktree(worktreeSession);
+            }
+            catch (error) {
+                // Never block print-mode exit on worktree cleanup failures
+                process.stdout.write(`\n⚠️ Skipping worktree removal: ${error.message}\n`);
+            }
+        }
         process.exit(0);
     }
     catch (error) {
@@ -162,20 +176,32 @@ export async function startPrintCli(options) {
             }
             // Display timing information even on error
             displayTimingInfo(startTime, showStats);
-            await agent.destroy();
-            // Handle worktree cleanup for print mode even on error
+            // Trigger WorktreeRemove hook (before destroy) when the worktree is clean
+            let cleanWorktree = false;
             if (worktreeSession) {
                 const cwd = workdir || worktreeSession.path;
                 const baseBranch = getDefaultRemoteBranch(cwd);
                 const hasChanges = hasUncommittedChanges(cwd);
                 const hasCommits = hasNewCommits(cwd, baseBranch);
-                if (!hasChanges && !hasCommits) {
-                    await removeWorktree(worktreeSession);
+                cleanWorktree = !hasChanges && !hasCommits;
+                if (cleanWorktree) {
+                    await agent.triggerWorktreeRemoveHook(worktreeSession.path);
                 }
                 else {
                     process.stdout.write(`\n⚠️ Worktree '${worktreeSession.name}' has changes or commits. Keeping it at: ${worktreeSession.path}\n`);
                 }
             }
+            await agent.destroy();
+            // Handle worktree cleanup for print mode even on error
+            if (worktreeSession && cleanWorktree) {
+                try {
+                    validateWorktreeRemovalPath(worktreeSession.path, worktreeSession.repoRoot);
+                    await removeWorktree(worktreeSession);
+                }
+                catch (error) {
+                    process.stdout.write(`\n⚠️ Skipping worktree removal: ${error.message}\n`);
+                }
+            }
         }
         process.exit(1);
     }

package/dist/stdio/agentBridge.d.ts

@@ -21,6 +21,9 @@ export interface AgentBridgeOptions {
 }
 export declare class AgentBridge {
     private sessions;
+    /** Pending approval requests, keyed by requestId. Stored with the resolve +
+     * context so a re-attached client can list and respond to them (daemon mode:
+     * approvals outlive any single connection). */
     private pendingPermissions;
     private permissionCounter;
     private emit;
@@ -31,6 +34,21 @@ export declare class AgentBridge {
     handleNotification(method: string, params: unknown): void;
     private initialize;
     private destroy;
+    /**
+     * True when every hosted session has settled: not generating, nothing queued,
+     * and no background work (background bash / subagents / workflows) — the same
+     * condition `wave -p` waits on before exiting (print-cli.ts). Pending
+     * permission approvals keep the owning agent's isLoading true, so they are
+     * covered without an explicit check.
+     */
+    isIdle(): boolean;
+    /**
+     * Destroy every hosted session agent. Each Agent.destroy() saves its
+     * transcript, drains in-flight auto-memory extraction, and cleans up
+     * background tasks/subagents. Best-effort: one failing destroy must not
+     * block the rest of the shutdown.
+     */
+    destroyAll(): Promise<void>;
     private restoreSession;
     private listSessions;
     private listGitBranches;
@@ -40,6 +58,7 @@ export declare class AgentBridge {
     private updateConfig;
     private sendMessage;
     private bang;
+    private askBtw;
     private abortMessage;
     private clearMessages;
     private rewindToMessage;
@@ -64,6 +83,10 @@ export declare class AgentBridge {
     private getPromptHistory;
     private searchPromptHistory;
     private canUseTool;
+    /** Attach snapshot: re-surface approvals that are still pending after a
+     * client disconnected (daemon mode). Responding to any listed requestId
+     * resolves the in-process promise. */
+    private listPendingPermissions;
     private getAuthStatus;
     private login;
     private logout;

package/dist/stdio/agentBridge.js

@@ -14,14 +14,18 @@
  * - Implement the canUseTool permission flow over the stdio protocol
  * - Handle config updates by destroying and recreating the Agent
  */
-import { Agent, listSessions, searchFiles, generateRandomName, getDefaultRemoteBranch, getMessageContent, PromptHistoryManager, AuthService, PluginCore, } from "wave-agent-sdk";
+import { Agent, listSessions, searchFiles, generateRandomName, getDefaultRemoteBranch, getMessageContent, PromptHistoryManager, AuthService, PluginCore, validateWorktreeRemovalPath, } from "wave-agent-sdk";
 import { INTERNAL_ERROR as PROTOCOL_INTERNAL_ERROR, METHOD_NOT_FOUND as PROTOCOL_METHOD_NOT_FOUND, } from "./protocol.js";
 import { execFileSync } from "node:child_process";
 import { createWorktree, removeWorktree } from "../utils/worktree.js";
 import { logger } from "../utils/logger.js";
+import { isUserCheckpointMessage } from "../utils/rewindCheckpoints.js";
 export class AgentBridge {
     constructor(options) {
         this.sessions = new Map();
+        /** Pending approval requests, keyed by requestId. Stored with the resolve +
+         * context so a re-attached client can list and respond to them (daemon mode:
+         * approvals outlive any single connection). */
         this.pendingPermissions = new Map();
         this.permissionCounter = 0;
         this.emit = options.emit;
@@ -41,6 +45,8 @@ export class AgentBridge {
                 return this.listSessions(p.workdir, sessionId);
             case "getSessionInfo":
                 return this.getSessionInfo(sessionId);
+            case "listPendingPermissions":
+                return this.listPendingPermissions();
             case "updateConfig":
                 return this.updateConfig(p, sessionId);
             // ── Messages ──
@@ -48,6 +54,8 @@ export class AgentBridge {
                 return this.sendMessage(p, sessionId);
             case "bang":
                 return this.bang(p.command, sessionId);
+            case "askBtw":
+                return this.askBtw(p.question, sessionId);
             case "abortMessage":
                 return this.abortMessage(sessionId);
             case "clearMessages":
@@ -146,15 +154,29 @@ export class AgentBridge {
         if (method === "permissionResponse") {
             const p = params;
             // requestId is process-level unique; lookup doesn't need sessionId
-            const resolve = this.pendingPermissions.get(p.requestId);
-            if (resolve) {
+            const entry = this.pendingPermissions.get(p.requestId);
+            if (entry) {
                 this.pendingPermissions.delete(p.requestId);
-                resolve(p.decision);
+                entry.resolve(p.decision);
             }
         }
     }
     // ── Lifecycle ─────────────────────────────────────────────────
     async initialize(params) {
+        // Re-attach (daemon mode): if the target session is already live in this
+        // process, reuse it instead of creating a second agent writing to the same
+        // transcript. The live agent keeps running across client detach/attach.
+        if (params.restoreSessionId) {
+            const live = this.sessions.get(params.restoreSessionId);
+            if (live) {
+                return {
+                    sessionId: live.agent.sessionId,
+                    workingDirectory: live.agent.workingDirectory,
+                    permissionMode: live.agent.getPermissionMode(),
+                    latestTotalTokens: live.agent.latestTotalTokens,
+                };
+            }
+        }
         const ctx = {};
         const callbacks = this.createCallbacks(ctx);
         const options = {
@@ -202,8 +224,53 @@ export class AgentBridge {
         }
         return null;
     }
+    /**
+     * True when every hosted session has settled: not generating, nothing queued,
+     * and no background work (background bash / subagents / workflows) — the same
+     * condition `wave -p` waits on before exiting (print-cli.ts). Pending
+     * permission approvals keep the owning agent's isLoading true, so they are
+     * covered without an explicit check.
+     */
+    isIdle() {
+        for (const entry of this.sessions.values()) {
+            const agent = entry.agent;
+            if (agent.isLoading ||
+                agent.hasPendingMessages ||
+                agent.hasRunningBackgroundWork) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Destroy every hosted session agent. Each Agent.destroy() saves its
+     * transcript, drains in-flight auto-memory extraction, and cleans up
+     * background tasks/subagents. Best-effort: one failing destroy must not
+     * block the rest of the shutdown.
+     */
+    async destroyAll() {
+        const entries = [...this.sessions.values()];
+        this.sessions.clear();
+        await Promise.all(entries.map((entry) => entry.agent.destroy().catch(() => { })));
+    }
     async restoreSession(restoreId, sessionId) {
         const entry = this.requireSession(sessionId);
+        // Re-attach to a live session: the SDK restore would no-op (target is
+        // already current). Emit the current messages so the freshly attached
+        // client — whose router registered only after initialize returned and so
+        // missed any earlier notifications — gets a snapshot without replay.
+        if (entry.agent.sessionId === restoreId) {
+            this.emit("messagesChange", { messages: entry.agent.messages }, entry.agent.sessionId);
+            // The re-attached client also missed the loading state that settled
+            // before its router registered — replay it or the client's
+            // isStreaming/running indicator stays false while the live session
+            // keeps generating.
+            this.emit("loadingChange", {
+                loading: entry.agent.isLoading,
+                latestTotalTokens: entry.agent.latestTotalTokens,
+            }, entry.agent.sessionId);
+            return null;
+        }
         await entry.agent.restoreSession(restoreId);
         return null;
     }
@@ -268,6 +335,28 @@ export class AgentBridge {
         }
     }
     async removeWorktreeSession(params) {
+        // Align with Claude Code v2.1.216+: refuse to remove a worktree whose path
+        // is a symlink or resolves outside the repo root. Already-removed (missing)
+        // paths pass validation so removal stays idempotent.
+        try {
+            validateWorktreeRemovalPath(params.path, params.repoRoot);
+        }
+        catch (e) {
+            throw new RpcError(PROTOCOL_INTERNAL_ERROR, e.message);
+        }
+        // Trigger the WorktreeRemove hook (before git removal, non-blocking) using
+        // the session that runs in this worktree, if it is still registered.
+        for (const entry of this.sessions.values()) {
+            if (entry.agent.workingDirectory === params.path) {
+                try {
+                    await entry.agent.triggerWorktreeRemoveHook(params.path);
+                }
+                catch (e) {
+                    logger.warn("WorktreeRemove hooks execution failed:", e);
+                }
+                break;
+            }
+        }
         // removeWorktree is best-effort/idempotent: already-removed worktrees or
         // branches only log, never throw.
         await removeWorktree({
@@ -355,6 +444,22 @@ export class AgentBridge {
         await entry.agent.bang(command);
         return null;
     }
+    async askBtw(question, sessionId) {
+        const entry = this.requireSession(sessionId);
+        return entry.agent.askBtw(question, undefined, 
+        // Stream partial content to the client so webview hosts can render the
+        // answer incrementally (thinking and content travel on separate
+        // channels so the panel can drop thinking text once content starts).
+        (content) => {
+            if (sessionId) {
+                this.emit("btwContent", { question, content, type: "content" }, sessionId);
+            }
+        }, (content) => {
+            if (sessionId) {
+                this.emit("btwContent", { question, content, type: "thinking" }, sessionId);
+            }
+        });
+    }
     async abortMessage(sessionId) {
         const entry = this.requireSession(sessionId);
         entry.agent.abortMessage();
@@ -381,7 +486,7 @@ export class AgentBridge {
         const entry = this.requireSession(sessionId);
         const { messages } = await entry.agent.getFullMessageThread();
         const checkpoints = messages
-            .filter((m) => m.role === "user" && !m.isMeta && m.id)
+            .filter((m) => isUserCheckpointMessage(m) && m.id)
             .map((m) => ({
             id: m.id,
             content: getMessageContent(m).replace(/\s+/g, " ").trim(),
@@ -499,10 +604,26 @@ export class AgentBridge {
     canUseTool(context, ctx) {
         const requestId = `perm_${++this.permissionCounter}`;
         return new Promise((resolve) => {
-            this.pendingPermissions.set(requestId, resolve);
+            this.pendingPermissions.set(requestId, {
+                resolve,
+                sessionId: ctx.registeredSessionId,
+                context,
+            });
             this.emit("permissionRequest", { requestId, context }, ctx.registeredSessionId);
         });
     }
+    /** Attach snapshot: re-surface approvals that are still pending after a
+     * client disconnected (daemon mode). Responding to any listed requestId
+     * resolves the in-process promise. */
+    listPendingPermissions() {
+        return {
+            requests: [...this.pendingPermissions.entries()].map(([requestId, entry]) => ({
+                requestId,
+                sessionId: entry.sessionId,
+                context: entry.context,
+            })),
+        };
+    }
     // ── Auth (global) ────────────────────────────────────────────
     async getAuthStatus() {
         const authService = AuthService.getInstance();
@@ -604,9 +725,6 @@ export class AgentBridge {
     // ── Callbacks → Notifications ─────────────────────────────────
     createCallbacks(ctx) {
         return {
-            onMessagesChange: (messages) => {
-                this.emit("messagesChange", { messages }, ctx.registeredSessionId);
-            },
             onUserMessageAdded: () => {
                 const msg = this.findLastUserMessage(ctx.agent);
                 if (msg)
@@ -618,13 +736,28 @@ export class AgentBridge {
                     this.emit("assistantMessageAdded", { message: msg }, ctx.registeredSessionId);
             },
             onAssistantContentUpdated: (params) => {
-                this.emit("assistantContentUpdated", params, ctx.registeredSessionId);
+                // Wire carries only the delta; consumers accumulate (spec: 流式通知纯增量负载).
+                this.emit("assistantContentUpdated", {
+                    messageId: params.messageId,
+                    chunk: params.chunk,
+                    stage: params.stage,
+                }, ctx.registeredSessionId);
             },
             onAssistantReasoningUpdated: (params) => {
-                this.emit("assistantReasoningUpdated", params, ctx.registeredSessionId);
+                this.emit("assistantReasoningUpdated", {
+                    messageId: params.messageId,
+                    chunk: params.chunk,
+                    stage: params.stage,
+                }, ctx.registeredSessionId);
             },
             onToolBlockUpdated: (params) => {
-                this.emit("toolBlockUpdated", params, ctx.registeredSessionId);
+                // Streaming stages carry only the parametersChunk delta; start/running
+                // (one-time snapshots) and end (authoritative full value) keep
+                // `parameters` (spec: 流式通知纯增量负载).
+                const { parameters, ...rest } = params;
+                void parameters;
+                const wireParams = params.stage === "streaming" ? rest : params;
+                this.emit("toolBlockUpdated", wireParams, ctx.registeredSessionId);
             },
             onErrorBlockAdded: (error) => {
                 this.emit("errorBlockAdded", { error }, ctx.registeredSessionId);
@@ -682,14 +815,14 @@ export class AgentBridge {
             onMcpServersChange: (servers) => {
                 this.emit("mcpServersChange", { servers }, ctx.registeredSessionId);
             },
-            onAddBangMessage: () => {
-                this.emit("bangMessageAdded", {}, ctx.registeredSessionId);
+            onAddBangMessage: (command, messageId) => {
+                this.emit("bangMessageAdded", { command, messageId }, ctx.registeredSessionId);
             },
-            onUpdateBangMessage: () => {
-                this.emit("bangMessageUpdated", {}, ctx.registeredSessionId);
+            onUpdateBangMessage: (command, output, messageId) => {
+                this.emit("bangMessageUpdated", { command, output, messageId }, ctx.registeredSessionId);
             },
-            onCompleteBangMessage: () => {
-                this.emit("bangMessageCompleted", {}, ctx.registeredSessionId);
+            onCompleteBangMessage: (command, exitCode, messageId) => {
+                this.emit("bangMessageCompleted", { command, exitCode, messageId }, ctx.registeredSessionId);
             },
             onNotificationMessageAdded: (params) => {
                 const msg = ctx.agent?.messages.find((m) => m.role === "user" &&

package/dist/stdio/daemonServer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * DaemonServer — JSON-RPC server over a unix socket for remote background
+ * sessions (spec: docs/specs/ui/desktop-app.md 「SSH 远程后台会话」).
+ *
+ * The desktop app launches `wave --daemon <socket>` on the remote host via
+ * nohup/setsid, then tunnels the socket back with `ssh -L`. All connections
+ * share one AgentBridge, so sessions and pending tool permissions survive
+ * client detach/attach — the daemon keeps running (and generating) while no
+ * desktop is connected. The daemon never exits on a client disconnect; it
+ * only exits when killed (app quit / 删除会话 / remote reboot).
+ *
+ * Idle auto-exit (spec: 「远程 daemon 空闲自动退出」): once every session has
+ * settled and no client is connected, the daemon mirrors `wave -p`'s exit
+ * semantics — after a grace period it destroys the sessions (saving their
+ * transcripts), closes the socket, and exits, so the remote process doesn't
+ * linger forever after background work completes.
+ */
+import { AgentBridge, type AgentBridgeOptions } from "./agentBridge.js";
+export interface DaemonServerOptions {
+    socketPath: string;
+    bridgeOptions?: AgentBridgeOptions;
+    /** Idle grace period before the daemon auto-exits (default 60s). */
+    graceMs?: number;
+}
+export declare class DaemonServer {
+    static readonly DEFAULT_IDLE_GRACE_MS = 60000;
+    private socketPath;
+    private server;
+    private bridge;
+    private connections;
+    private sockets;
+    private graceMs;
+    private idleTimer;
+    private shuttingDown;
+    private stopped;
+    constructor(options: DaemonServerOptions);
+    get agentBridge(): AgentBridge;
+    /**
+     * Listen on the socket path. Rejects when a live daemon already holds it. A
+     * stale socket file left by a crashed daemon would otherwise block the
+     * restart with EADDRINUSE, so it is cleaned up first: non-socket files are
+     * unlinked outright; socket files are probe-connected — ECONNREFUSED means
+     * no listener (stale → unlink and listen), anything else means a live
+     * daemon owns the path (reject).
+     */
+    start(): Promise<void>;
+    private listen;
+    stop(): Promise<void>;
+    private clearIdleTimer;
+    /**
+     * Re-evaluate the idle condition after any state transition: sessions busy
+     * (loading / pending messages / background work) or any client attached →
+     * cancel the timer. Fully idle + detached → arm the grace timer once; when
+     * it fires, shut the daemon down. Evaluation is event-driven (every
+     * busy→idle transition emits a notification, every attach/detach fires a
+     * connection event), so nothing is polled. The failure mode is
+     * conservative: a missed transition just leaves the daemon running.
+     */
+    private evaluateIdle;
+    /**
+     * Destroy the sessions (each agent saves its transcript and drains
+     * auto-memory), close the listener, unlink the socket file, then exit.
+     * `shuttingDown` guards against re-entry: new connections are refused and
+     * further idle evaluations become no-ops.
+     */
+    private shutdown;
+}

package/dist/stdio/daemonServer.js

@@ -0,0 +1,191 @@
+/**
+ * DaemonServer — JSON-RPC server over a unix socket for remote background
+ * sessions (spec: docs/specs/ui/desktop-app.md 「SSH 远程后台会话」).
+ *
+ * The desktop app launches `wave --daemon <socket>` on the remote host via
+ * nohup/setsid, then tunnels the socket back with `ssh -L`. All connections
+ * share one AgentBridge, so sessions and pending tool permissions survive
+ * client detach/attach — the daemon keeps running (and generating) while no
+ * desktop is connected. The daemon never exits on a client disconnect; it
+ * only exits when killed (app quit / 删除会话 / remote reboot).
+ *
+ * Idle auto-exit (spec: 「远程 daemon 空闲自动退出」): once every session has
+ * settled and no client is connected, the daemon mirrors `wave -p`'s exit
+ * semantics — after a grace period it destroys the sessions (saving their
+ * transcripts), closes the socket, and exits, so the remote process doesn't
+ * linger forever after background work completes.
+ */
+import net from "net";
+import * as fs from "fs";
+import { AgentBridge } from "./agentBridge.js";
+import { JsonRpcConnection } from "./jsonRpcConnection.js";
+export class DaemonServer {
+    constructor(options) {
+        this.connections = new Set();
+        this.sockets = new Set();
+        this.shuttingDown = false;
+        this.stopped = false;
+        this.socketPath = options.socketPath;
+        this.graceMs = options.graceMs ?? DaemonServer.DEFAULT_IDLE_GRACE_MS;
+        this.bridge = new AgentBridge({
+            ...options.bridgeOptions,
+            // Notifications go to every attached client; a fully detached daemon
+            // has none, and the write is dropped silently (the attach snapshot
+            // re-syncs state on reconnect).
+            emit: (method, params, sessionId) => {
+                for (const conn of this.connections) {
+                    conn.sendNotification(method, params, sessionId);
+                }
+                // Any session activity can change the idle state — re-evaluate.
+                this.evaluateIdle();
+            },
+        });
+        this.server = net.createServer((socket) => {
+            if (this.shuttingDown) {
+                socket.destroy();
+                return;
+            }
+            const conn = new JsonRpcConnection(socket, socket, this.bridge);
+            this.connections.add(conn);
+            this.sockets.add(socket);
+            // A (re)attached client cancels a pending idle exit.
+            this.evaluateIdle();
+            socket.on("error", () => {
+                // The client (ssh tunnel) can reset the socket mid-detach; the daemon
+                // must keep running — 'close' below cleans up the connection.
+            });
+            socket.on("close", () => {
+                this.connections.delete(conn);
+                this.sockets.delete(socket);
+                // A client detach may leave the daemon idle — re-evaluate.
+                this.evaluateIdle();
+            });
+            conn.start();
+        });
+    }
+    get agentBridge() {
+        return this.bridge;
+    }
+    /**
+     * Listen on the socket path. Rejects when a live daemon already holds it. A
+     * stale socket file left by a crashed daemon would otherwise block the
+     * restart with EADDRINUSE, so it is cleaned up first: non-socket files are
+     * unlinked outright; socket files are probe-connected — ECONNREFUSED means
+     * no listener (stale → unlink and listen), anything else means a live
+     * daemon owns the path (reject).
+     */
+    start() {
+        return new Promise((resolve, reject) => {
+            const server = this.server;
+            if (!server)
+                return resolve();
+            try {
+                const st = fs.statSync(this.socketPath);
+                if (st.isSocket()) {
+                    const probe = net.connect(this.socketPath);
+                    probe.once("connect", () => {
+                        probe.destroy();
+                        reject(new Error(`另一个 wave daemon 已在 ${this.socketPath} 监听`));
+                    });
+                    probe.once("error", (err) => {
+                        probe.destroy();
+                        if (err.code === "ECONNREFUSED") {
+                            fs.unlinkSync(this.socketPath);
+                            this.listen(server, resolve, reject);
+                        }
+                        else {
+                            reject(err);
+                        }
+                    });
+                    return;
+                }
+                fs.unlinkSync(this.socketPath);
+            }
+            catch {
+                // ENOENT — no stale socket, listen directly.
+            }
+            this.listen(server, resolve, reject);
+        });
+    }
+    listen(server, resolve, reject) {
+        server.once("error", reject);
+        server.listen(this.socketPath, () => {
+            server.removeListener("error", reject);
+            resolve();
+            // A freshly started daemon may already be idle (no sessions) — start the
+            // idle watch so a zero-session daemon also auto-exits.
+            this.evaluateIdle();
+        });
+    }
+    stop() {
+        this.stopped = true;
+        this.clearIdleTimer();
+        return new Promise((resolve) => {
+            const server = this.server;
+            if (!server)
+                return resolve();
+            this.server = undefined;
+            server.close(() => resolve());
+        });
+    }
+    // ── Idle auto-exit ────────────────────────────────────────────
+    clearIdleTimer() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = undefined;
+        }
+    }
+    /**
+     * Re-evaluate the idle condition after any state transition: sessions busy
+     * (loading / pending messages / background work) or any client attached →
+     * cancel the timer. Fully idle + detached → arm the grace timer once; when
+     * it fires, shut the daemon down. Evaluation is event-driven (every
+     * busy→idle transition emits a notification, every attach/detach fires a
+     * connection event), so nothing is polled. The failure mode is
+     * conservative: a missed transition just leaves the daemon running.
+     */
+    evaluateIdle() {
+        // A stopped/shutting-down daemon never (re)arms the idle timer — late
+        // socket 'close' events (which fire after server.close resolves) must not
+        // resurrect a timer after stop().
+        if (this.shuttingDown || this.stopped)
+            return;
+        if (this.connections.size > 0 || !this.bridge.isIdle()) {
+            this.clearIdleTimer();
+            return;
+        }
+        if (this.idleTimer)
+            return;
+        this.idleTimer = setTimeout(() => {
+            this.idleTimer = undefined;
+            void this.shutdown();
+        }, this.graceMs);
+    }
+    /**
+     * Destroy the sessions (each agent saves its transcript and drains
+     * auto-memory), close the listener, unlink the socket file, then exit.
+     * `shuttingDown` guards against re-entry: new connections are refused and
+     * further idle evaluations become no-ops.
+     */
+    async shutdown() {
+        if (this.shuttingDown)
+            return;
+        this.shuttingDown = true;
+        this.clearIdleTimer();
+        // Destroy client sockets first so server.close() can complete (an open
+        // socket keeps the close callback pending).
+        for (const socket of this.sockets)
+            socket.destroy();
+        this.sockets.clear();
+        await this.bridge.destroyAll();
+        await this.stop();
+        try {
+            fs.unlinkSync(this.socketPath);
+        }
+        catch {
+            // Already gone — a stale file would be probed/unlinked on next start.
+        }
+        process.exit(0);
+    }
+}
+DaemonServer.DEFAULT_IDLE_GRACE_MS = 60000;

package/dist/stdio/index.d.ts

@@ -1,3 +1,5 @@
 export { StdioServer, type StdioServerOptions } from "./stdioServer.js";
+export { JsonRpcConnection } from "./jsonRpcConnection.js";
+export { DaemonServer, type DaemonServerOptions } from "./daemonServer.js";
 export { AgentBridge, type AgentBridgeOptions, RpcError, } from "./agentBridge.js";
 export * from "./protocol.js";