@hwip/cli 0.0.1 → 0.1.1

package/dist/remote-agents.d.ts

@@ -0,0 +1,410 @@
+import { spawnSync } from 'child_process';
+import { type TranscriptProjector, type TranscriptReader } from './transcript-tail.js';
+export interface RemoteAgent {
+    /** Wire value for AgentSession.agentKind (server/phone contract). */
+    kind: string;
+    /** Human name for --help text. */
+    displayName: string;
+    /** Binary launched in the tmux pane; also the primary pane-match token. */
+    binary: string;
+    /** `hwip <subcommand>` aliases that launch this agent. */
+    subcommands: readonly string[];
+    /**
+     * What this agent is typed to make it quit, if it has such a command.
+     *
+     * Signals are not enough on their own: Claude Code holds its prompt
+     * through both `C-c` and `C-d`, so a remote "end this session" built only
+     * out of key presses reports failure against the agent people actually
+     * run. Omitted where the command has not been verified against the real
+     * binary — sending a guess into a live pane types it at whatever prompt
+     * is there.
+     */
+    quitCommand?: string;
+    /** Extra pane_command basenames accepted as this agent (beyond binary). */
+    paneMatchAliases?: readonly string[];
+    /**
+     * 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: carried by Claude Code and OpenCode. 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;
+    /**
+     * Resolve the name the agent calls this session by — what the user sees in
+     * their own terminal, which the phone shows instead of the computed
+     * `<project> · <Agent> #N` label.
+     *
+     * Same shape as `resolveSessionId` and the same EXTENSION POINT rule: a row
+     * carries this only once that agent's name store is confirmed. Cursor and
+     * Gemini never will — their state files hold ids, cwds and timestamps and no
+     * name at all, so there is nothing to read and the computed label stands.
+     */
+    resolveSessionName?: (paneCwd: string, panePid?: number) => string | null;
+    /**
+     * Resolve the file this agent is writing its session transcript to, for the
+     * live chat timeline (`turn-watch`).
+     *
+     * Same shape and the same EXTENSION POINT rule as the two above: a row
+     * carries this only once that agent's transcript format is confirmed, and a
+     * pane whose agent omits it answers `no_transcript` rather than guessing.
+     * That is the seam a second agent hangs off — the reader that parses the
+     * file is `projectTranscript` below.
+     */
+    resolveTranscript?: (paneCwd: string, panePid?: number) => string | null;
+    /**
+     * Read this agent's transcript lines into the events the timeline draws.
+     *
+     * Set with `resolveTranscript` or not at all — `remote-agents.test.ts`
+     * enforces the pair over the whole table. Half a pair is the one failure
+     * mode worth a test here: a path nothing can parse reaches the phone as an
+     * empty timeline, which reads as a hung agent, where the missing row would
+     * have said "no live timeline" and been true.
+     */
+    projectTranscript?: TranscriptProjector;
+    /**
+     * How to read what `resolveTranscript` returned, for an agent whose
+     * transcript is not an append-only file. Omitted by every row whose is —
+     * those are tailed by `readTranscriptDelta`. opencode is the one that sets
+     * it: its "path" names a session in its SQLite store (`opencode-transcript.ts`).
+     */
+    readTranscript?: TranscriptReader;
+}
+/**
+ * The directory name Claude Code gives a cwd under `~/.claude/projects/`.
+ * Copied from the Claude Code 2.1.287 binary (`k` / `Jx`): every character
+ * outside `[a-zA-Z0-9]` becomes `-`, so `.`, `_`, spaces, `@` and Hangul all
+ * collapse, one `-` per UTF-16 unit. Names past 200 characters are cut and
+ * suffixed with `-` plus the base-36 of a Java-style string hash of the cwd.
+ * mcp-server/src/config.ts carries the same rule and test vectors — keep the
+ * two in step.
+ */
+export declare const claudeProjectDirName: (cwd: string) => string;
+/**
+ * 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/<claudeProjectDirName(cwd)>/<UUID>.jsonl`.
+ * Cached for 60s — see
+ * claudeSessionCache.
+ */
+export declare const detectClaudeSessionId: (cwd: string) => string | null;
+export interface PidSessionRecord {
+    pid: number;
+    sessionId: string;
+    cwd: string;
+    /**
+     * What Claude Code calls this session (`hwipit-95` when derived from the
+     * cwd, free text once named). Optional: an older CC writes the record
+     * without it, and a record without a name is still a valid id match.
+     */
+    name?: string;
+}
+export interface ProcTable {
+    /** ppid → its direct children, for walking a pane's process tree. */
+    children: Map<number, number[]>;
+    /** pid → process start time in epoch ms. Only pids whose `lstart` parsed. */
+    startTimes: Map<number, number>;
+    /** pid → its process group id. Absent when the row carried no pgid. */
+    pgidOf: Map<number, number>;
+    /** pid → the foreground process group of its controlling tty. A pane
+     *  shell whose tpgid equals its own pgid IS the foreground — a plain
+     *  prompt; anything else is running a foreground command. */
+    tpgidOf: Map<number, number>;
+    /** pid → its command name (`comm`), last column because it may contain
+     *  spaces (`tmux: client`). Basename-matched against the agent registry. */
+    commOf: Map<number, string>;
+}
+/**
+ * Parse `ps -axo pid=,ppid=,lstart=`. A row is `<pid> <ppid> [<lstart>]`, e.g.
+ * `    1     0 Fri Aug  7 11:12:59 2026    ` — note the two spaces before a
+ * single-digit day and the trailing padding.
+ *
+ * The third field is OPTIONAL in the pattern, and that is load-bearing rather
+ * than defensive. Requiring it would mean that on any machine whose `ps` prints
+ * a different `lstart` shape, EVERY row fails to match, `children` comes back
+ * empty, `collectDescendantPids` answers `{rootPid}`, and
+ * `detectClaudeSessionByPid` finds nothing — dropping Claude Code back to the
+ * mtime heuristic and its identity theft (see CLAUDE_SESSIONS_DIR above). The
+ * parent links must survive an unreadable timestamp; only the start time is
+ * allowed to go missing, and every consumer of `startTimes` treats an absent
+ * entry as "no match" rather than guessing.
+ */
+/**
+ * Parse `ps -axo pid=,ppid=,pgid=,tpgid=,lstart=,comm=`. A row is
+ * `<pid> <ppid> <pgid> <tpgid> [<lstart>] [<comm>]`, e.g.
+ * `  902     1   902   902 Fri Aug  7 11:12:59 2026 zsh` — note the two spaces
+ * before a single-digit day and the trailing padding.
+ *
+ * Token positions, not one regex: `lstart` is a fixed 5 tokens when present
+ * and `comm` is LAST because it may contain spaces. A row with fewer tokens
+ * simply contributes fewer maps — the shape is load-bearing rather than
+ * defensive: parent links must survive an unreadable timestamp (the reason
+ * `lstart` is optional), and the pgid/tpgid/comm columns are absent only when
+ * a caller fed the old narrower argv, which nothing in production does.
+ */
+export declare const parseProcTable: (table: string) => ProcTable;
+/**
+ * The process table, or null when `ps` failed. Exported with its spawn as a
+ * seam so the bounds are testable without a real `ps`.
+ */
+export declare const readProcTable: (run?: typeof spawnSync) => ProcTable | null;
+/**
+ * The agent running in the FOREGROUND process group of the tty owned by a
+ * pane shell, or null. This is what separates a subagent pane from a plain
+ * prompt: the subagent pane reports `pane_current_command=bash` (a script
+ * execs pi), so the pane-level command identifies nothing — but the tty's
+ * foreground group is pi's, and `comm` names it. A pane sitting at its login
+ * shell has the shell's own group in the foreground (tpgid === pgid) and is
+ * not a subagent, no matter what the registry would match.
+ */
+export declare const foregroundAgentFor: (panePid: number, table?: ProcTable | null) => RegisteredRemoteAgent | null;
+/** Start times for this cycle's snapshot. Empty when `ps` is unavailable. */
+export declare const psStartTimes: () => Map<number, number>;
+/** pid set of `rootPid` + all descendants, from one `ps` snapshot. */
+export declare const collectDescendantPids: (rootPid: number) => Set<number>;
+/** Test seam for the pid-based resolver. */
+export interface PidResolveDeps {
+    records?: PidSessionRecord[];
+    descendants?: Set<number>;
+}
+/**
+ * Whether this machine's Claude Code writes `~/.claude/sessions` records at all.
+ *
+ * The difference between "no records anywhere" (an older CC — the mtime
+ * heuristic is the only option) and "records exist, none match this pane" (the
+ * pane is not a Claude session) is the difference between a useful fallback and
+ * a wrong answer, so callers that care ask it explicitly.
+ */
+export declare const pidSessionRecordsExist: () => boolean;
+/**
+ * Exact resolution: the session record whose pid lives in the pane's
+ * process tree AND whose cwd matches (guards against OS pid reuse
+ * leaving a stale record pointing elsewhere). Null → caller falls back
+ * to the mtime heuristic.
+ *
+ * Returns the whole record so the id and the name come from one lookup — they
+ * describe the same session, and reading the directory twice per cycle to get
+ * them separately is what the cache above exists to avoid.
+ */
+export declare const detectClaudeSessionByPid: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps) => PidSessionRecord | null;
+export declare const detectClaudeSessionIdByPid: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps) => string | null;
+/**
+ * The name of the session running in this pane. No mtime fallback exists here:
+ * the transcript filenames the heuristic walks carry a UUID and nothing else,
+ * so an older CC without `~/.claude/sessions` yields no name and the phone
+ * keeps the computed label.
+ */
+export declare const detectClaudeSessionNameByPid: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps) => string | null;
+/**
+ * The transcript file for the Claude Code session running in a tmux pane.
+ *
+ * Pid first, cwd only as a fallback, and the order is the whole point: the cwd
+ * heuristic picks the newest `*.jsonl` in the directory, so a second `claude`
+ * started in the same repo steals the first one's transcript (the comment above
+ * `detectClaudeSessionIdByPid` records that failure). Live-timeline viewers are
+ * per tmux session, so two sessions in one directory must resolve to two files
+ * or each phone reads the other's work.
+ *
+ * Returns null when this pane is not running Claude Code at all — a Codex or
+ * Gemini pane has no transcript here, and that is an answer, not a failure.
+ */
+export declare const claudeTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
+/**
+ * The transcript a pi pane is writing, or null when there is none to follow.
+ *
+ * Newest-by-mtime within the directory. pi keeps no pid→session record the way
+ * Claude Code does, so `panePid` cannot pick between two pi panes sharing a
+ * directory — both resolve to the newer session's file. That is the known limit
+ * of this resolver, and it is the same shape as Claude's mtime fallback.
+ *
+ * `panePid` still matters, as the cache key: a restart in the same directory
+ * writes a new file, and a cwd-only key would keep answering with the old one
+ * until the TTL ran out.
+ */
+export declare const piTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
+/**
+ * The row whose timestamp is closest to when one of the pane's processes started,
+ * within {@link PROC_MATCH_TOLERANCE_MS}. Null when nothing qualifies — including
+ * when no pid in the tree has a known start time, which is why the start times
+ * are collected before any row is compared rather than defaulted to zero.
+ */
+export declare const pickRowByProcStart: <T>(rows: readonly T[], tsMsOf: (row: T) => number | null, startTimes: Map<number, number>, pids: Set<number>) => T | null;
+/**
+ * Read rows from a SQLite file as JSON. Null on every failure — no `sqlite3` on
+ * PATH, a locked or corrupt database, a schema that moved — because a missing
+ * name costs the computed label and nothing else.
+ *
+ * The query carries no parameters BY DESIGN: SQL passed to the `sqlite3` binary
+ * as an argv string has nowhere to bind `?` to, so interpolating a cwd would
+ * make this file the place that has to know SQLite quoting rules. Callers select
+ * the columns they need and filter in JS instead; the stores hold tens of rows,
+ * not millions. The `timeout` keeps a locked database from holding up a report
+ * cycle that runs every five seconds.
+ */
+export declare const sqliteJson: (dbPath: string, sql: string, run?: typeof spawnSync) => unknown[] | null;
+/** Test seam for the store-backed resolvers. `rows: null` = the read failed. */
+export interface StoreResolveDeps {
+    rows?: unknown[] | null;
+    startTimes?: Map<number, number>;
+    descendants?: Set<number>;
+}
+export declare const detectHermesSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+/**
+ * The highest-numbered match, numerically. Codex versions its state file
+ * (`state_5.sqlite` today) and moves to the next number on a schema migration,
+ * so hard-coding a name would silently stop reading after an upgrade. Sorting
+ * the strings would break at `state_10` vs `state_9`.
+ */
+export declare const newestVersionedDb: (entries: readonly string[], pattern: RegExp) => string | null;
+/**
+ * No `source` filter, unlike the Hermes reader's `source = 'cli'`. The column
+ * exists here too (alongside `thread_source`), but Codex is unauthenticated on
+ * every machine measured so far and its `threads` table is empty, so which
+ * values mark a terminal session is unknown — and a wrong guess filters out
+ * every row, which fails as "no name ever" rather than loudly. A thread from a
+ * non-terminal frontend is therefore eligible to match, and it lands in the same
+ * accepted misjoin as two terminals in the same directory: it needs the same cwd
+ * AND a creation time within the tolerance of a process in this pane. Add the
+ * filter once the values can be observed.
+ */
+export declare const detectCodexSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+export declare const codexTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
+/**
+ * The transcript a Gemini pane is writing, or null when there is none to follow.
+ *
+ * Newest-by-mtime within the project's `chats` directory, which also follows a
+ * resumed session: Gemini keeps appending to the original file. Like pi's,
+ * Gemini keeps no pid → session record, so two Gemini panes in one directory
+ * both resolve to the newer file — the known limit — and `panePid` is only the
+ * cache key that lets a restart be noticed.
+ *
+ * The cwd is resolved as given; if a pane's cwd and the path Gemini registered
+ * ever differ by a symlink (`/tmp` ↔ `/private/tmp`) this answers null, and
+ * realpath is the fix to reach for then.
+ */
+export declare const geminiTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
+/**
+ * The opencode session running in this pane: the one in the pane's directory
+ * written to most recently since the pane's process started. Started-since is
+ * what keeps a pane that has not sent its first prompt — no session row yet —
+ * from being handed yesterday's session in the same directory. Two opencode
+ * panes in one directory both answer the busier one: the store says nothing
+ * about which process wrote what, the limit pi and Gemini already have.
+ */
+export declare const detectOpencodeSession: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => {
+    id: string;
+    title: string | null;
+} | null;
+export declare const opencodeTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
+declare const REMOTE_AGENT_TABLE: readonly [{
+    readonly kind: "claude";
+    readonly displayName: "Claude Code";
+    readonly binary: "claude";
+    readonly subcommands: readonly ["cc", "claude"];
+    readonly quitCommand: "/exit";
+    readonly resolveSessionId: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly projectTranscript: TranscriptProjector;
+}, {
+    readonly kind: "codex";
+    readonly displayName: "Codex CLI";
+    readonly binary: "codex";
+    readonly subcommands: readonly ["codex"];
+    readonly resolveSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+    readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly projectTranscript: TranscriptProjector;
+}, {
+    readonly kind: "cursor";
+    readonly displayName: "Cursor CLI";
+    readonly binary: "cursor-agent";
+    readonly subcommands: readonly ["cursor", "cursor-agent"];
+}, {
+    readonly kind: "gemini";
+    readonly displayName: "Gemini CLI";
+    readonly binary: "gemini";
+    readonly subcommands: readonly ["gemini"];
+    readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly projectTranscript: TranscriptProjector;
+}, {
+    readonly kind: "hermes";
+    readonly displayName: "Hermes";
+    readonly binary: "hermes";
+    readonly subcommands: readonly ["hermes"];
+    readonly resolveSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+}, {
+    readonly kind: "pi";
+    readonly displayName: "Pi";
+    readonly binary: "pi";
+    readonly subcommands: readonly ["pi"];
+    readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly projectTranscript: TranscriptProjector;
+}, {
+    readonly kind: "opencode";
+    readonly displayName: "OpenCode";
+    readonly binary: "opencode";
+    readonly subcommands: readonly ["opencode"];
+    readonly quitCommand: "/exit";
+    readonly resolveSessionId: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly projectTranscript: TranscriptProjector;
+    readonly readTranscript: (path: string, prev: import("./transcript-tail.js").TailState | null) => import("./transcript-tail.js").TailRead | null;
+}, {
+    readonly kind: "kimi";
+    readonly displayName: "Kimi Code";
+    readonly binary: "kimi";
+    readonly subcommands: readonly ["kimi"];
+}, {
+    readonly kind: "grok";
+    readonly displayName: "Grok Build";
+    readonly binary: "grok";
+    readonly subcommands: readonly ["grok"];
+}, {
+    readonly kind: "antigravity";
+    readonly displayName: "Antigravity";
+    readonly binary: "agy";
+    readonly subcommands: readonly ["agy", "antigravity"];
+}, {
+    readonly kind: "qwen";
+    readonly displayName: "Qwen Code";
+    readonly binary: "qwen";
+    readonly subcommands: readonly ["qwen"];
+}, {
+    readonly kind: "auggie";
+    readonly displayName: "Auggie";
+    readonly binary: "auggie";
+    readonly subcommands: readonly ["auggie"];
+}, {
+    readonly kind: "kilo";
+    readonly displayName: "Kilo";
+    readonly binary: "kilo";
+    readonly subcommands: readonly ["kilo"];
+}, {
+    readonly kind: "copilot";
+    readonly displayName: "Copilot CLI";
+    readonly binary: "copilot";
+    readonly subcommands: readonly ["copilot"];
+}, {
+    readonly kind: "kiro";
+    readonly displayName: "Kiro";
+    readonly binary: "kiro-cli";
+    readonly subcommands: readonly ["kiro-cli", "kiro"];
+}, {
+    readonly kind: "droid";
+    readonly displayName: "Factory Droid";
+    readonly binary: "droid";
+    readonly subcommands: readonly ["droid"];
+}];
+/** 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 & {
+    kind: AgentKind;
+};
+export declare const REMOTE_AGENTS: readonly RegisteredRemoteAgent[];
+export declare const findAgentBySubcommand: (cmd: string) => RegisteredRemoteAgent | undefined;
+export declare const matchAgentByPaneCommand: (base: string) => RegisteredRemoteAgent | undefined;
+export {};
+//# sourceMappingURL=remote-agents.d.ts.map