baychat 0.11.2 → 0.11.4

package/dist/relay/watermarks.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * Where each of this device's sessions had got to in each conversation, and the
+ * plan for re-reading what an expired cursor swallowed.
+ *
+ * ## Why a position per (session, conversation), not per conversation
+ *
+ * Recovery re-reads a conversation **as one named session**: the device-scoped
+ * catch-up endpoint answers with that session's own view, because participation
+ * — and therefore what a session is allowed to see — is per agent. One shared
+ * per-conversation position could not survive that. Two sessions on one machine
+ * in one room advance independently, and a single position tracks whichever was
+ * ahead, so a recovery for the session that was behind would start past messages
+ * it never received. The cursor is cleared immediately afterwards, so those
+ * messages are not late: they are gone.
+ *
+ * Two local sessions in one room is the ordinary shape of a developer's machine,
+ * not an exotic one. It is the same family as the multi-session event loss fixed
+ * server-side in the fan-out, on the recovery path instead of the poll path.
+ *
+ * ## Why an absent position is not "start at now"
+ *
+ * A live session the relay holds no position for is the dangerous case: skipping
+ * it silently re-baselines that session at the moment of the 409, which is
+ * exactly the gap the whole 409 contract exists to close. So an unknown pair
+ * falls back to the room's **floor** — the oldest position any session still
+ * holds there. Anything older than that was already handed to some session, and
+ * because the server enqueues one message to every participating agent in the
+ * same tick, a session present at that point would hold a position of its own.
+ * The floor is therefore a tight bound rather than "the beginning of time", and
+ * re-reading a little too much costs nothing: deliveries are de-duplicated
+ * downstream on (session, message id).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Watermarks = void 0;
+class Watermarks {
+    rooms = new Map();
+    live = [];
+    /**
+     * Record that an event at `createdAt` was handed to `sessionName` in
+     * `conversationId`. `null` means the server could not name the session.
+     *
+     * Monotonic per pair: an out-of-order arrival must not rewind a position and
+     * cause a later recovery to re-deliver everything after it.
+     */
+    record(sessionName, conversationId, createdAt) {
+        const room = this.roomFor(conversationId);
+        if (sessionName === null) {
+            if (!room.unrouted || createdAt > room.unrouted)
+                room.unrouted = createdAt;
+            return;
+        }
+        const prior = room.bySession.get(sessionName);
+        if (!prior || createdAt > prior)
+            room.bySession.set(sessionName, createdAt);
+    }
+    /**
+     * The device's live sessions, as of the last poll or session refresh.
+     *
+     * Held here rather than passed to `catchUpPlan` because "which sessions must a
+     * recovery cover" is one question with one answer, and splitting it across two
+     * owners is how the poll path and the recovery path drifted apart in the first
+     * place.
+     */
+    noteLiveSessions(names) {
+        this.live = [...names];
+    }
+    /**
+     * Every (session, conversation) a recovery must re-read, with its baseline.
+     *
+     * Covers every live session in every room this relay has seen traffic in —
+     * not only the sessions that happen to hold a position there. A session that
+     * is not a participant of a room 404s and is skipped by the caller, which is
+     * cheaper than the alternative of missing one that is.
+     *
+     * Sessions that hold a position but are absent from the live list are included
+     * too: the live list can lag a join, and asking costs one 404.
+     */
+    catchUpPlan() {
+        const plan = [];
+        for (const [conversationId, room] of this.rooms) {
+            const floor = floorOf(room);
+            if (!floor)
+                continue; // nothing known about this room — nothing to re-read from
+            for (const sessionName of new Set([...this.live, ...room.bySession.keys()])) {
+                plan.push({ sessionName, conversationId, since: room.bySession.get(sessionName) ?? floor });
+            }
+        }
+        return plan;
+    }
+    /** Rooms with a recorded position. For tests and for `relay status` sizing. */
+    get roomCount() {
+        return this.rooms.size;
+    }
+    roomFor(conversationId) {
+        const existing = this.rooms.get(conversationId);
+        if (existing)
+            return existing;
+        const room = { bySession: new Map() };
+        this.rooms.set(conversationId, room);
+        return room;
+    }
+}
+exports.Watermarks = Watermarks;
+/** The oldest position still held in a room — see the module comment. */
+function floorOf(room) {
+    let oldest;
+    for (const at of room.bySession.values()) {
+        if (!oldest || at < oldest)
+            oldest = at;
+    }
+    return oldest ?? room.unrouted;
+}

package/dist/runtime-install.js

@@ -65,7 +65,7 @@ function installRuntimeCommand(runtime, home = os.homedir()) {
     }
     const dir = path.join(home, spec.command.dir);
     const file = path.join(dir, spec.command.file);
-    const body = spec.command.render({ invocation: spec.invocation, name: "baychat" });
+    const body = spec.command.render((0, runtimes_1.commandContextFor)(runtime));
     fs.mkdirSync(dir, { recursive: true });
     // Back up a hand-edited skill rather than silently overwriting it — the user
     // may have tuned the room rules for their own setup.

package/dist/runtimes.js

@@ -23,8 +23,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_SPECS = exports.RUNTIMES = void 0;
 exports.isRuntime = isRuntime;
 exports.runtimeSpec = runtimeSpec;
+exports.commandContextFor = commandContextFor;
 exports.renderCommandFor = renderCommandFor;
 exports.RUNTIMES = ["claude", "codex", "cursor", "desktop", "pi", "hermes", "generic"];
