wave-agent-sdk 1.1.5 → 1.3.0

package/dist/services/session.js

@@ -22,9 +22,10 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import { PathEncoder } from "../utils/pathEncoder.js";
 import { JsonlHandler } from "../services/jsonlHandler.js";
+import { isReservedEntry } from "../services/sessionEntries.js";
 import { extractLatestTotalTokens } from "../utils/tokenCalculation.js";
 import { logger } from "../utils/globalLogger.js";
-import { getMessageContent, sliceFromLastCompact, } from "../utils/messageOperations.js";
+import { getMessageContent } from "../utils/messageOperations.js";
 const execFileAsync = promisify(execFile);
 /**
  * Generate a new session ID using Node.js native crypto.randomUUID()
@@ -119,6 +120,35 @@ export async function createSession(sessionId, workdir, sessionType = "main") {
         gitBranch: await getGitBranch(workdir),
     });
 }
+/**
+ * Rewrite a session file down to its first `keepMessageCount` messages.
+ *
+ * The only caller is `/rewind`. Unlike `appendMessages` this removes history
+ * from the file, but it keeps every file-level reserved entry (metadata header,
+ * `custom-title`) byte for byte — dropping them would silently turn the session
+ * into the "legacy file without a header" shape, losing its creation time,
+ * git branch and user-set title.
+ *
+ * @param sessionId - UUID session identifier
+ * @param keepMessageCount - Number of leading messages to keep
+ * @param workdir - Working directory for the session
+ * @param sessionType - Type of session ("main" or "subagent", defaults to "main")
+ */
+export async function truncateSession(sessionId, keepMessageCount, workdir, sessionType = "main") {
+    // Do not save session files in test environment
+    if (process.env.NODE_ENV === "test") {
+        return;
+    }
+    const jsonlHandler = new JsonlHandler();
+    const filePath = await generateSessionFilePath(sessionId, workdir, sessionType);
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        throw new Error(`Session file not found: ${sessionId}. Cannot rewind a session that was never persisted.`);
+    }
+    await jsonlHandler.truncateSession(filePath, keepMessageCount);
+}
 /**
  * Append messages to session using JSONL format (new approach)
  *
@@ -146,10 +176,114 @@ export async function appendMessages(sessionId, newMessages, workdir, sessionTyp
     catch {
         throw new Error(`Session file not found: ${sessionId}. Use createSession() to create a new session first.`);
     }
+    // Append only. Keeping the title inside the listing's tail window is the
+    // job of `reAppendSessionMetadata`, which runs at the session's sparse flush
+    // points — not here: appending the entry on every save costs a tail read and
+    // an extra line per save, for a guarantee only needed once the session is
+    // about to be read from disk by someone else.
     await jsonlHandler.append(filePath, newMessages, {
         atomic: false,
     });
 }
+/**
+ * Set (or replace) a session's user-set title.
+ *
+ * The title is persisted as a `custom-title` entry appended to the session's
+ * own JSONL file — never as a rewrite of the metadata header, and never in a
+ * sidecar index — so every host that reads session files sees it without any
+ * extra sync channel.
+ *
+ * A session whose transcript has not been materialized yet (only meta messages
+ * so far) is created here: renaming is an explicit user action, so it is not
+ * subject to the "meta-only sessions never hit disk" rule.
+ *
+ * An empty/blank title is a no-op — it is not a signal to clear the title.
+ *
+ * @param sessionId - UUID session identifier
+ * @param workdir - Working directory the session belongs to
+ * @param title - New title
+ * @returns The trimmed title that was written, or undefined for a blank no-op
+ */
+export async function setSessionCustomTitle(sessionId, workdir, title) {
+    const trimmed = title.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    const jsonlHandler = new JsonlHandler();
+    let filePath = await generateSessionFilePath(sessionId, workdir, "main");
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        // The session may live in another project directory (created from a
+        // different cwd, or a git worktree that no longer maps to this workdir).
+        const fallback = await findSessionFileAcrossProjects(sessionId, "main");
+        if (fallback) {
+            filePath = fallback;
+        }
+        else {
+            await createSession(sessionId, workdir, "main");
+            filePath = await generateSessionFilePath(sessionId, workdir, "main");
+        }
+    }
+    await jsonlHandler.appendCustomTitle(filePath, trimmed, sessionId);
+    return trimmed;
+}
+/**
+ * Re-append the session's reserved metadata entries at EOF.
+ *
+ * A listing reads only the tail window (64 KB) of each session file, so a
+ * `custom-title` entry that later messages pushed past that window becomes
+ * invisible — the session would flip back to showing its first message. This
+ * runs at the session's sparse flush points (spec `session-management.md`
+ * 验收场景 5): graceful exit, compaction, taking over a resumed session,
+ * switching away from one, and after `/rewind` rewrites the file. Claude Code
+ * solves the same problem the same way (`reAppendSessionMetadata`,
+ * `sessionStorage.ts:458/983/1533`, `compact.ts:711/1057`).
+ *
+ * The entry is refreshed from the tail first: another process (the CLI session
+ * picker, a second host) may have renamed the session while we held it, in
+ * which case its value — not our stale in-memory one — is the truth. When the
+ * tail holds nothing (already evicted, or never written by anyone else), the
+ * caller's in-memory value stands.
+ *
+ * A missing transcript file is a no-op: re-appending must never materialize a
+ * session that does not exist.
+ *
+ * @param sessionId - UUID session identifier
+ * @param workdir - Working directory the session belongs to
+ * @param customTitle - Title held in memory by the caller (may be undefined)
+ * @param sessionType - Type of session ("main" or "subagent", defaults to "main")
+ */
+export async function reAppendSessionMetadata(sessionId, workdir, customTitle, sessionType = "main") {
+    const jsonlHandler = new JsonlHandler();
+    let filePath = await generateSessionFilePath(sessionId, workdir, sessionType);
+    try {
+        await fs.access(filePath);
+    }
+    catch {
+        // The session may live in another project directory (created from a
+        // different cwd, or a git worktree). That sweep costs a directory walk per
+        // flush point, so it runs only when there is a title to write: with no
+        // in-memory title there is nothing this call could add that the entry
+        // already in the file does not say.
+        if (!customTitle) {
+            return;
+        }
+        const fallback = await findSessionFileAcrossProjects(sessionId, sessionType);
+        if (!fallback) {
+            return;
+        }
+        filePath = fallback;
+    }
+    // Absorb a fresher value written by another process since we last looked.
+    const tailTitle = await jsonlHandler.readCustomTitle(filePath);
+    const title = tailTitle ?? customTitle;
+    if (!title) {
+        return;
+    }
+    await jsonlHandler.appendCustomTitle(filePath, title, sessionId);
+}
 /**
  * Scan all project directories for a session file by ID. Used as a fallback
  * when the session is not found in the given working directory (e.g. resuming
@@ -214,9 +348,21 @@ export async function loadSessionFromJsonl(sessionId, workdir, sessionType = "ma
                 throw error;
             }
         }
-        const allMessages = await jsonlHandler.read(resolvedPath);
-        // Find the last compact boundary — only return messages from there forward
-        const messages = sliceFromLastCompact(allMessages);
+        const { messages: allMessages, customTitle } = await jsonlHandler.readMessagesAndCustomTitle(resolvedPath);
+        // Transcripts written by older CLI versions re-appended the preserved
+        // rounds at each compaction point, so a message id can appear twice.
+        // Keep the first occurrence — duplicates would render twice once the
+        // full-history restore below feeds them to displayMessages. Append-only
+        // transcripts (current write side) have unique ids, making this a no-op.
+        const seenIds = new Set();
+        const messages = [];
+        for (const message of allMessages) {
+            if (message.id && seenIds.has(message.id))
+                continue;
+            if (message.id)
+                seenIds.add(message.id);
+            messages.push(message);
+        }
         // Extract metadata from messages
         const lastMessage = messages.length > 0 ? messages[messages.length - 1] : null;
         const sessionData = {
@@ -227,9 +373,15 @@ export async function loadSessionFromJsonl(sessionId, workdir, sessionType = "ma
                 lastActiveAt: lastMessage
                     ? lastMessage.timestamp
                     : new Date().toISOString(),
-                latestTotalTokens: lastMessage?.usage
-                    ? extractLatestTotalTokens([lastMessage])
-                    : 0,
+                // Scan backwards for the last usage-bearing message instead of only
+                // testing the tail: a resumed conversation gets usage-less meta
+                // messages appended (SessionStart hooks), which would otherwise report
+                // 0 and blank the context-usage indicator for that conversation.
+                latestTotalTokens: extractLatestTotalTokens(messages),
+                // Recovered from the whole-file scan, not the tail window: a title the
+                // conversation has long outgrown is only reachable this way. The host
+                // holds it in memory so `reAppendSessionMetadata` puts it back at EOF.
+                customTitle,
             },
         };
         return sessionData;
@@ -348,9 +500,9 @@ export async function listSessionsFromJsonl(workdir) {
                         ? new Date(header.createdAt)
                         : new Date(),
                     lastActiveAt,
-                    latestTotalTokens: lastMessage?.usage
-                        ? extractLatestTotalTokens([lastMessage])
-                        : 0,
+                    // Scans the file tail: a resumed session's last line is a usage-less
+                    // hook message, so the line alone would report 0 tokens here.
+                    latestTotalTokens: await jsonlHandler.getLatestTotalTokens(filePath),
                     branch: header?.gitBranch,
                 };
                 // Try to get first message content for display
@@ -363,6 +515,8 @@ export async function listSessionsFromJsonl(workdir) {
                 catch {
                     // Ignore errors getting first message
                 }
+                // A user-set title, when present, wins over the first-message label.
+                sessionMeta.customTitle = await jsonlHandler.readCustomTitle(filePath);
                 sessions.push(sessionMeta);
             }
             catch {
@@ -535,10 +689,11 @@ export async function listAllSessions(options) {
                                 ? new Date(header.createdAt)
                                 : new Date(),
                             lastActiveAt,
-                            latestTotalTokens: lastMessage?.usage
-                                ? extractLatestTotalTokens([lastMessage])
-                                : 0,
+                            // Scans the file tail: a resumed session's last line is a
+                            // usage-less hook message, so the line alone would report 0.
+                            latestTotalTokens: await jsonlHandler.getLatestTotalTokens(filePath),
                             firstMessage,
+                            customTitle: await jsonlHandler.readCustomTitle(filePath),
                             branch: header?.gitBranch,
                         });
                     }
@@ -719,8 +874,8 @@ export async function getFirstMessageContentFromFile(filePath) {
         for (const line of lines) {
             try {
                 const message = JSON.parse(line);
-                // Skip the metadata header line and meta messages
-                if (message.type === "metadata" || message.isMeta) {
+                // Skip reserved entries (metadata header, custom-title) and meta messages
+                if (isReservedEntry(message.type) || message.isMeta) {
                     continue;
                 }
                 const content = getMessageContent(message);
@@ -828,7 +983,10 @@ export async function handleSessionRestoration(restoreSessionId, continueLastSes
             }
         }
         if (sessionToRestore) {
-            console.log(`Restoring session: ${sessionToRestore.id}`);
+            // Diagnostics only — never stdout: `wave --stdio`'s stdout carries the
+            // JSON-RPC channel, and a stray line there makes the host log a parse
+            // failure for every restore (the logger writes to the log file).
+            logger.info(`Restoring session: ${sessionToRestore.id}`);
             // // Initialize from session data
             // this.initializeFromSession();
             return sessionToRestore;

package/dist/services/sessionEntries.d.ts

@@ -0,0 +1,2 @@
+/** True when a parsed JSONL line is a reserved (non-message) entry. */
+export declare function isReservedEntry(type: string | undefined): boolean;

