@beeos-ai/device-agent 0.5.1 → 0.7.0

package/dist/app/session-manager.js

@@ -6,27 +6,57 @@
  * `session/update` envelopes are produced by translating `AgentEvent`s
  * received from the host bus.
  *
- * SessionManager itself is protocol-agnostic w.r.t. the agent core — it
- * speaks `AgentHost` only. The translation of host events into ACP
- * envelopes lives here so swapping `IAgentCore` (single-layer / pi
- * orchestrator / mock) doesn't change ACP semantics.
+ * Persistence model — turn-grained:
  *
- * Surface mirrors the Python `SessionHandler` so ACP handlers remain
- * thin pass-throughs.
+ *   - User prompts persist immediately on entry to `prompt()` (one
+ *     `user_message` JSONL row).
+ *   - Assistant chunks (`task:text`) and tool events (`task:tool`) are
+ *     accumulated in an in-memory `InFlightTurnAggregator`; nothing is
+ *     written until `task:end`, at which point a single
+ *     `assistant_turn` JSONL row captures the entire turn (full text,
+ *     every tool call in invocation order, stop reason, optional
+ *     terminal error). This matches OpenClaw's "one line = one
+ *     complete message" model and avoids the fragmented transcript
+ *     produced by the legacy "one row per chunk" implementation.
+ *
+ * Single-session mode (`fixedSessionId`):
+ *
+ *   When a fixedSessionId is supplied, every ACP session-management
+ *   method (`new`/`load`/`list`/`rename`/`delete`) collapses onto that
+ *   one sid. The mobile/web client receives `multipleSessions: false`
+ *   in the initialize handshake so the UI hides session-switching
+ *   affordances. This is the production configuration for device-agent
+ *   — a single physical device serialises tasks anyway, and a fixed
+ *   sid keeps the JSONL transcript stable across reconnects.
+ *
+ * Replay model — push-style:
+ *
+ *   `session/load` does NOT return history in the RPC `result` (the
+ *   web/mobile SDKs ignore that field). Instead, it pushes one
+ *   `history_turn` envelope per persisted turn followed by an
+ *   in-flight snapshot (streaming-style, WITHOUT `stream_complete`)
+ *   when a task is mid-flight. This matches beeos-claw's
+ *   `handleSessionLoad` exactly so the same chat-store reducer paths
+ *   handle both agents.
  */
 import { randomUUID } from "node:crypto";
 import { newSession } from "../core/session.js";
