kojee-mcp 0.4.0 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # kojee-mcp
 
+> **First time using Kojee Tandem in Claude Code?** See [docs/getting-started-tandem.md](docs/getting-started-tandem.md) for the 3-command setup + verification walkthrough.
+
 There are two ways to connect Kojee to an MCP-capable agent:
 
 1. **Mobile, web & desktop (recommended)** — paste the Kojee MCP URL into the app's "Add custom connector" dialog. The app handles OAuth login and consent. No local install. Works on Claude (web/desktop/iOS/Android) and ChatGPT (web/desktop/iOS/Android with Developer Mode enabled).
@@ -126,26 +128,35 @@ If both Channels (dangerous-flag launched) and hooks are active, the proxy dedup
 
 ## Waiting on Tandem Peers
 
-When kojee-mcp is running under Claude Code, the proxy writes one line per Tandem message to a per-session log file. The agent watches this log via Claude Code's built-in `Monitor` tool.
-
-**You don't need to figure out the path yourself.** The proxy bakes the resolved path into the MCP server's `instructions` string at startup, so the agent gets the exact command to spawn:
+When kojee-mcp is running under Claude Code, the proxy writes one line per
+Tandem message to a per-session log file under the OS's temp directory
+(`os.tmpdir()` — `/tmp` on Linux, `/var/folders/…` on macOS, `%TEMP%` on
+Windows). The agent watches this log via Claude Code's built-in `Monitor`
+tool — spawned once at the start of each session:
 
 ```ts
 Monitor({
-  command: "tail -n +1 -F /tmp/kojee-events-<discoveryKey>.log",
+  command: `npx kojee-mcp tail "${eventLogPath}"`,
   persistent: true,
   description: "kojee Tandem events",
 });
 ```
 
