kojee-mcp 0.7.5-staging.2 → 0.7.5-staging.20

package/README.md

@@ -11,7 +11,7 @@ There are three ways to connect Kojee to an MCP-capable agent:
 
 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).
+3. **OpenClaw / Hermes — native gateway runtimes.** On those runtimes kojee is registered as the agent's MCP server (so the agent can explore + call kojee tools), and Tandem is a first-class channel wired through the gateway (an in-gateway MCP wake injector on OpenClaw; a sidecar daemon + channel plugin on Hermes). See [Native gateway runtimes](#native-gateway-runtimes-openclaw--hermes).
 
 ## Mobile, Web & Desktop (Recommended)
 
@@ -189,8 +189,11 @@ Per-runtime config-path / hooks-path overrides: `--config-path`, `--hooks-path`.
   injector — no webhook receiver, no `--webhook-url`.
 - **hermes** — a **daemon** feeding a webhook receiver. `init --runtime hermes`
   (or `connect --runtime hermes`) validates the webhook env and prints + records
-  the env to export (secret redacted) into a source-able `~/.kojee/hermes.env`.
-  `--webhook-url` is optional (defaults to the hermes-plugin loopback receiver).
+  the env (secret redacted) into a single-quoted `~/.kojee/hermes.env`, loaded
+  with `set -a; . ~/.kojee/hermes.env; set +a` (the installed service unit's
+  `ExecStart` uses this exact wrapper so every var is exported to the daemon on
+  both Linux and macOS). `--webhook-url` is optional (defaults to the
+  hermes-plugin loopback receiver).
 
 `kojee-mcp init --uninstall` is runtime-aware (uses the recorded runtime when
 `--runtime` is omitted). `kojee-mcp doctor` is runtime-aware too.
@@ -428,12 +431,14 @@ constant beside it):
   ```
   { type, id, tandem_id, cursor, time,
     from{ member_id, principal, agent_id?, session_id?, displayname },
-    kind, content{ body, format? }, mentions?, reply_to?, severity? }
+    kind, content{ body, format? }, mentions?, reply_to?, severity?, wake?, wake_reason? }
   ```
 
   `from.session_id` and `severity` are present only when the wire carried them.
-  There is no `sender` object — the body is fully normalized and carries
-  `from.principal`.
+  `wake` is the backend's per-subscriber wake stamp (always `true` here — the sink
+  fires only for delivered wakes) and `wake_reason` names why it woke (e.g.
+  `direct`/`mention`), present when the backend stamped it. There is no `sender`
+  object — the body is fully normalized and carries `from.principal`.
 - **Verify** the `X-Kojee-Signature` header: it is the hex-encoded SHA-256 HMAC
   of the **raw request-body bytes**, keyed by `KOJEE_WEBHOOK_SECRET`. Recompute
   over the received bytes (before any re-serialization) and timing-safe compare;