-import { MessageStore } from "./message-store.js";
+import { MessageStore, } from "./message-store.js";
+import { InFlightTurnAggregator, } from "./in-flight-turn.js";
 export class SessionManager {
     host;
     store;
     notifier;
     onSetModel;
+    fixedSessionId;
     maxSessions;
     sessionTtlMs;
+    pluginCommands;
     sessions = new Map();
     /** taskId → sessionId for routing host events to the right ACP session. */
     taskToSession = new Map();
+    /** Per-task in-flight aggregators. Keyed by taskId. */
+    inFlightByTask = new Map();
     activeSessionId = null;
     currentTask = null;
     unsubscribe = null;
@@ -35,9 +65,18 @@ export class SessionManager {
         this.store = opts.messageStore ?? new MessageStore();
         this.notifier = opts.notifier;
         this.onSetModel = opts.onSetModel;
+        if (opts.fixedSessionId)
+            this.fixedSessionId = opts.fixedSessionId;
         this.maxSessions = opts.maxSessions ?? 50;
         this.sessionTtlMs = opts.sessionTtlMs ?? 60 * 60 * 1000;
+        this.pluginCommands = opts.pluginCommands;
         this.unsubscribe = this.host.on((ev) => this.handleHostEvent(ev));
+        // In single-session mode, eagerly materialise the fixed session so
+        // listSessions / load behave deterministically even before the
+        // first prompt.
+        if (this.fixedSessionId) {
+            this.ensureFixedSession();
+        }
     }
     /** Detach from the host bus (used when shutting down the ACP plugin). */
     detach() {
@@ -48,6 +87,10 @@ export class SessionManager {
     }
     // ── ACP semantics — name mirrors Python SessionHandler ───────────────────
     newSession() {
+        if (this.fixedSessionId) {
+            this.ensureFixedSession();
+            return { sessionId: this.fixedSessionId };
+        }
         this.evictExpired();
         const id = randomUUID();
         this.sessions.set(id, newSession(id));
@@ -55,34 +98,70 @@ export class SessionManager {
         this.store.upsertSession(id);
         return { sessionId: id };
     }
+    /**
+     * Load a session.
+     *
+     * Push-replay model: emit one `history_turn` envelope per persisted
+     * turn so the chat-store sidecar resolver can reconstruct the bubble
+     * graph identically to a fresh streaming run. If a task is currently
+     * in-flight on this sid, additionally emit a streaming-style
+     * snapshot (`agent_message_chunk` + `tool_call` + `tool_call_update`)
+     * WITHOUT the closing `stream_complete` so the client knows the turn
+     * is still active.
+     *
+     * Returns `{ sessionId }` only — the legacy `history` field has been
+     * dropped because no client reads it (see explore audit).
+     */
     loadSession(sessionId) {
-        let id = sessionId;
-        const known = this.sessions.has(id) || this.store.sessionExists(id);
-        if (!known)
-            id = randomUUID();
+        const id = this.aliasSessionId(sessionId);
         if (!this.sessions.has(id))
             this.sessions.set(id, newSession(id));
         const s = this.sessions.get(id);
         s.lastActive = Date.now();
         this.activeSessionId = id;
         this.store.upsertSession(id);
-        return { sessionId: id, history: this.store.getMessagesAsDicts(id, 50) };
+        // (1) Replay every persisted turn.
+        for (const rec of this.store.getTurns(id)) {
+            this.emitHistoryTurn(id, rec);
+        }
+        // (2) Emit in-flight snapshot if a task is still running on this sid.
+        const inflight = this.findInflightForSession(id);
+        if (inflight)
+            this.emitInflightSnapshot(id, inflight);
+        return { sessionId: id };
     }
     listSessions() {
+        if (this.fixedSessionId) {
+            this.ensureFixedSession();
+            return { sessions: this.store.listSessions(50) };
+        }
         this.evictExpired();
         return { sessions: this.store.listSessions(50) };
     }
     renameSession(sessionId, title) {
-        const s = this.sessions.get(sessionId);
+        const id = this.aliasSessionId(sessionId);
+        const s = this.sessions.get(id);
         if (s) {
             s.title = title || s.title;
             s.lastActive = Date.now();
         }
         if (title)
-            this.store.renameSession(sessionId, title);
-        return { sessionId, title };
+            this.store.renameSession(id, title);
+        return { sessionId: id, title };
     }
+    /**
+     * Delete a session.
+     *
+     * In single-session mode, this collapses to `clearSession` because
+     * the one-and-only session can't be removed without losing the
+     * device's identity. Otherwise drops the in-memory + persisted state
+     * for `sessionId`.
+     */
     deleteSession(sessionId) {
+        if (this.fixedSessionId) {
+            this.clearSession(this.fixedSessionId);
+            return { deleted: false };
+        }
         const had = this.sessions.has(sessionId);
         this.sessions.delete(sessionId);
         if (this.activeSessionId === sessionId)
@@ -91,23 +170,30 @@ export class SessionManager {
         return { deleted: had };
     }
     clearSession(sessionId) {
-        const s = this.sessions.get(sessionId);
+        const id = this.aliasSessionId(sessionId);
+        const s = this.sessions.get(id);
         if (s) {
             s.history = [];
             s.lastActive = Date.now();
         }
-        this.store.clearSession(sessionId);
+        this.store.clearSession(id);
+        // Also drop any pending in-flight aggregators that were targeting
+        // this sid — the user explicitly said they want a blank slate.
+        for (const [taskId, sid] of this.taskToSession) {
+            if (sid === id)
+                this.inFlightByTask.delete(taskId);
+        }
         return { cleared: !!s };
     }
     setMode(sessionId, mode) {
-        return { sessionId, mode };
+        return { sessionId: this.aliasSessionId(sessionId), mode };
     }
     async setModel(sessionId, model, provider = "") {
         if (!model)
             throw new Error("model is required");
         if (this.onSetModel)
             await this.onSetModel(provider, model);
-        return { sessionId, provider, model };
+        return { sessionId: this.aliasSessionId(sessionId), provider, model };
     }
     /**
      * Run a prompt to completion and return the ACP `stopReason`.
@@ -122,13 +208,31 @@ export class SessionManager {
         const session = this.resolveSession(sessionIdHint);
         session.lastActive = Date.now();
         session.history.push({ role: "user", content: prompt, createdAt: session.lastActive });
-        this.store.addMessage(session.id, "user", prompt, "text");
         this.activeSessionId = session.id;
+        // Plugin command short-circuit: if the prompt is a /command match,
+        // dispatch straight to the registered handler and skip the
+        // AgentRunner entirely. Mirrors OpenClaw `matchPluginCommand` —
+        // see `openclaw/src/plugins/commands.ts`. Natural-language prompts
+        // ("截屏发给我") flow through unchanged because `match()` only
+        // returns hits for `/`-prefixed text.
+        if (this.pluginCommands) {
+            const matched = this.pluginCommands.match(prompt);
+            if (matched) {
+                return this.handlePluginCommand(prompt, session.id, matched.command, matched.args);
+            }
+        }
         this.notify(session.id, { sessionUpdate: "agent_status", status: "running" });
         const submitted = this.host.submitTask(prompt, { correlationTag: session.id });
         this.taskToSession.set(submitted.taskId, session.id);
         this.currentTask = submitted;
         session.currentTaskId = submitted.taskId;
+        // Persist the user message AFTER taskToSession is wired so a
+        // concurrent loadSession from another connection can see this row
+        // alongside the upcoming in-flight assistant snapshot.
+        // turnId mirrors agent-host's convention (turnId === taskId).
+        this.store.appendUserMessage(session.id, prompt, {
+            turnId: submitted.taskId,
+        });
         let result;
         try {
             result = await submitted.done;
@@ -137,6 +241,10 @@ export class SessionManager {
             this.currentTask = null;
             session.currentTaskId = null;
             this.taskToSession.delete(submitted.taskId);
+            // Belt-and-suspenders: in normal flow `task:end` already
+            // finalised + cleared the in-flight; defend against the agent
+            // crashing without firing task:end.
+            this.inFlightByTask.delete(submitted.taskId);
             this.notify(session.id, { sessionUpdate: "agent_status", status: "idle" });
         }
         return { stopReason: result.cancelled ? "cancelled" : "end_turn" };
@@ -147,60 +255,105 @@ export class SessionManager {
             return false;
         return this.currentTask.cancel();
     }
-    // ── Internal ──────────────────────────────────────────────────────────────
     /**
-     * Translate host `AgentEvent`s into ACP `session/update` envelopes.
+     * Dispatch a `/command` prompt to its registered handler, bypassing
+     * the AgentRunner / LLM. The wire shape stays compatible with the
+     * regular prompt path:
+     *
+     *   1. user message persisted (so reload sees the typed `/screenshot`)
+     *   2. `agent_status: running`
+     *   3. handler runs — typically emits its own `agent_message_chunk`
+     *      with a `resource_link` (see `ScreenshotCommandHandler`)
+     *   4. `stream_complete` + `agent_status: idle`
      *
-     * Handles five legitimate ACP-emitting sources plus structural events:
-     *   - `task:text`      — streamed user-visible reply (agent_message_chunk)
-     *   - `task:reasoning` — streaming "thinking" delta (agent_thought_chunk):
-     *                        planner plan/replan descriptions and per-step
-     *                        VLM rationale.
-     *   - `task:tool`      — start / update / end (tool_call / tool_call_update).
-     *                        `update` carries partial progress for long-running
-     *                        tools (large APK install, long shell streams,
-     *                        large screenshots) so the chat-store tool card
-     *                        can refresh in-place without waiting for `end`.
-     *                        Mirrors beeos-claw's tool_call_update in_progress
-     *                        semantics (see acp-gateway/tool-call-payload-builder.ts).
-     *   - `task:notice`    — out-of-band protocol notice. level=warn
-     *                        (transient retry hints) is dropped — noise
-     *                        the user can't act on. level=error (terminal
-     *                        failure) becomes a `system_message_chunk`
-     *                        with `metadata.kind = "agent_notice"`; the
-     *                        web client merges it into the matching
-     *                        assistant bubble's footer. NOT persisted.
-     *   - `task:step`      — structural step record (no ACP emission, kept
-     *                        for HTTP debug / future plugins).
-     *   - `task:end`       — terminal lifecycle event. We emit the canonical
-     *                        ACP `stream_complete` envelope here (BEFORE the
-     *                        `prompt()` finally block fires `agent_status:
-     *                        "idle"`). chat-store's `applyIncrementalUpdate`
-     *                        relies on `stream_complete` to (a) collapse
-     *                        streaming text part `state` from "streaming"
-     *                        back to "done" so the cursor caret stops
-     *                        rendering, and (b) trim `pendingMap` /
-     *                        `currentAsstId` so history-replay paths don't
-     *                        re-flag the just-finished turn as processing.
-     *                        Without it the bubble caret never collapses
-     *                        and reload paths see a stale `processing`
-     *                        pending — see plan
-     *                        `device-agent_stream_complete_对齐`.
+     * Errors from the handler are converted into a `system_message_chunk`
+     * notice (level=error) instead of crashing the whole session.
      *
-     * Every emitted envelope carries `_turnId` (groups all chunks of a
-     * single user prompt) and `messageId` (the per-task authoritative id
-     * shared by every chunk / thought / tool / notice in this turn). The
-     * web `chat-store` sidecar resolver pins thoughts and tool calls to
-     * the assistant bubble bearing the matching `_messageId`.
+     * NOTE: assistant turns produced by plugin commands are intentionally
+     * NOT persisted — slash command output is time-sensitive (a stale
+     * screenshot helps no one) and the user should re-issue the command
+     * on reconnect. The user-side `/screenshot` text IS persisted so the
+     * conversation log makes sense.
+     */
+    async handlePluginCommand(prompt, sessionId, command, args) {
+        const turnId = randomUUID();
+        // Persist user message first so JSONL on disk survives a crash mid-handler.
+        this.store.appendUserMessage(sessionId, prompt, { turnId });
+        this.notify(sessionId, { sessionUpdate: "agent_status", status: "running" });
+        let stopReason = "end_turn";
+        let errorText;
+        try {
+            await command.handle({ sessionId, args });
+        }
+        catch (e) {
+            stopReason = "error";
+            errorText = e instanceof Error ? e.message : String(e);
+            this.notify(sessionId, {
+                sessionUpdate: "system_message_chunk",
+                content: { type: "text", text: `${command.name}: ${errorText}` },
+                metadata: { kind: "agent_notice", level: "error" },
+                _turnId: turnId,
+            });
+        }
+        finally {
+            const completeUpdate = {
+                sessionUpdate: "stream_complete",
+                stopReason,
+                _turnId: turnId,
+            };
+            if (errorText)
+                completeUpdate.error = errorText;
+            this.notify(sessionId, completeUpdate);
+            this.notify(sessionId, { sessionUpdate: "agent_status", status: "idle" });
+        }
+        return { stopReason };
+    }
+    // ── Internal ──────────────────────────────────────────────────────────────
+    /**
+     * Translate host `AgentEvent`s into ACP `session/update` envelopes
+     * AND accumulate the assistant turn into the in-memory aggregator
+     * for this task. The aggregator is finalised on `task:end` and
+     * persisted as a single `assistant_turn` JSONL row — chunk-level
+     * persistence is intentionally NOT done (it produces fragmented
+     * transcripts that can't be reconstructed cleanly on reload).
      *
-     * Events for tasks not owned by this SessionManager are ignored —
-     * other plugins (HTTP debug, custom) may submit tasks through the
-     * same host bus.
+     * Source events:
+     *   - `task:start`     — allocate the in-flight aggregator.
+     *   - `task:text`      — append delta to in-flight + emit
+     *                        `agent_message_chunk`.
+     *   - `task:reasoning` — emit `agent_thought_chunk` only (NOT
+     *                        persisted — bloats LLM context on resume).
+     *   - `task:tool`      — track in in-flight + emit
+     *                        `tool_call` / `tool_call_update`. Mid-flight
+     *                        progress is forwarded as `in_progress`.
+     *   - `task:notice`    — `warn` is dropped entirely; `error` becomes
+     *                        a `system_message_chunk` with
+     *                        `metadata.kind = "agent_notice"` AND is
+     *                        captured as the in-flight `error` field so
+     *                        the persisted turn carries the failure
+     *                        text.
+     *   - `task:step`      — structural; no ACP emission.
+     *   - `task:end`       — finalise the in-flight, persist a single
+     *                        `assistant_turn` row, emit `stream_complete`
+     *                        BEFORE the closing `agent_status: idle`
+     *                        (chat-store relies on this order).
      */
     handleHostEvent(ev) {
         const sessionId = this.taskToSession.get(ev.taskId);
         if (!sessionId)
             return;
+        if (ev.type === "task:start") {
+            const inflight = InFlightTurnAggregator.start({
+                taskId: ev.taskId,
+                turnId: ev.turnId,
+                // task:start doesn't carry messageId — we'll populate it on
+                // the first text/tool/reasoning event below.
+                messageId: ev.taskId,
+                now: ev.createdAt,
+            });
+            this.inFlightByTask.set(ev.taskId, inflight);
+            return;
+        }
         if (ev.type === "task:text") {
             if (!ev.text)
                 return;
@@ -210,7 +363,8 @@ export class SessionManager {
                 _turnId: ev.turnId,
                 messageId: ev.messageId,
             });
-            this.store.addMessage(sessionId, "assistant", ev.text, "text");
+            const inflight = this.ensureInflight(ev.taskId, ev.turnId, ev.messageId);
+            inflight.appendText(ev.text);
             return;
         }
         if (ev.type === "task:reasoning") {
@@ -218,9 +372,8 @@ export class SessionManager {
             // VLM rationale) flow through the dedicated `agent_thought_chunk`
             // ACP channel so the web UI can render them in the reasoning side
             // panel without polluting the main conversation. We intentionally
-            // do NOT persist reasoning text into MessageStore — it would bloat
-            // the LLM context window on resume and is purely a presentation
-            // signal.
+            // do NOT persist reasoning text — it would bloat the LLM context
+            // window on resume and is purely a presentation signal.
             if (!ev.text)
                 return;
             this.notify(sessionId, {
@@ -233,6 +386,7 @@ export class SessionManager {
         }
         if (ev.type === "task:tool") {
             const t = ev.tool;
+            const inflight = this.ensureInflight(ev.taskId, ev.turnId, ev.messageId);
             if (t.status === "start") {
                 this.notify(sessionId, {
                     sessionUpdate: "tool_call",
@@ -243,21 +397,9 @@ export class SessionManager {
                     _turnId: ev.turnId,
                     messageId: ev.messageId,
                 });
-                this.store.addMessage(sessionId, "assistant", t.name, "tool_call", {
-                    toolCallId: t.id,
-                    parameters: t.args,
-                });
+                inflight.noteToolStart({ id: t.id, name: t.name, args: t.args });
             }
             else if (t.status === "update") {
-                // Mid-flight progress for a long-running tool (large APK install,
-                // streaming shell, large screenshot). Forwarded as
-                // `tool_call_update` with `status: "in_progress"` so chat-store
-                // can refresh the tool card output in-place without waiting for
-                // the terminal `end` event. Mirrors beeos-claw's in_progress
-                // semantics (acp-gateway/tool-call-payload-builder.ts L138-148).
-                // NOT persisted — only the terminal `end` writes a `tool_result`
-                // row to MessageStore so resume context isn't bloated by every
-                // intermediate progress frame.
                 const output = t.result === undefined
                     ? undefined
                     : typeof t.result === "string"
@@ -273,6 +415,7 @@ export class SessionManager {
                 if (output !== undefined)
                     update.output = output;
                 this.notify(sessionId, update);
+                inflight.noteToolUpdate({ id: t.id, ...(output !== undefined ? { output } : {}) });
             }
             else if (t.status === "end") {
                 const status = t.isError ? "failed" : "completed";
@@ -285,7 +428,11 @@ export class SessionManager {
                     _turnId: ev.turnId,
                     messageId: ev.messageId,
                 });
-                this.store.addMessage(sessionId, "assistant", output || `${t.name} ${status}`, "tool_result", { toolCallId: t.id, status });
+                inflight.noteToolEnd({
+                    id: t.id,
+                    output: output || `${t.name} ${status}`,
+                    isError: !!t.isError,
+                });
             }
             return;
         }
@@ -304,17 +451,7 @@ export class SessionManager {
             //     this kind and merges the notice into the matching
             //     assistant bubble's `metadata.notices` (correlated by
             //     `_turnId`), so the user sees a small inline footer line
-            //     instead of a centered gray capsule. Older clients that
-            //     don't know `agent_notice` still render it as a plain
-            //     system message — the kind tag is purely additive.
-            //
-            // Intentionally NOT written to MessageStore — replaying retry
-            // hints / terminal-failure capsules on session resume would
-            // bloat the LLM context with stale degraded-state signals. We
-            // forward `_turnId` for ordering / merge correlation but DROP
-            // `messageId` because chat-store's sidecar resolver would
-            // otherwise still try to merge a system row with assistant
-            // rows sharing that id.
+            //     instead of a centered gray capsule.
             if (ev.level === "warn")
                 return;
             if (!ev.text)
@@ -325,38 +462,35 @@ export class SessionManager {
                 _turnId: ev.turnId,
                 metadata: { kind: "agent_notice", level: ev.level },
             });
+            // Capture the terminal text on the in-flight so the persisted
+            // assistant_turn record carries an `error` field even when the
+            // model produced no final reply.
+            const inflight = this.inFlightByTask.get(ev.taskId);
+            if (inflight)
+                inflight.noteFatalNotice(ev.text);
             return;
         }
         if (ev.type === "task:step") {
-            // `task:step` is a structural event (`{ stepIndex, action, finished,
-            // message }`) consumed by HTTP debug / future plugins. Per-step
-            // rationale is now delivered via `task:reasoning` →
-            // `agent_thought_chunk` (see above), so we no longer mis-emit
-            // `step.thinking` as `agent_message_chunk` here — that double-fire
-            // was leaking VLM rationale into the user-visible reply.
+            // Structural event — consumed by HTTP debug. No ACP emission.
             return;
         }
         if (ev.type === "task:end") {
-            const status = ev.error ? "failed" : ev.result.cancelled ? "cancelled" : "completed";
-            // Emit ACP `stream_complete` BEFORE the `prompt()` finally block
-            // fires `agent_status: "idle"`. Order matters: chat-store treats
-            // `stream_complete` as the canonical "this turn is over" signal
-            // (collapses text part `state: "streaming"` → "done", trims
-            // `pendingMap` / `currentAsstId`). Sending it from the host event
-            // path guarantees it arrives before idle because `task:end` is
-            // dispatched synchronously from `agent-host.runOne` BEFORE the
-            // task's `done` Promise resolves — and the `prompt()` finally is
-            // only entered after `await submitted.done`.
-            //
-            // `stopReason` mirrors beeos-claw's three-valued enum (`end_turn`
-            // / `cancelled` / `error`). The `error` field is forwarded only on
-            // the failure path so chat-store can surface it on the bubble
-            // footer; success / cancel envelopes omit it entirely.
             const stopReason = ev.error
                 ? "error"
                 : ev.result.cancelled
                     ? "cancelled"
                     : "end_turn";
+            // Finalise + persist BEFORE emitting `stream_complete`. This
+            // ordering matters for any concurrent `session/load` that comes
+            // in between `stream_complete` and the prompt's idle signal —
+            // the JSONL row should be on disk by the time we tell the
+            // client the turn is done.
+            const inflight = this.inFlightByTask.get(ev.taskId);
+            if (inflight) {
+                const record = inflight.finalize(stopReason, ev.completedAt);
+                this.store.appendAssistantTurn(sessionId, record);
+                this.inFlightByTask.delete(ev.taskId);
+            }
             const completeUpdate = {
                 sessionUpdate: "stream_complete",
                 stopReason,
@@ -365,13 +499,13 @@ export class SessionManager {
             if (ev.error)
                 completeUpdate.error = ev.error;
             this.notify(sessionId, completeUpdate);
-            this.store.addMessage(sessionId, "system", `Task ${status}`, "status", {
-                taskId: ev.taskId,
-                status,
-            });
         }
     }
     resolveSession(idHint) {
+        if (this.fixedSessionId) {
+            this.ensureFixedSession();
+            return this.sessions.get(this.fixedSessionId);
+        }
         if (idHint && this.sessions.has(idHint))
             return this.sessions.get(idHint);
         if (idHint && this.store.sessionExists(idHint)) {
@@ -384,12 +518,143 @@ export class SessionManager {
         const { sessionId } = this.newSession();
         return this.sessions.get(sessionId);
     }
+    /** Map any sid the client passes onto the canonical sid in fixed mode. */
+    aliasSessionId(sid) {
+        return this.fixedSessionId ?? sid;
+    }
+    /** Materialise the fixed session in-memory + on disk if it isn't yet. */
+    ensureFixedSession() {
+        if (!this.fixedSessionId)
+            return;
+        if (!this.sessions.has(this.fixedSessionId)) {
+            this.sessions.set(this.fixedSessionId, newSession(this.fixedSessionId));
+        }
+        if (!this.store.sessionExists(this.fixedSessionId)) {
+            this.store.upsertSession(this.fixedSessionId);
+        }
+        this.activeSessionId = this.fixedSessionId;
+    }
+    /**
+     * Lazily create an in-flight aggregator for events that arrive
+     * without a preceding `task:start` (defensive — agent-host always
+     * fires start, but tests + alternate adapters may not).
+     */
+    ensureInflight(taskId, turnId, messageId) {
+        let inflight = this.inFlightByTask.get(taskId);
+        if (!inflight) {
+            inflight = InFlightTurnAggregator.start({ taskId, turnId, messageId });
+            this.inFlightByTask.set(taskId, inflight);
+        }
+        return inflight;
+    }
+    findInflightForSession(sessionId) {
+        for (const [taskId, sid] of this.taskToSession) {
+            if (sid !== sessionId)
+                continue;
+            const inflight = this.inFlightByTask.get(taskId);
+            if (inflight)
+                return inflight;
+        }
+        return null;
+    }
+    /**
+     * Emit a single persisted record as a `history_turn` envelope.
+     *
+     * Mirrors beeos-claw `bridge-core.replayAssistantTurnAsStream` —
+     * `history_turn` is a stamped-done snapshot of an entire turn that
+     * the chat-store reducer renders as a complete bubble (no streaming
+     * cursor). For assistant turns, we serialise tool calls into the
+     * shape `apply-update.buildToolCalls` accepts.
+     */
+    emitHistoryTurn(sessionId, rec) {
+        if (rec.type === "user_message") {
+            const update = {
+                sessionUpdate: "history_turn",
+                role: "user",
+                content: rec.content,
+                timestamp: new Date(rec.ts).toISOString(),
+            };
+            if (rec.messageId)
+                update.messageId = rec.messageId;
+            if (rec.turnId)
+                update._turnId = rec.turnId;
+            this.notify(sessionId, update);
+            return;
+        }
+        // assistant_turn
+        const turn = rec;
+        const toolCalls = turn.toolCalls.map((tc) => ({
+            id: tc.id,
+            name: tc.name,
+            arguments: typeof tc.args === "string" ? tc.args : JSON.stringify(tc.args ?? {}),
+            status: tc.status,
+            ...(tc.output !== undefined ? { output: tc.output } : {}),
+            isError: tc.status === "failed",
+        }));
+        const update = {
+            sessionUpdate: "history_turn",
+            role: "assistant",
+            content: turn.text,
+            timestamp: new Date(turn.ts).toISOString(),
+            messageId: turn.messageId,
+            _turnId: turn.turnId,
+        };
+        if (toolCalls.length > 0)
+            update.toolCalls = toolCalls;
+        if (turn.error)
+            update.metadata = { error: turn.error };
+        this.notify(sessionId, update);
+    }
+    /**
+     * Emit the current state of an in-flight turn as streaming-style
+     * envelopes WITHOUT the closing `stream_complete`. The client uses
+     * the absence of `stream_complete` to recognise the turn is still
+     * generating, matching beeos-claw's `emitCurrentStreamSnapshot`.
+     */
+    emitInflightSnapshot(sessionId, inflight) {
+        const text = inflight.currentText();
+        if (text) {
+            this.notify(sessionId, {
+                sessionUpdate: "agent_message_chunk",
+                content: { type: "text", text },
+                _turnId: inflight.turnId,
+                messageId: inflight.messageId,
+            });
+        }
+        for (const tc of inflight.currentToolCalls()) {
+            this.notify(sessionId, {
+                sessionUpdate: "tool_call",
+                toolCallId: tc.id,
+                title: tc.name,
+                arguments: JSON.stringify(tc.args),
+                status: "in_progress",
+                _turnId: inflight.turnId,
+                messageId: inflight.messageId,
+            });
+            if (tc.status !== "in_progress") {
+                const update = {
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: tc.id,
+                    status: tc.status,
+                    _turnId: inflight.turnId,
+                    messageId: inflight.messageId,
+                };
+                if (tc.output !== undefined)
+                    update.output = tc.output;
+                this.notify(sessionId, update);
+            }
+        }
+        // Deliberately do NOT emit `stream_complete` — its absence is the
+        // signal the client uses to recognise a still-generating turn.
+    }
     notify(sessionId, update) {
         if (!this.notifier)
             return;
         this.notifier.send(sessionId, update);
     }
     evictExpired() {
+        if (this.fixedSessionId)
+            return;
         const now = Date.now();
         for (const [id, s] of this.sessions) {
             if (now - s.lastActive > this.sessionTtlMs) {
@@ -417,9 +682,7 @@ export class SessionManager {
  * `resource_link` URIs are preserved verbatim on their own line at the
  * end of the merged prompt, so the Resource Resolution Layer's parsers
  * (`UrlParser`, `BeeosFileParser`) can pick them up without any extra
- * out-of-band channel. This is the single ACP integration point — every
- * "the agent has access to a user-supplied resource" path goes through
- * here.
+ * out-of-band channel.
  */
 function normalizePrompt(raw) {
     if (typeof raw === "string")