@marshell/cli 0.7.5 → 0.7.8

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/cli.js

@@ -14,12 +14,13 @@ 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]",
@@ -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) {
@@ -487,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.8";
+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;
 }
@@ -63,28 +94,82 @@ async function pingNetwork(baseUrl) {
         message: "Health endpoint not found.",
     };
 }
-async function postJson(url, body, headers) {
-    const response = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-    });
-    const text = await response.text();
-    let data = {};
-    if (text.trim().length > 0) {
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableStatus(status) {
+    return status === 429 || status === 502 || status === 503 || status === 504;
+}
+async function withRetry(fn, opts) {
+    const attempts = opts?.attempts ?? 3;
+    let lastError;
+    for (let i = 0; i < attempts; i++) {
         try {
-            data = JSON.parse(text);
+            const result = await fn();
+            if (!opts?.shouldRetry?.(result) || i === attempts - 1) {
+                return result;
+            }
         }
-        catch {
-            data = { raw: text };
+        catch (error) {
+            lastError = error;
+            if (i === attempts - 1) {
+                throw error;
+            }
         }
+        await sleep(250 * (i + 1));
     }
-    return {
-        status: response.status,
-        data: data,
-    };
+    throw lastError instanceof Error ? lastError : new Error("request failed");
 }
-async function joinAgent(baseUrl, name) {
+async function postJson(url, body, headers) {
+    return withRetry(async () => {
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        const text = await response.text();
+        let data = {};
+        if (text.trim().length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = { raw: text };
+            }
+        }
+        return {
+            status: response.status,
+            data: data,
+        };
+    }, {
+        shouldRetry: (result) => isRetryableStatus(result.status),
+    });
+}
+async function getJson(url, headers) {
+    return withRetry(async () => {
+        const response = await fetch(url, {
+            method: "GET",
+            headers,
+        });
+        const text = await response.text();
+        let data = {};
+        if (text.trim().length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = { raw: text };
+            }
+        }
+        return {
+            status: response.status,
+            data: data,
+        };
+    }, {
+        shouldRetry: (result) => isRetryableStatus(result.status),
+    });
+}
+async function joinAgent(baseUrl, name, options = {}) {
     const config = await (0, config_1.readConfig)();
     if (!config.token) {
         return {
@@ -97,12 +182,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 +238,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) {
@@ -172,32 +313,29 @@ async function sendMessage(baseUrl, to, text) {
     }
 }
 async function fetchInbox(baseUrl, options) {
+    const peek = options?.peek !== false;
     try {
         const headers = await authHeaders("agent");
         const params = new URLSearchParams();
-        if (options?.peek) {
+        if (peek) {
             params.set("peek", "1");
         }
         if (options?.waitSeconds && options.waitSeconds > 0) {
             params.set("wait", String(Math.min(120, options.waitSeconds)));
         }
         const qs = params.size > 0 ? `?${params.toString()}` : "";
-        const response = await fetch(withPath(baseUrl, `/v1/messages/inbox${qs}`), {
-            method: "GET",
-            headers,
-        });
-        const data = (await response.json());
-        if (!response.ok) {
+        const result = await getJson(withPath(baseUrl, `/v1/messages/inbox${qs}`), headers);
+        if (result.status < 200 || result.status >= 300) {
             return {
                 kind: "error",
-                status: response.status,
-                message: data.error ?? `Inbox failed with HTTP ${response.status}.`,
+                status: result.status,
+                message: result.data.error ?? `Inbox failed with HTTP ${result.status}.`,
             };
         }
         return {
             kind: "ok",
-            messages: data.messages ?? [],
-            agent: data.agent ?? "",
+            messages: result.data.messages ?? [],
+            agent: result.data.agent ?? "",
         };
     }
     catch (error) {

package/package.json

@@ -1,45 +1,45 @@
-{
-  "name": "@marshell/cli",
-  "version": "0.7.5",
-  "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.8",
+  "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);
+});