merge: wave 2 executor (01-02) into main

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

paperclip-reference/packages/adapters/openclaw-gateway/src/cli/format-event.ts

@@ -0,0 +1,23 @@
+import pc from "picocolors";
+
+export function printOpenClawGatewayStreamEvent(raw: string, debug: boolean): void {
+  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));
+}

paperclip-reference/packages/adapters/openclaw-gateway/src/cli/index.ts

@@ -0,0 +1 @@
+export { printOpenClawGatewayStreamEvent } from "./format-event.js";

paperclip-reference/packages/adapters/openclaw-gateway/src/index.ts

@@ -0,0 +1,54 @@
+export const type = "openclaw_gateway";
+export const label = "OpenClaw Gateway";
+
+export const models: { id: string; label: string }[] = [];
+
+export const agentConfigurationDoc = `# openclaw_gateway agent configuration
+
+Adapter: openclaw_gateway
+
+Use when:
+- You want Paperclip 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 Paperclip 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; Paperclip forwards these in a standardized paperclip.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)
+- paperclipApiUrl (string, optional): absolute Paperclip 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 paperclip)
+
+Standard outbound payload additions:
+- paperclip (object): standardized Paperclip context added to every gateway agent request
+- paperclip.workspace (object, optional): resolved execution workspace for this run
+- paperclip.workspaces (array, optional): additional workspace hints Paperclip exposed to the run
+- paperclip.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
+`;

paperclip-reference/packages/adapters/openclaw-gateway/src/server/index.ts

@@ -0,0 +1,2 @@
+export { execute } from "./execute.js";
+export { testEnvironment } from "./test.js";

paperclip-reference/packages/adapters/openclaw-gateway/src/server/test.ts

