@contextableai/clawg-ui 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.9 (2026-03-06)
+
+### Fixed
+- Add `auth: "plugin"` to `registerHttpRoute` call — required by OpenClaw 2026.3.2; omitting it silently dropped the `/v1/clawg-ui` route, causing 404s
+- Pass `{ channel, accountId }` object to `readAllowFromStore` instead of a bare string — fixes 403 responses for approved devices after the pairing API changed in 2026.3.2
+- Add `pairing_code` and `bearer_token` at the root of the 403 pairing response alongside the existing nested `error.pairing` fields — restores compatibility with Kotlin `ClawgUIPairingResponse` clients expecting flat fields
+- Add diagnostic `console.log` for 400 responses to aid debugging of malformed requests
+
+### Changed
+- README event table was missing `TOOL_CALL_ARGS` and `TOOL_CALL_RESULT`; `tools` field incorrectly said "reserved for future use"
+- Integration tests used the gateway token directly instead of an HMAC-signed device token, causing 401s against v0.2.0+ servers
+- "Missing auth" integration test expected 401 instead of 403 (pairing initiation)
+
+### Added
+- "Tool call events" documentation section explaining client vs server tool flows and diagnostic tips
+- Unit tests for `handleBeforeToolCall` and `handleToolResultPersist` hook handlers (`src/tool-hooks.test.ts`)
+- Extracted hook handlers from `index.ts` into exported named functions for testability (no behavioral change)
+- Integration tests now accept `CLAWG_UI_DEVICE_TOKEN` or auto-generate one from `OPENCLAW_GATEWAY_TOKEN` + `CLAWG_UI_DEVICE_ID`
+
+## Unreleased
+
 ## 0.2.8 (2026-02-26)
 
 ### Fixed

package/README.md

@@ -47,6 +47,10 @@ AG-UI Client                        OpenClaw Gateway
     |<-------------------------------------|
     |  SSE: TOOL_CALL_START               |
     |<-------------------------------------|  (if agent uses tools)
+    |  SSE: TOOL_CALL_ARGS                |
+    |<-------------------------------------|
+    |  SSE: TOOL_CALL_RESULT              |
+    |<-------------------------------------|  (server tools only)
     |  SSE: TOOL_CALL_END                 |
     |<-------------------------------------|
     |  SSE: TEXT_MESSAGE_END              |
@@ -138,7 +142,7 @@ The endpoint accepts a POST with a JSON body matching the AG-UI `RunAgentInput`
 | `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). |
+| `tools` | Tool[] | no | Client-side tool definitions. The agent can invoke these; see [Tool call events](#tool-call-events). |
 | `state` | object | no | Client state (reserved for future use). |
 
 ### Message format
@@ -163,10 +167,28 @@ The response is an SSE stream. Each event is a `data:` line containing a JSON ob
 | `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 |
+| `TOOL_CALL_ARGS` | Tool call arguments (JSON delta) |
+| `TOOL_CALL_RESULT` | Server-side tool execution result |
+| `TOOL_CALL_END` | Tool call complete |
 | `RUN_FINISHED` | Agent run complete |
 | `RUN_ERROR` | On failure |
 
+### Tool call events
+
+Tool call events (`TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_RESULT`, `TOOL_CALL_END`) are emitted when the OpenClaw agent invokes a tool during its run. They are emitted via OpenClaw lifecycle hooks (`before_tool_call` and `tool_result_persist`) in `index.ts`.
+
+**When do tool events appear?**
+
+- The agent must have tools available (server-side tools on the agent, or client-side tools passed via the `tools` field)
+- The agent's LLM must decide to call a tool based on the conversation
+
+**Client tools vs server tools:**
+
+- **Client tools** (passed via `tools` in the request): the stream emits `TOOL_CALL_START` → `TOOL_CALL_ARGS` → `TOOL_CALL_END`, then the run finishes. The client executes the tool locally and starts a new run with the result as a `tool` message.
+- **Server tools** (registered on the OpenClaw agent): the stream emits `TOOL_CALL_START` → `TOOL_CALL_ARGS` → `TOOL_CALL_RESULT` → `TOOL_CALL_END`. The agent continues processing in the same or a subsequent run.
+
+> **Tip:** To confirm tool calls are being triggered, check the gateway logs for `[clawg-ui] before_tool_call:` entries.
+
 ## Authentication
 
 clawg-ui uses **device pairing** to authenticate clients. This provides secure, per-device access control without exposing the gateway's master token.

package/index.ts

@@ -16,6 +16,125 @@ import {
   setToolFiredInRun,
 } from "./src/tool-store.js";
 
