@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/providers/claude/transport/pty-query.d.ts

@@ -0,0 +1,493 @@
+import type { Logger } from "pino";
+import type { ModelInfo, SDKMessage, SDKSystemMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { type PtyTransport } from "./pty.js";
+import { type UserPromptLine } from "./transcript-sdk-reader.js";
+/** An interactive TUI dialog the user has to answer for the turn to continue. */
+export interface PtyInteractiveDialog {
+    toolUseId: string;
+    /** "AskUserQuestion" | "ExitPlanMode" */
+    name: string;
+    /** The tool_use input verbatim, so the app renders the real questions and options. */
+    input: Record<string, unknown>;
+    /** Option labels of the FIRST question, in on-screen order; empty when unknown. */
+    options: string[];
+    /**
+     * Option labels per question, in on-screen order. An AskUserQuestion call may carry
+     * several questions and the picker walks them one tab at a time, so a driver that only
+     * knows the first one answers question 1 and then waits forever for a tool_result that
+     * cannot arrive until every question is submitted.
+     */
+    optionsByQuestion: string[][];
+}
+export interface PtyQueryOptions {
+    transport: PtyTransport;
+    /** The shared input channel (createAsyncMessageInput().iterable) fed by startTurn(). */
+    input: AsyncIterable<SDKUserMessage>;
+    transcriptPath: string;
+    sessionId: string;
+    /** Optional synthesized system:init message. Omitted in MVP (not needed to render turns). */
+    initMessage?: SDKSystemMessage;
+    logger: Logger;
+    /**
+     * Transcript-silence budget for an in-flight turn, in ms. Defaults to
+     * {@link TURN_STALL_TIMEOUT_MS}. Pass `0` to disable the liveness backstop.
+     */
+    stallTimeoutMs?: number;
+    /**
+     * Called when the TUI starts (dialog) or finishes (null) waiting on an interactive
+     * question. The provider turns this into a permission request so the app can render
+     * the real options instead of an inert tool chip nobody can answer.
+     */
+    onDialogChange?: (dialog: PtyInteractiveDialog | null) => void;
+    /**
+     * Called with the transcript uuid of each plain user prompt claude writes. On PTY the
+     * prompt is typed into the terminal, so claude owns that uuid and paseo's own minted id is
+     * never on disk -- this is the only place the real one is observable. Identity only: it
+     * must not render anything.
+     */
+    onUserPrompt?: (prompt: UserPromptLine) => void;
+    /**
+     * Called with a short, sender-facing sentence when paseo knows something the person who
+     * sent the message cannot see. Today that is exactly one thing: the message was accepted
+     * but QUEUED behind a running turn, so the spinner they are looking at means "waiting in
+     * line", not "working on it".
+     *
+     * Everything PtyQuery already knew about this went to recordLine(), which appends to
+     * ~/.paseo/pty-recordings/<id>.log and reaches nobody.
+     */
+    onNotice?: (text: string) => void;
+}
+export declare class PtyQuery implements AsyncGenerator<SDKMessage, void> {
+    private readonly transport;
+    private readonly input;
+    private readonly sessionId;
+    private readonly transcriptPath;
+    private readonly logger;
+    private readonly reader;
+    private readonly onDialogChange;
+    private readonly onNotice;
+    /** One queued notice per message, not one per retry. Reset by deliverPrompt(). */
+    private queuedNoticeSent;
+    private readonly outQueue;
+    private readonly outResolvers;
+    private done;
+    private readonly readyPromise;
+    private offReadyData;
+    /** Unsubscribes the transport exit tap. Teardown MUST call this. */
+    private offExitTap;
+    /** Set once the agent process has exited; the two remaining "still running" claims read it. */
+    private transportExited;
+    /**
+     * Cancels the readiness gate and its timers.
+     *
+     * Teardown MUST call this. A query closed before the gate settles used to leave its
+     * deadline interval running, so a session that attached and detached in the same
+     * millisecond still logged "readiness gate hit its timeout" a full minute later, warning
+     * about a terminal nobody was waiting on and leaking a timer per closed session.
+     */
+    private cancelReadiness;
+    private turnEndTimer;
+    private lastStopReason;
+    private lastUsage;
+    private turnStartedAt;
+    private numTurns;
+    private readonly stallTimeoutMs;
+    private stallTimer;
+    private turnInFlight;
+    private terminalTail;
+    private offTerminalTap;
+    private readonly startedAt;
+    private recordingPath;
+    private recordingBytes;
+    private ptyBytesTotal;
+    private ptyBytesAtLastBeat;
+    private lastMeaningfulLine;
+    private lastTranscriptAt;
+    private heartbeatTimer;
+    private readySettledBy;
+    /** Last time the TUI footer said a turn was running. 0 = never seen. */
+    private lastBusyAt;
+    /**
+     * Serializes everything that TYPES into the terminal.
+     *
+     * Prompt delivery and control slash commands both write to the same single input line, and
+     * before this they ran on independent async paths with nothing ordering them.
+     */
+    private writeGate;
+    /** Last sighting of the large-session resume dialog. 0 = never seen. */
+    private resumeDialogAt;
+    /** Set when the CLI rejected the just-submitted command; carries the CLI's own reply. */
+    private rejectedCommandNotice;
+    /** Interactive TUI dialog awaiting the user (AskUserQuestion / plan approval), if any. */
+    private pendingDialog;
+    /**
+     * Raw capture window for echo verification. The rolling tail deliberately drops lines
+     * with fewer than three letters as spinner noise, which also swallows the echo of a
+     * short message: "> go" never reaches the tail, so verifying against the tail held a
+     * two-letter message forever. While this is non-null, appendTerminalTail mirrors every
+     * stripped chunk here unfiltered.
+     */
+    private echoProbe;
+    private interruptPromptAt;
+    constructor(opts: PtyQueryOptions);
+    private emit;
+    next(): Promise<IteratorResult<SDKMessage, void>>;
+    return(): Promise<IteratorResult<SDKMessage, void>>;
+    throw(error?: unknown): Promise<IteratorResult<SDKMessage, void>>;
+    [Symbol.asyncIterator](): AsyncGenerator<SDKMessage, void>;
+    private finish;
+    private runInputLoop;
+    /**
+     * The message the user sees when the terminal would not take their prompt.
+     *
+     * Only reachable while the query is still live (teardown breaks out before this), so it
+     * always describes a message that genuinely did not land and that only the user can
+     * resend. Shaped as a normal result so it renders in the timeline rather than being
+     * buried in the daemon log.
+     */
+    /** The CLI refused the command; relay its own reply so the sender can correct and resend. */
+    private buildCommandRejectedResult;
+    /**
+     * Write each inline base64 image block to a temp file so the terminal agent can Read it
+     * by path. A staging failure is logged and skipped rather than thrown: the text part of
+     * the message (if any) must still be delivered.
+     */
+    private stageInlineImages;
+    /**
+     * The message had no text and no stageable image, so there is literally nothing to type.
+     * Emitted instead of dropping the message, because the manager has already marked the
+     * agent running by the time the input loop sees it: silence here is a forever-spinner.
+     */
+    private buildNothingDeliverableResult;
+    /**
+     * " The session itself is still running." -- but only when it is.
+     *
+     * The exit tap fixes the in-flight turn and the stall message. These two other results
+     * asserted the same thing unconditionally and are reachable after the process is gone, so
+     * they need the same correction. Wording matches buildExitedResult: no "aborted", and
+     * "status" rather than "code", so isAbortError() cannot swallow it and
+     * buildTurnFailedEvent() cannot scrape a phantom exit code out of it.
+     */
+    private stillRunningClause;
+    /** Tell the provider the dialog state changed; never let a listener throw into the loop. */
+    private notifyDialogChange;
+    /** The dialog the TUI is waiting on, if any. */
+    interactiveDialog(): PtyInteractiveDialog | null;
+    /**
+     * Answer the pending dialog by option index (0-based), the way the app's question card
+     * does. Returns false when there is no dialog or the keystrokes never registered.
+     */
+    answerDialogByIndex(index: number): Promise<boolean>;
+    /**
+     * Answer a multi-question picker, one entry per question in on-screen order; a null
+     * leaves that question unanswered. The app's question card collects an answer for EVERY
+     * question, so collapsing them to a single index would throw away answers the user
+     * actually gave and submit those questions blank.
+     */
+    answerDialogByIndexes(indexes: Array<number | null>): Promise<boolean>;
+    /**
+     * Try to answer the pending TUI dialog with the user's reply. A reply that names an
+     * option (its 1-based number or its label) becomes Down-arrow presses + Enter, the same
+     * proven mechanism as the resume-dialog answerer. Anything else gets the question echoed
+     * back with the options, and nothing is typed - an unanswerable message must never turn
+     * into a silent decline.
+     */
+    private answerPendingDialog;
+    /**
+     * Answer the question with free text by driving the picker's own "Type something" entry.
+     *
+     * The entry number is READ OFF THE SCREEN rather than computed as options.length + 1:
+     * the CLI owns that list and appends more than one trailing entry (a free-text one and a
+     * chat one, verified against claude 2.1.239), so an offset derived from the tool input
+     * would silently drift the day the CLI adds another. Returns false when the entry is not
+     * on screen or the answer never registers, so the caller can still tell the sender.
+     */
+    private sendDialogFreeText;
+    /**
+     * 1-based number of the picker's free-text entry, or null when it is not on screen.
+     * Whitespace is squeezed out before matching because a redrawing TUI captured through a
+     * PTY loses spaces inside a line ("4.Typesomething." is a real observed frame).
+     */
+    private findFreeTextEntryNumber;
+    /**
+     * The dialog was driven and did not settle. Say so.
+     *
+     * This exists because of the failure it was written for: tapping an option on the app's
+     * question card resolved the permission, drove real keystrokes, answered the first
+     * question, and then stalled -- and every caller DISCARDED the false this returns, so the
+     * card vanished, the chip kept spinning, and nothing anywhere told the sender. The typed
+     * path had a result message to fall back on; the card path had nothing at all. A notice
+     * at the point of failure covers both callers instead of one.
+     */
+    private notifyDialogDriveFailed;
+    /** Sender-facing line; never let a listener throw into the delivery loop. */
+    private notify;
+    /**
+     * Drive the dialog's own keys: Down to the option, Enter to confirm. Confirmation is the
+     * tool_result landing in the transcript (which clears pendingDialog) - an optimistic flag
+     * here would record intent as fact.
+     */
+    private sendDialogAnswer;
+    /**
+     * Walk a multi-question picker to its Submit tab and confirm.
+     *
+     * Only the first question has an answer here (a reply, or the app card's choice), so the
+     * rest are submitted unanswered on purpose: the CLI supports exactly that and reports it
+     * to the model ("Beta went unanswered"), which is strictly better than the alternative
+     * this replaces, where the dialog stayed up until somebody cancelled it.
+     *
+     * Every step is screen-verified rather than counted, because the number of Tabs between
+     * the focused question and Submit depends on how many questions are left.
+     */
+    private finishMultiQuestionDialog;
+    /**
+     * Tab until the picker's review tab is on screen, then confirm the pre-selected
+     * "1. Submit answers". Screen-verified rather than counted: how many Tabs away Submit
+     * is depends on how many questions are left. Returns false if it never got there, so
+     * the caller does not claim a submission that did not happen.
+     */
+    private reachSubmitTabAndConfirm;
+    /** True when the picker is showing its review/Submit tab. */
+    private onSubmitTab;
+    /** The agent is waiting on a dialog; tell the sender what it asks and how to answer. */
+    private buildDialogPendingResult;
+    private buildSubmitFailedResult;
+    /**
+     * Press Enter to submit the composed prompt, and CONFIRM the turn actually started by
+     * watching for the USER LINE claude appends to <sid>.jsonl the instant it accepts a turn.
+     * During boot the TUI intermittently swallows the first Enter (a "what's new" notice /
+     * MCP-auth warning steals focus), so retry until it takes.
+     *
+     * The confirmation used to be `transcriptSize() > before`, which is any growth at all.
+     * That is not specific to the turn starting: claude writes `attachment`, `last-prompt`
+     * and other bookkeeping lines on its own schedule, so a swallowed Enter that happened to
+     * coincide with unrelated writes read as success. Observed in production 2026-08-01: a
+     * session logged 157 consecutive `attachment` lines and NOT ONE `user` line, yet
+     * submitTurn returned on the first attempt. The prompt stayed unsent in the TUI composer,
+     * paseo set turnInFlight and waited on a turn that had never begun, and the agent showed
+     * a spinner until the liveness backstop fired ten minutes later. The retry loop below was
+     * always right; the thing it was checking was not.
+     */
+    /**
+     * Dismiss the post-interrupt modal if the terminal is showing one. ESC is only sent on a
+     * recent sighting: on an idle prompt it is harmless, but on a live turn it would interrupt
+     * real work, so a stale marker must never trigger it.
+     */
+    private clearInterruptPrompt;
+    /**
+     * Answer the large-session resume dialog with "Resume full session as-is".
+     *
+     * Must run BEFORE anything is typed: text typed while the menu is up is eaten by it, and
+     * an Enter confirms the pre-selected "Resume from summary", compacting the session the
+     * user was trying to talk to. Down moves the selection off option 1; Enter confirms
+     * option 2. Only acts on a recent sighting, because on any other screen a stray
+     * Down+Enter is at best a wasted keystroke and at worst an answer to a different menu.
+     */
+    private answerResumeDialog;
+    /**
+     * Type the prompt and confirm the terminal actually received it, retrying against a
+     * deaf terminal with backoff.
+     *
+     * Returns true once an echo (or a transcript user line) confirms the keystrokes landed;
+     * false only after the terminal stayed deaf for the whole {@link READY_BUSY_MAX_WAIT_MS}
+     * ceiling. Retyping cannot double-deliver: a deaf terminal demonstrably discards input
+     * (zero echo), and every iteration first checks whether a user line landed anyway.
+     */
+    /**
+     * Empty the input box before a retype. Ctrl+U kills the line the TUI is composing; a
+     * pasted chip is dropped the same way. Best-effort: a transport that cannot take raw
+     * keys just leaves the composer as it was.
+     */
+    /**
+     * Is the TUI currently showing its "queued messages" footer?
+     *
+     * This reads a CLI STATUS LINE, not a rendering of our own text. The distinction matters
+     * because this file has (rightly) burned four incidents on trusting renderings as proof
+     * of DELIVERY -- bytes, then echoed text, then a raw probe, then a paste chip. Delivery
+     * is still proved by one thing only, a matching `user` record. The footer answers a
+     * different and much cheaper question: is a turn running right now. The CLI is the
+     * authority on that, and it prints the answer.
+     */
+    private queuedFooterVisible;
+    /** Tell the sender their message is in line, once per message. */
+    private notifyQueued;
+    private clearComposer;
+    /**
+     * Deliver a prompt and prove it, or say it failed. See docs/pty-delivery.md.
+     *
+     * One authority: a transcript user record matching the text. Nothing the terminal paints
+     * gates this - echoed characters, paste chips, boot noise and footer hints are renderings,
+     * and renderings changed with every CLI version while this code kept "discovering" new
+     * ones (bytes -> text -> raw probe -> paste chip, four incidents, same defect each time).
+     *
+     * Retries are safe because the composer is cleared first, and a message QUEUED behind a
+     * running turn is never retyped - that is the one way to send it twice.
+     */
+    private deliverPrompt;
+    /**
+     * Press Enter to submit the composed prompt, and CONFIRM the turn actually started by
+     * watching for the USER LINE claude appends to <sid>.jsonl the instant it accepts a turn.
+     * During boot the TUI intermittently swallows the first Enter (a "what's new" notice /
+     * MCP-auth warning steals focus), so retry until it takes.
+     *
+     * The confirmation used to be `transcriptSize() > before`, which is any growth at all.
+     * That is not specific to the turn starting: claude writes `attachment`, `last-prompt`
+     * and other bookkeeping lines on its own schedule, so a swallowed Enter that happened to
+     * coincide with unrelated writes read as success. Observed in production 2026-08-01: a
+     * session logged 157 consecutive `attachment` lines and NOT ONE `user` line, yet
+     * submitTurn returned on the first attempt. The prompt stayed unsent in the TUI composer,
+     * paseo set turnInFlight and waited on a turn that had never begun, and the agent showed
+     * a spinner until the liveness backstop fired ten minutes later. The retry loop below was
+     * always right; the thing it was checking was not.
+     */
+    /**
+     * Type the prompt and confirm the terminal actually received it, retrying against a
+     * deaf terminal with backoff.
+     *
+     * Returns true once an echo (or a transcript user line) confirms the keystrokes landed;
+     * false only after the terminal stayed deaf for the whole {@link READY_BUSY_MAX_WAIT_MS}
+     * ceiling. Retyping cannot double-deliver: a deaf terminal demonstrably discards input
+     * (zero echo), and every iteration first checks whether a user line landed anyway.
+     */
+    private submitTurn;
+    /**
+     * True once a real `user` line has been appended past `offset`. Reads only the bytes
+     * added since then, so it stays cheap on a transcript that can reach tens of MB.
+     * `isMeta` user lines are claude's own bookkeeping and do not mean a turn started.
+     */
+    /**
+     * Fingerprint used to match a transcript record against what we typed. Whitespace is
+     * stripped on both sides because the terminal is free to re-wrap and re-space anything
+     * it renders, while the transcript keeps the text verbatim - so the character sequence
+     * is the part that survives every rendering.
+     */
+    private static fingerprint;
+    /**
+     * THE delivery authority: did claude append a user record matching what we sent?
+     *
+     * Content-matched on purpose. The old check accepted ANY user record past the watermark,
+     * which cannot tell "my message became a turn" apart from an unrelated record (a resume
+     * dialog answering itself, a queued earlier message). Matching the text answers the only
+     * question that matters, and answers it identically whether the terminal echoed the
+     * characters, collapsed them into a paste chip, or drew nothing at all.
+     */
+    private receiptSince;
+    /** Text of every non-meta user record written past `offset`. */
+    private readUserRecordsSince;
+    private transcriptSize;
+    private onTranscriptMessage;
+    /**
+     * Track interactive TUI dialogs (AskUserQuestion / plan-mode approval) from the
+     * transcript. While one is pending the terminal is WAITING, not stalled: the stall
+     * backstop must stand down, no ESC may be sent (it declines the dialog - the source of
+     * every phantom "User declined" this week), and an incoming reply is translated to
+     * dialog keystrokes instead of typed text.
+     */
+    private trackInteractiveDialog;
+    private scheduleTurnEndCheck;
+    private maybeCompleteTurn;
+    /**
+     * (Re)arm the liveness backstop. Called when a turn starts and on every transcript
+     * message, so the deadline only expires after an unbroken window of silence.
+     */
+    private armStallTimer;
+    private clearStallTimer;
+    /**
+     * No transcript activity for the whole budget while a turn was outstanding. Surface it as
+     * a failed turn instead of leaving the caller on an endless spinner. We do NOT kill the
+     * PTY: claude may still be retrying, and if it recovers its messages keep flowing through
+     * the reader as a fresh turn.
+     */
+    private onTurnStalled;
+    /**
+     * Append terminal output to the rolling tail.
+     *
+     * Scrubbed and filtered on the way IN, not on the way out, because the TUI's spinner
+     * redraws at a few hundred bytes/second: a raw buffer holds only a second or two of
+     * history and would evict the one line worth reading. Keeping only lines that carry
+     * letters or digits means a message like "Compacting conversation…" survives minutes of
+     * animation. Verified against a real stall: the raw tail was 163 chars of pure spinner.
+     */
+    /**
+     * True when the rolling tail's last frame looks like an input box waiting for typing.
+     *
+     * Deliberately requires the busy marker to be ABSENT rather than trusting the prompt
+     * markers alone: the working footer renders as `… · esc to interrupt · ← for agents`, so
+     * "for agents" on its own is present in both states and would read a mid-turn terminal
+     * as idle.
+     */
+    /** Runs `fn` after every previously queued terminal write has finished. */
+    private runExclusive;
+    /**
+     * Type a control slash command (`/model`, `/effort`) into the terminal, but only once the
+     * TUI is actually accepting input, and never while another write is in flight.
+     *
+     * Why this exists instead of `transport.write()` straight from the agent: a control command
+     * written to the transport bypasses the input loop, so it races the prompt being delivered
+     * and the two COLLIDE on the same input line. Captured live 2026-08-29 (session c132c833)
+     * from claude's own transcript:
+     *
+     *     command-args>claude-opus-5[1m]Responda APENAS: R1<
+     *
+     * The model id and the user's prompt, concatenated with no separator. Measured
+     * consequences: the model never changed (the old one kept answering two minutes later),
+     * the user's prompt was swallowed by the slash command, and the agent never returned to
+     * idle. Waiting for the input box also keeps the command out of claude's PERSISTED input
+     * queue, so it cannot be replayed into a future session.
+     *
+     * Returns false when the terminal never became typeable, so the caller can refuse to
+     * record a setting change that did not happen.
+     */
+    sendControlCommand(command: string): Promise<boolean>;
+    private looksIdle;
+    private appendTerminalTail;
+    /** Open `$PASEO_HOME/pty-recordings/<sessionId>.log`. Best-effort: never fail a session. */
+    private openRecording;
+    private recordLine;
+    private safeSize;
+    /**
+     * While a turn is outstanding, emit one line every {@link LIVENESS_HEARTBEAT_MS} with
+     * enough state to tell the failure modes apart without waiting for the stall budget:
+     * terminal bytes since the last beat (0 means the TUI is frozen, not thinking), seconds
+     * since the transcript last grew, and the last meaningful line on screen.
+     */
+    private startHeartbeat;
+    private stopHeartbeat;
+    private beat;
+    /**
+     * The tail as readable text: ANSI/OSC sequences dropped and runs of whitespace collapsed,
+     * because a raw TUI capture is mostly cursor movement and redraw padding.
+     */
+    private readTerminalTail;
+    private buildResult;
+    /**
+     * The agent process exited. Fail any in-flight turn immediately and end the query.
+     *
+     * Unlike a stall there is nothing to wait for: no retry, no recovery, no later transcript
+     * activity. Emitting here rather than letting the stall timer fire turns a ten-minute wait
+     * plus a false "still running" into an immediate, accurate failure, and finishing the query
+     * stops the layer above treating this transport as a live destination for prompts.
+     */
+    private onTransportExit;
+    /**
+     * A non-success `result` for an agent that exited.
+     *
+     * Wording constraints match {@link buildStalledResult}: `isAbortError()` drops results
+     * matching /\baborted\b/i and `buildTurnFailedEvent()` scrapes /\bcode\s+(\d+)\b/i for an
+     * exit code, so this says "status", never "code", and never says "aborted". It also must
+     * NOT claim the session is still running, which is the exact lie this change deletes.
+     */
+    private buildExitedResult;
+    private buildStalledResult;
+    interrupt(): Promise<void>;
+    setPermissionMode(): Promise<void>;
+    setModel(): Promise<void>;
+    setMaxThinkingTokens(): Promise<void>;
+    applyFlagSettings(): Promise<void>;
+    supportedModels(): Promise<ModelInfo[]>;
+    supportedCommands(): Promise<unknown[]>;
+    supportedAgents(): Promise<unknown[]>;
+    mcpServerStatus(): Promise<unknown[]>;
+    close(): void;
+}
+//# sourceMappingURL=pty-query.d.ts.map