@zeph-to/cli 2.3.1 → 2.4.0

package/README.md

@@ -8,7 +8,7 @@
 
 **Your agent works, hits a decision, and asks your phone. You tap a button (or type a reply), and the answer lands back in the live session — so the agent keeps going.**
 
-`@zeph-to/cli` is the terminal side of that round trip: a zero-dependency push SDK, a `zeph` CLI that wires up 8 AI agents in one command, and a resident listener that lets your phone **drive Claude Code / Codex / Cursor / Gemini sessions** by typing straight into named tmux sessions.
+`@zeph-to/cli` is the terminal side of that round trip: a zero-dependency push SDK, a `zeph` CLI that wires up 8 AI agents in one command, and a resident listener that lets your phone **drive any agent session it can start** by typing straight into named tmux sessions.
 
 <p align="center">
   <img src="https://zeph.to/readme/demo.gif" alt="Agent asks 'Deploy to prod?' on your phone; you tap Deploy; the session ships" width="560"><br>
@@ -83,13 +83,13 @@ To **send** notifications:
 zeph notify --title "Deploy done" --body "v2.1.0 shipped"
 ```
 
-To **drive a Claude Code / Codex / Cursor / Gemini session from your phone**, see
+To **drive an agent 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.
+> Send messages from your phone *into* a live agent session — even after
+> a `zeph_ask` polling window has expired.
 
 <p align="center">
   <img src="https://zeph.to/readme/ask-phone.png" alt="A Zeph hook on the phone: a question with tappable answer buttons and a text field" width="300">
@@ -116,7 +116,7 @@ tmux session via `tmux send-keys`.
 [zeph listener — resident daemon, started by `zeph cc` automatically]
    │  tmux send-keys -l -t zeph-myapp "리팩토링 마무리해줘" + Enter
    ▼
-[tmux session "zeph-myapp" running claude / codex / cursor-agent / gemini]
+[tmux session "zeph-myapp" running claude / codex / cursor-agent / gemini / hermes]
 ```
 
 The listener polls its tmux session inventory every 5 seconds and
@@ -164,6 +164,26 @@ through. Same reason the `stop`-hook auto-push `zeph setup` installs
 covers the Cursor **IDE** but not `zeph cursor` panes; ask for a
 `zeph_notify` when you want one.
 
+`zeph hermes` is in the same position, and asking for it works the same
+way. `zeph install` does not wire Hermes either — add the MCP server to
+`~/.hermes/config.yaml` by hand, as one entry under `mcp_servers`:
+
+```yaml
+mcp_servers:
+  zeph:
+    command: "npx"
+    args: ["-y", "@zeph-to/mcp-server"]
+```
+
+Add the entry; do not replace the file. `mcp_servers` is shared with
+every other server you have configured, and nothing under `~/.hermes` is
+in version control. Then `/reload-mcp` inside Hermes.
+
+`zeph_ask` needs a hook id, which the MCP server reads from
+`ZEPH_HOOK_ID` or from `hookId` in `~/.zeph/config.json` — `zeph install`
+writes the latter, so a machine that has run it once needs no `env`
+block here.
+
 ### Setup
 
 1. **Install tmux.** The listener uses `send-keys`; the wrapper spawns
@@ -190,12 +210,27 @@ covers the Cursor **IDE** but not `zeph cursor` panes; ask for a
    zeph codex     # codex        → tmux session "zeph-<project>"
    zeph cursor    # cursor-agent → tmux session "zeph-<project>"
    zeph gemini    # gemini       → tmux session "zeph-<project>"
