kojee-mcp 0.5.7 → 0.5.9

package/README.md

@@ -1,11 +1,17 @@
 # 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.
+> Published version **0.5.8**.
+>
+> **First time using Kojee Tandem in Claude Code?** Three commands get you from
+> zero to a woken agent — see the [Quick start (Claude Code + Tandem)](#quick-start-claude-code--tandem)
+> below, or [docs/getting-started-tandem.md](docs/getting-started-tandem.md) for
+> the full walkthrough.
 
-There are two ways to connect Kojee to an MCP-capable agent:
+There are three 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).
-2. **Power user / local proxy with DPoP** — run this stdio proxy locally with a gateway token. Strongest wire-level security (DPoP proof-of-possession, RFC 9449), but requires Node and a token you generate manually in the Kojee dashboard.
+1. **Mobile, web & desktop (recommended for chat clients)** — 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).
+2. **Claude Code / Codex / Cursor — the local stdio proxy.** Run `kojee-mcp` locally; it holds a `gw_` gateway token + ES256 keypair and signs every request with DPoP (RFC 9449). The runtime-aware [`init` wizard](#quick-start-claude-code--tandem) wires it into your harness and sets up the wake path so an idle agent is woken by Tandem messages between turns. **This is the recommended path for agentic runtimes** and the focus of this README.
+3. **OpenClaw / Hermes — native Tandem channel plugins.** On those runtimes Tandem is a first-class channel (peer to Telegram/Discord), wired through a plugin that wraps the same gateway client — **not** MCP. See [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes).
 
 ## Mobile, Web & Desktop (Recommended)
 
@@ -30,92 +36,156 @@ The OAuth login + consent flow takes care of everything — no token paste, no c
 | Discovery | `https://api.kojee.ai/.well-known/oauth-protected-resource` |
 | Scopes | `mcp:tools`, `mcp:read` |
 
-## Power User: Local Proxy with DPoP
+## Quick start (Claude Code + Tandem)
 
-The `kojee-mcp` stdio proxy holds a `gw_` gateway token + ES256 keypair locally and signs every request with DPoP (RFC 9449). This survives token-in-transit theft (TLS-terminating proxy logs, etc.) — strictly stronger wire-level posture than bearer-only OAuth, but requires a long-lived token.
+From zero to a woken agent — the recommended path for Claude Code:
 
-### Claude Code / Claude Desktop
+```bash
+# 1. Pair this machine + configure your runtime in one guided step.
+#    Run it in a terminal (TTY): it walks you through broker URL → auth
+#    (paste a token OR enter a pair code) → wake setup. Defaults to claude-code.
+npx -y kojee-mcp@latest init
 
-```json
-{
-  "mcpServers": {
-    "kojee": {
-      "command": "npx",
-      "args": ["kojee-mcp", "--token", "YOUR_TOKEN", "--url", "https://kojee.ai"]
-    }
-  }
-}
+# 2. Confirm the wake path is healthy.
+npx -y kojee-mcp@latest doctor
+
+# 3. Start a fresh Claude Code session.
+claude
 ```
 
-### Generic MCP Client
+`init` is a **guided wizard** when stdin is a TTY (and no `--runtime` flag is
+given). It prompts for, in order:
 
-Any MCP client that supports stdio transports can use kojee-mcp:
+1. **Runtime** — `claude-code` (default), `hermes`, `openclaw`, or `codex`.
+2. **Broker URL** — Enter accepts the default `https://rosie-staging.kojee.net`.
+3. **Auth** — paste an existing gateway token (**token mode**), or enter a
+   **pair code** from the dashboard (**pair mode** — runs the DPoP enrollment and
+   writes `~/.kojee/config.json` for you, so you don't run `pair` separately).
+4. **Webhook receiver** (codex/hermes/openclaw only) — Enter to skip and set it up later.
 
-```bash
-npx kojee-mcp --token gw_abc123... --url https://kojee.ai
-```
+For non-interactive / CI use, pass flags instead (see
+[Non-interactive `init`](#non-interactive-init-flags--ci) below). Either way the
+final wake check is `kojee-mcp doctor`.
 
-Or install globally:
+> **Already have a pair code and just want one command?**
+> `npx -y kojee-mcp@latest init --pair-code YOUR-CODE` pairs **and** configures
+> claude-code in a single non-interactive step (URL defaults to
+> `https://rosie-staging.kojee.net`; override with `--url`).
 
-```bash
-npm install -g kojee-mcp
-kojee-mcp --token gw_abc123... --url https://kojee.ai
-```
+### What `init` writes (claude-code)
 
-## CLI Flags
+It adds the MCP entry to **every detected Claude installation**:
 
-| Flag | Required | Default | Description |
-|------|----------|---------|-------------|
-| `--token` | yes | -- | Your Kojee gateway token (starts with `gw_`) |
-| `--url` | yes | -- | Kojee broker URL (e.g. `https://kojee.ai`) |
-| `--keystore-path` | no | `~/.kojee/keypair.json` | Path for DPoP keypair storage |
+- `~/.claude.json` → MCP server entry (terminal `claude` CLI **and** Claude.app).
+- `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude.app on
+  macOS — Windows / Linux paths in the spec) if present.
+- `~/.claude/settings.json` → the **Stop + UserPromptSubmit hooks** (terminal CLI
+  only; Claude.app agent mode reads MCP servers but not hooks).
+
+The canonical MCP entry includes `env.KOJEE_RUNTIME=claude-code` so the proxy
+identifies as Claude Code even when the desktop app strips environment variables
+from MCP subprocesses. In **token mode** the entry launches the proxy with
+`--token`/`--url` (it enrolls its own per-token keystore); in **pair mode** the
+args stay `["kojee-mcp"]` and the proxy reads `~/.kojee/config.json` (mode 0600).
+Existing entries (other MCP servers, other hooks like babysitter wrappers) are
+preserved.
 
-## Pair Mode (Tandem)
+**Important for Claude.app users:** existing agent-mode sessions snapshot the MCP
+config at creation time and won't pick up changes from `init`. Start a NEW session
+(not a resumed one) to use the updated kojee config.
 
-If your token comes from the Kojee Tandem web wizard (a "pair code"), you can persist it for future runs:
+To remove kojee from your runtime (runtime-aware — uses the recorded runtime):
 
 ```bash
-# One-time setup:
-npx kojee-mcp pair ABCD-1234 --url https://rosie-server.kojee.net
-npx kojee-mcp init                              # adds the MCP entry to EVERY detected Claude installation
+npx kojee-mcp init --uninstall
 ```
 
-`init` writes to both `~/.claude.json` (terminal `claude` CLI) and `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude.app on macOS — Windows / Linux paths in the spec) if either exists. The canonical MCP entry includes `env.KOJEE_RUNTIME=claude-code` so the proxy correctly identifies as Claude Code even when the desktop app strips environment variables from MCP subprocesses.
+### Verify the wake path — `kojee-mcp doctor`
 
-**Important for Claude.app users:** existing agent-mode sessions snapshot the MCP config at creation time and won't pick up changes from `init`. Start a NEW session (not a resumed one) to use the updated kojee config.
+`doctor` is the one-command health check for the whole wake path. It derives the
+same discovery key the hooks use, finds the running proxy, and walks every link
+in order — paired config, proxy process alive, hook-server `/health` + `/status`,
+the **SSE stream** (connected? heartbeat age? subscribed tandem count?), the
+event log, and whether a **Monitor** is reading it — then prints a one-screen
+`HEALTHY` / `DEGRADED` / `BROKEN` verdict **plus the exact wake recipe to spawn**.
+It's runtime-aware (a codex install gets the codex webhook-sink + stop-hook
+checks). Exit code is non-zero only when the verdict is `BROKEN`.
 
-Subsequent runs of `claude` will find kojee automatically. The proxy writes credentials to `~/.kojee/config.json` (mode 0600). Existing `--token` users are unaffected.
+```bash
+npx kojee-mcp doctor
+```
+
+### CLI command reference
+
+| Command | What it does |
+|---|---|
+| `kojee-mcp` *(default, no subcommand)* | Run the stdio MCP proxy. Token mode (`--token`/`--url`) or paired mode (reads `~/.kojee/config.json`). |
+| `kojee-mcp init` | Runtime-aware setup wizard (guided in a TTY; flag-driven in CI). |
+| `kojee-mcp pair <code> --url <broker>` | Pair this machine (DPoP enroll + write `~/.kojee/config.json`). |
+| `kojee-mcp doctor` | Diagnose the wake path and print the exact wake recipe. |
+| `kojee-mcp install-hooks` | Install/remove (`--uninstall`) just the Claude Code Stop + UserPromptSubmit hooks. |
+| `kojee-mcp send <tandem_id> --body <text>` | Send a Tandem message from outside the proxy using paired creds (see [Local Send Control Surface](#local-send-control-surface-054)). |
+| `kojee-mcp tail <path>` | Portable line-streamer (`tail -F` replacement) — the Monitor command on every platform. |
+| `kojee-mcp hook --type <stop\|user-prompt-submit\|codex-stop>` | Internal hook entry point (Claude Code / Codex invoke it; you don't run it directly). |
+
+## Standalone pairing — `kojee-mcp pair`
+
+The guided `init` pairs for you, but you can also pair as a separate step (then
+run `init` to configure your runtime). Use this when scripting, or to re-pair
+after a code expires:
 
-To remove kojee from Claude:
 ```bash
-npx kojee-mcp init --uninstall
+npx kojee-mcp pair ABCD-1234 --url https://rosie-staging.kojee.net
 ```
 
+This runs the DPoP enrollment and persists credentials to `~/.kojee/config.json`
+(mode 0600) + the keypair to `~/.kojee/keypair.json`. Subsequent runs of the
+proxy find them automatically. `--keystore-path` overrides the keypair location.
+
 ## Runtime-aware setup wizard (`init` selects the runtime)
 
 `kojee-mcp init` is a runtime-aware wizard. The runtime selector is its core — one
-proxy adapts to four harnesses. Bare `init` with no flag and no TTY still defaults
-to `claude-code` (unchanged), so existing setups have zero regression.
+proxy adapts to four harnesses (`claude-code | hermes | openclaw | codex`). Bare
+`init` with no flag and no TTY still defaults to `claude-code` (unchanged), so
+existing setups have zero regression.
+
+### Non-interactive `init` (flags / CI)
+
+Passing `--runtime` makes `init` non-interactive (the contract for CI). Auth and
+webhook details come from flags:
 
 ```bash
-npx kojee-mcp init                       # interactive (prompts when stdin is a TTY)
-npx kojee-mcp init --runtime claude-code # Claude Code (default): MCP entry + Stop/UserPromptSubmit hooks
+npx kojee-mcp init                       # interactive guided wizard (TTY, no --runtime)
+npx kojee-mcp init --pair-code ABCD-1234 # pair + configure claude-code in one shot
+npx kojee-mcp init --runtime claude-code --token gw_abc... --url https://rosie-staging.kojee.net
+                                         # claude-code, token mode (no pair step)
 npx kojee-mcp init --runtime codex --webhook-url https://your-receiver/kojee
                                          # Codex: writes ~/.codex/config.toml + a codex-stop hook
-npx kojee-mcp init --runtime hermes --webhook-url https://your-receiver/kojee
+npx kojee-mcp init --runtime hermes  --webhook-url https://your-receiver/kojee
 npx kojee-mcp init --runtime openclaw --webhook-url https://your-receiver/kojee
                                          # daemon runtimes: print/record the webhook-sink env to export
 ```
 
+Auth flags (all runtimes): `--token <gw_…>` + `--url <broker>` (token mode), or
+`--pair-code <code>` (runs the pair flow up front, then configures). `--url`
+defaults to `https://rosie-staging.kojee.net`. A non-interactive `init` with **no**
+credential at all (no paired config, no `--token`/`--pair-code`) errors and tells
+you to pair first.
+
+Per-runtime config-path / hooks-path overrides: `--config-path`, `--hooks-path`.
+
 - **codex** — writes `[mcp_servers.kojee]` (with `env.KOJEE_RUNTIME="codex"` + the
   webhook env) into `~/.codex/config.toml`, and a `codex-stop` Stop hook into
   `~/.codex/hooks.json`. A `KOJEE_WEBHOOK_SECRET` is generated if you don't supply
   one. Codex has no Claude-style channel injection, so its wake is the **webhook
   sink + a stop-hook fast PEEK + a model-chosen bounded `tandem_listen` (cap 8s,
   never a blanket long-poll)**. See `docs/RUNTIMES.md`.
-- **hermes / openclaw** — run the proxy as a daemon and consume the webhook sink;
-  the wizard writes no config/hooks of ours, validates the webhook env, and prints
-  + records the env to export (secret redacted).
+- **hermes / openclaw** — these runtimes have **native channel plugins** (see
+  [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes)). When you
+  instead run the proxy as a **daemon** feeding a webhook receiver, `init --runtime
+  hermes|openclaw` writes no MCP-config/hooks of ours, validates the webhook env,
+  and prints + records the env to export (secret redacted) into a source-able
+  `~/.kojee/<runtime>.env`.
 
 `kojee-mcp init --uninstall` is runtime-aware (uses the recorded runtime when
 `--runtime` is omitted). `kojee-mcp doctor` is runtime-aware too.
@@ -124,6 +194,75 @@ npx kojee-mcp init --runtime openclaw --webhook-url https://your-receiver/kojee
 > adapter + wizard are unit/integration-tested only. Live-Codex end-to-end is
 > unverified — the wizard prints this note after a `--runtime codex` install.
 
+## Direct proxy invocation (advanced / generic MCP clients)
+
+Most users let `init` write the launch command. If you manage the MCP config by
+hand, the proxy runs in **token mode** with `--token` + `--url`:
+
+```json
+{
+  "mcpServers": {
+    "kojee": {
+      "command": "npx",
+      "args": ["kojee-mcp", "--token", "YOUR_TOKEN", "--url", "https://rosie-staging.kojee.net"]
+    }
+  }
+}
+```
+
+Any stdio-capable MCP client works the same way:
+
+```bash
+npx kojee-mcp --token gw_abc123... --url https://rosie-staging.kojee.net
+# or install globally:
+npm install -g kojee-mcp
+kojee-mcp --token gw_abc123... --url https://rosie-staging.kojee.net
+```
+
+Run bare (no `--token`) and the proxy uses **paired** credentials from
+`~/.kojee/config.json` — that's what the claude-code MCP entry does in pair mode.
+
+### Proxy CLI flags (default command)
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--token` | token mode only | — | Your Kojee gateway token (starts with `gw_`). Omit to use paired credentials. |
+| `--url` | with `--token` | paired `broker_url` | Kojee broker URL (e.g. `https://rosie-staging.kojee.net`). |
+| `--keystore-path` | no | per-token path under `~/.kojee/` | Path for DPoP keypair storage. |
+
+## How each runtime reaches Tandem
+
+| Runtime | How it connects | Wake path |
+|---|---|---|
+| **claude-code** | MCP stdio proxy (this package), wired by `init` | CC Channels (preview) · **Monitor** (`tail` of the event log) · **Stop/UserPromptSubmit hooks** — see below |
+| **cursor** & other MCP clients | MCP stdio proxy | poll/`tandem_listen`; no CC channel injection |
+| **codex** | MCP stdio proxy + `~/.codex` config/hook | webhook sink + stop-hook peek + bounded `tandem_listen` (cap 8s) |
+| **openclaw** | **native channel plugin** (not MCP) | OpenClaw's own routing/sessions wake the agent on each Tandem event |
+| **hermes** | **native channel plugin** (sidecar daemon + webhook) | Hermes gateway wakes the agent like a Telegram DM |
+
+## Native gateway runtimes (OpenClaw + Hermes)
+
+On OpenClaw and Hermes, Tandem is a **native channel** — peer to Telegram/Discord
+— not an MCP server. A plugin makes the agent *present* in its tandems whenever
+the gateway is up: it wakes on Tandem messages through the runtime's own
+routing/sessions and replies on the same channel. Both plugins wrap the **same**
+gateway client + DPoP auth + SSE event stream this proxy uses (`kojee-mcp/lib`);
+nothing is forked.
+
+- **OpenClaw** — `integrations/openclaw-plugin/` (`openclaw-channel-kojee-tandem`).
+  Imports `kojee-mcp/lib` directly; one SSE subscription covers all joined
+  tandems; outbound `sendText` → `tandem_send`. Shares the daemon's keystore so
+  pairing once works for both. See its [README](integrations/openclaw-plugin/README.md).
+- **Hermes** — `integrations/hermes-plugin/` (sidecar design v1). The kojee-mcp
+  proxy runs as a **daemon** and POSTs signed webhooks to a loopback adapter
+  listener; the adapter turns each event into a Hermes message. Configure the
+  daemon side with `kojee-mcp init --runtime hermes --webhook-url …`. See its
+  [README](integrations/hermes-plugin/README.md).
+
+Pair once (`kojee-mcp pair`, or any kojee-mcp-attached session), and the agent
+must be a member of the tandem (`tandem_join` once, or be invited); after that,
+presence is zero-config — gateway up ⇒ agent reachable in the tandem.
+
 ## Claude Code Channels Support
 
 When this proxy detects it's running under Claude Code, it declares the `claude/channel` capability and pushes Tandem messages directly into the Claude session via `notifications/claude/channel`. Other MCP clients (Cursor, Codex, Openclaw, etc.) see no behavior change.

package/dist/{chunk-64EOLZNI.js → chunk-65KRRDHP.js}

@@ -15,11 +15,17 @@ function defaultCodexHooksPath() {
   return path.join(kojeeHomeDir(), ".codex", "hooks.json");
 }
 var CODEX_STOP_HOOK_COMMAND = "npx -y kojee-mcp hook --type=codex-stop";
+function codexArgsLiteral(token, url) {
+  if (token && url) {
+    return `["-y", "kojee-mcp", "--token", "${escapeTomlString(token)}", "--url", "${escapeTomlString(url)}"]`;
+  }
+  return '["-y", "kojee-mcp"]';
+}
 function buildCodexMcpServerTable(opts) {
   return [
     "[mcp_servers.kojee]",
     'command = "npx"',
-    'args = ["-y", "kojee-mcp"]',
+    `args = ${codexArgsLiteral(opts.token, opts.url)}`,
     "",
     "[mcp_servers.kojee.env]",
     'KOJEE_RUNTIME = "codex"',
@@ -50,7 +56,14 @@ function writeCodexConfig(inputs) {
     toml = fs.readFileSync(configPath, "utf8");
   } catch {
   }
-  toml = upsertKojeeTomlTables(toml, inputs.webhookUrl, inputs.webhookSecret, inputs.signatureEnv ?? []);
+  toml = upsertKojeeTomlTables(
+    toml,
+    inputs.webhookUrl,
+    inputs.webhookSecret,
+    inputs.signatureEnv ?? [],
+    inputs.token,
+    inputs.url
+  );
   writeFile600(configPath, toml);
   const hooks = readJson(hooksPath);
   hooks.hooks ??= {};
@@ -95,20 +108,22 @@ function removeCodexConfig(opts = {}) {
   }
   return result;
 }
-function upsertKojeeTomlTables(existing, webhookUrl, webhookSecret, signatureEnv = []) {
+function upsertKojeeTomlTables(existing, webhookUrl, webhookSecret, signatureEnv = [], token, url) {
   const parsed = extractKojeeBlock(existing);
   if (!parsed) {
     const block = buildCodexMcpServerTable({
       webhookUrl,
       webhookSecret,
-      ...signatureEnv.length > 0 ? { signatureEnv } : {}
+      ...signatureEnv.length > 0 ? { signatureEnv } : {},
+      ...token ? { token } : {},
+      ...url ? { url } : {}
     });
     const base2 = existing.replace(/\s*$/, "");
     return base2.length === 0 ? block + "\n" : base2 + "\n\n" + block + "\n";
   }
   const tableKeys = upsertKeyLines(parsed.tableKeys, [
     ["command", '"npx"'],
-    ["args", '["-y", "kojee-mcp"]']
+    ["args", codexArgsLiteral(token, url)]
   ]);
   const envKeys = upsertKeyLines(parsed.envKeys, [
     ["KOJEE_RUNTIME", '"codex"'],

package/dist/chunk-CH32ELFX.js

@@ -0,0 +1,68 @@
+import {
+  secureDir,
+  secureFile
+} from "./chunk-BLEGIR35.js";
+
+// src/auth/keystore.ts
+import { importJWK, exportJWK, generateKeyPair } from "jose";
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+var DEFAULT_PATH = path.join(os.homedir(), ".kojee", "keypair.json");
+function defaultPairedKeystorePath() {
+  return path.join(os.homedir(), ".kojee", "keypair.json");
+}
+function deriveKeystorePath(token) {
+  const hash = crypto.createHash("sha256").update(token).digest("hex").slice(0, 12);
+  return path.join(os.homedir(), ".kojee", `keypair-${hash}.json`);
+}
+async function loadKeystore(keystorePath = DEFAULT_PATH, expectedBrokerUrl) {
+  if (!fs.existsSync(keystorePath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(keystorePath, "utf-8");
+  const data = JSON.parse(raw);
+  if (expectedBrokerUrl && data.broker_url !== expectedBrokerUrl) {
+    return null;
+  }
+  const privateKey = await importJWK(data.private_key_jwk, "ES256");
+  return {
+    privateKey,
+    publicJwk: data.public_jwk,
+    kid: data.kid,
+    data
+  };
+}
+async function saveKeystore(privateKey, publicJwk, kid, brokerUrl, keystorePath = DEFAULT_PATH) {
+  const dir = path.dirname(keystorePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  secureDir(dir);
+  const privateJwk = await exportJWK(privateKey);
+  const data = {
+    private_key_jwk: privateJwk,
+    kid,
+    broker_url: brokerUrl,
+    public_jwk: publicJwk,
+    enrolled_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  fs.writeFileSync(keystorePath, JSON.stringify(data, null, 2), {
+    mode: 384
+  });
+  secureFile(keystorePath);
+}
+async function generateES256KeyPair() {
+  const { privateKey, publicKey } = await generateKeyPair("ES256");
+  const publicJwk = await exportJWK(publicKey);
+  publicJwk.kty = "EC";
+  publicJwk.crv = "P-256";
+  return { privateKey, publicJwk };
+}
+
+export {
+  defaultPairedKeystorePath,
+  deriveKeystorePath,
+  loadKeystore,
+  saveKeystore,
+  generateES256KeyPair
+};

package/dist/{chunk-2TUAFAIW.js → chunk-DS26OORG.js}

@@ -117,11 +117,22 @@ function startEventLog(opts) {
 function formatStatusLine(fields) {
   return `[${(/* @__PURE__ */ new Date()).toISOString()}] ${STATUS_LINE_PREFIX} ${fields}`;
 }
+function oneLineField(value) {
+  return String(value ?? "").replace(/[\u0000-\u001f\u007f]/g, "");
+}
 function formatLine(event) {
   const body = (event.content?.body ?? "").replace(/[\r\n]+/g, " ").slice(0, MAX_BODY_CHARS + 1);
   const truncated = body.length > MAX_BODY_CHARS;
-  const safeBody = truncated ? body.slice(0, MAX_BODY_CHARS) + "\u2026" : body;
-  return `[${event.time}] tandem=${event.tandem_id} from=${event.from.displayname} (${event.from.principal}) kind=${event.kind} cursor=${event.cursor} msg=${event.id}: ${safeBody}`;
+  const safeBody = oneLineField(truncated ? body.slice(0, MAX_BODY_CHARS) + "\u2026" : body);
+  const time = oneLineField(event.time);
+  const tandemId = oneLineField(event.tandem_id);
+  const displayname = oneLineField(event.from.displayname);
+  const principal = oneLineField(event.from.principal);
+  const kind = oneLineField(event.kind);
+  const cursor = oneLineField(event.cursor);
+  const id = oneLineField(event.id);
+  const wakeReason = event.wake_reason ? ` wake_reason=${oneLineField(event.wake_reason)}` : "";
+  return `[${time}] tandem=${tandemId} from=${displayname} (${principal}) kind=${kind}${wakeReason} cursor=${cursor} msg=${id}: ${safeBody}`;
 }
 function monitorHeartbeatPath(eventLogPath) {
   const dir = path.dirname(eventLogPath);

package/dist/{chunk-3XDJOHMZ.js → chunk-HSR3GXCL.js}

@@ -7,69 +7,9 @@ import {
   translateJsonRpcError,
   translateNetworkError
 } from "./chunk-LDZXU3DW.js";
-import {
-  secureDir,
-  secureFile
-} from "./chunk-BLEGIR35.js";
-
-// src/auth/keystore.ts
-import { importJWK, exportJWK, generateKeyPair } from "jose";
-import crypto from "crypto";
-import fs from "fs";
-import os from "os";
-import path from "path";
-var DEFAULT_PATH = path.join(os.homedir(), ".kojee", "keypair.json");
-function defaultPairedKeystorePath() {
-  return path.join(os.homedir(), ".kojee", "keypair.json");
-}
-function deriveKeystorePath(token) {
-  const hash = crypto.createHash("sha256").update(token).digest("hex").slice(0, 12);
-  return path.join(os.homedir(), ".kojee", `keypair-${hash}.json`);
-}
-async function loadKeystore(keystorePath = DEFAULT_PATH, expectedBrokerUrl) {
-  if (!fs.existsSync(keystorePath)) {
-    return null;
-  }
-  const raw = fs.readFileSync(keystorePath, "utf-8");
-  const data = JSON.parse(raw);
-  if (expectedBrokerUrl && data.broker_url !== expectedBrokerUrl) {
-    return null;
-  }
-  const privateKey = await importJWK(data.private_key_jwk, "ES256");
-  return {
-    privateKey,
-    publicJwk: data.public_jwk,
-    kid: data.kid,
-    data
-  };
-}
-async function saveKeystore(privateKey, publicJwk, kid, brokerUrl, keystorePath = DEFAULT_PATH) {
-  const dir = path.dirname(keystorePath);
-  fs.mkdirSync(dir, { recursive: true, mode: 448 });
-  secureDir(dir);
-  const privateJwk = await exportJWK(privateKey);
-  const data = {
-    private_key_jwk: privateJwk,
-    kid,
-    broker_url: brokerUrl,
-    public_jwk: publicJwk,
-    enrolled_at: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  fs.writeFileSync(keystorePath, JSON.stringify(data, null, 2), {
-    mode: 384
-  });
-  secureFile(keystorePath);
-}
-async function generateES256KeyPair() {
-  const { privateKey, publicKey } = await generateKeyPair("ES256");
-  const publicJwk = await exportJWK(publicKey);
-  publicJwk.kty = "EC";
-  publicJwk.crv = "P-256";
-  return { privateKey, publicJwk };
-}
 
 // src/gateway-client.ts
-import crypto2 from "crypto";
+import crypto from "crypto";
 var GatewayClient = class {
   constructor(brokerUrl, token, privateKey, kid, sessionId) {
     this.brokerUrl = brokerUrl;
@@ -105,7 +45,7 @@ var GatewayClient = class {
    * session_id = sha256(token + "proxy").slice(0, 16)
    */
   static deriveSessionId(token) {
-    const hash = crypto2.createHash("sha256").update(token + "proxy").digest("hex");
+    const hash = crypto.createHash("sha256").update(token + "proxy").digest("hex");
     return hash.slice(0, 16);
   }
   /**
@@ -214,10 +154,5 @@ var GatewayClient = class {
 };
 
 export {
-  defaultPairedKeystorePath,
-  deriveKeystorePath,
-  loadKeystore,
-  saveKeystore,
-  generateES256KeyPair,
   GatewayClient
 };

package/dist/{chunk-6SK6ITFE.js → chunk-JXMVZEQ7.js}

@@ -2,7 +2,7 @@ import {
   generateES256KeyPair,
   loadKeystore,
   saveKeystore
-} from "./chunk-3XDJOHMZ.js";
+} from "./chunk-CH32ELFX.js";
 
 // src/auth/auth-module.ts
 import { calculateJwkThumbprint } from "jose";

package/dist/{chunk-UEGQGXPY.js → chunk-MKDMAAMN.js}

@@ -231,6 +231,7 @@ async function consumeSse(body, opts, controller, state, onCursor) {
             const raw = JSON.parse(evt.data);
             const parsed = normalizeBackendEvent(raw, evt.event);
             onCursor(parsed.tandem_id, parsed.cursor);
+            if (parsed.wake === false) continue;
             opts.queue?.push(parsed);
             if (opts.eventLog) {
               try {
@@ -340,8 +341,13 @@ function resolveDisplayname(rawDisplay, principal) {
 }
 function normalizeBackendEvent(raw, sseEventType) {
   const obj = raw ?? {};
+  const rawWake = obj["wake"];
+  const wake = typeof rawWake === "boolean" ? rawWake : void 0;
+  const rawWakeReason = obj["wake_reason"];
+  const wakeReason = typeof rawWakeReason === "string" && rawWakeReason.trim() ? sanitizeDisplayname(rawWakeReason) : void 0;
+  const senderPresent = typeof obj === "object" && obj !== null && "sender" in obj;
   const maybeFrom = obj["from"];
-  if (maybeFrom && typeof maybeFrom["principal"] === "string") {
+  if (!senderPresent && maybeFrom && typeof maybeFrom["principal"] === "string") {
     const canonical = raw;
     const canonicalPrincipal = sanitizeDisplayname(maybeFrom["principal"]);
     return {
@@ -350,7 +356,9 @@ function normalizeBackendEvent(raw, sseEventType) {
         ...canonical.from,
         principal: canonicalPrincipal,
         displayname: resolveDisplayname(maybeFrom["displayname"], canonicalPrincipal)
-      }
+      },
+      ...wake !== void 0 ? { wake } : {},
+      ...wakeReason !== void 0 ? { wake_reason: wakeReason } : {}
     };
   }
   const sender = obj["sender"] ?? {};
@@ -383,7 +391,9 @@ function normalizeBackendEvent(raw, sseEventType) {
     },
     ...Array.isArray(obj["mentions"]) ? { mentions: obj["mentions"] } : {},
     ...obj["reply_to"] !== void 0 ? { reply_to: obj["reply_to"] } : {},
-    ...severity ? { severity } : {}
+    ...severity ? { severity } : {},
+    ...wake !== void 0 ? { wake } : {},
+    ...wakeReason !== void 0 ? { wake_reason: wakeReason } : {}
   };
 }
 

package/dist/chunk-OGHDTFAX.js

@@ -0,0 +1,50 @@
+import {
+  loadPairedConfig,
+  savePairedConfig
+} from "./chunk-YH27B6SW.js";
+import {
+  AuthModule
+} from "./chunk-JXMVZEQ7.js";
+
+// src/tandem/pair.ts
+import fs from "fs";
+async function runPair(opts) {
+  if (loadPairedConfig(opts.configPath) !== null) {
+    throw new Error(
+      `Already paired (config exists at ${opts.configPath}). To re-pair this slot, delete the config file first. For a second account, use --keystore-path /custom/keypair.json.`
+    );
+  }
+  try {
+    fs.unlinkSync(opts.keystorePath);
+  } catch {
+  }
+  const auth = new AuthModule(opts.code, opts.url, opts.keystorePath);
+  await auth.ensureEnrolled();
+  let principal_id;
+  let agent_id;
+  try {
+    const me = await fetch(`${opts.url}/api/v1/users/me/`, {
+      headers: { Authorization: `DPoP ${opts.code}` }
+    });
+    if (me.ok) {
+      const body = await me.json();
+      principal_id = body.principal_id;
+      agent_id = body.agent_id;
+    }
+  } catch {
+  }
+  const config = {
+    token: opts.code,
+    broker_url: opts.url,
+    paired_at: (/* @__PURE__ */ new Date()).toISOString(),
+    ...principal_id ? { principal_id } : {},
+    ...agent_id ? { agent_id } : {}
+  };
+  savePairedConfig(opts.configPath, config);
+  const who = principal_id && agent_id ? `${principal_id} (${agent_id})` : "(use kojee-mcp without args to start the proxy)";
+  return { message: `Paired as ${who}. Keypair: ${opts.keystorePath}. Config: ${opts.configPath}.` };
+}
+
+export {
+  runPair
+};