kojee-mcp 0.7.5-staging.2 → 0.8.0-beta.0

package/README.md

@@ -555,6 +555,106 @@ literal URL in the body; de-fang or split it; this is **not** an auth failure),
 `approval_required`, `not_paired`, `not_enrolled`, `bad_request`,
 `unauthorized`, `send_unavailable`, `send_failed` (raw text preserved).
 
+## Claude Co-Work (paste-one-command wake)
+
+**Claude Co-Work** is a cloud-sandbox harness with no MCP registration and no
+restart available mid-session, so it can't use the `init`-wired MCP proxy above.
+Instead, one line — generated from the Kojee dashboard and pasted into the
+agent's first turn — enrolls the sandbox and gets it streaming Tandem wakes
+immediately. This is a separate, parallel wake path from the MCP proxy; it does
+not use `startProxy` at all.
+
+### The pasted command
+
+```bash
+KOJEE_TOKEN=<token> npx -y kojee-mcp@<version> cowork --tandem <tandem_id> --url <broker>
+```
+
+The dashboard fills in `<token>`, `<version>` (the currently published
+`kojee-mcp` version), `<tandem_id>`, and `<broker>` when it generates this line
+for you. Flags:
+
+| Flag | Required | Description |
+|---|---|---|
+| `--tandem <id>` | yes, to launch | Tandem id to subscribe to. |
+| `--url <url>` | yes, to launch | Broker base URL — the token does not encode it. |
+| `--token <token>` | no (fallback) | Gateway token fallback. The canonical intake is the `KOJEE_TOKEN=` env prefix (keeps the secret off `/proc/<pid>/cmdline` and npm debug logs); `--token` costs a few seconds of argv exposure and is never forwarded to the worker process. |
+| `--force` | no | Override the clobber guard — replace a different token/broker already planted in `~/.kojee/config.json`. Without it, `cowork` refuses to overwrite a different credential (protects against an accidental paste evicting another sandbox's DPoP key — see the warning below). |
+| `--detach` | no | Host the worker as a detached background daemon (hidden `cowork-daemon` subcommand) instead of the default Monitor-hosted worker. |
+
+Run once, in the foreground, `cowork` enrolls the token into the paired DPoP
+slot, plants `~/.kojee/config.json` + `~/.kojee/keypair.json`, joins the
+tandem, and runs a startup barrier read — so a bad or revoked token, or a
+token that isn't a member of the tandem, fails loudly at paste time (nonzero
+exit, no Monitor recipe printed) instead of silently starting deaf.
+
+### What the agent does with the printed output
+
+On success `cowork` prints a recipe similar to:
+
+```
+[kojee cowork] enrolled + subscribed to tandem_abc123 (seat cowork-9f2a1c7b4e05).
+[kojee cowork] baseline cursor = 4821.  NOTE: this command contains a secret token — don't re-share this transcript.
+
+1) Arm the wake watcher ONCE (persistent Monitor):
+   Monitor(command=`npx kojee-mcp@<version> cowork-stream --tandem tandem_abc123`, persistent=true, description="kojee Tandem events")
+   ...
+```
+
+The agent should:
+
+1. **Arm the Monitor exactly once**, using the printed command — e.g.
+   `Monitor(command=\`npx kojee-mcp@<version> cowork-stream --tandem <tandem_id>\`, persistent=true, description="kojee Tandem events")`.
+   This spawns `cowork-stream`, which subscribes over SSE, writes the event
+   log, and fuses a tail of it onto its own stdout — each line is one Monitor
+   wake, carrying `msg=<id>` and `cursor=<n>`. If a watcher is already armed,
+   don't arm a second one.
+2. **Catch up once, right after arming** — `npx kojee-mcp@<version> messages <tandem_id> --since <baseline cursor>` — to cover the gap between paste and Monitor arm.
+3. **Reply via the `send` CLI, never MCP** (there are no MCP tools in this
+   session) — `npx kojee-mcp@<version> send <tandem_id> --body "..." --reply-to <msg>`.
+   One JSON envelope on stdout: `{ok:true, message_id, cursor}` (exit 0) or
+   `{ok:false, error, message}` (exit 1). Surface `content_blocked` /
+   `rate_limited` / `gateway_auth` distinctly — don't blind-retry.
+4. **Pull full, untruncated context on any gap** with the same `messages
+   --since <last cursor you saw>` command — e.g. after a cursor jump or a
+   `status=rotated` reset (event lines on the Monitor stream are truncated to
+   200 characters).
+
+Lines the worker prints that start with `[kojee]` (e.g. `[kojee] log=<path>`,
+`[kojee] WARNING: ...`, `[kojee] WORKER EXITED ...`) are telemetry, not Tandem
+messages — never reply to them.
+
+### Stopping it
+
+```bash
+npx kojee-mcp@<version> cowork stop --tandem <tandem_id>
+```
+
+Scans for live cowork workers on that tandem (omit `--tandem` to stop all live
+cowork workers on the box), SIGTERMs each, and cleans up its discovery file.
+
+**Merged (default) vs `--detach`:** by default the persistent Monitor *is* the
+host for the worker (`cowork-stream`), so if the wake stream dies the harness
+sees the Monitor's own process exit. `--detach` instead spawns a headless
+`cowork-daemon` child in the background and has the agent's Monitor tail its
+event-log file — use it only on a sandbox that won't keep a long-lived Monitor
+child alive.
+
+> **WARNING — mint a fresh token per sandbox.** Enrolling with `cowork` claims
+> the token's single DPoP key slot: the Kojee backend keeps **exactly one**
+> DPoP key per gateway token, and every enrollment **replaces** it. Paste the
+> *same* token into a second sandbox and the first sandbox's credential is
+> silently evicted — it goes offline. Mint a **fresh** cowork token per
+> sandbox from the dashboard; never reuse one across sandboxes.
+>
+> The pasted command also **contains a secret token in plaintext**. It
+> persists in the agent's transcript and shell history for as long as those
+> are retained — don't re-share the transcript, and treat the token as
+> compromised if it does leak out.
+
+Keep the `@<version>` pin — seat coherence relies on a feature that only
+exists in that version; do not drop it.
+
 ## Development
 
 Run tests:

