/** * `ask`'s reply, by the ask's own id (Issue #4344, design * `docs/design/ask-attribution-4344.md` §0.2・§3.3・§3.6 cell 17・§4, PR3). * * Until #4344 `ask` printed "the newest reply after the send": a ledger row, or * the squeezed pane when the ledger had none. Twice that picked another turn's * answer (#4315's 5-2b). Now a synchronous `ask` names an id on the send, the * server stamps an envelope on the typed text, its transcript reader binds that * input to the completed turn that answered it, and this module reads the * answer back by that id (`GET /api/asks/:askId`). The reply is printed only * when the ledger says `matched`; anything else prints `reply: null` with the * state and the reason. The pane is never read for a reply (the human decision * of 2026-11-13: a tool or server that cannot attribute does not collect). * * - Which tools are attributed comes from the server (`GET /api/asks/capabilities`), * never a copy of the table here (§3.2). A server that predates the endpoint * (404) is `server_unsupported`: the send goes out with the old body. * - A tool in the table that is off for its version (older than the minimum, or * a version the server could not read) is still `tool_unsupported`, but the * outcome carries `toolVersion` from the table's `versions`, so the line says * that rather than "this tool has no ask attribution" (PR3 review). * - Running out of the reply grace with the row still `pending` is decided here * (`grace_expired` / `turn_incomplete` / `send_unknown`) and written nowhere: * the ledger is not made terminal by a client's patience (§3.6 cell 17, I12). */ import type { CLIToolId } from '../config/cli-tool-ids'; import type { AskAttributionReason, AskCapabilitiesBody, AskSendAnswer, AskToolVersion } from '../types/api-responses'; import { type ApiClient } from './api-client'; /** The envelope protocol this CLI speaks. Mirrors `ASK_PROTOCOL_VERSION` in `src/types/ask-correlation.ts`. */ export declare const ASK_PROTOCOL_VERSION = 1; /** `GET /api/asks/capabilities` (`src/app/api/asks/capabilities/route.ts`). */ export declare const ASK_CAPABILITIES_PATH = "/api/asks/capabilities"; /** What the CLI's final answer can say (`pending` never is one: §3.3). */ export type AskOutcomeState = 'matched' | 'ambiguous' | 'unmatched' | 'unavailable'; /** What `ask` prints about the reply (`--json`'s `askId` / `attribution` / `reply`). */ export interface AskOutcome { /** The id the send carried, or null when none was (unavailable). */ askId: string | null; state: AskOutcomeState; reason: AskAttributionReason | null; /** The answering turn also absorbed a background-task notice (§7 (a) ②). */ notified: boolean; /** The reply body, only when `state === 'matched'`. */ reply: string | null; /** * `tool_unsupported` only: the tool IS in the server's table but is off for * its version (`--json`'s `attribution.toolVersion`; absent otherwise). */ toolVersion?: AskToolVersionNote; } /** Why an attributed tool is off for its version: older than `minimum`, or its version could not be read. */ export interface AskToolVersionNote { state: 'too_old' | 'unreadable'; minimum: string; installed: string | null; } /** How `ask` treats the send, decided before it. */ export type AskSendPlan = /** * The server attributes (or, with no tool known, may attribute) this ask: the * send names `askId`. `versions` reads a refusal of the send (the default tool * off for its version) the way the table would have. */ { kind: 'ask'; askId: string; versions: Record; } /** Not attributed: the send goes out as it did before #4344, and the reply is not collected. */ | { kind: 'unavailable'; outcome: AskOutcome; }; /** An unavailable outcome (§0.2). */ export declare function unavailableOutcome(reason: AskAttributionReason): AskOutcome; /** * The version note of a tool the table names with a reading that is not `ok`, * or undefined (a tool off the table, a server that sends no `versions`). */ export declare function toolVersionNote(versions: Record | undefined, cliToolId: string | undefined): AskToolVersionNote | undefined; /** * The server's attribution table, or null for a server that predates it (a * 404). Any other failure is the command's: the send goes to the same server, * so it is not quietly turned into a send without the ledger (§0.2). * * @throws ApiError on anything but a 404 or a well-formed answer (a deadline stays 124) */ export declare function readAskCapabilities(client: ApiClient): Promise; /** * Decide the send (§0.2): a server without the table, or a protocol this CLI * does not speak, is `server_unsupported`; a known tool the table does not mark * true is `tool_unsupported`. Otherwise the send names a fresh id — with no tool * resolved (the worktree's default) the server decides, and its answer says. * * @param cliToolId - The resolved tool, when the CLI knows it */ export declare function planAskSend(client: ApiClient, cliToolId: string | undefined): Promise; /** * What the send's answer says about the ask. `unavailable` (a command body, a * tool the server turned down) is final; an answer with no `ask` at all means * the server did not read the field. Null: the ledger is to be read after the * turn. * * @param toolVersion - The table's version note for the tool the send reached * (the send answer names no version; a `tool_unsupported` is read with it) */ export declare function outcomeFromSendAnswer(answer: AskSendAnswer | undefined, toolVersion?: AskToolVersionNote): AskOutcome | null; /** * Read `askId`'s attribution until it settles or `graceMs` runs out (§4 * `readAskAttribution`). Each read is bounded by the grace (the turn already * ended inside `--timeout`, so running out is not 124). A `pending` read makes * the server run the tool's reader once (§3.5), so this settles with no poller. * * @throws ApiError for a failure other than the grace's deadline */ export declare function readAskOutcome(client: ApiClient, askId: string, options: { graceMs: number; pollMs: number; sleep: (ms: number) => Promise; }): Promise; /** * Per tool: whether `commandmate reply` can return its reply (PR3 review r1). * `reply` takes only rows a transcript reader wrote (`-turn:` request * ids, `reply-ledger.ts` `replyCandidates`/`pickLatestReply(…, true)`); these * are the tools whose readers write them (the same split as * `src/lib/relay/relay-bound-reply.ts` `TRANSCRIPT_READER_TOOLS`, opencode-v2's * `oc-turn:` included). For the others `reply` is always empty, so the line * does not recommend it. The guide's table (ja・en, "send, wait, read the * ledger") names the same tools — held equal by * `tests/unit/cli/commands/ask-reply-guidance-4344.test.ts`. A record, so a new * tool id fails `tsc` here. */ export declare const REPLY_COMMAND_TOOLS: Readonly>; /** * The one stderr line for an ask whose reply is not printed (§0.2), with where * to look instead. The reply may still exist — it is not this command's to * pick off the screen. For a tool the server cannot attribute, the line also * names the commands that still bring its reply back (PR3 review): a relay * (`ask --async`), and `reply --since ` after the turn — only for a * tool `reply` can answer for ({@link REPLY_COMMAND_TOOLS}) and only with the * send time, since a `reply` without `--since` may return the previous turn's * answer (the mix-up #4344 prevents). * * @param target.sentAt - ISO time of this ask's send; without it `reply` is not recommended */ export declare function formatReplyNotCollected(outcome: AskOutcome, target: { worktreeId: string; instanceId?: string; cliToolId?: string; sentAt?: string; }): string; /** The note for a matched reply whose turn also took a background-task notice (§7 (a) ②). */ export declare const NOTIFIED_NOTE = "Note: the answering turn also took a background-task notification; the reply may react to it as well."; //# sourceMappingURL=ask-reply.d.ts.map