@zeph-to/hook-sdk 1.9.0 → 1.10.1

package/README.md

@@ -1,12 +1,23 @@
 # @zeph-to/hook-sdk
 
-Push notification SDK + CLI for [Zeph](https://zeph.to). The `ZephHook` SDK uses native `fetch` with no runtime dependencies; the `zeph` CLI adds `@inquirer/prompts` for its interactive installer.
+[![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.
+
+- `ZephHook` SDK — native `fetch`, no runtime deps. Send/list/dismiss pushes.
+- `zeph` CLI — install Zeph plugins, send pushes, run agents under tmux,
+  and listen for inbound messages from your phone.
 
 ## Installation
 
 ```bash
-npm install @zeph-to/hook-sdk
-# or
+npm install -g @zeph-to/hook-sdk
+# or for one-off use
 npx @zeph-to/hook-sdk notify --title "Hello"
 ```
 
@@ -20,7 +31,214 @@ npx @zeph-to/hook-sdk install
 npx @zeph-to/hook-sdk install --key ak_... --hook hook_...
 ```
 
-Saves to `~/.zeph/config.json`. All Zeph tools (CLI, MCP server, plugin hooks) read this file.
+Saves to `~/.zeph/config.json`. All Zeph tools (CLI, MCP server, plugin
+hooks, listener) read this file.
+
+To **send** notifications:
+
+```bash
+zeph notify --title "Deploy done" --body "v2.1.0 shipped"
+```
+
+To **drive a Claude Code / Codex / Gemini session from your phone**, see
+[Remote Control](#remote-control) below.
+
+## Remote Control
+
+> Send messages from your phone *into* a live Claude Code / Codex /
+> Gemini session — even after a `zeph_ask` polling window has expired.
+
+The MCP tools `zeph_ask` / `zeph_prompt` / `zeph_input` open a polling
+loop on a fixed timeout (120–600 s). Once that window closes the
+session becomes unaddressable from the phone, even though it's still
+running. The `zeph listener` daemon fixes this by keeping a persistent
+WebSocket open to Zeph and injecting matching messages into a *named*
+tmux session via `tmux send-keys`.
+
+### Architecture
+
+```
+[phone — "Active Agents" picker on Zeph app]
+   │  selects session, types message
+   ▼  POST /pushes/send  { type: 'agent.command',
+   │                       agentSessionName: 'zeph-myapp',
+   │                       body: '리팩토링 마무리해줘' }
+[Zeph backend]
+   │  WebSocket fan-out (push.new)
+   ▼
+[zeph listener — resident daemon, started by `zeph cc` automatically]
+   │  tmux send-keys -l -t zeph-myapp "리팩토링 마무리해줘" + Enter
+   ▼
+[tmux session "zeph-myapp" running claude / codex / gemini]
+```
+
+The listener also reports its tmux session inventory back to the server
+every 5 seconds, so the phone picker stays in sync — no manual
+configuration needed once a session is running.
+
+### Setup
+
+1. **Install tmux.** The listener uses `send-keys`; the wrapper spawns
+   named sessions. `brew install tmux` on macOS, `apt install tmux` on
+   Debian/Ubuntu.
+
+2. **Add `wsUrl` to `~/.zeph/config.json`** (the WebSocket endpoint of
+   your Zeph backend — CDK output `WsApiUrl`):
+
+   ```json
+   {
+     "apiKey": "ak_...",
+     "hookId": "hook_...",
+     "wsUrl": "wss://<api-id>.execute-api.<region>.amazonaws.com/<stage>"
+   }
+   ```
+
+   Alternatively set `ZEPH_WS_URL` in your shell env.
+
+3. **Run agents through the wrapper.** That's it.
+
+   ```bash
+   zeph cc        # claude  → tmux session "zeph-<project>"
+   zeph codex     # codex   → tmux session "zeph-<project>"
+   zeph gemini    # gemini  → tmux session "zeph-<project>"
+   ```
+
+   The first `zeph cc` on a machine **auto-spawns a background
+   listener** (singleton, PID file at `~/.zeph/listener.pid`,
+   stdout/stderr at `~/.zeph/listener.log`). You never run
+   `zeph listener` by hand — every `zeph cc` checks the PID file and
+   skips the spawn when one is already alive, so opening a dozen
+   terminals doesn't create a dozen daemons. The daemon survives
+   between `zeph cc` invocations.
+
+   Project name resolves from `CLAUDE_PROJECT_DIR` /
+   `CURSOR_PROJECT_DIR` / `WINDSURF_PROJECT_DIR` if set, else the git
+   repo root, else the cwd basename. Any extra args after the command
+   pass through to the agent verbatim:
+
+   ```bash
+   zeph cc --resume "abc123"
+   zeph cc --dangerously-skip-permissions
+   zeph codex --model gpt-5-high "fix the failing test"
+   ```
+
+   **Multiple sessions in one project.** Open another terminal in the
+   same folder, run `zeph cc` again, and the wrapper auto-suffixes:
+   first session is `zeph-encl`, the next attached one becomes
+   `zeph-encl-2`, then `zeph-encl-3`, etc. The phone picker shows them
+   as `encl · Claude`, `encl · Claude #2`, `encl · Claude #3`. If
+   `zeph-encl` already exists but is **detached** (no one attached),
+   the wrapper reattaches to it instead of spawning a new one — close
+   the terminal, come back later, pick up where you left off.
+
+   If you're already inside a tmux session (`$TMUX` set) the wrapper
+   skips the outer tmux and runs the agent in the current pane — the
+   listener can't target an unnamed session that way, but you keep your
+   existing multiplexer setup.
+
+### Diagnostics
+
+The auto-spawned listener writes to two files under `~/.zeph/`:
+
+- `listener.pid` — the running daemon's PID. `cat ~/.zeph/listener.pid`
+  + `ps -p <pid>` to confirm it's alive.
+- `listener.log` — stdout + stderr from the daemon. `tail -f` to watch.
+
+A healthy listener log shows one line per cycle:
+
+```
+[xx:xx:xx] reported 2 session(s): zeph-myapp, zeph-otherapp
+[xx:xx:xx] ✓ server persisted 2 session(s)
+```
+
+If you see `! server rejected listener.sessions: ...` instead, the
+message points at the failure (auth, missing device record, etc.) so
+you can fix the actual problem instead of guessing.
+
+To force a restart — e.g. after upgrading `@zeph-to/hook-sdk`:
+
+```bash
+kill $(cat ~/.zeph/listener.pid)
+rm ~/.zeph/listener.pid
+zeph cc        # autospawns the new build
+```
+
+To run it in the foreground (for development of the SDK itself):
+
+```bash
+zeph listener
+```
+
+You'll get the same logs you'd otherwise tail from `listener.log`.
+
+### Custom tmux sockets
+
+The listener auto-discovers the tmux socket — it probes the default
+location, walks per-user `$TMPDIR` paths (macOS `/var/folders/.../T/`),
+falls back to `/tmp/tmux-<uid>/`, and finally finds running tmux servers
+via `lsof` so stale socket files don't trip discovery. If your tmux
+uses `tmux -L <name>` or a non-standard `-S <path>`, set the override
+explicitly:
+
+```bash
+export ZEPH_TMUX_SOCKET=/path/to/socket
+```
+
+(The wrapper passes the env to the auto-spawned listener, so setting
+it in your shell rc is enough.)
+
+### Wire format
+
+The listener only acts on pushes with `type='agent.command'` carrying
+the tmux session name in `agentSessionName` and the message in `body`.
+Other pushes (Stop-hook auto-pushes, `zeph_ask` responses, channel
+broadcasts, plain notes) are ignored. End-to-end:
+
+```
+tmux send-keys -l -t <agentSessionName> "<body>"
+tmux send-keys    -t <agentSessionName> Enter
+```
+
+If you need to send one from the command line (debugging, scripting),
+build the structured push directly:
+
+```bash
+curl -X POST "$ZEPH_BASE_URL/pushes/send" \
+  -H "X-API-Key: $ZEPH_API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "type": "agent.command",
+    "targetDeviceId": "dev_listener_<sha8(hostname)>",
+    "agentSessionName": "zeph-myapp",
+    "body": "테스트 통과시키고 PR 올려줘"
+  }'
+```
+
+### Defense
+
+The listener is a remote-code-execution surface by design (it types
+into a shell-adjacent pane). The defense is layered:
+
+1. **Pane guard** — before injecting, the listener checks
+   `tmux display-message -p '#{pane_current_command}'`. If the pane is
+   at an interactive shell (`bash`/`zsh`/`fish`/`sh`/`dash`/`ksh`/
+   `tcsh`/`csh`/`pwsh`), the inject is refused. CC/Codex/Gemini exited
+   ≠ phone gets free shell access.
+2. **Literal injection** — `tmux send-keys -l` takes the payload as
+   data; tmux escape sequences inside a message can't drive other tmux
+   commands.
+3. **Session-name allowlist** — only `[A-Za-z0-9._-]+` is accepted as
+   a session target, so shell metacharacters never reach the tmux argv.
+4. **Per-session rate limit** — 30 injections/minute/session token
+   bucket caps a runaway/compromised sender.
+5. **Agent permission gate stays on** — your CC/Codex/Gemini permission
+   prompt is still in front of every destructive tool call. The phone
+   can *talk* but can't approve `rm -rf` for you.
+
+The transport (WS) is currently authenticated by API key + `push:read`
+scope and is **not** end-to-end encrypted in v1 — your Zeph backend
+sees the message plaintext. If you self-host or trust your backend,
+that's fine. If you don't, hold off until per-device E2E ships.
 
 ## CLI Usage
 
@@ -42,6 +260,15 @@ zeph dismiss --all
 # Test connection
 zeph test
 
+# Run an agent in a named tmux session (so the listener can reach it)
+zeph cc                       # claude
+zeph codex                    # codex
+zeph gemini                   # gemini
+
+# Run the resident listener (foreground; background it as you like)
+zeph listener
+zeph listener --ws-url wss://...   # override config
+
 # JSON output
 zeph notify --title "Hello" --json
 ```
@@ -58,6 +285,8 @@ zeph notify --title "Hello" --json
 | `list` | List recent push notifications |
 | `dismiss <id>` | Dismiss a push (or `--all`) |
 | `test` | Verify connection and API key |
+| `cc` · `codex` · `gemini` | Run the agent in a `zeph-<project>` tmux session (auto-suffixed `-2`, `-3`, … on attached collisions). Auto-spawns the background listener on first invocation so the phone picker just works. Trailing args pass through to the agent (`zeph cc --resume "..."`) |
+| `listener` | (Usually unnecessary — `zeph cc` autospawns it.) Resident daemon: subscribes via WebSocket, reports tmux session inventory every 5 s, injects `agent.command` pushes into the matching session. Run in the foreground for SDK development; otherwise let `zeph cc` manage it |
 
 ### Notify Options
 
@@ -70,7 +299,22 @@ zeph notify --title "Hello" --json
 | `--priority <p>` | Priority: `low`, `normal`, `high`, `urgent` |
 | `--device <id>` | Target device ID |
 
-The defaults are tuned for hook-driven invocations (e.g. Stop hooks calling `zeph notify --title "Task done"` without a body) — you'll see which project + branch finished without writing per-IDE wrappers. Pass `--body ""` explicitly to suppress.
+The defaults are tuned for hook-driven invocations (e.g. Stop hooks
+calling `zeph notify --title "Task done"` without a body) — you'll see
+which project + branch finished without writing per-IDE wrappers. Pass
+`--body ""` explicitly to suppress.
+
+### Listener Options
+
+| Flag | Description |
+|------|-------------|
+| `--ws-url <url>` | WebSocket endpoint (or set `ZEPH_WS_URL` env, or `wsUrl` in `~/.zeph/config.json`) |
+| `--key <api-key>` | API key (or set `ZEPH_API_KEY` env) |
+
+The listener reconnects with exponential backoff + jitter (1 s → 30 s
+cap). Heartbeat is ping every 25 s with a 10 s pong timeout. On an
+authentication failure close (4001/4002/4003) the listener exits with
+code 3 instead of looping forever — fix the key and restart.
 
 ### List Options
 
@@ -90,9 +334,11 @@ The defaults are tuned for hook-driven invocations (e.g. Stop hooks calling `zep
 
 ### Mute
 
-Mute is project-scoped (uses project directory hash). Created by Claude Code `/zeph-mute` command.
+Mute is project-scoped (uses project directory hash). Created by Claude
+Code `/zeph-mute` command.
 
-Notifications are silently skipped when a mute file exists for the current project:
+Notifications are silently skipped when a mute file exists for the
+current project:
 
 ```bash
 # Mute (created by /zeph-mute in Claude Code plugin)
@@ -103,7 +349,8 @@ touch /tmp/zeph-muted-$HASH
 rm /tmp/zeph-muted-$HASH
 ```
 
-The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`, `WINDSURF_PROJECT_DIR`, and falls back to `cwd`.
+The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`,
+`WINDSURF_PROJECT_DIR`, and falls back to `cwd`.
 
 ### Exit Codes
 
@@ -112,7 +359,8 @@ The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`, `WINDSURF_PROJECT_DIR
 | 0 | Success |
 | 1 | General error |
 | 2 | Quota exceeded |
-| 3 | Authentication failed |
+| 3 | Authentication failed (also: listener auth close 4001/4002/4003) |
+| 127 | A required external binary (e.g. `tmux`, `claude`) was not found on PATH |
 
 ### Environment Variables
 
@@ -120,6 +368,9 @@ The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`, `WINDSURF_PROJECT_DIR
 |----------|-------------|
 | `ZEPH_API_KEY` | API key (fallback when `--key` not provided) |
 | `ZEPH_BASE_URL` | API base URL (default: `https://api.zeph.to/v1`) |
+| `ZEPH_WS_URL` | WebSocket endpoint for `zeph listener` (no default — required) |
+| `ZEPH_TMUX_SOCKET` | Explicit tmux socket path for the listener (skips auto-discovery — use when your tmux runs with `-L <name>` or a custom `-S <path>`) |
+| `ZEPH_SESSION_ID` | AI session ID (fallback when `--session` not provided) |
 
 ## SDK Usage
 
@@ -193,17 +444,39 @@ try {
 | Copilot CLI | Session end hook |
 | Cline | Rules file |
 
-## Encryption
+For remote-control via `zeph listener` the per-agent setup is the same
+across CC/Codex/Gemini — the wrapper just spawns them in a named tmux
+session.
 
-Push bodies are encrypted with AES-256-GCM. The wrapping key is derived via ECDH P-256 and synced across your own devices on first run so every device can read the same push. Toggle encryption in the Zeph app (Settings → Encryption); when disabled, the CLI sends plaintext. No configuration needed.
+## Encryption
 
-**Threat model honesty:** keys are persisted on the Zeph backend to enable cross-device sync, so this is *device-shared* encryption — not true end-to-end. It protects push contents from passive network observers and from a leaked database snapshot taken without the key store, but it does **not** protect against the Zeph backend itself (it has the keys it serves to your devices). A true E2E mode (per-device keypairs, server stores only public keys, no key escrow) is on the roadmap.
+Push bodies are encrypted with AES-256-GCM. The wrapping key is derived
+via ECDH P-256 and synced across your own devices on first run so every
+device can read the same push. Toggle encryption in the Zeph app
+(Settings → Encryption); when disabled, the CLI sends plaintext. No
+configuration needed.
+
+**Threat model honesty:** keys are persisted on the Zeph backend to
+enable cross-device sync, so this is *device-shared* encryption — not
+true end-to-end. It protects push contents from passive network
+observers and from a leaked database snapshot taken without the key
+store, but it does **not** protect against the Zeph backend itself (it
+has the keys it serves to your devices). A true E2E mode (per-device
+keypairs, server stores only public keys, no key escrow) is on the
+roadmap.
+
+The `zeph listener` ignores `isEncrypted` pushes for now — it has no
+per-device key to decrypt them. Stop-hook auto-pushes and `zeph_ask`
+responses are not part of the `@<session>` injection path, so this
+doesn't affect normal use.
 
 ## Requirements
 
-- Node.js >= 18 (uses native `fetch`)
+- **Node.js >= 18** (uses native `fetch`).
+- **tmux** — required for `zeph cc` / `codex` / `gemini` and `zeph listener`.
 - The `ZephHook` SDK has no runtime dependencies. The CLI depends on
-  `@inquirer/prompts` for the interactive `zeph install` picker.
+  `@inquirer/prompts` for the interactive `zeph install` picker and on
+  `ws` for the listener's WebSocket subscription.
 
 ## License
 

package/dist/cli.js

@@ -9,6 +9,8 @@ const installer_js_1 = require("./installer.js");
 const uninstall_js_1 = require("./uninstall.js");
 const verify_js_1 = require("./verify.js");
 const check_update_js_1 = require("./check-update.js");
+const wrapper_js_1 = require("./wrapper.js");
+const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
 const PROJECT_DIR_VARS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
 const detectProjectDir = () => PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
@@ -76,6 +78,16 @@ Commands:
   list            List recent push notifications
   dismiss <id>    Dismiss a push notification (or --all)
   test            Send a test notification to verify setup
+  cc [args…]      Run 'claude' in a named tmux session ('zeph-<project>')
+  codex [args…]   Run 'codex' in a named tmux session
+  gemini [args…]  Run 'gemini' in a named tmux session
+                  (auto-suffixed -2/-3/… when another zeph cc is already
+                   attached to the default name; any args after the
+                   subcommand are forwarded verbatim, e.g.
+                   'zeph cc --resume')
+  listener        Resident daemon — receives 'agent.command' pushes from
+                  the phone picker and injects them into the matching
+                  tmux session.
 
 Notify options:
   --title <text>     Push title
@@ -294,6 +306,16 @@ const handleError = (err, isJson) => {
     printError(err instanceof Error ? err.message : 'Unknown error', isJson);
     return 1;
 };
+// ── Passthrough ─────────────────────────────────────────────────
+/**
+ * Collect raw argv after the given subcommand token so flags like
+ * `--resume` reach the wrapped agent verbatim instead of being swallowed
+ * by `parseArgs`. Returns [] when the command isn't found.
+ */
+const collectPassthrough = (argv, cmd) => {
+    const idx = argv.indexOf(cmd, 2);
+    return idx >= 0 ? argv.slice(idx + 1) : [];
+};
 // ── Main ────────────────────────────────────────────────────────
 const main = async () => {
     const args = parseArgs(process.argv);
@@ -324,6 +346,14 @@ const main = async () => {
             return handleDismiss(args);
         case 'test':
             return handleTest(args);
+        case 'cc':
+            return (0, wrapper_js_1.handleAgentSession)('claude', collectPassthrough(process.argv, 'cc'));
+        case 'codex':
+            return (0, wrapper_js_1.handleAgentSession)('codex', collectPassthrough(process.argv, 'codex'));
+        case 'gemini':
+            return (0, wrapper_js_1.handleAgentSession)('gemini', collectPassthrough(process.argv, 'gemini'));
+        case 'listener':
+            return (0, listener_js_1.handleListener)(args);
         default:
             printError(`Unknown command: ${command}`, args.json === true);
             printUsage();

package/dist/config.d.ts

@@ -4,6 +4,7 @@ export interface ZephConfig {
     apiKey?: string;
     hookId?: string;
     baseUrl?: string;
+    wsUrl?: string;
     deviceId?: string;
 }
 export declare const resolvedEnv: (key: string) => string | undefined;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}

package/dist/listener.d.ts

@@ -0,0 +1,117 @@
+/**
+ * `zeph listener` — resident daemon that watches the user's Zeph feed
+ * over a persistent WebSocket and injects matching messages into a
+ * named tmux session via `tmux send-keys`.
+ *
+ * Solves the MCP polling-window problem: an `zeph_ask` polling cycle
+ * times out (120–600 s) and the CC/Codex session becomes unaddressable
+ * from the phone. The listener stays subscribed indefinitely and can
+ * deliver to any named tmux session at any time.
+ *
+ * Wire format: pushes with `type='agent.command'` carry the tmux
+ * session name in `agentSessionName` and the message in `body`. The
+ * "AI Agent에게 명령" sheet on the phone builds these structured
+ * pushes from the listener-reported session inventory. Other push
+ * types (Stop-hook auto-pushes, zeph_ask responses, channel
+ * broadcasts) are ignored.
+ *
+ * Transport: WebSocket against the Zeph $connect endpoint with
+ * `?apiKey=<key>`. The server fan-out pushes `{ type: 'push.new', data }`
+ * messages as new pushes are created. Reconnects with exponential
+ * backoff on transient failures; gives up on auth failures (4001/4002/4003).
+ */
+type AgentKind = 'claude' | 'codex' | 'gemini';
+interface AgentSession {
+    name: string;
+    attached: boolean;
+    agentKind: AgentKind;
+    agentSessionId?: string | null;
+    project: string;
+    label?: string | null;
+    createdAt?: string;
+    lastActivityAt?: string;
+}
+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;
+/**
+ * Parse a `zeph-*` tmux session name into `{project, label}`. For
+ * Phase 1 the wrapper only emits `zeph-<project>` (no labels), so the
+ * whole tail becomes the project. When labels land in Phase 2 the
+ * wrapper will sidecar `{project, label}` so the listener doesn't need
+ * to guess from a name that allows dashes in project names.
+ */
+export declare const parseSessionName: (name: string) => {
+    project: string;
+    label: string | null;
+} | 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.
+ */
+export declare const detectClaudeSessionId: (cwd: string) => string | null;
+export interface CollectResult {
+    sessions: AgentSession[];
+    /** Diagnostic notes per rejected session — surfaced under `--verbose`. */
+    rejected: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+/**
+ * Inventory pass that also records *why* each `zeph-*` session was
+ * skipped. The verbose log uses the rejection notes to explain empty
+ * pickers (most common cause: tmux pane lost its start_command after a
+ * re-attach, and the current command is `node` rather than `claude`).
+ */
+export declare const collectSessionsVerbose: () => CollectResult;
+/**
+ * Snapshot the live `zeph-*` tmux sessions on this machine, enriched
+ * with the running agent kind, CC session UUID (claude only), project,
+ * and tmux activity timestamps. Returns [] when tmux is unreachable
+ * or no agent sessions exist. Sessions whose pane is at a shell or
+ * running something other than claude/codex/gemini are filtered out
+ * — the phone can't usefully address them.
+ */
+export declare const collectSessions: () => AgentSession[];
+interface PushItem {
+    pushId: string;
+    type?: string;
+    body?: string;
+    title?: string;
+    createdAt?: string;
+    isEncrypted?: boolean;
+    /** Set when type='agent.command' — tmux session name to inject into. */
+    agentSessionName?: string;
+}
+interface HandlePushDeps {
+    paneCommand?: (session: string) => string | null;
+    inject?: (session: string, text: string) => boolean;
+    rateLimit?: (session: string) => boolean;
+    now?: () => number;
+}
+/**
+ * Process one push. Returns true when an injection actually fired.
+ * Exported for unit testing with mocked deps.
+ *
+ * Only acts on `type='agent.command'` pushes carrying both an
+ * `agentSessionName` (tmux session to inject into) and a non-empty
+ * `body`. Everything else (Stop-hook auto-pushes, zeph_ask responses,
+ * encrypted pushes, normal text/link/file notifications) is ignored.
+ */
+export declare const handlePush: (push: PushItem, deps?: HandlePushDeps) => boolean;
+/**
+ * Stable per-host device id for the listener. We hash the OS hostname so
+ * the same machine reuses the same DeviceRecord across listener restarts
+ * (otherwise the phone's session inventory grows a new ghost device every
+ * time `zeph listener` rebinds). `dev_listener_<sha8(hostname)>` keeps it
+ * human-recognisable in dev logs without leaking the raw hostname.
+ */
+export declare const computeListenerDeviceId: (host?: string) => string;
+export declare const handleListener: (args: Record<string, string | boolean>) => Promise<number>;
+export {};
+//# sourceMappingURL=listener.d.ts.map

package/dist/listener.d.ts.map

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