@perkos/perkos-a2a 0.8.11 → 0.8.13

package/README.md

@@ -117,6 +117,8 @@ openclaw perkos-a2a status
         "config": {
           "agentName": "my-agent",
           "port": 5050,
+          "bindHost": "0.0.0.0",
+          "publicUrl": "https://my-agent.example.com",
           "mode": "auto",
           "skills": [
             {
@@ -140,6 +142,10 @@ openclaw perkos-a2a status
             "url": "wss://relay.example.com:8787",
             "apiKey": "relay-api-key",
             "enabled": true
+          },
+          "runtime": {
+            "kind": "openclaw",
+            "sessionKey": "agent:main"
           }
         }
       }
@@ -151,7 +157,9 @@ openclaw perkos-a2a status
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `agentName` | string | `"agent"` | This agent's name in the network |
-| `port` | number | `5050` | HTTP server port (avoid 5000 on macOS — AirPlay) |
+| `port` | number | `5050` | HTTP server port. Use one unique port per agent/container on shared VPS hosts |
+| `bindHost` | string | `0.0.0.0` | Interface to bind. Use `0.0.0.0` in Docker, `127.0.0.1` behind local reverse proxies/tunnels |
+| `publicUrl` | string | — | Externally reachable base URL advertised in Agent Card; use DNS/tunnel/LAN URL when localhost is not reachable |
 | `mode` | string | `"auto"` | Operating mode: `auto`, `full`, `client-only`, `relay` |
 | `skills` | array | `[]` | Skills exposed via the agent card |
 | `peers` | object | `{}` | Map of peer names → A2A base URLs |
@@ -161,6 +169,91 @@ openclaw perkos-a2a status
 | `relay.url` | string | — | Relay hub WebSocket URL |
 | `relay.apiKey` | string | — | API key for relay hub authentication |
 | `relay.enabled` | boolean | `false` | Enable relay connectivity |
+| `runtime.kind` | string | `"openclaw"` | Inbound execution target: `openclaw`, `hermes`, or `none` |
+| `runtime.sessionKey` | string | runtime-specific | Target session (`agent:main` for OpenClaw, `main` for Hermes) |
+| `runtime.hermesUrl` | string | `http://127.0.0.1:3000` | Hermes Workspace URL when `runtime.kind = "hermes"` |
+| `runtime.hermesToken` | string | — | Optional Hermes Workspace session token, sent as `claude-auth` cookie |
+| `runtime.hermesEndpoint` | string | `/api/session-send` | Hermes Workspace send endpoint |
+
+## OpenClaw ↔ Hermes Delivery
+
+PerkOS A2A now separates the transport from the local runtime. Direct HTTP and relay routing stay the same, but inbound tasks can be delivered into either OpenClaw or Hermes Workspace.
+
+### OpenClaw receiver
+
+```json
+"runtime": {
+  "kind": "openclaw",
+  "sessionKey": "agent:main"
+}
+```
+
+OpenClaw uses `enqueueSystemEvent` + `requestHeartbeatNow` when available.
+
+### Hermes receiver
+
+```json
+"runtime": {
+  "kind": "hermes",
+  "sessionKey": "main",
+  "hermesUrl": "http://127.0.0.1:3000",
+  "hermesToken": "OPTIONAL_WORKSPACE_SESSION_TOKEN"
+}
+```
+
+Hermes delivery posts to `/api/session-send`, which forwards into Hermes Workspace's streaming chat path. If the Workspace has password protection enabled, provide the persisted workspace session token as `runtime.hermesToken` or `HERMES_WORKSPACE_TOKEN`.
+
+Hermes does not load OpenClaw plugins, so run the standalone bridge next to Hermes Workspace:
+
+```bash
+A2A_AGENT_NAME=hermes-agent \
+A2A_RUNTIME=hermes \
+A2A_MODE=client-only \
+A2A_RELAY_ENABLED=true \
+A2A_RELAY_URL=wss://relay.example.com \
+A2A_RELAY_API_KEY=*** \
+HERMES_WORKSPACE_URL=http://127.0.0.1:3000 \
+perkos-a2a-agent
+```
+
+The bridge keeps an outbound relay WebSocket open, so agents behind NAT or dynamic IPs receive tasks without cron polling or inbound port forwarding.
+
+## Deployment Reality: Docker, VPS, NAT, and Dynamic IPs
+
+PerkOS A2A must not assume one public machine equals one agent. Real deployments often run many agents as Docker containers on one VPS, or several local machines behind one office/home NAT.
+
+### Multiple Docker agents on one VPS
+
+Each agent needs a unique internal/listening port and, if exposed through the host, a unique host port or reverse-proxy route.
+
+```yaml
+services:
+  morpheus:
+    image: openclaw-agent
+    ports:
+      - "127.0.0.1:5050:5050"
+    environment:
+      A2A_AGENT_NAME: morpheus
+
+  neo:
+    image: openclaw-agent
+    ports:
+      - "127.0.0.1:5051:5050"
+    environment:
+      A2A_AGENT_NAME: neo
+```
+
+Recommended pattern: keep container ports private, put Caddy/Nginx/Traefik in front, and set each agent's `publicUrl` to its stable route, e.g. `https://morpheus-a2a.example.com`.
+
+### NAT / changing public IP
+
+For office/home/local agents behind NAT, direct P2P is brittle because all machines share one external IP and that IP can change. Use one of these patterns:
+
+1. **Relay hub** — preferred default. Every agent opens an outbound WebSocket to the relay; no inbound ports or static IP required.
+2. **Tunnel/DNS** — Cloudflare Tunnel, Tailscale Funnel, ngrok, or similar. Set `publicUrl` to the stable tunnel hostname.
+3. **Direct LAN/VPN only** — okay for trusted LAN/Tailscale networks, but still require API keys.
+
+Do not expose unauthenticated A2A ports publicly. If direct HTTP is used, pair `auth.requireApiKey` with per-peer `peerAuth`.
 
 ## Modes
 
