@rudderhq/agent-runtime-openclaw-gateway 0.1.0-canary.0

package/LICENSE

@@ -0,0 +1,14 @@
+This package is part of the Rudder project.
+
+Rudder began as a fork of an early version of Paperclip.
+
+Licensing for this package follows the repository-level transition:
+- new Rudder contributions are made under the Apache License, Version 2.0
+- upstream-derived Paperclip portions preserve the original MIT notice where applicable
+
+Canonical project-level license and attribution texts live in the source repository:
+- `LICENSE`
+- `NOTICE`
+- `LICENSES/MIT-PAPERCLIP`
+
+Source repository: https://github.com/Undertone0809/rudder

package/README.md

@@ -0,0 +1,72 @@
+# OpenClaw Gateway Adapter
+
+This document describes how `@rudderhq/agent-runtime-openclaw-gateway` invokes OpenClaw over the Gateway protocol.
+
+## Transport
+
+This adapter always uses WebSocket gateway transport.
+
+- URL must be `ws://` or `wss://`
+- Connect flow follows gateway protocol:
+1. receive `connect.challenge`
+2. send `req connect` (protocol/client/auth/device payload)
+3. send `req agent`
+4. wait for completion via `req agent.wait`
+5. stream `event agent` frames into Rudder logs/transcript parsing
+
+## Auth Modes
+
+Gateway credentials can be provided in any of these ways:
+
+- `authToken` / `token` in adapter config
+- `headers.x-openclaw-token`
+- `headers.x-openclaw-auth` (legacy)
+- `password` (shared password mode)
+
+When a token is present and `authorization` header is missing, the adapter derives `Authorization: Bearer <token>`.
+
+## Device Auth
+
+By default the adapter sends a signed `device` payload in `connect` params.
+
+- set `disableDeviceAuth=true` to omit device signing
+- set `devicePrivateKeyPem` to pin a stable signing key
+- without `devicePrivateKeyPem`, the adapter generates an ephemeral Ed25519 keypair per run
+- when `autoPairOnFirstConnect` is enabled (default), the adapter handles one initial `pairing required` by calling `device.pair.list` + `device.pair.approve` over shared auth, then retries once.
+
+## Session Strategy
+
+The adapter supports the same session routing model as HTTP OpenClaw mode:
+
+- `sessionKeyStrategy=issue|fixed|run`
+- `sessionKey` is used when strategy is `fixed`
+
+Resolved session key is sent as `agent.sessionKey`.
+
+## Payload Mapping
+
+The agent request is built as:
+
+- required fields:
+  - `message` (wake text plus optional `payloadTemplate.message`/`payloadTemplate.text` prefix)
+  - `idempotencyKey` (Rudder `runId`)
+  - `sessionKey` (resolved strategy)
+- optional additions:
+  - all `payloadTemplate` fields merged in
+  - `agentId` from config if set and not already in template
+
+## Timeouts
+
+- `timeoutSec` controls adapter-level request budget
+- `waitTimeoutMs` controls `agent.wait.timeoutMs`
+
+If `agent.wait` returns `timeout`, adapter returns `openclaw_gateway_wait_timeout`.
+
+## Log Format
+
+Structured gateway event logs use:
+
+- `[openclaw-gateway] ...` for lifecycle/system logs
+- `[openclaw-gateway:event] run=<id> stream=<stream> data=<json>` for `event agent` frames
+
+UI/CLI parsers consume these lines to render transcript updates.

package/dist/cli/format-event.d.ts

@@ -0,0 +1,2 @@
+export declare function printOpenClawGatewayStreamEvent(raw: string, debug: boolean): void;
+//# sourceMappingURL=format-event.d.ts.map

package/dist/cli/format-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-event.d.ts","sourceRoot":"","sources":["../../src/cli/format-event.ts"],"names":[],"mappings":"AAEA,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAoBjF"}

package/dist/cli/format-event.js

@@ -0,0 +1,20 @@
+import pc from "picocolors";
+export function printOpenClawGatewayStreamEvent(raw, debug) {
+    const line = raw.trim();
+    if (!line)
+        return;
+    if (!debug) {
+        console.log(line);
+        return;
+    }
+    if (line.startsWith("[openclaw-gateway:event]")) {
+        console.log(pc.cyan(line));
+        return;
+    }
+    if (line.startsWith("[openclaw-gateway]")) {
+        console.log(pc.blue(line));
+        return;
+    }
+    console.log(pc.gray(line));
+}
+//# sourceMappingURL=format-event.js.map

