Skip to content

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

feat(chat): stream live tool/MCP invocations as inline step rows

Yuting Zhong9b8c5b538932
diff --git a/src/app/api/chat/route.ts b/src/app/api/chat/route.ts
index ab91621d..459c31c5 100644
--- a/src/app/api/chat/route.ts
+++ b/src/app/api/chat/route.ts
@@ -140,6 +140,17 @@ export async function POST(request: Request) {
perf.mark("first_sse_delta_sent");
}
send("text", { chunk: evt.text });
+ } else if (evt.kind === "tool") {
+ // tool start/update/result — keyed by toolCallId so the client
+ // can update the matching step row instead of appending a new one.
+ send("tool", {
+ phase: evt.phase,
+ tool_call_id: evt.toolCallId,
+ name: evt.name,
+ label: evt.label,
+ });
+ } else if (evt.kind === "lifecycle") {
+ send("lifecycle", { phase: evt.phase });
} else if (evt.kind === "error") {
send("error", { message: evt.message });
}
diff --git a/src/components/agent-chat.tsx b/src/components/agent-chat.tsx
index 1ce1f413..f3ab6834 100644
--- a/src/components/agent-chat.tsx
+++ b/src/components/agent-chat.tsx
@@ -2,7 +2,18 @@
import { useLayoutEffect, useMemo, useRef, useState, useTransition } from "react";
import { useRouter } from "next/navigation";
-import { Send, AlertCircle, StopCircle } from "lucide-react";
+import {
+ Send,
+ AlertCircle,
+ StopCircle,
+ Loader2,
+ CheckCircle2,
+ Terminal,
+ FileText,
+ Edit3,
+ Globe,
+ Wrench,
+} from "lucide-react";
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";
import { toast } from "sonner";
@@ -15,10 +26,27 @@ import {
import { SlashCommandPopover } from "./slash-command-popover";
import { Markdown } from "./markdown";
+type Step = {
+ /** Stable per-invocation id from OpenClaw, used to update in-place. */
+ toolCallId: string;
+ /** Raw tool name (e.g. "exec", "read", "edit", "mcp:foo.bar"). */
+ name: string;
+ /** Pre-formatted one-liner from the server (command / path / etc.). */
+ label?: string;
+ /** start | update | result — drives the spinner vs check icon. */
+ phase: "start" | "update" | "result";
+};
+
type Message = {
id: string;
role: "user" | "assistant" | "error";
body: string;
+ /**
+ * Tool/MCP invocations the agent made before/while producing this reply,
+ * surfaced inline so the user can watch what's happening instead of
+ * staring at "thinking…". Empty on user/error rows.
+ */
+ steps?: Step[];
};
export type InitialMessage = {
@@ -228,6 +256,56 @@ export function AgentChat({
msg.id === assistantId ? { ...msg, body: msg.body + chunk } : msg,
),
);
+ } else if (evt === "tool") {
+ // Live tool/MCP invocation. Update in place by toolCallId so a
+ // start→result pair becomes one row that flips from spinner to
+ // check, rather than two separate rows.
+ const d = data as {
+ phase: "start" | "update" | "result";
+ tool_call_id: string;
+ name: string;
+ label?: string;
+ };
+ // Treat the first tool event as "we have visible progress" so the
+ // empty-reply branch below doesn't blow away the step list with
+ // the "(command handled by OpenClaw, no reply)" placeholder.
+ receivedText = true;
+ setMessages((m) =>
+ m.map((msg) => {
+ if (msg.id !== assistantId) return msg;
+ const existing = msg.steps ?? [];
+ const idx = existing.findIndex((s) => s.toolCallId === d.tool_call_id);
+ if (idx < 0) {
+ return {
+ ...msg,
+ steps: [
+ ...existing,
+ {
+ toolCallId: d.tool_call_id,
+ name: d.name,
+ label: d.label,
+ phase: d.phase,
+ },
+ ],
+ };
+ }
+ const next = existing.slice();
+ next[idx] = {
+ ...next[idx],
+ name: d.name,
+ // Label only arrives on "start"; preserve it on update/result.
+ label: d.label ?? next[idx].label,
+ phase: d.phase,
+ };
+ return { ...msg, steps: next };
+ }),
+ );
+ } else if (evt === "lifecycle") {
+ // Lifecycle markers (start/end/error) don't render today — the
+ // spinner on the assistant bubble already conveys "in progress"
+ // and the closing of the SSE stream marks the end. Reserved for
+ // future use (e.g. compaction toasts) so we accept-and-ignore
+ // rather than logging an "unknown event" warning.
} else if (evt === "perf") {
perf.recordServer(
(data as { marks: Array<{ name: string; at: number; delta: number }> })
@@ -459,22 +537,70 @@ function MessageRow({
// streaming, partial markdown (e.g. an unclosed fence) is rendered as far as
// remark can parse it — visually fine because the next chunk arrives within
// milliseconds.
- if (message.body === "") {
- return (
- <div className="group">
- <div className="text-sm italic text-muted-foreground">
- {`${agentDisplayName} is thinking…`}
- </div>
- </div>
- );
- }
+ const hasSteps = (message.steps?.length ?? 0) > 0;
+ const isEmpty = message.body === "";
return (
- <div className="group">
- <Markdown>{message.body}</Markdown>
+ <div className="group space-y-2">
+ {hasSteps && <StepList steps={message.steps!} />}
+ {isEmpty ? (
+ !hasSteps && (
+ <div className="text-sm italic text-muted-foreground">
+ {`${agentDisplayName} is thinking…`}
+ </div>
+ )
+ ) : (
+ <Markdown>{message.body}</Markdown>
+ )}
</div>
);
}
+function StepList({ steps }: { steps: Step[] }) {
+ return (
+ <div className="space-y-1 rounded-md border bg-muted/30 px-3 py-2">
+ {steps.map((s) => (
+ <StepRow key={s.toolCallId} step={s} />
+ ))}
+ </div>
+ );
+}
+
+function StepRow({ step }: { step: Step }) {
+ const Icon = iconForTool(step.name);
+ const done = step.phase === "result";
+ return (
+ <div className="flex items-center gap-2 text-xs">
+ <span className="flex size-4 shrink-0 items-center justify-center text-muted-foreground">
+ {done ? (
+ <CheckCircle2 className="size-3.5 text-emerald-600" />
+ ) : (
+ <Loader2 className="size-3.5 animate-spin" />
+ )}
+ </span>
+ <Icon className="size-3.5 shrink-0 text-muted-foreground" />
+ <span className="font-mono text-[11px] font-medium text-foreground">
+ {step.name}
+ </span>
+ {step.label && (
+ <span className="truncate font-mono text-[11px] text-muted-foreground">
+ {step.label}
+ </span>
+ )}
+ </div>
+ );
+}
+
+function iconForTool(name: string) {
+ // Match icons to OpenClaw's built-in tool kinds. Anything else (MCP tools,
+ // plugin tools) falls through to the generic Wrench icon.
+ const n = name.toLowerCase();
+ if (n === "exec" || n === "shell" || n.includes("bash")) return Terminal;
+ if (n === "read" || n === "cat" || n === "open") return FileText;
+ if (n === "write" || n === "edit" || n === "patch") return Edit3;
+ if (n === "fetch" || n.includes("http") || n.includes("web")) return Globe;
+ return Wrench;
+}
+
function formatAgentError(raw: string): string {
if (raw.includes("missing scope")) {
return `${raw}\n\nHint: this OpenClaw slash command requires a permission your gateway token does not grant. Use the “New thread” button above for new conversations.`;
diff --git a/src/server/openclaw/gateway-client.ts b/src/server/openclaw/gateway-client.ts
index 7484a0cd..0eb91561 100644
--- a/src/server/openclaw/gateway-client.ts
+++ b/src/server/openclaw/gateway-client.ts
@@ -192,7 +192,12 @@ export class GatewayClient {
},
role: "operator",
scopes: this.scopes,
- caps: [],
+ // "tool-events" opts us into the tool-event broadcast stream. Without
+ // this, the gateway gates those frames per `server-methods/chat.ts`
+ // (`registerToolEventRecipient` only fires when the cap is present), so
+ // the whole `stream:"tool"` channel goes dark — even though everything
+ // else (assistant deltas, lifecycle, chat) still arrives.
+ caps: ["tool-events"],
...(this.cfg.token || this.cfg.password
? { auth: { token: this.cfg.token, password: this.cfg.password } }
: {}),
@@ -296,6 +301,29 @@ export type ChatPerf = {
export type ChatStreamEvent =
| { kind: "delta"; text: string }
+ | {
+ kind: "tool";
+ /**
+ * OpenClaw emits start → (update*) → result for each tool invocation.
+ * We surface all three so the UI can show in-progress + final state.
+ */
+ phase: "start" | "update" | "result";
+ /** Stable id per tool invocation; lets the UI update the right row. */
+ toolCallId: string;
+ /** Raw tool name (e.g. "exec", "read", "edit", or "mcp:foo.bar"). */
+ name: string;
+ /**
+ * Human-readable one-liner the UI shows next to the tool name
+ * (e.g. command for exec, path for read/write). Pre-computed on the
+ * server so the client doesn't need to know every tool's args shape.
+ */
+ label?: string;
+ }
+ | {
+ kind: "lifecycle";
+ /** "start" | "end" | "error" — useful for UI heartbeat / "agent is working". */
+ phase: string;
+ }
| { kind: "final"; text: string }
| { kind: "error"; message: string };
@@ -398,17 +426,56 @@ export async function* streamChatViaGateway(
state?: string;
deltaText?: string;
replace?: boolean;
- data?: { delta?: string; text?: string; replace?: boolean };
+ data?: {
+ delta?: string;
+ text?: string;
+ replace?: boolean;
+ phase?: string;
+ name?: string;
+ toolCallId?: string;
+ args?: unknown;
+ };
message?: { content?: Array<{ type?: string; text?: string }> };
}
| undefined;
- if (!payload || payload.runId !== runId) return;
+ if (!payload) return;
+ // Filter by sessionKey, not runId: OpenClaw's tool/lifecycle/assistant
+ // events carry the *engine* runId, which is distinct from the
+ // idempotencyKey we pass in chat.send. Per the OpenClaw web UI
+ // (`ui/src/ui/app-tool-stream.ts`), session is the only reliable key.
+ // Runs are serialized per session, so only one turn is in flight here.
+ if (payload.sessionKey && payload.sessionKey !== input.sessionKey) return;
if (!firstEventSeen) {
firstEventSeen = true;
perf?.mark("gw_first_event");
}
+ if (evt.event === "agent" && payload.stream === "tool") {
+ const d = payload.data ?? {};
+ const toolCallId = typeof d.toolCallId === "string" ? d.toolCallId : "";
+ if (!toolCallId) return;
+ const phase = d.phase === "start" || d.phase === "update" || d.phase === "result"
+ ? d.phase
+ : null;
+ if (!phase) return;
+ const name = typeof d.name === "string" ? d.name : "tool";
+ const label = phase === "start" ? labelForTool(name, d.args) : undefined;
+ events.push({ kind: "tool", phase, toolCallId, name, label });
+ wake();
+ return;
+ }
+
+ if (evt.event === "agent" && payload.stream === "lifecycle") {
+ const d = payload.data ?? {};
+ const phase = typeof d.phase === "string" ? d.phase : payload.state;
+ if (phase) {
+ events.push({ kind: "lifecycle", phase });
+ wake();
+ }
+ return;
+ }
+
if (evt.event === "agent" && payload.stream === "assistant") {
const d = payload.data ?? {};
if (d.replace === true && typeof d.text === "string") {
@@ -506,6 +573,65 @@ export async function* streamChatViaGateway(
}
}
+/**
+ * Compress a tool invocation's args into a single human-readable label.
+ * Matches the spirit of OpenClaw's menu-bar status text (`exec: pnpm test`,
+ * `read: apps/foo.ts`) so the chat UI feels familiar to anyone who's seen
+ * the desktop app. Falls back to the bare tool name when nothing useful
+ * can be extracted.
+ */
+function labelForTool(name: string, args: unknown): string | undefined {
+ if (!args || typeof args !== "object") return undefined;
+ const a = args as Record<string, unknown>;
+ // exec / shell: show the first line of the command
+ const cmd = pickString(a, ["command", "cmd", "script"]);
+ if (cmd) return firstLine(cmd);
+ // file ops: show the path
+ const path = pickString(a, ["path", "file_path", "filename", "file"]);
+ if (path) return shortenPath(path);
+ // web fetches: show the URL
+ const url = pickString(a, ["url", "uri"]);
+ if (url) return url;
+ // MCP / generic: show a method or query if present
+ const method = pickString(a, ["method", "tool", "operation"]);
+ if (method) return method;
+ const query = pickString(a, ["query", "q", "prompt"]);
+ if (query) return truncate(query, 120);
+ // Last resort: stringify the args (capped) so the user sees *something*.
+ try {
+ const json = JSON.stringify(a);
+ return truncate(json, 120);
+ } catch {
+ return undefined;
+ }
+}
+
+function pickString(obj: Record<string, unknown>, keys: string[]): string | null {
+ for (const k of keys) {
+ const v = obj[k];
+ if (typeof v === "string" && v.trim().length > 0) return v.trim();
+ }
+ return null;
+}
+
+function firstLine(s: string): string {
+ const nl = s.indexOf("\n");
+ const line = nl >= 0 ? s.slice(0, nl) : s;
+ return truncate(line, 160);
+}
+
+function shortenPath(p: string): string {
+ // Keep filename + one parent dir to stay informative without taking up
+ // a whole row — matches the menu-bar app's heuristic.
+ const segs = p.split("/");
+ if (segs.length <= 2) return p;
+ return `…/${segs[segs.length - 2]}/${segs[segs.length - 1]}`;
+}
+
+function truncate(s: string, n: number): string {
+ return s.length > n ? `${s.slice(0, n - 1)}…` : s;
+}
+
function extractText(content: Array<{ type?: string; text?: string }> | undefined): string {
if (!Array.isArray(content)) return "";
return content