@@ -254,6 +347,39 @@ Agent A                           Agent B
 └─────────────┘                  └─────────────┘
 ```
 
+## Registrar / Rendezvous Security Model
+
+The relay hub should be treated as a **registrar/rendezvous server**, not as an unrestricted public chat server. Its jobs are:
+
+1. Keep presence: which approved agents are currently connected.
+2. Route frames when direct HTTP is impossible because of NAT, Docker, or dynamic IPs.
+3. Reject unapproved agents before they can discover or message anyone.
+
+In production, prefer an explicit approved-agent registry instead of one shared relay key:
+
+```bash
+a2a-relay \
+  --port 6060 \
+  --agents morpheus:KEY_FOR_MORPHEUS,neo:KEY_FOR_NEO,hermes-agent:KEY_FOR_HERMES
+```
+
+Or via environment:
+
+```bash
+RELAY_AGENTS="morpheus:KEY_FOR_MORPHEUS,neo:KEY_FOR_NEO,hermes-agent:KEY_FOR_HERMES" a2a-relay
+```
+
+With `registeredAgents` enabled:
+
+- An agent can only register under its approved name with its own key.
+- A stolen/shared key cannot impersonate another agent name.
+- Messages to unapproved target names are rejected.
+- Discovery only returns currently connected approved agents.
+
+A future pairing flow can generate these entries automatically: human approves an agent card/fingerprint, server stores `agentName -> registration key`, and only then can that agent connect.
+
+For Nexus-style product backends, see [`docs/nexus-communications-server.md`](docs/nexus-communications-server.md) for the communications-server pattern: backend orchestrator → A2A relay → OpenClaw/Hermes runtime worker → authenticated backend callbacks.
+
 ### Relay Hub (NAT Traversal)
 
 Agents behind NAT connect outbound to the relay hub via WebSocket. No port forwarding needed.

package/bin/agent.ts

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Standalone PerkOS A2A bridge.
+ *
+ * This is for runtimes that do not load OpenClaw plugins directly, especially
+ * Hermes Workspace. It runs the same A2A HTTP/relay server and delivers inbound
+ * tasks into a local runtime over that runtime's native wake/send API.
+ *
+ * Usage:
+ *   perkos-a2a-agent --config ./a2a.config.json
+ *   A2A_AGENT_NAME=hermes A2A_RUNTIME=hermes HERMES_WORKSPACE_URL=http://127.0.0.1:3000 perkos-a2a-agent
+ */
+
+import { readFileSync } from "fs";
+import { randomUUID } from "crypto";
+import { A2AServer } from "../src/server.js";
+import type { A2APluginConfig, Task } from "../src/types.js";
+
+function argValue(flag: string): string | undefined {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return undefined;
+  return process.argv[idx + 1];
+}
+
+function parseJsonEnv<T>(name: string, fallback: T): T {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch (err) {
+    throw new Error(`${name} must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+function loadConfig(): A2APluginConfig {
+  const configPath = argValue("--config") || argValue("-c") || process.env.A2A_CONFIG;
+  if (configPath) {
+    return JSON.parse(readFileSync(configPath, "utf8")) as A2APluginConfig;
+  }
+
+  const port = Number(process.env.A2A_PORT || "5050");
+  const relayEnabled = String(process.env.A2A_RELAY_ENABLED || "").toLowerCase() === "true";
+  return {
+    agentName: process.env.A2A_AGENT_NAME || "agent",
+    port,
+    bindHost: process.env.A2A_BIND_HOST || "0.0.0.0",
+    publicUrl: process.env.A2A_PUBLIC_URL,
+    mode: (process.env.A2A_MODE as A2APluginConfig["mode"]) || "auto",
+    skills: parseJsonEnv("A2A_SKILLS", []),
+    peers: parseJsonEnv("A2A_PEERS", {}),
+    peerAuth: parseJsonEnv("A2A_PEER_AUTH", {}),
+    auth: process.env.A2A_API_KEYS
+      ? { requireApiKey: true, apiKeys: process.env.A2A_API_KEYS.split(",").map((v) => v.trim()).filter(Boolean) }
+      : undefined,
+    relay: relayEnabled || process.env.A2A_RELAY_URL
+      ? {
+          enabled: relayEnabled || Boolean(process.env.A2A_RELAY_URL),
+          url: process.env.A2A_RELAY_URL || "",
+          apiKey: process.env.A2A_RELAY_API_KEY || "",
+          hubPort: process.env.A2A_RELAY_HUB_PORT ? Number(process.env.A2A_RELAY_HUB_PORT) : undefined,
+          hubApiKeys: process.env.A2A_RELAY_HUB_API_KEYS?.split(",").map((v) => v.trim()).filter(Boolean),
+        }
+      : undefined,
+    runtime: {
+      kind: (process.env.A2A_RUNTIME as A2APluginConfig["runtime"] extends infer R ? R extends { kind?: infer K } ? K : never : never) || "hermes",
+      sessionKey: process.env.A2A_SESSION_KEY,
+      hermesUrl: process.env.HERMES_WORKSPACE_URL,
+      hermesToken: process.env.HERMES_WORKSPACE_TOKEN || process.env.HERMES_SESSION_TOKEN,
+      hermesEndpoint: process.env.HERMES_WORKSPACE_ENDPOINT,
+    },
+  };
+}
+
+function taskMarker(task: Task): string {
+  return `[A2A_RESULT:${task.id}]`;
+}
+
+function buildRuntimeMessage(task: Task, text: string): string {
+  const from = (task.metadata?.fromAgent as string) || "unknown";
+  const marker = taskMarker(task);
+  return [
+    marker,
+    `From: ${from}`,
+    `Task ID: ${task.id}`,
+    `Context ID: ${task.contextId}`,
+    "",
+    "Execute the following request and include the final answer in your assistant reply.",
+    `Your final answer must begin with exactly: ${marker}`,
+    "Return the useful final answer after that marker.",
+    "",
+    text,
+  ].join("\n");
+}
+
+async function deliverToHermes(config: A2APluginConfig, message: string): Promise<void> {
+  const runtime = config.runtime || {};
+  const baseUrl = (runtime.hermesUrl || process.env.HERMES_WORKSPACE_URL || "http://127.0.0.1:3000").replace(/\/+$/, "");
+  const endpoint = runtime.hermesEndpoint || "/api/session-send";
+  const sessionKey = runtime.sessionKey || "main";
+  const token = runtime.hermesToken || process.env.HERMES_WORKSPACE_TOKEN || process.env.HERMES_SESSION_TOKEN;
+  const url = `${baseUrl}${endpoint.startsWith("/") ? endpoint : `/${endpoint}`}`;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (token) headers.cookie = `claude-auth=${token}`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ sessionKey, message }),
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(`Hermes delivery failed (${response.status}): ${body || response.statusText}`);
+  }
+}
+
+async function main(): Promise<void> {
+  const config = loadConfig();
+  const logger = console;
+  const server = new A2AServer(config, logger);
+
+  server.setTaskResultHandler(async (task, text) => {
+    const runtimeKind = config.runtime?.kind || "hermes";
+    task.status = {
+      state: "working",
+      timestamp: new Date().toISOString(),
+      message: { role: "agent", parts: [{ kind: "text", text: `Task dispatched to ${runtimeKind} runtime.` }] },
+    };
+
+    if (runtimeKind === "hermes") {
+      await deliverToHermes(config, buildRuntimeMessage(task, text));
+      task.artifacts.push({
+        kind: "artifact",
+        artifactId: randomUUID(),
+        parts: [{ kind: "text", text: "Delivered to Hermes Workspace." }],
+      });
+      return;
+    }
+
+    if (runtimeKind === "none") {
+      task.artifacts.push({
+        kind: "artifact",
+        artifactId: randomUUID(),
+        parts: [{ kind: "text", text: "Runtime delivery disabled." }],
+      });
+      return;
+    }
+
+    throw new Error(`Standalone runtime '${runtimeKind}' is not supported yet. Use OpenClaw plugin mode for OpenClaw delivery.`);
+  });
+
+  server.setTaskFailureHandler((task, errorText) => {
+    task.status = {
+      state: "failed",
+      timestamp: new Date().toISOString(),
+      message: { role: "agent", parts: [{ kind: "text", text: errorText }] },
+    };
+  });
+
+  await server.start();
+  logger.info(`[perkos-a2a] standalone bridge running for ${config.agentName} (${config.runtime?.kind || "hermes"})`);
+
+  const stop = () => {
+    logger.info("[perkos-a2a] standalone bridge shutting down");
+    process.exit(0);
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+}
+
+main().catch((err) => {
+  console.error(`[perkos-a2a] standalone bridge failed: ${err instanceof Error ? err.stack || err.message : String(err)}`);
+  process.exit(1);
+});

package/bin/relay.ts

@@ -8,6 +8,7 @@
  * Environment variables:
  *   RELAY_PORT          - WebSocket port (default: 6060)
  *   RELAY_API_KEYS      - Comma-separated list of accepted API keys
+ *   RELAY_AGENTS        - Comma-separated approved agents as name:key,name2:key2
  *   RELAY_MAX_QUEUE     - Max queued messages per offline agent (default: 200)
  *   RELAY_RATE_LIMIT    - Max messages per agent per minute (default: 60)
  */
@@ -28,6 +29,14 @@ function parseArgs(): Partial<RelayHubConfig> {
       case "--api-keys":
         config.apiKeys = args[++i].split(",").map((k) => k.trim()).filter(Boolean);
         break;
+      case "--agents":
+        config.registeredAgents = Object.fromEntries(
+          args[++i].split(",").map((entry) => {
+            const [name, ...keyParts] = entry.split(":");
+            return [name.trim(), keyParts.join(":").trim()];
+          }).filter(([name, key]) => name && key)
+        );
+        break;
       case "--max-queue":
         config.maxQueuePerAgent = parseInt(args[++i], 10);
         break;
@@ -40,7 +49,8 @@ function parseArgs(): Partial<RelayHubConfig> {
         console.log("");
         console.log("Options:");
         console.log("  --port, -p <port>       WebSocket port (default: 6060)");
-        console.log("  --api-keys <k1,k2,...>  Accepted API keys (default: none, auth disabled)");
+        console.log("  --api-keys <k1,k2,...>  Accepted API keys (legacy shared-key mode)");
+        console.log("  --agents <name:key,...> Approved agent registry (recommended)");
         console.log("  --max-queue <n>         Max queued messages per offline agent (default: 200)");
         console.log("  --rate-limit <n>        Max messages per agent per minute (default: 60)");
         console.log("");
@@ -57,6 +67,14 @@ function parseArgs(): Partial<RelayHubConfig> {
   if (!config.apiKeys && process.env.RELAY_API_KEYS) {
     config.apiKeys = process.env.RELAY_API_KEYS.split(",").map((k) => k.trim()).filter(Boolean);
   }
+  if (!config.registeredAgents && process.env.RELAY_AGENTS) {
+    config.registeredAgents = Object.fromEntries(
+      process.env.RELAY_AGENTS.split(",").map((entry) => {
+        const [name, ...keyParts] = entry.split(":");
+        return [name.trim(), keyParts.join(":").trim()];
+      }).filter(([name, key]) => name && key)
+    );
+  }
   if (!config.maxQueuePerAgent && process.env.RELAY_MAX_QUEUE) {
     config.maxQueuePerAgent = parseInt(process.env.RELAY_MAX_QUEUE, 10);
   }
@@ -74,7 +92,7 @@ hub.start();
 
 console.log("[perkos-a2a] Relay hub running");
 console.log(`[perkos-a2a] Port: ${config.port || 6060}`);
-console.log(`[perkos-a2a] Auth: ${config.apiKeys?.length ? "enabled" : "disabled (no API keys configured)"}`);
+console.log(`[perkos-a2a] Auth: ${config.registeredAgents && Object.keys(config.registeredAgents).length ? "approved-agent registry" : config.apiKeys?.length ? "shared-key" : "disabled (no API keys configured)"}`);
 
 process.on("SIGINT", () => {
   console.log("\n[perkos-a2a] Shutting down relay hub...");

package/dist/agent.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Standalone PerkOS A2A bridge.
+ *
+ * This is for runtimes that do not load OpenClaw plugins directly, especially
+ * Hermes Workspace. It runs the same A2A HTTP/relay server and delivers inbound
+ * tasks into a local runtime over that runtime's native wake/send API.
+ *
+ * Usage:
+ *   perkos-a2a-agent --config ./a2a.config.json
+ *   A2A_AGENT_NAME=hermes A2A_RUNTIME=hermes HERMES_WORKSPACE_URL=http://127.0.0.1:3000 perkos-a2a-agent
+ */
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG"}

package/dist/agent.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Standalone PerkOS A2A bridge.
+ *
+ * This is for runtimes that do not load OpenClaw plugins directly, especially
+ * Hermes Workspace. It runs the same A2A HTTP/relay server and delivers inbound
+ * tasks into a local runtime over that runtime's native wake/send API.
+ *
+ * Usage:
+ *   perkos-a2a-agent --config ./a2a.config.json
+ *   A2A_AGENT_NAME=hermes A2A_RUNTIME=hermes HERMES_WORKSPACE_URL=http://127.0.0.1:3000 perkos-a2a-agent
+ */
+import { readFileSync } from "fs";
+import { randomUUID } from "crypto";
+import { A2AServer } from "./server.js";
+import { completeTaskWithReply, generateRuntimeReply } from "./runtime-reply.js";
+function argValue(flag) {
+    const idx = process.argv.indexOf(flag);
+    if (idx === -1)
+        return undefined;
+    return process.argv[idx + 1];
+}
+function parseJsonEnv(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${name} must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function loadConfig() {
+    const configPath = argValue("--config") || argValue("-c") || process.env.A2A_CONFIG;
+    if (configPath) {
+        return JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    const port = Number(process.env.A2A_PORT || "5050");
+    const relayEnabled = String(process.env.A2A_RELAY_ENABLED || "").toLowerCase() === "true";
+    return {
+        agentName: process.env.A2A_AGENT_NAME || "agent",
+        port,
+        bindHost: process.env.A2A_BIND_HOST || "0.0.0.0",
+        publicUrl: process.env.A2A_PUBLIC_URL,
+        mode: process.env.A2A_MODE || "auto",
+        skills: parseJsonEnv("A2A_SKILLS", []),
+        peers: parseJsonEnv("A2A_PEERS", {}),
+        peerAuth: parseJsonEnv("A2A_PEER_AUTH", {}),
+        auth: process.env.A2A_API_KEYS
+            ? { requireApiKey: true, apiKeys: process.env.A2A_API_KEYS.split(",").map((v) => v.trim()).filter(Boolean) }
+            : undefined,
+        relay: relayEnabled || process.env.A2A_RELAY_URL
+            ? {
+                enabled: relayEnabled || Boolean(process.env.A2A_RELAY_URL),
+                url: process.env.A2A_RELAY_URL || "",
+                apiKey: process.env.A2A_RELAY_API_KEY || "",
+                hubPort: process.env.A2A_RELAY_HUB_PORT ? Number(process.env.A2A_RELAY_HUB_PORT) : undefined,
+                hubApiKeys: process.env.A2A_RELAY_HUB_API_KEYS?.split(",").map((v) => v.trim()).filter(Boolean),
+            }
+            : undefined,
+        runtime: {
+            kind: process.env.A2A_RUNTIME || "hermes",
+            sessionKey: process.env.A2A_SESSION_KEY,
+            hermesUrl: process.env.HERMES_WORKSPACE_URL,
+            hermesToken: process.env.HERMES_WORKSPACE_TOKEN || process.env.HERMES_SESSION_TOKEN,
+            hermesEndpoint: process.env.HERMES_WORKSPACE_ENDPOINT,
+        },
+    };
+}
+function taskMarker(task) {
+    return `[A2A_RESULT:${task.id}]`;
+}
+function buildRuntimeMessage(task, text) {
+    const from = task.metadata?.fromAgent || "unknown";
+    const marker = taskMarker(task);
+    return [
+        marker,
+        `From: ${from}`,
+        `Task ID: ${task.id}`,
+        `Context ID: ${task.contextId}`,
+        "",
+        "Execute the following request and include the final answer in your assistant reply.",
+        `Your final answer must begin with exactly: ${marker}`,
+        "Return the useful final answer after that marker.",
+        "",
+        text,
+    ].join("\n");
+}
+async function getHermesAuthCookie(baseUrl, explicitToken) {
+    if (explicitToken)
+        return `claude-auth=${explicitToken}`;
+    const password = process.env.HERMES_PASSWORD || process.env.CLAUDE_PASSWORD;
+    if (!password)
+        return undefined;
+    const response = await fetch(`${baseUrl}/api/auth`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ password }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Hermes auth failed (${response.status}): ${body || response.statusText}`);
+    }
+    const setCookie = response.headers.get("set-cookie");
+    return setCookie?.split(";")[0];
+}
+async function deliverToHermes(config, message) {
+    const runtime = config.runtime || {};
+    const baseUrl = (runtime.hermesUrl || process.env.HERMES_WORKSPACE_URL || "http://127.0.0.1:3000").replace(/\/+$/, "");
+    const endpoint = runtime.hermesEndpoint || "/api/session-send";
+    const sessionKey = runtime.sessionKey || "main";
+    const token = runtime.hermesToken || process.env.HERMES_WORKSPACE_TOKEN || process.env.HERMES_SESSION_TOKEN;
+    const url = `${baseUrl}${endpoint.startsWith("/") ? endpoint : `/${endpoint}`}`;
+    const headers = { "content-type": "application/json" };
+    const cookie = await getHermesAuthCookie(baseUrl, token);
+    if (cookie)
+        headers.cookie = cookie;
+    const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ sessionKey, message }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new Error(`Hermes delivery failed (${response.status}): ${body || response.statusText}`);
+    }
+}
+async function main() {
+    const config = loadConfig();
+    const logger = console;
+    const server = new A2AServer(config, logger);
+    server.setTaskResultHandler(async (task, text) => {
+        const runtimeKind = config.runtime?.kind || "hermes";
+        task.status = {
+            state: "working",
+            timestamp: new Date().toISOString(),
+            message: { role: "agent", parts: [{ kind: "text", text: `Task dispatched to ${runtimeKind} runtime.` }] },
+        };
+        if (runtimeKind === "hermes") {
+            await deliverToHermes(config, buildRuntimeMessage(task, text));
+            task.artifacts.push({
+                kind: "artifact",
+                artifactId: randomUUID(),
+                parts: [{ kind: "text", text: "Delivered to Hermes Workspace." }],
+            });
+            const finalText = await generateRuntimeReply(config, text, taskMarker(task));
+            completeTaskWithReply(task, finalText);
+            return;
+        }
+        if (runtimeKind === "none") {
+            task.artifacts.push({
+                kind: "artifact",
+                artifactId: randomUUID(),
+                parts: [{ kind: "text", text: "Runtime delivery disabled." }],
+            });
+            return;
+        }
+        throw new Error(`Standalone runtime '${runtimeKind}' is not supported yet. Use OpenClaw plugin mode for OpenClaw delivery.`);
+    });
+    server.setTaskFailureHandler((task, errorText) => {
+        task.status = {
+            state: "failed",
+            timestamp: new Date().toISOString(),
+            message: { role: "agent", parts: [{ kind: "text", text: errorText }] },
+        };
+    });
+    await server.start();
+    logger.info(`[perkos-a2a] standalone bridge running for ${config.agentName} (${config.runtime?.kind || "hermes"})`);
+    const stop = () => {
+        logger.info("[perkos-a2a] standalone bridge shutting down");
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+}
+main().catch((err) => {
+    console.error(`[perkos-a2a] standalone bridge failed: ${err instanceof Error ? err.stack || err.message : String(err)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,cAAc,YAAY,CAAC;AAuB3B,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QA0exC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,cAAc,YAAY,CAAC;AA6D3B,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAwgBxC"}