@zeph-to/hook-sdk 1.8.0 → 1.10.0

package/dist/wrapper.d.ts

@@ -0,0 +1,26 @@
+/** Resolve a project name for the tmux session: env > git root > cwd basename. */
+export declare const detectProjectName: () => string;
+/** `zeph-<project>` — the canonical tmux session base name. */
+export declare const tmuxSessionName: (project: string) => string;
+/**
+ * Pick a tmux session name that won't steal focus from another live
+ * `zeph cc`. Strategy:
+ *   - If `<base>` doesn't exist → use it (create new).
+ *   - If `<base>` exists but is detached → use it (reattach).
+ *   - If `<base>` exists *and* has a client attached → try `<base>-2`,
+ *     `<base>-3`, … so the new `zeph cc` gets an independent session
+ *     instead of joining the existing one.
+ * Falls back to `<base>` after 20 attempts (shouldn't realistically hit).
+ *
+ * Detection uses `tmux has-session` and `tmux list-clients`; both are
+ * dependency-free against the user's running tmux server.
+ */
+export declare const findAvailableSession: (base: string) => string;
+/**
+ * Launch the agent in a named tmux session (or directly if nested) and
+ * forward its exit code. `extra` is appended to the agent invocation, so
+ * `zeph cc --resume foo` runs `claude --resume foo` inside the session.
+ * Returns when the agent exits.
+ */
+export declare const handleAgentSession: (agent: string, extra?: string[]) => Promise<number>;
+//# sourceMappingURL=wrapper.d.ts.map

package/dist/wrapper.d.ts.map

@@ -0,0 +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"}

