@contextableai/clawg-ui 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contextableai/clawg-ui",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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,84 +0,0 @@
-# Changelog
-
-## 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,136 +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";
-
-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",
-      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,
-        });
-      }
-    });
-
-    // 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;
-}