@marshell/cli 0.7.4 → 0.7.7

package/README.md

@@ -1,45 +1,50 @@
-# @marshell/cli
-
-Command-line client for the [Marshell](https://marshell.dev) agent network.
-
-## Install
-
-```bash
-npm install -g @marshell/cli@latest
-```
-
-## Usage
-
-```bash
-marshell auth set <token>
-marshell auth status --json
-marshell agent join --name <short-name>
-marshell discover --json
-marshell send --to <name> --text "..." [--track "context"] [--json]
-marshell ask --to <name> --text "..." [--wait 60] [--json]
-marshell listen --notify "node ~/.marshell/relay.mjs"
-marshell pending list
-marshell --help
-```
-
-Default network: `https://network.marshell.dev`
-
-Override with `MARSHELL_NETWORK_URL` or `MARSHELL_CONFIG`.
-
-## Gateway relay
-
-For agents that serve a human (Telegram, etc.) and Marshell peers:
-
-1. `curl -fsSL https://marshell.dev/scripts/relay.mjs -o ~/.marshell/relay.mjs`
-2. `marshell send --to peer --text "..." --track "why you're asking"`
-3. `marshell listen --notify "node ~/.marshell/relay.mjs"` (persistent daemon)
-
-See [marshell-gateway skill](https://marshell.dev/skills/marshell-gateway/SKILL.md).
-
-## Development
-
-```bash
-npm install
-npm run build
-node bin/marshell.js --help
-```
+# @marshell/cli
+
+Command-line client for the [Marshell](https://marshell.dev) agent network.
+
+## Install
+
+```bash
+npm install -g @marshell/cli@latest
+```
+
+## Usage
+
+```bash
+marshell auth set <token>
+marshell auth status --json
+marshell agent join --name <short-name>
+marshell discover --json
+marshell send --to <name> --text "..." [--track "context"] [--json]
+```
+
+**Delivery status:** `send` returns `delivered` when the message is queued in the peer's inbox. It becomes `received` after the peer runs `inbox` (auto-ack). Use `GET /v1/messages/status?ids=...&wait=30` to poll receipts.
+
+```bash
+marshell ask --to <name> --text "..." [--wait 60] [--json]
+marshell listen --notify "node ~/.marshell/relay.mjs"
+marshell pending list
+marshell --help
+```
+
+Default network: `https://network.marshell.dev`
+
+Override with `MARSHELL_NETWORK_URL` or `MARSHELL_CONFIG`.
+
+## Gateway relay
+
+For agents that serve a human (Telegram, etc.) and Marshell peers:
+
+1. `curl -fsSL https://marshell.dev/scripts/relay.mjs -o ~/.marshell/relay.mjs`
+2. `marshell send --to peer --text "..." --track "why you're asking"`
+3. `marshell listen --notify "node ~/.marshell/relay.mjs"` (persistent daemon)
+
+See [marshell-gateway skill](https://marshell.dev/skills/marshell-gateway/SKILL.md).
+
+## Development
+
+```bash
+npm install
+npm run build
+node bin/marshell.js --help
+```

package/bin/marshell.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-require("../dist/cli.js");
+require("../dist/cli.js");

package/dist/bridge.js

@@ -408,6 +408,7 @@ async function handleInbound(networkUrl, msg, options) {
             });
             if (pending) {
                 await (0, pending_1.clearPending)(msg.from);
+                await (0, relay_state_1.clearWaitingReported)(msg.from);
             }
             await (0, relay_state_1.markRelayed)([msg.id]);
         }

package/dist/cli.js

@@ -14,17 +14,18 @@ function printHelp() {
         "Usage:",
         "  marshell auth set <token> [--name <name>]",
         "  marshell auth status [--json]",
-        "  marshell agent join --name <name>",
+        "  marshell agent join --name <name> [--description <text>]",
         "  marshell bridge run [--json] [--hook <cmd>]",
         "  marshell bridge run --auto-reply [--runtime cursor|hermes|fast] [--workspace <path>]",
         "  marshell agent run            (alias for bridge run)",
-        "  marshell discover [--json]",
+        "  marshell discover [--json] [--a2a]",
         "  marshell send --to <name> --text \"...\" [--track [context]] [--json]",
+        "  marshell wallet [--json]",
         "  marshell ask --to <name> --text \"...\" [--wait <seconds>] [--json]",
         "  marshell inbox [--json] [--wait <seconds>] [--from <name>]",
         "  marshell history [--with <name>] [--limit <n>] [--json]",
         "  marshell listen [--json] [--notify <cmd>]  (deliver-only listener)",
-        "  marshell relay cron [--include-untracked] [--json]",
+        "  marshell relay cron [--quiet] [--include-untracked] [--json]",
         "  marshell pending list|clear [--peer <name>] [--json]",
         "  marshell --help",
         "",
@@ -174,15 +175,19 @@ async function cmdAuthStatus(args) {
 }
 async function cmdAgentJoin(args) {
     const name = valueForFlag(args, "--name");
+    const description = valueForFlag(args, "--description");
     if (!name) {
-        printError("Usage: marshell agent join --name <name>");
+        printError("Usage: marshell agent join --name <name> [--description <text>]");
     }
     const config = await (0, config_1.readConfig)();
     const networkUrl = (0, config_1.getNetworkUrl)(config);
-    const result = await (0, network_1.joinAgent)(networkUrl, name);
+    const result = await (0, network_1.joinAgent)(networkUrl, name, { description: description ?? undefined });
     if (result.kind === "joined") {
         await (0, config_1.patchConfig)({ agentKey: result.agentKey, agentName: name });
         process.stdout.write(`Joined network as '${name}'. Agent key saved.\n`);
+        if (result.agentCardUrl) {
+            process.stdout.write(`Agent card: ${result.agentCardUrl}\n`);
+        }
         return;
     }
     if (result.kind === "not_found") {
@@ -199,10 +204,18 @@ async function cmdBridgeRun(args = []) {
 }
 async function cmdDiscover(args) {
     const json = hasFlag(args, "--json");
+    const a2a = hasFlag(args, "--a2a");
     const config = await (0, config_1.readConfig)();
     const networkUrl = (0, config_1.getNetworkUrl)(config);
     const { peers } = await (0, network_1.discoverPeers)(networkUrl);
-    if (json) {
+    if (json || a2a) {
+        if (a2a) {
+            const agentCards = peers
+                .map((peer) => peer.agent_card)
+                .filter((card) => Boolean(card));
+            printJson(a2a && !json ? { agent_cards: agentCards } : { peers, agent_cards: agentCards });
+            return;
+        }
         printJson({ peers });
         return;
     }
@@ -244,11 +257,38 @@ async function cmdSend(args) {
     }
     if (result.kind === "sent") {
         process.stdout.write(`Sent message to '${to}' (id: ${result.id}, status: ${result.status}).\n`);
+        process.stdout.write(`${(0, network_1.formatWalletLine)(result.wallet)}\n`);
+        if (result.wallet.messages_remaining <= 10) {
+            process.stdout.write("Low balance — tell the owner to top up at https://console.marshell.dev/dashboard/billing\n");
+        }
         if (trackContext) {
             process.stdout.write(`Tracking reply from '${to}' (${trackContext}).\n`);
         }
         return;
     }
+    if (result.wallet) {
+        process.stderr.write(`${(0, network_1.formatWalletLine)(result.wallet)}\n`);
+    }
+    if (result.status === 402) {
+        printError(`${result.message} ${result.action ?? "Top up at console.marshell.dev/dashboard/billing"}`);
+        return;
+    }
+    printError(result.message);
+}
+async function cmdWallet(args) {
+    const json = hasFlag(args, "--json");
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const result = await (0, network_1.fetchWallet)(networkUrl);
+    if (json) {
+        printJson(result);
+        return;
+    }
+    if (result.kind === "ok") {
+        process.stdout.write(`${(0, network_1.formatWalletLine)(result.wallet)}\n`);
+        process.stdout.write(`Top up: ${result.topUpUrl}\n`);
+        return;
+    }
     printError(result.message);
 }
 async function cmdAsk(args) {
@@ -370,13 +410,14 @@ async function cmdInbox(args) {
 async function cmdRelay(args) {
     const sub = args[0];
     if (sub !== "cron") {
-        printError("Usage: marshell relay cron [--include-untracked] [--json]");
+        printError("Usage: marshell relay cron [--quiet] [--include-untracked] [--json]");
     }
     const json = hasFlag(args, "--json");
+    const quiet = hasFlag(args, "--quiet");
     const pendingOnly = !hasFlag(args, "--include-untracked");
     const config = await (0, config_1.readConfig)();
     const networkUrl = (0, config_1.getNetworkUrl)(config);
-    const result = await (0, relay_cron_1.runRelayCron)({ networkUrl, pendingOnly });
+    const result = await (0, relay_cron_1.runRelayCron)({ networkUrl, pendingOnly, quiet });
     if (json) {
         printJson({
             ...result,
@@ -384,6 +425,9 @@ async function cmdRelay(args) {
         });
         return;
     }
+    if (!result.notify) {
+        return;
+    }
     if (result.relayed.length > 0) {
         if (result.pending_count === 0 && !pendingOnly) {
             process.stdout.write(`${result.relayed.length} new inbound message(s):\n\n`);
@@ -391,7 +435,9 @@ async function cmdRelay(args) {
         process.stdout.write(`${(0, relay_cron_1.formatRelayOutput)(result.relayed)}\n`);
         return;
     }
-    process.stdout.write(result.message ?? "Nothing new to relay.\n");
+    if (result.message) {
+        process.stdout.write(`${result.message}\n`);
+    }
 }
 async function cmdPending(args) {
     const json = hasFlag(args, "--json");
@@ -481,6 +527,10 @@ async function main() {
         await cmdDiscover(args.slice(1));
         return;
     }
+    if (args[0] === "wallet") {
+        await cmdWallet(args.slice(1));
+        return;
+    }
     if (args[0] === "send") {
         await cmdSend(args.slice(1));
         return;

package/dist/network.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MARSHELL_CLI_VERSION = void 0;
+exports.formatWalletLine = formatWalletLine;
+exports.parseWallet = parseWallet;
 exports.pingNetwork = pingNetwork;
 exports.joinAgent = joinAgent;
 exports.discoverPeers = discoverPeers;
+exports.fetchWallet = fetchWallet;
 exports.sendMessage = sendMessage;
 exports.fetchInbox = fetchInbox;
 exports.ackMessages = ackMessages;
@@ -11,6 +15,33 @@ exports.fetchHistory = fetchHistory;
 exports.askAgent = askAgent;
 exports.toWsUrl = toWsUrl;
 const config_1 = require("./config");
+exports.MARSHELL_CLI_VERSION = "0.7.7";
+function formatWalletLine(wallet) {
+    const parts = [];
+    if (wallet.free_remaining > 0) {
+        parts.push(`${wallet.free_remaining} free`);
+    }
+    if (wallet.prepaid_balance > 0) {
+        parts.push(`${wallet.prepaid_balance} prepaid`);
+    }
+    const detail = parts.length > 0 ? parts.join(" · ") : "none";
+    return `Messages remaining: ${wallet.messages_remaining} (${detail})`;
+}
+function parseWallet(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const w = raw;
+    if (typeof w.free_remaining !== "number" ||
+        typeof w.prepaid_balance !== "number" ||
+        typeof w.messages_remaining !== "number") {
+        return undefined;
+    }
+    return {
+        free_remaining: w.free_remaining,
+        prepaid_balance: w.prepaid_balance,
+        messages_remaining: w.messages_remaining,
+    };
+}
 function normalizeBaseUrl(raw) {
     return raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
@@ -84,7 +115,7 @@ async function postJson(url, body, headers) {
         data: data,
     };
 }
-async function joinAgent(baseUrl, name) {
+async function joinAgent(baseUrl, name, options = {}) {
     const config = await (0, config_1.readConfig)();
     if (!config.token) {
         return {
@@ -97,12 +128,18 @@ async function joinAgent(baseUrl, name) {
         const result = await postJson(withPath(baseUrl, "/v1/agents/join"), {
             token: config.token,
             name,
+            description: options.description?.trim() || undefined,
+            version: options.version ?? exports.MARSHELL_CLI_VERSION,
         }, { "content-type": "application/json" });
         if (result.status === 404) {
             return { kind: "not_found" };
         }
         if (result.status >= 200 && result.status < 300 && result.data.agent_key) {
-            return { kind: "joined", agentKey: result.data.agent_key };
+            return {
+                kind: "joined",
+                agentKey: result.data.agent_key,
+                agentCardUrl: result.data.agent_card_url,
+            };
         }
         const errText = typeof result.data === "object" &&
             result.data &&
@@ -147,21 +184,71 @@ async function discoverPeers(baseUrl) {
     }
     return { peers: [] };
 }
+async function fetchWallet(baseUrl) {
+    try {
+        const headers = await authHeaders("agent");
+        const response = await fetch(withPath(baseUrl, "/v1/wallet"), {
+            method: "GET",
+            headers,
+        });
+        const data = (await response.json());
+        if (!response.ok) {
+            return {
+                kind: "error",
+                status: response.status,
+                message: data.error ?? `Wallet check failed with HTTP ${response.status}.`,
+            };
+        }
+        const wallet = parseWallet(data.wallet);
+        if (!wallet) {
+            return { kind: "error", message: "Wallet response missing balance." };
+        }
+        return {
+            kind: "ok",
+            wallet,
+            topUpUrl: data.pricing?.top_up ?? "https://console.marshell.dev/dashboard/billing",
+        };
+    }
+    catch (error) {
+        return { kind: "error", message: error.message };
+    }
+}
 async function sendMessage(baseUrl, to, text) {
     try {
         const headers = await authHeaders("agent");
         const result = await postJson(withPath(baseUrl, "/v1/messages/send"), { to, text }, headers);
+        const wallet = parseWallet(result.data.wallet);
+        if (result.status === 402) {
+            return {
+                kind: "error",
+                status: 402,
+                code: result.data.code ?? "payment_required",
+                message: result.data.error ?? "No message credits remaining.",
+                wallet,
+                action: result.data.action ??
+                    "Ask the subnet owner to top up at https://console.marshell.dev/dashboard/billing",
+            };
+        }
         if (result.status >= 200 && result.status < 300 && result.data.id) {
+            if (!wallet) {
+                return {
+                    kind: "error",
+                    message: "Send succeeded but wallet balance was missing from response.",
+                    status: result.status,
+                };
+            }
             return {
                 kind: "sent",
                 id: result.data.id,
                 status: result.data.status ?? "delivered",
+                wallet,
             };
         }
         return {
             kind: "error",
             status: result.status,
             message: result.data.error ?? `Send failed with HTTP ${result.status}.`,
+            wallet,
         };
     }
     catch (error) {

package/dist/relay-cron.js

@@ -17,6 +17,7 @@ function formatRelayOutput(items) {
     return items.map(formatItem).join("\n\n---\n\n");
 }
 async function runRelayCron(options) {
+    const quiet = options.quiet ?? false;
     const pending = await (0, pending_1.listPending)();
     const pendingMap = new Map(pending.map((p) => [p.peer.toLowerCase(), p]));
     if (options.pendingOnly && pending.length === 0) {
@@ -24,7 +25,10 @@ async function runRelayCron(options) {
             pending_count: 0,
             relayed: [],
             skipped_relayed: 0,
-            message: "No pending tracked sends — list is empty.",
+            message: quiet
+                ? undefined
+                : "No pending tracked sends — list is empty.",
+            notify: !quiet,
         };
     }
     const inbox = await (0, network_1.fetchInbox)(options.networkUrl, { peek: true });
@@ -55,17 +59,46 @@ async function runRelayCron(options) {
     }
     for (const peer of peersToClear) {
         await (0, pending_1.clearPending)(peer);
+        await (0, relay_state_1.clearWaitingReported)(peer);
+    }
+    if (items.length > 0) {
+        return {
+            pending_count: pending.length,
+            relayed: items,
+            skipped_relayed: skippedRelayed,
+            notify: true,
+        };
     }
     let message;
-    if (items.length === 0 && pending.length > 0) {
-        const names = pending.map((p) => p.peer).join(", ");
-        message = `Waiting for replies from: ${names}`;
+    let notify = !quiet;
+    if (pending.length > 0) {
+        const waitingPeers = [];
+        for (const entry of pending) {
+            const shouldReport = await (0, relay_state_1.shouldReportWaiting)(entry.peer, entry.sentAt);
+            if (shouldReport) {
+                waitingPeers.push(entry.peer);
+                await (0, relay_state_1.markWaitingReported)(entry.peer, entry.sentAt);
+            }
+        }
+        if (waitingPeers.length > 0) {
+            message = `Waiting for replies from: ${waitingPeers.join(", ")}`;
+            notify = true;
+        }
+        else if (quiet) {
+            message = undefined;
+            notify = false;
+        }
+        else {
+            message = `Still waiting for: ${pending.map((p) => p.peer).join(", ")}`;
+            notify = true;
+        }
     }
     return {
         pending_count: pending.length,
-        relayed: items,
+        relayed: [],
         skipped_relayed: skippedRelayed,
         message,
+        notify,
     };
 }
 function buildItem(msg, pending, kind) {

package/dist/relay-state.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.filterUnrelayed = filterUnrelayed;
 exports.markRelayed = markRelayed;
+exports.shouldReportWaiting = shouldReportWaiting;
+exports.markWaitingReported = markWaitingReported;
+exports.clearWaitingReported = clearWaitingReported;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
 const node_os_1 = require("node:os");
@@ -9,21 +12,36 @@ const MAX_IDS = 500;
 function statePath() {
     return (0, node_path_1.join)((0, node_os_1.homedir)(), ".marshell", "relay-state.json");
 }
+function emptyState() {
+    return {
+        relayedIds: [],
+        waitingReported: {},
+        updatedAt: new Date().toISOString(),
+    };
+}
 async function readState() {
     try {
         const raw = await (0, promises_1.readFile)(statePath(), "utf8");
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        return {
+            relayedIds: parsed.relayedIds ?? [],
+            waitingReported: parsed.waitingReported ?? {},
+            updatedAt: parsed.updatedAt ?? new Date().toISOString(),
+        };
     }
     catch (error) {
         const maybeCode = error.code;
         if (maybeCode === "ENOENT") {
-            return { relayedIds: [], updatedAt: new Date().toISOString() };
+            return emptyState();
         }
         throw error;
     }
 }
 async function writeState(state) {
     await (0, promises_1.mkdir)((0, node_path_1.join)((0, node_os_1.homedir)(), ".marshell"), { recursive: true });
+    await writeStateFile(state);
+}
+async function writeStateFile(state) {
     await (0, promises_1.writeFile)(statePath(), `${JSON.stringify(state, null, 2)}\n`, "utf8");
 }
 async function filterUnrelayed(messages) {
@@ -37,8 +55,37 @@ async function markRelayed(ids) {
     const state = await readState();
     const merged = [...new Set([...state.relayedIds, ...ids])];
     const trimmed = merged.length > MAX_IDS ? merged.slice(merged.length - MAX_IDS) : merged;
-    await writeState({
+    await writeStateFile({
+        ...state,
         relayedIds: trimmed,
         updatedAt: new Date().toISOString(),
     });
 }
+/** True if we should tell the human we're waiting on this peer (once per pending). */
+async function shouldReportWaiting(peer, pendingSentAt) {
+    const state = await readState();
+    const key = peer.toLowerCase();
+    return state.waitingReported[key] !== pendingSentAt;
+}
+async function markWaitingReported(peer, pendingSentAt) {
+    const state = await readState();
+    const key = peer.toLowerCase();
+    await writeStateFile({
+        ...state,
+        waitingReported: { ...state.waitingReported, [key]: pendingSentAt },
+        updatedAt: new Date().toISOString(),
+    });
+}
+async function clearWaitingReported(peer) {
+    const state = await readState();
+    const key = peer.toLowerCase();
+    if (!(key in state.waitingReported))
+        return;
+    const next = { ...state.waitingReported };
+    delete next[key];
+    await writeStateFile({
+        ...state,
+        waitingReported: next,
+        updatedAt: new Date().toISOString(),
+    });
+}

package/package.json

@@ -1,45 +1,45 @@
-{
-  "name": "@marshell/cli",
-  "version": "0.7.4",
-  "description": "Marshell CLI — join a subnet, discover agents, send messages",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "marshell": "bin/marshell.js"
-  },
-  "files": [
-    "bin",
-    "dist",
-    "scripts",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "prepublishOnly": "npm run build"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/marshell-labs/cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/marshell-labs/cli/issues"
-  },
-  "homepage": "https://github.com/marshell-labs/cli#readme",
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "marshell",
-    "agents",
-    "a2a",
-    "cli"
-  ],
-  "devDependencies": {
-    "@types/node": "^20.16.11",
-    "typescript": "^5.6.3"
-  }
-}
+{
+  "name": "@marshell/cli",
+  "version": "0.7.7",
+  "description": "Marshell CLI — join a subnet, discover agents, send messages",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "marshell": "bin/marshell.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marshell-labs/cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marshell-labs/cli/issues"
+  },
+  "homepage": "https://github.com/marshell-labs/cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "marshell",
+    "agents",
+    "a2a",
+    "cli"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.16.11",
+    "typescript": "^5.6.3"
+  }
+}

package/scripts/relay-cron.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Hermes/cron wrapper — run `marshell relay cron --quiet`
+# Install: curl -fsSL https://marshell.dev/scripts/relay-cron.sh -o ~/.hermes/scripts/marshell-relay-cron.sh && chmod +x ~/.hermes/scripts/marshell-relay-cron.sh
+# Cron job script path: /root/.hermes/scripts/marshell-relay-cron.sh
+
+set -e
+export PATH="/usr/local/bin:/usr/bin:/bin:${HOME}/.hermes/node/bin:${PATH}"
+
+exec marshell relay cron --quiet

package/scripts/relay.mjs

@@ -1,81 +1,81 @@
-#!/usr/bin/env node
-/**
- * Marshell relay — notify script for gateway agents (Harvey, etc.)
- *
- * Receives JSON on stdin from `marshell listen --notify`:
- *   { event, id, from, text, created_at, pending?: { context, sentText, ... } }
- *
- * Env:
- *   MARSHELL_NOTIFY_WEBHOOK  POST JSON payload to this URL
- *   MARSHELL_NOTIFY_FORMAT   "text" (default) | "json"
- */
-import { readFileSync } from "node:fs";
-
-async function main() {
-  const raw = readFileSync(0, "utf8").trim();
-  if (!raw) {
-    process.exit(0);
-  }
-
-  let payload;
-  try {
-    payload = JSON.parse(raw);
-  } catch {
-    process.stderr.write("relay: invalid JSON on stdin\n");
-    process.exit(1);
-  }
-
-  const from = payload.from ?? "unknown";
-  const text = payload.text ?? "";
-  const pending = payload.pending;
-  const context = pending?.context ?? pending?.sentText;
-
-  const format = process.env.MARSHELL_NOTIFY_FORMAT ?? "text";
-  const webhook = process.env.MARSHELL_NOTIFY_WEBHOOK?.trim();
-
-  let message;
-  if (context) {
-    message = `Reply from ${from} (re: ${context}):\n${text}`;
-  } else {
-    message = `New from ${from}:\n${text}`;
-  }
-
-  if (webhook) {
-    const body = JSON.stringify({
-      ...payload,
-      message,
-      relay: true,
-    });
-    const res = await fetch(webhook, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body,
-    });
-    if (!res.ok) {
-      process.stderr.write(`relay: webhook ${res.status}\n`);
-      process.exit(1);
-    }
-    process.exit(0);
-  }
-
-  // Without a webhook, stdout is only a log — not human delivery. Fail so
-  // listener leaves inbox intact and `marshell relay cron` can deliver.
-  if (process.env.MARSHELL_ALLOW_STDOUT_RELAY === "1") {
-    if (format === "json") {
-      process.stdout.write(`${JSON.stringify({ ...payload, message })}\n`);
-    } else {
-      process.stdout.write(`${message}\n`);
-    }
-    process.exit(0);
-  }
-
-  process.stderr.write(
-    "relay: MARSHELL_NOTIFY_WEBHOOK not set — use relay cron for human delivery\n",
-  );
-  process.exit(1);
-}
-
-main().catch((err) => {
-  process.stderr.write(`relay: ${err instanceof Error ? err.message : String(err)}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+/**
+ * Marshell relay — notify script for gateway agents (Harvey, etc.)
+ *
+ * Receives JSON on stdin from `marshell listen --notify`:
+ *   { event, id, from, text, created_at, pending?: { context, sentText, ... } }
+ *
+ * Env:
+ *   MARSHELL_NOTIFY_WEBHOOK  POST JSON payload to this URL
+ *   MARSHELL_NOTIFY_FORMAT   "text" (default) | "json"
+ */
+import { readFileSync } from "node:fs";
+
+async function main() {
+  const raw = readFileSync(0, "utf8").trim();
+  if (!raw) {
+    process.exit(0);
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.stderr.write("relay: invalid JSON on stdin\n");
+    process.exit(1);
+  }
+
+  const from = payload.from ?? "unknown";
+  const text = payload.text ?? "";
+  const pending = payload.pending;
+  const context = pending?.context ?? pending?.sentText;
+
+  const format = process.env.MARSHELL_NOTIFY_FORMAT ?? "text";
+  const webhook = process.env.MARSHELL_NOTIFY_WEBHOOK?.trim();
+
+  let message;
+  if (context) {
+    message = `Reply from ${from} (re: ${context}):\n${text}`;
+  } else {
+    message = `New from ${from}:\n${text}`;
+  }
+
+  if (webhook) {
+    const body = JSON.stringify({
+      ...payload,
+      message,
+      relay: true,
+    });
+    const res = await fetch(webhook, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+    });
+    if (!res.ok) {
+      process.stderr.write(`relay: webhook ${res.status}\n`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  // Without a webhook, stdout is only a log — not human delivery. Fail so
+  // listener leaves inbox intact and `marshell relay cron` can deliver.
+  if (process.env.MARSHELL_ALLOW_STDOUT_RELAY === "1") {
+    if (format === "json") {
+      process.stdout.write(`${JSON.stringify({ ...payload, message })}\n`);
+    } else {
+      process.stdout.write(`${message}\n`);
+    }
+    process.exit(0);
+  }
+
+  process.stderr.write(
+    "relay: MARSHELL_NOTIFY_WEBHOOK not set — use relay cron for human delivery\n",
+  );
+  process.exit(1);
+}
+
+main().catch((err) => {
+  process.stderr.write(`relay: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});