package/dist/wrapper.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleAgentSession = exports.findAvailableSession = exports.tmuxSessionName = exports.detectProjectName = void 0;
+/**
+ * `zeph cc` / `zeph codex` / `zeph gemini` — spawn an agent inside a named
+ * tmux session so the resident listener (`zeph listener`) can address it
+ * by session name to inject messages later.
+ *
+ * The tmux session name follows `zeph-<project>` where <project> resolves
+ * from CLAUDE/CURSOR/WINDSURF_PROJECT_DIR → git repo root → cwd basename.
+ * When the wrapper is invoked from inside an existing tmux session
+ * ($TMUX set) it skips the outer tmux to avoid nesting and execs the
+ * agent directly — letting power users keep their own multiplexer setup.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/** First non-empty value among the supported per-agent project dir env vars. */
+const PROJECT_DIR_ENVS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
+const FALLBACK_NAME = 'project';
+/** basename(), with a stable fallback for edge paths like `/`. */
+const safeBasename = (path) => (0, path_1.basename)(path) || FALLBACK_NAME;
+/** Resolve a project name for the tmux session: env > git root > cwd basename. */
+const detectProjectName = () => {
+    for (const key of PROJECT_DIR_ENVS) {
+        const v = process.env[key];
+        if (v)
+            return safeBasename(v.replace(/\/+$/, ''));
+    }
+    try {
+        const root = (0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (root)
+            return safeBasename(root);
+    }
+    catch { /* not a git repo — fall through */ }
+    return safeBasename(process.cwd());
+};
+exports.detectProjectName = detectProjectName;
+/** `zeph-<project>` — the canonical tmux session base name. */
+const tmuxSessionName = (project) => `zeph-${project}`;
+exports.tmuxSessionName = tmuxSessionName;
+const MAX_SUFFIX_ATTEMPTS = 20;
+/**
+ * Pick a tmux session name that won't steal focus from another live
+ * `zeph cc`. Strategy:
+ *   - If `<base>` doesn't exist → use it (create new).
+ *   - If `<base>` exists but is detached → use it (reattach).
+ *   - If `<base>` exists *and* has a client attached → try `<base>-2`,
+ *     `<base>-3`, … so the new `zeph cc` gets an independent session
+ *     instead of joining the existing one.
+ * Falls back to `<base>` after 20 attempts (shouldn't realistically hit).
+ *
+ * Detection uses `tmux has-session` and `tmux list-clients`; both are
+ * dependency-free against the user's running tmux server.
+ */
+const findAvailableSession = (base) => {
+    for (let i = 0; i < MAX_SUFFIX_ATTEMPTS; i++) {
+        const name = i === 0 ? base : `${base}-${i + 1}`;
+        const has = (0, child_process_1.spawnSync)('tmux', ['has-session', '-t', name], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        if (has.status !== 0)
+            return name; // doesn't exist — fresh session
+        const clients = (0, child_process_1.spawnSync)('tmux', ['list-clients', '-t', name, '-F', '#{client_tty}'], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const attached = (clients.stdout ?? '').trim().length > 0;
+        if (!attached)
+            return name; // exists but detached — reattach
+    }
+    return base;
+};
+exports.findAvailableSession = findAvailableSession;
+/** POSIX shell-quote so passthrough args survive being joined into a tmux shell-command string. */
+const SHELL_SAFE = /^[\w\-./=:@%+,]+$/;
+const shellQuote = (s) => s.length > 0 && SHELL_SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+const targetForAgent = (agent, extra) => {
+    // Already inside tmux → no nested session, just run the agent in the
+    // current pane. Nested tmux prefix collisions are confusing and the
+    // listener can't reach a session it didn't name anyway.
+    if (process.env.TMUX) {
+        return { cmd: agent, args: extra };
+    }
+    const base = (0, exports.tmuxSessionName)((0, exports.detectProjectName)());
+    // Auto-suffix when the default name is taken by another attached
+    // session — lets the user keep `zeph cc` workflow simple and still
+    // get independent sessions when opening multiple terminals in the
+    // same project.
+    const session = (0, exports.findAvailableSession)(base);
+    // `tmux new -A`: attach if the named session exists, else create it.
+    // tmux joins trailing argv into a single shell-command, so flags like
+    // `--resume` would be eaten by tmux's own parser. Build one quoted
+    // shell string instead, which tmux passes through verbatim.
+    const shellCmd = [agent, ...extra].map(shellQuote).join(' ');
+    return { cmd: 'tmux', args: ['new', '-A', '-s', session, shellCmd] };
+};
+// ── Background listener auto-start ────────────────────────────────────
+const ZEPH_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
+const LISTENER_PID_FILE = (0, path_1.join)(ZEPH_DIR, 'listener.pid');
+const LISTENER_LOG_FILE = (0, path_1.join)(ZEPH_DIR, 'listener.log');
+/** True when the PID file points at a still-alive process. */
+const listenerAlive = () => {
+    try {
+        const pid = Number((0, fs_1.readFileSync)(LISTENER_PID_FILE, 'utf-8').trim());
+        if (!Number.isFinite(pid) || pid <= 0)
+            return false;
+        // Signal 0 = existence check; throws when the process is gone.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Path to the running cli.js entry. We're invoked AS cli.js (the bin
+ * shim defined in package.json), so process.argv[1] is our entry point.
+ * Resolves whether the user calls `zeph cc` via the npm-installed shim
+ * or directly via `node dist/cli.js cc`.
+ */
+const resolveCliPath = () => {
+    const entry = process.argv[1];
+    if (!entry)
+        return null;
+    // Sanity check: only autostart when we recognise the entry — refuse
+    // to spawn an unknown binary from a weird invocation.
+    if (!/cli\.(js|ts|mjs|cjs)$/.test(entry))
+        return null;
+    return entry;
+};
+/**
+ * Spawn `zeph listener` in the background if it isn't already running on
+ * this machine. The intent is that the user only ever has to know about
+ * `zeph cc` — the phone-to-tmux bridge tags along automatically. Output
+ * goes to `~/.zeph/listener.log` so it isn't lost on detach; the listener
+ * itself writes its own PID to `~/.zeph/listener.pid` on startup and
+ * removes it on graceful exit, so subsequent `zeph cc` invocations skip
+ * the spawn when a listener is already up.
+ *
+ * Failure here is non-fatal — `zeph cc` still launches the agent. The
+ * user just loses the phone-bridge feature until they restart.
+ */
+const ensureListenerRunning = () => {
+    if (listenerAlive())
+        return;
+    const cliPath = resolveCliPath();
+    if (!cliPath || !(0, fs_1.existsSync)(cliPath))
+        return;
+    try {
+        (0, fs_1.mkdirSync)(ZEPH_DIR, { recursive: true });
+        const out = (0, fs_1.openSync)(LISTENER_LOG_FILE, 'a');
+        const child = (0, child_process_1.spawn)(process.execPath, [cliPath, 'listener'], {
+            detached: true,
+            stdio: ['ignore', out, out],
+            env: { ...process.env, ZEPH_LISTENER_AUTOSTART: '1' },
+        });
+        child.unref();
+        console.log(`zeph: listener autostarted in background (log: ${LISTENER_LOG_FILE})`);
+    }
+    catch (err) {
+        console.error(`zeph: listener autostart failed: ${err.message}`);
+    }
+};
+/**
+ * Launch the agent in a named tmux session (or directly if nested) and
+ * forward its exit code. `extra` is appended to the agent invocation, so
+ * `zeph cc --resume foo` runs `claude --resume foo` inside the session.
+ * Returns when the agent exits.
+ */
+const handleAgentSession = (agent, extra = []) => {
+    // Best-effort: make sure the phone-bridge daemon is running before we
+    // launch the agent. The user shouldn't need to remember a second
+    // command for the picker on their phone to work.
+    ensureListenerRunning();
+    return new Promise((resolve) => {
+        const { cmd, args } = targetForAgent(agent, extra);
+        const start = Date.now();
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: 'inherit' });
+        child.on('exit', (code) => {
+            const dur = Date.now() - start;
+            // Short-lived non-zero exits are the symptom of "ran from a
+            // pane that isn't a real TTY" (iTerm tmux integration pane,
+            // some IDE terminals). The user otherwise just sees their
+            // shell return with `[exited]` and no clue what went wrong.
+            if (code && code !== 0 && dur < 2000) {
+                console.error(`zeph: ${cmd} ${args.join(' ')} exited ${code} after ${dur}ms.\n` +
+                    `  If this terminal is itself inside tmux (or an iTerm/Warp\n` +
+                    `  tmux-integration pane), run \`zeph cc\` from a plain shell\n` +
+                    `  pane instead — \`tmux new\` needs a real TTY to attach.`);
+            }
+            resolve(code ?? 0);
+        });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                console.error(`zeph: '${cmd}' not found on PATH`);
+                resolve(127);
+            }
+            else {
+                console.error(`zeph: failed to spawn ${cmd}: ${err.message}`);
+                resolve(1);
+            }
+        });
+    });
+};
+exports.handleAgentSession = handleAgentSession;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zeph-to/hook-sdk",
-  "version": "1.8.0",
-  "description": "Zeph push notification SDK + CLI — zero dependencies",
+  "version": "1.10.0",
+  "description": "Zeph push notification SDK + CLI for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -28,6 +28,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
     "typescript": "^5.8.0",
     "vitest": "^2.1.9"
   },
@@ -62,5 +63,9 @@
     "claude",
     "devtools"
   ],
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.3",
+    "ws": "^8.21.0"
+  }
 }