dsh-diff-approval 0.29.1 → 0.31.0

package/lib/types/client/slots.d.ts

@@ -2,16 +2,51 @@
 import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 import type { DockSnapshot } from './dock.tsx';
-import type { ChatView } from './chat-bridge.ts';
-import type { DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalOpenAction, DiffApprovalRefreshValue, PendingFileDiff, VcsImportValue } from '../types.ts';
+import type { CommentDraft } from './port.ts';
+import type { CommentLineRange } from '../comment-lines.ts';
+import type { CommentRecord, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, DiffApprovalOpenAction, DiffApprovalRefreshValue, DiffApprovalUpdateValue, PendingFileDiff, VcsImportValue } from '../types.ts';
 /** What the panel reads and drives: the pending list plus in-flight entries. */
 export interface PendingDiffSnapshot {
     /** Whether a list read has completed at least once. */
     read: boolean;
     /** Pending entries, one per file, oldest capture first. */
     files: PendingFileDiff[];
+    /**
+     * The session's comment threads, oldest first. They arrive on the same read as the
+     * entries, from the host — the one copy every client of this session shares, so two
+     * browsers show the same threads instead of two private ones.
+     */
+    comments: CommentRecord[];
+    /**
+     * The new-file lines each comment sits on NOW, keyed by comment id, as the HOST resolved them
+     * against the entry's current content (see the wire type). One map for the whole panel: the list
+     * pane's label, the card's own chip and the jump all draw it, so a comment cannot read one line in
+     * the list and another in the code view — and a file nobody has opened is named just as rightly,
+     * which is what the reader asked for. A comment the host could not place is absent, and its
+     * callers fall back to `record.anchor`.
+     */
+    commentLines: Readonly<Record<string, CommentLineRange>>;
+    /** The host's comment revision counter, bumped on every comment change. */
+    commentsRevision: number;
+    /** Derived answer text per comment id, read by the host from the session's transcript. */
+    commentAnswers: Record<string, string>;
     /** A read failure's message; absent while the latest read succeeded. */
     error?: string;
+    /**
+     * How many rows the host says this session has, from the LIGHT read (`list-count`) — the badge's
+     * question, answered without shipping any file content.
+     *
+     * It is the number a full read would have carried, but it is a separate fact with a separate age: a
+     * count lands on ticks that ask only for a count (when nothing is showing), and a FULL read clears it,
+     * because that read carries the same fact in `files` and is newer. So a reader's rule is
+     * `count ?? files.length` — the fallback covers both "no count has arrived" and "the list is fresher",
+     * and a count that FAILED leaves the previous number in place rather than showing zero.
+     *
+     * Absent on a host that predates the endpoint: there the store keeps doing full reads, the value stays
+     * absent, and every reader stays on the fallback — today's behaviour, at today's cost (see
+     * `PendingDiffStore.refreshCount`).
+     */
+    count?: number | undefined;
     /** Entry ids whose keep/revert is in flight; their controls are disabled. */
     busy: ReadonlySet<string>;
     /** Entry ids whose last keep/revert failed, mapped to the error message; the panel surfaces these inline (row tag + detail banner) instead of hiding the list. */
@@ -30,13 +65,100 @@ export interface PendingDiffSnapshot {
      * told finds the list gone later with nothing to explain it (see the wire type).
      */
     persistError?: string | undefined;
+    /**
+     * The last failure to write the session's COMMENT files, or absent while those writes are
+     * working. Their own field (and their own copy) because they are their own files: a comment
+     * that only exists in the host's memory is erased by a restart exactly like an unpersisted
+     * list, and the panel says so once — the same way, and for the same reason, as `persistError`.
+     */
+    commentPersistError?: string | undefined;
+    /**
+     * Why the last undo/redo was refused by the host, or absent when there is nothing to say.
+     * The host answers a refused undo with its reason (the divergence guard's "the file changed
+     * outside the review"), and the reader who pressed the key has to be told: the panel surfaces
+     * this once as a toast and clears it, so the next refusal is news again.
+     */
+    undoNotice?: string | undefined;
     /** Latched when an external change created a fresh undo checkpoint that
      * superseded the redo history; the panel surfaces it once (deferred if the
      * panel is closed) via a bottom-right notice. */
     redoCleared?: boolean;
 }
+/** One filter over one session's view of the pending list; the shape every view hook takes. */
+export type PendingViewSelector<T> = (view: PendingDiffSnapshot) => T;
+/**
+ * The number a badge, a header entry or a dock chip shows for one session: the light count when one has
+ * arrived, else the length of the list that read carried.
+ *
+ * The fallback is not a nicety — it is the whole older-host story and the state before the first count
+ * lands. `count` is absent when no count has arrived (the page just loaded, or the host predates the
+ * endpoint, where the store keeps doing full reads) and it is cleared by every full read, whose `files`
+ * are the same fact and newer. So `count` is only ever shown while it is the FRESHEST number the client
+ * has; otherwise the list speaks. See `PendingDiffSnapshot.count`.
+ * @param view - one session's view.
+ * @returns how many rows it holds.
+ */
+export declare function countOf(view: PendingDiffSnapshot): number;
+/**
+ * The view a seat draws when it has NO reviewable session: a session that is absent, or one the shell has
+ * told us is blank — a brand-new session with nothing said in it yet.
+ *
+ * This exists because the page-wide fallback is the wrong answer for such a seat. `viewFor(undefined)`
+ * and `getSnapshot()` deliberately answer the newest session read on the page (the whole-page contract the
+ * remap follows), and with the store's slots keyed only by session id and no workspace comparison anywhere
+ * in this client, "the newest read" can be another session's list — even another workspace's. A seat that
+ * has nothing of its own to show must draw NOTHING, and this is the nothing: no rows (so `countOf` is 0),
+ * no comments, no workspace, and `read: false` because nothing has been read FOR this seat.
+ *
+ * Shared rather than re-spelled per seat: the panel's badge and body, the header entry's count and the
+ * dock chip all have to agree that "no reviewable session" means zero, and a second literal here is how
+ * they would drift. Frozen because it is handed to readers as a snapshot: nothing may write through it.
+ */
+export declare const EMPTY_PENDING_VIEW: PendingDiffSnapshot;
+/**
+ * The view a seat DRAWS when there is nothing to review: the same emptiness as {@link EMPTY_PENDING_VIEW},
+ * but READ.
+ *
+ * The difference is what the panel draws: an unread view is a session whose list is still coming, so it
+ * shows the loading state, while this one says "no pending changes" — the truth for a session that is
+ * absent or blank. Using the unread view here would leave a docked panel spinning forever behind an entry
+ * that is disabled and can never be opened.
+ */
+export declare const NOTHING_TO_REVIEW_VIEW: PendingDiffSnapshot;
+/** Function shape of {@link PendingViewHooks.pendingView}; named so a seat can call it directly. */
+export type PendingViewReader = <T>(sessionId: SessionId | undefined, select: PendingViewSelector<T>) => T;
+/**
+ * How a seat reads pending state for the session it is actually about.
+ *
+ * The page runs several seats at once — the sidebar footer's badge, the Session header's entry, the
+ * docked tab's chip and body — and they can belong to different sessions. Reading the ONE page-wide
+ * snapshot is what let a badge show another session's count, so a seat that knows its session reads
+ * that session's own view through {@link PendingViewHooks.pendingView} and nothing else.
+ *
+ * This lives BESIDE the face's `hooks`, not inside it: that compartment is a map of observables
+ * (`HooksSources`), and the framework binds each one onto the component props as a `use<Name>` selector
+ * hook. Folding a non-observable in there would stop the whole compartment from matching, and the panel
+ * would lose `usePending` and `useDock` with it. `pendingView` is a read, not an observable: the panel's
+ * `usePending` subscription is what re-renders it.
+ *
+ * The hook is optional because the shapes are read structurally: a host (or a test) that offers only
+ * `pending` still renders, with the panel falling back to the page-wide snapshot.
+ */
+export interface PendingViewHooks {
+    /**
+     * Read one session's own view, with `select` applied inside the subscription.
+     *
+     * `sessionId === undefined` means "I have no session of my own": the answer is then the page-wide
+     * view (the newest session read), which is what a whole-page caller wants. A session that has never
+     * been read answers an unread empty view — never another session's list.
+     * @param sessionId - the session whose view to read.
+     * @param select - what to take out of that view.
+     * @returns the selected value.
+     */
+    pendingView?: PendingViewReader | undefined;
+}
 /** The injected face the panel component receives from the plugin body. */
-export interface PendingPanelFace {
+export interface PendingPanelFace extends PendingViewHooks {
     hooks: {
         /** Live pending-diff snapshot for the current page. */
         pending: HostObservable<PendingDiffSnapshot>;
@@ -57,8 +179,26 @@ export interface PendingPanelFace {
     /** Close the docked tab now, when one exists (the quick-summon chord's job
      *  while the panel lives in the sidebar). */
     closeDock?: (() => void) | undefined;
+    /**
+     * Ask the host whether a newer release of this plugin is published.
+     *
+     * Optional, and deliberately so: a seat that is not given one (an older shell wiring, or a
+     * harness that does not stage it) simply draws no update chip. The panel calls it ONCE, after
+     * mount, and never waits on it — a host that cannot answer, or has no answer to give, leaves the
+     * chip's site exactly as it was. The answer is drawn in ONE place (the open file's status bar, at
+     * the panel's bottom edge) out of one piece of panel state.
+     */
+    onCheckUpdate?: (() => Promise<DiffApprovalUpdateValue>) | undefined;
     /** Read the pending list for the current session into the snapshot. */
     onRefresh: (sessionId: SessionId | undefined) => void;
+    /**
+     * The badge's tick, for a seat with nothing on screen: ask how many rows the session has, with no file
+     * content on the wire. Optional so a face built against an older shape still renders — the panel then
+     * keeps the full read, which is what such a page did before the verb existed.
+     */
+    onRefreshCount?: ((sessionId: SessionId | undefined) => void) | undefined;
+    /** The reader is looking at this file now: its row's unseen dot goes out. */
+    onMarkSeen?: ((sessionId: SessionId | undefined, id: string) => void) | undefined;
     /** Keep one operation. `keepListed` leaves the resolved entry in the list. */
     onKeep: (sessionId: SessionId, id: string, keepListed?: boolean) => Promise<void>;
     /** Revert one operation (restore its prior content, or remove a created file).
@@ -75,15 +215,6 @@ export interface PendingPanelFace {
     onPreviewImage: (sessionId: SessionId, path: string) => Promise<string | undefined>;
     /** Paste a copied reference into the session's chat input and focus it. */
     onPasteReference: (sessionId: SessionId, reference: string) => void;
-    /**
-     * Send one prompt into the session as a real turn (the discussion's answer
-     * comes back through `watchChat`).
-     * @returns whether a send verb was available; false means the caller should
-     * fall back to the composer route.
-     */
-    onAskAgent: (sessionId: SessionId, text: string) => boolean;
-    /** Watch a session's transcript and turn state for a discussion's answer. */
-    watchChat: (sessionId: SessionId, listener: (view: ChatView) => void) => () => void;
     /** Undo the session's last keep/revert, then refresh the list; resolves to the affected entry id when it is still pending. */
     onUndo: (sessionId: SessionId) => Promise<string | undefined>;
     /** Redo the session's last undone keep/revert, then refresh the list; resolves to the affected entry id when it is still pending. */
@@ -101,8 +232,49 @@ export interface PendingPanelFace {
     onKeepAll: (sessionId: SessionId) => Promise<void>;
     /** Revert every pending entry of one session in a single host call (bulk). */
     onRevertAll: (sessionId: SessionId) => Promise<void>;
+    /**
+     * Keep a PICK of files in one host call. The pick is one decision the reader made, so it goes to the
+     * host as one request — one durable write, one read back, and one undo step — rather than a loop of
+     * per-file calls that undo would then peel apart.
+     */
+    onKeepMany: (sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined) => Promise<void>;
+    /**
+     * Revert a PICK of files in one host call; the same one request, one write, one undo step. Unlike a
+     * keep this writes over the files, and a file the agent created is DELETED with no undo — so the panel
+     * puts a confirmation in front of a pick whose revert would delete (see the pick's menu).
+     */
+    onRevertMany: (sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined) => Promise<void>;
+    /**
+     * Write one annotation down in the session's comment store. The host owns the
+     * record from here on, so the next read is what shows it (and every other client
+     * of this session sees it too).
+     */
+    onCommentAdd: (sessionId: SessionId, comment: CommentDraft) => Promise<DiffApprovalCommentAddValue>;
+    /** Drop one annotation from the session's comment store. */
+    onCommentRemove: (sessionId: SessionId, id: string) => Promise<DiffApprovalCommentRemoveValue>;
+    /**
+     * Drop several annotations in one host call. Ending a pick of comments is one action the reader
+     * asked for, so it goes to the host as one request and comes back as one read — see
+     * `PendingDiffStore.commentRemoveMany`.
+     */
+    onCommentRemoveMany: (sessionId: SessionId, ids: readonly string[]) => Promise<DiffApprovalCommentRemoveManyValue>;
+    /**
+     * Ask one stored comment as its own turn of the session; the answer arrives on the
+     * next read, derived by the host from the transcript. `prompt` is what the agent is
+     * asked and `text` is the reader's own words inside it, which the host stores on the
+     * question so the thread can draw what was written.
+     */
+    onCommentAsk: (sessionId: SessionId, id: string, prompt: string, text: string) => Promise<DiffApprovalCommentAskValue>;
+    /**
+     * The reader has this comment's card in view: its unseen dot goes out, and the answers on it become
+     * the baseline a later rewrite is measured against. A reader action, so it is its own call rather
+     * than something a read does — a read that cleared attention would make the dot impossible to see.
+     */
+    onCommentSeen?: ((sessionId: SessionId, id: string) => void) | undefined;
     /** Acknowledge the redo-cleared notice so it is only surfaced once. */
     onAckRedoCleared: () => void;
+    /** Acknowledge a refused-undo notice once the panel has said it (see `undoNotice`). */
+    onAckUndoNotice: () => void;
     /** Collapse the DSH sidebar (no-op when already collapsed) before the floating
      *  modal opens on a narrow window, so the sidebar can't overlap it. */
     collapseSidebar: () => void;

package/lib/types/client/store.d.ts

@@ -7,13 +7,56 @@
  */
 import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
-import type { DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalOpenAction, DiffApprovalRefreshValue, VcsImportValue } from '../types.ts';
+import type { DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, DiffApprovalOpenAction, DiffApprovalRefreshValue, VcsImportValue } from '../types.ts';
 import type { PendingDiffSnapshot } from './slots.ts';
-import type { DiffApprovalPort } from './port.ts';
+import type { CommentDraft, DiffApprovalPort } from './port.ts';
 /** The observable the panel reads and the plugin body drives. */
 export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
+    /**
+     * One session's own view of the pending list.
+     *
+     * The page runs several mounts of the panel at once — the footer entry, the Session header entry and
+     * the docked tab — and they can be about DIFFERENT sessions (the reader is in one, while the docked
+     * tab was opened from another). One page-wide snapshot made every badge read whichever session's read
+     * landed last, which is the cross-talk the reader reported: a badge showing another session's count,
+     * and a session with a real list showing zero. So each session's read publishes only into its own
+     * slot, and every consumer takes its own slot, by the session it is actually about.
+     *
+     * A session that has never been read answers an unread empty view — never another session's list.
+     * `sessionId === undefined` answers the most recently published view — exactly what
+     * {@link PendingDiffStore.getSnapshot} answers — because that is what a caller with no session of its
+     * own (a whole-page concern) is asking for.
+     * @param sessionId - the session whose view to read.
+     * @returns that session's snapshot, identity-stable until it is next published.
+     */
+    viewFor: (sessionId: SessionId | undefined) => PendingDiffSnapshot;
+    /**
+     * Every session's view this page is HOLDING, one per session it has read.
+     *
+     * This is the reader a press needs (see `produced-diff.ts`): a shell press names a file and asks whether
+     * ANY session this page has read holds it, and the press cannot wait for a poll. The slots are where the
+     * fresh paths live — the light read's `paths` and the last full read's `files` — so answering from the
+     * slots is what keeps a file edited since the last full read from being a press nothing recognises.
+     * @returns the held views; a session never read contributes nothing (it has no slot).
+     */
+    views: () => readonly PendingDiffSnapshot[];
     /** Re-read one session's pending list (an absent session empties the view). */
     refresh: (sessionId: SessionId | undefined) => Promise<void>;
+    /**
+     * Ask how many rows this session has, THE LIGHT WAY: one number, no file content.
+     *
+     * This is what a seat polls while it is showing nothing but its badge. It publishes into the same
+     * per-session slot as `refresh` — as `count`, never as `files` — so a badge keeps reading the view it
+     * already subscribes to, and it deliberately does NOT set `read` (a count is not a list: a session
+     * whose list has never been read stays unread, and its list stays empty rather than looking loaded).
+     *
+     * Failure keeps the LAST GOOD number: a count that failed knows nothing, and showing 0 or a blank
+     * badge for a list that may well be full is worse than showing the previous figure. A host that
+     * predates the endpoint (`unknown endpoint "list-count"`) is detected here ONCE and then this call
+     * degrades to `refresh`, which is exactly the old behaviour at exactly the old cost — one full read
+     * per tick — and an absent session has no count to ask for, so it returns without a call.
+     */
+    refreshCount: (sessionId: SessionId | undefined) => Promise<void>;
     /** Keep one operation. `keepListed` leaves the resolved entry in the list. */
     keep: (sessionId: SessionId, id: string, keepListed?: boolean) => Promise<void>;
     /** Revert one operation. `keepListed` leaves the resolved entry in the list. */
@@ -35,18 +78,58 @@ export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
     browse: (sessionId: SessionId, path?: string) => Promise<DiffApprovalBrowseValue>;
     /** Add one named path to the list, then refresh; resolves to what the scan did. */
     addPath: (sessionId: SessionId, path: string, includeUnchanged: boolean, exact?: boolean) => Promise<DiffApprovalAddValue>;
+    /**
+     * The reader is looking at this file now: its row's unseen dot goes out. Deliberately NOT followed by a
+     * re-read — see the note at the implementation.
+     */
+    markSeen: (sessionId: SessionId, id: string) => Promise<void>;
     /** Open one file with its default application or reveal it in the folder. */
     open: (sessionId: SessionId, id: string, action: DiffApprovalOpenAction) => Promise<void>;
     /** Keep every pending entry of one session in a single host call, then refresh. */
     keepAll: (sessionId: SessionId) => Promise<void>;
     /** Revert every pending entry of one session in a single host call, then refresh. */
     revertAll: (sessionId: SessionId) => Promise<void>;
+    /**
+     * Keep a pick of entries, then refresh once. The host makes the whole pick ONE undo step, so this is
+     * one action to the reader in every sense: one request, one read back, one Ctrl+Z.
+     */
+    keepMany: (sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined) => Promise<void>;
+    /**
+     * Revert a pick of entries, then refresh once. Its undo restores what the host could snapshot: a file
+     * the agent created is DELETED with no undo at all, so the panel asks before a pick that would do it.
+     */
+    revertMany: (sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined) => Promise<void>;
     /** Inline one workspace image as a base64 data URI (empty when unreadable). */
     previewImage: (sessionId: SessionId, path: string) => Promise<string | undefined>;
+    /**
+     * Write one annotation down, then refresh so the thread appears from the host's own
+     * copy (the panel keeps no thread state of its own).
+     */
+    commentAdd: (sessionId: SessionId, comment: CommentDraft) => Promise<DiffApprovalCommentAddValue>;
+    /** Drop one annotation, then refresh. */
+    commentRemove: (sessionId: SessionId, id: string) => Promise<DiffApprovalCommentRemoveValue>;
+    /**
+     * Drop several annotations in ONE host call, then refresh once.
+     *
+     * One refresh is the difference a batch makes here: a loop of `commentRemove` re-reads (and
+     * re-renders) the whole session between every comment, so the list visibly dismantles itself one
+     * item at a time while the reader asked for one action.
+     */
+    commentRemoveMany: (sessionId: SessionId, ids: readonly string[]) => Promise<DiffApprovalCommentRemoveManyValue>;
+    /** Ask one stored comment as its own turn, then refresh (the answer is derived on read). */
+    commentAsk: (sessionId: SessionId, id: string, prompt: string, text: string) => Promise<DiffApprovalCommentAskValue>;
+    /** The reader is looking at a comment: its card's dot goes out, then the list is re-read. */
+    commentSeen: (sessionId: SessionId, id: string) => Promise<void>;
     /** Drop every local fact (used on connection reset). */
     reset: () => void;
     /** Acknowledge a redo-cleared notice so the panel surfaces it only once. */
     clearRedoCleared: () => void;
+    /**
+     * Acknowledge the last refused-undo notice, once the panel has said it. Without this
+     * the field would sit there for the rest of the session and the same refusal later
+     * would not be news; the panel says it and clears it in one step.
+     */
+    clearUndoNotice: () => void;
 }
 /**
  * Create the store over the review-channel port.

package/lib/types/comment-ask.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Asking the session's agent about one comment, and reading the answer back out of
+ * the transcript.
+ *
+ * The submission goes through the host's own session API (`ctx.sessionController`),
+ * which is the one path that already knows how to admit a prompt: it mints the
+ * message, persists it, and — the reason this module needs no identity of its own —
+ * stores the request id the caller supplies on the exact user message it accepts
+ * (`source.rpcId`). That id is the join key between a comment and its message, and it
+ * makes a retried submission the same submission rather than a second one.
+ *
+ * The answer is never stored: `answers()` derives it from the session's own derived
+ * message history on every read, so the transcript stays the single source of truth
+ * for what the agent said. The agent is asked with `mode: 'queue'`, so a comment is
+ * its own turn ("one ordinary message of its own turn") — two comments asked at the
+ * same time are two turns, not one turn two blocks have to share.
+ *
+ * @module dsh-diff-approval/src/comment-ask
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { DiffApprovalCommentAskValue, CommentRecord } from './types.ts';
+import type { CommentScope, CommentStore } from './comments.ts';
+/** One derived transcript message, narrowed to what answering a comment needs. */
+interface DerivedMessage {
+    role?: unknown;
+    content?: unknown;
+    source?: {
+        kind?: unknown;
+        rpcId?: unknown;
+    } | undefined;
+}
+/**
+ * One entry of the session's event log, narrowed to what answering a comment reads.
+ *
+ * The log is where the turn numbers live: `deriveMessages` hands back messages with no
+ * attribution at all, and an answer belongs to the turn that claimed the question, not
+ * to "everything up to the next message a human happened to write".
+ */
+interface LogEvent {
+    type?: unknown;
+    data?: LogData | undefined;
+}
+/** One event's payload, as the by-type reads below see it. */
+interface LogData {
+    /** The turn a message or boundary belongs to (`turn/start`, `user/message`, …). */
+    turn?: unknown;
+    /** `assistant/message` carries its assembled message here rather than flat. */
+    message?: DerivedMessage | undefined;
+    /** `user/message` IS the message, so role/content/source sit on the payload. */
+    role?: unknown;
+    content?: unknown;
+    source?: {
+        kind?: unknown;
+        rpcId?: unknown;
+    } | undefined;
+}
+/**
+ * What one question's transcript read found.
+ *
+ * `ended` is the turn's own end, not a verdict about the answer: whether an answer exists
+ * is what `answer` says. Keeping the two apart is what lets the panel show a stopped note
+ * for a turn that ended with nothing while a turn that ended AFTER writing keeps showing
+ * its answer.
+ */
+export interface AskRead {
+    /** The claiming turn's last assistant text, or `undefined` while it has written none. */
+    answer: string | undefined;
+    /**
+     * The turn that claimed the question, as the transcript itself attributes it. The inbox
+     * claim records the same number (`agent/inbox/claimed`); this is the read that does not
+     * depend on having been subscribed at the time.
+     */
+    turn: number | undefined;
+    /** The claiming turn is over (`turn/end` in the log), whatever it did or did not write. */
+    ended: boolean;
+}
+/**
+ * One request's already-read transcripts, keyed by the session read.
+ *
+ * `undefined` is cached as a value (hence `has`, not a truthy check): a session whose log cannot be
+ * read must not be asked for again within the same read, or a folded-over lineage would pay for the
+ * same failure once per transcript.
+ */
+export type TranscriptCache = Map<SessionId, readonly LogEvent[] | undefined>;
+/**
+ * The answer to one submitted comment, read from the session's own event log.
+ *
+ * Our prompt and the turn that ran because of it are one thing. The submission carries a
+ * request id on its `user/message` (`source.rpcId`), and `turn/start` is the bracket the
+ * log puts around a turn, so the question's own turn IS the window: the assistant
+ * messages of that turn are the answer, and `turn/end` for it is where the question is
+ * over. Nothing between the two belongs to anyone else.
+ *
+ * That is what keeps a later input from stealing the answer. A session log has
+ * user-role messages no human wrote — a subagent report, a background-job notice, an
+ * injected context — and under the old "walk to the next human message, take the last
+ * assistant text" rule any of them let the span run on into the NEXT turn's answer, so a
+ * comment that had been answered was silently replaced by whatever the agent later said
+ * about something else entirely. A tool-result message (role `user` as well) has the
+ * same problem for the opposite reason: it is a boundary trap that would end a segment
+ * mid-turn and make a question with a tool call behind it look unanswered. Bound by the
+ * turn, both read correctly: the tool result is inside it, and the later input is not.
+ *
+ * @param events - the session's event log, in sequence order.
+ * @param requestId - the request id the comment was submitted under.
+ * @returns the claiming turn, its answer text, and whether the turn is over.
+ */
+export declare function answerForRequest(events: readonly LogEvent[], requestId: string): AskRead;
+/**
+ * Submits comments as turns of their session, and reads their answers back.
+ *
+ * One instance serves every session: the store is the state, and the per-agent
+ * subscription is registered on first use and lives with the agent's own context.
+ */
+export declare class CommentAsker {
+    private readonly ctx;
+    private readonly comments;
+    /**
+     * The agent each session's inbox events are subscribed on, keyed by session id, with
+     * the disposers that release those subscriptions.
+     *
+     * Keyed by AGENT IDENTITY, not merely "this session id was watched once": a
+     * resumed or re-created agent for the same session id is a different object
+     * whose listeners live on its OWN context, so a session-id set would consider
+     * the new agent already watched and never subscribe to it — leaving `turn`
+     * undefined forever, `agent/turn-stopping` never arriving, and the panel stuck
+     * on "replying" with no way out (the defect this map replaces). The disposers are
+     * what keeps a replacement from leaking a second set of handlers per event.
+     */
+    private readonly watched;
+    /**
+     * @param ctx - the plugin's host context (its `sessionController` and `agents` are asked for lazily).
+     * @param comments - the comment store the ask is recorded in.
+     */
+    constructor(ctx: Context, comments: CommentStore);
+    /**
+     * Ask one stored comment as its own turn.
+     *
+     * The request id is recorded BEFORE the submission leaves, so a claim event that
+     * arrives while the submission is still in flight already finds its comment. A
+     * submission that rejects is marked dropped rather than left looking pending.
+     *
+     * @param sessionId - the session the question is asked FROM: the prompt goes into it, so its
+     *   transcript is where the answer will appear.
+     * @param commentId - the comment to ask.
+     * @param prompt - the prompt text to send verbatim.
+     * @param text - the reader's own words, which the prompt wraps: the thread keeps these.
+     * @param signal - aborts the submission.
+     * @param inScope - which comment authors the caller's lineage covers, so a thread another seat
+     *   wrote can be asked from this one.
+     * @returns what the request did.
+     */
+    ask(sessionId: SessionId, commentId: string, prompt: string, text: string, signal: AbortSignal, inScope: CommentScope): Promise<DiffApprovalCommentAskValue>;
+    /**
+     * One scope's questions, grouped by THE TRANSCRIPT each was submitted into.
+     *
+     * A lineage's threads may hold questions asked from several seats, and an answer lives in the
+     * transcript of the session that was asked — so the read is per transcript, not per thread. Grouping
+     * here (rather than reading each thread separately) is what keeps a poll to ONE log walk per
+     * transcript, however many threads asked there.
+     *
+     * The legacy case is why `askTranscript` exists: a question asked before the asking session was
+     * recorded has only the comment's own session to go on, which is where it went.
+     * @param visible - the comments this read may see (already scoped by the caller).
+     * @returns the request ids per transcript; empty when nothing was ever asked.
+     */
+    answerGroups(visible: readonly CommentRecord[]): Map<SessionId, string[]>;
+    /**
+     * Every question submitted into ONE transcript and what it says about them, keyed by the
+     * question's request id (which is what `CommentAsk` records and what a client matches
+     * against). Derived from that session's event log on every call and never stored: the log
+     * is the one source of truth for what the agent said, so a stored copy could only ever
+     * disagree with it.
+     * @param sessionId - the transcript to read.
+     * @param requestIds - the questions that were submitted into it.
+     * @param cache - this request's already-read logs, so the answer fold and the turn-end read
+     *   below share ONE walk of a log that can hold >100k events.
+     * @returns the read per question; empty when the session holds no questions.
+     */
+    answersFor(sessionId: SessionId, requestIds: readonly string[], cache?: TranscriptCache): Record<string, AskRead>;
+    /**
+     * The turns the session's log shows as over, for the questions it holds.
+     *
+     * `agent/turn-stopping` already reports a turn's end live, and that is what usually
+     * writes `ended` down (see `markTurnEnded`). Reading it out of the log as well is what
+     * makes the flag survive a session this process did not watch end — a resumed session,
+     * a client that connected afterwards, a deployment whose agent events cannot be
+     * subscribed at all — because `turn/end` is durable and the event is not.
+     *
+     * @param sessionId - the transcript whose turns to check.
+     * @param cache - this request's already-read logs (see `answersFor`).
+     * @returns the turns the log closed, or empty when the log cannot be read.
+     */
+    endedTurns(sessionId: SessionId, cache?: TranscriptCache): number[];
+    /**
+     * One session's event log, as the reads above take it.
+     *
+     * `snapshotEvents()` and not `deriveMessages()`: the derived history is a list of
+     * messages with no turn attribution, and the turn is the whole point of the answer read
+     * (see `answerForRequest`). The event log is the session's append-only source of truth
+     * and `snapshotEvents` hands back a frozen, sequence-ordered copy of it, so walking it
+     * is a plain read that cannot disturb the session.
+     *
+     * The cache is per REQUEST, not per session: one list read asks this twice for every transcript
+     * (the answer fold and the turn-end read), and the copy is the expensive part of a long session's
+     * log. `has` rather than a truthy check, so "cannot be read" is cached as such instead of being
+     * asked again.
+     * @param sessionId - the session to read.
+     * @param cache - this request's already-read logs, when the caller is doing several reads.
+     * @returns its events, or undefined when no live session can be read.
+     */
+    private sessionEvents;
+    /** The live agent for one session, or `undefined` when this host drives none. */
+    private agentOf;
+    /**
+     * Subscribe to one agent's inbox, once per LIVE agent, moving to a replacement agent
+     * when the session's agent changes under us.
+     *
+     * The listeners live on the agent's own context, so they go away with the agent
+     * and never outlive it — which is exactly why the dedup has to be per agent and
+     * not per session: a session whose agent was re-created (a resume, a restart, a
+     * rebuilt agent for the same id) has nothing listening on the new one, and every
+     * event this module depends on would silently stop arriving. The remembered
+     * agent is compared by identity, so a different object re-subscribes and a
+     * disposed one's stale entry cannot block it. What the replaced agent held is
+     * released first, so re-arming is not a leak: one set of handlers per live agent,
+     * not one more per identity change.
+     *
+     * Called on every ask AND on every poll read (`answersFor`), because the agent can be
+     * replaced while a question is still pending — the case where nothing asks again.
+     * @param sessionId - the session whose agent to watch.
+     */
+    private watch;
+}
+export {};