dsh-diff-approval 0.29.1 → 0.30.1

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

@@ -5,9 +5,30 @@
  * @module dsh-diff-approval/client/port
  */
 import type { ClientConnectionRpc, SessionId } from '@deepseek-ai/dsh-client-connection/client';
-import type { DiffApprovalActionValue, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalBulkValue, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalPreviewImageValue, DiffApprovalRefreshValue, VcsImportValue } from '../types.ts';
+import type { CommentAnchor, CommentQuoteLine, DiffApprovalActionValue, DiffApprovalAddValue, DiffApprovalBlockRange, DiffApprovalBrowseValue, DiffApprovalBulkValue, DiffApprovalCommentAddValue, DiffApprovalCommentAskValue, DiffApprovalCommentRemoveManyValue, DiffApprovalCommentRemoveValue, DiffApprovalListValue, DiffApprovalOpenAction, DiffApprovalOpenValue, DiffApprovalPreviewImageValue, DiffApprovalRefreshValue, VcsImportValue } from '../types.ts';
 /** The channel the host half registers and this port calls. */
 export declare const DIFF_APPROVAL_CHANNEL = "/diff-approval";
+/**
+ * One annotation as the panel hands it over: what the reader wrote and where they
+ * wrote it. The display path is not part of it — the entry a comment hangs off is the
+ * host's authority on what the file is called.
+ */
+export interface CommentDraft {
+    /** Caller-minted id, so a retried write lands on the same comment. */
+    id: string;
+    /** The listed entry the annotation hangs off. */
+    entryId: string;
+    /** The lines it was made on, as new-file line numbers. */
+    anchor: CommentAnchor;
+    /** The anchored lines as they read then (the re-anchor fingerprint). */
+    quote: string;
+    /** `quote` with one line of context on each side, as it read then. */
+    quoteContext?: string | undefined;
+    /** The gutter numbers of `quote`'s lines, in the same order. */
+    quoteLines?: CommentQuoteLine[] | undefined;
+    /** What the reader wrote. */
+    text: string;
+}
 /** This package's business verbs over the review channel. */
 export interface DiffApprovalPort {
     /** Read one session's pending entries (plus its workspace root), oldest capture first. */
@@ -41,8 +62,36 @@ export interface DiffApprovalPort {
     keepAll(sessionId: SessionId): Promise<DiffApprovalBulkValue>;
     /** Revert every pending entry of one session in a single host call (one batch). */
     revertAll(sessionId: SessionId): Promise<DiffApprovalBulkValue>;
+    /**
+     * Keep a PICK of entries in one host call: one request, one durable write and one undo step — the
+     * host records the whole pick as a single batch, so one Ctrl+Z takes that one decision back instead
+     * of peeling it apart file by file. `keepListed` says whether the resolved files stay listed.
+     *
+     * There is a `revertMany` beside it, and the pair is NOT symmetric: a keep writes nothing, while a
+     * revert writes the baseline over each file — and DELETES the ones the agent created, which the host
+     * cannot undo. The panel asks before sending a pick whose revert would delete anything.
+     */
+    keepMany(sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined): Promise<DiffApprovalBulkValue>;
+    /** Revert a PICK of entries in one host call: the same one request, one write, one undo step. The undo
+     *  restores the entries the host could snapshot — see `keepMany` for the deletes it cannot. */
+    revertMany(sessionId: SessionId, ids: readonly string[], keepListed: boolean | undefined): Promise<DiffApprovalBulkValue>;
     /** Read one workspace image and inline it as a base64 data URI (for the Markdown preview). */
     previewImage(sessionId: SessionId, path: string): Promise<DiffApprovalPreviewImageValue>;
+    /**
+     * Write one annotation down. The host refuses a comment whose entry is not in the
+     * session's list, and the refusal is reported rather than retried.
+     */
+    commentAdd(sessionId: SessionId, comment: CommentDraft): Promise<DiffApprovalCommentAddValue>;
+    /** Drop one annotation (what "a comment dies with its entry" does by hand). */
+    commentRemove(sessionId: SessionId, id: string): Promise<DiffApprovalCommentRemoveValue>;
+    /**
+     * Drop several annotations in one host call: one request, one write of the session's comment file,
+     * and one read afterwards (`store.commentRemoveMany`). A batch that is a loop of `commentRemove`
+     * calls is a different thing — N requests, N writes — which is what this endpoint exists to avoid.
+     */
+    commentRemoveMany(sessionId: SessionId, ids: readonly string[]): Promise<DiffApprovalCommentRemoveManyValue>;
+    /** Ask one stored comment as its own turn of the session. */
+    commentAsk(sessionId: SessionId, id: string, prompt: string, text: string): Promise<DiffApprovalCommentAskValue>;
 }
 /** Build the port over one generic RPC caller.
  * @param rpc - the connection's channel caller.

package/lib/types/client/presentation-menu.d.ts

@@ -13,7 +13,7 @@
  * @module dsh-diff-approval/client/presentation-menu
  */
 import type { ReactNode } from 'react';
-import type { MenuEntry } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { MenuEntry } from './dsh-icons.ts';
 import type { DiffApprovalPresentation } from './settings.ts';
 import type { Translator } from './locales.ts';
 /**

package/lib/types/client/produced-diff.d.ts

@@ -1,27 +1,64 @@
 /**
- * Inject a "查看差异" button beside each DSH produced-file chip.
+ * Route a file press's own click.
  *
- * The harness's `ProducedFiles` component renders each produced file as a
- * `<button>` chip inside `[data-produced-files-row]`; the full path rides the
- * chip's `title`. This plugin wants a quick "view this file's diff" affordance
- * there, but the plugin should not have to touch the harness component. So this
- * module watches the DOM for those chips (via a MutationObserver, the same
- * bridge the dsh-pocket mobile fork uses to inject its 复制 buttons) and injects
- * a small button after each one. Clicking it dispatches a window event that the
- * diff-approval panel listens for (see PendingPanel), which opens the panel and
- * selects the file when it is still pending, or toasts otherwise.
+ * The harness draws several presses that answer by opening a file in a viewer of its OWN, and this
+ * module takes over exactly those — and only for a file the review panel is already holding — so the
+ * reader gets both ways of opening it instead of one fixed behaviour:
  *
- * The injected button is intentionally self-contained (inline styles + a fixed
- * label) so it needs no stylesheet and no harness change.
+ *   `[data-produced-files-row] button`    0.1.5's produced-file card       `title` = the path
+ *   `[data-presented-files-row] button`   0.1.7's presented-file card      `title` = the path
+ *   `[data-changed-files] button`         0.1.7's changed-files row        `aria-describedby` = the path
+ *   `button[title]`                       a message's file LINK (0.1.7)    `title` = the path
+ *   `button[data-ref-chip]`               a `@file` chip in a message      `title` = the token
+ *   `a[href]`                             any other link naming a file     `href`  = the path
+ *
+ * Everything else is left entirely alone: a link to a URL, an in-page anchor, a chip naming something
+ * that is not a file, a file this panel does not hold, a modified press (Ctrl/Cmd/Shift/Alt, or a
+ * middle click — gestures the harness may give its own meaning later), and any press inside this
+ * plugin's own surface, whose buttons carry paths too and belong to the panel that is already showing
+ * the file.
+ *
+ * The name of the module (and of the event it raises) dates from when the produced-file card was the
+ * only press of this kind; `data-presented-files-row` is that same list under 0.1.7's name for it.
  */
-/** Window event dispatched by the injected button; PendingPanel listens for it. */
+/** Window event dispatched when a pending file's press is taken over; the panel listens for it. */
+export declare const CHIP_MENU_EVENT = "diff-approval:chip-menu";
+/** Window event dispatched by the panel to open a file in the panel; PendingPanel listens for it. */
 export declare const OPEN_FILE_EVENT = "diff-approval:open-file";
+/** What a press tells the panel: which file, and where the press was (the menu hangs under it). */
+export interface ProducedChipMenuDetail {
+    /** The path the pressed element names. */
+    path: string;
+    /** The pressed element's own box, in viewport coordinates. */
+    x: number;
+    y: number;
+}
+/** What the bridge needs from the host to decide, and to report. */
+export interface ProducedChipBridge {
+    /**
+     * Whether the panel holds this file right now. Called synchronously on every press, because
+     * the decision it answers is whether the press is prevented — there is no second chance at it.
+     */
+    isPending: (path: string) => boolean;
+    /** A pending file's press was taken over: open the menu the press asked for. */
+    onMenu: (detail: ProducedChipMenuDetail) => void;
+}
 /**
- * Start injecting diff buttons into the produced-files row.
- * @param label - localized "查看差异" text, used as the icon button's accessible
- *   name + hover title (the button renders only an icon).
- * @param openPath - called with a produced-file path when its injected button is
- *   clicked; the diff-approval panel decides whether that file is still pending.
- * @returns a cleanup that disconnects the observer and removes injected buttons.
+ * Press a file's own press again — the shell's open, run the only way this plugin can run it
+ * faithfully, with the bridge standing down for that press (see the file's own doc).
+ *
+ * The menu's first row must open the file exactly the way the shell does, and what that is is the
+ * shell's business, not this plugin's: pressing the same element again keeps every part of it —
+ * the viewer it opens, the line a `#L24` suffix asked for, whatever a future shell adds there.
+ *
+ * @param path - the file the press names.
+ * @returns whether an element naming it was found to press.
+ */
+export declare function replayFilePress(path: string): boolean;
+/**
+ * Start routing the presses that would open a file in the shell's own viewer.
+ *
+ * @param bridge - the host's decision (is the file pending) and where to report a press that is.
+ * @returns a cleanup that stops routing.
  */
-export declare function startProducedDiffInjection(label: string, openPath: (path: string) => void): () => void;
+export declare function startProducedChipMenu(bridge: ProducedChipBridge): () => void;

package/lib/types/client/session-seat.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which session the review is about, as every shell of this plugin has offered it.
+ *
+ * 0.1.7 changed how a client learns the selected session. Its session-list store carries
+ * `{ ids, byId, phase, projectionsBySession }` — there is no `current` any more — and the shell's own
+ * components take the id from their composed SLOT PROPS instead (`const { sessionId, useSessions } =
+ * props`, then `useSessions(s => s.byId[sessionId]?.blank)`; measured in `dsh-client-ui-conversation`
+ * and `dsh-client-ui-agent-preset`). Older shells put it in the store as `state.current`.
+ *
+ * The seats differ, and that is the whole reason this module exists: the Session HEADER seat is
+ * session-scoped and is handed `sessionId`; the sidebar FOOTER seat — where this panel's own badge
+ * lives — is rendered `renderSlot('sidebar.footer.action', { wide })` and is handed nothing else. So
+ * the header publishes what it is showing, the footer reads it, and the store is the third fallback
+ * (`current` on the shells that have it). Every reader here is total: an unknown shape answers
+ * "nothing known" rather than throwing, and no field that is absent is taken for a value.
+ *
+ * @module dsh-diff-approval/client/session-seat
+ */
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+/**
+ * Publish the session the header entry is showing.
+ * @param id - the id, or `undefined` when the shell named none.
+ */
+export declare function publishSessionId(id: SessionId | undefined): void;
+/** The session the header entry last showed, or `undefined` when it never named one. */
+export declare function publishedSessionId(): SessionId | undefined;
+/**
+ * The selected session a shell's session-list state names, by every field the shells have used.
+ * @param state - the store state handed to the selector.
+ * @returns the id, or `undefined` when this shape names none.
+ */
+export declare function selectedSessionOf(state: unknown): SessionId | undefined;
+/**
+ * Whether one session row is BLANK — a freshly created session with nothing in it yet, which has
+ * nothing to review and leaves this plugin's entry inert exactly like no session at all.
+ *
+ * `byId[id].blank` is the row's own flag and has kept its name across the shells; a store that
+ * carries `blank` on the STATE (with the id beside it) is read too. An absent flag is not blank: a
+ * shape this plugin does not recognise must not disable the panel.
+ *
+ * @param state - the store state handed to the selector.
+ * @param id - the session the answer is about; `undefined` answers false.
+ * @returns true only when the shell says that session is blank.
+ */
+export declare function sessionIsBlank(state: unknown, id: SessionId | undefined): boolean;
+/**
+ * The session this mount is about: the slot prop the shell composed, else the store's own selected
+ * session, else what the header entry published (see the module doc).
+ * @param propSessionId - `sessionId` from the composed slot props, when the shell sends one.
+ * @param storeSelected - the store's selected session, when its shape names one.
+ * @returns the id, or `undefined` when nothing here knows one.
+ */
+export declare function sessionIdFor(propSessionId: SessionId | undefined, storeSelected: SessionId | undefined): SessionId | undefined;

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

@@ -2,14 +2,34 @@
 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, 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;
     /** Entry ids whose keep/revert is in flight; their controls are disabled. */
@@ -30,6 +50,20 @@ 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. */
@@ -75,15 +109,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 +126,43 @@ 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
+     * `DiffApprovalStore.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>;
     /** 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,9 +7,9 @@
  */
 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> {
     /** Re-read one session's pending list (an absent session empties the view). */
@@ -41,12 +41,45 @@ export interface PendingDiffStore extends HostObservable<PendingDiffSnapshot> {
     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>;
     /** 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,209 @@
+/**
+ * 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 } from './types.ts';
+import type { 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;
+}
+/**
+ * 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;
+/**
+ * Read every question one session has asked, keyed by its request id.
+ * @param events - the session's event log, in sequence order.
+ * @param requestIds - the questions' request ids.
+ * @returns the read per request id; a question the log holds nothing for reads as nothing.
+ */
+export declare function answersIn(events: readonly LogEvent[], requestIds: readonly string[]): Record<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 comment belongs to.
+     * @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.
+     * @returns what the request did.
+     */
+    ask(sessionId: SessionId, commentId: string, prompt: string, text: string, signal: AbortSignal): Promise<DiffApprovalCommentAskValue>;
+    /**
+     * Every question of one session and what the transcript says about it, keyed by the
+     * question's request id (which is what `CommentAsk` records and what a client matches
+     * against). Derived from the session's own 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 session whose comments to read.
+     * @returns the read per question; empty when the session holds no questions.
+     */
+    answers(sessionId: SessionId): 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 session whose turns to check.
+     * @returns the turns the log closed, or empty when the log cannot be read.
+     */
+    endedTurns(sessionId: SessionId): 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.
+     *
+     * @param sessionId - the session to read.
+     * @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 (`answers`), 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 {};