Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(transcript): SSE re-attach via OpenClaw sessions.messages.subscribe

Yuting Zhongb7aed7a0dd2b
diff --git a/src/app/api/agents/[agent]/threads/[thread]/live/route.ts b/src/app/api/agents/[agent]/threads/[thread]/live/route.ts
new file mode 100644
index 00000000..0fac2808
--- /dev/null
+++ b/src/app/api/agents/[agent]/threads/[thread]/live/route.ts
@@ -0,0 +1,171 @@
+import { NextResponse } from "next/server";
+
+import { getActiveProject } from "@/server/active-project";
+import { resolveAgentBySlug } from "@/server/agent-meta";
+import { getProject } from "@/server/db/projects";
+import { GatewayClient } from "@/server/openclaw/gateway-client";
+import {
+ buildPendingSessionKey,
+ findSessionBySessionId,
+} from "@/server/openclaw/sessions";
+import {
+ rawEntryToEvents,
+ type RawEntry,
+} from "@/server/openclaw/transcript-tail";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+/**
+ * SSE bridge that re-attaches to an in-progress OpenClaw session and
+ * forwards transcript events live. Bypasses the JSONL-flush latency:
+ * OpenClaw buffers session.jsonl until session.ended, so polling
+ * /api/agents/.../threads/.../transcript sees nothing mid-turn. This
+ * endpoint instead subscribes via `sessions.messages.subscribe` over
+ * the WS gateway and forwards every `session.message` event as SSE.
+ *
+ * Used by the LiveTranscript component for in-flight tasks (especially
+ * audit tasks that were auto-kicked-off server-side via the
+ * blocked-by-task propagation hook — those have no /api/chat SSE
+ * channel and would otherwise look "stuck" until JSONL flushes).
+ *
+ * Lifecycle:
+ * - Resolves agent_full_id from the project's roster.
+ * - Resolves the session key from threadId (the URL "label" segment
+ * of OpenClaw's `agent:<agent>:<label>` keying).
+ * - Opens a fresh GatewayClient (NOT the shared one — re-attach is
+ * long-lived and would block other callers if it shared the
+ * handshake), subscribes, listens, forwards.
+ * - On client disconnect (browser close, navigation): tears down the
+ * subscription and closes the gateway WS so we don't leak.
+ */
+export async function GET(
+ request: Request,
+ { params }: { params: Promise<{ agent: string; thread: string }> },
+): Promise<Response> {
+ const { agent: agentSlug, thread: threadId } = await params;
+
+ const url = new URL(request.url);
+ const projectSlug = url.searchParams.get("project");
+ const projectRow = projectSlug ? getProject(projectSlug) : await getActiveProject();
+ if (!projectRow || projectRow.archived_at) {
+ return NextResponse.json({ error: "Unknown project" }, { status: 404 });
+ }
+ const resolved = await resolveAgentBySlug(projectRow.slug, agentSlug);
+ if (!resolved) {
+ return NextResponse.json({ error: "Unknown agent" }, { status: 404 });
+ }
+ const agentFullId = resolved.agent_id;
+
+ // Resolve session key. If OpenClaw doesn't have a session row yet
+ // (brand-new thread — first message hasn't been sent), fall back to
+ // the pending key shape. Subscribing to a not-yet-existing session is
+ // a no-op from the gateway's side; events will start flowing as soon
+ // as the session is created.
+ const sessionRow = findSessionBySessionId(agentFullId, threadId);
+ const sessionKey =
+ sessionRow?.sessionKey ?? buildPendingSessionKey(agentFullId, threadId);
+
+ const encoder = new TextEncoder();
+ let evtCounter = 0;
+
+ const stream = new ReadableStream<Uint8Array>({
+ async start(controller) {
+ let client: GatewayClient | null = null;
+ let removeListener: (() => void) | null = null;
+ let closed = false;
+
+ function send(event: string, data: unknown): void {
+ if (closed) return;
+ try {
+ controller.enqueue(
+ encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
+ );
+ } catch {
+ // Stream already torn down; ignore.
+ }
+ }
+
+ function teardown(): void {
+ if (closed) return;
+ closed = true;
+ removeListener?.();
+ // Best-effort unsubscribe; gateway times the subscription out
+ // anyway when the WS closes.
+ if (client?.isOpen()) {
+ void client.request("sessions.messages.unsubscribe", {
+ key: sessionKey,
+ }).catch(() => {});
+ }
+ try {
+ client?.close();
+ } catch {}
+ try {
+ controller.close();
+ } catch {}
+ }
+
+ request.signal.addEventListener("abort", teardown);
+
+ try {
+ client = new GatewayClient();
+ await client.open();
+ removeListener = client.addEventListener((evt) => {
+ if (evt.event !== "session.message") return;
+ const payload = evt.payload as
+ | {
+ sessionKey?: string;
+ message?: unknown;
+ messageId?: string;
+ messageSeq?: number;
+ }
+ | undefined;
+ if (!payload) return;
+ // Filter cross-session noise — subscriptions are scoped but the
+ // gateway broadcasts on a shared listener pool.
+ if (payload.sessionKey !== sessionKey) return;
+
+ // The `message` payload mirrors the JSONL "message" field; wrap
+ // it in a RawEntry so the shared parser produces the same shape
+ // the polling path emits. Stable id from messageId/seq keeps
+ // the client-side dedup honest (the same event can land via
+ // SSE here AND via polling once JSONL flushes).
+ const idHint =
+ payload.messageId ??
+ (typeof payload.messageSeq === "number"
+ ? `msg-${payload.messageSeq}`
+ : `sse-${evtCounter++}`);
+ const raw: RawEntry = {
+ type: "message",
+ id: idHint,
+ message: payload.message as RawEntry["message"],
+ };
+ const events = rawEntryToEvents(raw, idHint);
+ if (events.length === 0) return;
+ send("transcript", { events });
+ });
+
+ // Subscribe + send a hello so the client knows the bridge is live.
+ await client.request("sessions.messages.subscribe", { key: sessionKey });
+ send("ready", { sessionKey });
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ send("error", { message });
+ teardown();
+ }
+ },
+ cancel() {
+ // Browser closed the EventSource — nothing else to do; the abort
+ // signal handler already runs teardown.
+ },
+ });
+
+ return new Response(stream, {
+ headers: {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache, no-transform",
+ Connection: "keep-alive",
+ "X-Accel-Buffering": "no",
+ },
+ });
+}
diff --git a/src/components/live-transcript.tsx b/src/components/live-transcript.tsx
index a8d0f3a8..ad093e22 100644
--- a/src/components/live-transcript.tsx
+++ b/src/components/live-transcript.tsx
@@ -276,6 +276,65 @@ export function LiveTranscript({
};
}, [pollIntervalMs, pollOnce, sendingChat, stopPolling]);
+ // ── Live re-attach: SSE bridge to OpenClaw's sessions.messages stream. ─
+ // OpenClaw buffers session JSONL until session.ended, so the polling
+ // path above sees nothing mid-turn. For an in-flight task (especially
+ // one auto-kicked-off server-side without a /api/chat SSE channel),
+ // this re-attaches to the gateway and forwards every session.message
+ // event live. Same dedup set as polling, so events that later land in
+ // JSONL don't double-render.
+ //
+ // Skipped during an active /api/chat send — that path already streams
+ // its own deltas; layering re-attach on top would just duplicate work.
+ useEffect(() => {
+ if (!composerDisabled) return;
+ if (sendingChat) return;
+ if (stopPolling) return;
+ // jsdom (vitest) doesn't ship EventSource. Skip the bridge there so
+ // component tests don't blow up; polling-path coverage stays intact.
+ if (typeof EventSource === "undefined") return;
+ const url = `/api/agents/${agentSlug}/threads/${threadId}/live?project=${encodeURIComponent(projectSlug)}`;
+ const es = new EventSource(url);
+ es.addEventListener("transcript", (e: MessageEvent) => {
+ try {
+ const data = JSON.parse(e.data) as { events: TranscriptEvent[] };
+ if (!Array.isArray(data.events)) return;
+ const fresh = data.events.filter(
+ (ev) => !seenEventIdsRef.current.has(ev.id),
+ );
+ for (const ev of fresh) seenEventIdsRef.current.add(ev.id);
+ if (fresh.length > 0) {
+ setEvents((prev) => [...prev, ...fresh]);
+ // Live events arrived: clear any optimistic placeholders for
+ // active sends + reset the "I'm waiting" indicator state.
+ setPendingUserMsg(null);
+ setPendingAssistant("");
+ setPendingTools([]);
+ setPendingError(null);
+ setPendingLifecycle(null);
+ }
+ } catch {
+ // Malformed payload; skip silently.
+ }
+ });
+ es.addEventListener("error", () => {
+ // EventSource auto-reconnects on transient drops; nothing else
+ // needed here. If the server actually returned an error response
+ // (4xx/5xx), reconnect attempts will keep failing and the source
+ // closes itself — polling continues regardless.
+ });
+ return () => {
+ es.close();
+ };
+ }, [
+ agentSlug,
+ composerDisabled,
+ projectSlug,
+ sendingChat,
+ stopPolling,
+ threadId,
+ ]);
+
// ── Send: optimistic user message + SSE-driven streaming reply. ─────
const send = useCallback(
async (overrideText?: string, opts: { hidden?: boolean } = {}) => {
diff --git a/src/server/openclaw/transcript-tail.ts b/src/server/openclaw/transcript-tail.ts
index 98d2e9ef..8af8e020 100644
--- a/src/server/openclaw/transcript-tail.ts
+++ b/src/server/openclaw/transcript-tail.ts
@@ -65,7 +65,7 @@ type RawMessage = {
isError?: boolean;
};
-type RawEntry = {
+export type RawEntry = {
type?: string;
id?: string;
timestamp?: string | number;
@@ -147,105 +147,109 @@ export function readTranscriptTail(
} catch {
continue;
}
- const baseId = `${entry.id ?? "anon"}-${lineIdx++}`;
- const ts =
- typeof entry.timestamp === "string"
- ? Date.parse(entry.timestamp)
- : typeof entry.timestamp === "number"
- ? entry.timestamp
- : 0;
+ events.push(...rawEntryToEvents(entry, `${entry.id ?? "anon"}-${lineIdx++}`));
+ }
- if (entry.type !== "message") {
- // Session metadata, model-config rows, etc. Surface as a faint
- // "unknown" event the client can hide unless verbose mode is on.
- events.push({ kind: "unknown", id: baseId, ts, raw_type: entry.type ?? "?" });
- continue;
+ return { events, byteOffset: newByteOffset, fileSize: size };
+}
+
+/**
+ * Convert one raw JSONL entry (or session.message broadcast payload) into
+ * the TranscriptEvents we render. Extracted so the SSE re-attach bridge
+ * (which receives `session.message` events from the gateway) can produce
+ * the same shapes the polling path already emits.
+ */
+export function rawEntryToEvents(entry: RawEntry, baseId: string): TranscriptEvent[] {
+ const events: TranscriptEvent[] = [];
+ const ts =
+ typeof entry.timestamp === "string"
+ ? Date.parse(entry.timestamp)
+ : typeof entry.timestamp === "number"
+ ? entry.timestamp
+ : 0;
+
+ if (entry.type !== "message") {
+ events.push({ kind: "unknown", id: baseId, ts, raw_type: entry.type ?? "?" });
+ return events;
+ }
+ const msg = entry.message;
+ if (!msg) return events;
+
+ if (msg.role === "user") {
+ const body = extractUserText(msg.content);
+ if (!body) return events;
+ events.push({ kind: "user_message", id: baseId, ts, body });
+ return events;
+ }
+ if (msg.role === "toolResult") {
+ const callId = msg.toolCallId ?? "";
+ const name = msg.toolName ?? "tool";
+ const ok = !msg.isError;
+ const summary = summarizeToolResult(msg.content);
+ if (callId) {
+ events.push({
+ kind: "tool_result",
+ id: baseId,
+ ts,
+ tool_call_id: callId,
+ name,
+ summary,
+ ok,
+ });
}
- const msg = entry.message;
- if (!msg) continue;
+ return events;
+ }
+ if (msg.role !== "assistant") return events;
- if (msg.role === "user") {
- const body = extractUserText(msg.content);
- if (!body) continue;
- events.push({ kind: "user_message", id: baseId, ts, body });
+ const parts = Array.isArray(msg.content) ? msg.content : [];
+ let partIdx = 0;
+ for (const part of parts) {
+ const partId = `${baseId}:${partIdx++}`;
+ if (typeof part === "string") {
+ if (part.trim()) {
+ events.push({ kind: "assistant_text", id: partId, ts, body: part });
+ }
continue;
}
- // Tool results land as their own top-level message with role "toolResult".
- // We don't render them as a standalone row — collapseToolPairs in the
- // client matches them by tool_call_id to flip the prior tool_call from
- // spinner → check.
- if (msg.role === "toolResult") {
- const callId = msg.toolCallId ?? "";
- const name = msg.toolName ?? "tool";
- const ok = !msg.isError;
- const summary = summarizeToolResult(msg.content);
- if (callId) {
- events.push({
- kind: "tool_result",
- id: baseId,
- ts,
- tool_call_id: callId,
- name,
- summary,
- ok,
- });
+ if (part?.type === "text") {
+ const text = (part.text ?? "").trim();
+ if (text) {
+ events.push({ kind: "assistant_text", id: partId, ts, body: text });
}
continue;
}
- if (msg.role !== "assistant") continue;
-
- // Assistant: content is an array of parts. Each part becomes one event.
- const parts = Array.isArray(msg.content) ? msg.content : [];
- let partIdx = 0;
- for (const part of parts) {
- const partId = `${baseId}:${partIdx++}`;
- if (typeof part === "string") {
- if (part.trim()) {
- events.push({ kind: "assistant_text", id: partId, ts, body: part });
- }
- continue;
- }
- if (part?.type === "text") {
- const text = (part.text ?? "").trim();
- if (text) {
- events.push({ kind: "assistant_text", id: partId, ts, body: text });
- }
- continue;
- }
- if (part?.type === "toolCall") {
- const callId = part.id ?? partId;
- const name = part.name ?? "tool";
- const label = formatToolLabel(name, part.arguments ?? part.input);
- events.push({
- kind: "tool_call",
- id: partId,
- ts,
- tool_call_id: callId,
- name,
- label,
- });
- continue;
- }
- if (part?.type === "toolResult") {
- const callId = part.toolCallId ?? part.tool_call_id ?? partId;
- const name = part.name ?? "tool";
- const ok = !(part.isError ?? part.is_error ?? false);
- const summary = summarizeToolResult(part.content ?? part.output);
- events.push({
- kind: "tool_result",
- id: partId,
- ts,
- tool_call_id: callId,
- name,
- summary,
- ok,
- });
- continue;
- }
+ if (part?.type === "toolCall") {
+ const callId = part.id ?? partId;
+ const name = part.name ?? "tool";
+ const label = formatToolLabel(name, part.arguments ?? part.input);
+ events.push({
+ kind: "tool_call",
+ id: partId,
+ ts,
+ tool_call_id: callId,
+ name,
+ label,
+ });
+ continue;
+ }
+ if (part?.type === "toolResult") {
+ const callId = part.toolCallId ?? part.tool_call_id ?? partId;
+ const name = part.name ?? "tool";
+ const ok = !(part.isError ?? part.is_error ?? false);
+ const summary = summarizeToolResult(part.content ?? part.output);
+ events.push({
+ kind: "tool_result",
+ id: partId,
+ ts,
+ tool_call_id: callId,
+ name,
+ summary,
+ ok,
+ });
+ continue;
}
}
-
- return { events, byteOffset: newByteOffset, fileSize: size };
+ return events;
}
function extractUserText(content: RawMessage["content"]): string {