package/dist/{chunk-67F67AQ6.js → chunk-3N4YYIOJ.js}

@@ -73,6 +73,33 @@ function readSessionDiscoveryByKey(key) {
     return null;
   }
 }
+function scanLiveCoworkWorkers(opts = {}) {
+  const dir = opts.dir ?? sessionDiscoveryDir();
+  const alive = opts.isAlive ?? isProcessAlive;
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (!name.startsWith("cc-") || !name.endsWith(".json")) continue;
+    const filePath = path.join(dir, name);
+    let entry = null;
+    try {
+      entry = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    } catch {
+      continue;
+    }
+    if (!entry || entry.origin !== "cowork") continue;
+    const pid = entry.proxyPid ?? entry.pid;
+    if (typeof pid !== "number" || !alive(pid)) continue;
+    const key = name.slice("cc-".length, -".json".length);
+    out.push({ key, entry, path: filePath, pid });
+  }
+  return out;
+}
 var DEFAULT_SWEEP_MIN_AGE_MS = 6e4;
 function isProcessAlive(pid) {
   try {
@@ -143,5 +170,6 @@ export {
   writeDiscoveryByKey,
   cleanupDiscoveryByKey,
   readSessionDiscoveryByKey,
+  scanLiveCoworkWorkers,
   sweepStaleDiscovery
 };

package/dist/{chunk-WBXU27BF.js → chunk-7J5CSXGS.js}

@@ -1,6 +1,6 @@
 import {
   readSessionDiscoveryByKey
-} from "./chunk-67F67AQ6.js";
+} from "./chunk-3N4YYIOJ.js";
 import {
   deriveDiscoveryKey,
   findClaudeAncestorPid

package/dist/{chunk-XPIW4N55.js → chunk-BO52SILE.js}

@@ -49,7 +49,7 @@ import {
   CODEX_LISTEN_CAP_MS,
   buildCondensedTandemRules,
   buildWebhookReceiverNote
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-QLARIAUJ.js";
 
 // src/wizard/pair-slot.ts
 import fs from "fs";

package/dist/{chunk-TCWIXG5C.js → chunk-D5VPUCPY.js}

@@ -1,6 +1,6 @@
 import {
   buildReplyRecipe
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-QLARIAUJ.js";
 
 // src/adapters/claude-code.ts
 function computeSeverity(event) {

package/dist/{chunk-CUOJHP2S.js → chunk-GP7XNGUR.js}

@@ -82,6 +82,13 @@ async function startEventStream(opts) {
     headersTimeout: UNDICI_DEFAULT_BODY_TIMEOUT_MS
   });
   const cursors = /* @__PURE__ */ new Map();
+  if (opts.initialCursors) {
+    for (const [tandemId, cursor] of Object.entries(opts.initialCursors)) {
+      if (typeof cursor === "number" && Number.isFinite(cursor)) {
+        cursors.set(tandemId, cursor);
+      }
+    }
+  }
   let currentController = new AbortController();
   let connectGeneration = 0;
   const state = {
@@ -273,10 +280,11 @@ async function consumeSse(body, opts, controller, state, onCursor) {
                 console.error("[event-stream] event-log append failed:", err);
               }
             }
-            if (opts.adapter.supportsChannels) {
+            const channelServer = opts.server;
+            if (opts.adapter.supportsChannels && channelServer) {
               try {
                 const channel = opts.adapter.formatTandemEvent(parsed);
-                await opts.server.notification({
+                await channelServer.notification({
                   method: "notifications/claude/channel",
                   params: channel
                 });

package/dist/{chunk-TNZITJAB.js → chunk-HMS4PZLC.js}

@@ -1,7 +1,7 @@
 import {
   readSessionDiscoveryByKey,
   sessionDiscoveryDir
-} from "./chunk-67F67AQ6.js";
+} from "./chunk-3N4YYIOJ.js";
 import {
   secureFile
 } from "./chunk-U5HHHRXA.js";

package/dist/chunk-JRCHS6CP.js

@@ -0,0 +1,14 @@
+// src/adapters/unknown.ts
+var unknownAdapter = {
+  runtime: "unknown",
+  supportsChannels: false,
+  formatTandemEvent() {
+    throw new Error(
+      "unknownAdapter.formatTandemEvent() is unreachable \u2014 caller should gate on supportsChannels"
+    );
+  }
+};
+
+export {
+  unknownAdapter
+};

package/dist/chunk-NMHM6SII.js

@@ -0,0 +1,118 @@
+import {
+  createPairedGateway
+} from "./chunk-VGZ4M3FP.js";
+import {
+  classifySendFailure,
+  ensureJoined,
+  sendFailure
+} from "./chunk-WZP7HXXN.js";
+import {
+  translateToolCallResult
+} from "./chunk-PPTKGWFF.js";
+
+// src/tandem/messages-cli.ts
+import os from "os";
+import path from "path";
+function parseMessagesRequest(input) {
+  const tandemId = input.tandem_id;
+  if (typeof tandemId !== "string" || tandemId.length === 0) {
+    return sendFailure("bad_request", "tandem_id is required and must be a non-empty string");
+  }
+  const request = { tandem_id: tandemId };
+  if (input.since !== void 0) {
+    if (typeof input.since !== "string" || input.since.length === 0) {
+      return sendFailure("bad_request", "--since must be a non-empty cursor when present");
+    }
+    request.since = input.since;
+  }
+  if (input.limit !== void 0) {
+    const raw = String(input.limit);
+    if (!/^\d+$/.test(raw)) {
+      return sendFailure("bad_request", "--limit must be a positive integer");
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0) {
+      return sendFailure("bad_request", "--limit must be a positive integer");
+    }
+    request.limit = n;
+  }
+  return { ok: true, request };
+}
+function deriveMaxCursor(messages) {
+  let max = null;
+  for (const m of messages) {
+    if (m !== null && typeof m === "object") {
+      const c = m["cursor"];
+      if (typeof c === "number" && (max === null || c > max)) max = c;
+    }
+  }
+  return max;
+}
+async function executeRead(gateway, request) {
+  const sinceArg = request.since !== void 0 ? /^\d+$/.test(request.since) ? Number(request.since) : request.since : void 0;
+  const args = {
+    tandem_id: request.tandem_id,
+    ...sinceArg !== void 0 ? { since: sinceArg } : {},
+    ...request.limit !== void 0 ? { limit: request.limit } : {}
+  };
+  let result;
+  try {
+    result = await gateway.sendRpc("tools/call", {
+      name: "tandem_messages",
+      arguments: args
+    });
+  } catch (err) {
+    return classifySendFailure(
+      `tandem_messages failed: ${err?.message ?? String(err)}`
+    );
+  }
+  const translated = translateToolCallResult(result);
+  const text = (translated.content ?? []).map((c) => typeof c?.text === "string" ? c.text : "").filter(Boolean).join("\n");
+  if (translated.isError) {
+    return classifySendFailure(text || "tandem_messages returned an error with no text");
+  }
+  let messages = [];
+  let cursor = null;
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      messages = parsed;
+    } else if (parsed !== null && typeof parsed === "object") {
+      const obj = parsed;
+      if (Array.isArray(obj["messages"])) messages = obj["messages"];
+      const rawCursor = obj["cursor"];
+      if (typeof rawCursor === "number") cursor = rawCursor;
+    }
+    if (cursor === null) cursor = deriveMaxCursor(messages);
+  } catch {
+  }
+  return { ok: true, tandem_id: request.tandem_id, messages, cursor, text };
+}
+async function runMessagesCli(args, deps = {}) {
+  const parsed = parseMessagesRequest({
+    tandem_id: args.tandemId,
+    ...args.since !== void 0 ? { since: args.since } : {},
+    ...args.limit !== void 0 ? { limit: args.limit } : {}
+  });
+  if (!parsed.ok) {
+    return { exitCode: 1, envelope: parsed };
+  }
+  const kojeeDir = args.kojeeDir ?? path.join(os.homedir(), ".kojee");
+  const createGateway = deps.createGateway ?? createPairedGateway;
+  const resolution = await createGateway(kojeeDir);
+  if (!resolution.ok) {
+    return { exitCode: 1, envelope: resolution };
+  }
+  const guard = await ensureJoined(resolution.gateway, parsed.request.tandem_id);
+  if (!guard.ok) {
+    return { exitCode: 1, envelope: guard.failure };
+  }
+  const envelope = await executeRead(resolution.gateway, parsed.request);
+  return { exitCode: envelope.ok ? 0 : 1, envelope };
+}
+
+export {
+  parseMessagesRequest,
+  executeRead,
+  runMessagesCli
+};

package/dist/{chunk-A4IOKD4Z.js → chunk-P2R3KWYK.js}

@@ -6,7 +6,7 @@ import {
   buildCondensedTandemRules,
   buildMonitorSpawn,
   buildReplyRecipe
-} from "./chunk-FJUAMJHU.js";
+} from "./chunk-QLARIAUJ.js";
 import {
   translateToolCallResult
 } from "./chunk-PPTKGWFF.js";

package/dist/{chunk-FJUAMJHU.js → chunk-QLARIAUJ.js}

@@ -1,10 +1,18 @@
 // src/tandem/recipe.ts
 var SEND_BODY_PARAM = "body";
+var KOJEE_PACKAGE = "kojee-mcp";
+var MONITOR_DESCRIPTION = "kojee Tandem events";
+function pinnedPackage(version) {
+  return `${KOJEE_PACKAGE}@${version}`;
+}
+function buildMonitorSpawnFor(command) {
+  return `Monitor(command=\`${command}\`, persistent=true, description="${MONITOR_DESCRIPTION}")`;
+}
 function buildMonitorCommand(logPath) {
-  return `npx kojee-mcp tail "${logPath}"`;
+  return `npx ${KOJEE_PACKAGE} tail "${logPath}"`;
 }
 function buildMonitorSpawn(logPath) {
-  return `Monitor(command=\`${buildMonitorCommand(logPath)}\`, persistent=true, description="kojee Tandem events")`;
+  return buildMonitorSpawnFor(buildMonitorCommand(logPath));
 }
 function buildReplyRecipe(event) {
   if (event) {
@@ -21,6 +29,18 @@ function buildCondensedTandemRules() {
 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()}.`;
 }
+function buildCoworkMonitorSpawn(tandemId, version) {
+  return buildMonitorSpawnFor(
+    `npx ${pinnedPackage(version)} cowork-stream --tandem ${tandemId}`
+  );
+}
+function buildCliReplyRecipe(tandemId, version) {
+  return `npx ${pinnedPackage(version)} send ${tandemId} --${SEND_BODY_PARAM} "..." --reply-to <msg>`;
+}
+function buildCliCatchUpNote(tandemId, version, sinceCursor) {
+  const since = sinceCursor !== void 0 ? String(sinceCursor) : "<cursor>";
+  return `npx ${pinnedPackage(version)} messages ${tandemId} --since ${since}`;
+}
 var WEBHOOK_BODY_SHAPE = "{ type, id, tandem_id, cursor, time, from{ member_id, principal, agent_id?, session_id?, displayname }, kind, content{ body, format? }, mentions?, reply_to?, severity? }";
 function buildWebhookReceiverNote(sig) {
   const header = sig?.header ?? "X-Kojee-Signature";
@@ -32,11 +52,15 @@ var CODEX_LISTEN_CAP_MS = 8e3;
 var CODEX_WAKE_BELL = "[kojee] Tandem events may be pending. Call tandem_pending now and drain each room it lists (tandem_messages(id, since=cursor)), then reply in the room with a normal message (kind=message \u2014 never status). If it returns none for you, ignore this.";
 
 export {
+  pinnedPackage,
   buildMonitorSpawn,
   buildReplyRecipe,
   buildCatchUpNote,
   buildCondensedTandemRules,
   buildMonitorNudge,
+  buildCoworkMonitorSpawn,
+  buildCliReplyRecipe,
+  buildCliCatchUpNote,
   buildWebhookReceiverNote,
   CODEX_LISTEN_CAP_MS,
   CODEX_WAKE_BELL

package/dist/{chunk-ZSHCHOPL.js → chunk-TXGO2W5I.js}

@@ -1,6 +1,9 @@
+import {
+  unknownAdapter
+} from "./chunk-JRCHS6CP.js";
 import {
   claudeCodeAdapter
-} from "./chunk-TCWIXG5C.js";
+} from "./chunk-D5VPUCPY.js";
 import {
   GatewayClient,
   applyStableSessionId
@@ -11,7 +14,7 @@ import {
 import {
   createMcpServer,
   startMcpServer
-} from "./chunk-A4IOKD4Z.js";
+} from "./chunk-P2R3KWYK.js";
 import {
   findClaudeAncestorPid
 } from "./chunk-XJEBJIQE.js";
@@ -181,17 +184,6 @@ var openclawAdapter = {
   }
 };
 
-// src/adapters/unknown.ts
-var unknownAdapter = {
-  runtime: "unknown",
-  supportsChannels: false,
-  formatTandemEvent() {
-    throw new Error(
-      "unknownAdapter.formatTandemEvent() is unreachable \u2014 caller should gate on supportsChannels"
-    );
-  }
-};
-
 // src/index.ts
 var DEFAULT_KEYSTORE_PATH = path.join(os.homedir(), ".kojee", "keypair.json");
 function isDPoPEnrollmentError(err) {
@@ -295,7 +287,7 @@ async function startProxy(config) {
   }
   console.error(`[kojee-mcp] Tandem memberships: ${tandemMembershipCount === -1 ? "unknown" : tandemMembershipCount}`);
   let server;
-  const { selectDelivery } = await import("./registry-XJ67EO22.js");
+  const { selectDelivery } = await import("./registry-E2DW73RE.js");
   const delivery = selectDelivery(adapter.runtime, {
     supportsChannels: adapter.supportsChannels,
     // Per-window delivered mirror for the tandem_pending tool (codex only —

package/dist/{send-cli-45RLGYIC.js → chunk-VGZ4M3FP.js}

@@ -2,11 +2,11 @@ import {
   resolvePairedSlot
 } from "./chunk-EIH2LNF4.js";
 import {
-  executeJoin,
+  ensureJoined,
   executeSend,
   parseSendRequest,
   sendFailure
-} from "./chunk-PKOBR7ZN.js";
+} from "./chunk-WZP7HXXN.js";
 import {
   loadPairedConfig
 } from "./chunk-5SZHXYPK.js";
@@ -14,15 +14,10 @@ import {
   GatewayClient,
   applyStableSessionId
 } from "./chunk-247WFMCJ.js";
-import "./chunk-Z5LPNJQ6.js";
-import "./chunk-MIEI4PLB.js";
 import {
   deriveKeystorePath,
   loadKeystore
 } from "./chunk-6G6YYST6.js";
-import "./chunk-U5HHHRXA.js";
-import "./chunk-PPTKGWFF.js";
-import "./chunk-KNEJTD6G.js";
 
 // src/tandem/send-cli.ts
 import os from "os";
@@ -42,7 +37,8 @@ async function createPairedGateway(kojeeDir, stableDeps = {}, slot = {}) {
       `no paired config at ${configPath} \u2014 run \`kojee-mcp connect <code> --runtime <id>\` first`
     );
   }
-  await applyStableSessionId(paired.token, stableDeps);
+  const seatDeps = paired.default_instance ? { instanceKey: paired.default_instance } : stableDeps;
+  await applyStableSessionId(paired.token, seatDeps);
   const brokerUrl = paired.broker_url.replace(/\/+$/, "");
   const keystorePath = resolution.scope === "paired" ? deriveKeystorePath(paired.token) : path.join(kojeeDir, "keypair.json");
   const keystore = await loadKeystore(keystorePath, brokerUrl).catch(() => null);
@@ -80,13 +76,14 @@ async function runSendCli(args, deps = {}) {
   if (!resolution.ok) {
     return { exitCode: 1, envelope: resolution };
   }
-  const joined = await executeJoin(resolution.gateway, parsed.request.tandem_id);
-  if (!joined.ok && (joined.error === "not_member" || joined.error === "gateway_auth")) {
-    return { exitCode: 1, envelope: joined };
+  const guard = await ensureJoined(resolution.gateway, parsed.request.tandem_id);
+  if (!guard.ok) {
+    return { exitCode: 1, envelope: guard.failure };
   }
   const envelope = await executeSend(resolution.gateway, parsed.request);
   return { exitCode: envelope.ok ? 0 : 1, envelope };
 }
+
 export {
   createPairedGateway,
   runSendCli

package/dist/{chunk-PKOBR7ZN.js → chunk-WZP7HXXN.js}

@@ -129,6 +129,13 @@ async function executeJoin(gateway, tandemId) {
   }
   return { ok: true, tandem_id: tandemId, message_id: null, cursor: null, text };
 }
+async function ensureJoined(gateway, tandemId) {
+  const joined = await executeJoin(gateway, tandemId);
+  if (!joined.ok && (joined.error === "not_member" || joined.error === "gateway_auth")) {
+    return { ok: false, failure: joined };
+  }
+  return { ok: true };
+}
 var HTTP_STATUS_BY_CODE = {
   bad_request: 400,
   unauthorized: 401,
@@ -155,7 +162,9 @@ function httpStatusForEnvelope(envelope) {
 export {
   sendFailure,
   parseSendRequest,
+  classifySendFailure,
   executeSend,
   executeJoin,
+  ensureJoined,
   httpStatusForEnvelope
 };