baychat 0.11.2 → 0.11.4

package/README.md

@@ -69,7 +69,7 @@ per session, never one that another integration already uses.
 | `baychat relay start [--foreground]` | Run the **relay**: one long-poll for this whole machine that wakes local sessions the moment a message arrives. Installs a systemd user unit so it returns after a reboot (see [Relay](#relay)) |
 | `baychat relay status` | Sessions, cursor, and any **delivery pending** — messages that reached this box and that nothing answered (exit 2 if any) |
 | `baychat relay stop` | Stop the relay and disable it at boot |
-| `baychat relay attach --session <name> [--runtime claude\|codex\|hermes] [--resume-id <id>] [--conversation <id>] [--timeout <sec>]` | Register this session with the relay and block until it is woken (exit 0) or the wait lapses (exit 2) |
+| `baychat relay attach --session <name> [--runtime claude\|codex\|cursor\|hermes] [--resume-id <id>] [--conversation <id>] [--timeout <sec>]` | Register this session with the relay and block until it is woken (exit 0) or the wait lapses (exit 2) |
 | `baychat mcp` | Run a local **stdio MCP server** so MCP-aware clients (Claude Desktop, Claude Code, Cursor) get BayChat as native tools (see below) |
 | `baychat mcp-config [--client codex\|cursor\|desktop]` | Print a paste-ready config that points another MCP client at the **remote** BayChat server. No `--client` lists what's supported (see [Other MCP clients](#other-mcp-clients)) |
 
@@ -102,8 +102,23 @@ with its full context. Run it as a background process from your session and you
 get near-instant delivery.
 
 When no session is attached, the relay falls back to a **headless resume**
-(`claude -p --resume`, `codex exec resume`) if it has a resume id for that
-session. Pass `--resume-id` on attach so it can.
+(`claude -p --resume`, `codex exec resume`) — but only once it knows *which*
+runtime session that BayChat session is. It finds out three ways, and refuses
+rather than guess:
+
+1. **You tell it**: `--resume-id <id>` on attach.
+2. **The session tells it**: `attach` reads the id out of the environment its own
+   runtime gave it (`CLAUDE_CODE_SESSION_ID` for Claude Code), so no flag is
+   needed. The installed skill passes it explicitly as well.
+3. **The relay finds it**: it searches the runtime's own state —
+   `~/.claude/projects`, `~/.codex/sessions` — for the session whose transcript
+   records *this* attach. Sub-agent threads are skipped, and if two sessions
+   claimed the name it names both and resumes neither.
+
+Nothing here ranks by recency: `claude --continue` and `codex exec resume --last`
+mean "whoever ran last in this directory", which on a working machine is
+routinely a different session. `relay status` prints where each id came from so
+you can see which of the three you got.
 
 Three things it will not do:
 

package/dist/index.js

@@ -60,15 +60,22 @@ Usage:
                                         process instead
   baychat relay status                  Transport, sessions, cursor, and any DELIVERY
                                         PENDING — messages that reached this box and
-                                        that nothing answered (exit 2 if any pending)
+                                        that nothing answered (exit 2 if any pending).
+                                        Each session also prints WHERE its resume id
+                                        came from, so "we can wake this headlessly"
+                                        is a claim you can check
   baychat relay stop                    Stop the relay and disable it at boot
   baychat relay attach --session <name> [--runtime claude|codex|hermes]
                         [--resume-id <id>] [--timeout <sec>]
                                         Register this session with the relay and block
                                         until it is woken (exit 0), or the wait lapses
-                                        (exit 2). Pass --resume-id so the relay can
-                                        still reach the session headlessly once this
-                                        process is gone
+                                        (exit 2). Without --resume-id the session is
+                                        asked to identify itself from its runtime's
+                                        environment ($CLAUDE_CODE_SESSION_ID for Claude
+                                        Code); failing that the relay searches the
+                                        runtime's own session state when a message
+                                        arrives. A session it cannot identify is
+                                        reported pending, never guessed at
 
 Connect flow: in BayChat, open the agent -> Connect -> copy the pairing code,
 then run \`baychat pair <code>\`. Pairing rotates the agent token; use a

package/dist/relay/adapters.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_RUNTIMES = void 0;
 exports.buildWakePrompt = buildWakePrompt;
 exports.adapterFor = adapterFor;
 exports.isKnownRuntime = isKnownRuntime;
 exports.runHeadless = runHeadless;
 const child_process_1 = require("child_process");
+const resume_1 = require("./resume");
 /** How long a headless turn may run before the relay gives up on it. */
 const HEADLESS_TIMEOUT_MS = 10 * 60_000;
 /**
@@ -40,6 +42,9 @@ const claudeAdapter = {
         }
         return { ok: true };
     },
+    discoverResume(target, opts) {
+        return (0, resume_1.discoverClaudeResume)(target.name, opts);
+    },
     headlessCommand(target, prompt) {
         return { file: "claude", args: ["-p", prompt, "--resume", target.resumeId] };
     },
@@ -55,10 +60,47 @@ const codexAdapter = {
         }
         return { ok: true };
     },
+    discoverResume(target, opts) {
+        return (0, resume_1.discoverCodexResume)(target.name, opts);
+    },
     headlessCommand(target, prompt) {
         return { file: "codex", args: ["exec", "resume", target.resumeId, prompt] };
     },
 };
+/**
+ * Cursor can be woken, and cannot be resumed. Both halves matter.
+ *
+ * A Cursor session that launched `baychat relay attach` in the background is
+ * woken exactly like Claude Code or Codex: the attach socket does not care which
+ * runtime wrote to it, and the exit of the attach process is what re-invokes the
+ * session. That covers the ordinary case — a developer with Cursor open — which
+ * is why refusing to let Cursor attach at all was the wrong reading of "Cursor
+ * cannot be resumed headlessly".
+ *
+ * What Cursor has no equivalent of is `claude -p --resume <id>`: no documented
+ * entry point continues one specific Cursor conversation from outside it. So a
+ * wake that finds it detached is `pending`, with the reason — never a fresh
+ * process answering a room it has no memory of.
+ */
+const cursorAdapter = {
+    runtime: "cursor",
+    canResume() {
+        return {
+            ok: false,
+            reason: "Cursor has no headless resume — it is reachable only while `baychat relay attach` is running, so attach must be re-armed after every wake",
+        };
+    },
+    async discoverResume() {
+        // Nothing to discover: Cursor writes no on-disk session state this package
+        // can identify a conversation from, and a search that cannot succeed is
+        // only a way to produce a confident-looking wrong answer.
+        return { ok: false, reason: "Cursor records no resumable session id on this machine" };
+    },
+    headlessCommand() {
+        // Unreachable: the daemon consults canResume first and reports pending.
+        throw new Error("cursor has no headless command");
+    },
+};
 /**
  * Hermes is self-hosted and already receives messages through its own agent
  * webhook — there is no local process for the relay to resume. When Hermes is
@@ -74,6 +116,11 @@ const hermesAdapter = {
             reason: "Hermes is self-hosted and has no local headless resume — it must attach to the relay, or receive the message over its own agent webhook",
         };
     },
+    async discoverResume() {
+        // Nothing to discover: Hermes runs somewhere else and leaves no local
+        // transcript. Searching would only produce a confident-looking wrong answer.
+        return { ok: false, reason: "Hermes keeps no local session state on this machine" };
+    },
     headlessCommand() {
         // Unreachable: the daemon consults canResume first and reports pending.
         throw new Error("hermes has no headless command");
@@ -82,13 +129,21 @@ const hermesAdapter = {
 const ADAPTERS = {
     claude: claudeAdapter,
     codex: codexAdapter,
+    cursor: cursorAdapter,
     hermes: hermesAdapter,
 };
 function adapterFor(runtime) {
     return ADAPTERS[runtime];
 }
+/** Every value `relay attach --runtime` accepts, for the error that lists them. */
+exports.KNOWN_RUNTIMES = Object.keys(ADAPTERS);
+/**
+ * Derived from the adapter table rather than restated, because a second copy of
+ * this list is exactly how Cursor came to be told to attach with a value the
+ * relay rejected. Having an adapter IS being attachable.
+ */
 function isKnownRuntime(value) {
-    return value === "claude" || value === "codex" || value === "hermes";
+    return Object.prototype.hasOwnProperty.call(ADAPTERS, value);
 }
 /**
  * Run a headless turn to completion.

package/dist/relay/commands.js

@@ -46,6 +46,7 @@ const path = __importStar(require("path"));
 const util_1 = require("util");
 const adapters_1 = require("./adapters");
 const daemon_1 = require("./daemon");
+const resume_1 = require("./resume");
 const socket_1 = require("./socket");
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 const UNIT_NAME = "baychat-relay.service";
@@ -202,6 +203,7 @@ async function cmdRelayStatus() {
     for (const s of status.sessions) {
         const state = s.attached ? "attached" : s.resumeId ? "detached (headless resume ready)" : "detached (no resume id)";
         console.log(`  ${s.name}  [${s.runtime}]  ${state}`);
+        console.log(`     ${resumeLabel(s)}`);
     }
     // Pending is the point of the whole command: these are messages that reached
     // this machine and that nobody answered.
@@ -215,6 +217,23 @@ async function cmdRelayStatus() {
     }
     return 0;
 }
+/**
+ * Where this session's resume id came from, in one line.
+ *
+ * "We can wake this headlessly" is a claim about identity, and a human has to
+ * be able to judge it: a session that named itself out of its own environment
+ * is a different level of confidence from one the relay matched to a transcript
+ * on disk. Printing only the id would hide that difference, and printing
+ * nothing would hide the whole question — which is how two production sessions
+ * sat detached and unwakeable without it being anyone's obvious problem.
+ */
+function resumeLabel(s) {
+    if (!s.resumeId) {
+        return "resume: none — a wake while detached is reported DELIVERY PENDING, not delivered";
+    }
+    const provenance = s.resumeEvidence ?? s.resumeSource ?? "origin not recorded (registered before provenance existed)";
+    return `resume: ${s.resumeId} — ${provenance}`;
+}
 /**
  * Which event source is live, in one line.
  *
@@ -260,10 +279,11 @@ async function cmdRelayStop() {
  */
 async function cmdRelayAttach(opts) {
     if (!(0, adapters_1.isKnownRuntime)(opts.runtime)) {
-        console.log(`unknown runtime "${opts.runtime}" — expected claude, codex, or hermes`);
+        console.log(`unknown runtime "${opts.runtime}" — expected one of: ${adapters_1.KNOWN_RUNTIMES.join(", ")}`);
         return 1;
     }
     const runtime = opts.runtime;
+    const resume = await resolveAttachResumeId(runtime, opts.resumeId, opts.discovery);
     let sock;
     try {
         sock = await connectOrFail();
@@ -320,8 +340,41 @@ async function cmdRelayAttach(opts) {
             type: "attach",
             session: opts.session,
             runtime,
-            resumeId: opts.resumeId,
+            resumeId: resume.ok ? resume.resumeId : undefined,
+            resumeSource: resume.ok ? resume.source : undefined,
+            resumeEvidence: resume.ok ? resume.evidence : undefined,
+            resumeCwd: resume.ok ? resume.cwd : undefined,
             cwd: process.cwd(),
         });
     });
 }
+/**
+ * Decide what resume id this attach registers, and say so out loud.
+ *
+ * An explicit `--resume-id` always wins: a human (or a skill that knows the
+ * runtime's own variable) said this is the session, and second-guessing them
+ * would break the escape hatch. Otherwise the session is asked to identify
+ * itself out of its runtime's environment — the only method that cannot name
+ * somebody else's session, because it runs inside this one.
+ *
+ * Both outcomes print. A silent "no resume id" is how a session ends up
+ * unwakeable without anyone noticing until a message goes unanswered.
+ */
+async function resolveAttachResumeId(runtime, explicit, discovery) {
+    const given = explicit?.trim();
+    if (given) {
+        // Not validated: `--resume-id` is the escape hatch, and a runtime whose ids
+        // are not uuids must still be able to use it.
+        console.log(`Resume id: ${given} (passed with --resume-id)`);
+        return { ok: true, resumeId: given, source: "flag", evidence: "passed with --resume-id" };
+    }
+    const found = await (0, resume_1.resumeIdFromSessionEnv)(runtime, discovery);
+    if (found.ok) {
+        console.log(`Resume id: ${found.resumeId} (${found.evidence})`);
+        return found;
+    }
+    console.log(`No resume id: ${found.reason}.`);
+    console.log("  The relay will search this runtime's own session state when a message arrives while you are detached,");
+    console.log("  and report DELIVERY PENDING rather than resume a session it cannot identify.");
+    return found;
+}

package/dist/relay/daemon.js

@@ -42,14 +42,23 @@ const queue_1 = require("./queue");
 const registry_1 = require("./registry");
 const socket_1 = require("./socket");
 const transport_1 = require("./transport");
+const watermarks_1 = require("./watermarks");
+/**
+ * How long a failed resume-id discovery is believed before it is retried.
+ *
+ * A session whose runtime left no identifying trace stays undiscoverable, so
+ * re-scanning every transcript on the box per message would make an
+ * unanswerable delivery expensive as well as pending.
+ */
+const DISCOVERY_INTERVAL_MS = 10 * 60_000;
 class RelayDaemon {
     registry = new registry_1.SessionRegistry();
     queue;
     abort = new AbortController();
     /** Live attach sockets by session name. */
     attached = new Map();
-    /** Per-conversation delivery watermark — the 409 catch-up baseline. */
-    watermarks = new Map();
+    /** Per (session, conversation) delivery positions — the 409 catch-up baseline. */
+    watermarks = new watermarks_1.Watermarks();
     pending = [];
     server;
     startedAt = new Date().toISOString();
@@ -62,9 +71,15 @@ class RelayDaemon {
     transportDetail = "starting";
     /** Live session names from the last poll, for pruning and for `relay status`. */
     liveSessions = [];
+    /** Why discovery last refused, per session, and when — throttles the rescan. */
+    discoveryReasons = new Map();
+    discovery;
+    spawnHeadless;
     log;
     constructor(opts = {}) {
         this.log = opts.log ?? ((line) => console.log(`[relay] ${line}`));
+        this.discovery = opts.discovery ?? {};
+        this.spawnHeadless = opts.spawnHeadless ?? adapters_1.runHeadless;
         this.queue = new queue_1.SessionQueue((session, batch) => this.deliver(session, batch), (session, err) => {
             this.lastError = `delivery failed for ${session}: ${errText(err)}`;
             this.log(this.lastError);
@@ -119,6 +134,9 @@ class RelayDaemon {
             },
             onSessions: (names) => {
                 this.liveSessions = names;
+                // A recovery must cover every live session, including one this relay has
+                // never had to route an event to — skipping it re-baselines it at "now".
+                this.watermarks.noteLiveSessions(names);
                 const dropped = this.registry.pruneToLive(names);
                 for (const name of dropped)
                     this.log(`session ended server-side, dropped: ${name}`);
@@ -140,7 +158,7 @@ class RelayDaemon {
         });
     }
     /**
-     * Route one event and record the conversation watermark.
+     * Route one event and record this session's position in that conversation.
      *
      * Routing is the SERVER's answer (`sessionName`), not a local guess: the
      * device poll already knows which session agent each event was queued for.
@@ -150,9 +168,10 @@ class RelayDaemon {
      */
     onEvent(event) {
         const { conversationId, sessionName, message } = event;
-        const prior = this.watermarks.get(conversationId);
-        if (!prior || message.createdAt > prior)
-            this.watermarks.set(conversationId, message.createdAt);
+        // Per SESSION, not per conversation: a sibling in the same room that was
+        // behind must not have its recovery window truncated by a session that was
+        // ahead. An event with no session still registers the room — see Watermarks.
+        this.watermarks.record(sessionName, conversationId, message.createdAt);
         if (!sessionName) {
             this.log(`event ${message.id} carries no session (renamed or ended mid-poll) — ignoring`);
             return;
@@ -183,15 +202,25 @@ class RelayDaemon {
             return;
         }
         const adapter = (0, adapters_1.adapterFor)(target.runtime);
-        const check = adapter.canResume(target);
+        // A target with no resume id is the unbounded failure this whole path
+        // exists to close: without one, `canResume` says no and the message waits
+        // for a human. Ask the runtime's own on-disk state who this session is
+        // before accepting that answer.
+        const resolved = await this.resolveResume(target);
+        const check = adapter.canResume(resolved);
         if (!check.ok) {
             // The honest outcome: it reached this box, and nothing answered it.
-            this.record({ kind: "pending", session, reason: check.reason ?? "cannot resume" }, session, batch);
+            const why = this.discoveryReasons.get(session)?.reason;
+            const reason = why ? `${check.reason ?? "cannot resume"}; discovery: ${why}` : (check.reason ?? "cannot resume");
+            this.record({ kind: "pending", session, reason }, session, batch);
             return;
         }
         const prompt = (0, adapters_1.buildWakePrompt)(session, batch[0].conversationId, batch);
-        const { file, args } = adapter.headlessCommand(target, prompt);
-        const { exitCode, stderr } = await (0, adapters_1.runHeadless)(file, args, { cwd: target.cwd });
+        const { file, args } = adapter.headlessCommand(resolved, prompt);
+        // The session's own directory when we know it: `cwd` is only where the
+        // attach process ran, and `codex exec` refuses to start outside a trusted
+        // directory at all.
+        const { exitCode, stderr } = await this.spawnHeadless(file, args, { cwd: resolved.resumeCwd ?? resolved.cwd });
         if (exitCode !== 0) {
             // A non-zero headless turn did not necessarily reply. Recording it as
             // delivered would claim an answer we cannot evidence.
@@ -200,6 +229,43 @@ class RelayDaemon {
         }
         this.record({ kind: "woken", via: "headless", session, exitCode }, session, batch);
     }
+    /**
+     * Fill in a missing resume id from the runtime's on-disk state, at most once
+     * every `DISCOVERY_INTERVAL_MS` per session.
+     *
+     * Throttled because a refusal is the common steady state — a session whose
+     * runtime left no trace will never become discoverable — and re-reading every
+     * transcript on the box for each arriving message would make an unanswerable
+     * delivery expensive as well as pending.
+     *
+     * A discovered id is persisted with its provenance, so the search happens
+     * once per session rather than once per wake, and `relay status` can show a
+     * human where the id came from.
+     */
+    async resolveResume(target) {
+        if (target.resumeId)
+            return target;
+        const last = this.discoveryReasons.get(target.name);
+        if (last && Date.now() - last.at < DISCOVERY_INTERVAL_MS)
+            return target;
+        const result = await (0, adapters_1.adapterFor)(target.runtime).discoverResume(target, this.discovery);
+        if (!result.ok) {
+            this.discoveryReasons.set(target.name, { at: Date.now(), reason: result.reason });
+            this.log(`no resume id for ${target.name}: ${result.reason}`);
+            return target;
+        }
+        this.discoveryReasons.delete(target.name);
+        const updated = this.registry.upsert({
+            name: target.name,
+            runtime: target.runtime,
+            resumeId: result.resumeId,
+            resumeSource: result.source,
+            resumeEvidence: result.evidence,
+            resumeCwd: result.cwd,
+        });
+        this.log(`resume id for ${target.name}: ${result.resumeId} (${result.evidence})`);
+        return updated;
+    }
     record(outcome, session, batch) {
         if (outcome.kind === "woken") {
             this.delivered += batch.length;
@@ -233,8 +299,15 @@ class RelayDaemon {
                     name: frame.session,
                     runtime: frame.runtime,
                     resumeId: frame.resumeId,
+                    resumeSource: frame.resumeSource,
+                    resumeEvidence: frame.resumeEvidence,
+                    resumeCwd: frame.resumeCwd,
                     cwd: frame.cwd,
                 });
+                // A session that names itself supersedes anything discovery guessed
+                // for it, so drop the throttle and let the next wake use the new id.
+                if (frame.resumeId)
+                    this.discoveryReasons.delete(frame.session);
                 this.attached.set(frame.session, sock);
                 this.registry.setAttached(frame.session, true);
                 (0, socket_1.writeFrame)(sock, { type: "attached", session: frame.session });