package/dist/services/sessionEntries.js

@@ -0,0 +1,20 @@
+/**
+ * Reserved (non-message) entry types found in a session JSONL file.
+ *
+ * A session file is an append-only log of messages plus a few reserved
+ * bookkeeping entries: the `metadata` header written once at creation, and a
+ * `custom-title` entry appended on every rename. Every reader must skip all of
+ * them — a reserved entry parsed as a message yields `lastActiveAt: Invalid
+ * Date`, corrupts the token scan, or surfaces in the conversation.
+ *
+ * Lives in its own dependency-free module because both the writer
+ * (`jsonlHandler.ts`) and the reader (`session.ts`) need it, and the session
+ * tests mock `jsonlHandler` wholesale.
+ *
+ * Add a new file-level entry type here when adding one.
+ */
+const RESERVED_ENTRY_TYPES = new Set(["metadata", "custom-title"]);
+/** True when a parsed JSONL line is a reserved (non-message) entry. */
+export function isReservedEntry(type) {
+    return type !== undefined && RESERVED_ENTRY_TYPES.has(type);
+}

package/dist/services/worktreeHooks.js

@@ -58,7 +58,12 @@ export async function executeWorktreeRemoveHook(worktreePath, configuration, con
     const results = await runWorktreeHooks("WorktreeRemove", hookConfigs, context, { worktreePath });
     for (const result of results) {
         if (!result.success) {
-            logger?.error(`WorktreeRemove hook failed [${result.command}]: ${result.stderr || "no output"}`);
+            // The path identifies which worktree survived; exit/timeout/duration tell
+            // apart "the hook failed on its own" from "the hook was killed by the
+            // hook timeout" when failures are aggregated later.
+            logger?.error(`WorktreeRemove hook failed [${result.command}] worktree=${worktreePath} ` +
+                `exit=${result.exitCode ?? "n/a"} timedOut=${result.timedOut} ` +
+                `durationMs=${result.duration}: ${result.stderr || "no output"}`);
         }
     }
     return true;

package/dist/stdio/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Host-side stdio RPC layer shared by the VS Code extension and the desktop
+ * app: a typed StdioAgent wrapper (mirrors the CLI Agent API over JSON-RPC)
+ * plus the sessionId-demultiplexing NotificationRouter.
+ *
+ * Re-exported by the `wave-agent-sdk/host` entry — import it from there. It has
+ * no subpath of its own: the RPC layer is only reachable through `/host`, so a
+ * host cannot pick it up by accident while reaching for a shared literal.
+ */
+export * from "./rpcClient.js";
+export * from "./notificationRouter.js";
+export * from "./stdioAgent.js";

package/dist/stdio/index.js

@@ -0,0 +1,12 @@
+/**
+ * Host-side stdio RPC layer shared by the VS Code extension and the desktop
+ * app: a typed StdioAgent wrapper (mirrors the CLI Agent API over JSON-RPC)
+ * plus the sessionId-demultiplexing NotificationRouter.
+ *
+ * Re-exported by the `wave-agent-sdk/host` entry — import it from there. It has
+ * no subpath of its own: the RPC layer is only reachable through `/host`, so a
+ * host cannot pick it up by accident while reaching for a shared literal.
+ */
+export * from "./rpcClient.js";
+export * from "./notificationRouter.js";
+export * from "./stdioAgent.js";

package/dist/stdio/notificationRouter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * NotificationRouter — demultiplexes server→client notifications by sessionId.
+ *
+ * In the single-shared-process architecture, all sessions share one StdioClient.
+ * The server tags each session-scoped notification with `sessionId` on the
+ * JSON-RPC envelope. The router inspects that field and dispatches to the
+ * matching StdioAgent; notifications without sessionId (e.g. `authUrl`) go to
+ * a global handler.
+ *
+ * Lifecycle:
+ * 1. `attach()` once — subscribes to every notification method on the shared client
+ * 2. Per session: `register(sessionId, agent)` after `initialize` response
+ * 3. On `sessionIdChange`: router auto-rekeys the agent (old → new)
+ * 4. On `destroy`: `unregister(sessionId)` removes the agent
+ */
+import type { RpcClient } from "./rpcClient.js";
+type GlobalHandler = (params: unknown) => void;
+import type { StdioAgent } from "./stdioAgent.js";
+export declare class NotificationRouter {
+    private client;
+    private sessions;
+    private globalHandlers;
+    private attached;
+    constructor(client: RpcClient);
+    /**
+     * Subscribe to all notification methods on the shared client.
+     * Must be called once after construction. Idempotent.
+     */
+    attach(): void;
+    /** Register a session-scoped agent. Call after `initialize` response. */
+    register(sessionId: string, agent: StdioAgent): void;
+    /** Unregister a session. Call on destroy. */
+    unregister(sessionId: string): void;
+    /** Register a global (non-session-scoped) notification handler. */
+    registerGlobal(method: string, handler: GlobalHandler): void;
+    private dispatch;
+}
+export {};

package/dist/stdio/notificationRouter.js

@@ -0,0 +1,97 @@
+/**
+ * NotificationRouter — demultiplexes server→client notifications by sessionId.
+ *
+ * In the single-shared-process architecture, all sessions share one StdioClient.
+ * The server tags each session-scoped notification with `sessionId` on the
+ * JSON-RPC envelope. The router inspects that field and dispatches to the
+ * matching StdioAgent; notifications without sessionId (e.g. `authUrl`) go to
+ * a global handler.
+ *
+ * Lifecycle:
+ * 1. `attach()` once — subscribes to every notification method on the shared client
+ * 2. Per session: `register(sessionId, agent)` after `initialize` response
+ * 3. On `sessionIdChange`: router auto-rekeys the agent (old → new)
+ * 4. On `destroy`: `unregister(sessionId)` removes the agent
+ */
+const ALL_NOTIFICATION_METHODS = [
+    "userMessageAdded",
+    "assistantMessageAdded",
+    "assistantContentUpdated",
+    "assistantReasoningUpdated",
+    "toolBlockUpdated",
+    "errorBlockAdded",
+    "loadingChange",
+    "contextUsage",
+    "commandRunningChange",
+    "queuedMessagesChange",
+    "tasksChange",
+    "sessionIdChange",
+    "permissionModeChange",
+    "mcpServersChange",
+    "workdirChange",
+    "notificationMessageAdded",
+    "permissionRequest",
+    "authUrl",
+    "btwContent",
+    "compactBlockAdded",
+    "compactionStateChange",
+    "compactionContentUpdate",
+    "planFileUpdated",
+    "backgroundTasksChange",
+];
+export class NotificationRouter {
+    constructor(client) {
+        this.client = client;
+        this.sessions = new Map();
+        this.globalHandlers = new Map();
+        this.attached = false;
+    }
+    /**
+     * Subscribe to all notification methods on the shared client.
+     * Must be called once after construction. Idempotent.
+     */
+    attach() {
+        if (this.attached)
+            return;
+        this.attached = true;
+        for (const method of ALL_NOTIFICATION_METHODS) {
+            this.client.onNotification(method, (params, sessionId) => {
+                this.dispatch(method, params, sessionId);
+            });
+        }
+    }
+    /** Register a session-scoped agent. Call after `initialize` response. */
+    register(sessionId, agent) {
+        this.sessions.set(sessionId, agent);
+    }
+    /** Unregister a session. Call on destroy. */
+    unregister(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    /** Register a global (non-session-scoped) notification handler. */
+    registerGlobal(method, handler) {
+        this.globalHandlers.set(method, handler);
+    }
+    dispatch(method, params, sessionId) {
+        if (sessionId) {
+            const agent = this.sessions.get(sessionId);
+            if (!agent)
+                return; // early notification before register — drop (v1)
+            // sessionIdChange requires rekeying the agent in the map
+            if (method === "sessionIdChange") {
+                const newId = params.sessionId;
+                if (newId && newId !== sessionId) {
+                    this.sessions.delete(sessionId);
+                    this.sessions.set(newId, agent);
+                }
+            }
+            agent.handleNotification(method, params);
+        }
+        else {
+            // Global notification (e.g. authUrl)
+            const handler = this.globalHandlers.get(method);
+            if (handler)
+                handler(params);
+        }
+    }
+}

package/dist/stdio/rpcClient.d.ts

@@ -0,0 +1,18 @@
+/**
+ * RpcClient — the structural transport surface StdioAgent + NotificationRouter
+ * depend on.
+ *
+ * Both hosts keep their own transports (vscode's `StdioClient`; desktop's
+ * `JsonRpcClient` subclasses `StdioClient` / `SocketClient`); each satisfies
+ * this interface structurally (TypeScript), so the shared stdio layer never
+ * needs to know which transport backs it.
+ */
+export type NotificationHandler = (params: unknown, sessionId?: string) => void;
+export interface RpcClient {
+    /** Send a request; resolves with the JSON-RPC result. */
+    request(method: string, params?: unknown, sessionId?: string): Promise<unknown>;
+    /** Fire-and-forget JSON-RPC notification (no response expected). */
+    notify(method: string, params?: unknown, sessionId?: string): void;
+    /** Subscribe to a server→client notification method. */
+    onNotification(method: string, handler: NotificationHandler): void;
+}

package/dist/stdio/rpcClient.js

@@ -0,0 +1,10 @@
+/**
+ * RpcClient — the structural transport surface StdioAgent + NotificationRouter
+ * depend on.
+ *
+ * Both hosts keep their own transports (vscode's `StdioClient`; desktop's
+ * `JsonRpcClient` subclasses `StdioClient` / `SocketClient`); each satisfies
+ * this interface structurally (TypeScript), so the shared stdio layer never
+ * needs to know which transport backs it.
+ */
+export {};