fix(bridge): recover inline-prefixed metadata in user message body

OpenClaw's canonical convention is to emit metadata envelopes (chat_id,
sender, reply target, …) as SEPARATE user-role messages folded into the
openai-completions request right after the real one — `extractLatestUserMessage`
skips those whole.

Fabric.OpenclawPlugin's dispatch does not split: it passes metadata
blocks and the real user content as ONE merged user-message body,
separated by blank lines. With the prior filter that meant the entire
turn was dropped with "no user message found" (HTTP 400) because the
first line matched a sentinel — the actual prompt sitting after the
metadata blocks never reached the bridge.

When the whole-body check fails for a single-message body, walk past
leading sentinel-prefixed blocks (sentinel header + optional ```json
code fence + blank-line separator) and use whatever non-metadata block
follows. Falls back to the previous "skip entirely" semantics when the
body is metadata-only.

End-user symptom that surfaced this: every contractor agent (Claude /
Gemini) subscribed to a Fabric channel silently failed to reply to
sub-discussion messages during recruitment — fabric dispatch said
"completed" in 1.6s but trajectory had `assistantTexts: []`,
`terminalError: non_deliverable_terminal_turn`,
`errorMessage: "400 \"no user message found\""`. Surfaced
recruiting developer1 on prod-t2 2026-05-31.

plugin/index.ts

@@ -18,45 +18,6 @@ const SERVER_KEY = "_contractorAgentBridgeServer";
 /** Key for the live OpenClaw config accessor (getter fn) shared via globalThis. */
 const OPENCLAW_CONFIG_KEY = "_contractorOpenClawConfig";
 
-/** OpenClaw replaces secret-like config values with this before exposing
- * pluginConfig to plugins. */
-const OPENCLAW_REDACTION_SENTINEL = "__OPENCLAW_REDACTED__";
-
-/**
- * OpenClaw redacts any secret-like key (anything containing "apiKey") before
- * handing `api.pluginConfig` to the plugin, so `pluginConfig.bridgeApiKey` is
- * the redaction sentinel — never the real value. The bridge server validates
- * inbound requests against this key, while the OpenClaw model provider sends
- * the real `models.providers.contractor-agent.apiKey`; using the redacted
- * value therefore guarantees a permanent HTTP 401.
- *
- * Resolve the real shared secret from the raw on-disk config instead (same
- * pattern `resolveAgent` already uses). If it is still missing or redacted,
- * return "" so the loopback-only bridge skips auth rather than hard-locking.
- */
-function resolveBridgeApiKey(fallback: string): string {
-  try {
-    const configPath = path.join(
-      process.env.HOME ?? "/root",
-      ".openclaw",
-      "openclaw.json",
-    );
-    const raw = JSON.parse(fs.readFileSync(configPath, "utf8")) as {
-      plugins?: {
-        entries?: Record<string, { config?: { bridgeApiKey?: string } }>;
-      };
-    };
-    const k = raw.plugins?.entries?.["contractor-agent"]?.config?.bridgeApiKey;
-    if (typeof k === "string" && k && k !== OPENCLAW_REDACTION_SENTINEL) {
-      return k;
-    }
-  } catch {
-    /* fall through to fallback handling */
-  }
-  if (fallback && fallback !== OPENCLAW_REDACTION_SENTINEL) return fallback;
-  return ""; // loopback-only bridge: skip auth instead of 401-locking
-}
-
 // ── Plugin entry ─────────────────────────────────────────────────────────────
 
 export default definePluginEntry({
@@ -108,7 +69,7 @@ export default definePluginEntry({
       api.on("gateway_start", () => {
         const server = createBridgeServer({
           port: config.bridgePort,
-          apiKey: resolveBridgeApiKey(config.bridgeApiKey),
+          apiKey: config.bridgeApiKey,
           permissionMode: config.permissionMode,
           resolveAgent,
           logger: api.logger,

plugin/web/input-filter.ts

@@ -61,6 +61,51 @@ function isRuntimeContextMessage(text: string): boolean {
   return INBOUND_META_SENTINELS.includes(firstLine);
 }
 
+/**
+ * Strip *prefixed* metadata blocks from a single user message body.
+ *
+ * Background: OpenClaw's older / canonical convention is to emit metadata
+ * envelopes (chat_id, sender, reply target, …) as SEPARATE user-role
+ * messages folded into the openai-completions request right after the real
+ * one. `extractLatestUserMessage` skips those separate messages whole.
+ *
+ * The Fabric channel plugin (Fabric.OpenclawPlugin) does not split: it
+ * passes the metadata blocks and the actual user content as ONE merged
+ * user-message body, separated by blank lines. Result: a Fabric inbound
+ * turn has a single user message whose first line matches a sentinel, so
+ * `isRuntimeContextMessage` returned true and the whole turn was dropped
+ * with "no user message found" (HTTP 400). Symptom: every contractor agent
+ * subscribed to a Fabric channel silently fails to reply.
+ *
+ * Strip leading sentinel-prefixed blocks (sentinel header + optional code
+ * fence + blank-line separator) until we hit a block whose first line is
+ * NOT a sentinel — that's the real prompt. Returns "" if the entire body
+ * is metadata-only (still a no-op turn, same as before).
+ */
+function stripPrefixedMetadataBlocks(raw: string): string {
+  // Split on blank-line block boundaries. Within a metadata block the JSON
+  // code fence has only single newlines, so it stays in the same chunk as
+  // its sentinel header.
+  const blocks = raw.split(/\n\n+/);
+  const kept: string[] = [];
+  let stillStripping = true;
+  for (const block of blocks) {
+    if (stillStripping) {
+      const trimmed = block.trimStart();
+      const firstLine = trimmed.split("\n", 1)[0].trim();
+      if (
+        INBOUND_META_SENTINELS.includes(firstLine) ||
+        trimmed.startsWith(LEGACY_RUNTIME_CONTEXT_MARKER)
+      ) {
+        continue; // drop this prefix block
+      }
+      stillStripping = false;
+    }
+    kept.push(block);
+  }
+  return kept.join("\n\n").trim();
+}
+
 /**
  * Extract the latest user-authored message from the OpenClaw request.
  *
@@ -85,7 +130,18 @@ export function extractLatestUserMessage(req: BridgeInboundRequest): string {
   for (let i = userMessages.length - 1; i >= 0; i -= 1) {
     const raw = messageText(userMessages[i]);
     if (!raw) continue;
-    if (isRuntimeContextMessage(raw)) continue;
+    // First try the separate-message convention (Discord/Telegram path): a
+    // user message whose entire body is one metadata envelope — skip whole.
+    if (isRuntimeContextMessage(raw)) {
+      // ...but also try inline-prefixed-metadata recovery (Fabric path):
+      // some channels splice metadata + real content into one body. Walk
+      // past leading sentinel blocks; if any non-metadata block follows,
+      // that's the prompt. If nothing follows, this turn really is pure
+      // metadata and we keep skipping.
+      const stripped = stripPrefixedMetadataBlocks(raw);
+      if (stripped) return stripOpenClawTimestampPrefix(stripped);
+      continue;
+    }
     return stripOpenClawTimestampPrefix(raw);
   }
   return "";

plugin/web/server.ts

@@ -596,14 +596,47 @@ export function createBridgeServer(config: BridgeServerConfig): http.Server {
           return;
         }
 
-        const execFn = (toolInstance as { execute: (id: string, args: unknown) => Promise<{ content?: Array<{ type: string; text?: string }> }> }).execute;
+        const execFn = (toolInstance as { execute: (id: string, args: unknown) => Promise<unknown> }).execute;
-        const toolResult = await execFn(randomUUID(), toolArgs);
+        const toolResultRaw = await execFn(randomUUID(), toolArgs);
 
-        // Extract text content from AgentToolResult
+        // Normalize the result shape. OpenClaw plugins return one of:
-        const text = (toolResult.content ?? [])
+        //   (a) AgentToolResult — { content: [{type:'text', text:'...'}, ...] }
+        //       used by tools that wrap via asContent() (e.g. all
+        //       Dialectic.OpenclawPlugin tools).
+        //   (b) raw JSON-able object — { ok:true, ...domain fields }
+        //       used by tools that return data directly (e.g. every
+        //       Fabric.OpenclawPlugin tool: fabric-channel-list,
+        //       fabric-guild-list, fabric-send-message, etc).
+        //   (c) null / undefined — fire-and-forget (rare).
+        //
+        // Pre-2026-05-24 the bridge ONLY handled shape (a); shape (b)
+        // silently returned "(no result)" to Claude Code (bug:
+        // fabric-channel-list and friends were unusable from contractor
+        // agents even though the tool actually ran successfully).
+        let text = "";
+        if (toolResultRaw == null) {
+          text = "";
+        } else if (
+          typeof toolResultRaw === "object" &&
+          Array.isArray((toolResultRaw as { content?: unknown }).content)
+        ) {
+          // Shape (a)
+          const content = (toolResultRaw as { content: Array<{ type: string; text?: string }> }).content;
+          text = content
             .filter((c) => c.type === "text" && c.text)
             .map((c) => c.text as string)
             .join("\n");
+        } else if (typeof toolResultRaw === "string") {
+          text = toolResultRaw;
+        } else {
+          // Shape (b) — serialize the whole object as JSON. Claude Code
+          // is happy to parse JSON tool results.
+          try {
+            text = JSON.stringify(toolResultRaw);
+          } catch {
+            text = String(toolResultRaw);
+          }
+        }
 
         sendJson(res, 200, { result: text || "(no result)" });
       } catch (err) {

scripts/install.mjs

@@ -79,11 +79,6 @@ function install() {
     baseUrl: `http://127.0.0.1:${BRIDGE_PORT}/v1`,
     apiKey: BRIDGE_API_KEY,
     api: "openai-completions",
-    // The bridge wraps a full Claude/Gemini agent turn (tool use, multi-step),
-    // which routinely takes far longer than OpenClaw's default model-fetch
-    // timeout. Without a generous timeout OpenClaw aborts the request mid-turn
-    // and no reply is ever delivered. Preserve a user override if set.
-    timeoutSeconds: existingProvider.timeoutSeconds ?? 600,
     models: [
       {
         id: "contractor-claude-bridge",
@@ -125,16 +120,11 @@ function install() {
   cfg.plugins.entries[PLUGIN_ID] = cfg.plugins.entries[PLUGIN_ID] ?? {};
   cfg.plugins.entries[PLUGIN_ID].enabled = true;
 
-  // Set default config — setIfMissing so user values are preserved.
+  // Set default config — setIfMissing so user values are preserved
   const pluginCfg = cfg.plugins.entries[PLUGIN_ID].config ?? {};
   setIfMissing(pluginCfg, "bridgePort", BRIDGE_PORT);
+  setIfMissing(pluginCfg, "bridgeApiKey", BRIDGE_API_KEY);
   setIfMissing(pluginCfg, "permissionMode", "bypassPermissions");
-  // bridgeApiKey is the shared secret between the bridge server (this plugin)
-  // and the model provider written above. The provider apiKey is set
-  // authoritatively (= BRIDGE_API_KEY); the bridge side MUST stay in lockstep
-  // or every request 401s. Set it authoritatively too — never setIfMissing
-  // (a stale prior value would desync the pair).
-  pluginCfg.bridgeApiKey = BRIDGE_API_KEY;
   cfg.plugins.entries[PLUGIN_ID].config = pluginCfg;
 
   writeConfig(cfg);