-The `<discoveryKey>` is computed from `sha256(CLAUDE_PROJECT_DIR).slice(0,12) + '-' + <ccPid>` where `ccPid` is the parent Claude Code process. (This replaces the pre-v0.4 scheme that used `CLAUDE_CODE_SESSION_ID`, which Claude.app doesn't forward to MCP servers.) The matching `~/.kojee/sessions/cc-<discoveryKey>.json` discovery file lets the Stop / UserPromptSubmit hooks find this proxy via the same independent derivation.
+`kojee-mcp tail` is a portable line-streamer shipped with this proxy —
+works the same on macOS, Linux, and Windows. The proxy interpolates the
+resolved `eventLogPath` into the Channel-`instructions` string so the
+agent receives a ready-to-run command.
+
+The `<discoveryKey>` embedded in the log filename is computed from `sha256(CLAUDE_PROJECT_DIR).slice(0,12) + '-' + <ccPid>` where `ccPid` is the parent Claude Code process. (This replaces the pre-v0.4 scheme that used `CLAUDE_CODE_SESSION_ID`, which Claude.app doesn't forward to MCP servers.) The matching `~/.kojee/sessions/cc-<discoveryKey>.json` discovery file lets the Stop / UserPromptSubmit hooks find this proxy via the same independent derivation.
 
 Each appended event line arrives as a separate spontaneous wake notification. The agent stays free to chat with the user between events; CC delivers each event from idle as it arrives.
 
-**Stop hook is Monitor-aware** (v0.4+): when a Monitor is watching the log file, the Stop hook does an instant queue snapshot (~50ms) instead of a 30s long-poll, since events have already been delivered push-style. When no Monitor is running, the Stop hook long-polls for up to 30s AND emits a "spawn a Monitor" recommendation to the agent — self-healing if the session-start spawn was skipped.
+**Stop hook always long-polls** (up to 30s): the queue's `markMonitorDelivered` dedup ensures every event is delivered exactly once across the Channel / Monitor / Stop-hook paths, so the hook doesn't need to probe whether a Monitor is running. If the agent skipped the session-start Monitor spawn, the long-poll backstop still catches events; if Monitor is running, the dedup filters out anything already delivered push-style.
 
 Channel notifications (when available — see "Claude Code Channels Support" above) supplement this with mid-turn `<channel>` tag delivery, but Monitor is the default no-allowlist wake path that works for every user.
 
+**Cross-platform support:** the proxy core, the `kojee-mcp tail` Monitor command, and the Channel wake path are portable across macOS, Linux, and Windows — path resolution uses `os.homedir()` / `os.tmpdir()` and process-ancestry detection uses the pure-JS `ps-list` package. Claude Code hook invocation on Windows is pending end-to-end verification; on macOS and Linux it is exercised by CI.
+
 For one-shot blocking waits (return as soon as a single reply arrives), call `tandem_listen(tandem_id, since=cursor, timeout_ms=N)` instead.
 
 ## Backend SSE Wire Compatibility

package/dist/{chunk-36DMIXH7.js → chunk-BJMASMKX.js}

@@ -1,36 +1,26 @@
 // src/runtime/ancestry.ts
-import childProcess from "child_process";
+import psList from "ps-list";
 import { createHash } from "crypto";
-function findClaudeAncestorPid(startPid = process.ppid) {
-  if (process.platform === "win32") return null;
+async function findClaudeAncestorPid(startPid = process.ppid) {
+  let processes;
+  try {
+    processes = await psList();
+  } catch {
+    return null;
+  }
+  const byPid = /* @__PURE__ */ new Map();
+  for (const p of processes) byPid.set(p.pid, p);
   let pid = startPid;
   for (let depth = 0; depth < 20 && pid !== void 0 && pid > 1; depth++) {
-    let row;
-    try {
-      row = readProcInfo(pid);
-    } catch {
-      return null;
-    }
+    const row = byPid.get(pid);
     if (!row) return null;
-    if (/\bclaude\b/.test(row.command)) return pid;
+    const haystack = `${row.name} ${row.cmd ?? ""}`;
+    if (/\bclaude\b/i.test(haystack)) return pid;
     if (row.ppid === void 0 || row.ppid === pid) return null;
     pid = row.ppid;
   }
   return null;
 }
-function readProcInfo(pid) {
-  const out = childProcess.execFileSync("ps", ["-ww", "-p", String(pid), "-o", "ppid=,command="], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"]
-  }).trim();
-  if (!out) return null;
-  const firstSpace = out.indexOf(" ");
-  if (firstSpace < 0) return null;
-  const ppid = Number.parseInt(out.slice(0, firstSpace).trim(), 10);
-  if (!Number.isFinite(ppid)) return null;
-  const command = out.slice(firstSpace + 1).trim();
-  return { command, ppid };
-}
 function deriveDiscoveryKey(projectDir, ccPid) {
   const hasProjectDir = typeof projectDir === "string" && projectDir.length > 0;
   if (!hasProjectDir && ccPid === null) {

package/dist/chunk-E26AHU6J.js

@@ -0,0 +1,27 @@
+// src/tandem/recipe.ts
+var SEND_BODY_PARAM = "body";
+function buildMonitorCommand(logPath) {
+  return `npx kojee-mcp tail "${logPath}"`;
+}
+function buildMonitorSpawn(logPath) {
+  return `Monitor(command=\`${buildMonitorCommand(logPath)}\`, persistent=true, description="kojee Tandem events")`;
+}
+function buildReplyRecipe(event) {
+  if (event) {
+    return `reply directly with tandem_send(tandem_id="${event.tandem_id}", ${SEND_BODY_PARAM}="...", reply_to="${event.message_id}"); fetch context only if needed via tandem_messages(tandem_id, since=cursor-1)`;
+  }
+  return `reply directly with tandem_send(tandem_id, ${SEND_BODY_PARAM}, reply_to=<msg>); fetch context only if needed via tandem_messages(tandem_id, since=cursor-1)`;
+}
+function buildCatchUpNote() {
+  return "If the event line `cursor=<n>` ever jumps (a gap) or the log resets (the proxy caps and truncates the messages log in place on overflow \u2014 a `status=rotated` line is recorded in the status sibling), you may have missed messages: catch up with tandem_messages(tandem_id, since=<last cursor you saw>).";
+}
+function buildMonitorNudge(logPath) {
+  return `[kojee] Tandem events are being logged but no Monitor is reading them \u2014 you may be missing wake notifications. Spawn the watcher once: ${buildMonitorSpawn(logPath)}. Then ${buildReplyRecipe()}.`;
+}
+
+export {
+  buildMonitorSpawn,
+  buildReplyRecipe,
+  buildCatchUpNote,
+  buildMonitorNudge
+};

package/dist/{chunk-E7TE4QZD.js → chunk-GBOTBYEP.js}

@@ -1,8 +1,9 @@
 // src/auth/paired-config.ts
 import fs from "fs";
+import os from "os";
 import path from "path";
 function pairedConfigPath() {
-  return path.join(process.env["HOME"] ?? "~", ".kojee", "config.json");
+  return path.join(os.homedir(), ".kojee", "config.json");
 }
 function loadPairedConfig(filePath = pairedConfigPath()) {
   try {