relay-companion 0.1.82 → 0.1.84

package/bin/relay.js

@@ -492,6 +492,11 @@ async function main() {
       return cmdPill(flags);
     case "mcp":
       return runMcpServer({ mode: modeFromFlags(flags) });
+    case "channel":
+      // EXPERIMENTAL: Claude Code channel server (see src/channel-server.js).
+      // Register in .mcp.json and start the session with
+      //   claude --dangerously-load-development-channels server:relay
+      return import("../src/channel-server.js").then(({ runChannelServer }) => runChannelServer());
     case "update":
     case "self-update":
       return runUpdateOnce({ mode: modeFromFlags(flags) }).then(() => {});

package/overlay/inbox.html

@@ -3097,10 +3097,16 @@
     }, ms));
   }
   if (window.relay.onInjected) window.relay.onInjected((id, info) => {
+    if (info.channel) {
+      // Wake path: a channel event starts a real turn even in an idle chat.
+      if (injectedNoteTimers.has(id)) { clearTimeout(injectedNoteTimers.get(id)); injectedNoteTimers.delete(id); }
+      setRowNote(id, "Pushed to your current Claude chat — waking it now…", "ok");
+      return;
+    }
     if (info.awaitingTurn) {
       // Persistent until delivery / the auto-fresh hop — never a silent limbo.
       if (injectedNoteTimers.has(id)) { clearTimeout(injectedNoteTimers.get(id)); injectedNoteTimers.delete(id); }
-      setRowNote(id, "Handed to your current Claude chat…", "ok");
+      setRowNote(id, "Handed to your current Claude chat — lands when it next takes a turn. If it\u2019s idle: type anything there, or use Open in New Chat for instant.", "ok");
       return;
     }
     const hostName = info.host === "codex" ? "Codex" : "Claude";

package/overlay/main.cjs

@@ -310,6 +310,22 @@ function loadSentStager() {
   return sentStagerPromise;
 }
 
+// Relay channel deps (ESM, lazy): the wake path for "Open in current chat".
+// A session started with the relay channel takes a REAL turn on a pushed
+// event — the only supported way to wake an idle chat (live-proven 2026-08-05:
+// idle terminal session answered a queued event with zero keystrokes).
+let channelDepsPromise = null;
+function loadChannelDeps() {
+  if (!channelDepsPromise) {
+    const url = pathToFileURL(path.join(__dirname, "..", "src", "channel-server.js")).href;
+    channelDepsPromise = import(url).catch((error) => {
+      channelDepsPromise = null;
+      throw error;
+    });
+  }
+  return channelDepsPromise;
+}
+
 // Codex "Open in current chat" deps (ESM, loaded lazily like the modules
 // above): codex-inject resolves the current thread / stages the heartbeat
 // automation, codex-desktop drives the live bridge submit. The tier ordering
@@ -1897,18 +1913,20 @@ async function openPacket(packetId, { sent = false, fresh = false } = {}) {
 // injection for an idle session sat invisible for minutes and the click read as
 // completely dead; a waiting state that never lies beats a success toast.
 //
-// The GRACE WINDOW closes the remaining gap. Nothing outside a session can make
-// it take a turn (verified against the platform docs: deep links only pre-fill
-// NEW sessions; no external submit API exists), so an idle chat cannot be woken
-// — but the user must still get the relay QUICKLY. A busy chat ingests at a
-// tool boundary within seconds; if the grace window passes unconsumed, the
-// target is idle: reclaim the injection (same rename-first consume-once
-// discipline as the hook, so a racing delivery always wins) and open the relay
-// in a fresh chat instead. Every click produces a visible result in seconds.
+// Nothing outside a session can make it take a turn (verified against the
+// platform docs: deep links only pre-fill NEW sessions; no external submit API
+// exists), so an idle chat cannot be woken — the honest waiting/delivered
+// states are the truth until the Relay channel plugin (the platform's supported
+// push-into-a-running-session mechanism) lands. The 0.1.82 grace hop — reclaim
+// after 6s and open a fresh chat — is now OFF by default: the same-evening
+// field verdict was that silently converting "current chat" into "new chat"
+// betrays the button. The user chose current; Open in New Chat sits one row
+// below for when they want instant. RELAY_CURRENT_CHAT_GRACE_MS > 0 re-enables
+// the hop for anyone who prefers motion over fidelity.
 const injectionWatchers = new Map(); // packetId -> interval
 const AUTO_FRESH_GRACE_MS = (() => {
   const raw = Number(process.env.RELAY_CURRENT_CHAT_GRACE_MS);
-  return Number.isFinite(raw) && raw >= 0 ? raw : 6000; // 0 disables auto-fresh
+  return Number.isFinite(raw) && raw > 0 ? raw : 0; // 0 (default): never hop
 })();
 function reclaimInjection(stagedPath) {
   const claimed = `${stagedPath}.${process.pid}.${Date.now()}.autofresh`;
@@ -1922,7 +1940,7 @@ function reclaimInjection(stagedPath) {
   } catch {}
   return true;
 }
-function watchInjectionDelivery(packetId, stagedPath, { timeoutMs = 10 * 60 * 1000, intervalMs = 500, autoFreshMs = AUTO_FRESH_GRACE_MS, onAutoFresh = null } = {}) {
+function watchInjectionDelivery(packetId, stagedPath, { timeoutMs = 10 * 60 * 1000, intervalMs = 500, autoFreshMs = AUTO_FRESH_GRACE_MS, onAutoFresh = null, onTimeout = null } = {}) {
   if (!stagedPath) return;
   const existing = injectionWatchers.get(packetId);
   if (existing) clearInterval(existing); // newest click owns the watch
@@ -1954,11 +1972,13 @@ function watchInjectionDelivery(packetId, stagedPath, { timeoutMs = 10 * 60 * 10
       onAutoFresh();
       return;
     }
-    // A restaged/overwritten click or a very long idle: stop polling quietly.
-    // The waiting note remains accurate — the injection is still pending.
+    // A restaged/overwritten click or a very long idle: stop polling quietly
+    // (the waiting note remains accurate — the injection is still pending),
+    // unless the caller owns the timeout (channel wake falls back to staging).
     if (Date.now() - startedAt > timeoutMs) {
       clearInterval(timer);
       injectionWatchers.delete(packetId);
+      if (onTimeout) onTimeout();
     }
   }, intervalMs);
   if (typeof timer.unref === "function") timer.unref();
@@ -2090,6 +2110,46 @@ async function openPacketInCurrent(packetId) {
         },
       });
     };
+    // WAKE TIER (live-proven): when exactly one relay-channel session is alive,
+    // push the instruction as a channel event — the session takes a REAL turn on
+    // it even when idle, which hook staging can never cause. One instance only:
+    // queue events are claimed first-rename-wins, so with several live channel
+    // sessions the event could wake a chat the user is not looking at; the
+    // session-targeted hook path stays correct for that world. If the claimed
+    // event somehow never gets picked up (server died between heartbeats), the
+    // watcher falls through to hook staging — the click never dead-ends.
+    const tryChannelWake = () =>
+      loadChannelDeps().then((channel) => {
+        if (channel.countLiveChannelInstances(RELAY_HOME) !== 1) return false;
+        const instruction = claudeInject.buildInjectionInstruction({
+          relayId: packetId,
+          senderName: row.senderName || "",
+          title: row.title || row.displayTitle || "",
+          ...threadInfoFor(row),
+        });
+        const eventFile = channel.enqueueChannelEvent(RELAY_HOME, {
+          content: instruction,
+          meta: { relayId: packetId, source: "relay-pill-open-in-current" },
+        });
+        console.error(`[overlay] openInCurrent ${packetId}: pushed via relay channel (wake path)`);
+        if (target.source === "desktop") activateHost("claude", bundle);
+        confirmInjected("claude", { awaitingTurn: true, channel: true });
+        finish();
+        watchInjectionDelivery(packetId, eventFile, {
+          autoFreshMs: 0,
+          timeoutMs: 15_000,
+          onTimeout: () => {
+            // Presence lied (instance died between heartbeats): reclaim the
+            // event and hand the click to the hook path so it still lands.
+            console.error(`[overlay] openInCurrent ${packetId}: channel event unclaimed after 15s; falling back to hook staging`);
+            try {
+              fs.rmSync(eventFile, { force: true });
+            } catch {}
+            stageNow();
+          },
+        });
+        return true;
+      });
     // NOTHING but the `relay claude-hook` runtime registered in ~/.claude/settings.json
     // ever reads the staged file. Where setup never wrote those hooks (Windows installs
     // where the `claude` CLI isn't on PATH — see src/install.js runSetupInstall) staging
@@ -2098,7 +2158,16 @@ async function openPacketInCurrent(packetId) {
     // and finish the click twice.
     loadClaudeHooksModule().then(
       (install) => {
-        if (claudeHooksInstalled(install)) return stageNow();
+        if (claudeHooksInstalled(install)) {
+          return tryChannelWake()
+            .catch((error) => {
+              console.error("[overlay] channel wake unavailable:", error && error.message);
+              return false;
+            })
+            .then((woke) => {
+              if (!woke) stageNow();
+            });
+        }
         // Repair for FUTURE sessions — but a Claude session that is already running
         // loaded its hooks at startup and will never consume a file staged now, so this
         // click has to take the fresh-open path, the only one that actually shows the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relay-companion",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "description": "Relay companion for ordinary messages, with dormant coordination features available only by explicit opt-in.",
   "type": "module",
   "bin": {

package/src/channel-server.js

@@ -0,0 +1,165 @@
+// `relay channel` — EXPERIMENTAL Claude Code channel server.
+//
+// This is the real fix for "Open in Current Chat must wake an idle chat".
+// Hook-file injection (claude-inject.cjs) can only deliver when the session
+// takes a turn on its own; a channel event is the platform's supported way to
+// PUSH into a running session — an idle session takes a turn on it (docs:
+// channels-reference, notifications/claude/channel). Sessions opt in at start:
+//   claude --channels server:relay            (registered in .mcp.json), or
+//   claude --dangerously-load-development-channels server:relay   (dev)
+// Whether Claude Code Desktop threads can enable channels is still an open
+// platform question; terminal sessions work today.
+//
+// Protocol with the pill/daemon (filesystem, same discipline as claude-inject):
+//   RELAY_HOME/channel-queue/<name>.json — one event per file:
+//     { content: string, meta?: object, createdAt: ISO }
+//   Consume-once via rename-first, so N live channel instances deliver an
+//   event exactly once fleet-wide (first rename wins; losers stay silent).
+//   RELAY_HOME/channel-instances/<pid>.json — presence heartbeat so the pill
+//   knows a wake-capable session exists before preferring this path.
+//
+// The event content is an INSTRUCTION built by the same sanitized builders as
+// hook injection (relay body is never inlined; the model fetches via MCP tools).
+
+import fs from "node:fs";
+import path from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { storeDir } from "./host-paths.js";
+
+const QUEUE_DIR = "channel-queue";
+const PRESENCE_DIR = "channel-instances";
+const POLL_MS = 700; // fs.watch is unreliable across atomic renames; poll cheaply
+const PRESENCE_MS = 15_000;
+
+export function channelQueueDir(homeDir = storeDir()) {
+  return path.join(homeDir, QUEUE_DIR);
+}
+
+export function channelPresenceDir(homeDir = storeDir()) {
+  return path.join(homeDir, PRESENCE_DIR);
+}
+
+// Drop one event for whichever live channel session claims it first.
+export function enqueueChannelEvent(homeDir, { content, meta = {} } = {}) {
+  const text = String(content || "").trim();
+  if (!text) throw new Error("enqueueChannelEvent requires content");
+  const dir = channelQueueDir(homeDir);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `evt-${Date.now()}-${process.pid}-${Math.floor(Math.random() * 1e6)}.json`);
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify({ content: text, meta, createdAt: new Date().toISOString() })}\n`, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+// How many channel instances heartbeated recently. The pill prefers the wake
+// path only when EXACTLY ONE live instance exists: queue events are claimed by
+// whichever instance renames first, so with several live sessions the event
+// could wake a different chat than the one the user is looking at — hook
+// staging (session-targeted) stays the correct route until per-session
+// channel targeting exists.
+export function countLiveChannelInstances(homeDir = storeDir(), { maxAgeMs = PRESENCE_MS * 3, nowMs = Date.now() } = {}) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(channelPresenceDir(homeDir));
+  } catch {
+    return 0;
+  }
+  let live = 0;
+  for (const name of entries) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const row = JSON.parse(fs.readFileSync(path.join(channelPresenceDir(homeDir), name), "utf8"));
+      if (nowMs - (Number(row.heartbeatAt) || 0) <= maxAgeMs) live += 1;
+    } catch {}
+  }
+  return live;
+}
+
+// True when at least one channel instance heartbeated recently — the pill uses
+// this to decide whether a wake-capable session exists at all.
+export function channelInstanceAlive(homeDir = storeDir(), opts = {}) {
+  return countLiveChannelInstances(homeDir, opts) > 0;
+}
+
+function consumeEventFile(file) {
+  const claimed = `${file}.${process.pid}.claimed`;
+  try {
+    fs.renameSync(file, claimed); // exactly-once across instances
+  } catch {
+    return null;
+  }
+  let payload = null;
+  try {
+    payload = JSON.parse(fs.readFileSync(claimed, "utf8"));
+  } catch {
+    payload = null;
+  }
+  try {
+    fs.rmSync(claimed, { force: true });
+  } catch {}
+  return payload && typeof payload === "object" ? payload : null;
+}
+
+export async function runChannelServer({ homeDir = storeDir(), log = (m) => console.error(`[relay-channel] ${m}`) } = {}) {
+  const server = new Server(
+    { name: "relay-channel", version: "0.1.0" },
+    // The experimental channel capability is what lets notifications push into
+    // the session; no tools are exposed (the relay MCP server already serves
+    // tools — this process exists ONLY to wake the session with events).
+    { capabilities: { experimental: { "claude/channel": {} } } },
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  log(`connected; watching ${channelQueueDir(homeDir)}`);
+
+  const presencePath = path.join(channelPresenceDir(homeDir), `${process.pid}.json`);
+  const heartbeat = () => {
+    try {
+      fs.mkdirSync(channelPresenceDir(homeDir), { recursive: true, mode: 0o700 });
+      fs.writeFileSync(presencePath, `${JSON.stringify({ pid: process.pid, cwd: process.cwd(), heartbeatAt: Date.now() })}\n`);
+    } catch {}
+  };
+  heartbeat();
+  const presenceTimer = setInterval(heartbeat, PRESENCE_MS);
+  if (presenceTimer.unref) presenceTimer.unref();
+
+  const pump = async () => {
+    let names = [];
+    try {
+      names = fs.readdirSync(channelQueueDir(homeDir)).filter((n) => n.startsWith("evt-") && n.endsWith(".json"));
+    } catch {
+      return;
+    }
+    names.sort(); // oldest first (timestamp-prefixed names)
+    for (const name of names) {
+      const payload = consumeEventFile(path.join(channelQueueDir(homeDir), name));
+      if (!payload) continue;
+      try {
+        await server.notification({
+          method: "notifications/claude/channel",
+          params: { content: String(payload.content || ""), meta: payload.meta || {} },
+        });
+        log(`pushed event ${name}`);
+      } catch (error) {
+        log(`push failed for ${name}: ${error && error.message}`);
+      }
+    }
+  };
+  const pumpTimer = setInterval(() => void pump(), POLL_MS);
+  if (pumpTimer.unref) pumpTimer.unref();
+  void pump();
+
+  const cleanup = () => {
+    try {
+      fs.rmSync(presencePath, { force: true });
+    } catch {}
+  };
+  process.on("exit", cleanup);
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+  return { server, pump };
+}