@@ -0,0 +1,317 @@
+import type {
+  AdapterEnvironmentCheck,
+  AdapterEnvironmentTestContext,
+  AdapterEnvironmentTestResult,
+} from "@paperclipai/adapter-utils";
+import { asString, parseObject } from "@paperclipai/adapter-utils/server-utils";
+import { randomUUID } from "node:crypto";
+import { WebSocket } from "ws";
+
+function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {
+  if (checks.some((check) => check.level === "error")) return "fail";
+  if (checks.some((check) => check.level === "warn")) return "warn";
+  return "pass";
+}
+
+function nonEmpty(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const value = hostname.trim().toLowerCase();
+  return value === "localhost" || value === "127.0.0.1" || value === "::1";
+}
+
+function toStringRecord(value: unknown): Record<string, string> {
+  const parsed = parseObject(value);
+  const out: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(parsed)) {
+    if (typeof entry === "string") out[key] = entry;
+  }
+  return out;
+}
+
+function toStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value
+      .filter((entry): entry is string => typeof entry === "string")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+  }
+  return [];
+}
+
+function headerMapGetIgnoreCase(headers: Record<string, string>, key: string): string | null {
+  const match = Object.entries(headers).find(([entryKey]) => entryKey.toLowerCase() === key.toLowerCase());
+  return match ? match[1] : null;
+}
+
+function tokenFromAuthHeader(rawHeader: string | null): string | null {
+  if (!rawHeader) return null;
+  const trimmed = rawHeader.trim();
+  if (!trimmed) return null;
+  const match = trimmed.match(/^bearer\s+(.+)$/i);
+  return match ? nonEmpty(match[1]) : trimmed;
+}
+
+function resolveAuthToken(config: Record<string, unknown>, headers: Record<string, string>): string | null {
+  const explicit = nonEmpty(config.authToken) ?? nonEmpty(config.token);
+  if (explicit) return explicit;
+
+  const tokenHeader = headerMapGetIgnoreCase(headers, "x-openclaw-token");
+  if (nonEmpty(tokenHeader)) return nonEmpty(tokenHeader);
+
+  const authHeader =
+    headerMapGetIgnoreCase(headers, "x-openclaw-auth") ??
+    headerMapGetIgnoreCase(headers, "authorization");
+  return tokenFromAuthHeader(authHeader);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function rawDataToString(data: unknown): string {
+  if (typeof data === "string") return data;
+  if (Buffer.isBuffer(data)) return data.toString("utf8");
+  if (data instanceof ArrayBuffer) return Buffer.from(data).toString("utf8");
+  if (Array.isArray(data)) {
+    return Buffer.concat(
+      data.map((entry) => (Buffer.isBuffer(entry) ? entry : Buffer.from(String(entry), "utf8"))),
+    ).toString("utf8");
+  }
+  return String(data ?? "");
+}
+
+async function probeGateway(input: {
+  url: string;
+  headers: Record<string, string>;
+  authToken: string | null;
+  role: string;
+  scopes: string[];
+  timeoutMs: number;
+}): Promise<"ok" | "challenge_only" | "failed"> {
+  return await new Promise((resolve) => {
+    const ws = new WebSocket(input.url, { headers: input.headers, maxPayload: 2 * 1024 * 1024 });
+    const timeout = setTimeout(() => {
+      try {
+        ws.close();
+      } catch {
+        // ignore
+      }
+      resolve("failed");
+    }, input.timeoutMs);
+
+    let completed = false;
+
+    const finish = (status: "ok" | "challenge_only" | "failed") => {
+      if (completed) return;
+      completed = true;
+      clearTimeout(timeout);
+      try {
+        ws.close();
+      } catch {
+        // ignore
+      }
+      resolve(status);
+    };
+
+    ws.on("message", (raw) => {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(rawDataToString(raw));
+      } catch {
+        return;
+      }
+      const event = asRecord(parsed);
+      if (event?.type === "event" && event.event === "connect.challenge") {
+        const nonce = nonEmpty(asRecord(event.payload)?.nonce);
+        if (!nonce) {
+          finish("failed");
+          return;
+        }
+
+        const connectId = randomUUID();
+        ws.send(
+          JSON.stringify({
+            type: "req",
+            id: connectId,
+            method: "connect",
+            params: {
+              minProtocol: 3,
+              maxProtocol: 3,
+              client: {
+                id: "gateway-client",
+                version: "paperclip-probe",
+                platform: process.platform,
+                mode: "probe",
+              },
+              role: input.role,
+              scopes: input.scopes,
+              ...(input.authToken
+                ? {
+                    auth: {
+                      token: input.authToken,
+                    },
+                  }
+                : {}),
+            },
+          }),
+        );
+        return;
+      }
+
+      if (event?.type === "res") {
+        if (event.ok === true) {
+          finish("ok");
+        } else {
+          finish("challenge_only");
+        }
+      }
+    });
+
+    ws.on("error", () => {
+      finish("failed");
+    });
+
+    ws.on("close", () => {
+      if (!completed) finish("failed");
+    });
+  });
+}
+
+export async function testEnvironment(
+  ctx: AdapterEnvironmentTestContext,
+): Promise<AdapterEnvironmentTestResult> {
+  const checks: AdapterEnvironmentCheck[] = [];
+  const config = parseObject(ctx.config);
+  const urlValue = asString(config.url, "").trim();
+
+  if (!urlValue) {
+    checks.push({
+      code: "openclaw_gateway_url_missing",
+      level: "error",
+      message: "OpenClaw gateway adapter requires a WebSocket URL.",
+      hint: "Set adapterConfig.url to ws://host:port (or wss://).",
+    });
+    return {
+      adapterType: ctx.adapterType,
+      status: summarizeStatus(checks),
+      checks,
+      testedAt: new Date().toISOString(),
+    };
+  }
+
+  let url: URL | null = null;
+  try {
+    url = new URL(urlValue);
+  } catch {
+    checks.push({
+      code: "openclaw_gateway_url_invalid",
+      level: "error",
+      message: `Invalid URL: ${urlValue}`,
+    });
+  }
+
+  if (url && url.protocol !== "ws:" && url.protocol !== "wss:") {
+    checks.push({
+      code: "openclaw_gateway_url_protocol_invalid",
+      level: "error",
+      message: `Unsupported URL protocol: ${url.protocol}`,
+      hint: "Use ws:// or wss://.",
+    });
+  }
+
+  if (url) {
+    checks.push({
+      code: "openclaw_gateway_url_valid",
+      level: "info",
+      message: `Configured gateway URL: ${url.toString()}`,
+    });
+
+    if (url.protocol === "ws:" && !isLoopbackHost(url.hostname)) {
+      checks.push({
+        code: "openclaw_gateway_plaintext_remote_ws",
+        level: "warn",
+        message: "Gateway URL uses plaintext ws:// on a non-loopback host.",
+        hint: "Prefer wss:// for remote gateways.",
+      });
+    }
+  }
+
+  const headers = toStringRecord(config.headers);
+  const authToken = resolveAuthToken(config, headers);
+  const password = nonEmpty(config.password);
+  const role = nonEmpty(config.role) ?? "operator";
+  const scopes = toStringArray(config.scopes);
+
+  if (authToken || password) {
+    checks.push({
+      code: "openclaw_gateway_auth_present",
+      level: "info",
+      message: "Gateway credentials are configured.",
+    });
+  } else {
+    checks.push({
+      code: "openclaw_gateway_auth_missing",
+      level: "warn",
+      message: "No gateway credentials detected in adapter config.",
+      hint: "Set authToken/password or headers.x-openclaw-token for authenticated gateways.",
+    });
+  }
+
+  if (url && (url.protocol === "ws:" || url.protocol === "wss:")) {
+    try {
+      const probeResult = await probeGateway({
+        url: url.toString(),
+        headers,
+        authToken,
+        role,
+        scopes: scopes.length > 0 ? scopes : ["operator.admin"],
+        timeoutMs: 3_000,
+      });
+
+      if (probeResult === "ok") {
+        checks.push({
+          code: "openclaw_gateway_probe_ok",
+          level: "info",
+          message: "Gateway connect probe succeeded.",
+        });
+      } else if (probeResult === "challenge_only") {
+        checks.push({
+          code: "openclaw_gateway_probe_challenge_only",
+          level: "warn",
+          message: "Gateway challenge was received, but connect probe was rejected.",
+          hint: "Check gateway credentials, scopes, role, and device-auth requirements.",
+        });
+      } else {
+        checks.push({
+          code: "openclaw_gateway_probe_failed",
+          level: "warn",
+          message: "Gateway probe failed.",
+          hint: "Verify network reachability and gateway URL from the Paperclip server host.",
+        });
+      }
+    } catch (err) {
+      checks.push({
+        code: "openclaw_gateway_probe_error",
+        level: "warn",
+        message: err instanceof Error ? err.message : "Gateway probe failed",
+      });
+    }
+  }
+
+  return {
+    adapterType: ctx.adapterType,
+    status: summarizeStatus(checks),
+    checks,
+    testedAt: new Date().toISOString(),
+  };
+}

