feat(openclaw-plugin): bridge W2A sensors to OpenClaw via runEmbedded…

openclaw-plugin/.gitignore

@@ -0,0 +1,4 @@
+dist
+node_modules
+*.tsbuildinfo
+

openclaw-plugin/README.md

@@ -0,0 +1,54 @@
+# @world2agent/openclaw-plugin
+
+Native OpenClaw plugin for running World2Agent sensors and dispatching their signals into embedded OpenClaw agent turns.
+
+The default path is in-process: enabled sensors are imported directly inside the plugin process and each signal is sent to `api.runtime.agent.runEmbeddedAgent(...)`. `isolated: true` is opt-in and reuses the Hermes bridge runner/supervisor patterns for subprocess execution plus plugin-local HTTP ingest.
+
+## Install
+
+1. Set the required OpenClaw agent config first:
+
+   ```yaml
+   agents:
+     defaults:
+       contextInjection: continuation-skip
+   ```
+
+2. Install dependencies and build this package:
+
+   ```bash
+   cd world2agent-plugins/openclaw-plugin
+   pnpm install
+   pnpm build
+   ```
+
+3. Add the plugin package to your OpenClaw plugin search/install path and enable `@world2agent/openclaw-plugin`.
+
+4. Use the registered CLI:
+
+   ```bash
+   openclaw world2agent sensor list
+   openclaw world2agent sensor add @world2agent/sensor-hackernews --config-file ./hackernews.json
+   ```
+
+## Scope
+
+- Reads and writes the W2A sensor manifest at `~/.world2agent/sensors.json` by default.
+- Runs sensors in-process unless a sensor entry sets `isolated: true`.
+- Reuses the Hermes runner/supervisor patterns instead of inventing a second isolation protocol.
+- Uses a stable per-sensor embedded-agent session id: `w2a:<sensor_id>`.
+- Requires plugin config `ingestUrl` only when `isolated: true` sensors are used.
+
+## ContextInjection Prerequisite
+
+This plugin refuses to start unless `agents.defaults.contextInjection` is exactly `"continuation-skip"`.
+
+That check also runs before `openclaw world2agent sensor add`. There is no warning mode, no fallback mode, and no override flag. The design requires a hard failure because OpenClaw's default `"always"` setting would re-inject bootstrap on every sensor signal and silently turn high-frequency sensors into a token sink.
+
+## Relation To `hermes-sensor-bridge`
+
+`hermes-sensor-bridge` solved the same World2Agent runtime problem for Hermes with webhook subscriptions plus supervised subprocesses. This package keeps the same manifest shape and reuses the runner/supervisor mechanics for `isolated: true`, but the primary OpenClaw path is simpler: native plugin registration plus `runEmbeddedAgent(...)`.
+
+## Known M0 Spike
+
+`api.runtime.agent.runEmbeddedAgent(...)` from a third-party external plugin remains a live-install verification point. This package guards it defensively and throws a clear error if the runtime helper is absent, but a real OpenClaw install still has to confirm the end-to-end external-plugin path.

openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,66 @@
+{
+  "id": "world2agent",
+  "name": "World2Agent",
+  "description": "Run World2Agent sensors inside OpenClaw and dispatch signals into embedded agent turns.",
+  "skills": [
+    "./skills/world2agent-manage"
+  ],
+  "commandAliases": [
+    "world2agent"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "sensorsManifestPath": {
+        "type": "string",
+        "description": "Absolute or relative path to the World2Agent sensor manifest."
+      },
+      "stateDir": {
+        "type": "string",
+        "description": "Directory for per-sensor FileSensorStore state."
+      },
+      "sessionDir": {
+        "type": "string",
+        "description": "Directory for plugin-managed embedded-agent session files."
+      },
+      "workspaceDir": {
+        "type": "string",
+        "description": "Workspace directory passed to runEmbeddedAgent when the OpenClaw runtime helper is unavailable."
+      },
+      "ingestUrl": {
+        "type": "string",
+        "description": "Absolute URL for the plugin's /w2a/ingest route when isolated runners are enabled."
+      },
+      "defaultAgentId": {
+        "type": "string",
+        "default": "world2agent",
+        "description": "Dedicated OpenClaw agent id whose skills allowlist should receive W2A skills."
+      },
+      "provider": {
+        "type": "string",
+        "description": "Provider passed to runEmbeddedAgent (e.g. 'openai-codex' for OAuth, 'openai' for API key). When unset OpenClaw resolves from agent/global defaults."
+      },
+      "model": {
+        "type": "string",
+        "description": "Model id passed to runEmbeddedAgent (e.g. 'gpt-5.4'). When unset OpenClaw resolves from agent/global defaults."
+      },
+      "requestTimeoutMs": {
+        "type": "integer",
+        "minimum": 1,
+        "default": 120000,
+        "description": "Timeout passed to runEmbeddedAgent and isolated ingest POSTs."
+      },
+      "ingestHmacSecretFile": {
+        "type": "string",
+        "description": "Path to the HMAC secret used by isolated runner ingest requests."
+      },
+      "ingestDedupTtlMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "default": 3600000,
+        "description": "How long X-Request-ID dedup entries stay in memory."
+      }
+    }
+  }
+}