@contextableai/clawg-ui 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 (2026-02-02)
+
+Initial release.
+
+- AG-UI protocol endpoint at `/v1/agui` for OpenClaw gateway
+- SSE streaming of agent responses as AG-UI events (`RUN_STARTED`, `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, `TEXT_MESSAGE_END`, `TOOL_CALL_START`, `TOOL_CALL_END`, `RUN_FINISHED`, `RUN_ERROR`)
+- Bearer token authentication using the gateway token
+- Content negotiation via `@ag-ui/encoder` (SSE and protobuf support)
+- Standard OpenClaw channel plugin (`agui`) for gateway status visibility
+- Agent routing via `X-OpenClaw-Agent-Id` header
+- Abort on client disconnect
+- Compatible with `@ag-ui/client` `HttpAgent`, CopilotKit, and any AG-UI consumer

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contextable
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# clawg-ui
+
+![Banner](./clawgui.png)
+
+An [OpenClaw](https://github.com/openclaw/openclaw) channel plugin that exposes the gateway as an [AG-UI](https://docs.ag-ui.com) protocol-compatible HTTP endpoint. AG-UI clients such as [CopilotKit](https://www.copilotkit.ai) UIs and `@ag-ui/client` `HttpAgent` instances can connect to OpenClaw and receive streamed responses.
+
+## Installation
+
+```bash
+npm install contextable/clawg-ui
+```
+
+Or with the OpenClaw plugin CLI:
+
+```bash
+openclaw plugins install contextable/clawg-ui
+```
+
+Then restart the gateway. The plugin auto-registers the `/v1/agui` endpoint and the `agui` channel.
+
+## How it works
+
+The plugin registers as an OpenClaw channel and adds an HTTP route at `/v1/agui`. When an AG-UI client POSTs a `RunAgentInput` payload, the plugin:
+
+1. Authenticates the request using the gateway bearer token
+2. Parses the AG-UI messages into an OpenClaw inbound context
+3. Routes to the appropriate agent via the gateway's standard routing
+4. Dispatches the message through the reply pipeline (same path as Telegram, Teams, etc.)
+5. Streams the agent's response back as AG-UI SSE events
+
+```
+AG-UI Client                        OpenClaw Gateway
+    |                                      |
+    |  POST /v1/agui (RunAgentInput)       |
+    |------------------------------------->|
+    |                                      |  Auth (bearer token)
+    |                                      |  Route to agent
+    |                                      |  Dispatch inbound message
+    |                                      |
+    |  SSE: RUN_STARTED                    |
+    |<-------------------------------------|
+    |  SSE: TEXT_MESSAGE_START             |
+    |<-------------------------------------|
+    |  SSE: TEXT_MESSAGE_CONTENT (delta)   |
+    |<-------------------------------------|  (streamed chunks)
+    |  SSE: TEXT_MESSAGE_CONTENT (delta)   |
+    |<-------------------------------------|
+    |  SSE: TOOL_CALL_START               |
+    |<-------------------------------------|  (if agent uses tools)
+    |  SSE: TOOL_CALL_END                 |
+    |<-------------------------------------|
+    |  SSE: TEXT_MESSAGE_END              |
+    |<-------------------------------------|
+    |  SSE: RUN_FINISHED                  |
+    |<-------------------------------------|
+```
+
+## Usage
+
+### Prerequisites
+
+- OpenClaw gateway running (`openclaw gateway run`)
+- A gateway auth token configured (`OPENCLAW_GATEWAY_TOKEN` env var or `gateway.auth.token` in config)
+
+### curl
+
+```bash
+curl -N -X POST http://localhost:18789/v1/agui \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -d '{
+    "threadId": "thread-1",
+    "runId": "run-1",
+    "messages": [
+      {"role": "user", "content": "What is the weather in San Francisco?"}
+    ]
+  }'
+```
+
+### @ag-ui/client HttpAgent
+
+```typescript
+import { HttpAgent } from "@ag-ui/client";
+
+const agent = new HttpAgent({
+  url: "http://localhost:18789/v1/agui",
+  headers: {
+    Authorization: `Bearer ${process.env.OPENCLAW_GATEWAY_TOKEN}`,
+  },
+});
+
+const stream = agent.run({
+  threadId: "thread-1",
+  runId: "run-1",
+  messages: [
+    { role: "user", content: "Hello from AG-UI" },
+  ],
+});
+
+for await (const event of stream) {
+  console.log(event.type, event);
+}
+```
+
+### CopilotKit
+
+```tsx
+import { CopilotKit } from "@copilotkit/react-core";
+
+function App() {
+  return (
+    <CopilotKit
+      runtimeUrl="http://localhost:18789/v1/agui"
+      headers={{
+        Authorization: `Bearer ${process.env.OPENCLAW_GATEWAY_TOKEN}`,
+      }}
+    >
+      {/* your app */}
+    </CopilotKit>
+  );
+}
+```
+
+## Request format
+
+The endpoint accepts a POST with a JSON body matching the AG-UI `RunAgentInput` schema:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `threadId` | string | no | Conversation thread ID. Auto-generated if omitted. |
+| `runId` | string | no | Unique run ID. Auto-generated if omitted. |
+| `messages` | Message[] | yes | Array of messages. At least one `user` message required. |
+| `tools` | Tool[] | no | Client-side tool definitions (reserved for future use). |
+| `state` | object | no | Client state (reserved for future use). |
+
+### Message format
+
+```json
+{
+  "role": "user",
+  "content": "Hello"
+}
+```
+
+Supported roles: `user`, `assistant`, `system`, `tool`.
+
+## Response format
+
+The response is an SSE stream. Each event is a `data:` line containing a JSON object with a `type` field from the AG-UI `EventType` enum:
+
+| Event | When |
+|---|---|
+| `RUN_STARTED` | Immediately after validation |
+| `TEXT_MESSAGE_START` | First assistant text chunk |
+| `TEXT_MESSAGE_CONTENT` | Each streamed text delta |
+| `TEXT_MESSAGE_END` | After last text chunk |
+| `TOOL_CALL_START` | Agent invokes a tool |
+| `TOOL_CALL_END` | Tool execution complete |
+| `RUN_FINISHED` | Agent run complete |
+| `RUN_ERROR` | On failure |
+
+## Authentication
+
+The endpoint uses the same bearer token as the OpenClaw gateway. Set it via:
+
+- Environment variable: `OPENCLAW_GATEWAY_TOKEN`
+- Config file: `gateway.auth.token`
+
+Pass it in the `Authorization` header:
+
+```
+Authorization: Bearer <token>
+```
+
+## Agent routing
+
+The plugin uses OpenClaw's standard agent routing. By default, messages route to the `main` agent. To target a specific agent, set the `X-OpenClaw-Agent-Id` header:
+
+```bash
+curl -N -X POST http://localhost:18789/v1/agui \
+  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "X-OpenClaw-Agent-Id: my-agent" \
+  -d '{"messages":[{"role":"user","content":"Hello"}]}'
+```
+
+## Error responses
+
+Non-streaming errors return JSON:
+
+| Status | Meaning |
+|---|---|
+| 400 | Invalid request (missing messages, bad JSON) |
+| 401 | Unauthorized (missing or invalid token) |
+| 405 | Method not allowed (only POST accepted) |
+
+Streaming errors emit a `RUN_ERROR` event and close the connection.
+
+## Development
+
+```bash
+git clone https://github.com/contextable/clawg-ui
+cd clawg-ui
+npm install
+npm test
+```
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,88 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { randomUUID } from "node:crypto";
+import { EventType } from "@ag-ui/core";
+import { aguiChannelPlugin } from "./src/channel.js";
+import { createAguiHttpHandler } from "./src/http-handler.js";
+import { clawgUiToolFactory } from "./src/client-tools.js";
+import {
+  getWriter,
+  pushToolCallId,
+  popToolCallId,
+  isClientTool,
+  setClientToolCalled,
+} from "./src/tool-store.js";
+
+const plugin = {
+  id: "clawg-ui",
+  name: "AG-UI",
+  description: "AG-UI protocol endpoint for CopilotKit and HttpAgent clients",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    api.registerChannel({ plugin: aguiChannelPlugin });
+    api.registerTool(clawgUiToolFactory);
+    api.registerHttpRoute({
+      path: "/v1/clawg-ui",
+      handler: createAguiHttpHandler(api),
+    });
+
+    // Emit TOOL_CALL_START + TOOL_CALL_ARGS from before_tool_call hook.
+    // For client tools: also emit TOOL_CALL_END immediately (fire-and-forget).
+    // For server tools: TOOL_CALL_END is emitted later by tool_result_persist.
+    api.on("before_tool_call", (event, ctx) => {
+      const sk = ctx.sessionKey;
+      if (!sk) return;
+      const writer = getWriter(sk);
+      if (!writer) return;
+      const toolCallId = `tool-${randomUUID()}`;
+      writer({
+        type: EventType.TOOL_CALL_START,
+        toolCallId,
+        toolCallName: event.toolName,
+      });
+      if (event.params && Object.keys(event.params).length > 0) {
+        writer({
+          type: EventType.TOOL_CALL_ARGS,
+          toolCallId,
+          delta: JSON.stringify(event.params),
+        });
+      }
+
+      if (isClientTool(sk, event.toolName)) {
+        // Client tool: emit TOOL_CALL_END now. The run will finish and the
+        // client initiates a new run with the tool result.
+        writer({
+          type: EventType.TOOL_CALL_END,
+          toolCallId,
+        });
+        setClientToolCalled(sk);
+      } else {
+        // Server tool: push ID so tool_result_persist can emit
+        // TOOL_CALL_RESULT + TOOL_CALL_END after execute() completes.
+        pushToolCallId(sk, toolCallId);
+      }
+    });
+
+    // Emit TOOL_CALL_RESULT + TOOL_CALL_END for server-side tools only.
+    // Client tools already emitted TOOL_CALL_END in before_tool_call.
+    api.on("tool_result_persist", (_event, ctx) => {
+      const sk = ctx.sessionKey;
+      if (!sk) return;
+      const writer = getWriter(sk);
+      const toolCallId = popToolCallId(sk);
+      if (writer && toolCallId) {
+        writer({
+          type: EventType.TOOL_CALL_RESULT,
+          toolCallId,
+          content: "",
+        });
+        writer({
+          type: EventType.TOOL_CALL_END,
+          toolCallId,
+        });
+      }
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "clawg-ui",
+  "channels": ["clawg-ui"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@contextableai/clawg-ui",
+  "version": "0.1.0",
+  "description": "AG-UI protocol channel plugin for OpenClaw — connect CopilotKit and AG-UI clients to your OpenClaw gateway",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contextable/clawg-ui"
+  },
+  "keywords": [
+    "openclaw",
+    "ag-ui",
+    "copilotkit",
+    "sse",
+    "agent",
+    "channel-plugin"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ag-ui/core": "^0.0.43",
+    "@ag-ui/encoder": "^0.0.43"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "clawg-ui",
+      "label": "AG-UI",
+      "docsPath": "/channels/agui",
+      "docsLabel": "agui",
+      "blurb": "AG-UI protocol endpoint for CopilotKit and HttpAgent clients.",
+      "order": 90
+    }
+  }
+}

package/src/channel.ts

@@ -0,0 +1,33 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk";
+
+type ResolvedAguiAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+};
+
+export const aguiChannelPlugin: ChannelPlugin<ResolvedAguiAccount> = {
+  id: "clawg-ui",
+  meta: {
+    id: "clawg-ui",
+    label: "AG-UI",
+    selectionLabel: "AG-UI (CopilotKit / HttpAgent)",
+    docsPath: "/channels/agui",
+    docsLabel: "agui",
+    blurb: "AG-UI protocol endpoint for CopilotKit and HttpAgent clients.",
+    order: 90,
+  },
+  capabilities: {
+    chatTypes: ["direct"],
+    blockStreaming: true,
+  },
+  config: {
+    listAccountIds: () => ["default"],
+    resolveAccount: () => ({
+      accountId: "default",
+      enabled: true,
+      configured: true,
+    }),
+    defaultAccountId: () => "default",
+  },
+};

package/src/client-tools.ts

@@ -0,0 +1,42 @@
+import { popTools } from "./tool-store.js";
+
+/**
+ * Plugin tool factory registered via `api.registerTool`.
+ * Receives the full `OpenClawPluginToolContext` including `sessionKey`,
+ * so it's fully reentrant across concurrent requests.
+ *
+ * Returns AG-UI client-provided tools converted to agent tools,
+ * or null if no client tools were stashed for this session.
+ */
+export function clawgUiToolFactory(ctx: { sessionKey?: string }) {
+  const sessionKey = ctx.sessionKey;
+  if (!sessionKey) {
+    return null;
+  }
+  const clientTools = popTools(sessionKey);
+  if (clientTools.length === 0) {
+    return null;
+  }
+  return clientTools.map((t) => ({
+    name: t.name,
+    label: t.name,
+    description: t.description,
+    parameters: t.parameters ?? { type: "object", properties: {} },
+    async execute(_toolCallId: string, args: unknown) {
+      // Client-side tools are fire-and-forget per AG-UI protocol.
+      // TOOL_CALL_START/ARGS/END are emitted by the before_tool_call hook.
+      // The run ends, and the client initiates a new run with the tool result.
+      // Return args so the agent loop can continue (the dispatcher will
+      // suppress any text output after a client tool call).
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify(args),
+          },
+        ],
+        details: { clientTool: true, name: t.name, args },
+      };
+    },
+  }));
+}

package/src/http-handler.ts

@@ -0,0 +1,465 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { randomUUID } from "node:crypto";
+import { EventType } from "@ag-ui/core";
+import type { RunAgentInput, Message } from "@ag-ui/core";
+import { EventEncoder } from "@ag-ui/encoder";
+import type { OpenClawPluginApi, PluginRuntime } from "openclaw/plugin-sdk";
+import {
+  stashTools,
+  setWriter,
+  clearWriter,
+  markClientToolNames,
+  wasClientToolCalled,
+  clearClientToolCalled,
+  clearClientToolNames,
+} from "./tool-store.js";
+
+// ---------------------------------------------------------------------------
+// Lightweight HTTP helpers (no internal imports needed)
+// ---------------------------------------------------------------------------
+
+function sendJson(res: ServerResponse, status: number, body: unknown) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+}
+
+function sendMethodNotAllowed(res: ServerResponse) {
+  res.setHeader("Allow", "POST");
+  res.statusCode = 405;
+  res.setHeader("Content-Type", "text/plain; charset=utf-8");
+  res.end("Method Not Allowed");
+}
+
+function sendUnauthorized(res: ServerResponse) {
+  sendJson(res, 401, { error: { message: "Unauthorized", type: "unauthorized" } });
+}
+
+function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > maxBytes) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf-8")));
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function getBearerToken(req: IncomingMessage): string | undefined {
+  const raw = req.headers.authorization?.trim() ?? "";
+  if (!raw.toLowerCase().startsWith("bearer ")) {
+    return undefined;
+  }
+  return raw.slice(7).trim() || undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Extract text from AG-UI messages
+// ---------------------------------------------------------------------------
+
+function extractTextContent(msg: Message): string {
+  if (typeof msg.content === "string") {
+    return msg.content;
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Build MsgContext-compatible body from AG-UI messages
+// ---------------------------------------------------------------------------
+
+function buildBodyFromMessages(messages: Message[]): {
+  body: string;
+  systemPrompt?: string;
+} {
+  const systemParts: string[] = [];
+  const parts: string[] = [];
+  let lastUserBody = "";
+  let lastToolBody = "";
+
+  for (const msg of messages) {
+    const role = msg.role?.trim() ?? "";
+    const content = extractTextContent(msg).trim();
+    // Allow messages with no content (e.g., assistant with only toolCalls)
+    if (!role) {
+      continue;
+    }
+    if (role === "system") {
+      if (content) systemParts.push(content);
+      continue;
+    }
+    if (role === "user") {
+      lastUserBody = content;
+      if (content) parts.push(`User: ${content}`);
+    } else if (role === "assistant") {
+      if (content) parts.push(`Assistant: ${content}`);
+    } else if (role === "tool") {
+      lastToolBody = content;
+      if (content) parts.push(`Tool result: ${content}`);
+    }
+  }
+
+  // If there's only a single user message, use it directly (no envelope needed)
+  // If there's only a tool result (resuming after client tool), use it directly
+  const userMessages = messages.filter((m) => m.role === "user");
+  const toolMessages = messages.filter((m) => m.role === "tool");
+  let body: string;
+  if (userMessages.length === 1 && parts.length === 1) {
+    body = lastUserBody;
+  } else if (userMessages.length === 0 && toolMessages.length > 0 && parts.length === toolMessages.length) {
+    // Tool-result-only submission: format as tool result for agent context
+    body = `Tool result: ${lastToolBody}`;
+  } else {
+    body = parts.join("\n");
+  }
+
+  return {
+    body,
+    systemPrompt: systemParts.length > 0 ? systemParts.join("\n\n") : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Token-based auth check against gateway config
+// ---------------------------------------------------------------------------
+
+function authenticateRequest(
+  req: IncomingMessage,
+  api: OpenClawPluginApi,
+): boolean {
+  const token = getBearerToken(req);
+  if (!token) {
+    return false;
+  }
+  // Read the configured gateway token from config
+  const gatewayAuth = api.config.gateway?.auth;
+  const configuredToken =
+    (gatewayAuth as Record<string, unknown> | undefined)?.token ??
+    process.env.OPENCLAW_GATEWAY_TOKEN ??
+    process.env.CLAWDBOT_GATEWAY_TOKEN;
+  if (typeof configuredToken !== "string" || !configuredToken) {
+    return false;
+  }
+  // Constant-time comparison
+  if (token.length !== configuredToken.length) {
+    return false;
+  }
+  let mismatch = 0;
+  for (let i = 0; i < token.length; i++) {
+    mismatch |= token.charCodeAt(i) ^ configuredToken.charCodeAt(i);
+  }
+  return mismatch === 0;
+}
+
+// ---------------------------------------------------------------------------
+// HTTP handler factory
+// ---------------------------------------------------------------------------
+
+export function createAguiHttpHandler(api: OpenClawPluginApi) {
+  const runtime: PluginRuntime = api.runtime;
+
+  return async function handleAguiRequest(
+    req: IncomingMessage,
+    res: ServerResponse,
+  ): Promise<void> {
+    // POST-only
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res);
+      return;
+    }
+
+    // Auth
+    if (!authenticateRequest(req, api)) {
+      sendUnauthorized(res);
+      return;
+    }
+
+    // Parse body
+    let body: unknown;
+    try {
+      body = await readJsonBody(req, 1024 * 1024);
+    } catch (err) {
+      sendJson(res, 400, {
+        error: { message: String(err), type: "invalid_request_error" },
+      });
+      return;
+    }
+
+    const input = body as RunAgentInput;
+    const threadId = input.threadId || `clawg-ui-${randomUUID()}`;
+    const runId = input.runId || `clawg-ui-run-${randomUUID()}`;
+
+    // Validate messages
+    const messages: Message[] = Array.isArray(input.messages)
+      ? input.messages
+      : [];
+
+    const hasUserMessage = messages.some((m) => m.role === "user");
+    const hasToolMessage = messages.some((m) => m.role === "tool");
+    if (!hasUserMessage && !hasToolMessage) {
+      sendJson(res, 400, {
+        error: {
+          message: "At least one user or tool message is required in `messages`.",
+          type: "invalid_request_error",
+        },
+      });
+      return;
+    }
+
+    // Build body from messages
+    const { body: messageBody } = buildBodyFromMessages(messages);
+    if (!messageBody.trim()) {
+      sendJson(res, 400, {
+        error: {
+          message: "Could not extract a prompt from `messages`.",
+          type: "invalid_request_error",
+        },
+      });
+      return;
+    }
+
+    // Resolve agent route
+    const cfg = runtime.config.loadConfig();
+    const route = runtime.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "clawg-ui",
+      peer: { kind: "dm", id: `clawg-ui-${threadId}` },
+    });
+
+    // Set up SSE via EventEncoder
+    const accept =
+      typeof req.headers.accept === "string"
+        ? req.headers.accept
+        : "text/event-stream";
+    const encoder = new EventEncoder({ accept });
+    res.statusCode = 200;
+    res.setHeader("Content-Type", encoder.getContentType());
+    res.setHeader("Cache-Control", "no-cache");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.flushHeaders?.();
+
+    let closed = false;
+    const messageId = `msg-${randomUUID()}`;
+    let messageStarted = false;
+
+    const writeEvent = (event: Record<string, unknown>) => {
+      if (closed) {
+        return;
+      }
+      try {
+        res.write(encoder.encode(event));
+      } catch {
+        // Client may have disconnected
+        closed = true;
+      }
+    };
+
+    // Handle client disconnect
+    req.on("close", () => {
+      closed = true;
+    });
+
+    // Emit RUN_STARTED
+    writeEvent({
+      type: EventType.RUN_STARTED,
+      threadId,
+      runId,
+    });
+
+    // Build inbound context using the plugin runtime (same pattern as msteams)
+    const sessionKey = route.sessionKey;
+
+    // Stash client-provided tools so the plugin tool factory can pick them up
+    if (Array.isArray(input.tools) && input.tools.length > 0) {
+      stashTools(sessionKey, input.tools);
+      markClientToolNames(
+        sessionKey,
+        input.tools.map((t: { name: string }) => t.name),
+      );
+    }
+
+    // Register SSE writer so before/after_tool_call hooks can emit AG-UI events
+    setWriter(sessionKey, writeEvent);
+    const storePath = runtime.channel.session.resolveStorePath(cfg.session?.store, {
+      agentId: route.agentId,
+    });
+    const envelopeOptions = runtime.channel.reply.resolveEnvelopeFormatOptions(cfg);
+    const previousTimestamp = runtime.channel.session.readSessionUpdatedAt({
+      storePath,
+      sessionKey,
+    });
+    const envelopedBody = runtime.channel.reply.formatAgentEnvelope({
+      channel: "AG-UI",
+      from: "User",
+      timestamp: new Date(),
+      previousTimestamp,
+      envelope: envelopeOptions,
+      body: messageBody,
+    });
+
+    const ctxPayload = runtime.channel.reply.finalizeInboundContext({
+      Body: envelopedBody,
+      RawBody: messageBody,
+      CommandBody: messageBody,
+      From: `clawg-ui:${threadId}`,
+      To: "clawg-ui",
+      SessionKey: sessionKey,
+      ChatType: "direct",
+      ConversationLabel: "AG-UI",
+      SenderName: "AG-UI Client",
+      SenderId: `clawg-ui-${threadId}`,
+      Provider: "clawg-ui" as const,
+      Surface: "clawg-ui" as const,
+      MessageSid: runId,
+      Timestamp: Date.now(),
+      WasMentioned: true,
+      CommandAuthorized: true,
+      OriginatingChannel: "clawg-ui" as const,
+    });
+
+    // Record inbound session
+    await runtime.channel.session.recordInboundSession({
+      storePath,
+      sessionKey,
+      ctx: ctxPayload,
+      onRecordError: () => {},
+    });
+
+    // Create reply dispatcher — translates reply payloads into AG-UI SSE events
+    const abortController = new AbortController();
+    req.on("close", () => {
+      abortController.abort();
+    });
+
+    const dispatcher = {
+      sendToolResult: (_payload: { text?: string }) => {
+        // Tool call events are emitted by before/after_tool_call hooks
+        return !closed;
+      },
+      sendBlockReply: (payload: { text?: string }) => {
+        if (closed || wasClientToolCalled(sessionKey)) {
+          return false;
+        }
+        const text = payload.text?.trim();
+        if (!text) {
+          return false;
+        }
+        if (!messageStarted) {
+          messageStarted = true;
+          writeEvent({
+            type: EventType.TEXT_MESSAGE_START,
+            messageId,
+            role: "assistant",
+          });
+        }
+        writeEvent({
+          type: EventType.TEXT_MESSAGE_CONTENT,
+          messageId,
+          delta: text,
+        });
+        return true;
+      },
+      sendFinalReply: (payload: { text?: string }) => {
+        if (closed) {
+          return false;
+        }
+        const text = wasClientToolCalled(sessionKey) ? "" : payload.text?.trim();
+        if (text) {
+          if (!messageStarted) {
+            messageStarted = true;
+            writeEvent({
+              type: EventType.TEXT_MESSAGE_START,
+              messageId,
+              role: "assistant",
+            });
+          }
+          writeEvent({
+            type: EventType.TEXT_MESSAGE_CONTENT,
+            messageId,
+            delta: text,
+          });
+        }
+        // End the message and run
+        if (messageStarted) {
+          writeEvent({
+            type: EventType.TEXT_MESSAGE_END,
+            messageId,
+          });
+        }
+        writeEvent({
+          type: EventType.RUN_FINISHED,
+          threadId,
+          runId,
+        });
+        closed = true;
+        res.end();
+        return true;
+      },
+      waitForIdle: () => Promise.resolve(),
+      getQueuedCounts: () => ({ tool: 0, block: 0, final: 0 }),
+    };
+
+    // Dispatch the inbound message — this triggers the agent run
+    try {
+      await runtime.channel.reply.dispatchReplyFromConfig({
+        ctx: ctxPayload,
+        cfg,
+        dispatcher,
+        replyOptions: {
+          runId,
+          abortSignal: abortController.signal,
+          disableBlockStreaming: false,
+          onAgentRunStart: () => {},
+          onToolResult: () => {
+            // Tool call events are emitted by before/after_tool_call hooks
+          },
+        },
+      });
+
+      // If the dispatcher's final reply didn't close the stream, close it now
+      if (!closed) {
+        if (messageStarted) {
+          writeEvent({
+            type: EventType.TEXT_MESSAGE_END,
+            messageId,
+          });
+        }
+        writeEvent({
+          type: EventType.RUN_FINISHED,
+          threadId,
+          runId,
+        });
+        closed = true;
+        res.end();
+      }
+    } catch (err) {
+      if (!closed) {
+        writeEvent({
+          type: EventType.RUN_ERROR,
+          message: String(err),
+        });
+        closed = true;
+        res.end();
+      }
+    } finally {
+      clearWriter(sessionKey);
+      clearClientToolCalled(sessionKey);
+      clearClientToolNames(sessionKey);
+    }
+  };
+}

package/src/tool-store.ts

@@ -0,0 +1,104 @@
+import type { Tool } from "@ag-ui/core";
+
+export type EventWriter = (event: Record<string, unknown>) => void;
+
+/**
+ * Per-session store for:
+ * 1. AG-UI client-provided tools (read by the plugin tool factory)
+ * 2. SSE event writer (read by before/after_tool_call hooks)
+ *
+ * Fully reentrant — concurrent requests use different session keys.
+ */
+const toolStore = new Map<string, Tool[]>();
+const writerStore = new Map<string, EventWriter>();
+
+// --- Client tools (for the plugin tool factory) ---
+
+export function stashTools(sessionKey: string, tools: Tool[]): void {
+  toolStore.set(sessionKey, tools);
+}
+
+export function popTools(sessionKey: string): Tool[] {
+  const tools = toolStore.get(sessionKey) ?? [];
+  toolStore.delete(sessionKey);
+  return tools;
+}
+
+// --- SSE event writer (for before/after_tool_call hooks) ---
+
+export function setWriter(sessionKey: string, writer: EventWriter): void {
+  writerStore.set(sessionKey, writer);
+}
+
+export function getWriter(sessionKey: string): EventWriter | undefined {
+  return writerStore.get(sessionKey);
+}
+
+export function clearWriter(sessionKey: string): void {
+  writerStore.delete(sessionKey);
+}
+
+// --- Pending toolCallId stack (before_tool_call pushes, tool_result_persist pops) ---
+// Only used for SERVER-side tools. Client tools emit TOOL_CALL_END in
+// before_tool_call and never push to this stack.
+
+const pendingStacks = new Map<string, string[]>();
+
+export function pushToolCallId(sessionKey: string, toolCallId: string): void {
+  let stack = pendingStacks.get(sessionKey);
+  if (!stack) {
+    stack = [];
+    pendingStacks.set(sessionKey, stack);
+  }
+  stack.push(toolCallId);
+}
+
+export function popToolCallId(sessionKey: string): string | undefined {
+  const stack = pendingStacks.get(sessionKey);
+  const id = stack?.pop();
+  if (stack && stack.length === 0) {
+    pendingStacks.delete(sessionKey);
+  }
+  return id;
+}
+
+// --- Client tool name tracking ---
+// Tracks which tool names are client-provided so hooks can distinguish them.
+
+const clientToolNames = new Map<string, Set<string>>();
+
+export function markClientToolNames(
+  sessionKey: string,
+  names: string[],
+): void {
+  clientToolNames.set(sessionKey, new Set(names));
+}
+
+export function isClientTool(
+  sessionKey: string,
+  toolName: string,
+): boolean {
+  return clientToolNames.get(sessionKey)?.has(toolName) ?? false;
+}
+
+export function clearClientToolNames(sessionKey: string): void {
+  clientToolNames.delete(sessionKey);
+}
+
+// --- Client-tool-called flag ---
+// Set when a client tool is invoked during a run so the dispatcher can
+// suppress text output and end the run after the tool call events.
+
+const clientToolCalledFlags = new Map<string, boolean>();
+
+export function setClientToolCalled(sessionKey: string): void {
+  clientToolCalledFlags.set(sessionKey, true);
+}
+
+export function wasClientToolCalled(sessionKey: string): boolean {
+  return clientToolCalledFlags.get(sessionKey) ?? false;
+}
+
+export function clearClientToolCalled(sessionKey: string): void {
+  clientToolCalledFlags.delete(sessionKey);
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist"
+  },
+  "include": ["index.ts", "src"]
+}