aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reintroduce OpenClaw webhook transport alongside SSE

Browse Source
This commit is contained in:
Dotta
2026-03-06 15:15:24 -06:00
parent af09510f6a
commit b155415d7d
8 changed files with 1292 additions and 810 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
server/src/__tests__/openclaw-adapter.test.ts
View File

@@ -159,7 +159,7 @@ describe("openclaw ui stdout parser", () => {
});
describe("openclaw adapter execute", () => {
it("uses strict SSE and includes canonical PAPERCLIP context in text payload", async () => {
it("uses SSE transport and includes canonical PAPERCLIP context in text payload", async () => {
const fetchMock = vi.fn().mockResolvedValue(
sseResponse([
"event: response.completed\n",
@@ -534,14 +534,109 @@ describe("openclaw adapter execute", () => {
expect(result.errorCode).toBe("openclaw_text_required");
});
it("rejects non-sse transport configuration", async () => {
it("supports webhook transport and sends Paperclip webhook payloads", async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ ok: true }), {
status: 200,
statusText: "OK",
headers: {
"content-type": "application/json",
},
}),
);
vi.stubGlobal("fetch", fetchMock);
const result = await execute(
buildContext({
url: "https://agent.example/webhook",
streamTransport: "webhook",
payloadTemplate: { foo: "bar" },
}),
);
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.foo).toBe("bar");
expect(body.stream).toBe(false);
expect(body.sessionKey).toBe("paperclip");
expect(String(body.text ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");
expect((body.paperclip as Record<string, unknown>).streamTransport).toBe("webhook");
});
it("uses wake compatibility payloads for /hooks/wake when transport=webhook", async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ ok: true }), {
status: 200,
statusText: "OK",
headers: {
"content-type": "application/json",
},
}),
);
vi.stubGlobal("fetch", fetchMock);
const result = await execute(
buildContext({
url: "https://agent.example/hooks/wake",
streamTransport: "webhook",
}),
);
expect(result.exitCode).toBe(0);
const body = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;
expect(body.mode).toBe("now");
expect(String(body.text ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");
expect(body.paperclip).toBeUndefined();
});
it("retries webhook payloads with wake compatibility format on text-required errors", async () => {
const fetchMock = vi
.fn()
.mockResolvedValueOnce(
new Response(JSON.stringify({ error: "text required" }), {
status: 400,
statusText: "Bad Request",
headers: {
"content-type": "application/json",
},
}),
)
.mockResolvedValueOnce(
new Response(JSON.stringify({ ok: true }), {
status: 200,
statusText: "OK",
headers: {
"content-type": "application/json",
},
}),
);
vi.stubGlobal("fetch", fetchMock);
const result = await execute(
buildContext({
url: "https://agent.example/v1/responses",
streamTransport: "webhook",
}),
);
expect(result.exitCode).toBe(0);
expect(fetchMock).toHaveBeenCalledTimes(2);
const firstBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body ?? "{}")) as Record<string, unknown>;
const secondBody = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body ?? "{}")) as Record<string, unknown>;
expect(firstBody.paperclip).toBeTypeOf("object");
expect(secondBody.mode).toBe("now");
expect(String(secondBody.text ?? "")).toContain("PAPERCLIP_RUN_ID=run-123");
});
it("rejects unsupported transport configuration", async () => {
const fetchMock = vi.fn();
vi.stubGlobal("fetch", fetchMock);
const result = await execute(
buildContext({
url: "https://agent.example/sse",
streamTransport: "webhook",
streamTransport: "invalid",
}),
);
@@ -550,7 +645,7 @@ describe("openclaw adapter execute", () => {
expect(fetchMock).not.toHaveBeenCalled();
});
it("rejects /hooks/wake compatibility endpoints in strict SSE mode", async () => {
it("rejects /hooks/wake compatibility endpoints in SSE mode", async () => {
const fetchMock = vi.fn();
vi.stubGlobal("fetch", fetchMock);
@@ -567,7 +662,7 @@ describe("openclaw adapter execute", () => {
});
describe("openclaw adapter environment checks", () => {
it("reports /hooks/wake endpoints as incompatible for strict SSE mode", async () => {
it("reports /hooks/wake endpoints as incompatible for SSE mode", async () => {
const fetchMock = vi
.fn()
.mockResolvedValue(new Response(null, { status: 405, statusText: "Method Not Allowed" }));
@@ -602,13 +697,36 @@ describe("openclaw adapter environment checks", () => {
adapterType: "openclaw",
config: {
url: "https://agent.example/sse",
streamTransport: "webhook",
streamTransport: "invalid",
},
});
const check = result.checks.find((entry) => entry.code === "openclaw_stream_transport_unsupported");
expect(check?.level).toBe("error");
});
it("accepts webhook 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/hooks/wake",
streamTransport: "webhook",
},
});
const unsupported = result.checks.find((entry) => entry.code === "openclaw_stream_transport_unsupported");
const configured = result.checks.find((entry) => entry.code === "openclaw_stream_transport_configured");
const wakeIncompatible = result.checks.find((entry) => entry.code === "openclaw_wake_endpoint_incompatible");
expect(unsupported).toBeUndefined();
expect(configured?.level).toBe("info");
expect(wakeIncompatible).toBeUndefined();
});
});
describe("onHireApproved", () => {

35
server/src/routes/access.ts
View File

@@ -135,6 +135,14 @@ function isWakePath(pathname: string): boolean {
return value === "/hooks/wake" || value.endsWith("/hooks/wake");
}
function normalizeOpenClawTransport(value: unknown): "sse" | "webhook" | null {
if (typeof value !== "string") return "sse";
const normalized = value.trim().toLowerCase();
if (!normalized || normalized === "sse") return "sse";
if (normalized === "webhook") return "webhook";
return null;
}
function normalizeHostname(value: string | null | undefined): string | null {
if (!value) return null;
const trimmed = value.trim();
@@ -592,13 +600,25 @@ function normalizeAgentDefaultsForJoin(input: {
level: "warn",
message:
"No OpenClaw callback config was provided in agentDefaultsPayload.",
hint: "Include agentDefaultsPayload.url so Paperclip can invoke the OpenClaw SSE endpoint immediately after approval."
hint: "Include agentDefaultsPayload.url so Paperclip can invoke the OpenClaw endpoint immediately after approval."
});
return { normalized: null as Record<string, unknown> | null, diagnostics };
}
const defaults = input.defaultsPayload as Record<string, unknown>;
const streamTransportInput = defaults.streamTransport ?? defaults.transport;
const streamTransport = normalizeOpenClawTransport(streamTransportInput);
const normalized: Record<string, unknown> = { streamTransport: "sse" };
if (!streamTransport) {
diagnostics.push({
code: "openclaw_stream_transport_unsupported",
level: "warn",
message: `Unsupported streamTransport: ${String(streamTransportInput)}`,
hint: "Use streamTransport=sse or streamTransport=webhook."
});
} else {
normalized.streamTransport = streamTransport;
}
let callbackUrl: URL | null = null;
const rawUrl = typeof defaults.url === "string" ? defaults.url.trim() : "";
@@ -607,7 +627,7 @@ function normalizeAgentDefaultsForJoin(input: {
code: "openclaw_callback_url_missing",
level: "warn",
message: "OpenClaw callback URL is missing.",
hint: "Set agentDefaultsPayload.url to your OpenClaw SSE endpoint."
hint: "Set agentDefaultsPayload.url to your OpenClaw endpoint."
});
} else {
try {
@@ -630,12 +650,12 @@ function normalizeAgentDefaultsForJoin(input: {
message: `Callback endpoint set to ${callbackUrl.toString()}`
});
}
if (isWakePath(callbackUrl.pathname)) {
if ((streamTransport ?? "sse") === "sse" && 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.",
"Configured callback path targets /hooks/wake, which is not stream-capable for SSE transport.",
hint: "Use an endpoint that returns text/event-stream for the full run duration."
});
}
@@ -696,7 +716,7 @@ function normalizeAgentDefaultsForJoin(input: {
code: "openclaw_auth_header_missing",
level: "warn",
message: "Gateway auth token is missing from agent defaults.",
hint: "Set agentDefaultsPayload.headers.x-openclaw-auth to the token your OpenClaw /v1/responses endpoint requires."
hint: "Set agentDefaultsPayload.headers.x-openclaw-auth to the token your OpenClaw endpoint requires."
});
}
@@ -943,10 +963,10 @@ function buildInviteOnboardingManifest(
requiredFields: {
requestType: "agent",
agentName: "Display name for this agent",
adapterType: "Use 'openclaw' for OpenClaw streaming agents",
adapterType: "Use 'openclaw' for OpenClaw agents",
capabilities: "Optional capability summary",
agentDefaultsPayload:
"Adapter config for OpenClaw SSE endpoint. MUST include headers.x-openclaw-auth; also include url/method/paperclipApiUrl (and optional webhookAuthHeader/timeoutSec/payloadTemplate)."
"Adapter config for OpenClaw endpoint. MUST include headers.x-openclaw-auth; include streamTransport ('sse' or 'webhook') plus url/method/paperclipApiUrl (and optional webhookAuthHeader/timeoutSec/payloadTemplate)."
},
registrationEndpoint: {
method: "POST",
@@ -1103,6 +1123,7 @@ export function buildInviteOnboardingTextDocument(
IMPORTANT: You MUST include agentDefaultsPayload.headers.x-openclaw-auth with your gateway token.
Without this token, Paperclip callback requests to your OpenClaw endpoint will fail with 401 Unauthorized.
Set "streamTransport" to "sse" for streaming /v1/responses endpoints, or "webhook" for wake-style callbacks.
Body (JSON):
{