@perkos/perkos-a2a 0.8.34 → 0.9.0

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 /** A2A Protocol types (v0.3.0) */
+export type { AckFrame, AuthErrorFrame, AuthFrame, AuthOkFrame, ChannelJoinFrame, ChatConfig, ChatDeliverFrame, ChatErrorFrame, ChatFrame, ChatIdentity, ChatMessage, ChatMessageInboundFrame, ChatReplyFrame, HistoryChunkFrame, HistoryRequestFrame, PingFrame, PongFrame, TypingFrame, } from "./chat-types.js";
 export interface AgentCard {
     name: string;
     description: string;
@@ -114,6 +115,15 @@ export interface A2APluginConfig {
     };
     relay?: RelayConfig;
     auth?: AuthConfig;
+    /**
+     * Optional PerkOS-Chat client. When `enabled`, the plugin opens a WS to
+     * `chat.perkos.xyz` alongside the A2A relay so the agent can participate
+     * in user-facing project chats and 1-on-1 DMs.
+     *
+     * Separate from the relay because chat traffic has different volume and
+     * rate-limit characteristics than task dispatch. See `src/chat-client.ts`.
+     */
+    chat?: import("./chat-types.js").ChatConfig;
 }
 export type RuntimeKind = "openclaw" | "hermes" | "hermes-api" | "none";
 export interface RuntimeDeliveryConfig {
@@ -129,7 +139,32 @@ export interface RuntimeDeliveryConfig {
     hermesEndpoint?: string;
 }
 /** Wire protocol for relay WebSocket messages */
-export type RelayMessageType = "register" | "register_ack" | "task" | "task_response" | "discover" | "discover_response" | "heartbeat" | "heartbeat_ack" | "error";
+export type RelayMessageType = "register" | "register_ack" | "task" | "task_response" | "discover" | "discover_response" | "heartbeat" | "heartbeat_ack" | "webhook_event" | "error";
+/**
+ * Payload of a `webhook_event` frame. Transport delivers these when an
+ * external system (GitHub, GitLab, Linear, generic) fires a webhook
+ * that matches one of this agent's subscriptions. Hooks-first design:
+ * the agent does not need to expose its own HTTP surface.
+ *
+ * `headers` contains only the small set of upstream headers that are
+ * useful downstream (delivery id, user-agent). `body` is the parsed
+ * JSON body, or `null` when the upstream payload wasn't JSON.
+ */
+export interface WebhookEventPayload {
+    subscriptionId: string;
+    source: "github" | "gitlab" | "linear" | "generic" | string;
+    eventType: string;
+    headers: {
+        delivery?: string;
+        userAgent?: string;
+    };
+    body: unknown;
+}
+/** Convenience helper: narrows a RelayMessage to a webhook_event frame. */
+export declare function isWebhookEvent(msg: RelayMessage): msg is RelayMessage & {
+    type: "webhook_event";
+    payload: WebhookEventPayload;
+};
 export interface RelayMessage {
     type: RelayMessageType;
     /** Sender agent name */

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -1,3 +1,6 @@
 /** A2A Protocol types (v0.3.0) */
-export {};
+/** Convenience helper: narrows a RelayMessage to a webhook_event frame. */
+export function isWebhookEvent(msg) {
+    return msg.type === "webhook_event";
+}
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kCAAkC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kCAAkC;AA6MlC,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAC5B,GAAiB;IAEjB,OAAO,GAAG,CAAC,IAAI,KAAK,eAAe,CAAC;AACtC,CAAC"}

package/docs/chat-client.md

@@ -0,0 +1,190 @@
+# PerkOS-Chat client
+
+The A2A package ships with a `ChatClient` that connects to PerkOS-Chat
+(`wss://chat.perkos.xyz/chat`) alongside the existing A2A relay. Tasks and
+chat travel on separate sockets — different rate limits, different
+semantics — but both use the same agent identity and the same relay API key
+issued during PerkOS-Transport pairing.
+
+Server reference: [PerkOS-Chat](https://github.com/PerkOS-xyz/PerkOS-Chat)
+and `docs/protocol.md` therein.
+
+## Privacy model (C-hybrid)
+
+The agent owns the canonical conversation history.
+
+- **PerkOS cloud (Firestore)** — metadata only: title, participants,
+  `historyHost`, `lastMessageAt`. No bodies, no previews.
+- **This client** — receives every frame addressed to the agent and appends
+  it to `<storeRoot>/<convId>/messages.jsonl`. The store is **the** record
+  of conversation content for this agent.
+- **History queries** — when a user scrolls back in the MiniApp, the chat
+  server forwards the request to the `historyHost` agent. The client
+  paginates from the JSONL and responds.
+
+Backups are the operator's responsibility. The standard advice: rsync
+`~/.perkos/conversations/` somewhere durable on a schedule.
+
+## Wiring it in — OpenClaw
+
+The A2A plugin already wires chat for you when you set `chat.enabled: true`
+in your `openclaw.plugin.json` config:
+
+```json
+{
+  "perkos-a2a": {
+    "config": {
+      "agentName": "apollo",
+      "relay": {
+        "enabled": true,
+        "url": "wss://transport.perkos.xyz/a2a",
+        "apiKey": "<your relay key>"
+      },
+      "chat": {
+        "enabled": true,
+        "url": "wss://chat.perkos.xyz/chat"
+      }
+    }
+  }
+}
+```
+
+`chat.apiKey` defaults to `relay.apiKey` — one key, two sockets. When an
+inbound message arrives, the plugin enqueues a system event with a marker
+`[PERKOS_CHAT:<convId>]`, wakes the runtime, and the LLM should call the
+`perkos_chat_reply` tool to respond.
+
+Two tools are added to the agent's tool surface:
+
+- `perkos_chat_reply({ convId, walletAddress, text, replyTo? })`
+- `perkos_chat_history({ convId, before?, limit? })`
+
+Run `openclaw perkos-a2a status` (or hit the gateway method
+`perkos-a2a.status`) to verify the chat client is connected.
+
+## Wiring it in — Hermes (via `perkos-a2a-agent` bridge)
+
+The standalone bridge binary (`bin/agent.ts`, shipped as `perkos-a2a-agent`)
+multiplexes A2A tasks **and** chat in one process. Run it next to Hermes
+on the same VPS:
+
+```bash
+A2A_AGENT_NAME=apollo \
+A2A_RUNTIME=hermes-api \
+HERMES_API_URL=http://127.0.0.1:8642 \
+A2A_RELAY_URL=wss://transport.perkos.xyz/a2a \
+A2A_RELAY_API_KEY=<your relay key> \
+A2A_CHAT_ENABLED=true \
+A2A_CHAT_URL=wss://chat.perkos.xyz/chat \
+A2A_CHAT_API_KEY=<your relay key>   # defaults to A2A_RELAY_API_KEY \
+A2A_CHAT_REPLY_PORT=5060 \
+  perkos-a2a-agent
+```
+
+Inbound flow:
+
+1. `chat.perkos.xyz` sends `chat_deliver` over WS to the bridge.
+2. Bridge appends to local JSONL **and** POSTs the message to Hermes at
+   `POST $HERMES_API_URL/v1/responses` with a `[PERKOS_CHAT:<convId>]`
+   marker and explicit instructions: *"reply via POST to
+   http://127.0.0.1:$A2A_CHAT_REPLY_PORT/chat/reply"*.
+3. Hermes (via a tool you configure on the Hermes side — `http_request`
+   or a custom plugin) POSTs the reply to:
+
+   ```
+   POST http://127.0.0.1:5060/chat/reply
+   { "convId": "...", "walletAddress": "0x...", "text": "...", "replyTo": "..." }
+   ```
+
+4. The bridge calls `chatClient.sendReply(...)` which appends to the
+   JSONL log and broadcasts to other conversation participants via
+   `chat.perkos.xyz`.
+
+The reply listener is bound to `127.0.0.1` only — never expose it to the
+public internet. The relay API key never leaves the bridge.
+
+If Hermes is offline or returns 503, the reply is still appended to the
+local JSONL store, so reconciliation on reconnect is possible later.
+
+## Wiring it in — programmatic
+
+If you're not in an OpenClaw plugin context (e.g. a Hermes bridge), use the
+class directly:
+
+```ts
+import { ChatClient } from "@perkos/perkos-a2a";
+
+const chat = new ChatClient({
+  agentName: "apollo",
+  config: {
+    enabled: true,
+    url: "wss://chat.perkos.xyz/chat",
+    apiKey: process.env.PERKOS_RELAY_API_KEY!,
+    // storeRoot defaults to ~/.perkos/conversations
+  },
+  handlers: {
+    onChatDeliver: async (frame) => {
+      // Hand the message to the agent runtime (Hermes /v1/responses, custom
+      // LLM loop, …). When the runtime produces a reply, call sendReply.
+    },
+    onChannelJoin: async (frame) => {
+      // A new conv exists. The store already has metadata written; this
+      // hook is for runtime-side wiring (subscribe a memory module, etc.).
+    },
+  },
+});
+
+chat.start();
+```
+
+To respond:
+
+```ts
+await chat.sendReply({
+  convId: "c-1234",
+  walletAddress: "0xabc...",       // user wallet that owns the conv tree
+  text: "Aquí tienes el resumen.",
+  replyTo: "u-1234",                // optional id of the user's message
+});
+```
+
+The reply is appended to the local JSONL before being sent on the wire, so
+it shows up in history even if delivery fails.
+
+## Storage layout
+
+```
+<storeRoot>/
+  <convId>/
+    metadata.json   ConversationMetadata (participants, historyHost, ...)
+    messages.jsonl  Append-only, one JSON object per line
+    attachments/    Reserved for future use
+```
+
+`messages.jsonl` is **append-only**. Each line is `JSON.stringify(msg)`
+where `msg: ChatMessage`. Out-of-order timestamps are preserved as written;
+pagination uses `timestamp < before` as the filter.
+
+## Pagination
+
+```ts
+const store = chat.getStore();
+const { messages, hasMore } = await store.readPage("c-1234", {
+  before: "2026-05-19T18:00:00.000Z",
+  limit: 50,
+});
+// messages: chronological ascending (oldest of the page first)
+```
+
+`readPage` reads the whole jsonl into memory and walks backward — fine for
+conversations up to ~tens of thousands of messages. If you anticipate
+larger logs, swap the implementation for a streaming reverse-iterator
+(left as a future task).
+
+## Reconnect, heartbeat, rate limit
+
+- Exponential backoff: 1s → 60s.
+- Heartbeat: a `ping` frame every 25s (the server's default reap timeout is
+  90s).
+- The server rate-limits each agent socket to 600 messages/min by default;
+  history responses and acks are counted.

package/docs/demo-setup.md

@@ -0,0 +1,273 @@
+# PerkOS multi-agent demo — provisioning playbook
+
+End-to-end recipe for standing up the three-agent demo on a Hetzner VPS
+(or any Linux host with Docker, Caddy, and outbound HTTPS). Read it
+once, then `scripts/demo/` does most of the work.
+
+## Topology
+
+```
+┌──── PerkOS-Transport (transport.perkos.xyz) ────┐
+│  tasks routing, pairing registry                 │
+└──────────────────────────────────────────────────┘
+            ▲                               ▲
+            │ wss /a2a                      │ wss /a2a
+            │                               │
+┌──── PerkOS-Chat (chat.perkos.xyz) ────┐  │
+│  chat routing, Firebase metadata write │  │
+└────────────────────────────────────────┘  │
+       ▲                                    │
+       │ wss /chat (user)                   │ wss /chat
+       │                                    │ (agent)
+   browser                                  │
+                                            │
+   ┌────────────────────────────────────────┴────────┐
+   │ Apollo (orchestrator, Hermes runtime)            │
+   │ Builder (worker, OpenClaw)                       │
+   │ QA      (worker, OpenClaw)                       │
+   │   each: perkos-a2a-agent → Transport + Chat WS   │
+   └─────────────────────────────────────────────────-┘
+```
+
+For the demo we use a **single VPS** with all three agents running as
+separate `perkos-a2a-agent` processes (different ports, different
+config dirs). Apollo runs **Hermes** as its runtime — the others run
+**OpenClaw**.
+
+## Prerequisites on the VPS
+
+1. Docker + docker compose
+2. Caddy already serving `transport.perkos.xyz` and `chat.perkos.xyz`
+3. Hermes Agent installed and reachable on `http://127.0.0.1:8642`
+   (the Apollo orchestrator) — see [hermes-workspace install
+   guide](https://github.com/NousResearch/hermes-agent)
+4. OpenClaw installed (the worker agents) — see [OpenClaw
+   docs](https://openclaw.dev) — they don't need a separate HTTP
+   server; the A2A plugin handles networking
+5. Node.js 22+ on the host (or use the published
+   `@perkos/perkos-a2a` npm package)
+6. The Transport admin key (`PAIRING_ADMIN_KEY` from Transport's
+   `.env`) — needed to mint invites
+7. SSH access as a non-root user with sudo
+
+## Step 0 — Decide identities
+
+```
+ORG_SYSTEM=perkos-demo
+PROJECT_ID=demo-q4
+
+# Three agents, one orchestrator + two workers
+APOLLO_NAME=apollo
+BUILDER_NAME=builder
+QA_NAME=qa
+```
+
+## Step 1 — Mint Transport pairing invites
+
+For each agent, ask Transport for an invite. The wrapper script in
+`scripts/demo/mint-pairing.sh` does it; or call the HTTP API directly:
+
+```bash
+export TRANSPORT_BASE=https://transport.perkos.xyz
+export TRANSPORT_ADMIN_KEY=<from your Transport .env>
+
+for agent in apollo builder qa; do
+  echo "=== minting invite for $agent ==="
+  curl -fsS -X POST "$TRANSPORT_BASE/api/systems/perkos-demo/agents/invites" \
+    -H "x-api-key: $TRANSPORT_ADMIN_KEY" \
+    -H "content-type: application/json" \
+    -d "{
+      \"agentName\": \"$agent\",
+      \"runtime\": \"$( [[ $agent == apollo ]] && echo hermes-api || echo openclaw )\",
+      \"scopes\": [\"a2a:connect\", \"tasks:receive\", \"messages:send\", \"chat:send\"]
+    }" | tee /tmp/invite-$agent.json
+done
+```
+
+Each invite response looks like:
+
+```json
+{
+  "inviteId": "inv_…",
+  "pairingUrl": "https://transport.perkos.xyz/pairing/invites/inv_…",
+  "expiresAt": "2026-05-20T..."
+}
+```
+
+Keep them — the agent uses the URL to claim and the operator (you)
+approves.
+
+## Step 2 — Claim and approve
+
+The pairing flow is two-step: the agent claims with a public key, then
+admin approves to issue the scoped `relayApiKey`.
+
+For the demo we **auto-approve** by passing the admin key on the claim
+step. `scripts/demo/claim-and-approve.sh` wraps this:
+
+```bash
+scripts/demo/claim-and-approve.sh apollo  /tmp/invite-apollo.json
+scripts/demo/claim-and-approve.sh builder /tmp/invite-builder.json
+scripts/demo/claim-and-approve.sh qa      /tmp/invite-qa.json
+```
+
+Each call prints the `relayApiKey` for that agent. Save them:
+
+```bash
+APOLLO_KEY=…
+BUILDER_KEY=…
+QA_KEY=…
+```
+
+## Step 3 — Update chat.perkos.xyz registry
+
+Until the production bridge between Transport's pairing registry and
+Chat's agent-key store lands, chat.perkos.xyz reads agent keys from
+its `RELAY_API_KEYS` env var. SSH to the chat host and add the new
+keys:
+
+```bash
+ssh hetzner
+sudo nano /opt/PerkOS-Chat/.env
+
+# Update or extend:
+RELAY_API_KEYS=apollo:<APOLLO_KEY>,builder:<BUILDER_KEY>,qa:<QA_KEY>
+
+# Reload:
+cd /opt/PerkOS-Chat
+docker compose -f docker-compose.example.yml up -d
+```
+
+Verify:
+
+```bash
+curl https://chat.perkos.xyz/health | jq .agents
+# expect 0 (no agents connected yet — that's fine)
+```
+
+## Step 4 — Start Apollo (Hermes orchestrator)
+
+```bash
+# On the Hermes host:
+export A2A_AGENT_NAME=apollo
+export A2A_RUNTIME=hermes-api
+export HERMES_API_URL=http://127.0.0.1:8642
+export A2A_RELAY_URL=wss://transport.perkos.xyz/a2a
+export A2A_RELAY_API_KEY=<APOLLO_KEY>
+export A2A_CHAT_ENABLED=true
+export A2A_CHAT_URL=wss://chat.perkos.xyz/chat
+export A2A_CHAT_API_KEY=<APOLLO_KEY>
+export A2A_CHAT_REPLY_PORT=5060
+export A2A_PORT=5050
+export A2A_PEERS='{"builder":"http://127.0.0.1:5051","qa":"http://127.0.0.1:5052"}'
+
+npx -p @perkos/perkos-a2a perkos-a2a-agent
+```
+
+A systemd unit template is in `scripts/demo/systemd/apollo.service`.
+
+## Step 5 — Start Builder + QA (OpenClaw workers)
+
+OpenClaw agents load the A2A plugin natively. Drop this config into
+each worker's OpenClaw plugins directory:
+
+```jsonc
+// builder.plugin.config.json
+{
+  "perkos-a2a": {
+    "config": {
+      "agentName": "builder",
+      "port": 5051,
+      "bindHost": "127.0.0.1",
+      "mode": "client-only",
+      "peers": {
+        "apollo": "http://127.0.0.1:5050"
+      },
+      "relay": {
+        "enabled": true,
+        "url": "wss://transport.perkos.xyz/a2a",
+        "apiKey": "<BUILDER_KEY>"
+      },
+      "chat": {
+        "enabled": true,
+        "url": "wss://chat.perkos.xyz/chat",
+        "apiKey": "<BUILDER_KEY>"
+      },
+      "runtime": {
+        "kind": "openclaw"
+      }
+    }
+  }
+}
+```
+
+`qa` is identical except `agentName`, `port=5052`, and `apiKey`.
+
+Restart each OpenClaw process to pick up the plugin config.
+
+## Step 6 — Verify all three connect
+
+```bash
+scripts/demo/verify.sh
+```
+
+Output should look like:
+
+```
+✓ transport.perkos.xyz reachable
+✓ chat.perkos.xyz reachable
+✓ apollo  — A2A connected, chat connected
+✓ builder — A2A connected, chat connected
+✓ qa      — A2A connected, chat connected
+```
+
+Or hit the health endpoints manually:
+
+```bash
+curl https://chat.perkos.xyz/health | jq .agents
+# expect 3
+curl https://transport.perkos.xyz/health | jq .connectedAgents
+# expect 3
+curl "https://transport.perkos.xyz/api/agents/apollo/heartbeat" -H "x-api-key: $TRANSPORT_ADMIN_KEY" | jq
+# expect { "ok": true, "approved": true, "connected": true }
+```
+
+## Step 7 — Smoke from the MiniApp
+
+Open the MiniApp, sign in with a wallet, and walk through the
+[chat E2E checklist](https://github.com/PerkOS-xyz/PerkOS/blob/main/docs/CHAT-E2E.md).
+
+Quickest happy-path: click **+ New**, pick "Direct message" + apollo,
+type "hola apollo" — you should see Apollo's reply within 5 seconds
+(Hermes processing time).
+
+## Troubleshooting
+
+| Symptom | First-pass diagnosis |
+|---|---|
+| MiniApp sidebar empty | Firestore rules deployed? — see `Perkos/firestore.rules` |
+| `auth_error` on the chat WS | Firebase project mismatch between MiniApp and chat.perkos.xyz |
+| Agent not connecting | Check the `RELAY_API_KEYS` value matches what claim-and-approve issued |
+| Apollo gets the chat_deliver but no reply | Hermes is not configured to POST to `127.0.0.1:5060/chat/reply` (see `docs/chat-client.md` "Wiring it in — Hermes") |
+| `HOST_OFFLINE` banner stays up | The host agent's WS dropped; check the agent process logs |
+| Builder/QA never receive sub-tasks | Apollo's peer config wrong; check the JSON peers map in apollo's env |
+
+## Decommissioning the demo
+
+```bash
+# Revoke each agent on Transport
+for agent in apollo builder qa; do
+  curl -X POST "$TRANSPORT_BASE/pairing/agents/$agent/revoke" \
+    -H "x-api-key: $TRANSPORT_ADMIN_KEY"
+done
+
+# Remove from chat.perkos.xyz
+ssh hetzner 'sudo sed -i "s/RELAY_API_KEYS=.*/RELAY_API_KEYS=/" /opt/PerkOS-Chat/.env && \
+  cd /opt/PerkOS-Chat && docker compose -f docker-compose.example.yml up -d'
+
+# Stop the agent processes (systemd or direct)
+```
+
+Conversation metadata stays in Firestore. Conversation content stays
+in each agent's `~/.perkos/conversations/` jsonl. Delete those if you
+want a clean wipe.

package/openclaw.plugin.json

@@ -170,6 +170,41 @@
       "pairingStorePath": {
         "type": "string",
         "description": "Path to a local pairing credential profile, e.g. ~/.perkos/a2a/agents/Alice.json. The plugin may load relay credentials from this store without printing secrets."
+      },
+      "chat": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Connect to PerkOS-Chat for user-facing chat (DMs + channels). Independent of the A2A relay used for tasks."
+          },
+          "url": {
+            "type": "string",
+            "default": "wss://chat.perkos.xyz/chat",
+            "description": "PerkOS-Chat WebSocket URL"
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "Relay API key for this agent. If omitted, falls back to relay.apiKey."
+          },
+          "storeRoot": {
+            "type": "string",
+            "description": "Directory for the conversations JSONL store. Defaults to ~/.perkos/conversations."
+          },
+          "defaultHistoryLimit": {
+            "type": "number",
+            "default": 50,
+            "description": "Max messages returned per history page (1-500)."
+          },
+          "heartbeatIntervalMs": {
+            "type": "number",
+            "default": 25000,
+            "description": "Ping cadence in ms. The server reaps after 90s of silence."
+          }
+        },
+        "description": "PerkOS-Chat client config — opt-in. The agent owns conversation history on local disk; the PerkOS cloud stores metadata only."
       }
     }
   },
@@ -204,7 +239,9 @@
     "tools": [
       "perkos_a2a_send",
       "perkos_a2a_discover",
-      "perkos_a2a_status"
+      "perkos_a2a_status",
+      "perkos_chat_reply",
+      "perkos_chat_history"
     ]
   },
   "activation": {

package/package.json

@@ -1,10 +1,28 @@
 {
   "name": "@perkos/perkos-a2a",
-  "version": "0.8.34",
+  "version": "0.9.0",
   "description": "A2A Protocol communication plugin for OpenClaw — Agent-to-Agent protocol implementation",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "perkos-a2a-agent": "./dist/agent.js",
+    "perkos-a2a-hermes": "./dist/hermes-cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./hermes": {
+      "types": "./dist/hermes-plugin.d.ts",
+      "default": "./dist/hermes-plugin.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/types.js"
+    }
+  },
   "files": [
     "dist/index.js",
     "dist/index.js.map",
@@ -26,6 +44,20 @@
     "dist/runtime-reply.d.ts.map",
     "dist/agentic-actions.d.ts",
     "dist/agentic-actions.d.ts.map",
+    "dist/agent.js",
+    "dist/agent.js.map",
+    "dist/agent.d.ts",
+    "dist/agent.d.ts.map",
+    "dist/hermes-cli.js",
+    "dist/hermes-cli.js.map",
+    "dist/hermes-cli.d.ts",
+    "dist/hermes-cli.d.ts.map",
+    "dist/hermes-plugin.js",
+    "dist/hermes-plugin.js.map",
+    "dist/hermes-plugin.d.ts",
+    "dist/hermes-plugin.d.ts.map",
+    "scripts/install-hermes.mjs",
+    "scripts/hermes",
     "docs",
     "skills",
     "openclaw.plugin.json",