tailii-host 0.1.1 → 0.4.0

package/dist/backend/herdr.d.ts

@@ -0,0 +1,260 @@
+import { type SessionInfo } from "../protocol.js";
+import { SessionMetadataStore } from "../sessions/sessionMetadataStore.js";
+import { type CapturePaneOptions, type ReattachResult } from "./tmux.js";
+/** herdr コマンド 1 回分の実行結果。 */
+export interface HerdrCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** herdr コマンド実行の注入可能な抽象（テストはモックを注入する）。 */
+export type HerdrCommandRunner = (args: string[]) => Promise<HerdrCommandResult>;
+/** herdr 実行ファイルの既定絶対パス（SSH exec は非ログインシェルで PATH 外のため絶対指定）。 */
+export declare function defaultHerdrPath(): string;
+/**
+ * Tailii セッション pane を収容する herdr named session。
+ * ユーザーの default セッション（普段使いの herdr）を汚さないよう、Tailii は専用の
+ * named session（別サーバー・別ソケット `~/.config/herdr/sessions/tailii/`）に全 pane を
+ * 収容する。CLI は全操作に `--session tailii` を前置する（runner レベルで一元付与）。
+ * まとめて消すときは `herdr session stop tailii` → `herdr session delete tailii`。
+ */
+export declare const HERDR_TAILII_SESSION = "tailii";
+/** herdr が導入済みか（backend_get の可用性表示・backend_set の検証に使う）。 */
+export declare function herdrInstalled(herdrPath?: string): boolean;
+/**
+ * 実 herdr を起動する既定ランナー。herdr 非0 exit は throw せず結果で表現する。
+ * `sessionName`（既定 tailii）を `--session` として全コマンドに前置する。
+ */
+export declare function processHerdrCommandRunner(herdrPath?: string, sessionName?: string): HerdrCommandRunner;
+/** HerdrSessionManager が投げる型付きエラー。 */
+export declare class HerdrFailedError extends Error {
+    readonly args: string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(args: string[], exitCode: number, stderr: string);
+}
+/**
+ * 画面に選択ダイアログのフッター行があるか。チャット本文が「Enter to select」を
+ * 引用しただけの偽陽性（誤 Esc・再送スキップの実害）を避けるため、substring では
+ * なく trim 後にフッター文言で始まる行だけをダイアログとみなす。
+ */
+export declare function screenHasSelectionFooter(screen: string): boolean;
+/**
+ * 入力反映検証に使う probe（本文の**末尾側**）。検証不能な本文（空など）は null。
+ *
+ * 末尾側なのは composer の表示特性のため: 入力が表示高を超えると composer は下へ
+ * スクロールし**先頭行が窓外へ消える**（実測 2.1.220: 10行ペーストで先頭4行が
+ * capture から消失）。カーソルは常に末尾にあるので、末尾側の probe だけが
+ * 「見えている範囲」との照合を保証できる（先頭24字の旧 probe は多行/長文で
+ * 構造的に偽陰性 → 再投入 → 本文二重化の温床だった）。
+ *
+ * 先頭 `!`（シェルモード）は claude TUI がモード記号として吸い上げ、入力欄本文には
+ * 残らない（`!ls -la` は `! ls -la` と描画される）。単一行本文では照合キーからも
+ * 落とさないと末尾24字に `!` が含まれるとき反映検証が失敗する。
+ */
+export declare function typedTextProbe(text: string): string | null;
+/**
+ * 入力欄テキストに probe が反映されているか（折り返し非依存）。
+ * extractClaudeInputBox は表示行を trim + "\n" 連結で返すため、probe が入力欄の
+ * 行折り返しをまたぐと生の includes は絶対に一致しない（全角24字=48桁 > 内幅で必発）。
+ * この偽陰性が「反映済み本文の再投入 = 初回送信の本文二重化」の根因だった（実機5件）。
+ * 空白類（折り返しの改行・trim 痕・全角空白含む）を両辺から除去して照合する。
+ */
+export declare function inputBoxTextIncludesProbe(boxText: string, probe: string): boolean;
+/** herdr CLI の JSON stdout から `result` を取り出す。JSON でない/エラー封筒は null。 */
+export declare function parseHerdrResult(stdout: string): Record<string, unknown> | null;
+/** `pane list` の 1 pane 分。 */
+export interface HerdrPane {
+    paneId: string;
+    label: string | null;
+    /** pane を収容するタブ ID（タブラベル書換=session-title に使う。旧形式は null）。 */
+    tabId: string | null;
+}
+/** `pane list` stdout をパースする（形式不明は空配列）。 */
+export declare function parseHerdrPaneList(stdout: string): HerdrPane[];
+/**
+ * herdr 0.7.5 の `tab create` が自動付与する既定タブラベル（連番文字列 "1"/"2"…）か。
+ * 既定ラベルは「未命名」として扱う: hub tick の自動タイトルは上書きしてよく、
+ * 逆方向同期（displayTitle）は人為リネームと誤認して会話タイトルへ取り込んではならない。
+ */
+export declare function isDefaultHerdrTabLabel(label: string): boolean;
+/** `tab list` stdout を tab_id → label のマップにパースする（形式不明は空マップ）。 */
+export declare function parseHerdrTabLabels(stdout: string): Map<string, string>;
+/** `workspace list` から label 一致の workspace_id を探す（不在は null）。 */
+export declare function parseHerdrWorkspaceId(stdout: string, label: string): string | null;
+/** `workspace create` stdout から workspace_id を取り出す（失敗は null）。 */
+export declare function parseHerdrCreatedWorkspaceId(stdout: string): string | null;
+/** `agent start` stdout から pane_id を取り出す（失敗は null）。 */
+export declare function parseHerdrStartedPaneId(stdout: string): string | null;
+/** `tab create` stdout から root pane の pane_id を取り出す（失敗は null）。 */
+export declare function parseHerdrCreatedTabPaneId(stdout: string): string | null;
+/**
+ * `pane get` stdout から agent_status を取り出す（判定不能は null）。
+ * 0.7.5 では `agent get <name>` が使えない（agent レジストリは herdr の自動検出のみで
+ * Tailii のセッション名を知らず agent_not_found になる）ため、pane 単位の status を読む。
+ */
+export declare function parseHerdrPaneAgentStatus(stdout: string): string | null;
+/** `pane process-info` stdout から前面プロセス名を取り出す（判定不能は空文字）。 */
+export declare function parseHerdrForegroundCommand(stdout: string): string;
+/** herdr backend のセッション list / reattach / kill / send / read とメタデータ統合。 */
+export declare class HerdrSessionManager {
+    private readonly runner;
+    readonly store: SessionMetadataStore;
+    private readonly captureLines;
+    private readonly protocolVersion;
+    /** sendTextSubmit の本文→CR 間隔 ms（実測 300ms 未満で CR が飲まれる。テスト注入用）。 */
+    private readonly submitDelayMs;
+    /** sendTextSubmit の CR→残留確認 間隔 ms（テスト注入用）。 */
+    private readonly submitVerifyDelayMs;
+    /** 入力欄へ本文が反映されなかったときの再投入間隔 ms（RC 切断 limbo 対策）。 */
+    private readonly inputRetryDelayMs;
+    /** clearInputBox の C-u 1回ごとの反映待ち ms（実測レイテンシ 9〜27ms。テスト注入用）。 */
+    private readonly clearKeyDelayMs;
+    /** 注入前の claude 検出待ちの上限/間隔 ms（テスト注入用）。 */
+    private readonly readyTimeoutMs;
+    private readonly readyPollMs;
+    constructor(options?: {
+        runner?: HerdrCommandRunner;
+        store?: SessionMetadataStore;
+        captureLines?: number;
+        protocolVersion?: number;
+        submitDelayMs?: number;
+        submitVerifyDelayMs?: number;
+        inputRetryDelayMs?: number;
+        clearKeyDelayMs?: number;
+        readyTimeoutMs?: number;
+        readyPollMs?: number;
+    });
+    /**
+     * herdr 担当（メタの backend=herdr）のセッションを name/cwd/alive で列挙する（name 昇順）。
+     * tmux 側と異なり herdr pane は名前で自己申告しないため、メタデータが列挙の権威。
+     * 生存は「記録済み pane ID が現存」または「pane label が session 名に一致」。
+     */
+    list(): Promise<SessionInfo[]>;
+    /**
+     * 生存 pane の session 名 → { tabId, tabLabel } を返す（session-title の自動タイトル同期用）。
+     * pane label（= セッション解決の権威）が無い pane・タブ不明の pane は含めない。
+     */
+    tabInfoByName(): Promise<Map<string, {
+        tabId: string;
+        label: string | null;
+    }>>;
+    /** `tab list` を tab_id → label で読む（失敗は空マップ = displayTitle 無しに倒す）。 */
+    private tabLabels;
+    /** 既存セッションへ reattach（生存: attached / 不在: session_not_found エラー封筒）。 */
+    reattach(name: string): Promise<ReattachResult>;
+    /** pane 内のエージェント生存判定。herdr エラーや空出力は二重起動を避けて true に倒す。 */
+    agentProcessAlive(name: string): Promise<boolean>;
+    /**
+     * 会話カスタムタイトルの端末表示追随（session-title）: pane を収容するタブのラベルを
+     * 書き換える（`tab rename`）。pane の label はセッション解決の権威（findPane の
+     * fallback / list の生存判定）なので触らない。title 空/null は解除=セッション名へ戻す
+     * （未命名扱いになり hub tick の自動タイトルが再適用される）。
+     */
+    setDisplayTitle(name: string, title: string | null): Promise<void>;
+    /** 指定セッションの pane のみを閉じる（herdr pane close）。 */
+    kill(name: string): Promise<void>;
+    /**
+     * 本文入力と送信確定を 1 操作で行う（chat 注入・kick 用, SessionBackend 共通面）。
+     * 実測（2026-07-22, jsonl を ground truth に検証）:
+     * - 本文+CR の単一 send-text は不成立（ペースト末尾の改行として除去され本文が残る）
+     * - 分割送信でも claude TUI ブート直後は 600ms 間隔の CR すら飲まれる
+     *   （アイドル時は 300ms 以上で成立。遅れて送る単発 CR は常に成立）
+     * よって「本文 → CR → 入力欄を読んで残留確認 → 残っていれば CR 再送」の確認つき
+     * リトライで確定させる。submit 済みの空入力への Enter は no-op なので二重送信は起きない。
+     */
+    sendTextSubmit(name: string, text: string): Promise<void>;
+    /**
+     * 入力欄に probe テキストが反映されているか。
+     * ペイン履歴の同文エコー（同一メッセージの再送時など）を誤って「入力済み」と
+     * 判定しないよう、走査範囲を入力欄（末尾の罫線に挟まれた領域）に限定する。
+     * 判定不能は false。
+     */
+    private inputBoxContainsText;
+    /**
+     * 入力欄を空にする（反映検証が偽陰性だったときの再投入前クリア／throw 前の残骸掃除）。
+     * C-u(kill-line) のみを繰り返す（実測: 2N-1 回で必ず空になる。Backspace は本文の
+     * 実文字を削るため使わない）。空にできたら true。次の場合は false を返し、呼び出し側は
+     * 再投入を諦める:
+     * - 選択/承認ダイアログ表示中（本文側の罫線を入力欄と誤認して C-u を撃ち込むと
+     *   既存の誤 Esc/誤 Continue と同型の実害になるため、書き込み自体をしない）
+     * - 入力欄が見えない（罫線が窓外・描画崩れ・capture 失敗）
+     * - 上限回数で空にならない（1回150ms×15回=2.25s。iOS の chat_send ACK 予算 18s の
+     *   内側で速やかに諦めて明示再送へ倒す）
+     *
+     * トレードオフ（意図的な設計判断）: 中断直後に claude が queued 本文を composer へ
+     * 書き戻すタイミングと重なると、そのテキストも C-u で消える（receipt なしの破棄）。
+     * 再投入前クリアを省くと「本文二重化」という別のデータ破損になるため、注入経路では
+     * 「重複より欠落」を選ぶ（残存の主経路は sendTextSubmit 冒頭の Enter flush が先に守る）。
+     */
+    private clearInputBox;
+    /**
+     * 入力欄がシェルモード（プロンプト `!`）なら Backspace でモード記号を消し、通常入力へ戻す。
+     * 本文が残っている状態では呼ばない（呼び出し元が Enter で送信し切ってから使う）。
+     *
+     * 判定不能・herdr エラーは no-op（fail-open）。pane 不在などの実エラーはここで throw せず、
+     * 続く本文注入の `send-text` 失敗として顕在化させる（この補助操作のエラーを表に出すと
+     * 「送信できない」原因が Backspace 送出の失敗に見えてしまう）。
+     */
+    private exitShellMode;
+    /**
+     * claude TUI の選択ダイアログ（`Enter to select` フッター）が表示中か。判定不能は false。
+     *
+     * 窓は入力欄判定より狭い 30 行に据え置く（ダイアログのフッターは画面最下部にあるので
+     * 広げる必要が無い一方、閉じたダイアログの転写が viewport に残っていると誤検出し、
+     * 不要な Esc で入力欄の打ちかけを「送信されないまま」消してしまう）。
+     */
+    private selectionDialogVisible;
+    /**
+     * claude TUI の入力準備完了（herdr の agent 検出が unknown を抜ける）を待つ。
+     * 0.7.5 で `agent get <name>` は常に agent_not_found（レジストリが herdr 自動検出のみで
+     * セッション名を知らない）になり、旧実装は毎送信 10s のタイムアウト空回りになっていた
+     * （実機FB 2026-07-30: 送信後の pending / ライブビュー点灯が遅い）。pane を解決して
+     * `pane get` の agent_status を読む。pane 不在は即 fail-open（後続 sendKeys が
+     * pane not found で正しく失敗する）。
+     */
+    private waitForAgentReady;
+    /**
+     * claude TUI の入力欄に未送信テキストが残っているか。
+     * 送信済みメッセージのエコーも `❯` で始まるため、入力欄（末尾の罫線に挟まれた領域）
+     * だけを見る。判定不能（読取失敗・入力欄を特定できない）は false = 送信成立扱い
+     * （fail-open。誤リトライしても空入力 Enter の no-op で無害だが、無限再送はしない側に倒す）。
+     */
+    private inputBoxHasPendingText;
+    /**
+     * 指定セッションの pane へキー/テキストを送出する。
+     * literal はテキスト送出。非 literal は herdr が受理するキー名のみ send-keys、
+     * BTab は生 Shift+Tab シーケンス、その他（数字キー等）はテキストとして送る。
+     */
+    sendKeys(name: string, keys: string[], literal?: boolean): Promise<void>;
+    /**
+     * pane 末尾 N 行を返す（tmux capture-pane 相当。末尾空行は削る）。
+     * joinWrappedLines は herdr の recent-unwrapped（折返し結合済み出力リング）を使い、
+     * リング未充填の新規 pane では visible（viewport 全行）へフォールバックする。
+     */
+    capturePane(name: string, options?: CapturePaneOptions): Promise<string>;
+    /**
+     * 入力欄判定用に **viewport 全体**を取る（末尾 N 行で切らない）。
+     *
+     * claude TUI の入力欄の最大高さは端末サイズにほぼ比例する（実測 2.1.220:
+     * 63 行端末で 26 行 / 120 行端末で 55 行）。固定行数の窓では大きな端末で上罫線が
+     * 窓外に出て入力欄を見失い、本文を 3 回重ね打ちして送信失敗する。窓を広く取っても
+     * `extractClaudeInputBox` は罫線で入力欄を切り出すので過検出にはならない。
+     * `--source visible` は viewport 全行を返す（`--lines` は無視される）。
+     */
+    private captureVisibleScreen;
+    private readPane;
+    /**
+     * tailii セッションの server を pane ゼロのときだけ停止する（reaper の空サーバー回収）。
+     * tmux server の「セッションゼロで自動終了」に対応する挙動。launch 側に ensure（不在なら
+     * detached 起動）があるため、停止しても次のセッション起動で自動復帰する。
+     * ユーザーが tailii セッション内に手動 pane を作っていた場合は停止しない（pane 総数で判定）。
+     */
+    stopServerIfEmpty(): Promise<void>;
+    /** 生存 pane の一覧。herdr server 未起動などの失敗は空集合として扱う（tmux `ls` と同じ流儀）。 */
+    private livePanes;
+    /** セッション名の現存 pane を解決する（記録済み pane ID 優先、無ければ label 一致）。 */
+    private findPane;
+    /** 入出力 target の pane ID（現存しなければ null）。 */
+    private paneTarget;
+}