@perkos/perkos-a2a 0.12.57 → 0.12.58

package/README.md

@@ -130,6 +130,31 @@ curl -s -X POST http://localhost:5050/a2a/jsonrpc \
   -d '{"jsonrpc":"2.0","method":"tasks/list","id":1,"params":{}}' | python3 -m json.tool
 ```
 
+## Which one do you need: plugin or standalone bridge?
+
+This package ships **two different entry points**, and picking the wrong one is
+the most common way to end up with an agent that looks connected but never does
+any work.
+
+| | In-runtime plugin (`index.ts`) | Standalone bridge (`bridge-agent.ts`) |
+|---|---|---|
+| How it runs | Loaded inside the OpenClaw gateway process | Its own process (`perkos-a2a-agent`) |
+| Chat + A2A peer tasks | Yes | Yes |
+| **PerkOS job-board work** | **No** | **Yes** |
+| Reads the dispatcher's board scope | No | Yes |
+| Reply sent back to the caller | Synthesized by the bridge | The runtime's real answer |
+| Board MCP tools (`updateTaskStatus`, …) | Not hosted | Hosted on loopback |
+
+**If the agent has to pick up tasks from a PerkOS board, you need the standalone
+bridge.** This is true for **both** runtimes: it is not a Hermes-only concern.
+The in-runtime plugin ignores the board scope the dispatcher attaches to a task
+and completes the A2A task with a reply it synthesizes itself, so the board
+never advances and the dispatcher burns its retries against a plausible-looking
+answer.
+
+Run **one** of them, never both against the same agent: two listeners will both
+answer the same inbound task.
+
 ## Quick Start
 
 ```bash
@@ -161,6 +186,12 @@ pairing flow. Do not share one global relay key across production agents.
 
 ### OpenClaw agent
 
