@marshell/cli 0.6.0 → 0.7.1

package/README.md

@@ -14,9 +14,11 @@ npm install -g @marshell/cli@latest
 marshell auth set <token>
 marshell auth status --json
 marshell agent join --name <short-name>
-marshell agent run
 marshell discover --json
-marshell send --to <name> --text "..." [--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
 ```
 
@@ -24,6 +26,16 @@ 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

package/dist/bridge.js

@@ -4,23 +4,145 @@ exports.tryFastReply = tryFastReply;
 exports.handleInbound = handleInbound;
 exports.runBridge = runBridge;
 const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const network_1 = require("./network");
+const pending_1 = require("./pending");
 const DEFAULT_REPLY_TIMEOUT_MS = 120_000;
-/** Instant replies — no LLM spawn. Marshell transport stays fast. */
-function tryFastReply(msg) {
+const GREETING_COOLDOWN_MS = 120_000;
+const ECHO_WINDOW_MS = 60_000;
+const peers = new Map();
+function peerState(name) {
+    const key = name.toLowerCase();
+    let state = peers.get(key);
+    if (!state) {
+        state = { lastGreetingAt: 0, recentOutbound: [], inflight: false };
+        peers.set(key, state);
+    }
+    return state;
+}
+function rememberOutbound(peer, text) {
+    const state = peerState(peer);
+    const now = Date.now();
+    state.recentOutbound.push({ text: text.trim().toLowerCase(), at: now });
+    state.recentOutbound = state.recentOutbound.filter((item) => now - item.at < ECHO_WINDOW_MS);
+}
+function isEcho(peer, text) {
+    const normalized = text.trim().toLowerCase();
+    const state = peerState(peer);
+    const now = Date.now();
+    return state.recentOutbound.some((item) => {
+        if (now - item.at >= ECHO_WINDOW_MS)
+            return false;
+        if (item.text === normalized)
+            return true;
+        // Peer quoting/acking our last reply ("got it — acknowledged").
+        if (normalized.includes(item.text) || item.text.includes(normalized)) {
+            return item.text.length >= 4 && normalized.length <= item.text.length + 40;
+        }
+        return false;
+    });
+}
+function isGreeting(text) {
+    return /^(hi|hello|hey|yo|sup|picun)[!.?\s]*$/i.test(text.trim());
+}
+/** Short acks / reactions — deliver only, never auto-reply (stops chat spam). */
+function isAckOnly(text) {
+    const t = text.trim();
+    if (!t)
+        return true;
+    if (/^[\p{Emoji_Presentation}\p{Extended_Pictographic}\s\p{P}]+$/u.test(t)) {
+        return true;
+    }
+    if (/^(got it|ok|okay|k|kk|thanks|thank you|thx|ty|cool|nice|great|ack|acknowledged|roger|copy|noted|np|no problem|sounds good|sg|lgtm|sure|yep|yeah|yes|no|nah|👍|✅)[.!*]*$/i.test(t)) {
+        return true;
+    }
+    // Very short non-questions are almost always reactions.
+    if (t.length <= 16 && !/[?]/.test(t) && !/\bwho\b|\bwhat\b|\bhow\b/i.test(t)) {
+        return true;
+    }
+    return false;
+}
+/** Only spend LLM budget on real questions / tasks. */
+function needsReply(text) {
+    const t = text.trim();
+    if (!t || isGreeting(t) || isAckOnly(t) || /^pong$/i.test(t)) {
+        return false;
+    }
+    if (/[?]/.test(t))
+        return true;
+    if (/\b(who are you|who're you|what are you|and you are)\b/i.test(t)) {
+        return true;
+    }
+    if (/^(who|what|where|when|why|how|can|could|would|please|tell|ask|explain|list|show|find|read|check|run|write|fix|deploy|summarize)\b/i.test(t)) {
+        return true;
+    }
+    // Longer messages are likely real tasks.
+    return t.length >= 48;
+}
+/**
+ * Instant replies — no LLM. Never reply in a way that loops with another bridge.
+ * ping → pong (pong alone is ignored)
+ * greetings → one-shot per peer, non-greeting text
+ * echo:… → body
+ */
+function tryFastReply(msg, options) {
     const text = msg.text.trim();
-    if (/^(ping|pong)$/i.test(text)) {
+    if (/^ping$/i.test(text)) {
         return "pong";
     }
-    if (/^(hi|hello|hey|yo|sup|picun)[!.?\s]*$/i.test(text)) {
-        return text.toLowerCase() === "picun" ? "picun" : "hi";
+    // Never auto-reply to "pong" — breaks ping/pong loops.
+    if (/^pong$/i.test(text)) {
+        return null;
+    }
+    if (isGreeting(text)) {
+        if (options?.allowGreeting === false) {
+            return null;
+        }
+        const state = peerState(msg.from);
+        const now = Date.now();
+        if (now - state.lastGreetingAt < GREETING_COOLDOWN_MS) {
+            return null;
+        }
+        state.lastGreetingAt = now;
+        // Reply must NOT match isGreeting / ping, or peer bridge will loop.
+        return `hey ${msg.from} — here. send a question anytime.`;
     }
     if (text.toLowerCase().startsWith("echo:")) {
         const body = text.slice(5).trim();
         return body || "(empty)";
     }
+    // Identity questions — answer without spawning LLM (reliable + instant).
+    if (/\bwho are you\b|\bwho're you\b|\bwhat are you\b|\band you are\??\s*$/i.test(text)) {
+        return "I'm cursor — Marshell agent on this machine (codebase workspace).";
+    }
     return null;
 }
+/** Resolve a CLI binary so Windows .cmd wrappers work under spawn(shell:false). */
+function resolveRuntimeCommand(command) {
+    if (process.platform === "win32" && command === "agent") {
+        const base = (0, node_path_1.join)(process.env.LOCALAPPDATA ?? "", "cursor-agent");
+        const versionsDir = (0, node_path_1.join)(base, "versions");
+        if ((0, node_fs_1.existsSync)(versionsDir)) {
+            const versions = (0, node_fs_1.readdirSync)(versionsDir)
+                .filter((name) => /^\d{4}\./.test(name))
+                .sort()
+                .reverse();
+            for (const version of versions) {
+                const nodePath = (0, node_path_1.join)(versionsDir, version, "node.exe");
+                const entry = (0, node_path_1.join)(versionsDir, version, "index.js");
+                if ((0, node_fs_1.existsSync)(nodePath) && (0, node_fs_1.existsSync)(entry)) {
+                    return { command: nodePath, argsPrefix: [entry] };
+                }
+            }
+        }
+        const agentCmd = (0, node_path_1.join)(base, "agent.cmd");
+        if ((0, node_fs_1.existsSync)(agentCmd)) {
+            return { command: agentCmd, argsPrefix: [] };
+        }
+    }
+    return { command, argsPrefix: [] };
+}
 function killProcessTree(pid) {
     if (!pid)
         return;
@@ -96,13 +218,19 @@ function spawnCommand(command, args, options) {
 }
 async function generateRuntimeReply(msg, runtime, workspace, timeoutMs) {
     const prompt = [
-        `Marshell agent "${msg.from}" sent:`,
-        msg.text,
+        `You are Marshell agent listening on this machine.`,
+        `Peer agent "${msg.from}" sent you a message.`,
+        "Answer using the local workspace when relevant.",
+        "If they ask who you are, say you are the cursor agent on this Marshell subnet.",
+        "Reply with ONLY the answer text. No tools, no marshell CLI, no meta commentary.",
         "",
-        "Reply with ONLY the answer. No tools, no marshell CLI, no meta commentary.",
+        "Message:",
+        msg.text,
     ].join("\n");
     if (runtime === "cursor") {
-        const result = await spawnCommand("agent", [
+        const resolved = resolveRuntimeCommand("agent");
+        const result = await spawnCommand(resolved.command, [
+            ...resolved.argsPrefix,
             "-p",
             "--trust",
             "--mode",
@@ -130,6 +258,31 @@ async function generateRuntimeReply(msg, runtime, workspace, timeoutMs) {
     }
     return result.stdout.trim();
 }
+async function runNotifyCommand(notify, msg, pending) {
+    const payload = JSON.stringify({
+        event: "message",
+        id: msg.id,
+        from: msg.from,
+        text: msg.text,
+        created_at: msg.created_at,
+        pending: pending ?? undefined,
+    });
+    const timeoutMs = 30_000;
+    if (process.platform === "win32") {
+        const result = await spawnCommand("cmd.exe", ["/d", "/s", "/c", notify], { input: payload, timeoutMs });
+        if (result.code !== 0) {
+            throw new Error(result.stderr || result.stdout || "notify failed");
+        }
+        return;
+    }
+    const result = await spawnCommand("sh", ["-c", notify], {
+        input: payload,
+        timeoutMs,
+    });
+    if (result.code !== 0) {
+        throw new Error(result.stderr || result.stdout || "notify failed");
+    }
+}
 async function runHookReply(hook, msg, timeoutMs) {
     const payload = JSON.stringify({
         id: msg.id,
@@ -171,6 +324,12 @@ function emitEvent(json, event) {
     else if (kind === "reply") {
         process.stdout.write(`[reply] to=${event.to} id=${event.id}\n`);
     }
+    else if (kind === "skip") {
+        process.stdout.write(`[skip] from=${event.from} reason=${event.reason}\n`);
+    }
+    else if (kind === "notify") {
+        process.stdout.write(`[notify] from=${event.from} id=${event.id}${event.pending ? " (tracked)" : ""}\n`);
+    }
     else if (kind === "error") {
         process.stderr.write(`[bridge] ${event.message}\n`);
     }
@@ -180,6 +339,7 @@ async function deliverReply(networkUrl, msg, reply, json) {
     if (sent.kind !== "sent") {
         throw new Error(sent.message);
     }
+    rememberOutbound(msg.from, reply);
     emitEvent(json, {
         type: "reply",
         to: msg.from,
@@ -189,6 +349,17 @@ async function deliverReply(networkUrl, msg, reply, json) {
     });
 }
 async function processReplyAsync(networkUrl, msg, options) {
+    const state = peerState(msg.from);
+    if (state.inflight) {
+        emitEvent(options.json, {
+            type: "skip",
+            from: msg.from,
+            reason: "peer already has an inflight reply",
+            id: msg.id,
+        });
+        return;
+    }
+    state.inflight = true;
     try {
         let reply = tryFastReply(msg);
         if (!reply && options.hook) {
@@ -208,42 +379,135 @@ async function processReplyAsync(networkUrl, msg, options) {
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         emitEvent(options.json, { type: "error", message, in_reply_to: msg.id });
-        await (0, network_1.sendMessage)(networkUrl, msg.from, `Auto-reply failed (${message}). Please retry.`);
+        // Never send failure text to peers — it spams the subnet and triggers loops.
+    }
+    finally {
+        state.inflight = false;
     }
 }
 async function handleInbound(networkUrl, msg, options) {
+    const pending = await (0, pending_1.matchPending)(msg.from);
     emitEvent(options.json, {
         type: "message",
         id: msg.id,
         from: msg.from,
         text: msg.text,
         created_at: msg.created_at,
+        pending: pending ?? undefined,
     });
+    // Push to human channel (Telegram, webhook, etc.) — side effect only.
+    if (options.notify && !isEcho(msg.from, msg.text)) {
+        try {
+            await runNotifyCommand(options.notify, msg, pending);
+            emitEvent(options.json, {
+                type: "notify",
+                from: msg.from,
+                id: msg.id,
+                pending: pending?.context,
+            });
+            if (pending) {
+                await (0, pending_1.clearPending)(msg.from);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            emitEvent(options.json, {
+                type: "error",
+                message: `notify: ${message}`,
+                in_reply_to: msg.id,
+            });
+        }
+    }
+    // Always ack so backlog never sticks.
+    await (0, network_1.ackMessages)(networkUrl, [msg.id]);
+    // Drop echoes of our own recent outbound (hi↔hi loops).
+    if (isEcho(msg.from, msg.text)) {
+        emitEvent(options.json, {
+            type: "skip",
+            from: msg.from,
+            reason: "echo of our recent outbound",
+            id: msg.id,
+        });
+        return;
+    }
     const fast = tryFastReply(msg);
     if (fast) {
         await deliverReply(networkUrl, msg, fast, options.json);
-        await (0, network_1.ackMessages)(networkUrl, [msg.id]);
+        return;
+    }
+    // Greetings / acks / reactions: deliver only, no reply spam.
+    if (!needsReply(msg.text)) {
+        emitEvent(options.json, {
+            type: "skip",
+            from: msg.from,
+            reason: "no-reply (ack/greeting/trivial)",
+            id: msg.id,
+        });
         return;
     }
     const willReply = Boolean(options.hook) ||
         (options.autoReply && options.runtime !== "fast");
-    // Ack immediately so transport never blocks on slow LLM / hook.
-    await (0, network_1.ackMessages)(networkUrl, [msg.id]);
     if (!willReply) {
         return;
     }
     void processReplyAsync(networkUrl, msg, options);
 }
+async function drainBacklog(networkUrl, options) {
+    const result = await (0, network_1.fetchInbox)(networkUrl, { peek: true });
+    if (result.kind !== "ok" || result.messages.length === 0) {
+        return;
+    }
+    // With --notify, deliver backlog for tracked peers only (avoid hi storms).
+    if (options.notify) {
+        const pendingPeers = new Set((await (0, pending_1.listPending)()).map((p) => p.peer.toLowerCase()));
+        const messages = [...result.messages].sort((a, b) => {
+            const ta = Date.parse(a.created_at) || 0;
+            const tb = Date.parse(b.created_at) || 0;
+            return ta - tb;
+        });
+        let drained = 0;
+        for (const msg of messages) {
+            if (pendingPeers.has(msg.from.toLowerCase())) {
+                await handleInbound(networkUrl, msg, options);
+            }
+            else {
+                await (0, network_1.ackMessages)(networkUrl, [msg.id]);
+                drained += 1;
+            }
+        }
+        if (drained > 0) {
+            emitEvent(options.json, {
+                type: "skip",
+                from: "*",
+                reason: `drained ${drained} untracked backlog message(s) on startup`,
+            });
+        }
+        return;
+    }
+    await (0, network_1.ackMessages)(networkUrl, result.messages.map((m) => m.id));
+    emitEvent(options.json, {
+        type: "skip",
+        from: "*",
+        reason: `drained ${result.messages.length} backlog message(s) on startup`,
+    });
+}
 async function runBridge(options) {
     const label = options.agentName ?? "agent";
-    const mode = options.hook
-        ? "hook"
-        : options.autoReply
-            ? options.runtime === "fast"
-                ? "fast-only"
-                : `auto-reply (${options.runtime})`
-            : "deliver-only";
+    const mode = options.notify
+        ? options.hook
+            ? "hook+notify"
+            : options.autoReply
+                ? `auto-reply (${options.runtime})+notify`
+                : "deliver+notify"
+        : options.hook
+            ? "hook"
+            : options.autoReply
+                ? options.runtime === "fast"
+                    ? "fast-only"
+                    : `auto-reply (${options.runtime})`
+                : "deliver-only";
     process.stdout.write(`Bridge listening as '${label}' (${mode}).\n`);
+    await drainBacklog(options.networkUrl, options);
     let stopped = false;
     const cleanup = () => {
         if (stopped)
@@ -264,7 +528,13 @@ async function runBridge(options) {
             await new Promise((resolve) => setTimeout(resolve, 2000));
             continue;
         }
-        for (const msg of result.messages) {
+        // Newest first — real questions beat greeting backlog.
+        const messages = [...result.messages].sort((a, b) => {
+            const ta = Date.parse(a.created_at) || 0;
+            const tb = Date.parse(b.created_at) || 0;
+            return tb - ta;
+        });
+        for (const msg of messages) {
             await handleInbound(options.networkUrl, msg, options);
         }
     }

package/dist/cli.js

@@ -5,6 +5,7 @@ const node_os_1 = require("node:os");
 const bridge_1 = require("./bridge");
 const config_1 = require("./config");
 const network_1 = require("./network");
+const pending_1 = require("./pending");
 function printHelp() {
     const message = [
         "marshell - agent messaging bridge",
@@ -17,23 +18,24 @@ function printHelp() {
         "  marshell bridge run --auto-reply [--runtime cursor|hermes|fast] [--workspace <path>]",
         "  marshell agent run            (alias for bridge run)",
         "  marshell discover [--json]",
-        "  marshell send --to <name> --text \"...\" [--json]",
+        "  marshell send --to <name> --text \"...\" [--track [context]] [--json]",
         "  marshell ask --to <name> --text \"...\" [--wait <seconds>] [--json]",
         "  marshell inbox [--json] [--wait <seconds>] [--from <name>]",
-        "  marshell listen [--json]      (alias for bridge run)",
+        "  marshell history [--with <name>] [--limit <n>] [--json]",
+        "  marshell listen [--json] [--notify <cmd>]  (deliver-only listener)",
+        "  marshell pending list|clear [--peer <name>] [--json]",
         "  marshell --help",
         "",
-        "Bridge (Happy-style transport):",
-        "  Keeps a persistent listener. Delivers messages instantly.",
-        "  Fast path: ping→pong, hi→hi, echo:…→… (no LLM).",
-        "  --auto-reply spawns LLM only for non-trivial messages (async, non-blocking).",
-        "  Prefer: marshell ask --to <peer> --text \"...\" for request/response.",
+        "Middleware: send / inbox / history. Agents think; Marshell only delivers.",
+        "  inbox  = unread only (empty after read)",
+        "  history = last 24h with a peer (use this to recall past chats)",
         "",
         "Environment:",
         "  MARSHELL_NETWORK_URL  default: https://network.marshell.dev",
         "  MARSHELL_AGENT_NAME   default agent name for auth set",
         "  MARSHELL_WORKSPACE    workspace for cursor auto-reply",
         "  MARSHELL_HOOK         default hook command for bridge",
+        "  MARSHELL_NOTIFY       default notify command for listen (--notify)",
         "  MARSHELL_CONFIG       optional path to config file",
     ].join("\n");
     process.stdout.write(`${message}\n`);
@@ -73,6 +75,21 @@ function valueForFlag(args, flag) {
     }
     return args[index + 1];
 }
+function trackContextFromArgs(args, fallback) {
+    if (!hasFlag(args, "--track")) {
+        return undefined;
+    }
+    const explicit = valueForFlag(args, "--track");
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    const trackIndex = args.indexOf("--track");
+    const next = args[trackIndex + 1];
+    if (next && !next.startsWith("--")) {
+        return next;
+    }
+    return fallback;
+}
 function bridgeOptionsFromArgs(args) {
     const configPromise = (0, config_1.readConfig)();
     // sync read not available — caller must await
@@ -83,6 +100,7 @@ function bridgeOptionsFromArgs(args) {
         process.env.MARSHELL_WORKSPACE ??
         process.cwd();
     const hook = valueForFlag(args, "--hook") ?? process.env.MARSHELL_HOOK;
+    const notify = valueForFlag(args, "--notify") ?? process.env.MARSHELL_NOTIFY;
     const runtimeFlag = valueForFlag(args, "--runtime");
     const runtime = runtimeFlag === "hermes" || runtimeFlag === "cursor" || runtimeFlag === "fast"
         ? runtimeFlag
@@ -99,6 +117,7 @@ function bridgeOptionsFromArgs(args) {
         runtime,
         workspace,
         hook,
+        notify,
         json,
         replyTimeoutMs,
     };
@@ -199,18 +218,33 @@ async function cmdSend(args) {
     const json = hasFlag(args, "--json");
     const to = valueForFlag(args, "--to");
     const text = valueForFlag(args, "--text");
+    const trackContext = trackContextFromArgs(args, text ?? "");
     if (!to || !text) {
-        printError("Usage: marshell send --to <name> --text \"...\" [--json]");
+        printError('Usage: marshell send --to <name> --text "..." [--track [context]] [--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);
+    if (result.kind === "sent" && trackContext) {
+        await (0, pending_1.trackPending)(to, {
+            sentMessageId: result.id,
+            sentText: text,
+            context: trackContext,
+            sentAt: new Date().toISOString(),
+        });
+    }
     if (json) {
-        printJson(result);
+        printJson({
+            ...result,
+            tracked: Boolean(trackContext && result.kind === "sent"),
+        });
         return;
     }
     if (result.kind === "sent") {
         process.stdout.write(`Sent message to '${to}' (id: ${result.id}, status: ${result.status}).\n`);
+        if (trackContext) {
+            process.stdout.write(`Tracking reply from '${to}' (${trackContext}).\n`);
+        }
         return;
     }
     printError(result.message);
@@ -227,8 +261,19 @@ async function cmdAsk(args) {
     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);
+    if (result.kind === "timeout") {
+        await (0, pending_1.trackPending)(to, {
+            sentMessageId: result.sent_id,
+            sentText: text,
+            context: text,
+            sentAt: new Date().toISOString(),
+        });
+    }
     if (json) {
-        printJson(result);
+        printJson({
+            ...result,
+            tracked: result.kind === "timeout",
+        });
         return;
     }
     if (result.kind === "ok") {
@@ -236,10 +281,35 @@ async function cmdAsk(args) {
         return;
     }
     if (result.kind === "timeout") {
-        printError(`No reply from '${to}' within ${waitSeconds}s (sent id: ${result.sent_id}). Is their bridge running?`);
+        process.stderr.write(`No reply from '${to}' within ${waitSeconds}s — tracking for later notify (sent id: ${result.sent_id}).\n`);
+        process.exit(1);
     }
     printError(result.message);
 }
+async function cmdHistory(args) {
+    const json = hasFlag(args, "--json");
+    const withPeer = valueForFlag(args, "--with");
+    const limitRaw = valueForFlag(args, "--limit");
+    const limit = limitRaw ? Number(limitRaw) : 50;
+    const config = await (0, config_1.readConfig)();
+    const networkUrl = (0, config_1.getNetworkUrl)(config);
+    const result = await (0, network_1.fetchHistory)(networkUrl, { with: withPeer, limit });
+    if (result.kind === "error") {
+        printError(result.message);
+    }
+    if (json) {
+        printJson({ agent: result.agent, messages: result.messages });
+        return;
+    }
+    if (result.messages.length === 0) {
+        process.stdout.write("No messages in the last 24h.\n");
+        return;
+    }
+    for (const msg of [...result.messages].reverse()) {
+        const arrow = msg.direction === "out" ? "→" : "←";
+        process.stdout.write(`${msg.created_at} ${arrow} ${msg.peer}: ${msg.text}\n`);
+    }
+}
 async function cmdInbox(args) {
     const json = hasFlag(args, "--json");
     const from = valueForFlag(args, "--from");
@@ -295,6 +365,39 @@ async function cmdInbox(args) {
         process.stdout.write(`[${msg.from}] ${msg.text}\n`);
     }
 }
+async function cmdPending(args) {
+    const json = hasFlag(args, "--json");
+    const sub = args[0];
+    if (sub === "list") {
+        const entries = await (0, pending_1.listPending)();
+        if (json) {
+            printJson({ pending: entries });
+            return;
+        }
+        if (entries.length === 0) {
+            process.stdout.write("No pending replies.\n");
+            return;
+        }
+        for (const entry of entries) {
+            process.stdout.write(`- ${entry.peer}: ${entry.context} (since ${entry.sentAt})\n`);
+        }
+        return;
+    }
+    if (sub === "clear") {
+        const peer = valueForFlag(args, "--peer");
+        if (!peer) {
+            printError("Usage: marshell pending clear --peer <name>");
+        }
+        const cleared = await (0, pending_1.clearPending)(peer);
+        if (json) {
+            printJson({ peer, cleared });
+            return;
+        }
+        process.stdout.write(cleared ? `Cleared pending for '${peer}'.\n` : `No pending for '${peer}'.\n`);
+        return;
+    }
+    printError("Usage: marshell pending list|clear [--peer <name>]");
+}
 async function cmdListen(args) {
     const waitRaw = valueForFlag(args, "--wait");
     const waitSeconds = waitRaw ? Number(waitRaw) : 0;
@@ -362,10 +465,18 @@ async function main() {
         await cmdInbox(args.slice(1));
         return;
     }
+    if (args[0] === "history") {
+        await cmdHistory(args.slice(1));
+        return;
+    }
     if (args[0] === "listen") {
         await cmdListen(args.slice(1));
         return;
     }
+    if (args[0] === "pending") {
+        await cmdPending(args.slice(1));
+        return;
+    }
     printError(`Unknown command '${args[0]}'. Run marshell --help`);
 }
 main().catch((error) => {

package/dist/network.js

@@ -7,6 +7,7 @@ exports.sendMessage = sendMessage;
 exports.fetchInbox = fetchInbox;
 exports.ackMessages = ackMessages;
 exports.waitForInbox = waitForInbox;
+exports.fetchHistory = fetchHistory;
 exports.askAgent = askAgent;
 exports.toWsUrl = toWsUrl;
 const config_1 = require("./config");
@@ -124,8 +125,11 @@ async function joinAgent(baseUrl, name) {
     }
 }
 async function discoverPeers(baseUrl) {
-    const headers = await authHeaders("token");
+    // Prefer agent_key — survives join-token rotation.
+    const config = await (0, config_1.readConfig)();
+    const kind = config.agentKey ? "agent" : "token";
     try {
+        const headers = await authHeaders(kind);
         const response = await fetch(withPath(baseUrl, "/v1/peers"), {
             method: "GET",
             headers,
@@ -244,6 +248,36 @@ async function waitForInbox(baseUrl, options) {
     }
     return { kind: "timeout" };
 }
+async function fetchHistory(baseUrl, options) {
+    try {
+        const headers = await authHeaders("agent");
+        const params = new URLSearchParams();
+        if (options?.with) {
+            params.set("with", options.with);
+        }
+        if (options?.limit && options.limit > 0) {
+            params.set("limit", String(options.limit));
+        }
+        const qs = params.size > 0 ? `?${params.toString()}` : "";
+        const response = await fetch(withPath(baseUrl, `/v1/messages/history${qs}`), { method: "GET", headers });
+        const data = (await response.json());
+        if (!response.ok) {
+            return {
+                kind: "error",
+                status: response.status,
+                message: data.error ?? `History failed with HTTP ${response.status}.`,
+            };
+        }
+        return {
+            kind: "ok",
+            agent: data.agent ?? "",
+            messages: data.messages ?? [],
+        };
+    }
+    catch (error) {
+        return { kind: "error", message: error.message };
+    }
+}
 async function askAgent(baseUrl, to, text, waitSeconds) {
     // Drain any stale messages from this peer before asking.
     const stale = await fetchInbox(baseUrl, { peek: true });

package/dist/pending.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackPending = trackPending;
+exports.matchPending = matchPending;
+exports.clearPending = clearPending;
+exports.listPending = listPending;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+function pendingDir() {
+    return (0, node_path_1.join)((0, node_os_1.homedir)(), ".marshell", "pending");
+}
+function pendingPath(peer) {
+    const safe = peer.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
+    return (0, node_path_1.join)(pendingDir(), `${safe}.json`);
+}
+async function trackPending(peer, entry) {
+    await (0, promises_1.mkdir)(pendingDir(), { recursive: true });
+    const full = { peer: peer.toLowerCase(), ...entry };
+    await (0, promises_1.writeFile)(pendingPath(peer), `${JSON.stringify(full, null, 2)}\n`, "utf8");
+    return full;
+}
+async function matchPending(peer) {
+    try {
+        const raw = await (0, promises_1.readFile)(pendingPath(peer), "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const maybeCode = error.code;
+        if (maybeCode === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function clearPending(peer) {
+    try {
+        await (0, promises_1.unlink)(pendingPath(peer));
+        return true;
+    }
+    catch (error) {
+        const maybeCode = error.code;
+        if (maybeCode === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+async function listPending() {
+    try {
+        const files = await (0, promises_1.readdir)(pendingDir());
+        const entries = [];
+        for (const file of files) {
+            if (!file.endsWith(".json"))
+                continue;
+            try {
+                const raw = await (0, promises_1.readFile)((0, node_path_1.join)(pendingDir(), file), "utf8");
+                entries.push(JSON.parse(raw));
+            }
+            catch {
+                // ignore corrupt files
+            }
+        }
+        return entries.sort((a, b) => Date.parse(b.sentAt) - Date.parse(a.sentAt));
+    }
+    catch (error) {
+        const maybeCode = error.code;
+        if (maybeCode === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshell/cli",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Marshell CLI — join a subnet, discover agents, send messages",
   "license": "MIT",
   "type": "commonjs",
@@ -10,6 +10,7 @@
   "files": [
     "bin",
     "dist",
+    "scripts",
     "README.md"
   ],
   "scripts": {

package/scripts/relay.mjs

@@ -0,0 +1,71 @@
+#!/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 = `Message 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);
+  }
+
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify({ ...payload, message })}\n`);
+  } else {
+    process.stdout.write(`${message}\n`);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`relay: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});