@gigaflow/gmux 0.15.0

package/dist/services/ask-transcript.d.ts

@@ -0,0 +1,256 @@
+/**
+ * The ask thread, on disk.
+ *
+ * `gmux ask`'s REPL keeps its turns in a closure and replays them, because the
+ * providers we call are one-shot. The picker's chat cannot: every question is
+ * answered by a fresh detached worker that exits when it is done, so there is no
+ * closure left to hold anything. **The transcript file IS the turn array**, and
+ * `foldCompletedTurns` is what turns it back into one — `buildAskPrompt` never
+ * learns the difference.
+ *
+ * An append-only JSONL *event* log, not a document, and three things force that:
+ *
+ * 1. **A question must land before its answer exists.** The echo of what you
+ *    typed appears the instant you press enter, ~9–20s before there is an answer
+ *    to pair it with. A turn record cannot be written until both halves exist.
+ * 2. **Two writers.** `__ask-send` appends `meta`/`question`, the worker appends
+ *    `chunk`/`end`. `O_APPEND` makes the offset update atomic, so ordering holds
+ *    for whole records — and for nothing else.
+ * 3. **The reader is unsynchronized.** The preview re-runs on every cursor move
+ *    and takes no lock, so it must be able to parse a file that is being
+ *    appended to right now.
+ *
+ * Which is why **gmux must never truncate-and-rewrite a transcript**: a reader
+ * would catch the file mid-rewrite and the pane would flash empty, or show the
+ * previous answer. Appends are whole-line and ordered, so the only line a reader
+ * can ever see torn is the last one — `parseTranscript` drops it and the next
+ * refresh gets it. A dropped tail costs one repaint; a lock on the read path
+ * would cost the whole format.
+ */
+import { type SpawnOptions } from "node:child_process";
+import type { AskEvent, AskTurn } from "../core/types.js";
+import { type AutoSummarizeLock } from "./auto-summarize.js";
+/**
+ * How many prior turns a worker replays into the prompt.
+ *
+ * Every turn re-sends every earlier answer, so tokens grow quadratically and the
+ * 300s timeout starts to bite exactly when the thread gets useful. A bare slice
+ * of the most recent turns is the bound.
+ *
+ * Bounded at the fold, deliberately: `buildAskPrompt` is shared with bare
+ * `gmux ask`, which this design does not change.
+ */
+export declare const ASK_MAX_REPLAY_TURNS = 8;
+/**
+ * The in-flight heartbeat. The only timer in the design.
+ *
+ * The provider buffers — a 40-line request came back as one 111-byte write at
+ * +3.32s — so nothing else fires for the whole think, and a pane that is silent
+ * and static for 20s is indistinguishable from a wedged one. This is what makes
+ * `thinking… 14s` tick. It exists only while a request is in flight; that is the
+ * whole of the exception to "no idle polling".
+ */
+export declare const ASK_HEARTBEAT_MS = 1000;
+/**
+ * Trailing-edge throttle on chunk-driven refreshes.
+ *
+ * Against `claude -p` this fires once, with the answer. It is throttled anyway
+ * because `onChunk` is a tee: a provider that trickles would otherwise spawn one
+ * preview process per chunk. fzf does not save us — measured on 0.74, 100
+ * back-to-back `refresh-preview` POSTs ran a fast preview command 100 times. It
+ * bounds concurrency, not spawn rate.
+ */
+export declare const REFRESH_INTERVAL_MS = 150;
+/** How long a cancelled worker's group gets to die politely before SIGKILL. */
+export declare const ASK_KILL_GRACE_MS = 250;
+/**
+ * A parsed transcript. `torn` is true when the final line failed to parse —
+ * normal, not an error: the writer is appending as we read.
+ */
+export interface AskTranscript {
+    events: AskEvent[];
+    torn: boolean;
+}
+/** Same shape and same staleness predicate as the auto-summarize lock. */
+export type AskLock = AutoSummarizeLock;
+/** `<pid>-<rand8>`: the pid reaps, the random half keeps two pickers apart. */
+export declare function newAskRunId(pid?: number): string;
+/** The transcript for a fresh run. Allocates a path and creates nothing. */
+export declare function newAskTranscriptPath(): string;
+/** The run id a transcript path carries. Derived, so it is never stored twice. */
+export declare function askRunIdOf(transcript: string): string;
+/**
+ * Open a transcript for appending, creating it and its directory if needed.
+ *
+ * The fd is the caller's to close, and it is held for the life of the turn:
+ * `openSync`/`writeSync` rather than a stream because `createWriteStream` can
+ * defer its flush past the refresh POST, and with one paint per answer that is
+ * not a frame of lag — it is the whole answer missing until something else
+ * happens to repaint. **The bytes are on disk before the POST goes out.**
+ */
+export declare function openAskTranscript(transcript: string): number;
+/** One record, one whole-line append. Synchronous — see `openAskTranscript`. */
+export declare function appendAskEvent(fd: number, event: AskEvent): void;
+/**
+ * Parse a transcript's text.
+ *
+ * Takes no lock and cannot fail. A half-written last line is the normal case,
+ * not the error case — the reader is a preview re-running on a keystroke while
+ * a worker appends a multi-KB answer. Whole-line appends mean only the last line
+ * can ever be torn, so everything before it is still true.
+ */
+export declare function parseTranscript(text: string): AskTranscript;
+/**
+ * Read a transcript. A missing file is the empty state, not an error — it is
+ * how "no conversation yet" costs no flag and no branch.
+ */
+export declare function readAskTranscript(transcript: string): Promise<AskTranscript>;
+/** The seq the next question takes. Questions are the only thing that allocates one. */
+export declare function nextSeq(events: readonly AskEvent[]): number;
+/**
+ * The turn being answered right now, if any — a question with no `end`,
+ * `aborted` or `error` against it. What `__ask-cancel` aborts, and what the pane
+ * renders as `thinking… Ns`.
+ */
+export declare function inFlightSeq(events: readonly AskEvent[]): number | null;
+/**
+ * The conversation so far, as `buildAskPrompt` wants it.
+ *
+ * Two rules carry the weight:
+ *
+ * - **Keyed by `seq`, never file order.** Chunks are contiguous in practice
+ *   because the lock guarantees one writer, but folding by position would make
+ *   this function's correctness depend on a lock in another module.
+ * - **A turn enters history only with an `end` record.** In-flight, aborted and
+ *   errored turns are excluded, so an aborted question is dropped from the
+ *   model's view entirely (the human still sees it in the pane). A half-written
+ *   answer promoted to history is shown to the model as its own completed
+ *   statement of fact, and it will build on a sentence that stops mid-clause.
+ *   "The answer so far" and "the conversation so far" are different things.
+ */
+export declare function foldCompletedTurns(events: readonly AskEvent[], options?: {
+    maxTurns?: number;
+}): AskTurn[];
+/**
+ * `transform` returns immediately, so nothing stops you pressing enter twice.
+ *
+ * Two workers interleaving chunks of different seqs is the one thing that makes
+ * the fold ambiguous. With the lock the second enter appends nothing and
+ * refreshes a pane that already says "still answering". A key that visibly does
+ * nothing for a stated reason is fine; a key that silently corrupts the thread
+ * is not.
+ */
+export declare function askLockPath(transcript: string): string;
+/**
+ * Where ctrl-o parks the browse query while ask mode owns fzf's query line.
+ *
+ * A sibling of the transcript rather than a state directory: it inherits the
+ * `<pid>-<rand8>` uniqueness for free, so two concurrent pickers cannot collide,
+ * and it falls into the cleanup and sweep paths that already exist with no new
+ * concept to name.
+ *
+ * The picker spells this suffix a second time, because it may not import a
+ * service and the path is baked into a shell binding. A drift between the two is
+ * SILENT — esc restores an empty query and the browse filter is gone — so
+ * tests/picker.test.ts pins them equal.
+ */
+export declare function askBrowseQueryPath(transcript: string): string;
+export declare function readAskLock(transcript: string): Promise<AskLock | null>;
+/**
+ * Take the turn lock, or report that a turn is already in flight.
+ *
+ * `pid: 0` until the worker exists — the same acquired-but-not-yet-spawned shape
+ * `auto-summarize` uses, and the reason `isLockStale` ANDs liveness with age
+ * rather than trusting a pid on its own. That AND is also the pid-reuse guard:
+ * a recycled pid can only look alive, never young.
+ */
+export declare function acquireAskLock(transcript: string, now?: Date): Promise<boolean>;
+/** Record the worker that now owns the turn. `__ask-cancel` kills this pid's group. */
+export declare function writeAskLockPid(transcript: string, pid: number, now?: Date): Promise<void>;
+export declare function releaseAskLock(transcript: string): Promise<void>;
+/**
+ * Reap the files left behind by pickers that died without cleaning up.
+ *
+ * Normal exit is `pick.ts`'s `onClose`; this is the `kill -9` path. **A run
+ * whose owning pid is alive is never removed** — that is another picker's live
+ * thread, and deleting it would empty a pane someone is reading.
+ *
+ * The spec also says "or the mtime is older than LOCK_STALE_MS", on the grounds
+ * that a live worker's file cannot be 10 minutes idle. That reasoning does not
+ * survive the filename: the pid is the *picker's*, not the worker's, and a
+ * picker left open for an hour after one question is entirely ordinary. So age
+ * alone reaps only a run we cannot attribute to a pid at all.
+ *
+ * Never throws, and never able to fail the picker: an orphan is a few KB of
+ * disposable cache, so the cost of not reaping is nil and the cost of a sweep
+ * that throws is a picker that will not open.
+ */
+export declare function sweepAskTranscripts(now?: Date, staleMs?: number): Promise<string[]>;
+/**
+ * How `__ask-send` forks the worker. Pure, so the decision is testable without
+ * spawning anything — the same seam `maybeAutoSummarize`'s `spawnWorker` has.
+ *
+ * `detached` is not a nicety twice over: it lets the sender exit at once, and it
+ * makes the worker a process-group leader, which is the only thing that lets
+ * `__ask-cancel` reap the provider underneath it. `spawn` does not kill its
+ * child on POSIX, so a worker that merely exits leaves `claude -p` running and
+ * billing. (`setsid` does not exist on macOS — gmux's own platform — so Node's
+ * `detached: true` is the portable equivalent; it calls `setsid(2)`.)
+ *
+ * `childEnv()`, not `process.env`: the worker is a `gmux` that is about to make a
+ * model call, which is the definition of a child — its provider may shell back
+ * into `gmux grep`, and that nested `gmux` must not start a summarize pass. The fzf
+ * api key rides here by inheritance and nowhere else; it must never reach an
+ * argv, where `ps` would hand it to any user on the box.
+ */
+export declare function askChildSpawnOptions(env?: NodeJS.ProcessEnv): SpawnOptions;
+/**
+ * Re-enter this same CLI, detached, on a hidden command.
+ *
+ * `execArgv` is forwarded for the reason picker.ts already documents once: under
+ * `npm run dev` the entry is `src/cli/main.ts` and `execArgv` carries tsx's
+ * loader flags. Drop them and the command is `node src/cli/main.ts`, which Node
+ * 20 cannot run — so in development every answer silently never arrives, with
+ * `stdio: "ignore"` swallowing the evidence.
+ */
+export declare function spawnAskWorker(args: readonly string[]): number | undefined;
+/** Throttle state. `lastAt` is null before the first refresh; `final` bypasses the interval. */
+export interface RefreshState {
+    lastAt: number | null;
+    pending: boolean;
+    final: boolean;
+}
+/** The throttle policy, as a function of state, so it is testable without a socket. */
+export declare function shouldRefresh(state: RefreshState, now: number): boolean;
+export interface StreamAnswerOptions {
+    /** The provider's argv. The fake-binary seam: tests pass a `node -e` here. */
+    argv: readonly string[];
+    prompt: string;
+    /** Open for append, owned by the caller, closed by the caller. */
+    transcriptFd: number;
+    seq: number;
+    /** Injected, so the write-then-notify order is testable without a port. */
+    notify: () => void;
+    signal: AbortSignal;
+    timeoutMs?: number;
+}
+/**
+ * Run one turn: call the provider, append what it says, tell fzf to repaint.
+ *
+ * **Write, then notify.** Notify-then-write renders the previous chunk, forever
+ * one behind — and with a provider that buffers, "one behind" means an empty
+ * pane until something else repaints it.
+ *
+ * **No `env` is passed to `runProviderCommand`, and that is load-bearing.** It
+ * defaults to `childEnv()`, which is what stops the provider's `gmux grep` from
+ * starting a summarize pass. A well-meant `env: { ...process.env, FZF_PORT }`
+ * here would silently drop `GMUX_CHILD` and reopen the loop — which is why
+ * the port travels on the worker's argv instead, where the trap cannot be set.
+ *
+ * **The canceller owns the `aborted` record, not us.** On abort we write nothing
+ * and return: a wedged worker must not be able to leave the pane stuck on
+ * "answering", and only the process that knows the kill happened can be sure.
+ */
+export declare function streamAnswer(options: StreamAnswerOptions): Promise<void>;
+/** Close a transcript fd. Always from a `finally` — the fd lives for the turn. */
+export declare function closeAskTranscript(fd: number): void;