+   zeph hermes    # hermes       → tmux session "zeph-<project>"
    ```
 
    `zeph cursor` runs **`cursor-agent`**, Cursor's terminal agent — a
    separate install from the Cursor IDE (the bare `cursor` on your PATH
    is the editor launcher, which exits immediately and can't be driven).
 
+   `zeph hermes` runs Hermes in its classic REPL, which is the default.
+   Launching it in TUI mode instead (`zeph hermes --tui`, or `HERMES_TUI=1`
+   in the environment) puts the pane on the terminal's alternate screen,
+   and the alternate screen has no scrollback — the live mirror on your
+   phone still draws, but scrolling up in it comes back empty.
+
+   If a Hermes session disappears from the phone's picker, the cause is
+   tmux having dropped the pane's `start_command`: all the listener sees
+   then is the interpreter Hermes execs (`python3.11` at time of writing),
+   which names no agent. `zeph listener` run in the foreground prints the
+   reason (`no agent in pane (start=…, current=python3.11)`). Kill the
+   session and start it again with `zeph hermes` to recover. `claude` sits
+   on the same edge for the same reason — it execs node.
+
    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
@@ -407,6 +442,7 @@ zeph cc                       # claude
 zeph codex                    # codex
 zeph cursor                   # cursor-agent (Cursor CLI, not the IDE)
 zeph gemini                   # gemini
+zeph hermes                   # hermes
 
 # Run the resident listener (foreground; background it as you like)
 zeph listener

package/dist/remote-agents.d.ts

@@ -23,8 +23,9 @@ export interface RemoteAgent {
     /**
      * Resolve the agent's own session id from the pane's cwd (+ pane pid
      * when the caller knows it — enables exact process-tree matching).
-     * EXTENSION POINT: omitted for codex/gemini until their session-file
-     * formats are confirmed — the listener then reports agentSessionId: null.
+     * EXTENSION POINT: carried only by Claude Code. Every other row omits
+     * it until that agent's session-file format is confirmed — the listener
+     * then reports agentSessionId: null.
      */
     resolveSessionId?: (paneCwd: string, panePid?: number) => string | null;
 }
@@ -76,8 +77,13 @@ declare const REMOTE_AGENT_TABLE: readonly [{
     readonly displayName: "Gemini CLI";
     readonly binary: "gemini";
     readonly subcommands: readonly ["gemini"];
+}, {
+    readonly kind: "hermes";
+    readonly displayName: "Hermes";
+    readonly binary: "hermes";
+    readonly subcommands: readonly ["hermes"];
 }];
-/** Closed union of remote-controllable agent kinds ('claude' | 'codex' | 'cursor' | 'gemini'). */
+/** Closed union of remote-controllable agent kinds, derived from the table above. */
 export type AgentKind = (typeof REMOTE_AGENT_TABLE)[number]['kind'];
 /** A registry row: the uniform RemoteAgent shape with `kind` narrowed to the closed union. */
 export type RegisteredRemoteAgent = RemoteAgent & {

package/dist/remote-agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-agents.d.ts","sourceRoot":"","sources":["../src/remote-agents.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,WAAW;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3E;AAyCD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAaF,UAAU,gBAAgB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACf;AA4ED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACnC,SAAS,MAAM,EACf,SAAS,MAAM,GAAG,IAAI,EACtB,OAAM,cAAmB,KAC1B,MAAM,GAAG,IAOX,CAAC;AAIF,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;EAmCmB,CAAC;AAE5C,kGAAkG;AAClG,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,8FAA8F;AAC9F,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtE,eAAO,MAAM,aAAa,EAAE,SAAS,qBAAqB,EAAuB,CAAC;AAElF,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,qBAAqB,GAAG,SAClB,CAAC;AAE3D,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,qBAAqB,GAAG,SAG9E,CAAC"}
+{"version":3,"file":"remote-agents.d.ts","sourceRoot":"","sources":["../src/remote-agents.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,WAAW;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3E;AAyCD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAaF,UAAU,gBAAgB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACf;AA4ED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACnC,SAAS,MAAM,EACf,SAAS,MAAM,GAAG,IAAI,EACtB,OAAM,cAAmB,KAC1B,MAAM,GAAG,IAOX,CAAC;AAIF,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+CmB,CAAC;AAE5C,qFAAqF;AACrF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,8FAA8F;AAC9F,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtE,eAAO,MAAM,aAAa,EAAE,SAAS,qBAAqB,EAAuB,CAAC;AAElF,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,qBAAqB,GAAG,SAClB,CAAC;AAE3D,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,qBAAqB,GAAG,SAG9E,CAAC"}

package/dist/remote-agents.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchAgentByPaneCommand = exports.findAgentBySubcommand = exports.REMOTE_AGENTS = exports.detectClaudeSessionIdByPid = exports.detectClaudeSessionId = void 0;
 /**
- * Remote-control agent registry — the single table behind `zeph cc` /
- * `zeph codex` / `zeph gemini`, the listener's pane matching, and the
+ * Remote-control agent registry — the single table behind every
+ * `zeph <agent>` subcommand, the listener's pane matching, and the
  * per-agent session-id enrichment. Adding a remote-controllable agent is
  * one row here (plus, for a genuinely new kind, backend/phone support:
  * `kind` is a wire contract — AgentSession.agentKind flows to the server
@@ -217,6 +217,18 @@ const REMOTE_AGENT_TABLE = [
         binary: 'gemini',
         subcommands: ['gemini'],
     },
+    {
+        // `hermes` on PATH is a bash script that execs a venv Python, so the
+        // pane's *current* command reads the interpreter (`python3.11` as
+        // measured). Only `pane_start_command` identifies it, which is the
+        // same bargain `claude` (node) already makes. Deliberately no
+        // paneMatchAliases: matching interpreter names would adopt every
+        // Python REPL on the machine as a Hermes session.
+        kind: 'hermes',
+        displayName: 'Hermes',
+        binary: 'hermes',
+        subcommands: ['hermes'],
+    },
 ];
 exports.REMOTE_AGENTS = REMOTE_AGENT_TABLE;
 const findAgentBySubcommand = (cmd) => exports.REMOTE_AGENTS.find((a) => a.subcommands.includes(cmd));

package/dist/remote-hook.js

@@ -126,8 +126,17 @@ const remoteOrigin = (prompt, cwd, now) => {
         return 'unclear';
     // Marker format: "<epochSec> <sha256hex>\n" (listener.ts writeRemoteMarker).
     const record = content.match(/^(\d+) ([0-9a-f]{64})\n?$/);
-    if (!record)
+    if (!record) {
+        // Junk can only ever be re-read and re-rejected — same housekeeping a
+        // stale marker gets. Twin: zeph-remote.sh's `rm -f` on the parse branches.
+        try {
+            (0, fs_1.unlinkSync)(marker);
+        }
+        catch {
+            /* best-effort housekeeping */
+        }
         return 'keyboard';
+    }
     if (Math.floor(now() / 1000) - Number(record[1]) > FRESH_WINDOW_SEC) {
         // Stale markers are dead weight (can never flag) — delete on sight.
         try {

package/package.json

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