package/dist/cli/format-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-event.js","sourceRoot":"","sources":["../../src/cli/format-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,UAAU,+BAA+B,CAAC,GAAW,EAAE,KAAc;IACzE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC,IAAI;QAAE,OAAO;IAElB,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3B,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+export { printOpenClawGatewayStreamEvent } from "./format-event.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,2 @@
+export { printOpenClawGatewayStreamEvent } from "./format-event.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export declare const type = "openclaw_gateway";
+export declare const label = "OpenClaw Gateway";
+export declare const models: {
+    id: string;
+    label: string;
+}[];
+export declare const agentConfigurationDoc = "# openclaw_gateway agent configuration\n\nAdapter: openclaw_gateway\n\nUse when:\n- You want Rudder to invoke OpenClaw over the Gateway WebSocket protocol.\n- You want native gateway auth/connect semantics instead of HTTP /v1/responses or /hooks/*.\n\nDon't use when:\n- You only expose OpenClaw HTTP endpoints.\n- Your deployment does not permit outbound WebSocket access from the Rudder server.\n\nCore fields:\n- url (string, required): OpenClaw gateway WebSocket URL (ws:// or wss://)\n- headers (object, optional): handshake headers; supports x-openclaw-token / x-openclaw-auth\n- authToken (string, optional): shared gateway token override\n- password (string, optional): gateway shared password, if configured\n\nGateway connect identity fields:\n- clientId (string, optional): gateway client id (default gateway-client)\n- clientMode (string, optional): gateway client mode (default backend)\n- clientVersion (string, optional): client version string\n- role (string, optional): gateway role (default operator)\n- scopes (string[] | comma string, optional): gateway scopes (default [\"operator.admin\"])\n- disableDeviceAuth (boolean, optional): disable signed device payload in connect params (default false)\n\nRequest behavior fields:\n- payloadTemplate (object, optional): additional fields merged into gateway agent params\n- workspaceRuntime (object, optional): desired runtime service intents; Rudder forwards these in a standardized rudder.workspaceRuntime block for remote execution environments\n- timeoutSec (number, optional): adapter timeout in seconds (default 120)\n- waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)\n- autoPairOnFirstConnect (boolean, optional): on first \"pairing required\", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)\n- rudderApiUrl (string, optional): absolute Rudder base URL advertised in wake text\n\nSession routing fields:\n- sessionKeyStrategy (string, optional): issue (default), fixed, or run\n- sessionKey (string, optional): fixed session key when strategy=fixed (default rudder)\n\nStandard outbound payload additions:\n- rudder (object): standardized Rudder context added to every gateway agent request\n- rudder.workspace (object, optional): resolved execution workspace for this run\n- rudder.workspaces (array, optional): additional workspace hints Rudder exposed to the run\n- rudder.workspaceRuntime (object, optional): normalized runtime service intent config for the workspace\n\nStandard result metadata supported:\n- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports\n- meta.previewUrl (string, optional): shorthand single preview URL\n- meta.previewUrls (string[], optional): shorthand multiple preview URLs\n";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,qBAAqB,CAAC;AACvC,eAAO,MAAM,KAAK,qBAAqB,CAAC;AAExC,eAAO,MAAM,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAO,CAAC;AAE1D,eAAO,MAAM,qBAAqB,6vFAgDjC,CAAC"}

package/dist/index.js

@@ -0,0 +1,53 @@
+export const type = "openclaw_gateway";
+export const label = "OpenClaw Gateway";
+export const models = [];
+export const agentConfigurationDoc = `# openclaw_gateway agent configuration
+
+Adapter: openclaw_gateway
+
+Use when:
+- You want Rudder to invoke OpenClaw over the Gateway WebSocket protocol.
+- You want native gateway auth/connect semantics instead of HTTP /v1/responses or /hooks/*.
+
+Don't use when:
+- You only expose OpenClaw HTTP endpoints.
+- Your deployment does not permit outbound WebSocket access from the Rudder server.
+
+Core fields:
+- url (string, required): OpenClaw gateway WebSocket URL (ws:// or wss://)
+- headers (object, optional): handshake headers; supports x-openclaw-token / x-openclaw-auth
+- authToken (string, optional): shared gateway token override
+- password (string, optional): gateway shared password, if configured
+
+Gateway connect identity fields:
+- clientId (string, optional): gateway client id (default gateway-client)
+- clientMode (string, optional): gateway client mode (default backend)
+- clientVersion (string, optional): client version string
+- role (string, optional): gateway role (default operator)
+- scopes (string[] | comma string, optional): gateway scopes (default ["operator.admin"])
+- disableDeviceAuth (boolean, optional): disable signed device payload in connect params (default false)
+
+Request behavior fields:
+- payloadTemplate (object, optional): additional fields merged into gateway agent params
+- workspaceRuntime (object, optional): desired runtime service intents; Rudder forwards these in a standardized rudder.workspaceRuntime block for remote execution environments
+- timeoutSec (number, optional): adapter timeout in seconds (default 120)
+- waitTimeoutMs (number, optional): agent.wait timeout override (default timeoutSec * 1000)
+- autoPairOnFirstConnect (boolean, optional): on first "pairing required", attempt device.pair.list/device.pair.approve via shared auth, then retry once (default true)
+- rudderApiUrl (string, optional): absolute Rudder base URL advertised in wake text
+
+Session routing fields:
+- sessionKeyStrategy (string, optional): issue (default), fixed, or run
+- sessionKey (string, optional): fixed session key when strategy=fixed (default rudder)
+
+Standard outbound payload additions:
+- rudder (object): standardized Rudder context added to every gateway agent request
+- rudder.workspace (object, optional): resolved execution workspace for this run
+- rudder.workspaces (array, optional): additional workspace hints Rudder exposed to the run
+- rudder.workspaceRuntime (object, optional): normalized runtime service intent config for the workspace
+
+Standard result metadata supported:
+- meta.runtimeServices (array, optional): normalized adapter-managed runtime service reports
+- meta.previewUrl (string, optional): shorthand single preview URL
+- meta.previewUrls (string[], optional): shorthand multiple preview URLs
+`;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,kBAAkB,CAAC;AACvC,MAAM,CAAC,MAAM,KAAK,GAAG,kBAAkB,CAAC;AAExC,MAAM,CAAC,MAAM,MAAM,GAAoC,EAAE,CAAC;AAE1D,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgDpC,CAAC"}

package/dist/server/execute.d.ts

@@ -0,0 +1,3 @@
+import type { AgentRuntimeExecutionContext, AgentRuntimeExecutionResult } from "@rudderhq/agent-runtime-utils";
+export declare function execute(ctx: AgentRuntimeExecutionContext): Promise<AgentRuntimeExecutionResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/server/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/server/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,4BAA4B,EAC5B,2BAA2B,EAE5B,MAAM,+BAA+B,CAAC;AAm+BvC,wBAAsB,OAAO,CAAC,GAAG,EAAE,4BAA4B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAsbrG"}