@zeph-to/hook-sdk 1.10.0 → 1.10.2

package/README.md

@@ -1,5 +1,10 @@
 # @zeph-to/hook-sdk
 
+[![npm](https://img.shields.io/npm/v/@zeph-to/hook-sdk.svg)](https://www.npmjs.com/package/@zeph-to/hook-sdk)
+[![downloads](https://img.shields.io/npm/dm/@zeph-to/hook-sdk.svg)](https://www.npmjs.com/package/@zeph-to/hook-sdk)
+[![node](https://img.shields.io/node/v/@zeph-to/hook-sdk.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@zeph-to/hook-sdk.svg)](./LICENSE)
+
 Push notification SDK + CLI for [Zeph](https://zeph.to), with an optional
 resident listener that **drives Claude Code / Codex / Gemini sessions
 from your phone** by injecting messages into named tmux sessions.

package/dist/listener.d.ts

@@ -34,6 +34,15 @@ interface AgentSession {
 export declare const checkRateLimit: (session: string, now?: number) => boolean;
 /** Read the foreground command in the named tmux session's active pane. */
 export declare const paneCurrentCommand: (session: string) => string | null;
+/**
+ * Mark the cached socket as no longer trustworthy — call this when a
+ * tmux command fails against the cached path. The next findTmuxSocket()
+ * will redo full discovery (default probe → /var/folders walk → lsof
+ * fallback) instead of returning a stale answer. Without this the
+ * listener wedged at "reported 0 session(s)" forever after a tmux
+ * server restart, even when a new server was live and discoverable.
+ */
+export declare const invalidateTmuxSocketCache: () => void;
 /**
  * Parse a `zeph-*` tmux session name into `{project, label}`. For
  * Phase 1 the wrapper only emits `zeph-<project>` (no labels), so the
@@ -50,7 +59,8 @@ export declare const parseSessionName: (name: string) => {
  * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
  * detectClaudeSessionId: CC writes per-session jsonl files at
  * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
- * the cwd with `/` replaced by `-`.
+ * the cwd with `/` replaced by `-`. Cached for 60s — see
+ * claudeSessionCache.
  */
 export declare const detectClaudeSessionId: (cwd: string) => string | null;
 export interface CollectResult {

package/dist/listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAuBH,KAAK,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAG/C,UAAU,YAAY;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2BD,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,MAAK,MAAmB,KAAG,OAgB1E,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,MAAM,GAAG,IAO7D,CAAC;AA6QF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAK3F,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAkB5D,CAAC;AAoEF,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAO,aA0DzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAAO,YAAY,EAAuC,CAAC;AAIvF,UAAU,QAAQ;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,UAAU,cAAc;IACpB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAgCD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GACnB,MAAM,QAAQ,EACd,OAAM,cAAmB,KAC1B,OAQF,CAAC;AA2BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAM,MAAmB,KAAG,MAGnE,CAAC;AAyLF,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA6E3F,CAAC"}
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAuBH,KAAK,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAG/C,UAAU,YAAY;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AA2BD,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,MAAK,MAAmB,KAAG,OAgB1E,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,MAAM,GAAG,IAO7D,CAAC;AAiDF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAG5C,CAAC;AA8NF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAK3F,CAAC;AAuCF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAoEF,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAO,aA+DzC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,QAAO,YAAY,EAAuC,CAAC;AAIvF,UAAU,QAAQ;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,UAAU,cAAc;IACpB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAgCD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GACnB,MAAM,QAAQ,EACd,OAAM,cAAmB,KAC1B,OAQF,CAAC;AA2BF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAM,MAAmB,KAAG,MAGnE,CAAC;AAyLF,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAyF3F,CAAC"}

package/dist/listener.js

@@ -25,7 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleListener = exports.computeListenerDeviceId = exports.handlePush = exports.collectSessions = exports.collectSessionsVerbose = exports.detectClaudeSessionId = exports.parseSessionName = exports.paneCurrentCommand = exports.checkRateLimit = void 0;
+exports.handleListener = exports.computeListenerDeviceId = exports.handlePush = exports.collectSessions = exports.collectSessionsVerbose = exports.detectClaudeSessionId = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -135,6 +135,19 @@ let cachedSocketPath = null;
  *  removes the ambiguity so we don't re-probe every collectSessions
  *  cycle (which was spamming the log with "tmux: default socket OK"). */
 let cacheValid = false;
+/**
+ * Mark the cached socket as no longer trustworthy — call this when a
+ * tmux command fails against the cached path. The next findTmuxSocket()
+ * will redo full discovery (default probe → /var/folders walk → lsof
+ * fallback) instead of returning a stale answer. Without this the
+ * listener wedged at "reported 0 session(s)" forever after a tmux
+ * server restart, even when a new server was live and discoverable.
+ */
+const invalidateTmuxSocketCache = () => {
+    cacheValid = false;
+    cachedSocketPath = null;
+};
+exports.invalidateTmuxSocketCache = invalidateTmuxSocketCache;
 const probeTmuxSocketDetail = (socketPath) => {
     const args = socketPath ? ['-S', socketPath, 'list-sessions'] : ['list-sessions'];
     const r = (0, child_process_1.spawnSync)('tmux', args, {
@@ -379,13 +392,20 @@ const parseSessionName = (name) => {
 exports.parseSessionName = parseSessionName;
 const CLAUDE_PROJECTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.claude', 'projects');
 /**
- * Locate the most recent Claude Code session UUID for the working
- * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
- * detectClaudeSessionId: CC writes per-session jsonl files at
- * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
- * the cwd with `/` replaced by `-`.
+ * Cache for detectClaudeSessionId. The function walks every jsonl file
+ * in `~/.claude/projects/<hash>/` on each call — after weeks of CC use
+ * that directory holds hundreds of session files, and we were calling
+ * this per tmux session per 5-second report cycle. Heavy disk I/O
+ * compounded with multiple sessions caused the report cycle to spike
+ * CPU and starve the host shell.
+ *
+ * The current-session UUID only changes when a new CC session starts
+ * in that directory (rare, on the order of hours), so a 60-second TTL
+ * is safe and cuts the per-cycle stat count by ~12×.
  */
-const detectClaudeSessionId = (cwd) => {
+const claudeSessionCache = new Map();
+const CLAUDE_SESSION_CACHE_TTL_MS = 60_000;
+const doDetectClaudeSessionId = (cwd) => {
     try {
         const projectHash = cwd.replace(/\//g, '-');
         const sessionsDir = (0, path_1.join)(CLAUDE_PROJECTS_DIR, projectHash);
@@ -407,6 +427,32 @@ const detectClaudeSessionId = (cwd) => {
         return null;
     }
 };
+/**
+ * Locate the most recent Claude Code session UUID for the working
+ * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
+ * detectClaudeSessionId: CC writes per-session jsonl files at
+ * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
+ * the cwd with `/` replaced by `-`. Cached for 60s — see
+ * claudeSessionCache.
+ */
+const detectClaudeSessionId = (cwd) => {
+    const now = Date.now();
+    const cached = claudeSessionCache.get(cwd);
+    if (cached && cached.expiresAt > now)
+        return cached.sessionId;
+    // Cap cache size so a long-lived listener that's seen many cwds
+    // doesn't grow unbounded. 64 is plenty for any realistic setup.
+    if (claudeSessionCache.size >= 64) {
+        // Evict the oldest-expiring entry — Map iteration order is
+        // insertion order, so the first key we hit is the oldest.
+        const firstKey = claudeSessionCache.keys().next().value;
+        if (firstKey !== undefined)
+            claudeSessionCache.delete(firstKey);
+    }
+    const sessionId = doDetectClaudeSessionId(cwd);
+    claudeSessionCache.set(cwd, { sessionId, expiresAt: now + CLAUDE_SESSION_CACHE_TTL_MS });
+    return sessionId;
+};
 exports.detectClaudeSessionId = detectClaudeSessionId;
 // U+241F "Symbol for Unit Separator" — a *printable* Unicode glyph
 // (3-byte UTF-8) that visually represents the C0 Unit Separator but is
@@ -485,6 +531,11 @@ const collectSessionsVerbose = () => {
     if (list.status !== 0) {
         const stderr = (list.stderr ?? '').toString().trim();
         log(`  tmux list-sessions failed: status=${list.status}${stderr ? ', stderr=' + stderr : ''}`);
+        // Tmux call failed against the cached socket — the server it
+        // pointed at is gone (died, restarted at a different path, etc).
+        // Invalidate so the next cycle re-runs full discovery instead of
+        // wedging the listener at "reported 0 session(s)" forever.
+        (0, exports.invalidateTmuxSocketCache)();
         return { sessions: [], rejected: [] };
     }
     const rawLines = (list.stdout ?? '').split('\n').filter(Boolean);
@@ -842,6 +893,17 @@ const handleListener = async (args) => {
     log(`zeph listener starting — ${wsUrl}`);
     log(`device=${(0, exports.computeListenerDeviceId)()} host=${(0, os_1.hostname)()} pid=${process.pid}`);
     log("Waiting for 'agent.command' pushes from the phone picker. Ctrl-C to stop.");
+    // Heartbeat memory log — once an hour. Lets the user (and us) spot
+    // gradual growth in a long-running daemon before it gets bad enough
+    // to make the host shell unresponsive. The MB counter is human-
+    // readable and tiny enough not to bloat the log.
+    const HEAP_LOG_INTERVAL_MS = 60 * 60 * 1000;
+    const heapLogTimer = setInterval(() => {
+        const m = process.memoryUsage();
+        const mb = (n) => Math.round(n / 1024 / 1024);
+        log(`heap: rss=${mb(m.rss)}MB heapUsed=${mb(m.heapUsed)}MB external=${mb(m.external)}MB`);
+    }, HEAP_LOG_INTERVAL_MS);
+    heapLogTimer.unref();
     let shuttingDown = false;
     let activeHandle = null;
     const stop = (sig) => {

package/dist/wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAwBA,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,QAAO,MAapC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAA2B,CAAC;AAI9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAenD,CAAC;AAkGF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmCtF,CAAC"}
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAwBA,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,QAAO,MAapC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAA2B,CAAC;AAI9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAenD,CAAC;AAmHF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmCtF,CAAC"}

package/dist/wrapper.js

@@ -145,6 +145,23 @@ const resolveCliPath = () => {
  * Failure here is non-fatal — `zeph cc` still launches the agent. The
  * user just loses the phone-bridge feature until they restart.
  */
+/**
+ * Rotate the listener log once it grows past 5 MB. The daemon runs for
+ * days and writes 2-3 lines per 5-s cycle, so without rotation the file
+ * climbs into the tens of megabytes range pretty quickly. We keep the
+ * previous run's tail under `.old` for post-mortem and start fresh.
+ */
+const LISTENER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+const rotateListenerLogIfLarge = () => {
+    try {
+        if (!(0, fs_1.existsSync)(LISTENER_LOG_FILE))
+            return;
+        if ((0, fs_1.statSync)(LISTENER_LOG_FILE).size <= LISTENER_LOG_MAX_BYTES)
+            return;
+        (0, fs_1.renameSync)(LISTENER_LOG_FILE, LISTENER_LOG_FILE + '.old');
+    }
+    catch { /* best-effort */ }
+};
 const ensureListenerRunning = () => {
     if (listenerAlive())
         return;
@@ -153,6 +170,7 @@ const ensureListenerRunning = () => {
         return;
     try {
         (0, fs_1.mkdirSync)(ZEPH_DIR, { recursive: true });
+        rotateListenerLogIfLarge();
         const out = (0, fs_1.openSync)(LISTENER_LOG_FILE, 'a');
         const child = (0, child_process_1.spawn)(process.execPath, [cliPath, 'listener'], {
             detached: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/hook-sdk",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Zeph push notification SDK + CLI for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",