@@ -571,6 +576,22 @@ npm run dev:stub
 # Stub listens on http://localhost:8765
 ```
 
+## Releases & staging versioning
+
+Two channels, and one rule that keeps them clean:
+
+- **`latest` (production)** — a **manual** release off `main` (`npm publish` → `latest`, or promote a verified staging build via `npm dist-tag add kojee-mcp@<ver> latest`).
+- **`staging` (pre-release)** — **automatic** on every merge to the `staging` branch, via `.github/workflows/publish-staging.yml`, published under the `staging` dist-tag (never touches `latest`).
+
+**How the staging version is computed** (`scripts/next-staging-version.mjs`):
+
+1. **base** = `package.json.version` with its **PATCH bumped once** — e.g. `0.7.4` → `0.7.5`.
+2. **counter** = `1 + highest existing <base>-staging.N on npm`. This is **per-base**, so it **RESETS to 1 automatically when the base progresses** (a brand-new base has no prior `-staging.N`).
+
+So a run yields e.g. `0.7.5-staging.6`, and once `0.7.5` ships to `latest` and `package.json` moves to `0.7.5`, the next staging build resets to `0.7.6-staging.1`.
+
+> ⚠️ **THE RULE: `package.json.version` must hold the LAST STABLE version — never a `-staging`/`-beta` pre-release.** The CI bumps the patch itself; if the file already carries the *next* version (or a `-beta` whose stable part is the next version), the base **double-bumps**. That is exactly how a `0.7.5-beta.1` base once published `0.7.6-staging.6` instead of the intended `0.7.5-staging.6`. Cutting a stable release is the *only* time `package.json.version` advances, and it advances to the version you just shipped to `latest`.
+
 ## How Approvals Work
 
 Some tools are governed by approval policies configured in the Kojee dashboard. When an agent calls a governed tool:

package/dist/{cc-session-id-RURNIHHC.js → cc-session-id-5HHQJ7VC.js}

@@ -1,10 +1,12 @@
 import {
   SESSION_ID_ENV_VARS,
+  STABLE_RUNTIMES,
   resolveInstanceKey,
   resolveSharedSessionId
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SZLNNMIZ.js";
 export {
   SESSION_ID_ENV_VARS,
+  STABLE_RUNTIMES,
   resolveInstanceKey,
   resolveSharedSessionId
 };

package/dist/{chunk-ZSHCHOPL.js → chunk-676WQSWZ.js}

@@ -1,17 +1,17 @@
 import {
   claudeCodeAdapter
-} from "./chunk-TCWIXG5C.js";
+} from "./chunk-CCVRXJJ2.js";
 import {
   GatewayClient,
   applyStableSessionId
-} from "./chunk-247WFMCJ.js";
+} from "./chunk-AGZ7ZGLY.js";
 import {
   AuthModule
 } from "./chunk-I67C2HYA.js";
 import {
   createMcpServer,
   startMcpServer
-} from "./chunk-A4IOKD4Z.js";
+} from "./chunk-QYZP6QT2.js";
 import {
   findClaudeAncestorPid
 } from "./chunk-XJEBJIQE.js";
@@ -22,6 +22,10 @@ import os from "os";
 import path from "path";
 
 // src/tool-registry.ts
+import { readFileSync, statSync } from "fs";
+import { basename } from "path";
+var UPLOAD_TOOL = "tandem_upload_attachment";
+var MAX_UPLOAD_FILE_BYTES = 25 * 1024 * 1024;
 var ToolRegistry = class {
   constructor(gateway) {
     this.gateway = gateway;
@@ -68,8 +72,87 @@ var ToolRegistry = class {
       }
       this.tools.set(tool.name, tool);
     }
+    this.augmentUploadTool();
     console.error(`[tools] Registered ${this.tools.size} tools from gateway`);
   }
+  /**
+   * Teach the gateway's `tandem_upload_attachment` tool about a `file_path` arg
+   * that THIS proxy resolves in-process (see {@link resolveUploadFilePath}): the
+   * model emits a local path, the proxy reads the bytes and forwards them as
+   * `data_base64`, so a multi-MB image never has to be generated into the model's
+   * tool call. Purely additive — the original `data_base64` shape still works. A
+   * no-op if the gateway doesn't expose the tool (older backend).
+   */
+  augmentUploadTool() {
+    const tool = this.tools.get(UPLOAD_TOOL);
+    if (!tool) return;
+    const schema = { ...tool.inputSchema ?? {} };
+    const properties = { ...schema.properties ?? {} };
+    if ("file_path" in properties) return;
+    properties.file_path = {
+      type: "string",
+      description: "Absolute path to a local image file. Your local kojee-mcp-server reads the bytes and uploads them for you (downscaled server-side), so the image is NEVER placed in your prompt/tool-call. Prefer this over data_base64 for photos. Provide file_path OR data_base64, not both; filename is derived from the path when omitted."
+    };
+    schema.properties = properties;
+    if (Array.isArray(schema.required)) {
+      schema.required = schema.required.filter(
+        (k) => k !== "data_base64" && k !== "filename"
+      );
+    }
+    const dependent = {
+      ...schema.dependentRequired ?? {},
+      data_base64: ["filename"]
+    };
+    schema.dependentRequired = dependent;
+    this.tools.set(UPLOAD_TOOL, { ...tool, inputSchema: schema });
+  }
+  /**
+   * Resolve a `tandem_upload_attachment` call that used `file_path`: read the file
+   * locally, base64-encode the RAW bytes (Buffer→base64 is byte-exact — no text
+   * round-trip, so no U+FFFD corruption), and rewrite the args to the `data_base64`
+   * shape the gateway expects. Returns the args to forward, or throws with a clear
+   * message the caller surfaces as an isError result.
+   */
+  resolveUploadFilePath(args) {
+    const filePath = args.file_path;
+    const hasFilePath = typeof filePath === "string" && filePath.length > 0;
+    const hasBase64 = typeof args.data_base64 === "string" && args.data_base64.length > 0;
+    const hasFilename = typeof args.filename === "string" && args.filename.trim().length > 0;
+    if (!hasFilePath) {
+      if (hasBase64 && !hasFilename) {
+        throw new Error("filename is required when uploading with data_base64");
+      }
+      return args;
+    }
+    if (hasBase64) {
+      throw new Error("provide file_path OR data_base64, not both");
+    }
+    let size;
+    try {
+      const st = statSync(filePath);
+      if (!st.isFile()) throw new Error("not a regular file");
+      size = st.size;
+    } catch (err) {
+      throw new Error(`cannot read file_path '${filePath}': ${err?.message ?? String(err)}`);
+    }
+    if (size > MAX_UPLOAD_FILE_BYTES) {
+      throw new Error(
+        `file_path is ${size} bytes; exceeds the ${MAX_UPLOAD_FILE_BYTES}-byte upload cap`
+      );
+    }
+    const buf = readFileSync(filePath);
+    if (buf.length > MAX_UPLOAD_FILE_BYTES) {
+      throw new Error(
+        `file_path is ${buf.length} bytes; exceeds the ${MAX_UPLOAD_FILE_BYTES}-byte upload cap`
+      );
+    }
+    const { file_path: _drop, ...rest } = args;
+    return {
+      ...rest,
+      data_base64: buf.toString("base64"),
+      filename: hasFilename ? args.filename : basename(filePath)
+    };
+  }
   /**
    * Return all registered tools for the MCP ListTools response — gateway tools
    * first (minus any a local tool shadows), then local tools.
@@ -114,9 +197,20 @@ var ToolRegistry = class {
         isError: true
       };
     }
+    let outgoing = args;
+    if (name === UPLOAD_TOOL) {
+      try {
+        outgoing = this.resolveUploadFilePath(args);
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: err?.message ?? String(err) }],
+          isError: true
+        };
+      }
+    }
     return this.gateway.sendRpc("tools/call", {
       name,
-      arguments: args
+      arguments: outgoing
     });
   }
   /** Total number of registered tools (gateway + local, shadowed names once). */
@@ -295,9 +389,11 @@ async function startProxy(config) {
   }
   console.error(`[kojee-mcp] Tandem memberships: ${tandemMembershipCount === -1 ? "unknown" : tandemMembershipCount}`);
   let server;
-  const { selectDelivery } = await import("./registry-XJ67EO22.js");
+  const isHeadlessDaemon = !!process.env["KOJEE_HEADLESS"] || !!process.env["KOJEE_WEBHOOK_EXPECTED"];
+  const { selectDelivery } = await import("./registry-MCJAVXJW.js");
   const delivery = selectDelivery(adapter.runtime, {
     supportsChannels: adapter.supportsChannels,
+    headless: isHeadlessDaemon,
     // Per-window delivered mirror for the tandem_pending tool (codex only —
     // other runtimes' deliveries ignore this even when passed).
     ...pendingState ? { onDelivered: (e) => pendingState.noteDelivered(e.tandem_id, e.cursor) } : {}
@@ -331,10 +427,21 @@ async function startProxy(config) {
     }
     for (const step of started.teardown) teardownSteps.push(step);
   } else {
+    if (process.env["KOJEE_WEBHOOK_EXPECTED"]) {
+      console.error(
+        "[kojee-mcp] webhook expected (KOJEE_WEBHOOK_EXPECTED=1) but no delivery configured \u2014 env injection likely failed; check the daemon env file (~/.kojee/hermes.env) / service wiring (ExecStart should be `/bin/sh -c 'set -a; . <envFile>; set +a; exec <bin>'`)."
+      );
+    }
     server = createMcpServer(registry, adapter, tandemMembershipCount);
   }
-  process.stdin.on("end", () => shutdown("stdin end"));
-  process.stdin.on("close", () => shutdown("stdin close"));
+  if (!isHeadlessDaemon) {
+    process.stdin.on("end", () => shutdown("stdin end"));
+    process.stdin.on("close", () => shutdown("stdin close"));
+  } else {
+    console.error(
+      "[kojee-mcp] headless daemon (KOJEE_HEADLESS / KOJEE_WEBHOOK_EXPECTED): stdin EOF ignored; lifecycle owned by the service manager (SIGTERM/SIGINT/SIGHUP)."
+    );
+  }
   process.on("SIGHUP", () => shutdown("SIGHUP"));
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
@@ -351,6 +458,55 @@ async function startProxy(config) {
       "[kojee-mcp] no resolvable Claude ancestor (Windows fallback) \u2014 parent-liveness watchdog not armed; stdin close/end + SIGHUP/SIGINT/SIGTERM cover shutdown, and per-window wake is preserved via the session-id discovery key."
     );
   }
+  if (isHeadlessDaemon && activeStreamHandle) {
+    const { createStreamWatchdog } = await import("./stream-watchdog-K2AWNCQW.js");
+    const { recordFlap } = await import("./flap-log-D4KG7RK4.js");
+    const handleForWatchdog = activeStreamHandle;
+    const bootAt = Date.now();
+    const streamWatchdog = createStreamWatchdog({
+      getState: () => {
+        const s = handleForWatchdog.getState();
+        return { connected: s.connected, lastEventAt: s.lastEventAt };
+      },
+      onUnhealthy: ({ disconnectedForMs, reason }) => {
+        recordFlap({
+          ts: Date.now(),
+          instanceKey,
+          reason,
+          disconnectedForMs,
+          uptimeMs: Date.now() - bootAt
+        });
+        console.error(
+          `[kojee-mcp] stream-liveness watchdog: ${reason} \u2014 self-exiting(1); the service manager (Restart=always) will start a fresh process. Repeated exits are recorded and surfaced by \`kojee-mcp doctor\` (flap detection).`
+        );
+        process.exit(1);
+      }
+    });
+    streamWatchdog.start();
+    teardownSteps.push(() => streamWatchdog.stop());
+  }
+  if (!isHeadlessDaemon && activeStreamHandle) {
+    const { createStreamWatchdog } = await import("./stream-watchdog-K2AWNCQW.js");
+    const handleForWatchdog = activeStreamHandle;
+    const streamWatchdog = createStreamWatchdog({
+      getState: () => {
+        const s = handleForWatchdog.getState();
+        return { connected: s.connected, lastEventAt: s.lastEventAt };
+      },
+      reArmAfterUnhealthy: true,
+      onUnhealthy: ({ reason }) => {
+        console.error(
+          `[kojee-mcp] stream-liveness watchdog: ${reason} \u2014 reconnecting in place (no supervisor on the stdio path; recovering the wedged stream).`
+        );
+        try {
+          handleForWatchdog.reconnect();
+        } catch {
+        }
+      }
+    });
+    streamWatchdog.start();
+    teardownSteps.push(() => streamWatchdog.stop());
+  }
   await startMcpServer(server);
 }
 async function enrollAndDiscover(config, keystorePath, isRetry = false) {

package/dist/{chunk-FJUAMJHU.js → chunk-6NPMVZD7.js}

@@ -1,7 +1,32 @@
+// src/version.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var FALLBACK_VERSION = "0.0.0-unknown";
+function resolveVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const parsed = JSON.parse(
+      fs.readFileSync(path.join(here, "..", "package.json"), "utf8")
+    );
+    return typeof parsed?.version === "string" && parsed.version ? parsed.version : FALLBACK_VERSION;
+  } catch (err) {
+    process.stderr.write(
+      `kojee-mcp: could not resolve version from package.json, falling back to ${FALLBACK_VERSION}: ${String(err)}
+`
+    );
+    return FALLBACK_VERSION;
+  }
+}
+var VERSION = resolveVersion();
+
 // src/tandem/recipe.ts
 var SEND_BODY_PARAM = "body";
