@lelouchhe/webagent 0.8.0 → 0.10.0

package/lib/bridge.js

@@ -2,26 +2,40 @@ import { spawn } from "node:child_process";
 import { Writable, Readable } from "node:stream";
 import { EventEmitter } from "node:events";
 import * as acp from "@agentclientprotocol/sdk";
-import { interruptBashProc } from "./session-manager.js";
+import { interruptBashProc } from "./task-manager.js";
+import { abbreviateHomePath } from "./home-path.js";
 import { log } from "./log.js";
 const blog = log.scope("bridge");
 export class AgentBridge extends EventEmitter {
     proc = null;
     conn = null;
     permissionResolvers = new Map();
-    permissionRequestSessions = new Map();
+    permissionRequestTasks = new Map();
     silentSessions = new Set(); // Sessions that don't emit events
-    silentBuffers = new Map(); // Text buffers for silent sessions
+    silentBuffers = new Map(); // Text buffers for silent tasks
+    pendingNewSessions = 0;
+    unboundNewSessionIds = new Set();
+    pendingSessionUpdates = new Map();
     pendingAborts = new Map();
     deadReason = null;
+    /** Capabilities advertised by the agent at initialize; gates retire calls. */
+    sessionCapabilities = null;
     stderrTail = "";
     closedProcesses = new WeakSet();
     agentCmd;
+    sessionIds;
     reloading = false;
     attachmentDispatcher = null;
-    constructor(agentCmd) {
+    constructor(agentCmd, sessionIds) {
         super();
         this.agentCmd = agentCmd;
+        this.sessionIds = sessionIds;
+    }
+    agentSessionId(taskId) {
+        const id = this.sessionIds.getAgentSessionId(taskId);
+        if (!id)
+            throw new Error(`Task is not available for the current agent: ${taskId}`);
+        return id;
     }
     /**
      * Inject the dispatcher used to translate client attachment refs into
@@ -87,6 +101,7 @@ export class AgentBridge extends EventEmitter {
             },
         }));
         const agentInfo = init.agentInfo;
+        this.sessionCapabilities = agentInfo?.sessionCapabilities ?? null;
         this.emit("event", {
             type: "connected",
             agent: {
@@ -99,41 +114,95 @@ export class AgentBridge extends EventEmitter {
     async newSession(cwd, opts) {
         if (!this.conn)
             throw new Error("Not connected");
-        const session = await this.conn.newSession({
-            cwd,
-            mcpServers: [],
-        });
-        const configOptions = (session.configOptions ??
-            []);
-        if (!opts?.silent) {
-            this.emit("event", {
-                type: "session_created",
-                sessionId: session.sessionId,
+        this.pendingNewSessions++;
+        try {
+            const session = await this.conn.newSession({
                 cwd,
-                configOptions,
+                mcpServers: opts?.mcpServers ?? [],
+            });
+            if (opts?.silent) {
+                this.pendingSessionUpdates.delete(session.sessionId);
+                this.silentSessions.add(session.sessionId);
+            }
+            else {
+                this.unboundNewSessionIds.add(session.sessionId);
+            }
+            const configOptions = (session.configOptions ??
+                []);
+            return { sessionId: session.sessionId, configOptions };
+        }
+        finally {
+            this.pendingNewSessions--;
+            if (this.pendingNewSessions === 0) {
+                for (const sessionId of this.pendingSessionUpdates.keys()) {
+                    if (!this.unboundNewSessionIds.has(sessionId)) {
+                        this.pendingSessionUpdates.delete(sessionId);
+                        blog.warn("discarded update for unrelated unmapped ACP session", {
+                            sessionId,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    sessionMapped(agentSessionId) {
+        this.unboundNewSessionIds.delete(agentSessionId);
+        const updates = this.pendingSessionUpdates.get(agentSessionId) ?? [];
+        this.pendingSessionUpdates.delete(agentSessionId);
+        for (const update of updates) {
+            void this.handleSessionUpdate({ sessionId: agentSessionId, update });
+        }
+    }
+    discardUnboundSession(agentSessionId) {
+        this.unboundNewSessionIds.delete(agentSessionId);
+        this.pendingSessionUpdates.delete(agentSessionId);
+    }
+    /**
+     * Explicitly retire an ACP execution whose WebAgent binding has been
+     * rotated away or deleted. Best-effort: prefers `session/delete` when the
+     * agent advertises it, falls back to `session/close`, and skips silently
+     * when the agent supports neither. Failures are logged but never thrown,
+     * so retirement can never roll back an already-successful rotation.
+     */
+    async retireExecution(agentSessionId) {
+        if (!this.conn)
+            return;
+        const params = { sessionId: agentSessionId };
+        try {
+            if (this.sessionCapabilities?.delete) {
+                await this.conn.deleteSession(params);
+            }
+            else if (this.sessionCapabilities?.close) {
+                await this.conn.closeSession(params);
+            }
+        }
+        catch (err) {
+            blog.warn("failed to retire retired ACP session", {
+                agentSessionId,
+                error: err instanceof Error ? err.message : String(err),
             });
         }
-        return { sessionId: session.sessionId, configOptions };
     }
-    async loadSession(sessionId, cwd) {
+    async loadSession(taskId, cwd, mcpServers) {
         if (!this.conn)
             throw new Error("Not connected");
+        const agentSessionId = this.agentSessionId(taskId);
         let session;
         try {
             session = await this.conn.loadSession({
-                sessionId,
+                sessionId: agentSessionId,
                 cwd,
-                mcpServers: [],
+                mcpServers: mcpServers ?? [],
             });
         }
         catch (err) {
             // -32002 = Resource not found. Some agents (e.g. claude-agent-acp) don't
-            // persist sessions across process restarts, so a session in our DB may
+            // persist tasks across process restarts, so a session in our DB may
             // be unknown to the live agent. Translate the JSON-RPC error into a
             // user-actionable message; routes returns it as 500 / SSE 'error' event.
             const code = err.code;
             if (code === -32002) {
-                throw new Error(`The agent no longer remembers session ${sessionId.slice(0, 8)}… ` +
+                throw new Error(`The agent no longer remembers task ${taskId.slice(0, 8)}… ` +
                     `(it may not persist sessions across restarts). Use /new to start a fresh one.`, { cause: err });
             }
             throw err;
@@ -141,18 +210,31 @@ export class AgentBridge extends EventEmitter {
         const configOptions = (session.configOptions ??
             []);
         this.emit("event", {
-            type: "session_created",
-            sessionId,
+            type: "task_created",
+            taskId,
             cwd,
+            cwdDisplay: abbreviateHomePath(cwd),
             configOptions,
         });
-        return { sessionId, configOptions };
+        return { taskId, configOptions };
+    }
+    async setConfigOption(taskId, configId, value) {
+        if (!this.conn)
+            throw new Error("Not connected");
+        const result = await this.conn.setSessionConfigOption({
+            sessionId: this.agentSessionId(taskId),
+            configId,
+            ...(typeof value === "boolean"
+                ? { type: "boolean", value }
+                : { value }),
+        });
+        return result.configOptions;
     }
-    async setConfigOption(sessionId, configId, value) {
+    async setAgentConfigOption(agentSessionId, configId, value) {
         if (!this.conn)
             throw new Error("Not connected");
         const result = await this.conn.setSessionConfigOption({
-            sessionId,
+            sessionId: agentSessionId,
             configId,
             ...(typeof value === "boolean"
                 ? { type: "boolean", value }
@@ -160,14 +242,14 @@ export class AgentBridge extends EventEmitter {
         });
         return result.configOptions;
     }
-    async prompt(sessionId, text, attachments, 
+    async prompt(taskId, text, attachments, 
     /** Turn identity echoed back on this prompt's terminal event, so a
      *  completion that outlives its turn can be told apart from the live one. */
     promptId) {
         if (this.deadReason) {
             this.emit("event", {
                 type: "error",
-                sessionId,
+                taskId,
                 message: this.deadReason,
             });
             return;
@@ -178,7 +260,7 @@ export class AgentBridge extends EventEmitter {
         const abortPromise = new Promise((_, rej) => {
             abortReject = rej;
         });
-        this.pendingAborts.set(sessionId, abortReject);
+        this.pendingAborts.set(taskId, abortReject);
         try {
             const promptParts = [];
             if (attachments && attachments.length > 0) {
@@ -189,21 +271,21 @@ export class AgentBridge extends EventEmitter {
                     throw new Error("attachment dispatcher not configured");
                 }
                 for (const ref of attachments) {
-                    const block = await this.attachmentDispatcher.dispatch(sessionId, ref);
-                    promptParts.push(block);
+                    const blocks = await this.attachmentDispatcher.dispatch(taskId, ref);
+                    promptParts.push(...blocks);
                 }
             }
             promptParts.push({ type: "text", text });
             const result = (await Promise.race([
                 this.conn.prompt({
-                    sessionId,
+                    sessionId: this.agentSessionId(taskId),
                     prompt: promptParts,
                 }),
                 abortPromise,
             ]));
             this.emit("event", {
                 type: "prompt_done",
-                sessionId,
+                taskId,
                 stopReason: result.stopReason ?? "end_turn",
                 ...(promptId ? { promptId } : {}),
             });
@@ -217,7 +299,7 @@ export class AgentBridge extends EventEmitter {
             if (/cancel/i.test(message)) {
                 this.emit("event", {
                     type: "prompt_done",
-                    sessionId,
+                    taskId,
                     stopReason: "cancelled",
                     ...(promptId ? { promptId } : {}),
                 });
@@ -225,23 +307,25 @@ export class AgentBridge extends EventEmitter {
             }
             this.emit("event", {
                 type: "error",
-                sessionId,
+                taskId,
                 message,
                 ...(promptId ? { promptId } : {}),
             });
         }
         finally {
-            this.pendingAborts.delete(sessionId);
+            this.pendingAborts.delete(taskId);
         }
     }
-    async cancel(sessionId) {
-        for (const [requestId, requestSessionId] of this
-            .permissionRequestSessions) {
-            if (requestSessionId === sessionId) {
+    async cancel(taskId) {
+        for (const [requestId, requestTaskId] of this.permissionRequestTasks) {
+            if (requestTaskId === taskId) {
                 this.denyPermission(requestId);
             }
         }
-        await this.conn?.cancel({ sessionId });
+        await this.conn?.cancel({ sessionId: this.agentSessionId(taskId) });
+    }
+    async cancelAgentSession(agentSessionId) {
+        await this.conn?.cancel({ sessionId: agentSessionId });
     }
     /**
      * Mark the agent subprocess as dead. Rejects in-flight prompts and emits
@@ -261,10 +345,10 @@ export class AgentBridge extends EventEmitter {
         blog.error("agent subprocess dead", { reason });
         const aborts = [...this.pendingAborts.entries()];
         this.pendingAborts.clear();
-        for (const [sessionId, abort] of aborts) {
+        for (const [taskId, abort] of aborts) {
             this.emit("event", {
                 type: "error",
-                sessionId,
+                taskId,
                 message: reason,
             });
             abort(new Error(reason));
@@ -314,7 +398,7 @@ export class AgentBridge extends EventEmitter {
         if (resolve) {
             resolve({ outcome: { outcome: "selected", optionId } });
             this.permissionResolvers.delete(requestId);
-            this.permissionRequestSessions.delete(requestId);
+            this.permissionRequestTasks.delete(requestId);
         }
     }
     denyPermission(requestId) {
@@ -322,75 +406,75 @@ export class AgentBridge extends EventEmitter {
         if (resolve) {
             resolve({ outcome: { outcome: "cancelled" } });
             this.permissionResolvers.delete(requestId);
-            this.permissionRequestSessions.delete(requestId);
+            this.permissionRequestTasks.delete(requestId);
         }
     }
     /**
      * Restart the agent subprocess. Cancels all active work, cleans up state,
-     * shuts down the old process, and starts a new one. Sessions are restored
+     * shuts down the old process, and starts a new one. Tasks are restored
      * lazily via ensureResumed() on next user interaction.
      */
-    async restart(sessions, titleService) {
+    async restart(tasks) {
         if (this.reloading)
             throw new Error("Already reloading");
         this.reloading = true;
-        const liveSessionIds = [...sessions.liveSessions];
+        const liveTaskIds = [...tasks.liveTasks];
         this.emit("event", { type: "agent_reloading" });
         blog.info("reloading agent...");
         try {
             // 1. Cancel all active prompts + kill bash procs
-            for (const sessionId of [...sessions.activePrompts]) {
-                const proc = sessions.runningBashProcs.get(sessionId);
+            for (const taskId of [...tasks.activePrompts]) {
+                const proc = tasks.runningBashProcs.get(taskId);
                 if (proc) {
                     interruptBashProc(proc);
-                    sessions.runningBashProcs.delete(sessionId);
+                    tasks.runningBashProcs.delete(taskId);
                 }
                 try {
-                    await this.cancel(sessionId);
+                    await this.cancel(taskId);
                 }
                 catch {
                     /* best-effort */
                 }
             }
             // 2. Flush buffers to persist partial content
-            for (const sessionId of liveSessionIds) {
-                sessions.flushBuffers(sessionId);
+            for (const taskId of liveTaskIds) {
+                tasks.flushBuffers(taskId);
             }
-            // 3. Clean up SessionManager state
-            sessions.pendingPermissions.clear();
-            sessions.state.clearPlans();
-            const busySessionIds = new Set([
-                ...sessions.activePrompts,
-                ...sessions.pendingPromptSubmissions.keys(),
+            // 3. Clean up TaskManager state
+            tasks.pendingPermissions.clear();
+            tasks.state.clearPlans();
+            const busyTaskIds = new Set([
+                ...tasks.activePrompts,
+                ...tasks.pendingPromptSubmissions.keys(),
             ]);
-            for (const id of busySessionIds) {
-                sessions.state.patch(id, { runtime: { busy: null } });
+            for (const id of busyTaskIds) {
+                tasks.state.patch(id, { runtime: { busy: null } });
             }
-            for (const submissionId of sessions.pendingPromptSubmissions.values()) {
-                sessions.cancelledPromptSubmissions.add(submissionId);
+            for (const submissionId of tasks.pendingPromptSubmissions.values()) {
+                tasks.cancelledPromptSubmissions.add(submissionId);
             }
-            sessions.activePrompts.clear();
-            sessions.pendingPromptSubmissions.clear();
+            tasks.activePrompts.clear();
+            tasks.pendingPromptSubmissions.clear();
             // 4. Clean up bridge-side silent session state
             this.silentSessions.clear();
             this.silentBuffers.clear();
-            // 5. Invalidate title service session
-            titleService.invalidate();
-            // 5. Clear liveSessions so ensureResumed() will re-register on next access
-            sessions.liveSessions.clear();
+            this.unboundNewSessionIds.clear();
+            this.pendingSessionUpdates.clear();
+            // 5. Clear liveTasks so ensureResumed() will re-register on next access
+            tasks.liveTasks.clear();
             // Also clear the global configOptions cache — a restarted agent may
             // speak a different schema (e.g. agent upgrade removed a model). The
-            // next resumeSession will warm it from the user's stored config.
-            sessions.cachedConfigOptions = [];
+            // next resumeTask will warm it from the user's stored config.
+            tasks.cachedConfigOptions = [];
             // 6. Shutdown old process
             await this.shutdown();
             // Cancellation is asynchronous: the old agent may emit final chunks
             // before shutdown completes. Persist that tail and make the terminal
             // stream state authoritative before starting the replacement process.
-            for (const sessionId of liveSessionIds) {
-                sessions.flushBuffers(sessionId);
+            for (const taskId of liveTaskIds) {
+                tasks.flushBuffers(taskId);
             }
-            sessions.state.clearStreaming();
+            tasks.state.clearStreaming();
             // 7. Start new process with retry (exponential backoff, max 3 attempts)
             let lastError;
             for (let i = 0; i < 3; i++) {
@@ -426,7 +510,7 @@ export class AgentBridge extends EventEmitter {
             resolve({ outcome: { outcome: "cancelled" } });
         }
         this.permissionResolvers.clear();
-        this.permissionRequestSessions.clear();
+        this.permissionRequestTasks.clear();
         const proc = this.proc;
         if (proc && !this.closedProcesses.has(proc)) {
             await new Promise((resolve) => {
@@ -457,6 +541,10 @@ export class AgentBridge extends EventEmitter {
     }
     // --- ACP Client callbacks ---
     handlePermission(params) {
+        const taskId = this.sessionIds.getTaskId(params.sessionId);
+        if (!taskId) {
+            return Promise.resolve({ outcome: { outcome: "cancelled" } });
+        }
         const requestId = crypto.randomUUID();
         const toolCall = params.toolCall;
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- toolCall may be undefined in practice
@@ -467,11 +555,11 @@ export class AgentBridge extends EventEmitter {
         return new Promise((resolve) => {
             // Register resolver BEFORE emitting, so synchronous auto-approve can find it
             this.permissionResolvers.set(requestId, resolve);
-            this.permissionRequestSessions.set(requestId, params.sessionId);
+            this.permissionRequestTasks.set(requestId, taskId);
             this.emit("event", {
                 type: "permission_request",
                 requestId,
-                sessionId: params.sessionId,
+                taskId: taskId,
                 title,
                 toolCallId,
                 options: params.options,
@@ -484,12 +572,26 @@ export class AgentBridge extends EventEmitter {
     }
     handleSessionUpdate(params) {
         const update = params.update;
-        const sessionId = params.sessionId;
-        if (this.silentSessions.has(sessionId)) {
-            this.captureSilentText(sessionId, update);
+        const agentSessionId = params.sessionId;
+        if (this.silentSessions.has(agentSessionId)) {
+            this.captureSilentText(agentSessionId, update);
             return Promise.resolve();
         }
-        const event = this.sessionUpdateToEvent(sessionId, update);
+        const taskId = this.sessionIds.getTaskId(agentSessionId);
+        if (!taskId) {
+            if (this.pendingNewSessions > 0 ||
+                this.unboundNewSessionIds.has(agentSessionId)) {
+                const updates = this.pendingSessionUpdates.get(agentSessionId) ?? [];
+                updates.push(update);
+                this.pendingSessionUpdates.set(agentSessionId, updates);
+                return Promise.resolve();
+            }
+            blog.warn("ignored event for unmapped ACP session", {
+                sessionId: agentSessionId,
+            });
+            return Promise.resolve();
+        }
+        const event = this.sessionUpdateToEvent(taskId, update);
         if (event)
             this.emit("event", event);
         return Promise.resolve();
@@ -501,21 +603,21 @@ export class AgentBridge extends EventEmitter {
             this.silentBuffers.set(sessionId, buf);
         }
     }
-    sessionUpdateToEvent(sessionId, update) {
+    sessionUpdateToEvent(taskId, update) {
         // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- only handles events with UI effects
         switch (update.sessionUpdate) {
             case "agent_message_chunk":
                 return update.content.type === "text"
-                    ? { type: "message_chunk", sessionId, text: update.content.text }
+                    ? { type: "message_chunk", taskId, text: update.content.text }
                     : null;
             case "agent_thought_chunk":
                 return update.content.type === "text"
-                    ? { type: "thought_chunk", sessionId, text: update.content.text }
+                    ? { type: "thought_chunk", taskId, text: update.content.text }
                     : null;
             case "tool_call":
                 return {
                     type: "tool_call",
-                    sessionId,
+                    taskId,
                     id: update.toolCallId,
                     title: update.title,
                     kind: update.kind ?? "unknown",
@@ -524,24 +626,41 @@ export class AgentBridge extends EventEmitter {
             case "tool_call_update":
                 return {
                     type: "tool_call_update",
-                    sessionId,
+                    taskId,
                     id: update.toolCallId,
                     status: update.status ?? "",
                     content: (update.content ?? undefined),
+                    ...(typeof update.title === "string" ? { title: update.title } : {}),
+                    ...(typeof update.kind === "string" ? { kind: update.kind } : {}),
+                    ...(update.rawInput ? { rawInput: update.rawInput } : {}),
+                    ...(Object.hasOwn(update, "rawOutput")
+                        ? { rawOutput: update.rawOutput }
+                        : {}),
+                    ...(Array.isArray(update.locations)
+                        ? { locations: update.locations }
+                        : {}),
                 };
             case "plan":
-                return { type: "plan", sessionId, entries: update.entries };
+                return { type: "plan", taskId, entries: update.entries };
+            case "usage_update":
+                return {
+                    type: "usage_update",
+                    taskId,
+                    used: update.used,
+                    size: update.size,
+                    cost: update.cost,
+                };
             case "config_option_update":
                 return {
                     type: "config_option_update",
-                    sessionId,
+                    taskId,
                     configOptions: update
                         .configOptions ?? [],
                 };
             case "available_commands_update":
                 return {
                     type: "available_commands_update",
-                    sessionId,
+                    taskId,
                     commands: update.availableCommands.map((command) => ({
                         name: command.name,
                         description: command.description,

package/lib/client-registry.js

@@ -48,7 +48,7 @@ export class ClientRegistry {
      *   - Returns `becameVisibleFor=X` only on first transition into
      *     (visible:true, active:X) — heartbeat refreshes return null so
      *     callers can fire edge-triggered side effects exactly once.
-     *   - Session-switch while visible (active X→Y) restarts the TTL clock
+     *   - Task-switch while visible (active X→Y) restarts the TTL clock
      *     even when the patch doesn't carry an explicit visible:true.
      *
      * No-op on unknown client.
@@ -57,7 +57,7 @@ export class ClientRegistry {
         const entry = this.clients.get(id);
         if (!entry)
             return { becameVisibleFor: null };
-        const wasVisibleForSession = entry.visible && entry.active != null ? entry.active : null;
+        const wasVisibleForTask = entry.visible && entry.active != null ? entry.active : null;
         if (patch.visible !== undefined) {
             entry.visible = patch.visible;
             entry.visibleSince = patch.visible ? this.now() : 0;
@@ -67,37 +67,37 @@ export class ClientRegistry {
         }
         const becameVisibleFor = entry.visible &&
             entry.active != null &&
-            entry.active !== wasVisibleForSession
+            entry.active !== wasVisibleForTask
             ? entry.active
             : null;
         if (becameVisibleFor) {
             // Any transition into "visible + active=X" restarts TTL — including
-            // session-switches that arrive without an explicit visible:true.
+            // task-switches that arrive without an explicit visible:true.
             entry.visibleSince = this.now();
         }
         entry.lastSeen = this.now();
         return { becameVisibleFor };
     }
-    /** Is this specific client currently visible & viewing `sessionId` & fresh? */
-    isVisibleForSession(id, sessionId) {
+    /** Is this specific client currently visible & viewing `taskId` & fresh? */
+    isVisibleForTask(id, taskId) {
         const entry = this.clients.get(id);
         if (!entry)
             return false;
         if (!entry.visible)
             return false;
-        if (entry.active !== sessionId)
+        if (entry.active !== taskId)
             return false;
         if (this.now() - entry.visibleSince > this.visibilityTtlMs)
             return false;
         return true;
     }
-    /** Is at least one fresh visible client viewing `sessionId`? */
-    isSessionVisibleToAnyClient(sessionId) {
+    /** Is at least one fresh visible client viewing `taskId`? */
+    isTaskVisibleToAnyClient(taskId) {
         const now = this.now();
         for (const e of this.clients.values()) {
             if (!e.visible)
                 continue;
-            if (e.active !== sessionId)
+            if (e.active !== taskId)
                 continue;
             if (now - e.visibleSince > this.visibilityTtlMs)
                 continue;
@@ -105,7 +105,7 @@ export class ClientRegistry {
         }
         return false;
     }
-    /** Is this specific client currently fresh-visible (any session)? */
+    /** Is this specific client currently fresh-visible (any task)? */
     isClientVisible(id) {
         const entry = this.clients.get(id);
         if (!entry)
@@ -116,7 +116,7 @@ export class ClientRegistry {
             return false;
         return true;
     }
-    /** Is at least one fresh visible client connected (any session)? */
+    /** Is at least one fresh visible client connected (any task)? */
     hasAnyVisibleClient() {
         const now = this.now();
         for (const e of this.clients.values()) {