The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Cut over OpenClaw adapter to strict SSE streaming
Dotta0cc75c6e1009
diff --git a/package.json b/package.jsonindex b0ac83d5ed..ad6d692f11 100644--- a/package.json+++ b/package.json@@ -23,7 +23,8 @@"check:tokens": "node scripts/check-forbidden-tokens.mjs","docs:dev": "cd docs && npx mintlify dev","smoke:openclaw-join": "./scripts/smoke/openclaw-join.sh",- "smoke:openclaw-docker-ui": "./scripts/smoke/openclaw-docker-ui.sh"+ "smoke:openclaw-docker-ui": "./scripts/smoke/openclaw-docker-ui.sh",+ "smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh"},"devDependencies": {"@changesets/cli": "^2.30.0",diff --git a/packages/adapters/openclaw/src/index.ts b/packages/adapters/openclaw/src/index.tsindex 165435e46b..88968ee1f1 100644--- a/packages/adapters/openclaw/src/index.ts+++ b/packages/adapters/openclaw/src/index.ts@@ -16,8 +16,8 @@ Don't use when:- The OpenClaw endpoint is not reachable from the Paperclip server.Core fields:-- url (string, required): OpenClaw endpoint URL-- streamTransport (string, optional): \`sse\` (default) or \`webhook\`+- url (string, required): OpenClaw SSE endpoint URL+- streamTransport (string, optional): must be \`sse\` when provided- method (string, optional): HTTP method, default POST- headers (object, optional): extra HTTP headers for requests- webhookAuthHeader (string, optional): Authorization header value if your endpoint requires auth@@ -28,5 +28,5 @@ Session routing fields:- sessionKey (string, optional): fixed session key value when strategy is \`fixed\` (default \`paperclip\`)Operational fields:-- timeoutSec (number, optional): request timeout in seconds (default 30)+- timeoutSec (number, optional): SSE request timeout in seconds (default 0 = no adapter timeout)`;diff --git a/packages/adapters/openclaw/src/server/execute.ts b/packages/adapters/openclaw/src/server/execute.tsindex 677cf23192..959499641a 100644--- a/packages/adapters/openclaw/src/server/execute.ts+++ b/packages/adapters/openclaw/src/server/execute.ts@@ -1,19 +1,13 @@import type { AdapterExecutionContext, AdapterExecutionResult } from "@paperclipai/adapter-utils";-import { asNumber, asString, parseObject } from "@paperclipai/adapter-utils/server-utils";+import { asNumber, asString, buildPaperclipEnv, parseObject } from "@paperclipai/adapter-utils/server-utils";import { parseOpenClawResponse } from "./parse.js";-type OpenClawTransport = "sse" | "webhook";type SessionKeyStrategy = "fixed" | "issue" | "run";function nonEmpty(value: unknown): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}-function normalizeTransport(value: unknown): OpenClawTransport {- const normalized = asString(value, "sse").trim().toLowerCase();- return normalized === "webhook" ? "webhook" : "sse";-}-function normalizeSessionKeyStrategy(value: unknown): SessionKeyStrategy {const normalized = asString(value, "fixed").trim().toLowerCase();if (normalized === "issue" || normalized === "run") return normalized;@@ -32,7 +26,7 @@ function resolveSessionKey(input: {return fallback;}-function shouldUseWakeTextPayload(url: string): boolean {+function isWakeCompatibilityEndpoint(url: string): boolean {try {const parsed = new URL(url);const path = parsed.pathname.toLowerCase();@@ -42,7 +36,28 @@ function shouldUseWakeTextPayload(url: string): boolean {}}-function buildWakeText(payload: {+function isOpenResponsesEndpoint(url: string): boolean {+ try {+ const parsed = new URL(url);+ const path = parsed.pathname.toLowerCase();+ return path === "/v1/responses" || path.endsWith("/v1/responses");+ } catch {+ return false;+ }+}++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;+}++type WakePayload = {runId: string;agentId: string;companyId: string;@@ -53,23 +68,44 @@ function buildWakeText(payload: {approvalId: string | null;approvalStatus: string | null;issueIds: string[];-}): string {+};++function buildWakeText(payload: WakePayload, paperclipEnv: Record<string, string>): string {+ const orderedKeys = [+ "PAPERCLIP_RUN_ID",+ "PAPERCLIP_AGENT_ID",+ "PAPERCLIP_COMPANY_ID",+ "PAPERCLIP_API_URL",+ "PAPERCLIP_TASK_ID",+ "PAPERCLIP_WAKE_REASON",+ "PAPERCLIP_WAKE_COMMENT_ID",+ "PAPERCLIP_APPROVAL_ID",+ "PAPERCLIP_APPROVAL_STATUS",+ "PAPERCLIP_LINKED_ISSUE_IDS",+ ];++ const envLines: string[] = [];+ for (const key of orderedKeys) {+ const value = paperclipEnv[key];+ if (!value) continue;+ envLines.push(`${key}=${value}`);+ }+const lines = [- "Paperclip wake event.",+ "Paperclip wake event for a cloud adapter.","",- `runId: ${payload.runId}`,- `agentId: ${payload.agentId}`,- `companyId: ${payload.companyId}`,+ "Set these values in your run context:",+ ...envLines,+ "",+ `task_id=${payload.taskId ?? ""}`,+ `issue_id=${payload.issueId ?? ""}`,+ `wake_reason=${payload.wakeReason ?? ""}`,+ `wake_comment_id=${payload.wakeCommentId ?? ""}`,+ `approval_id=${payload.approvalId ?? ""}`,+ `approval_status=${payload.approvalStatus ?? ""}`,+ `linked_issue_ids=${payload.issueIds.join(",")}`,];- if (payload.taskId) lines.push(`taskId: ${payload.taskId}`);- if (payload.issueId) lines.push(`issueId: ${payload.issueId}`);- if (payload.wakeReason) lines.push(`wakeReason: ${payload.wakeReason}`);- if (payload.wakeCommentId) lines.push(`wakeCommentId: ${payload.wakeCommentId}`);- if (payload.approvalId) lines.push(`approvalId: ${payload.approvalId}`);- if (payload.approvalStatus) lines.push(`approvalStatus: ${payload.approvalStatus}`);- if (payload.issueIds.length > 0) lines.push(`issueIds: ${payload.issueIds.join(",")}`);-lines.push("", "Run your Paperclip heartbeat procedure now.");return lines.join("\n");}@@ -83,13 +119,6 @@ function isTextRequiredResponse(responseText: string): boolean {return responseText.toLowerCase().includes("text required");}-function isWebhookAcceptedResponse(parsed: Record<string, unknown> | null): boolean {- if (!parsed) return false;- if (parsed.ok === true) return true;- const status = nonEmpty(parsed.status)?.toLowerCase();- return status === "ok" || status === "accepted";-}-async function sendJsonRequest(params: {url: string;method: string;@@ -121,26 +150,6 @@ async function readAndLogResponseText(params: {return responseText;}-async function sendWebhookRequest(params: {- url: string;- method: string;- headers: Record<string, string>;- payload: Record<string, unknown>;- onLog: AdapterExecutionContext["onLog"];- signal: AbortSignal;-}): Promise<{ response: Response; responseText: string }> {- const response = await sendJsonRequest({- url: params.url,- method: params.method,- headers: params.headers,- payload: params.payload,- signal: params.signal,- });-- const responseText = await readAndLogResponseText({ response, onLog: params.onLog });- return { response, responseText };-}-type ConsumedSse = {eventCount: number;lastEventType: string | null;@@ -387,9 +396,30 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};}- const transport = normalizeTransport(config.streamTransport);+ if (isWakeCompatibilityEndpoint(url)) {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage: "OpenClaw /hooks/wake is not stream-capable. Use a streaming endpoint.",+ errorCode: "openclaw_sse_incompatible_endpoint",+ };+ }++ const streamTransport = asString(config.streamTransport, "sse").trim().toLowerCase();+ if (streamTransport && streamTransport !== "sse") {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage: "OpenClaw adapter only supports streamTransport=sse.",+ errorCode: "openclaw_stream_transport_unsupported",+ };+ }+const method = asString(config.method, "POST").trim().toUpperCase() || "POST";- const timeoutSec = Math.max(1, asNumber(config.timeoutSec, 30));+ const timeoutSecRaw = asNumber(config.timeoutSec, 0);+ const timeoutSec = timeoutSecRaw > 0 ? Math.max(1, Math.floor(timeoutSecRaw)) : 0;const headersConfig = parseObject(config.headers) as Record<string, unknown>;const payloadTemplate = parseObject(config.payloadTemplate);const webhookAuthHeader = nonEmpty(config.webhookAuthHeader);@@ -431,252 +461,137 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecissueId: wakePayload.issueId ?? wakePayload.taskId,});- const paperclipBody = {- ...payloadTemplate,- stream: transport === "sse",- sessionKey,- paperclip: {- ...wakePayload,- sessionKey,- streamTransport: transport,- context,- },+ const templateText = nonEmpty(payloadTemplate.text);+ const paperclipEnv: Record<string, string> = {+ ...buildPaperclipEnv(agent),+ PAPERCLIP_RUN_ID: runId,};+ if (wakePayload.taskId) paperclipEnv.PAPERCLIP_TASK_ID = wakePayload.taskId;+ if (wakePayload.wakeReason) paperclipEnv.PAPERCLIP_WAKE_REASON = wakePayload.wakeReason;+ if (wakePayload.wakeCommentId) paperclipEnv.PAPERCLIP_WAKE_COMMENT_ID = wakePayload.wakeCommentId;+ if (wakePayload.approvalId) paperclipEnv.PAPERCLIP_APPROVAL_ID = wakePayload.approvalId;+ if (wakePayload.approvalStatus) paperclipEnv.PAPERCLIP_APPROVAL_STATUS = wakePayload.approvalStatus;+ if (wakePayload.issueIds.length > 0) {+ paperclipEnv.PAPERCLIP_LINKED_ISSUE_IDS = wakePayload.issueIds.join(",");+ }- const wakeTextBody = {- text: buildWakeText(wakePayload),- mode: "now",- sessionKey,- paperclip: {- ...wakePayload,+ const wakeText = buildWakeText(wakePayload, paperclipEnv);+ const payloadText = templateText ? `${templateText}\n\n${wakeText}` : wakeText;+ const isOpenResponses = isOpenResponsesEndpoint(url);++ const paperclipBody: Record<string, unknown> = isOpenResponses+ ? {+ ...payloadTemplate,+ stream: true,+ model:+ nonEmpty(payloadTemplate.model) ??+ nonEmpty(config.model) ??+ "openclaw",+ input: Object.prototype.hasOwnProperty.call(payloadTemplate, "input")+ ? payloadTemplate.input+ : payloadText,+ metadata: {+ ...toStringRecord(payloadTemplate.metadata),+ ...paperclipEnv,+ paperclip_session_key: sessionKey,+ },+ }+ : {+ ...payloadTemplate,+ stream: true,sessionKey,- streamTransport: transport,- context,- },- };+ text: payloadText,+ paperclip: {+ ...wakePayload,+ sessionKey,+ streamTransport: "sse",+ env: paperclipEnv,+ context,+ },+ };++ if (isOpenResponses) {+ delete paperclipBody.text;+ delete paperclipBody.sessionKey;+ delete paperclipBody.paperclip;+ if (!headers["x-openclaw-session-key"] && !headers["X-OpenClaw-Session-Key"]) {+ headers["x-openclaw-session-key"] = sessionKey;+ }+ }if (onMeta) {await onMeta({adapterType: "openclaw",- command: transport === "sse" ? "sse" : "webhook",+ command: "sse",commandArgs: [method, url],context,});}- await onLog("stdout", `[openclaw] invoking ${method} ${url} (transport=${transport})\n`);+ await onLog("stdout", `[openclaw] invoking ${method} ${url} (transport=sse)\n`);const controller = new AbortController();- const timeout = setTimeout(() => controller.abort(), timeoutSec * 1000);+ const timeout = timeoutSec > 0 ? setTimeout(() => controller.abort(), timeoutSec * 1000) : null;try {- const preferWakeTextPayload = shouldUseWakeTextPayload(url);-- if (transport === "sse") {- if (preferWakeTextPayload) {- await onLog(- "stdout",- "[openclaw] /hooks/wake compatibility endpoint does not stream SSE; falling back to wake text payload\n",- );- const retry = await sendWebhookRequest({- url,- method,- headers,- payload: wakeTextBody,- onLog,- signal: controller.signal,- });-- if (retry.response.ok) {- return {- exitCode: 0,- signal: null,- timedOut: false,- provider: "openclaw",- model: null,- summary: `OpenClaw webhook ${method} ${url} (wake compatibility fallback)`,- resultJson: {- status: retry.response.status,- statusText: retry.response.statusText,- compatibilityMode: "wake_text",- transportFallback: "webhook",- response: parseOpenClawResponse(retry.responseText) ?? retry.responseText,- },- };- }- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: `OpenClaw webhook failed with status ${retry.response.status}`,- errorCode: "openclaw_http_error",- resultJson: {- status: retry.response.status,- statusText: retry.response.statusText,- compatibilityMode: "wake_text",- transportFallback: "webhook",- response: parseOpenClawResponse(retry.responseText) ?? retry.responseText,- },- };- }-- const sseHeaders = {+ const response = await sendJsonRequest({+ url,+ method,+ headers: {...headers,accept: "text/event-stream",- };-- const response = await sendJsonRequest({- url,- method,- headers: sseHeaders,- payload: paperclipBody,- signal: controller.signal,- });-- if (!response.ok) {- const responseText = await readAndLogResponseText({ response, onLog });- if (isTextRequiredResponse(responseText)) {- await onLog(- "stdout",- "[openclaw] SSE endpoint reported text-required; falling back to wake compatibility payload\n",- );- const retry = await sendWebhookRequest({- url,- method,- headers,- payload: wakeTextBody,- onLog,- signal: controller.signal,- });- if (retry.response.ok) {- return {- exitCode: 0,- signal: null,- timedOut: false,- provider: "openclaw",- model: null,- summary: `OpenClaw webhook ${method} ${url} (wake compatibility fallback)`,- resultJson: {- status: retry.response.status,- statusText: retry.response.statusText,- compatibilityMode: "wake_text",- transportFallback: "webhook",- response: parseOpenClawResponse(retry.responseText) ?? retry.responseText,- },- };- }- }- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: `OpenClaw SSE request failed with status ${response.status}`,- errorCode: "openclaw_http_error",- resultJson: {- status: response.status,- statusText: response.statusText,- response: parseOpenClawResponse(responseText) ?? responseText,- },- };- }+ },+ payload: paperclipBody,+ signal: controller.signal,+ });- const contentType = (response.headers.get("content-type") ?? "").toLowerCase();- if (!contentType.includes("text/event-stream")) {- const responseText = await readAndLogResponseText({ response, onLog });- const parsedResponse = parseOpenClawResponse(responseText);- if (isTextRequiredResponse(responseText)) {- await onLog(- "stdout",- "[openclaw] non-SSE response indicated text-required; falling back to wake compatibility payload\n",- );- const retry = await sendWebhookRequest({- url,- method,- headers,- payload: wakeTextBody,- onLog,- signal: controller.signal,- });- if (retry.response.ok) {- return {- exitCode: 0,- signal: null,- timedOut: false,- provider: "openclaw",- model: null,- summary: `OpenClaw webhook ${method} ${url} (wake compatibility fallback)`,- resultJson: {- status: retry.response.status,- statusText: retry.response.statusText,- compatibilityMode: "wake_text",- transportFallback: "webhook",- response: parseOpenClawResponse(retry.responseText) ?? retry.responseText,- },- };- }- }- if (isWebhookAcceptedResponse(parsedResponse)) {- await onLog(- "stdout",- "[openclaw] non-SSE response acknowledged run; treating as webhook compatibility success\n",- );- return {- exitCode: 0,- signal: null,- timedOut: false,- provider: "openclaw",- model: null,- summary: `OpenClaw webhook ${method} ${url} (non-stream compatibility)`,- resultJson: {- status: response.status,- statusText: response.statusText,- contentType,- compatibilityMode: "json_ack",- transportFallback: "webhook",- response: parsedResponse ?? responseText,- },- };- }- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: "OpenClaw SSE endpoint did not return text/event-stream",- errorCode: "openclaw_sse_expected_event_stream",- resultJson: {- status: response.status,- statusText: response.statusText,- contentType,- response: parsedResponse ?? responseText,- },- };- }+ if (!response.ok) {+ const responseText = await readAndLogResponseText({ response, onLog });+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage:+ isTextRequiredResponse(responseText)+ ? "OpenClaw endpoint rejected the payload as text-required."+ : `OpenClaw SSE request failed with status ${response.status}`,+ errorCode: isTextRequiredResponse(responseText)+ ? "openclaw_text_required"+ : "openclaw_http_error",+ resultJson: {+ status: response.status,+ statusText: response.statusText,+ response: parseOpenClawResponse(responseText) ?? responseText,+ },+ };+ }- const consumed = await consumeSseResponse({ response, onLog });- if (consumed.failed) {- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: consumed.errorMessage ?? "OpenClaw SSE stream failed",- errorCode: "openclaw_sse_stream_failed",- resultJson: {- eventCount: consumed.eventCount,- terminal: consumed.terminal,- lastEventType: consumed.lastEventType,- lastData: consumed.lastData,- response: consumed.lastPayload ?? consumed.lastData,- },- };- }+ const contentType = (response.headers.get("content-type") ?? "").toLowerCase();+ if (!contentType.includes("text/event-stream")) {+ const responseText = await readAndLogResponseText({ response, onLog });+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorMessage: "OpenClaw SSE endpoint did not return text/event-stream",+ errorCode: "openclaw_sse_expected_event_stream",+ resultJson: {+ status: response.status,+ statusText: response.statusText,+ contentType,+ response: parseOpenClawResponse(responseText) ?? responseText,+ },+ };+ }+ const consumed = await consumeSseResponse({ response, onLog });+ if (consumed.failed) {return {- exitCode: 0,+ exitCode: 1,signal: null,timedOut: false,- provider: "openclaw",- model: null,- summary: `OpenClaw SSE ${method} ${url}`,+ errorMessage: consumed.errorMessage ?? "OpenClaw SSE stream failed",+ errorCode: "openclaw_sse_stream_failed",resultJson: {eventCount: consumed.eventCount,terminal: consumed.terminal,@@ -687,81 +602,19 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec};}- if (preferWakeTextPayload) {- await onLog("stdout", "[openclaw] using wake text payload for /hooks/wake compatibility\n");- }-- const initialPayload = preferWakeTextPayload ? wakeTextBody : paperclipBody;-- const { response, responseText } = await sendWebhookRequest({- url,- method,- headers,- payload: initialPayload,- onLog,- signal: controller.signal,- });-- if (!response.ok) {- const canRetryWithWakeText = !preferWakeTextPayload && isTextRequiredResponse(responseText);-- if (canRetryWithWakeText) {- await onLog(- "stdout",- "[openclaw] endpoint requires text payload; retrying with wake compatibility format\n",- );-- const retry = await sendWebhookRequest({- url,- method,- headers,- payload: wakeTextBody,- onLog,- signal: controller.signal,- });-- if (retry.response.ok) {- return {- exitCode: 0,- signal: null,- timedOut: false,- provider: "openclaw",- model: null,- summary: `OpenClaw webhook ${method} ${url} (wake compatibility)`,- resultJson: {- status: retry.response.status,- statusText: retry.response.statusText,- compatibilityMode: "wake_text",- response: parseOpenClawResponse(retry.responseText) ?? retry.responseText,- },- };- }-- return {- exitCode: 1,- signal: null,- timedOut: false,- errorMessage: `OpenClaw webhook failed with status ${retry.response.status}`,- errorCode: "openclaw_http_error",- resultJson: {- status: retry.response.status,- statusText: retry.response.statusText,- compatibilityMode: "wake_text",- response: parseOpenClawResponse(retry.responseText) ?? retry.responseText,- },- };- }-+ if (!consumed.terminal) {return {exitCode: 1,signal: null,timedOut: false,- errorMessage: `OpenClaw webhook failed with status ${response.status}`,- errorCode: "openclaw_http_error",+ errorMessage: "OpenClaw SSE stream closed without a terminal event",+ errorCode: "openclaw_sse_stream_incomplete",resultJson: {- status: response.status,- statusText: response.statusText,- response: parseOpenClawResponse(responseText) ?? responseText,+ eventCount: consumed.eventCount,+ terminal: consumed.terminal,+ lastEventType: consumed.lastEventType,+ lastData: consumed.lastData,+ response: consumed.lastPayload ?? consumed.lastData,},};}@@ -772,22 +625,28 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExectimedOut: false,provider: "openclaw",model: null,- summary: `OpenClaw webhook ${method} ${url}`,+ summary: `OpenClaw SSE ${method} ${url}`,resultJson: {- status: response.status,- statusText: response.statusText,- response: parseOpenClawResponse(responseText) ?? responseText,+ eventCount: consumed.eventCount,+ terminal: consumed.terminal,+ lastEventType: consumed.lastEventType,+ lastData: consumed.lastData,+ response: consumed.lastPayload ?? consumed.lastData,},};} catch (err) {if (err instanceof Error && err.name === "AbortError") {- await onLog("stderr", `[openclaw] request timed out after ${timeoutSec}s\n`);+ const timeoutMessage =+ timeoutSec > 0+ ? `[openclaw] SSE request timed out after ${timeoutSec}s\n`+ : "[openclaw] SSE request aborted\n";+ await onLog("stderr", timeoutMessage);return {exitCode: null,signal: null,timedOut: true,- errorMessage: `Timed out after ${timeoutSec}s`,- errorCode: "timeout",+ errorMessage: timeoutSec > 0 ? `Timed out after ${timeoutSec}s` : "Request aborted",+ errorCode: "openclaw_sse_timeout",};}@@ -801,6 +660,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecerrorCode: "openclaw_request_failed",};} finally {- clearTimeout(timeout);+ if (timeout) clearTimeout(timeout);}}diff --git a/packages/adapters/openclaw/src/server/test.ts b/packages/adapters/openclaw/src/server/test.tsindex a6093dabcc..83c02f3f5d 100644--- a/packages/adapters/openclaw/src/server/test.ts+++ b/packages/adapters/openclaw/src/server/test.ts@@ -107,8 +107,8 @@ export async function testEnvironment(checks.push({code: "openclaw_url_missing",level: "error",- message: "OpenClaw adapter requires a webhook URL.",- hint: "Set adapterConfig.url to your OpenClaw webhook endpoint.",+ message: "OpenClaw adapter requires a streaming endpoint URL.",+ hint: "Set adapterConfig.url to your OpenClaw SSE endpoint.",});return {adapterType: ctx.adapterType,@@ -156,14 +156,24 @@ export async function testEnvironment(if (isWakePath(url.pathname)) {checks.push({- code: "openclaw_wake_endpoint_compat_mode",- level: "info",- message: "Endpoint targets /hooks/wake; adapter will use OpenClaw wake compatibility payload (text/mode).",- hint: "For structured Paperclip JSON payloads, use a mapped webhook endpoint such as /hooks/paperclip.",+ code: "openclaw_wake_endpoint_incompatible",+ level: "error",+ message: "Endpoint targets /hooks/wake, which is not stream-capable for strict SSE mode.",+ hint: "Use an endpoint that returns text/event-stream for the full run duration.",});}}+ const streamTransport = asString(config.streamTransport, "sse").trim().toLowerCase();+ if (streamTransport && streamTransport !== "sse") {+ checks.push({+ code: "openclaw_stream_transport_unsupported",+ level: "error",+ message: `Unsupported streamTransport: ${streamTransport}`,+ hint: "OpenClaw adapter now requires streamTransport=sse.",+ });+ }+pushDeploymentDiagnostics(checks, ctx, url);const method = asString(config.method, "POST").trim().toUpperCase() || "POST";@@ -183,7 +193,7 @@ export async function testEnvironment(code: "openclaw_endpoint_probe_unexpected_status",level: "warn",message: `Endpoint probe returned HTTP ${response.status}.`,- hint: "Verify OpenClaw webhook reachability and auth/network settings.",+ hint: "Verify OpenClaw endpoint reachability and auth/network settings.",});} else {checks.push({diff --git a/packages/adapters/openclaw/src/ui/build-config.ts b/packages/adapters/openclaw/src/ui/build-config.tsindex 6e71a37901..f1386780ee 100644--- a/packages/adapters/openclaw/src/ui/build-config.ts+++ b/packages/adapters/openclaw/src/ui/build-config.ts@@ -4,7 +4,7 @@ export function buildOpenClawConfig(v: CreateConfigValues): Record<string, unknoconst ac: Record<string, unknown> = {};if (v.url) ac.url = v.url;ac.method = "POST";- ac.timeoutSec = 30;+ ac.timeoutSec = 0;ac.streamTransport = "sse";ac.sessionKeyStrategy = "fixed";ac.sessionKey = "paperclip";diff --git a/scripts/smoke/openclaw-sse-standalone.sh b/scripts/smoke/openclaw-sse-standalone.shnew file mode 100755index 0000000000..65b42ae72f--- /dev/null+++ b/scripts/smoke/openclaw-sse-standalone.sh@@ -0,0 +1,146 @@+#!/usr/bin/env bash+set -euo pipefail++log() {+ echo "[openclaw-sse-standalone] $*"+}++fail() {+ echo "[openclaw-sse-standalone] ERROR: $*" >&2+ exit 1+}++require_cmd() {+ local cmd="$1"+ command -v "$cmd" >/dev/null 2>&1 || fail "missing required command: $cmd"+}++require_cmd curl+require_cmd jq+require_cmd grep++OPENCLAW_URL="${OPENCLAW_URL:-}"+OPENCLAW_METHOD="${OPENCLAW_METHOD:-POST}"+OPENCLAW_AUTH_HEADER="${OPENCLAW_AUTH_HEADER:-}"+OPENCLAW_TIMEOUT_SEC="${OPENCLAW_TIMEOUT_SEC:-180}"+OPENCLAW_MODEL="${OPENCLAW_MODEL:-openclaw}"+OPENCLAW_USER="${OPENCLAW_USER:-paperclip-smoke}"++PAPERCLIP_RUN_ID="${PAPERCLIP_RUN_ID:-smoke-run-$(date +%s)}"+PAPERCLIP_AGENT_ID="${PAPERCLIP_AGENT_ID:-openclaw-smoke-agent}"+PAPERCLIP_COMPANY_ID="${PAPERCLIP_COMPANY_ID:-openclaw-smoke-company}"+PAPERCLIP_API_URL="${PAPERCLIP_API_URL:-http://localhost:3100}"+PAPERCLIP_TASK_ID="${PAPERCLIP_TASK_ID:-openclaw-smoke-task}"+PAPERCLIP_WAKE_REASON="${PAPERCLIP_WAKE_REASON:-openclaw_smoke_test}"+PAPERCLIP_WAKE_COMMENT_ID="${PAPERCLIP_WAKE_COMMENT_ID:-}"+PAPERCLIP_APPROVAL_ID="${PAPERCLIP_APPROVAL_ID:-}"+PAPERCLIP_APPROVAL_STATUS="${PAPERCLIP_APPROVAL_STATUS:-}"+PAPERCLIP_LINKED_ISSUE_IDS="${PAPERCLIP_LINKED_ISSUE_IDS:-}"+OPENCLAW_TEXT_PREFIX="${OPENCLAW_TEXT_PREFIX:-Standalone OpenClaw SSE smoke test.}"++[[ -n "$OPENCLAW_URL" ]] || fail "OPENCLAW_URL is required"++read -r -d '' TEXT_BODY <<EOF || true+${OPENCLAW_TEXT_PREFIX}++PAPERCLIP_RUN_ID=${PAPERCLIP_RUN_ID}+PAPERCLIP_AGENT_ID=${PAPERCLIP_AGENT_ID}+PAPERCLIP_COMPANY_ID=${PAPERCLIP_COMPANY_ID}+PAPERCLIP_API_URL=${PAPERCLIP_API_URL}+PAPERCLIP_TASK_ID=${PAPERCLIP_TASK_ID}+PAPERCLIP_WAKE_REASON=${PAPERCLIP_WAKE_REASON}+PAPERCLIP_WAKE_COMMENT_ID=${PAPERCLIP_WAKE_COMMENT_ID}+PAPERCLIP_APPROVAL_ID=${PAPERCLIP_APPROVAL_ID}+PAPERCLIP_APPROVAL_STATUS=${PAPERCLIP_APPROVAL_STATUS}+PAPERCLIP_LINKED_ISSUE_IDS=${PAPERCLIP_LINKED_ISSUE_IDS}++Run your Paperclip heartbeat procedure now.+EOF++PAYLOAD="$(jq -nc \+ --arg text "$TEXT_BODY" \+ --arg model "$OPENCLAW_MODEL" \+ --arg user "$OPENCLAW_USER" \+ --arg runId "$PAPERCLIP_RUN_ID" \+ --arg agentId "$PAPERCLIP_AGENT_ID" \+ --arg companyId "$PAPERCLIP_COMPANY_ID" \+ --arg apiUrl "$PAPERCLIP_API_URL" \+ --arg taskId "$PAPERCLIP_TASK_ID" \+ --arg wakeReason "$PAPERCLIP_WAKE_REASON" \+ --arg wakeCommentId "$PAPERCLIP_WAKE_COMMENT_ID" \+ --arg approvalId "$PAPERCLIP_APPROVAL_ID" \+ --arg approvalStatus "$PAPERCLIP_APPROVAL_STATUS" \+ --arg linkedIssueIds "$PAPERCLIP_LINKED_ISSUE_IDS" \+ '{+ model: $model,+ user: $user,+ input: $text,+ stream: true,+ metadata: {+ PAPERCLIP_RUN_ID: $runId,+ PAPERCLIP_AGENT_ID: $agentId,+ PAPERCLIP_COMPANY_ID: $companyId,+ PAPERCLIP_API_URL: $apiUrl,+ PAPERCLIP_TASK_ID: $taskId,+ PAPERCLIP_WAKE_REASON: $wakeReason,+ PAPERCLIP_WAKE_COMMENT_ID: $wakeCommentId,+ PAPERCLIP_APPROVAL_ID: $approvalId,+ PAPERCLIP_APPROVAL_STATUS: $approvalStatus,+ PAPERCLIP_LINKED_ISSUE_IDS: $linkedIssueIds,+ paperclip_session_key: ("paperclip:run:" + $runId)+ }+ }')"++headers_file="$(mktemp)"+body_file="$(mktemp)"+cleanup() {+ rm -f "$headers_file" "$body_file"+}+trap cleanup EXIT++args=(+ -sS+ -N+ --max-time "$OPENCLAW_TIMEOUT_SEC"+ -X "$OPENCLAW_METHOD"+ -H "content-type: application/json"+ -H "accept: text/event-stream"+ -H "x-openclaw-session-key: paperclip:run:${PAPERCLIP_RUN_ID}"+ -D "$headers_file"+ -o "$body_file"+ --data "$PAYLOAD"+ "$OPENCLAW_URL"+)++if [[ -n "$OPENCLAW_AUTH_HEADER" ]]; then+ args=(-H "Authorization: $OPENCLAW_AUTH_HEADER" "${args[@]}")+fi++log "posting SSE wake payload to ${OPENCLAW_URL}"+http_code="$(curl "${args[@]}" -w "%{http_code}")"+log "http status: ${http_code}"++if [[ ! "$http_code" =~ ^2 ]]; then+ tail -n 80 "$body_file" >&2 || true+ fail "non-success HTTP status: ${http_code}"+fi++if ! grep -Eqi '^content-type:.*text/event-stream' "$headers_file"; then+ tail -n 40 "$body_file" >&2 || true+ fail "response content-type was not text/event-stream"+fi++if grep -Eqi 'event:\s*(error|failed|cancel)|"status":"(failed|cancelled|error)"|"type":"[^"]*(failed|cancelled|error)"' "$body_file"; then+ tail -n 120 "$body_file" >&2 || true+ fail "stream reported a failure event"+fi++if ! grep -Eqi 'event:\s*(done|completed|response\.completed)|\[DONE\]|"status":"(completed|succeeded|done)"|"type":"response\.completed"' "$body_file"; then+ tail -n 120 "$body_file" >&2 || true+ fail "stream ended without a terminal completion marker"+fi++event_count="$(grep -Ec '^event:' "$body_file" || true)"+log "stream completed successfully (events=${event_count})"+echo+tail -n 40 "$body_file"diff --git a/server/src/__tests__/issues-checkout-wakeup.test.ts b/server/src/__tests__/issues-checkout-wakeup.test.tsnew file mode 100644index 0000000000..12b2387095--- /dev/null+++ b/server/src/__tests__/issues-checkout-wakeup.test.ts@@ -0,0 +1,48 @@+import { describe, expect, it } from "vitest";+import { shouldWakeAssigneeOnCheckout } from "../routes/issues-checkout-wakeup.js";++describe("shouldWakeAssigneeOnCheckout", () => {+ it("keeps wakeup behavior for board actors", () => {+ expect(+ shouldWakeAssigneeOnCheckout({+ actorType: "board",+ actorAgentId: null,+ checkoutAgentId: "agent-1",+ checkoutRunId: null,+ }),+ ).toBe(true);+ });++ it("skips wakeup for agent self-checkout in an active run", () => {+ expect(+ shouldWakeAssigneeOnCheckout({+ actorType: "agent",+ actorAgentId: "agent-1",+ checkoutAgentId: "agent-1",+ checkoutRunId: "run-1",+ }),+ ).toBe(false);+ });++ it("still wakes when checkout run id is missing", () => {+ expect(+ shouldWakeAssigneeOnCheckout({+ actorType: "agent",+ actorAgentId: "agent-1",+ checkoutAgentId: "agent-1",+ checkoutRunId: null,+ }),+ ).toBe(true);+ });++ it("still wakes when agent checks out on behalf of another agent id", () => {+ expect(+ shouldWakeAssigneeOnCheckout({+ actorType: "agent",+ actorAgentId: "agent-1",+ checkoutAgentId: "agent-2",+ checkoutRunId: "run-1",+ }),+ ).toBe(true);+ });+});diff --git a/server/src/__tests__/openclaw-adapter.test.ts b/server/src/__tests__/openclaw-adapter.test.tsindex 75835f3aa5..b11b1ffb6f 100644--- a/server/src/__tests__/openclaw-adapter.test.ts+++ b/server/src/__tests__/openclaw-adapter.test.ts@@ -58,28 +58,21 @@ afterEach(() => {});describe("openclaw adapter execute", () => {- it("uses SSE by default and streams into one run", async () => {+ it("uses strict SSE and includes canonical PAPERCLIP context in text payload", async () => {const fetchMock = vi.fn().mockResolvedValue(sseResponse([- 'event: response.delta\n',- 'data: {"type":"response.delta","delta":"hi"}\n\n',- 'event: response.completed\n',+ "event: response.completed\n",'data: {"type":"response.completed","status":"completed"}\n\n',]),);vi.stubGlobal("fetch", fetchMock);- const onLog = vi.fn<AdapterExecutionContext["onLog"]>().mockResolvedValue(undefined);-const result = await execute(- buildContext(- {- url: "https://agent.example/gateway",- method: "POST",- payloadTemplate: { foo: "bar" },- },- { onLog },- ),+ buildContext({+ url: "https://agent.example/sse",+ method: "POST",+ payloadTemplate: { foo: "bar", text: "OpenClaw task prompt" },+ }),);expect(result.exitCode).toBe(0);@@ -88,24 +81,34 @@ describe("openclaw adapter execute", () => {expect(body.foo).toBe("bar");expect(body.stream).toBe(true);expect(body.sessionKey).toBe("paperclip");+ expect((body.paperclip as Record<string, unknown>).streamTransport).toBe("sse");expect((body.paperclip as Record<string, unknown>).runId).toBe("run-123");expect((body.paperclip as Record<string, unknown>).sessionKey).toBe("paperclip");- expect((body.paperclip as Record<string, unknown>).streamTransport).toBe("sse");- expect(onLog).toHaveBeenCalled();+ expect(+ ((body.paperclip as Record<string, unknown>).env as Record<string, unknown>).PAPERCLIP_RUN_ID,+ ).toBe("run-123");+ const text = String(body.text ?? "");+ expect(text).toContain("OpenClaw task prompt");+ expect(text).toContain("PAPERCLIP_RUN_ID=run-123");+ expect(text).toContain("PAPERCLIP_AGENT_ID=agent-123");+ expect(text).toContain("PAPERCLIP_COMPANY_ID=company-123");+ expect(text).toContain("PAPERCLIP_TASK_ID=task-123");+ expect(text).toContain("PAPERCLIP_WAKE_REASON=issue_assigned");+ expect(text).toContain("PAPERCLIP_LINKED_ISSUE_IDS=issue-123");});it("derives issue session keys when configured", async () => {const fetchMock = vi.fn().mockResolvedValue(sseResponse([- 'event: done\n',- 'data: [DONE]\n\n',+ "event: done\n",+ "data: [DONE]\n\n",]),);vi.stubGlobal("fetch", fetchMock);const result = await execute(buildContext({- url: "https://agent.example/gateway",+ url: "https://agent.example/sse",method: "POST",sessionKeyStrategy: "issue",}),@@ -117,32 +120,45 @@ describe("openclaw adapter execute", () => {expect((body.paperclip as Record<string, unknown>).sessionKey).toBe("paperclip:issue:issue-123");});- it("fails when SSE endpoint does not return text/event-stream and no compatibility fallback applies", async () => {+ it("maps requests to OpenResponses schema for /v1/responses endpoints", async () => {const fetchMock = vi.fn().mockResolvedValue(- new Response(JSON.stringify({ ok: false, error: "unexpected payload" }), {- status: 200,- statusText: "OK",- headers: {- "content-type": "application/json",- },- }),+ sseResponse([+ "event: response.completed\n",+ 'data: {"type":"response.completed","status":"completed"}\n\n',+ ]),);vi.stubGlobal("fetch", fetchMock);const result = await execute(buildContext({- url: "https://agent.example/gateway",+ url: "https://agent.example/v1/responses",method: "POST",+ payloadTemplate: {+ model: "openclaw",+ user: "paperclip",+ },}),);- expect(result.exitCode).toBe(1);- expect(result.errorCode).toBe("openclaw_sse_expected_event_stream");+ expect(result.exitCode).toBe(0);+ const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;+ expect(body.stream).toBe(true);+ expect(body.model).toBe("openclaw");+ expect(typeof body.input).toBe("string");+ expect(String(body.input)).toContain("PAPERCLIP_RUN_ID=run-123");+ expect(body.metadata).toBeTypeOf("object");+ expect((body.metadata as Record<string, unknown>).PAPERCLIP_RUN_ID).toBe("run-123");+ expect(body.text).toBeUndefined();+ expect(body.paperclip).toBeUndefined();+ expect(body.sessionKey).toBeUndefined();++ const headers = (fetchMock.mock.calls[0]?.[1]?.headers ?? {}) as Record<string, string>;+ expect(headers["x-openclaw-session-key"]).toBe("paperclip");});- it("treats webhook-style JSON ack as compatibility success when SSE endpoint returns JSON", async () => {+ it("fails when SSE endpoint does not return text/event-stream", async () => {const fetchMock = vi.fn().mockResolvedValue(- new Response(JSON.stringify({ ok: true, runId: "oc-run-1" }), {+ new Response(JSON.stringify({ ok: false, error: "unexpected payload" }), {status: 200,statusText: "OK",headers: {@@ -154,102 +170,90 @@ describe("openclaw adapter execute", () => {const result = await execute(buildContext({- url: "https://agent.example/hooks/paperclip",+ url: "https://agent.example/sse",method: "POST",}),);- expect(result.exitCode).toBe(0);- expect(result.resultJson?.compatibilityMode).toBe("json_ack");- expect(result.resultJson?.transportFallback).toBe("webhook");+ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("openclaw_sse_expected_event_stream");});- it("falls back to wake text payload when SSE is configured against /hooks/wake", async () => {+ it("fails when SSE stream closes without a terminal event", async () => {const fetchMock = vi.fn().mockResolvedValue(- new Response(JSON.stringify({ ok: true }), { status: 200, statusText: "OK" }),+ sseResponse([+ "event: response.delta\n",+ 'data: {"type":"response.delta","delta":"partial"}\n\n',+ ]),);vi.stubGlobal("fetch", fetchMock);const result = await execute(buildContext({- url: "https://agent.example/hooks/wake",- method: "POST",+ url: "https://agent.example/sse",}),);- expect(result.exitCode).toBe(0);- expect(fetchMock).toHaveBeenCalledTimes(1);- const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;- expect(body.mode).toBe("now");- expect(typeof body.text).toBe("string");- expect(body.paperclip).toBeTypeOf("object");- expect((body.paperclip as Record<string, unknown>).runId).toBe("run-123");- expect(result.resultJson?.compatibilityMode).toBe("wake_text");- expect(result.resultJson?.transportFallback).toBe("webhook");+ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("openclaw_sse_stream_incomplete");});- it("uses wake text payload for /hooks/wake endpoints in webhook mode", async () => {+ it("fails with explicit text-required error when endpoint rejects payload", async () => {const fetchMock = vi.fn().mockResolvedValue(- new Response(JSON.stringify({ ok: true }), { status: 200, statusText: "OK" }),+ new Response(JSON.stringify({ error: "text required" }), {+ status: 400,+ statusText: "Bad Request",+ headers: {+ "content-type": "application/json",+ },+ }),);vi.stubGlobal("fetch", fetchMock);const result = await execute(buildContext({- url: "https://agent.example/hooks/wake",- method: "POST",- streamTransport: "webhook",+ url: "https://agent.example/sse",}),);- expect(result.exitCode).toBe(0);- expect(fetchMock).toHaveBeenCalledTimes(1);- const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;- expect(body.mode).toBe("now");- expect(typeof body.text).toBe("string");- expect(body.paperclip).toBeTypeOf("object");- expect((body.paperclip as Record<string, unknown>).runId).toBe("run-123");+ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("openclaw_text_required");});- it("retries with wake text payload when endpoint reports text required in webhook mode", async () => {- const fetchMock = vi- .fn()- .mockResolvedValueOnce(- new Response(JSON.stringify({ ok: false, error: "text required" }), {- status: 400,- statusText: "Bad Request",- }),- )- .mockResolvedValueOnce(- new Response(JSON.stringify({ ok: true }), { status: 200, statusText: "OK" }),- );+ it("rejects non-sse transport configuration", async () => {+ const fetchMock = vi.fn();vi.stubGlobal("fetch", fetchMock);const result = await execute(buildContext({- url: "https://agent.example/hooks/paperclip",- method: "POST",+ url: "https://agent.example/sse",streamTransport: "webhook",}),);- expect(result.exitCode).toBe(0);- expect(fetchMock).toHaveBeenCalledTimes(2);+ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("openclaw_stream_transport_unsupported");+ expect(fetchMock).not.toHaveBeenCalled();+ });- const firstBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;- expect(firstBody.paperclip).toBeTypeOf("object");+ it("rejects /hooks/wake compatibility endpoints in strict SSE mode", async () => {+ const fetchMock = vi.fn();+ vi.stubGlobal("fetch", fetchMock);- const secondBody = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body ?? "{}")) as Record<string, unknown>;- expect(secondBody.mode).toBe("now");- expect(typeof secondBody.text).toBe("string");- expect(secondBody.paperclip).toBeTypeOf("object");- expect((secondBody.paperclip as Record<string, unknown>).runId).toBe("run-123");- expect(result.resultJson?.compatibilityMode).toBe("wake_text");+ const result = await execute(+ buildContext({+ url: "https://agent.example/hooks/wake",+ }),+ );++ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("openclaw_sse_incompatible_endpoint");+ expect(fetchMock).not.toHaveBeenCalled();});});describe("openclaw adapter environment checks", () => {- it("reports compatibility mode info for /hooks/wake endpoints", async () => {+ it("reports /hooks/wake endpoints as incompatible for strict SSE mode", async () => {const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 405, statusText: "Method Not Allowed" }));@@ -269,9 +273,26 @@ describe("openclaw adapter environment checks", () => {},});- const compatibilityCheck = result.checks.find(- (check) => check.code === "openclaw_wake_endpoint_compat_mode",- );- expect(compatibilityCheck?.level).toBe("info");+ const check = result.checks.find((entry) => entry.code === "openclaw_wake_endpoint_incompatible");+ expect(check?.level).toBe("error");+ });++ it("reports unsupported streamTransport settings", async () => {+ const fetchMock = vi+ .fn()+ .mockResolvedValue(new Response(null, { status: 405, statusText: "Method Not Allowed" }));+ vi.stubGlobal("fetch", fetchMock);++ const result = await testEnvironment({+ companyId: "company-123",+ adapterType: "openclaw",+ config: {+ url: "https://agent.example/sse",+ streamTransport: "webhook",+ },+ });++ const check = result.checks.find((entry) => entry.code === "openclaw_stream_transport_unsupported");+ expect(check?.level).toBe("error");});});diff --git a/server/src/routes/access.ts b/server/src/routes/access.tsindex 610f952cee..e310c9a924 100644--- a/server/src/routes/access.ts+++ b/server/src/routes/access.ts@@ -104,6 +104,11 @@ function isLoopbackHost(hostname: string): boolean {return value === "localhost" || value === "127.0.0.1" || value === "::1";}+function isWakePath(pathname: string): boolean {+ const value = pathname.trim().toLowerCase();+ return value === "/hooks/wake" || value.endsWith("/hooks/wake");+}+function normalizeHostname(value: string | null | undefined): string | null {if (!value) return null;const trimmed = value.trim();@@ -217,13 +222,13 @@ function normalizeAgentDefaultsForJoin(input: {code: "openclaw_callback_config_missing",level: "warn",message: "No OpenClaw callback config was provided in agentDefaultsPayload.",- hint: "Include agentDefaultsPayload.url so Paperclip can invoke the OpenClaw webhook immediately after approval.",+ hint: "Include agentDefaultsPayload.url so Paperclip can invoke the OpenClaw SSE endpoint immediately after approval.",});return { normalized: null as Record<string, unknown> | null, diagnostics };}const defaults = input.defaultsPayload as Record<string, unknown>;- const normalized: Record<string, unknown> = {};+ const normalized: Record<string, unknown> = { streamTransport: "sse" };let callbackUrl: URL | null = null;const rawUrl = typeof defaults.url === "string" ? defaults.url.trim() : "";@@ -232,7 +237,7 @@ function normalizeAgentDefaultsForJoin(input: {code: "openclaw_callback_url_missing",level: "warn",message: "OpenClaw callback URL is missing.",- hint: "Set agentDefaultsPayload.url to your OpenClaw webhook endpoint.",+ hint: "Set agentDefaultsPayload.url to your OpenClaw SSE endpoint.",});} else {try {@@ -252,6 +257,14 @@ function normalizeAgentDefaultsForJoin(input: {message: `Callback endpoint set to ${callbackUrl.toString()}`,});}+ if (isWakePath(callbackUrl.pathname)) {+ diagnostics.push({+ code: "openclaw_callback_wake_path_incompatible",+ level: "warn",+ message: "Configured callback path targets /hooks/wake, which is not stream-capable for strict SSE mode.",+ hint: "Use an endpoint that returns text/event-stream for the full run duration.",+ });+ }if (isLoopbackHost(callbackUrl.hostname)) {diagnostics.push({code: "openclaw_callback_loopback",@@ -273,7 +286,7 @@ function normalizeAgentDefaultsForJoin(input: {normalized.method = rawMethod || "POST";if (typeof defaults.timeoutSec === "number" && Number.isFinite(defaults.timeoutSec)) {- normalized.timeoutSec = Math.max(1, Math.min(120, Math.floor(defaults.timeoutSec)));+ normalized.timeoutSec = Math.max(0, Math.min(7200, Math.floor(defaults.timeoutSec)));}const headers = normalizeHeaderMap(defaults.headers);@@ -470,10 +483,10 @@ function buildInviteOnboardingManifest(requiredFields: {requestType: "agent",agentName: "Display name for this agent",- adapterType: "Use 'openclaw' for OpenClaw webhook-based agents",+ adapterType: "Use 'openclaw' for OpenClaw streaming agents",capabilities: "Optional capability summary",agentDefaultsPayload:- "Optional adapter config such as url/method/headers/webhookAuthHeader for OpenClaw callback endpoint",+ "Optional adapter config such as url/method/headers/webhookAuthHeader for OpenClaw SSE endpoint",},registrationEndpoint: {method: "POST",@@ -498,7 +511,7 @@ function buildInviteOnboardingManifest(path: testResolutionPath,url: testResolutionUrl,query: {- url: "https://your-openclaw-webhook.example/webhook",+ url: "https://your-openclaw-agent.example/v1/responses",timeoutMs: 5000,},},@@ -579,10 +592,11 @@ export function buildInviteOnboardingTextDocument(' "adapterType": "openclaw",',' "capabilities": "Optional summary",',' "agentDefaultsPayload": {',- ' "url": "https://your-openclaw-webhook.example/webhook",',+ ' "url": "https://your-openclaw-agent.example/v1/responses",',+ ' "streamTransport": "sse",',' "method": "POST",',' "headers": { "x-openclaw-auth": "replace-me" },',- ' "timeoutSec": 30',+ ' "timeoutSec": 0'," }","}","",@@ -622,9 +636,9 @@ export function buildInviteOnboardingTextDocument(lines.push("","## Optional: test callback resolution from Paperclip",- `${onboarding.connectivity.testResolutionEndpoint.method ?? "GET"} ${onboarding.connectivity.testResolutionEndpoint.url}?url=https%3A%2F%2Fyour-openclaw-webhook.example%2Fwebhook`,+ `${onboarding.connectivity.testResolutionEndpoint.method ?? "GET"} ${onboarding.connectivity.testResolutionEndpoint.url}?url=https%3A%2F%2Fyour-openclaw-agent.example%2Fv1%2Fresponses`,"",- "This endpoint checks whether Paperclip can reach your webhook URL and reports reachable, timeout, or unreachable.",+ "This endpoint checks whether Paperclip can reach your OpenClaw endpoint and reports reachable, timeout, or unreachable.",);}diff --git a/server/src/routes/issues-checkout-wakeup.ts b/server/src/routes/issues-checkout-wakeup.tsnew file mode 100644index 0000000000..287b7bbf6d--- /dev/null+++ b/server/src/routes/issues-checkout-wakeup.ts@@ -0,0 +1,14 @@+type CheckoutWakeInput = {+ actorType: "board" | "agent" | "none";+ actorAgentId: string | null;+ checkoutAgentId: string;+ checkoutRunId: string | null;+};++export function shouldWakeAssigneeOnCheckout(input: CheckoutWakeInput): boolean {+ if (input.actorType !== "agent") return true;+ if (!input.actorAgentId) return true;+ if (input.actorAgentId !== input.checkoutAgentId) return true;+ if (!input.checkoutRunId) return true;+ return false;+}diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex 824493f477..779ac34c6f 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -25,6 +25,7 @@ import {import { logger } from "../middleware/logger.js";import { forbidden, HttpError, unauthorized } from "../errors.js";import { assertCompanyAccess, getActorInfo } from "./authz.js";+import { shouldWakeAssigneeOnCheckout } from "./issues-checkout-wakeup.js";const MAX_ATTACHMENT_BYTES = Number(process.env.PAPERCLIP_ATTACHMENT_MAX_BYTES) || 10 * 1024 * 1024;const ALLOWED_ATTACHMENT_CONTENT_TYPES = new Set([@@ -634,17 +635,26 @@ export function issueRoutes(db: Db, storage: StorageService) {details: { agentId: req.body.agentId },});- void heartbeat- .wakeup(req.body.agentId, {- source: "assignment",- triggerDetail: "system",- reason: "issue_checked_out",- payload: { issueId: issue.id, mutation: "checkout" },- requestedByActorType: actor.actorType,- requestedByActorId: actor.actorId,- contextSnapshot: { issueId: issue.id, source: "issue.checkout" },+ if (+ shouldWakeAssigneeOnCheckout({+ actorType: req.actor.type,+ actorAgentId: req.actor.type === "agent" ? req.actor.agentId ?? null : null,+ checkoutAgentId: req.body.agentId,+ checkoutRunId,})- .catch((err) => logger.warn({ err, issueId: issue.id }, "failed to wake assignee on issue checkout"));+ ) {+ void heartbeat+ .wakeup(req.body.agentId, {+ source: "assignment",+ triggerDetail: "system",+ reason: "issue_checked_out",+ payload: { issueId: issue.id, mutation: "checkout" },+ requestedByActorType: actor.actorType,+ requestedByActorId: actor.actorId,+ contextSnapshot: { issueId: issue.id, source: "issue.checkout" },+ })+ .catch((err) => logger.warn({ err, issueId: issue.id }, "failed to wake assignee on issue checkout"));+ }res.json(updated);});