@zeph-to/hook-sdk 1.8.0 → 1.10.0

package/dist/listener.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `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 `-`.
+ */
+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;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"}