paperclip-reference/packages/adapters/openclaw-gateway/src/shared/stream.ts

@@ -0,0 +1,16 @@
+export function normalizeOpenClawGatewayStreamLine(rawLine: string): {
+  stream: "stdout" | "stderr" | null;
+  line: string;
+} {
+  const trimmed = rawLine.trim();
+  if (!trimmed) return { stream: null, line: "" };
+
+  const prefixed = trimmed.match(/^(stdout|stderr)\s*[:=]?\s*(.*)$/i);
+  if (!prefixed) {
+    return { stream: null, line: trimmed };
+  }
+
+  const stream = prefixed[1]?.toLowerCase() === "stderr" ? "stderr" : "stdout";
+  const line = (prefixed[2] ?? "").trim();
+  return { stream, line };
+}

paperclip-reference/packages/adapters/openclaw-gateway/src/ui/build-config.ts

@@ -0,0 +1,30 @@
+import type { CreateConfigValues } from "@paperclipai/adapter-utils";
+
+function parseJsonObject(text: string): Record<string, unknown> | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function buildOpenClawGatewayConfig(v: CreateConfigValues): Record<string, unknown> {
+  const ac: Record<string, unknown> = {};
+  if (v.url) ac.url = v.url;
+  ac.timeoutSec = 120;
+  ac.waitTimeoutMs = 120000;
+  ac.sessionKeyStrategy = "issue";
+  ac.role = "operator";
+  ac.scopes = ["operator.admin"];
+  const payloadTemplate = parseJsonObject(v.payloadTemplateJson ?? "");
+  if (payloadTemplate) ac.payloadTemplate = payloadTemplate;
+  const runtimeServices = parseJsonObject(v.runtimeServicesJson ?? "");
+  if (runtimeServices && Array.isArray(runtimeServices.services)) {
+    ac.workspaceRuntime = runtimeServices;
+  }
+  return ac;
+}

