tailii-host 0.1.0 → 0.3.0

package/dist/codex/codexAppServer.d.ts

@@ -0,0 +1,166 @@
+import type { CodexModelInfo } from "../protocol.js";
+export type CodexAppServerSandbox = "read-only" | "workspace-write" | "danger-full-access";
+export type CodexAppServerApprovalPolicy = "untrusted" | "on-request" | "never";
+export interface CodexThreadStartOptions {
+    cwd: string;
+    model?: string | null;
+    sandbox?: CodexAppServerSandbox | null;
+}
+export interface CodexThreadTitleGenerationOptions {
+    threadId: string;
+    cwd: string;
+    prompt: string;
+}
+export type CodexThreadTitleSource = "model" | "promptFallback";
+export interface CodexThreadTitleGenerationResult {
+    title: string | null;
+    source: CodexThreadTitleSource | null;
+}
+export type CodexAppServerRequestId = number | string;
+export interface CodexAppServerNotification {
+    method: string;
+    params: unknown;
+}
+export interface CodexAppServerRequest extends CodexAppServerNotification {
+    id: CodexAppServerRequestId;
+}
+export interface CodexAppServerThreadOptions {
+    threadId: string;
+    cwd?: string | null;
+    onNotification?: (notification: CodexAppServerNotification) => void;
+    onServerRequest?: (request: CodexAppServerRequest) => Promise<unknown>;
+    onDisconnect?: (error: Error) => void;
+}
+/** テスト差し替え可能なApp Server 1接続分。 */
+export interface CodexAppServerConnection {
+    initialize(): Promise<void>;
+    request(method: string, params: unknown, timeoutMs?: number): Promise<unknown>;
+    onNotification(handler: (notification: CodexAppServerNotification) => void): () => void;
+    onServerRequest(handler: (request: CodexAppServerRequest) => void): () => void;
+    onDisconnect?(handler: (error: Error) => void): () => void;
+    respond(id: CodexAppServerRequestId, result: unknown): void;
+    respondError(id: CodexAppServerRequestId, code: number, message: string): void;
+    close(): void;
+}
+export type CodexAppServerConnect = (socketPath: string, requestTimeoutMs?: number) => Promise<CodexAppServerConnection>;
+export type CodexAppServerLaunch = (executable: string, args: string[], env: NodeJS.ProcessEnv) => void | Promise<void>;
+/** 1 thread を購読し、Tailii から turn を開始する長寿命 App Server 接続。 */
+export declare class CodexAppServerThread {
+    readonly threadId: string;
+    readonly initialItems: readonly Record<string, unknown>[];
+    readonly initialActiveTurnId: string | null;
+    /**
+     * この接続で thread/resume（または作成元 bootstrap）が成功し、live 通知を受け取れるか。
+     * rollout 未生成の新規 thread は resume に失敗するため false。呼び出し側は初回 turn の
+     * 表示を rollout tail へフォールバックし、通知が来ない接続を live 権威にしない。
+     */
+    readonly liveSubscriptionReady: boolean;
+    private readonly connection;
+    private readonly cwd;
+    /** 読み取り専用の readiness 確認だけは、共有 App Server の一時的な混雑を自動回復する。 */
+    private static readonly activeTurnReadMaxAttempts;
+    private static readonly activeTurnReadRetryTimeoutMs;
+    /** null=未判定、true=stable ID対応、false=旧App ServerなのでIDなしsteerへ固定。 */
+    private supportsSteerClientUserMessageId;
+    constructor(threadId: string, initialItems: readonly Record<string, unknown>[], initialActiveTurnId: string | null, 
+    /**
+     * この接続で thread/resume（または作成元 bootstrap）が成功し、live 通知を受け取れるか。
+     * rollout 未生成の新規 thread は resume に失敗するため false。呼び出し側は初回 turn の
+     * 表示を rollout tail へフォールバックし、通知が来ない接続を live 権威にしない。
+     */
+    liveSubscriptionReady: boolean, connection: CodexAppServerConnection, cwd: string | null);
+    startTurn(text: string, clientUserMessageId?: string | null, effort?: string | null, sandbox?: "read-only" | "workspace-write" | "danger-full-access" | null, approvalPolicy?: CodexAppServerApprovalPolicy | null): Promise<string>;
+    readActiveTurnId(): Promise<string | null | undefined>;
+    /** 親履歴で欠落する sub-agent の終端状態を、子 thread 自身から読み直す。 */
+    readThreadStatus(threadId: string): Promise<{
+        status: unknown;
+        timestampMs?: number;
+    } | undefined>;
+    steerTurn(turnId: string, text: string, clientUserMessageId?: string | null): Promise<void>;
+    interruptTurn(turnId: string): Promise<void>;
+    close(): void;
+}
+export interface CodexAppServerManagerOptions {
+    codexHome?: string;
+    codexPath?: string;
+    socketPath?: string;
+    remoteEndpoint?: string;
+    connect?: CodexAppServerConnect;
+    launch?: CodexAppServerLaunch;
+    pollIntervalMs?: number;
+    startupTimeoutMs?: number;
+    titleGenerationTimeoutMs?: number;
+}
+/** thread/list の公開スキーマから一覧表示に必要なフィールドだけを保持する。 */
+export interface CodexAppServerThreadInfo {
+    id: string;
+    name: string | null;
+    preview: string | null;
+    updatedAt: number;
+    cwd: string | null;
+    source: unknown;
+    parentThreadId: string | null;
+}
+export type CodexRemoteControlState = "disabled" | "connecting" | "connected" | "errored";
+export interface CodexRemoteControlStatus {
+    status: CodexRemoteControlState;
+    hasEnvironment: boolean;
+}
+export interface CodexRemoteControlPairing {
+    pairingCode: string;
+    manualPairingCode: string | null;
+    expiresAt: number;
+}
+/** 1 CODEX_HOMEにつき1つのApp Serverを共有し、論理threadを作成する。 */
+export declare class CodexAppServerManager {
+    readonly socketPath: string;
+    readonly remoteEndpoint: string;
+    private readonly codexHome;
+    private readonly codexPath;
+    private readonly connect;
+    private readonly launch;
+    private readonly pollIntervalMs;
+    private readonly startupTimeoutMs;
+    private readonly titleGenerationTimeoutMs;
+    private readonly startupLockPath;
+    /** 最初の turn 前（rollout 未作成）の thread を生存させる作成元購読。openThread が引き継ぐ。 */
+    private readonly bootstrapConnections;
+    constructor(options?: CodexAppServerManagerOptions);
+    /** serverを再利用または排他的に起動し、利用可能になるまで待つ。 */
+    ensureRunning(): Promise<void>;
+    /** 稼働中の server にだけ接続する。停止中・不達時は起動せず null を返す。 */
+    connectIfRunning(requestTimeoutMs?: number): Promise<CodexAppServerConnection | null>;
+    /** 稼働中の server から thread/list を最大200件取得する。停止中なら null。 */
+    listThreads(maxThreads?: number): Promise<CodexAppServerThreadInfo[] | null>;
+    /**
+     * Codex App Server の正式な会話名を設定する。
+     *
+     * loaded thread と persisted rollout の両方を同じ API で更新できる。
+     * schema上は空文字もstringだが、実App Serverは `thread name must not be empty` で拒否する。
+     */
+    setThreadName(threadId: string, name: string): Promise<void>;
+    /** 現在共有中の App Server から Remote Control 状態を読む。 */
+    remoteControlStatus(): Promise<CodexRemoteControlStatus | null>;
+    /** 現在共有中の App Server 自体で Remote Control を有効化する。 */
+    enableRemoteControl(): Promise<CodexRemoteControlStatus | null>;
+    /** 現在共有中の App Server 自体で Remote Control を無効化する。 */
+    disableRemoteControl(): Promise<CodexRemoteControlStatus | null>;
+    /** 短命なペアリングコードを発行する。呼び出し側は URL 化後も永続化しない。 */
+    startRemoteControlPairing(): Promise<CodexRemoteControlPairing | null>;
+    /** 新規threadをApp Serverで作り、TUI起動前に安定IDを返す。 */
+    startThread(options: CodexThreadStartOptions): Promise<string>;
+    /**
+     * Codex Desktop と同じ短命 thread で初回 prompt の短いタイトルを生成し、対象 thread へ保存する。
+     * `gpt-5.6-luna` を優先し、App Server が利用不能と判断した場合は既定モデルへ委ねる。
+     */
+    generateThreadTitle(options: CodexThreadTitleGenerationOptions): Promise<CodexThreadTitleGenerationResult>;
+    /** ログイン中アカウントで利用可能なCodexモデルをApp Server APIから取得する。 */
+    listModels(): Promise<CodexModelInfo[]>;
+    /** 既存 thread を購読する長寿命接続を開く。turn と native approval はこの接続を流れる。 */
+    openThread(options: CodexAppServerThreadOptions): Promise<CodexAppServerThread>;
+    private probe;
+    private remoteControlRequest;
+    private waitUntilReady;
+    /** lockが他の生存processに所有されていればnull。死んだownerのlockは1回だけ回収する。 */
+    private acquireStartupLock;
+}