/** * Reading an agent's reply out of the chat ledger (Issue #2376 / #2386 / #3039) * * `ask` used to read the reply after its own turn here (until Issue #4344, * which reads it by the ask's id instead and keeps only the overlap check's * reads here); `reply` (Issue #3039) reads the * latest reply of a turn somebody else sent — a worker told to "stop and * report" by a supervisor nudge. Both mean the same thing by "the reply", so * the rules live here once rather than in two commands that can drift: * * - only assistant rows in `GET /api/worktrees/:id/messages` are candidates, * prompt rows excluded; * - CommandMate's own furniture (`relay-sys:` / `model-changed:`) is never an * answer; * - a row a transcript reader wrote (`-turn:`) wins over a scrape; * - ANSI escapes and control bytes are dropped before the text is returned. * * What differs between the two callers — how long to hold out for a turn row, * and whether an unmarked row may stand in for one — stays with the caller. */ import type { PromptMessageResponse } from '../types/api-responses'; import { type ApiClient } from './api-client'; /** * Chat rows read back per request. * * Bounded because only the tail matters and an unbounded read of a long-running * worktree's history is a large response for one line of answer. Generous * enough that a turn which wrote several assistant rows (a tool-use narration * followed by the summary) still has its last one inside the window. */ export declare const REPLY_LOOKBACK_MESSAGES = 30; /** * Tools whose reply CommandMate reads out of a transcript rather than a screen. * * For these six the ledger is authoritative and a row with no turn marker is * by definition not the answer. For every other tool (copilot / gemini / * vibe-local) the scraper's row is the only record there will ever be. * * Mirrors the six readers that live under `src/lib/hooks/sources/`. */ export declare const TRANSCRIPT_READER_TOOLS: ReadonlySet; /** * A reply body fit to print, or `''` if nothing survived. * * Issue #2386 asked for this as a belt to the braces: the row the junk came * from held RAW ANSI, and a caller that pipes a reply into a report or a commit * message should never have to strip escape codes out of an agent's sentence. * * @param raw - Reply text as it arrived */ export declare function sanitizeReply(raw: string): string; /** * {@link sanitizeReply} without the trim (Issue #4344): `ask` prints the reply * its ledger matched as the whole body, so only escapes and control bytes go. */ export declare function stripReplyControls(raw: string): string; /** One assistant row that could be the reply. */ export interface ReplyCandidate { /** Sanitized body. Never empty — an empty one is not a candidate. */ content: string; /** Whether a transcript reader wrote it (see {@link isTurnRow}). */ fromTranscript: boolean; /** The row's `request_id`, or null when the producer had none. */ requestId: string | null; /** The row's own timestamp, as the messages route serialized it. */ at: string; } /** * The rows that could be a reply written at or after `since`, oldest first. * * @param messages - Rows as the messages route serialized them * @param since - Epoch ms; rows stamped earlier are not candidates */ export declare function replyCandidates(messages: PromptMessageResponse[], since: number): ReplyCandidate[]; /** * The newest reply among `candidates`, or null. * * Newest first among the rows a reader wrote: a turn that emitted several * assistant rows (a narration then the summary) still ends on its summary. * When `turnRowsOnly` is false and no reader wrote anything, the newest row of * any kind is taken — the only record a tool without a transcript has. * * @param candidates - Output of {@link replyCandidates} * @param turnRowsOnly - Whether an unmarked (scraped) row may stand in */ export declare function pickLatestReply(candidates: ReplyCandidate[], turnRowsOnly: boolean): ReplyCandidate | null; /** * Whether another message reached this instance inside `[since, until]` * (Issue #3955). * * codex folds a message typed while a turn is running into that same turn and * answers both with one reply, so an `ask` whose turn also carried somebody * else's message cannot know which of the two the reply answers. The ledger * shows it: `/send` writes a `user` row for every message the instant it is * handed to the pane, so a `user` row in this instance's window whose text is * not this `ask`'s own is a second sender's. * * Text, not id, tells the rows apart: the transcript reader claims the `/send` * row rather than writing a second one (`user-turn-recorder`), so this `ask`'s * own message is one row, or one plus a reader's copy with the same text. * * @param messages - Rows as the messages route serialized them * @param ownContent - The message this `ask` sent * @param since - Epoch ms taken before the send * A row on another instance is not this turn's: `instanceId` keeps a read that * was not scoped to one instance (no `--instance` / `--agent`) from counting a * message somebody sent to a different session. Without it every row counts, * which is right only for a read the server already scoped. * * @param until - Epoch ms at which the turn ended * @param instanceId - The instance this `ask`'s message went to */ export declare function hasForeignPromptInWindow(messages: PromptMessageResponse[], ownContent: string, since: number, until: number, instanceId?: string): boolean; /** * The one instance this `ask`'s own `user` row landed on, or null * (Issue #3955). * * An `ask` with no `--instance` / `--agent` leaves the choice to the server, * and `/send` does not say which it picked to this caller. The ledger does: the * row `/send` wrote carries it. Two rows with this text on different instances * (the same request sent to two sessions at once) say nothing certain, so that * is null too. * * @param messages - Rows as the messages route serialized them * @param ownContent - The message this `ask` sent * Bounded on both sides, like {@link hasForeignPromptInWindow}: the same text * sent to another instance after this turn ended is somebody else's later * request, and must not make this one's instance undecided. * * @param since - Epoch ms taken before the send * @param until - Epoch ms at which the turn ended (`ask` always passes it; * unbounded when omitted) */ export declare function ownPromptInstance(messages: PromptMessageResponse[], ownContent: string, since: number, until?: number): string | null; /** * User turns read back per page by {@link fetchPromptRowsSince}. * * The route's `unit=pairs` counts user rows, so a turn that wrote many * assistant rows cannot push a user row out of the page the way it can out of * {@link REPLY_LOOKBACK_MESSAGES} rows. */ export declare const PROMPT_ROWS_PAGE_TURNS = 20; /** * Whether a read of {@link REPLY_LOOKBACK_MESSAGES} rows may have cut off rows * stamped at or after `since` (Issue #3955): it came back full and its oldest * row is not older than `since`. */ export declare function mayHaveDroppedRowsSince(messages: PromptMessageResponse[], since: number): boolean; /** * Every `user` row stamped at or after `since`, however many rows came after * it (Issue #3955), or null if the rows cannot be read. * * Pages backwards with the route's existing `unit=pairs` and `before`: a page * holds the newest {@link PROMPT_ROWS_PAGE_TURNS} user rows and every row from * the oldest of them on, so the next page's `before` (that oldest timestamp) * leaves no user row between two pages. Stops at the first page that reaches * back past `since`, or that holds fewer user rows than asked for (nothing * older is left). * * @param client - API client * @param worktreeId - Worktree ID * @param instanceId - Instance to scope to, or undefined for every instance * @param since - Epoch ms taken before the send */ export declare function fetchPromptRowsSince(client: ApiClient, worktreeId: string, instanceId: string | undefined, since: number): Promise; /** * The recent chat rows for this instance. Throws what the API client throws. * * @param client - API client * @param worktreeId - Worktree ID * @param instanceId - Resolved instance ID, or undefined for every instance */ export declare function requestRecentMessages(client: ApiClient, worktreeId: string, instanceId: string | undefined): Promise; /** * {@link requestRecentMessages}, or null if the rows cannot be read. * * For a caller whose turn already completed: a daemon that cannot serve the * ledger is a reason to fall back, not a reason to lose the turn. */ export declare function fetchRecentMessages(client: ApiClient, worktreeId: string, instanceId: string | undefined): Promise; //# sourceMappingURL=reply-ledger.d.ts.map