+// ---------------------------------------------------------------------------
+// Hook handlers — exported for testability
+// ---------------------------------------------------------------------------
+
+export interface BeforeToolCallEvent {
+  toolName: string;
+  params?: Record<string, unknown>;
+}
+
+export interface ToolCallContext {
+  sessionKey?: string;
+}
+
+/**
+ * Handles the `before_tool_call` OpenClaw hook.
+ * Emits TOOL_CALL_START + TOOL_CALL_ARGS (and TOOL_CALL_END for client tools).
+ */
+export function handleBeforeToolCall(
+  event: BeforeToolCallEvent,
+  ctx: ToolCallContext,
+): void {
+  const sk = ctx.sessionKey;
+  console.log(
+    `[clawg-ui] before_tool_call: tool=${event.toolName}, sessionKey=${sk ?? "none"}, hasParams=${!!(event.params && Object.keys(event.params).length > 0)}, params=${JSON.stringify(event.params ?? {})}`,
+  );
+  if (!sk) {
+    console.log(`[clawg-ui] before_tool_call: skipping, no sessionKey`);
+    return;
+  }
+  const writer = getWriter(sk);
+  if (!writer) {
+    console.log(
+      `[clawg-ui] before_tool_call: skipping, no writer for sessionKey=${sk}`,
+    );
+    return;
+  }
+  const toolCallId = `tool-${randomUUID()}`;
+  console.log(
+    `[clawg-ui] before_tool_call: emitting TOOL_CALL_START, toolCallId=${toolCallId}`,
+  );
+  writer({
+    type: EventType.TOOL_CALL_START,
+    toolCallId,
+    toolCallName: event.toolName,
+  });
+  setToolFiredInRun(sk);
+  if (event.params && Object.keys(event.params).length > 0) {
+    console.log(
+      `[clawg-ui] before_tool_call: emitting TOOL_CALL_ARGS, params=${JSON.stringify(event.params)}`,
+    );
+    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.
+    console.log(
+      `[clawg-ui] before_tool_call: client tool detected, emitting TOOL_CALL_END immediately`,
+    );
+    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.
+    console.log(
+      `[clawg-ui] before_tool_call: server tool, pushing toolCallId to stack`,
+    );
+    pushToolCallId(sk, toolCallId);
+  }
+}
+
+/**
+ * Handles the `tool_result_persist` OpenClaw hook.
+ * Emits TOOL_CALL_RESULT + TOOL_CALL_END for server-side tools.
+ */
+export function handleToolResultPersist(
+  event: Record<string, unknown>,
+  ctx: ToolCallContext,
+): void {
+  const sk = ctx.sessionKey;
+  console.log(
+    `[clawg-ui] tool_result_persist: sessionKey=${sk ?? "none"}, event=${JSON.stringify(event)}`,
+  );
+  if (!sk) {
+    console.log(
+      `[clawg-ui] tool_result_persist: skipping, no sessionKey`,
+    );
+    return;
+  }
+  const writer = getWriter(sk);
+  const toolCallId = popToolCallId(sk);
+  const messageId = getMessageId(sk);
+  console.log(
+    `[clawg-ui] tool_result_persist: writer=${writer ? "present" : "missing"}, toolCallId=${toolCallId ?? "none"}, messageId=${messageId ?? "none"}`,
+  );
+  if (writer && toolCallId && messageId) {
+    console.log(
+      `[clawg-ui] tool_result_persist: emitting TOOL_CALL_RESULT and TOOL_CALL_END`,
+    );
+    writer({
+      type: EventType.TOOL_CALL_RESULT,
+      toolCallId,
+      messageId,
+      content: "",
+    });
+    writer({
+      type: EventType.TOOL_CALL_END,
+      toolCallId,
+    });
+  }
+}
+
 const plugin = {
   id: "clawg-ui",
   name: "CLAWG-UI",
@@ -26,85 +145,12 @@ const plugin = {
     api.registerTool(clawgUiToolFactory);
     api.registerHttpRoute({
       path: "/v1/clawg-ui",
+      auth: "plugin",
       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;
-      console.log(`[clawg-ui] before_tool_call: tool=${event.toolName}, sessionKey=${sk ?? "none"}, hasParams=${!!(event.params && Object.keys(event.params).length > 0)}, params=${JSON.stringify(event.params ?? {})}`);
-      if (!sk) {
-        console.log(`[clawg-ui] before_tool_call: skipping, no sessionKey`);
-        return;
-      }
-      const writer = getWriter(sk);
-      if (!writer) {
-        console.log(`[clawg-ui] before_tool_call: skipping, no writer for sessionKey=${sk}`);
-        return;
-      }
-      const toolCallId = `tool-${randomUUID()}`;
-      console.log(`[clawg-ui] before_tool_call: emitting TOOL_CALL_START, toolCallId=${toolCallId}`);
-      writer({
-        type: EventType.TOOL_CALL_START,
-        toolCallId,
-        toolCallName: event.toolName,
-      });
-      setToolFiredInRun(sk);
-      if (event.params && Object.keys(event.params).length > 0) {
-        console.log(`[clawg-ui] before_tool_call: emitting TOOL_CALL_ARGS, params=${JSON.stringify(event.params)}`);
-        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.
-        console.log(`[clawg-ui] before_tool_call: client tool detected, emitting TOOL_CALL_END immediately`);
-        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.
-        console.log(`[clawg-ui] before_tool_call: server tool, pushing toolCallId to stack`);
-        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;
-      console.log(`[clawg-ui] tool_result_persist: sessionKey=${sk ?? "none"}, event=${JSON.stringify(event)}`);
-      if (!sk) {
-        console.log(`[clawg-ui] tool_result_persist: skipping, no sessionKey`);
-        return;
-      }
-      const writer = getWriter(sk);
-      const toolCallId = popToolCallId(sk);
-      const messageId = getMessageId(sk);
-      console.log(`[clawg-ui] tool_result_persist: writer=${writer ? "present" : "missing"}, toolCallId=${toolCallId ?? "none"}, messageId=${messageId ?? "none"}`);
-      if (writer && toolCallId && messageId) {
-        console.log(`[clawg-ui] tool_result_persist: emitting TOOL_CALL_RESULT and TOOL_CALL_END`);
-        writer({
-          type: EventType.TOOL_CALL_RESULT,
-          toolCallId,
-          messageId,
-          content: "",
-        });
-        writer({
-          type: EventType.TOOL_CALL_END,
-          toolCallId,
-        });
-      }
-    });
+    api.on("before_tool_call", handleBeforeToolCall);
+    api.on("tool_result_persist", handleToolResultPersist);
 
     // CLI commands for device management
     api.registerCli(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/clawg-ui",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "AG-UI protocol channel plugin for OpenClaw — connect CopilotKit and AG-UI clients to your OpenClaw gateway",
   "type": "module",
   "license": "MIT",

package/src/http-handler.ts

@@ -245,6 +245,8 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
 
       // Return pairing pending response with device token and pairing code
       sendJson(res, 403, {
+        pairing_code: pairingCode,
+        bearer_token: deviceToken,
         error: {
           type: "pairing_pending",
           message: "Device pending approval",
@@ -270,7 +272,7 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
     // Pairing check: verify device is approved
     // ---------------------------------------------------------------------------
     const storeAllowFrom = await runtime.channel.pairing
-      .readAllowFromStore("clawg-ui")
+      .readAllowFromStore({ channel: "clawg-ui", accountId: "default" })
       .catch(() => []);
     const normalizedAllowFrom = storeAllowFrom.map((e) =>
       e.replace(/^clawg-ui:/i, "").toLowerCase(),
@@ -314,6 +316,9 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
     const hasUserMessage = messages.some((m) => m.role === "user");
     const hasToolMessage = messages.some((m) => m.role === "tool");
     if (!hasUserMessage && !hasToolMessage) {
+      console.log(
+        `[clawg-ui] 400: no user/tool message, roles=[${messages.map((m) => m.role).join(",")}], messageCount=${messages.length}`,
+      );
       sendJson(res, 400, {
         error: {
           message: "At least one user or tool message is required in `messages`.",
@@ -326,6 +331,9 @@ export function createAguiHttpHandler(api: OpenClawPluginApi) {
     // Build body from messages
     const { body: messageBody } = buildBodyFromMessages(messages);
     if (!messageBody.trim()) {
+      console.log(
+        `[clawg-ui] 400: empty extracted body, roles=[${messages.map((m) => m.role).join(",")}], contents=[${messages.map((m) => JSON.stringify(m.content)).join(",")}]`,
+      );
       sendJson(res, 400, {
         error: {
           message: "Could not extract a prompt from `messages`.",

package/test-device-setup.md

@@ -1,28 +0,0 @@
-# Integration Test Setup
-
-To run integration tests against the local gateway:
-
-1. Initiate device pairing:
-   ```bash
-   curl -X POST http://localhost:18789/v1/clawg-ui \
-     -H "Content-Type: application/json" \
-     -d '{"messages":[{"role":"user","content":"test"}]}'
-   ```
-   
-2. Copy the pairing code from the 403 response
-
-3. Approve the device:
-   ```bash
-   openclaw pairing approve clawg-ui <pairing-code>
-   ```
-
-4. Copy the device token from step 1's response
-
-5. Run tests with the device token:
-   ```bash
-   OPENCLAW_SERVER_URL="http://localhost" \
-   OPENCLAW_GATEWAY_TOKEN="<device-token>" \
-   npm test
-   ```
-
-**Note**: The OPENCLAW_GATEWAY_TOKEN env var name is misleading in the integration tests - it should be renamed to OPENCLAW_DEVICE_TOKEN in a future update.