@contextableai/clawg-ui 0.2.9 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/clawg-ui",
-  "version": "0.2.9",
+  "version": "0.3.1",
   "description": "AG-UI protocol channel plugin for OpenClaw — connect CopilotKit and AG-UI clients to your OpenClaw gateway",
   "type": "module",
   "license": "MIT",
@@ -16,7 +16,14 @@
     "agent",
     "channel-plugin"
   ],
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
   "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
     "test": "vitest run"
   },
   "dependencies": {
@@ -27,11 +34,15 @@
     "openclaw": "*"
   },
   "devDependencies": {
+    "@types/node": "^25.3.5",
+    "commander": "^14.0.3",
+    "openclaw": "file:../openclaw",
+    "typescript": "^5.9.3",
     "vitest": "^3.0.0"
   },
   "openclaw": {
     "extensions": [
-      "./index.ts"
+      "./dist/index.js"
     ],
     "channel": {
       "id": "clawg-ui",

package/CHANGELOG.md

@@ -1,105 +0,0 @@
-# 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
-- Remove literal `process.env` from a code comment in `http-handler.ts` that was itself triggering the security scanner — the comment documenting the v0.2.5/v0.2.6 fix contained the exact pattern the scanner flags
-
-## 0.2.7 (2026-02-18)
-
-### Fixed
-- Close open text messages before emitting `RUN_FINISHED` in `splitRunIfToolFired()` — fixes `AGUIError: Cannot send 'RUN_FINISHED' while text messages are still active` when text streaming is followed by a server-side tool call and then more text
-
-## 0.2.6 (2026-02-10)
-
-### Fixed
-- Move gateway secret resolution into its own module (`gateway-secret.ts`) so the HTTP handler file contains zero `process.env` references — eliminates plugin security scanner warning ("Environment variable access combined with network send")
-
-## 0.2.5 (2026-02-10)
-
-### Fixed
-- Resolve gateway secret at factory initialization time instead of per-request to eliminate plugin security scanner warning ("Environment variable access combined with network send")
-
-## 0.2.4 (2026-02-06)
-
-### Changed
-- Separate tool call events and text message events into distinct AG-UI runs — when text follows a tool call, the tool run is finished and a new run (with a unique runId) is started for the text messages
-
-## 0.2.3 (2026-02-06)
-
-### Fixed
-- Append `\n\n` paragraph joiner to streamed text deltas so chunks render with proper spacing
-- Include `runId` in all `TEXT_MESSAGE_START`, `TEXT_MESSAGE_CONTENT`, and `TEXT_MESSAGE_END` events for AG-UI protocol compliance
-
-### Changed
-- Set channel defaults to `blockStreaming: true` and `chunkMode: "newline"` for correct paragraph-based streaming out of the box
-- Clean up multi-run logic for tool-call-then-text flows (single run per request)
-
-## 0.2.2 (2026-02-05)
-
-### Fixed
-- Include `messageId` in `TOOL_CALL_RESULT` events as required by AG-UI client v0.0.43 Zod schema
-
-### Added
-- Debug logging throughout tool call flow for easier troubleshooting
-
-## 0.2.1 (2026-02-05)
-
-### Fixed
-- Return HTTP 429 `rate_limit` error when max pending pairing requests (3) is reached, instead of returning an empty pairing code
-
-## 0.2.0 (2026-02-04)
-
-### Added
-- **Device pairing authentication** - Secure per-device access control
-  - HMAC-signed device tokens (no master token exposure)
-  - Pairing approval workflow (`openclaw pairing approve clawg-ui <code>`)
-  - New CLI command: `openclaw clawg-ui devices` - List approved devices
-
-### Changed
-- **Breaking:** Direct bearer token authentication using `OPENCLAW_GATEWAY_TOKEN` is now deprecated and no longer supported. All clients must use device pairing.
-
-### Security
-- Device tokens are HMAC-signed and do not expose the gateway's master secret
-- Pending pairing requests expire after 1 hour (max 3 per channel)
-- Each device requires explicit approval by the gateway owner
-
-## 0.1.1 (2026-02-03)
-
-### Changed
-- Endpoint path changed from `/v1/agui` to `/v1/clawg-ui`
-- Package name changed to `@contextableai/clawg-ui`
-
-## 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/index.ts

@@ -1,182 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import type { Command } from "commander";
-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,
-  getMessageId,
-  pushToolCallId,
-  popToolCallId,
-  isClientTool,
-  setClientToolCalled,
-  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",
-  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",
-      auth: "plugin",
-      handler: createAguiHttpHandler(api),
-    });
-
-    api.on("before_tool_call", handleBeforeToolCall);
-    api.on("tool_result_persist", handleToolResultPersist);
-
-    // CLI commands for device management
-    api.registerCli(
-      ({ program }: { program: Command }) => {
-        const clawgUi = program
-          .command("clawg-ui")
-          .description("CLAWG-UI (AG-UI) channel commands");
-
-        clawgUi
-          .command("devices")
-          .description("List approved devices")
-          .action(async () => {
-            const devices = await api.runtime.channel.pairing.readAllowFromStore("clawg-ui");
-            if (devices.length === 0) {
-              console.log("No approved devices.");
-              return;
-            }
-            console.log("Approved devices:");
-            for (const deviceId of devices) {
-              console.log(`  ${deviceId}`);
-            }
-          });
-      },
-      { commands: ["clawg-ui"] },
-    );
-  },
-};
-
-export default plugin;

