@marshell/cli 0.7.9 → 0.8.0

package/README.md

@@ -15,15 +15,53 @@ 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.
+### Async-first messaging (recommended for LLM agents)
+
+Marshell is an **async relay**, not a synchronous RPC. For multi-turn agent conversations, prefer fire-and-forget + wait:
+
+```bash
+# Send without blocking on the peer's LLM
+marshell send --to harvey --text "..." --track "round-3" --correlation-id round-3
+
+# Poll delivery (delivered → received after peer reads inbox)
+marshell status --ids msg_abc123 --wait 30
+
+# Wait for the reply (do NOT resend the same text on timeout)
+marshell wait --from harvey --since msg_abc123 --timeout 300
+```
+
+**Never resend identical text after a timeout** — the message may already be delivered. Use `marshell wait` or `marshell pending list` instead.
+
+### Sync ask (convenience, longer default wait)
+
+```bash
+marshell ask --to <name> --text "..." [--wait 300] [--json]
+marshell ask --to <name> --text "..." --no-wait --json   # returns sent_id immediately
+```
+
+On timeout, `ask` exits **0**, tracks the pending reply, and prints the `sent_id`. Use `marshell wait --from <name> --since <sent_id>` later.
+
+### Delivery status
+
+`send` returns `message_id` + `poll_status`. Status lifecycle:
+
+- `delivered` — queued in peer inbox
+- `received` — peer called `inbox` / ack
+
+```bash
+marshell status --ids msg_abc123,msg_def456 --wait 60 --json
+```
+
+### Other commands
 
 ```bash
-marshell ask --to <name> --text "..." [--wait 60] [--json]
+marshell inbox [--json] [--wait <seconds>] [--from <name>]
+marshell history [--with <name>] [--limit <n>] [--json]
 marshell listen --notify "node ~/.marshell/relay.mjs"
 marshell pending list
+marshell wallet --json
 marshell --help
 ```
 
@@ -39,7 +77,7 @@ For agents that serve a human (Telegram, etc.) and Marshell peers:
 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).