+function monitorPackageSpec() {
+  return VERSION && VERSION !== "0.0.0-unknown" ? `kojee-mcp@${VERSION}` : "kojee-mcp";
+}
 function buildMonitorCommand(logPath) {
-  return `npx kojee-mcp tail "${logPath}"`;
+  return `npx ${monitorPackageSpec()} tail --wake-only "${logPath}"`;
 }
 function buildMonitorSpawn(logPath) {
   return `Monitor(command=\`${buildMonitorCommand(logPath)}\`, persistent=true, description="kojee Tandem events")`;
@@ -15,26 +40,36 @@ function buildReplyRecipe(event) {
 function buildCatchUpNote() {
   return "Cursors are allocated per-Tandem, and the event-log interleaves every subscribed room into one stream \u2014 so track the last `cursor=<n>` you saw keyed by the line's `tandem=<id>` field, and only treat a jump WITHIN the same tandem_id as a gap (a jump between lines from different rooms is normal interleaving, not a missed message). If the cursor jumps within one tandem, 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 for THAT tandem>).";
 }
+function buildSessionStartReminder(source) {
+  const freshProcess = source === "startup" || source === "resume";
+  const catchUp = "Catch up on anything sent while your context was away: " + buildCatchUpNote();
+  if (!freshProcess) {
+    return "[kojee] Context reset \u2014 your kojee Tandem connection and wake watcher from this process are still running; do NOT spawn another watcher (a second one would double-deliver every wake). " + catchUp;
+  }
+  return "[kojee] New session \u2014 reconnect to Tandem before anything else. FIRST ACTION this turn, before other work: ensure your kojee wake watcher is running \u2014 if you don't already have one, spawn it now by running the exact Monitor(command=`\u2026 kojee-mcp tail \u2026`, persistent=true) call given in your kojee MCP server instructions (they carry the version-pinned command + your live event-log path). Without it you receive no Tandem wakes. THEN " + catchUp;
+}
 function buildCondensedTandemRules() {
   return "Tandem ground rules: (1) catch up before you speak \u2014 fetch messages since your last cursor (cursors are per-Tandem); never answer from a stale view. (2) close every loop \u2014 taking / done (with evidence) / blocked, said out loud; silence is a bug on a team. (3) your seat_name IS your room identity \u2014 keep it stable across sessions and reconnects. (4) plan your wake path per task and set your wake filter deliberately (heads-down \u2192 mentions; waiting on one reply \u2192 listen; co-working \u2192 all), and tell the room your posture WHEN IT CHANGES \u2014 skip the check-in ceremony when you are merely re-joining/reconnecting with the same posture. (5) send all replies and check-ins as kind=message \u2014 never kind=status; status is lifecycle-only (joined/left, system-generated).";
 }
 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()}.`;
 }
-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? }";
+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?, wake?, wake_reason? }";
 function buildWebhookReceiverNote(sig) {
   const header = sig?.header ?? "X-Kojee-Signature";
   const prefix = sig?.prefix ?? "";
   const digestDesc = prefix ? `the literal prefix \`${prefix}\` followed by the hex-encoded SHA-256 HMAC` : "the hex-encoded SHA-256 HMAC";
-  return "Webhook sink (optional, OFF unless KOJEE_WEBHOOK_URL + KOJEE_WEBHOOK_SECRET are set): the proxy POSTs every Tandem event as JSON to your endpoint. The body is the canonical normalized TandemEvent \u2014 " + WEBHOOK_BODY_SHAPE + ` \u2014 where from.session_id and severity are present only when the wire carried them (the body is fully normalized: it carries from.principal, never the raw backend sender envelope). To build a receiver: (1) verify the ${header} header \u2014 it is ${digestDesc} of the RAW request body bytes keyed by your KOJEE_WEBHOOK_SECRET; recompute over the received bytes and timing-safe compare, reject mismatches. (2) Dedupe by message_id \u2014 the body's \`id\`, also in the X-Kojee-Delivery header: delivery is AT-LEAST-ONCE (the proxy replays backlog from the cursor on restart), so the same event may arrive more than once \u2014 there is no exactly-once promise.`;
+  return "Webhook sink (optional, OFF unless KOJEE_WEBHOOK_URL + KOJEE_WEBHOOK_SECRET are set): the proxy POSTs every Tandem event as JSON to your endpoint. The body is the canonical normalized TandemEvent \u2014 " + WEBHOOK_BODY_SHAPE + ` \u2014 where from.session_id and severity are present only when the wire carried them (the body is fully normalized: it carries from.principal, never the raw backend sender envelope). \`wake\` is the backend's per-subscriber wake stamp (always true here \u2014 the sink fires only for delivered wakes) and \`wake_reason\` names WHY it woke (e.g. direct/mention), present when the backend stamped it. To build a receiver: (1) verify the ${header} header \u2014 it is ${digestDesc} of the RAW request body bytes keyed by your KOJEE_WEBHOOK_SECRET; recompute over the received bytes and timing-safe compare, reject mismatches. (2) Dedupe by message_id \u2014 the body's \`id\`, also in the X-Kojee-Delivery header: delivery is AT-LEAST-ONCE (the proxy replays backlog from the cursor on restart), so the same event may arrive more than once \u2014 there is no exactly-once promise.`;
 }
 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 {
+  VERSION,
   buildMonitorSpawn,
   buildReplyRecipe,
   buildCatchUpNote,
+  buildSessionStartReminder,
   buildCondensedTandemRules,
   buildMonitorNudge,
   buildWebhookReceiverNote,

package/dist/{chunk-247WFMCJ.js → chunk-AGZ7ZGLY.js}

@@ -13,10 +13,13 @@ import {
 } from "./chunk-PPTKGWFF.js";
 import {
   resolveInstanceKey
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SZLNNMIZ.js";
 
 // src/gateway-client.ts
 import crypto from "crypto";
+import zlib from "zlib";
+import { promisify } from "util";
+var gunzipAsync = promisify(zlib.gunzip);
 var GatewayClient = class {
   constructor(brokerUrl, token, privateKey, kid, sessionId) {
     this.brokerUrl = brokerUrl;
@@ -117,7 +120,7 @@ var GatewayClient = class {
         isError: true
       };
     }
-    const rpcResponse = await response.json();
+    const rpcResponse = await this.readJsonBody(response);
     if (rpcResponse.error) {
       return translateJsonRpcError(rpcResponse.error);
     }
@@ -154,6 +157,14 @@ var GatewayClient = class {
     );
     return {
       "Content-Type": "application/json",
+      // Accept gzip (bandwidth win) but DECOMPRESS EXPLICITLY on read (readJsonBody),
+      // rather than relying on the HTTP client's transparent decompression — that
+      // was inconsistent across the two undici versions in play (Node-builtin fetch
+      // here vs the npm undici used by the SSE stream), which let raw gzip bytes
+      // (`1f 8b 08…`) reach JSON.parse and wedge every in-session read (incident
+      // 2026-09-22, hot-fixed first with `identity`). We request ONLY gzip (never
+      // br/deflate) so readJsonBody's gzip-magic check fully covers what's on the wire.
+      "Accept-Encoding": "gzip",
       Authorization: `DPoP ${this.token}`,
       DPoP: proof,
       "Mcp-Session-Id": getSessionId()
@@ -187,11 +198,27 @@ var GatewayClient = class {
   }
   async tryParseErrorBody(response) {
     try {
-      return await response.json();
+      return await this.readJsonBody(response);
     } catch {
       return null;
     }
   }
+  /**
+   * Read + JSON-parse a response body, decompressing gzip EXPLICITLY. The gateway
+   * may return `Content-Encoding: gzip`; transparent decompression by the HTTP
+   * client proved unreliable in the long-lived in-session context (two undici
+   * versions in play), so we detect the gzip magic (0x1f 0x8b) on the raw bytes
+   * and gunzip ourselves. Plain (already-decompressed or identity) bodies pass
+   * through untouched — valid JSON never starts with 0x1f, so there's no false
+   * positive. Version-agnostic: correct whether or not the client transparently
+   * decompressed.
+   */
+  async readJsonBody(response) {
+    const buf = Buffer.from(await response.arrayBuffer());
+    const isGzip = buf.length >= 2 && buf[0] === 31 && buf[1] === 139;
+    const text = (isGzip ? await gunzipAsync(buf) : buf).toString("utf8");
+    return JSON.parse(text);
+  }
 };
 
 // src/runtime/stable-session.ts

package/dist/chunk-AXBJQJKA.js

@@ -0,0 +1,65 @@
+// src/hooks/hook-command.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+function npxHookCommand(type) {
+  return `npx -y kojee-mcp hook --type=${type}`;
+}
+var NPX_CACHE_RE = /[\\/]_npx[\\/]/;
+function resolveCliEntry(moduleUrl = import.meta.url) {
+  try {
+    const here = fileURLToPath(moduleUrl);
+    const candidate = path.join(path.dirname(here), "cli.js");
+    if (!fs.existsSync(candidate)) return null;
+    if (NPX_CACHE_RE.test(candidate)) return null;
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+function stableExecPath(execPath = process.execPath) {
+  const m = /^(.*)\/Cellar\/node(?:@[^/]+)?\/[^/]+\/bin\/node$/.exec(execPath);
+  if (!m || !m[1]) return execPath;
+  const alias = path.join(m[1], "bin", "node");
+  try {
+    if (!fs.existsSync(alias)) return execPath;
+    const real = fs.realpathSync(alias);
+    return /[\\/]Cellar[\\/]node(@[^/]+)?[\\/]/.test(real) ? alias : execPath;
+  } catch {
+    return execPath;
+  }
+}
+function buildHookCommand(type, opts = {}) {
+  const cliEntry = opts.cliEntry !== void 0 ? opts.cliEntry : resolveCliEntry();
+  if (!cliEntry) return npxHookCommand(type);
+  const execPath = stableExecPath(opts.execPath ?? process.execPath);
+  return `"${execPath}" "${cliEntry}" hook --type=${type}`;
+}
+var PINNED_HOOK_RE = /^"[^"]+" "[^"]+" hook --type=(stop|user-prompt-submit|session-start|codex-stop|codex-prompt-submit)$/;
+function isKojeeHookCommand(command) {
+  if (command.startsWith("npx -y kojee-mcp hook --type=")) return true;
+  return PINNED_HOOK_RE.test(command);
+}
+function classifyHookCommand(command, deps = {}) {
+  if (command.startsWith("npx -y kojee-mcp hook --type=")) return "npx";
+  if (!PINNED_HOOK_RE.test(command)) return "foreign";
+  const paths = [...command.matchAll(/"([^"]+)"/g)].map((m) => m[1] ?? "");
+  const cliPath = paths[1] ?? "";
+  if (NPX_CACHE_RE.test(cliPath)) return "pinned-ephemeral";
+  const exists = deps.exists ?? ((p) => {
+    try {
+      return fs.existsSync(p);
+    } catch {
+      return true;
+    }
+  });
+  if (cliPath && !exists(cliPath)) return "pinned-broken";
+  return "pinned-durable";
+}
+
+export {
+  npxHookCommand,
+  buildHookCommand,
+  isKojeeHookCommand,
+  classifyHookCommand
+};

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

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

package/dist/{chunk-WBXU27BF.js → chunk-FNMKP34Y.js}

@@ -7,7 +7,7 @@ import {
 } from "./chunk-XJEBJIQE.js";
 import {
   resolveSharedSessionId
-} from "./chunk-KNEJTD6G.js";
+} from "./chunk-SZLNNMIZ.js";
 
 // src/hooks/discovery.ts
 async function resolveHookDiscovery(stdinSessionId, deps = {}) {

package/dist/chunk-GEGUWQYT.js

@@ -0,0 +1,90 @@
+// src/wizard/capabilities/hermes-mcp-config.ts
+import fs from "fs";
+import path from "path";
+import { parseDocument, isMap } from "yaml";
+var HERMES_MCP_SERVER_NAME = "kojee";
+var HERMES_INSTANCE_KEY = "hermes-gateway";
+var HERMES_MCP_CONNECT_TIMEOUT_S = 120;
+function defaultHermesConfigPath(homeDir) {
+  return path.join(homeDir, ".hermes", "config.yaml");
+}
+function buildKojeeEntry(binPath) {
+  return {
+    command: binPath,
+    args: [],
+    env: {
+      KOJEE_RUNTIME: "hermes",
+      KOJEE_INSTANCE: HERMES_INSTANCE_KEY,
+      // Vanilla tools-only proxy: NEVER a second webhook delivery (see header).
+      KOJEE_WEBHOOK_URL: ""
+    },
+    connect_timeout: HERMES_MCP_CONNECT_TIMEOUT_S
+  };
+}
+function resolveMode(filePath) {
+  try {
+    return fs.statSync(filePath).mode & 511;
+  } catch {
+    return 384;
+  }
+}
+function atomicWrite(filePath, content, mode) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  fs.writeFileSync(tmp, content, { mode });
+  fs.renameSync(tmp, filePath);
+}
+function backupSuffix(now) {
+  return (now ? now() : /* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+}
+function writeHermesMcpConfig(configPath, opts) {
+  let raw = null;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch {
+    raw = null;
+  }
+  let backedUp;
+  let doc = parseDocument("");
+  if (raw !== null && raw.trim() !== "") {
+    const parsed = parseDocument(raw);
+    if (parsed.errors.length > 0) {
+      backedUp = `${configPath}.corrupt-${backupSuffix(opts.now)}`;
+      fs.copyFileSync(configPath, backedUp);
+    } else {
+      doc = parsed;
+    }
+  }
+  if (doc.hasIn(["mcp_servers"]) && !isMap(doc.getIn(["mcp_servers"], true))) {
+    doc.deleteIn(["mcp_servers"]);
+  }
+  doc.setIn(["mcp_servers", HERMES_MCP_SERVER_NAME], buildKojeeEntry(opts.binPath));
+  atomicWrite(configPath, String(doc), resolveMode(configPath));
+  return { configPath, ...backedUp ? { backedUp } : {} };
+}
+function removeHermesMcpServer(configPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch {
+    return false;
+  }
+  const doc = parseDocument(raw);
+  if (doc.errors.length > 0) return false;
+  if (!doc.hasIn(["mcp_servers", HERMES_MCP_SERVER_NAME])) return false;
+  doc.deleteIn(["mcp_servers", HERMES_MCP_SERVER_NAME]);
+  const servers = doc.getIn(["mcp_servers"], true);
+  if (isMap(servers) && servers.items.length === 0) {
+    doc.deleteIn(["mcp_servers"]);
+  }
+  atomicWrite(configPath, String(doc), resolveMode(configPath));
+  return true;
+}
+
+export {
+  HERMES_MCP_SERVER_NAME,
+  HERMES_INSTANCE_KEY,
+  defaultHermesConfigPath,
+  writeHermesMcpConfig,
+  removeHermesMcpServer
+};

package/dist/{chunk-NE2F5CKS.js → chunk-LKGKDZSO.js}

@@ -87,18 +87,22 @@ function createCachedOpenclawWakeResolver(opts = {}) {
     return resolution;
   };
 }
-async function postOpenclawWake(target, body, deps = {}) {
+function openclawAgentUrl(wakeUrl) {
+  return wakeUrl.replace(/\/wake$/, "/agent");
+}
+async function postOpenclawAgent(target, body, deps = {}) {
   const doFetch = deps.fetch ?? fetch;
+  const url = openclawAgentUrl(target.url);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? 4e3);
   try {
-    const res = await doFetch(target.url, {
+    const res = await doFetch(url, {
       method: "POST",
       headers: { "content-type": "application/json", authorization: `Bearer ${target.token}` },
-      body: JSON.stringify(body),
+      body: JSON.stringify({ name: "Kojee", wakeMode: "now", ...body }),
       signal: controller.signal
     });
-    return res.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: `wake POST ${res.status}` };
+    return res.ok ? { ok: true, status: res.status } : { ok: false, status: res.status, error: `agent POST ${res.status}` };
   } catch (err) {
     return { ok: false, error: err.message };
   } finally {
@@ -109,5 +113,5 @@ async function postOpenclawWake(target, body, deps = {}) {
 export {
   resolveOpenclawWakeTarget,
   createCachedOpenclawWakeResolver,
-  postOpenclawWake
+  postOpenclawAgent
 };