tailii-host 0.1.1 → 0.3.0

package/dist/engine/context.js

@@ -0,0 +1,184 @@
+// engine/context.ts
+// engine の 1 接続分の共有状態（HandlerContext）と、ハンドラ横断で使う小ヘルパー群。
+// handleLine のドメイン別ハンドラ（handlers/）は全てここ経由で状態に触る。
+import { randomUUID } from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import { bumpHeartbeat } from "../sessions/heartbeat.js";
+import { PROTOCOL_V1, } from "../protocol.js";
+import { claudeProjectSlug } from "../shared/paths.js";
+import { sleep } from "../shared/sleep.js";
+export function engineDiag(message) {
+    if (process.env["TAILII_DEBUG"] === "1")
+        process.stderr.write(`[tailii-host engine] ${message}\n`);
+}
+export const DEFAULT_MODE_TIMING = {
+    getPollMs: 250,
+    getAttempts: 4,
+    setInitialPollMs: 300,
+    setInitialTimeoutMs: 10_000,
+    setChangePollMs: 150,
+    setChangeTimeoutMs: 1_500,
+};
+/**
+ * chat オープン/再オープン時、そのセッションに未回答の設問があれば question_prompt を再送する。
+ * 未回答の間 transcript に tool_use 行が無く履歴再生では設問が復元されないため、engine の
+ * 保持分から再掲する（question-hook-relay）。
+ */
+export async function emitPendingQuestion(ctx, session) {
+    const pending = await ctx.requestHubState(session);
+    if (pending === null)
+        return;
+    ctx.writer.write({
+        type: "question_prompt",
+        v: PROTOCOL_V1,
+        id: pending.id,
+        questions: pending.questions,
+    });
+}
+export function subscribeConversation(ctx, session, newerThanMs) {
+    const previous = ctx.activeChatSession.name;
+    if (previous !== null && previous !== session) {
+        if (ctx.processingSessions.has(previous)) {
+            ctx.backgroundChatSessions.add(previous);
+            ctx.hubLink.send({ type: "conversation_subscribe", session: previous, preview: false });
+        }
+        else {
+            ctx.backgroundChatSessions.delete(previous);
+            ctx.hubLink.send({ type: "conversation_unsubscribe", session: previous });
+        }
+    }
+    ctx.activeChatSession.name = session;
+    ctx.backgroundChatSessions.delete(session);
+    ctx.hubLink.send({ type: "conversation_subscribe", session,
+        ...(newerThanMs !== undefined
+            ? { newerThanMs }
+            : ctx.lastServerSeq.has(session) ? { afterSeq: ctx.lastServerSeq.get(session) } : {}),
+        preview: true });
+}
+/** prepare 中は購読を始めず、reaper が読む権威ファイルの idle deadline だけを即時に更新する。 */
+export function touchPreparedSession(ctx, session) {
+    try {
+        bumpHeartbeat(ctx.heartbeatDir, session, Date.now() / 1_000, "session-prepare");
+        return true;
+    }
+    catch {
+        // heartbeat を更新できないまま成功 ack を返すと、直後の reaper tick による kill を
+        // クライアントが防げない。prepare 自体を構造化エラーとして失敗させる。
+        return false;
+    }
+}
+/** 通常オープンは購読を開始し、prepare は購読せず heartbeat だけを保護する。 */
+export async function activateOrTouchSession(ctx, writer, version, requestId, session, shouldSubscribe, newerThanMs) {
+    if (shouldSubscribe) {
+        subscribeConversation(ctx, session, newerThanMs);
+        await emitPendingQuestion(ctx, session);
+        return true;
+    }
+    if (touchPreparedSession(ctx, session))
+        return true;
+    writeError(writer, version, requestId, "session_prepare_heartbeat_failed", "セッションの保護時刻を更新できませんでした。");
+    return false;
+}
+export async function claimRuntime(ctx, session) {
+    const id = randomUUID();
+    try {
+        const result = await ctx.hubRpc({ type: "runtime_claim", id, session }, id, 1_500);
+        return result.status;
+    }
+    catch {
+        // Hub 障害時は可用性を優先し、排他導入前と同じく engine 自身で起動を続行する。
+        return "granted";
+    }
+}
+export async function waitForLiveSession(sessionManager, predicate) {
+    const deadline = Date.now() + 8_000;
+    while (Date.now() < deadline) {
+        const found = (await sessionManager.list()).find((info) => info.alive && predicate(info));
+        if (found !== undefined)
+            return found;
+        await sleep(500);
+    }
+    return null;
+}
+export async function officialAppRuntimeContext(ctx, session, provider) {
+    if (ctx.activeChatSession.name !== session)
+        return { reason: "official_app_focus_changed" };
+    const meta = ctx.metadataStore?.get(session) ?? null;
+    if ((meta?.agent ?? ctx.defaultAgent) !== provider) {
+        return { reason: "official_app_provider_mismatch" };
+    }
+    try {
+        if (!(await ctx.sessionManager.agentProcessAlive(session))) {
+            return { reason: "official_app_session_not_live" };
+        }
+    }
+    catch {
+        return { reason: "official_app_session_not_live" };
+    }
+    let pending;
+    try {
+        const id = randomUUID();
+        const response = await ctx.hubRpc({ type: "hub_state_request", id, session }, id, 1_500);
+        pending = response.pendingQuestion;
+        if (response.processing) {
+            ctx.processingSessions.set(session, Math.floor(Date.now() / 1_000));
+        }
+        else {
+            ctx.processingSessions.delete(session);
+        }
+    }
+    catch {
+        return { reason: "official_hub_state_unavailable" };
+    }
+    if (ctx.activeChatSession.name !== session)
+        return { reason: "official_app_focus_changed" };
+    let codexTurnActive = false;
+    for (const processingSession of ctx.processingSessions.keys()) {
+        const processingMeta = ctx.metadataStore?.get(processingSession) ?? null;
+        if ((processingMeta?.agent ?? ctx.defaultAgent) === "codex") {
+            codexTurnActive = true;
+            break;
+        }
+    }
+    // Remote Control URL の権威は transcript の bridge_status 行（pane 引用に汚染されない）。
+    const claudeSessionId = meta?.claudeSessionId;
+    const claudeTranscriptPath = provider === "claude" &&
+        meta !== null &&
+        typeof claudeSessionId === "string" &&
+        /^[A-Za-z0-9-]+$/u.test(claudeSessionId)
+        ? path.join(os.homedir(), ".claude", "projects", claudeProjectSlug(meta.cwd), `${claudeSessionId}.jsonl`)
+        : null;
+    return {
+        context: {
+            session,
+            provider,
+            sessionManager: ctx.sessionManager,
+            canInjectClaudeCommand: !ctx.processingSessions.has(session) && pending === null,
+            canMutateCodexDaemon: !codexTurnActive,
+            claudeTranscriptPath,
+        },
+    };
+}
+/** session_list_response を書き出す（optional cursor / host 採用名は null なら省略）。 */
+export function writeSessionListResponse(writer, v, id, sessions, nextCursor, adoptedName = null, worktree = null) {
+    writer.write({
+        type: "session_list_response",
+        v,
+        id,
+        sessions,
+        ...(nextCursor !== null && { nextCursor }),
+        ...(adoptedName !== null && { adoptedName }),
+        ...(worktree !== null && worktree),
+    });
+}
+/** error 封筒を書き出す小ヘルパー。 */
+export function writeError(writer, v, id, code, message) {
+    try {
+        writer.write({ type: "error", v, ...(id !== undefined && { id }), code, message });
+    }
+    catch (error) {
+        process.stderr.write(`[tailii-host engine] error 送出失敗: ${String(error)}\n`);
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/engine/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"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"}

package/dist/engine/engine.d.ts

@@ -0,0 +1,121 @@
+import type { Readable, Writable } from "node:stream";
+import type { ChatAgent } from "../chat/chatTailController.js";
+import { type CodexAccountUsageProvider } from "../codex/codexAccountUsage.js";
+import { CodexAppServerManager } from "../codex/codexAppServer.js";
+import { type CodexTurnControllerRuntime } from "../codex/codexNativeTurnController.js";
+import { ClaudeSessionStore } from "../sessions/claudeSessionStore.js";
+import { CodexSessionStore } from "../codex/codexSessionStore.js";
+import { type HubLink } from "../hub/hubClient.js";
+import { ImageService } from "../chat/imageService.js";
+import { type EngineLauncher } from "../commands/launch.js";
+import { type ClaudeModelListProvider } from "../services/claudeModelCatalog.js";
+import { type AccountIdentityProvider } from "../services/accountIdentity.js";
+import { type HostVersionsProvider } from "../services/hostVersions.js";
+import { type PlanUsageProvider } from "../services/planUsageFetcher.js";
+import { SessionListService } from "../sessions/sessionListService.js";
+import { SessionMetadataStore } from "../sessions/sessionMetadataStore.js";
+import { OfficialAppsService } from "../services/officialApps.js";
+import { TranscriptTailer } from "../chat/transcriptTailer.js";
+import { type SessionBackend, type SessionBackendKind } from "../backend/sessionBackend.js";
+import { type StaleDistGuard } from "../shared/version.js";
+import { type ModeTiming } from "./context.js";
+/**
+ * engine サブコマンドのエントリポイント。実 stdin/stdout を使って EngineControl を起動する。
+ * 引数（省略可、統合テスト注入用）: --sessions-dir / --inner-command / --images-dir /
+ * --transcript / --claude-projects-dir / --idle-timeout / --resume-command。
+ */
+/**
+ * 既定エージェントを host 側設定から解決する（`--agent` 未指定時のフォールバック）。
+ * `~/.tailii/agent` の内容が `codex` なら codex、それ以外/不在は claude。
+ * これにより iOS を改修せず（engine 起動コマンドは `<binary> engine` のまま）codex に切替できる。
+ */
+export declare function resolveDefaultAgent(agentFilePath?: string): ChatAgent;
+export declare function runEngineCommand(args: string[]): Promise<number>;
+export interface RunEngineOptions {
+    /** "stdin" 側（iOS→Mac の制御要求が流れてくる）。 */
+    input: Readable;
+    /** "stdout" 側（Mac→iOS の応答を流す）。 */
+    output: Writable;
+    sessionManager: SessionBackend;
+    /** 新規セッションの端末バックエンド解決子（既定 tmux 固定。per-session launcher 組立と backend_get/set に使う）。 */
+    backendKind?: () => SessionBackendKind;
+    /** backend_set の永続化先（テスト注入用。既定は `~/.tailii/backend` への書き込み）。 */
+    backendWriter?: (kind: SessionBackendKind) => void;
+    /** herdr 導入済み判定（テスト注入用。既定は実バイナリの存在検査）。 */
+    herdrInstalledProbe?: () => boolean;
+    /** 画像通知/取得の橋渡し（省略時は画像処理なし = 後方互換）。 */
+    imageService?: ImageService | null;
+    /** 会話出力キャプチャ（省略時は chat_output なし = 後方互換）。 */
+    transcriptTailer?: TranscriptTailer | null;
+    /** tail 対象の claude セッショントランスクリプト JSONL の絶対パス。 */
+    transcriptPath?: string | null;
+    /** session_start の橋渡し先。省略時（null）は error(launch_failed) を返す安全側既定。 */
+    launcher?: EngineLauncher | null;
+    /** codex セッション用 launcher（agentType=codex 時）。省略時は launcher にフォールバック。 */
+    codexLauncher?: EngineLauncher | null;
+    sessionListService?: SessionListService | null;
+    metadataStore?: SessionMetadataStore | null;
+    /** @deprecated heartbeat 書き込みは Hub が所有する。 */
+    heartbeatDir?: string | null;
+    /** @deprecated heartbeat tick は Hub が所有する。 */
+    heartbeatTickSeconds?: number;
+    resumeLauncher?: EngineLauncher | null;
+    /** codex セッションの reattach 時 resume 用 launcher。省略時は resumeLauncher にフォールバック。 */
+    codexResumeLauncher?: EngineLauncher | null;
+    claudeSessionStore?: ClaudeSessionStore | null;
+    /** codex 会話一覧の導出（agent-tag）。省略時は codex 会話を一覧に含めない（後方互換）。 */
+    codexSessionStore?: CodexSessionStore | null;
+    /** 対象エージェント（既定 claude）。codex は rollout tail を使う。 */
+    agent?: ChatAgent;
+    /** Codex turn/approval を同一 App Server 接続で扱う共有 runtime。 */
+    codexAppServer?: CodexAppServerManager | null;
+    /** Claude / ChatGPT 公式アプリ連携。null は機能無効、未指定は固定コマンド実装。 */
+    officialApps?: OfficialAppsService | null;
+    /** テスト注入用の native turn controller。指定時は codexAppServer より優先する。 */
+    codexTurnController?: CodexTurnControllerRuntime | null;
+    /** 自分がサポートする最大版（既定 PROTOCOL_MAX_SUPPORTED）。 */
+    maxVersion?: number;
+    /** プラン使用状況の取得（既定は実 OAuth 使用量 API。テストは () => null を注入する）。 */
+    planUsage?: PlanUsageProvider;
+    /** Claude モデル一覧の取得（既定は実 Models API。テストは固定値/null を注入する）。 */
+    claudeModelList?: ClaudeModelListProvider;
+    /**
+     * Codex アカウント使用量の取得（既定は `codexAppServer` 経由の実 App Server 呼び出し。
+     * テストは固定値/null を注入する, account-usage）。
+     */
+    codexAccountUsage?: CodexAccountUsageProvider;
+    /**
+     * ホスト環境のバージョン情報（既定は package.json + `claude/codex --version`。
+     * プロセス内キャッシュ付き。テストは固定値/null を注入する, account-usage）。
+     */
+    hostVersions?: HostVersionsProvider;
+    /**
+     * ログイン中アカウントのマスク済み表示（既定は `claude auth status` + `~/.codex/auth.json`。
+     * プロセス内キャッシュ付き。テストは固定値を注入する, account-usage）。
+     */
+    accountIdentity?: AccountIdentityProvider;
+    /** slash_list のユーザーレベル探索ルート（既定は os.homedir()）。 */
+    homeDir?: string;
+    /** mode_get/mode_set の待機間隔（テストは短縮値を注入する）。 */
+    modeTiming?: Partial<ModeTiming>;
+    /** 起動時 package version と現在の package version を比較する stale 判定（テスト注入用）。 */
+    staleDistGuard?: StaleDistGuard | null;
+    /**
+     * channel_hello に載せるマシン名（既定は scutil ComputerName → os.hostname()）。
+     * iOS の接続先一覧タイトルの供給源。null は省略（テスト注入用）。
+     */
+    hostDisplayName?: string | null;
+    /** stale dist 検出時の通知（CLI では return によりプロセス終了、テストは観測用）。 */
+    onStaleDist?: () => void;
+    /** @deprecated Hub 移管前のテスト互換。現在は使用しない。 */
+    engineRelaySocketPath?: string | null;
+    /** Session Hub link。省略時は daemon の hub.sock へ接続する。 */
+    hubLink?: HubLink;
+    /** Codex Hub start ACK の待機時間（テスト注入用、既定15秒）。 */
+    codexHubRpcTimeoutMs?: number;
+}
+/**
+ * EngineControl の本体。`input` から NDJSON 行を読み、session_* を `sessionManager` に
+ * 橋渡しし、応答を `output` へ NDJSON 行で書く。EOF（input end）で正常終了する。
+ */
+export declare function runEngine(options: RunEngineOptions): Promise<void>;