package/src/channel.ts

@@ -1,37 +0,0 @@
-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",
-  },
-  pairing: {
-    idLabel: "clawgUiDeviceId",
-    normalizeAllowEntry: (entry: string) => entry.replace(/^clawg-ui:/i, "").toLowerCase(),
-  },
-};

package/src/client-tools.ts

@@ -1,51 +0,0 @@
-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;
-  console.log(`[clawg-ui] clawgUiToolFactory: sessionKey=${sessionKey ?? "none"}`);
-  if (!sessionKey) {
-    console.log(`[clawg-ui] clawgUiToolFactory: returning null, no sessionKey`);
-    return null;
-  }
-  const clientTools = popTools(sessionKey);
-  console.log(`[clawg-ui] clawgUiToolFactory: popped ${clientTools.length} client tools`);
-  if (clientTools.length === 0) {
-    console.log(`[clawg-ui] clawgUiToolFactory: returning null, no client tools`);
-    return null;
-  }
-  console.log(`[clawg-ui] clawgUiToolFactory: creating ${clientTools.length} agent tools`);
-  for (const t of clientTools) {
-    console.log(`[clawg-ui]   creating tool: name=${t.name}, description=${t.description ?? "(none)"}, hasParams=${!!t.parameters}, params=${JSON.stringify(t.parameters ?? {})}`);
-  }
-  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).
-      console.log(`[clawg-ui] client tool execute: name=${t.name}, args=${JSON.stringify(args)}`);
-      return {
-        content: [
-          {
-            type: "text" as const,
-            text: JSON.stringify(args),
-          },
-        ],
-        details: { clientTool: true, name: t.name, args },
-      };
-    },
-  }));
-}

package/src/gateway-secret.ts

@@ -1,20 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-
-/**
- * Resolve the gateway HMAC secret from config or environment variables.
- *
- * This lives in its own module so that the HTTP handler file contains zero
- * `process.env` references — plugin security scanners flag "env access +
- * network send" when both appear in the same source file.
- */
-export function resolveGatewaySecret(api: OpenClawPluginApi): string | null {
-  const gatewayAuth = api.config.gateway?.auth;
-  const secret =
-    (gatewayAuth as Record<string, unknown> | undefined)?.token ??
-    process.env.OPENCLAW_GATEWAY_TOKEN ??
-    process.env.CLAWDBOT_GATEWAY_TOKEN;
-  if (typeof secret === "string" && secret) {
-    return secret;
-  }
-  return null;
-}