+> **Board work needs the standalone bridge, not this plugin.** Installing the
+> plugin gives an OpenClaw agent chat and peer-to-peer A2A. It does **not** let
+> it work a PerkOS job board. See
+> [Which one do you need](#which-one-do-you-need-plugin-or-standalone-bridge)
+> and [PerkOS board tools](#perkos-board-tools-job-board-over-mcp).
+
 OpenClaw agents install `@perkos/perkos-a2a` as an OpenClaw plugin:
 
 ```bash
@@ -510,7 +541,10 @@ OpenClaw uses `enqueueSystemEvent` + `requestHeartbeatNow` when available.
 
 Hermes delivery uses the supported Hermes API Server HTTP surface. By default the bridge posts to `/v1/responses`; `/v1/runs` is available when you want observable run state/events, and `/v1/chat/completions` is available for OpenAI-compatible chat payloads. Validate the local Hermes API Server with `GET /health` and `GET /v1/capabilities`. Do not use UI/workspace endpoints such as `/api/session-send` or `/api/sessions/send`; those are not the stable Hermes runtime delivery interface.
 
-Hermes does not load OpenClaw plugins, so run the standalone bridge next to Hermes with API Server enabled:
+Hermes does not load OpenClaw plugins, so a Hermes agent always runs the standalone
+bridge. Note this is not the only reason to run it: an **OpenClaw** agent that has to
+work a PerkOS board needs the standalone bridge too (point `HERMES_API_URL` at the
+OpenClaw gateway and set `A2A_RUNTIME=openclaw`). Run it with API Server enabled:
 
 ```bash
 A2A_AGENT_NAME=hermes-agent \
@@ -672,6 +706,60 @@ When the plugin is active, three tools are available to the agent:
 | `perkos_a2a_send` | Send a task to a named peer (direct HTTP → relay fallback) |
 | `perkos_a2a_status` | Check the status of a previously sent task by ID |
 
+These three are the plugin's **entire** tool surface. Job-board tools are not
+here: they are served over MCP by the standalone bridge, below.
+
+## PerkOS board tools (job board over MCP)
+
+To let an agent actually work a PerkOS job board (claim a task, move it to
+Done, post to the project chat), the **standalone bridge** hosts a local MCP
+server exposing the board tools natively. The model calls them like any other
+tool: no shell, no `execute_code`, no approval gate. It works for **both**
+runtimes, Hermes and OpenClaw.
+
+The bridge mints a wallet-scoped, short-lived JWT per call using
+`A2A_TOOLS_JWT_SECRET`, which never leaves the bridge process. The model never
+supplies a wallet, only board arguments such as `projectId`.
+
+Tools exposed: `createTask`, `updateTaskStatus`, `listProjectTasks`,
+`postProjectMessage`, `listDocs`, `createDoc`, `readDoc`, `upsertPlanGroup`,
+`upsertPlanTask`, `proposePlan`, `postDocMessage`.
+
+### Enabling it
+
+All three of these must be set on the **bridge** process, or the board MCP
+server silently does not start:
+
+| Variable | Required | Notes |
+|---|---|---|
+| `A2A_TOOLS_JWT_SECRET` | yes | Must be **>=32 characters**, or the listener is disabled. Must equal the Tools API's `JWT_SHARED_SECRET`. |
+| `A2A_TOOLS_API_URL` | yes | e.g. `https://api.perkos.xyz/tools` |
+| `PERKOS_OWNER_WALLET` | yes | The board owner's wallet. **Without it the board MCP server is disabled** and the agent has no way to move a task. |
+| `A2A_BOARD_MCP_PORT` | no | Defaults to `5071`. |
+| `A2A_TOOLS_TOKEN_TTL_SECONDS` | no | Defaults to `60`. |
+
+Startup is logged. If you see this line, the agent can receive board tasks but
+can never complete them:
+
+```
+[board-mcp] PERKOS_OWNER_WALLET unset — board MCP server disabled (set it to enable native job-board tools)
+```
+
+Then point the runtime's MCP client at `http://127.0.0.1:5071` (transport:
+MCP streamable-http). The server binds loopback only.
+
+### Symptom checklist
+
+An agent that is assigned board tasks but never moves them usually has one of:
+
+1. It is running the **in-runtime plugin** instead of the standalone bridge, so
+   the board scope never reaches it and the reply is synthesized. Check for a
+   separate `perkos-a2a-agent` / `bridge-agent.js` process; if there is none,
+   this is your problem.
+2. `PERKOS_OWNER_WALLET` is unset, so the board tools were never served.
+3. `A2A_TOOLS_JWT_SECRET` is shorter than 32 characters, or does not match the
+   Tools API secret.
+
 ## CLI Commands
 
 ```bash

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -27782,6 +27782,22 @@ import { readFileSync as readFileSync5 } from "node:fs";
 import { dirname as dirname3, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
+// src/task-context.ts
+function perkosTaskContext(task, trustedDispatcher = process.env.PERKOS_DISPATCHER_AGENT_NAME || "perkos-ci-probe-dispatcher") {
+  const metadata = task.metadata;
+  if (metadata?.fromAgent !== trustedDispatcher) return void 0;
+  const raw = metadata.perkosBoard;
+  if (!raw || typeof raw !== "object") return void 0;
+  const value = raw;
+  if (typeof value.wallet !== "string" || typeof value.convId !== "string") {
+    return void 0;
+  }
+  const wallet = value.wallet.trim().toLowerCase();
+  const convId = value.convId.trim();
+  if (!/^0x[0-9a-f]{40}$/.test(wallet) || !convId) return void 0;
+  return { wallet, convId };
+}
+
 // src/agentic-actions.ts
 var FALLBACK_AGENT_ALIASES = [
   ["Perkos-Claw-Tester", ["perkos-claw-tester", "openclaw", "open claw", "claw"]],
@@ -29654,6 +29670,7 @@ function isWebhookEvent(msg) {
 }
 
 // src/index.ts
+var warnedBoardTaskUnsupported = false;
 function loadedPluginVersion() {
   try {
     const manifest = JSON.parse(readFileSync5(new URL("../openclaw.plugin.json", import.meta.url), "utf8"));
@@ -30158,6 +30175,12 @@ function register(api) {
       });
       return;
     }
+    if (!warnedBoardTaskUnsupported && perkosTaskContext(task)) {
+      warnedBoardTaskUnsupported = true;
+      logger.error(
+        '[perkos-a2a] This is a PerkOS BOARD task, and the in-runtime plugin cannot work a board. It will be answered with a synthesized reply and the task will never move. Run the standalone bridge (perkos-a2a-agent) for this agent instead, with A2A_TOOLS_JWT_SECRET, A2A_TOOLS_API_URL and PERKOS_OWNER_WALLET set, then disable this plugin so both do not answer the same task. See the README section "Which one do you need: plugin or standalone bridge?".'
+      );
+    }
     task.artifacts.push({
       kind: "artifact",
       artifactId: randomUUID7(),