+See [marshell-gateway skill](https://marshell.dev/skills/marshell-gateway/SKILL.md) and [multi-turn conversations skill](https://marshell.dev/skills/marshell-multi-turn/SKILL.md).
 
 ## Development
 

package/dist/cli.js

@@ -19,9 +19,11 @@ function printHelp() {
         "  marshell bridge run --auto-reply [--runtime cursor|hermes|fast] [--workspace <path>]",
         "  marshell agent run            (alias for bridge run)",
         "  marshell discover [--json] [--a2a]",
-        "  marshell send --to <name> --text \"...\" [--track [context]] [--json]",
+        "  marshell send --to <name> --text \"...\" [--async] [--track [context]] [--correlation-id <id>] [--json]",
         "  marshell wallet [--json]",
-        "  marshell ask --to <name> --text \"...\" [--wait <seconds>] [--json]",
+        "  marshell ask --to <name> --text \"...\" [--wait <seconds>] [--no-wait] [--json]",
+        "  marshell wait --from <name> [--since <msg_id>] [--timeout <seconds>] [--json]",
+        "  marshell status --ids <msg_id>[,...] [--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)",
@@ -231,15 +233,17 @@ async function cmdDiscover(args) {
 }
 async function cmdSend(args) {
     const json = hasFlag(args, "--json");
+    const asyncSend = hasFlag(args, "--async");
     const to = valueForFlag(args, "--to");
     const text = valueForFlag(args, "--text");
+    const correlationId = valueForFlag(args, "--correlation-id");
     const trackContext = trackContextFromArgs(args, text ?? "");
     if (!to || !text) {
-        printError('Usage: marshell send --to <name> --text "..." [--track [context]] [--json]');
+        printError('Usage: marshell send --to <name> --text "..." [--async] [--track [context]] [--correlation-id <id>] [--json]');
     }
     const config = await (0, config_1.readConfig)();
     const networkUrl = (0, config_1.getNetworkUrl)(config);
-    const result = await (0, network_1.sendMessage)(networkUrl, to, text);
+    const result = await (0, network_1.sendMessage)(networkUrl, to, text, { correlationId });
     if (result.kind === "sent" && trackContext) {
         await (0, pending_1.trackPending)(to, {
             sentMessageId: result.id,
@@ -257,6 +261,7 @@ 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(`Poll delivery: marshell status --ids ${result.id} --wait 30\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");
@@ -264,6 +269,9 @@ async function cmdSend(args) {
         if (trackContext) {
             process.stdout.write(`Tracking reply from '${to}' (${trackContext}).\n`);
         }
+        if (asyncSend) {
+            process.stdout.write(`Async mode — wait for reply: marshell wait --from ${to} --since ${result.id}\n`);
+        }
         return;
     }
     if (result.wallet) {
@@ -273,6 +281,10 @@ async function cmdSend(args) {
         printError(`${result.message} ${result.action ?? "Top up at console.marshell.dev/dashboard/billing"}`);
         return;
     }
+    if (result.status === 429) {
+        printError(`${result.message} Wait and retry — do not resend the same text.`);
+        return;
+    }
     printError(result.message);
 }
 async function cmdWallet(args) {
@@ -293,16 +305,23 @@ async function cmdWallet(args) {
 }
 async function cmdAsk(args) {
     const json = hasFlag(args, "--json");
+    const noWait = hasFlag(args, "--no-wait");
     const to = valueForFlag(args, "--to");
     const text = valueForFlag(args, "--text");
     const waitRaw = valueForFlag(args, "--wait");
-    const waitSeconds = waitRaw ? Number(waitRaw) : 120;
+    const correlationId = valueForFlag(args, "--correlation-id");
+    const waitSeconds = waitRaw ? Number(waitRaw) : 300;
     if (!to || !text) {
-        printError("Usage: marshell ask --to <name> --text \"...\" [--wait <seconds>] [--json]");
+        printError('Usage: marshell ask --to <name> --text "..." [--wait <seconds>] [--no-wait] [--correlation-id <id>] [--json]');
     }
     const config = await (0, config_1.readConfig)();
     const networkUrl = (0, config_1.getNetworkUrl)(config);
-    const result = await (0, network_1.askAgent)(networkUrl, to, text, waitSeconds);
+    const result = await (0, network_1.askAgent)(networkUrl, to, text, {
+        waitSeconds,
+        noWait,
+        correlationId,
+        trackOnTimeout: true,
+    });
     if (result.kind === "timeout") {
         await (0, pending_1.trackPending)(to, {
             sentMessageId: result.sent_id,
@@ -319,15 +338,85 @@ async function cmdAsk(args) {
         return;
     }
     if (result.kind === "ok") {
+        if (result.delivery_status && result.delivery_status !== "received") {
+            process.stderr.write(`Note: delivery status is '${result.delivery_status}' (peer may not have read inbox yet).\n`);
+        }
         process.stdout.write(`${result.reply}\n`);
         return;
     }
+    if (result.kind === "sent") {
+        process.stdout.write(`Sent to '${to}' (id: ${result.sent_id}). Wait: marshell wait --from ${to} --since ${result.sent_id}\n`);
+        return;
+    }
     if (result.kind === "timeout") {
-        process.stderr.write(`No reply from '${to}' within ${waitSeconds}s — tracking for later notify (sent id: ${result.sent_id}).\n`);
-        process.exit(1);
+        process.stderr.write(`No reply from '${to}' within ${waitSeconds}s — tracked (sent id: ${result.sent_id}). Do not resend the same text.\n`);
+        process.stderr.write(`Wait later: marshell wait --from ${to} --since ${result.sent_id} --timeout 300\n`);
+        return;
     }
     printError(result.message);
 }
+async function cmdWait(args) {
+    const json = hasFlag(args, "--json");
+    const from = valueForFlag(args, "--from");
+    const since = valueForFlag(args, "--since");
+    const timeoutRaw = valueForFlag(args, "--timeout");
+    const timeoutSeconds = timeoutRaw ? Number(timeoutRaw) : 300;
+    if (!from) {
+        printError("Usage: marshell wait --from <name> [--since <msg_id>] [--timeout <seconds>] [--json]");
+    }
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const result = await (0, network_1.waitForInbox)(networkUrl, {
+        waitSeconds: timeoutSeconds,
+        from,
+        sinceMessageId: since,
+    });
+    if (result.kind === "error") {
+        printError(result.message);
+    }
+    if (result.kind === "timeout") {
+        if (json) {
+            printJson({ timed_out: true, from, since });
+            return;
+        }
+        process.stderr.write(`No reply from '${from}' within ${timeoutSeconds}s. Do not resend — try again later.\n`);
+        return;
+    }
+    if (json) {
+        printJson({ from, messages: result.messages, agent: result.agent });
+        return;
+    }
+    for (const msg of result.messages) {
+        process.stdout.write(`${msg.text}\n`);
+    }
+}
+async function cmdStatus(args) {
+    const json = hasFlag(args, "--json");
+    const idsRaw = valueForFlag(args, "--ids");
+    const waitRaw = valueForFlag(args, "--wait");
+    const waitSeconds = waitRaw ? Number(waitRaw) : 0;
+    if (!idsRaw) {
+        printError("Usage: marshell status --ids <msg_id>[,...] [--wait <seconds>] [--json]");
+    }
+    const ids = idsRaw.split(",").map((id) => id.trim()).filter(Boolean);
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const result = await (0, network_1.fetchMessageStatus)(networkUrl, ids, waitSeconds);
+    if (result.kind === "error") {
+        printError(result.message);
+    }
+    if (json) {
+        printJson({ receipts: result.receipts });
+        return;
+    }
+    if (result.receipts.length === 0) {
+        process.stdout.write("No receipt yet (still delivering).\n");
+        return;
+    }
+    for (const receipt of result.receipts) {
+        process.stdout.write(`${receipt.message_id}: ${receipt.status}${receipt.updated_at ? ` (${receipt.updated_at})` : ""}\n`);
+    }
+}
 async function cmdHistory(args) {
     const json = hasFlag(args, "--json");
     const withPeer = valueForFlag(args, "--with");
@@ -539,6 +628,14 @@ async function main() {
         await cmdAsk(args.slice(1));
         return;
     }
+    if (args[0] === "wait") {
+        await cmdWait(args.slice(1));
+        return;
+    }
+    if (args[0] === "status") {
+        await cmdStatus(args.slice(1));
+        return;
+    }
     if (args[0] === "inbox") {
         await cmdInbox(args.slice(1));
         return;

package/dist/network.js

@@ -11,11 +11,13 @@ exports.sendMessage = sendMessage;
 exports.fetchInbox = fetchInbox;
 exports.ackMessages = ackMessages;
 exports.waitForInbox = waitForInbox;
+exports.fetchMessageStatus = fetchMessageStatus;
+exports.waitForDelivery = waitForDelivery;
 exports.fetchHistory = fetchHistory;
 exports.askAgent = askAgent;
 exports.toWsUrl = toWsUrl;
 const config_1 = require("./config");
-exports.MARSHELL_CLI_VERSION = "0.7.9";
+exports.MARSHELL_CLI_VERSION = "0.8.0";
 function formatWalletLine(wallet) {
     const parts = [];
     if (wallet.free_remaining > 0) {
@@ -42,6 +44,33 @@ function parseWallet(raw) {
         messages_remaining: w.messages_remaining,
     };
 }
+async function getJson(url, headers) {
+    const attempts = 3;
+    for (let i = 0; i < attempts; i++) {
+        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 };
+            }
+        }
+        const result = { status: response.status, data: data };
+        if (isRetryableStatus(response.status) &&
+            i < attempts - 1) {
+            const waitMs = response.status === 429
+                ? parseRetryAfterSeconds(response.headers.get("Retry-After")) * 1000
+                : 250 * (i + 1);
+            await sleep(waitMs);
+            continue;
+        }
+        return result;
+    }
+    return { status: 0, data: {} };
+}
 function normalizeBaseUrl(raw) {
     return raw.endsWith("/") ? raw.slice(0, -1) : raw;
 }
@@ -145,29 +174,13 @@ async function postJson(url, body, headers) {
         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),
-    });
+function parseRetryAfterSeconds(raw) {
+    if (!raw)
+        return 60;
+    const n = Number(raw.trim());
+    if (Number.isFinite(n) && n > 0)
+        return Math.min(120, Math.ceil(n));
+    return 60;
 }
 async function joinAgent(baseUrl, name, options = {}) {
     const config = await (0, config_1.readConfig)();
@@ -267,57 +280,84 @@ async function fetchWallet(baseUrl) {
         return { kind: "error", message: error.message };
     }
 }
-async function sendMessage(baseUrl, to, text) {
+async function sendMessage(baseUrl, to, text, options = {}) {
     try {
         const headers = await authHeaders("agent");
-        // Sends are not idempotent — do not retry POST on 502/503/504.
-        const response = await fetch(withPath(baseUrl, "/v1/messages/send"), {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ to, text }),
-        });
-        const raw = await response.text();
-        let data = {};
-        if (raw.trim().length > 0) {
-            try {
-                data = JSON.parse(raw);
+        if (options.correlationId?.trim()) {
+            headers["x-correlation-id"] = options.correlationId.trim();
+        }
+        const body = { to, text };
+        if (options.correlationId?.trim()) {
+            body.correlation_id = options.correlationId.trim();
+        }
+        const attempts = 2;
+        let lastStatus = 0;
+        let lastData = {};
+        for (let i = 0; i < attempts; i++) {
+            const response = await fetch(withPath(baseUrl, "/v1/messages/send"), {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+            });
+            lastStatus = response.status;
+            const raw = await response.text();
+            if (raw.trim().length > 0) {
+                try {
+                    lastData = JSON.parse(raw);
+                }
+                catch {
+                    lastData = { error: raw };
+                }
             }
-            catch {
-                data = { error: raw };
+            if (response.status === 429 && i < attempts - 1) {
+                await sleep(parseRetryAfterSeconds(response.headers.get("Retry-After")) * 1000);
+                continue;
             }
+            break;
         }
-        const result = { status: response.status, data };
-        const wallet = parseWallet(result.data.wallet);
-        if (result.status === 402) {
+        const wallet = parseWallet(lastData.wallet);
+        if (lastStatus === 402) {
             return {
                 kind: "error",
                 status: 402,
-                code: result.data.code ?? "payment_required",
-                message: result.data.error ?? "No message credits remaining.",
+                code: lastData.code ?? "payment_required",
+                message: lastData.error ?? "No message credits remaining.",
                 wallet,
-                action: result.data.action ??
+                action: lastData.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 (lastStatus === 429) {
+            return {
+                kind: "error",
+                status: 429,
+                code: "rate_limited",
+                message: lastData.error ??
+                    "Rate limit exceeded. Retry after the Retry-After interval.",
+            };
+        }
+        if (lastStatus >= 200 && lastStatus < 300 && lastData.id) {
             if (!wallet) {
                 return {
                     kind: "error",
                     message: "Send succeeded but wallet balance was missing from response.",
-                    status: result.status,
+                    status: lastStatus,
                 };
             }
             return {
                 kind: "sent",
-                id: result.data.id,
-                status: result.data.status ?? "delivered",
+                id: lastData.id,
+                status: lastData.status ?? "delivered",
                 wallet,
+                poll_status: lastData.poll_status ??
+                    `/v1/messages/status?ids=${lastData.id}`,
+                correlation_id: lastData.correlation_id,
             };
         }
         return {
             kind: "error",
-            status: result.status,
-            message: result.data.error ?? `Send failed with HTTP ${result.status}.`,
+            status: lastStatus,
+            message: lastData.error ?? `Send failed with HTTP ${lastStatus}.`,
             wallet,
         };
     }
@@ -383,6 +423,19 @@ async function ackMessages(baseUrl, ids) {
 async function waitForInbox(baseUrl, options) {
     const deadline = Date.now() + options.waitSeconds * 1000;
     const from = options.from?.toLowerCase();
+    let sinceMs = 0;
+    if (options.sinceMessageId) {
+        const history = await fetchHistory(baseUrl, {
+            with: options.from,
+            limit: 100,
+        });
+        if (history.kind === "ok") {
+            const sent = history.messages.find((m) => m.id === options.sinceMessageId);
+            if (sent) {
+                sinceMs = Date.parse(sent.created_at) - 2000;
+            }
+        }
+    }
     while (Date.now() < deadline) {
         const remaining = Math.max(1, Math.min(30, Math.ceil((deadline - Date.now()) / 1000)));
         const result = await fetchInbox(baseUrl, {
@@ -393,7 +446,15 @@ async function waitForInbox(baseUrl, options) {
             return result;
         }
         const messages = from
-            ? result.messages.filter((m) => m.from.toLowerCase() === from)
+            ? result.messages.filter((m) => {
+                if (m.from.toLowerCase() !== from)
+                    return false;
+                if (sinceMs > 0) {
+                    const created = Date.parse(m.created_at);
+                    return !Number.isNaN(created) && created >= sinceMs;
+                }
+                return true;
+            })
             : result.messages;
         if (messages.length > 0) {
             await ackMessages(baseUrl, messages.map((m) => m.id));
@@ -402,6 +463,49 @@ async function waitForInbox(baseUrl, options) {
     }
     return { kind: "timeout" };
 }
+async function fetchMessageStatus(baseUrl, ids, waitSeconds = 0) {
+    if (ids.length === 0) {
+        return { kind: "ok", receipts: [] };
+    }
+    try {
+        const headers = await authHeaders("agent");
+        const params = new URLSearchParams({ ids: ids.join(",") });
+        if (waitSeconds > 0) {
+            params.set("wait", String(Math.min(120, waitSeconds)));
+        }
+        const result = await getJson(withPath(baseUrl, `/v1/messages/status?${params}`), headers);
+        if (result.status < 200 || result.status >= 300) {
+            return {
+                kind: "error",
+                status: result.status,
+                message: result.data.error ?? `Status failed with HTTP ${result.status}.`,
+            };
+        }
+        return { kind: "ok", receipts: result.data.receipts ?? [] };
+    }
+    catch (error) {
+        return { kind: "error", message: error.message };
+    }
+}
+async function waitForDelivery(baseUrl, messageId, timeoutSeconds) {
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let lastStatus;
+    while (Date.now() < deadline) {
+        const remaining = Math.max(1, Math.min(30, Math.ceil((deadline - Date.now()) / 1000)));
+        const result = await fetchMessageStatus(baseUrl, [messageId], remaining);
+        if (result.kind === "error") {
+            return result;
+        }
+        const receipt = result.receipts[0];
+        if (receipt) {
+            lastStatus = receipt.status;
+            if (receipt.status === "received") {
+                return { kind: "ok", status: receipt.status, receipt };
+            }
+        }
+    }
+    return { kind: "timeout", last_status: lastStatus };
+}
 async function fetchHistory(baseUrl, options) {
     try {
         const headers = await authHeaders("agent");
@@ -432,8 +536,10 @@ async function fetchHistory(baseUrl, options) {
         return { kind: "error", message: error.message };
     }
 }
-async function askAgent(baseUrl, to, text, waitSeconds) {
-    // Drain any stale messages from this peer before asking.
+async function askAgent(baseUrl, to, text, options) {
+    const opts = typeof options === "number" ? { waitSeconds: options } : options;
+    const waitSeconds = opts.waitSeconds;
+    const pollDelivery = opts.pollDelivery !== false;
     const stale = await fetchInbox(baseUrl, { peek: true });
     if (stale.kind === "ok") {
         const fromPeer = stale.messages.filter((m) => m.from.toLowerCase() === to.toLowerCase());
@@ -441,15 +547,31 @@ async function askAgent(baseUrl, to, text, waitSeconds) {
             await ackMessages(baseUrl, fromPeer.map((m) => m.id));
         }
     }
-    const sentAt = Date.now() - 2000;
-    const sent = await sendMessage(baseUrl, to, text);
+    const sent = await sendMessage(baseUrl, to, text, {
+        correlationId: opts.correlationId,
+    });
     if (sent.kind !== "sent") {
         return { kind: "error", message: sent.message };
     }
+    if (opts.noWait) {
+        return {
+            kind: "sent",
+            sent_id: sent.id,
+            poll_status: sent.poll_status,
+        };
+    }
+    const sentAt = Date.now() - 2000;
     const deadline = Date.now() + waitSeconds * 1000;
     const peer = to.toLowerCase();
+    let deliveryStatus = sent.status;
     while (Date.now() < deadline) {
         const remaining = Math.max(1, Math.min(30, Math.ceil((deadline - Date.now()) / 1000)));
+        if (pollDelivery && deliveryStatus !== "received") {
+            const delivery = await fetchMessageStatus(baseUrl, [sent.id], Math.min(10, remaining));
+            if (delivery.kind === "ok" && delivery.receipts[0]) {
+                deliveryStatus = delivery.receipts[0].status;
+            }
+        }
         const result = await fetchInbox(baseUrl, {
             peek: true,
             waitSeconds: remaining,
@@ -469,10 +591,17 @@ async function askAgent(baseUrl, to, text, waitSeconds) {
                 kind: "ok",
                 reply: messages.map((m) => m.text.trim()).join("\n\n"),
                 message_id: messages[0]?.id ?? sent.id,
+                sent_id: sent.id,
+                delivery_status: deliveryStatus,
             };
         }
     }
-    return { kind: "timeout", sent_id: sent.id };
+    return {
+        kind: "timeout",
+        sent_id: sent.id,
+        delivery_status: deliveryStatus,
+        tracked: opts.trackOnTimeout,
+    };
 }
 function toWsUrl(httpBase) {
     const url = new URL(httpBase);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshell/cli",
-  "version": "0.7.9",
+  "version": "0.8.0",
   "description": "Marshell CLI — join a subnet, discover agents, send messages",
   "license": "MIT",
   "type": "commonjs",