paperclip-reference/packages/adapters/openclaw-gateway/src/ui/index.ts

@@ -0,0 +1,2 @@
+export { parseOpenClawGatewayStdoutLine } from "./parse-stdout.js";
+export { buildOpenClawGatewayConfig } from "./build-config.js";

paperclip-reference/packages/adapters/openclaw-gateway/src/ui/parse-stdout.ts

@@ -0,0 +1,75 @@
+import type { TranscriptEntry } from "@paperclipai/adapter-utils";
+import { normalizeOpenClawGatewayStreamLine } from "../shared/stream.js";
+
+function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function parseAgentEventLine(line: string, ts: string): TranscriptEntry[] {
+  const match = line.match(/^\[openclaw-gateway:event\]\s+run=([^\s]+)\s+stream=([^\s]+)\s+data=(.*)$/s);
+  if (!match) return [{ kind: "stdout", ts, text: line }];
+
+  const stream = asString(match[2]).toLowerCase();
+  const data = asRecord(safeJsonParse(asString(match[3]).trim()));
+
+  if (stream === "assistant") {
+    const delta = asString(data?.delta);
+    if (delta.length > 0) {
+      return [{ kind: "assistant", ts, text: delta, delta: true }];
+    }
+
+    const text = asString(data?.text);
+    if (text.length > 0) {
+      return [{ kind: "assistant", ts, text }];
+    }
+    return [];
+  }
+
+  if (stream === "error") {
+    const message = asString(data?.error) || asString(data?.message);
+    return message ? [{ kind: "stderr", ts, text: message }] : [];
+  }
+
+  if (stream === "lifecycle") {
+    const phase = asString(data?.phase).toLowerCase();
+    const message = asString(data?.error) || asString(data?.message);
+    if ((phase === "error" || phase === "failed" || phase === "cancelled") && message) {
+      return [{ kind: "stderr", ts, text: message }];
+    }
+  }
+
+  return [];
+}
+
+export function parseOpenClawGatewayStdoutLine(line: string, ts: string): TranscriptEntry[] {
+  const normalized = normalizeOpenClawGatewayStreamLine(line);
+  if (normalized.stream === "stderr") {
+    return [{ kind: "stderr", ts, text: normalized.line }];
+  }
+
+  const trimmed = normalized.line.trim();
+  if (!trimmed) return [];
+
+  if (trimmed.startsWith("[openclaw-gateway:event]")) {
+    return parseAgentEventLine(trimmed, ts);
+  }
+
+  if (trimmed.startsWith("[openclaw-gateway]")) {
+    return [{ kind: "system", ts, text: trimmed.replace(/^\[openclaw-gateway\]\s*/, "") }];
+  }
+
+  return [{ kind: "stdout", ts, text: normalized.line }];
+}