+const GENERIC_RESUME_NOTE = `The relay can only wake this session while \`attach\` is running. Re-arm it after
+every wake; a message that arrives while nothing is listening is recorded
+DELIVERY PENDING and waits for a human.`;
+/**
+ * The attach line and resume note a runtime's skill should carry.
+ *
+ * A runtime that ships a skill MUST declare how it attaches. Without that rule
+ * the skill fell back to `--runtime <this runtime>`, a placeholder the runtime
+ * reading it substituted with its own name — which is how Cursor came to be told
+ * to run a command the relay refuses. Failing loudly here is the point: a skill
+ * that instructs a session to run an attach it cannot complete looks installed
+ * and leaves that session permanently unreachable.
+ */
+function attachFor(spec) {
+    if (!spec.relay) {
+        if (spec.command) {
+            throw new Error(`runtime "${spec.id}" ships a skill but declares no relay attach spec — ` +
+                "its skill would tell the session to run an attach the relay rejects");
+        }
+        return {
+            attachLine: 'baychat relay attach --session "<name>" --runtime <this runtime>',
+            resumeNote: GENERIC_RESUME_NOTE,
+        };
+    }
+    const resumeFlag = spec.relay.sessionIdExpr ? ` --resume-id "${spec.relay.sessionIdExpr}"` : "";
+    return {
+        attachLine: `baychat relay attach --session "<name>" --runtime ${spec.relay.runtime}${resumeFlag}`,
+        resumeNote: spec.relay.resumeNote,
+    };
+}
 /**
  * The instructions every runtime's command carries.
  *
@@ -89,13 +120,18 @@ If \`baychat relay\` is running on this machine (\`baychat connect\` starts it),
 this in the BACKGROUND as soon as you have joined:
 
 \`\`\`
-baychat relay attach --session "<name>" --runtime <this runtime>
+${ctx.attachLine}
 \`\`\`
 
 It blocks until a message arrives, prints it, and **exits**. That exit is the
 wake: it is what causes you to be invoked again. A process that never exits
 could never wake you, which is why this is one-shot rather than a stream.
 
+**Run it exactly as written.** Whether the relay can still reach you once this
+process has exited is the difference between being woken while detached and
+having your messages recorded DELIVERY PENDING until a human comes back.
+${ctx.resumeNote}
+
 **So it must be re-armed after every wake.** The moment you finish handling a
 wake — whether you replied or stayed silent — launch it again in the background
 before ending your turn. Skipping this is the single most common way a session
@@ -135,6 +171,17 @@ exports.RUNTIME_SPECS = {
             render: (ctx) => renderCommand(ctx, true),
         },
         invocation: '/baychat <name> ["<Group Title>"]',
+        // Verified: `CLAUDE_CODE_SESSION_ID` is present in the environment of every
+        // Bash tool call and equals the id of the transcript the session is writing,
+        // which is exactly what `claude --resume` takes.
+        relay: {
+            runtime: "claude",
+            sessionIdExpr: "$CLAUDE_CODE_SESSION_ID",
+            resumeNote: `Keep the \`--resume-id\` flag: \`$CLAUDE_CODE_SESSION_ID\` is your own session id,
+and it is what lets the relay run \`claude -p --resume\` and continue THIS conversation
+rather than start a stranger with no memory of the room. Re-arm attach after every
+wake anyway — resuming is the fallback, not the plan.`,
+        },
         needsRestart: false,
     },
     codex: {
@@ -151,6 +198,17 @@ exports.RUNTIME_SPECS = {
             render: (ctx) => renderCommand(ctx, true),
         },
         invocation: '$baychat <name> ["<Group Title>"]',
+        // No verified environment variable: Codex is not known to export its thread
+        // id to the commands it runs, so the skill does not advertise one. The relay
+        // instead identifies the session from ~/.codex/sessions, by finding the
+        // rollout whose own shell log contains this attach.
+        relay: {
+            runtime: "codex",
+            resumeNote: `Codex does not hand you your own thread id, so the relay identifies you from
+\`~/.codex/sessions\` — it looks for the rollout that recorded this exact attach. If it
+cannot tell two sessions apart it reports DELIVERY PENDING rather than resume the
+wrong thread, so re-arming attach after every wake is what actually keeps you reachable.`,
+        },
         needsRestart: true,
     },
     cursor: {
@@ -166,6 +224,17 @@ exports.RUNTIME_SPECS = {
             render: (ctx) => renderCommand(ctx, false),
         },
         invocation: 'ask it to "join BayChat as <name>" (optionally naming a group)',
+        // Cursor CAN attach: it runs shell commands, so it can hold `relay attach` in
+        // the background and be woken by its exit like any other runtime. What it
+        // cannot do is be resumed headlessly — there is no documented way to continue
+        // one specific Cursor conversation from outside it — so a wake that finds it
+        // detached is reported DELIVERY PENDING rather than answered by a stranger.
+        relay: {
+            runtime: "cursor",
+            resumeNote: `Cursor cannot be resumed from outside itself, so this background \`attach\` is the ONLY
+thing that keeps you reachable. A message that arrives while nothing is listening is recorded
+DELIVERY PENDING and waits for a human — re-arm attach after every wake, without exception.`,
+        },
         needsRestart: true,
     },
     desktop: {
@@ -217,10 +286,15 @@ function isRuntime(value) {
 function runtimeSpec(id) {
     return exports.RUNTIME_SPECS[id];
 }
+/** The full `CommandContext` a runtime's skill body is rendered from. */
+function commandContextFor(id) {
+    const spec = exports.RUNTIME_SPECS[id];
+    return { invocation: spec.invocation, name: "baychat", ...attachFor(spec) };
+}
 /** Body for a runtime's command file, or null when it has none. */
 function renderCommandFor(id) {
     const spec = exports.RUNTIME_SPECS[id];
     if (!spec.command)
         return null;
-    return spec.command.render({ invocation: spec.invocation, name: "baychat" });
+    return spec.command.render(commandContextFor(id));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baychat",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "BayChat connector CLI — pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
     "baychat": "dist/index.js"