dsh-diff-approval 0.22.2 → 0.23.0

package/lib/index.js

@@ -1276,6 +1276,45 @@ function defaultOpenPath(path, action) {
 	}
 }
 //#endregion
+//#region lib/types/comment-skill.js
+/**
+* The one skill this plugin offers the agent: how to answer a diff comment.
+*
+* The rules live here rather than in the system prompt. The harness's own `skill`
+* tool advertises every registered skill's name and description as a context message
+* and loads the body on demand, so the long form costs nothing until a comment is
+* actually being answered — and nothing this plugin registers can leak into unrelated
+* turns the way a global system-prompt section would.
+*
+* The comment prompt itself still carries the short version (see
+* `discussion.promptRule` in `src/client/locales.ts`) and names this skill, so the
+* behavior survives a build whose harness has no skill registry at all. The two are
+* kept in step by a test in `tests/diff-approval.spec.ts`.
+*/
+/** The kebab-case name the comment prompt points the agent at. Prefixed with the whole
+* package name: skill names share one flat namespace with no reverse-DNS scoping, so a
+* short name like `diff-comment` is the kind of thing another plugin would also pick. */
+const COMMENT_SKILL_NAME = "dsh-diff-approval-comment";
+/** The contribution to register with the skill registry. */
+const COMMENT_SKILL = {
+	name: COMMENT_SKILL_NAME,
+	description: "How to answer a [评论] / [Review] comment on a few diff lines: answer those lines only, at most 3 lines, no blank line between them, and point at the message box below when three lines cannot carry the answer.",
+	whenToUse: "A message that starts with `[评论] (path:lines)` (or `[Review] (path:lines)` in English) is a comment from the diff panel — load this skill before answering it.",
+	content: `# 回答代码批注
+
+消息以 \`[评论] (path:lines)\` 开头时，就是 diff 面板里对那几行代码提的批注。按下面的规则回答：
+
+- 只谈这几行（最多带上直接相邻的一两行），不要扩到整个文件或整个任务。
+- 不超过 3 行。
+- 行与行之间不要空行：讨论区按代码行排版，一个空行就占掉一整行高度，看起来像代码里的空洞。
+- 要引用代码就写 \`文件:行号\`，不要把整段贴回来。
+- 回答直接显示在批注下方的小讨论区里，所以不要写"如你所见""上面提到"这类指代。
+- 不确定就说不确定，并说清需要看哪一段。
+- 3 行里说不清（要展开、要看更多代码、要来回几轮），就直说一句"这条在批注里说不清，去下方发消息的输入框里聊"，不要在批注里硬塞长回答。
+`,
+	source: "runtime"
+};
+//#endregion
 //#region lib/types/vcs.js
 /**
 * Version-control integration, host half: detect which VCS (git/svn/p4)
@@ -1608,6 +1647,82 @@ const inject = [
 ];
 /** The connection RPC channel this plugin serves. */
 const DIFF_APPROVAL_CHANNEL = "/diff-approval";
+/**
+* The skill to name in a comment prompt on this deployment, or `undefined` when the
+* harness cannot deliver it.
+*
+* The prompt has two shapes: the short rules inline (always works), or nothing but a
+* pointer at this skill (the rules then cost nothing until a comment is answered). Which
+* one the client sends is the HOST's answer, because the host is the only side that knows
+* whether the contribution landed.
+*
+* The answer turns on the registration alone — the half this plugin performs and can be
+* sure of. The other half, the `skill` tool that advertises the catalog and loads the
+* body, belongs to the harness: `dsh-base` mounts `@deepseek-ai/dsh-tool-skill` beside
+* `dsh-skill`, and both have shipped in every release since `0.0.1-rc.1`. Asking the tool
+* registry for it instead was tried and reads absent in a live session whose catalog was
+* demonstrably working — a false negative that kept the rules inline. The registration is
+* the honest signal.
+*
+* @param _ctx - the plugin's host context (kept for the shape of the question).
+* @param registered - whether {@link registerCommentSkill} got the skill in.
+* @returns the skill name to point the prompt at, or undefined for the inline rules.
+*/
+function commentSkillCapability(_ctx, registered) {
+	return registered ? COMMENT_SKILL_NAME : void 0;
+}
+/**
+* The answer to {@link commentSkillCapability}, asked no earlier than the first list
+* request — applying is too early for anything that reads another plugin's services. A
+* positive is kept; a negative is re-checked on the next request, since it costs two
+* property lookups.
+*
+* @param ctx - the plugin's host context.
+* @param registered - whether the skill is in the registry.
+* @returns a memo that answers with the skill name or undefined.
+*/
+function lazyCommentSkill(ctx, registered) {
+	let resolved;
+	let reported = false;
+	return () => {
+		if (resolved !== void 0) return resolved;
+		resolved = commentSkillCapability(ctx, registered);
+		if (!reported) {
+			reported = true;
+			ctx.logger.info(`diff-approval: comment skill ${resolved ?? "not used"} (registered=${registered})`);
+		}
+		return resolved;
+	};
+}
+/**
+* Register the comment-answering skill with the harness's skill registry, when it has
+* one. The registry's own `skill` tool advertises the catalog and loads the body on
+* demand, so this costs nothing until a comment is answered — and unlike a
+* system-prompt section, a global registration here cannot shape unrelated turns.
+*
+* Feature-detected and contained: a build without the registry, or a registry that
+* refuses the contribution, simply leaves the short rules the comment prompt already
+* carries as the whole policy.
+*
+* @param ctx - the plugin's host context.
+* @returns whether the skill is now in the registry.
+*/
+function registerCommentSkill(ctx) {
+	if (typeof ctx.get("skills")?.register !== "function") return false;
+	let registered = false;
+	ctx.effect(() => {
+		const skills = ctx.get("skills");
+		if (typeof skills?.register !== "function") return () => {};
+		try {
+			const dispose = skills.register(COMMENT_SKILL);
+			registered = true;
+			return typeof dispose === "function" ? dispose : () => {};
+		} catch {
+			return () => {};
+		}
+	});
+	return registered;
+}
 /** The dominant line ending of `text`: CRLF when `\r\n` meets or beats lone
 * `\n`, else LF; a text with no line breaks falls back to LF.
 * @param text - the content to inspect.
@@ -1803,6 +1918,7 @@ function apply(ctx, config) {
 	const store = new PendingDiffStore();
 	const persistence = new PendingPersistence(resolve(expandHomePath(storageDir ?? defaultStorageDir())));
 	const launchPath = config?.openPath ?? defaultOpenPath;
+	const commentSkill = lazyCommentSkill(ctx, registerCommentSkill(ctx));
 	/** Hydrate the globally-unique store once from the single persistence file. */
 	let loadPromise;
 	const ensureLoaded = () => {
@@ -2346,7 +2462,8 @@ function apply(ctx, config) {
 					value: {
 						files,
 						workspacePath: workspaceOf(sessionId)?.path,
-						redoCleared: redoCleared || void 0
+						redoCleared: redoCleared || void 0,
+						commentSkill: commentSkill()
 					}
 				};
 			}
@@ -3183,4 +3300,4 @@ function openTargetOf(payload) {
 	};
 }
 //#endregion
-export { DIFF_APPROVAL_CHANNEL, PendingDiffStore, PendingPersistence, apply, defaultOpenPath, defaultStorageDir, inject, name };
+export { COMMENT_SKILL_NAME, DIFF_APPROVAL_CHANNEL, PendingDiffStore, PendingPersistence, apply, defaultOpenPath, defaultStorageDir, inject, name };

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

@@ -120,5 +120,5 @@ export declare const SplitDiff: import("react").ForwardRefExoticComponent<{
  */
 export declare function selectedPlainText(): string | undefined;
 /** Render the pending-edit review panel and its unified footer action. */
-export declare function PendingPanel({ wide, useSessions, usePending, onRefresh, onKeep, onRevert, onBlockKeep, onBlockRevert, onOpen, onPreviewImage, onPasteReference, onUndo, onRedo, onImportVcs, onRefreshVcs, onBrowse, onAddPath, onKeepAll, onRevertAll, onAckRedoCleared, collapseSidebar, t, docked, dockHost, onOpenDock, closeDock, useDock, }: PendingPanelProps): import("react").JSX.Element;
+export declare function PendingPanel({ wide, useSessions, usePending, onRefresh, onKeep, onRevert, onBlockKeep, onBlockRevert, onOpen, onPreviewImage, onPasteReference, onAskAgent, watchChat, onUndo, onRedo, onImportVcs, onRefreshVcs, onBrowse, onAddPath, onKeepAll, onRevertAll, onAckRedoCleared, collapseSidebar, t, docked, dockHost, onOpenDock, closeDock, useDock, }: PendingPanelProps): import("react").JSX.Element;
 export {};

package/lib/types/client/chat-bridge.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The panel's one connection to the session's chat: send one prompt, and watch
+ * the transcript so a discussion can show its answer where it was asked.
+ *
+ * Everything here is deliberately defensive. The surfaces it uses (the scoped
+ * `conversation` input face, the `sessions` binding, the `chat` view target) are
+ * public types but not plugin-documented API, so a build that lacks one reports
+ * "unavailable" and the caller falls back to the composer route it already had.
+ *
+ * @module dsh-diff-approval/client/chat-bridge
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
+/** One human-visible transcript node, reduced to what a discussion shows. */
+export interface ChatNodeView {
+    /** `user`, `assistant`, or the node's own kind for anything else. */
+    kind: string;
+    /** The node's text blocks joined; empty for nodes that carry no prose. */
+    text: string;
+    /**
+     * The runtime froze this assistant node when the turn was stopped (`interrupted` on
+     * the durable node). A stopped turn leaves one of these, often with no text, which is
+     * how a caller can tell "the answer was cut off" from "the answer is still coming".
+     * Only ever set when true.
+     */
+    interrupted?: boolean;
+}
+/** What a discussion needs to know about the session's chat right now. */
+export interface ChatView {
+    /** A turn is running for this session. */
+    running: boolean;
+    /** The durable transcript, in order. */
+    nodes: readonly ChatNodeView[];
+    /** The in-flight assistant text, or '' when nothing is streaming. */
+    partial: string;
+    /** The session's recorded prompt error, when there is one. */
+    error: string | undefined;
+    /**
+     * The prompts the session is still holding — its inbox queue plus the local
+     * submission echoes that have not become durable yet — or `undefined` on a build
+     * that does not publish them. A prompt that is not in the transcript is either one
+     * of these (still waiting) or gone (dropped with a stopped turn); without the
+     * evidence a caller can only keep waiting.
+     */
+    queued: readonly string[] | undefined;
+}
+/** The session chat as the panel uses it. */
+export interface ChatBridge {
+    /**
+     * Send one prompt into the session as a real turn.
+     * @param sessionId - the session to prompt.
+     * @param text - the prompt text, sent verbatim.
+     * @returns whether the send verb was available (false means "not sent").
+     */
+    ask: (sessionId: SessionId, text: string) => boolean;
+    /**
+     * Watch the session's transcript and turn state.
+     * @param sessionId - the session to watch.
+     * @param listener - called with the current view, then on every change.
+     * @returns the unsubscribe function.
+     */
+    watch: (sessionId: SessionId, listener: (view: ChatView) => void) => () => void;
+}
+/**
+ * Build the bridge over the client context. Every verb takes the session it
+ * addresses, so one bridge serves whichever session the panel is showing.
+ * @param ctx - the plugin's client context.
+ * @returns the bridge (its verbs report unavailability instead of throwing).
+ */
+export declare function createChatBridge(ctx: ClientContext): ChatBridge;

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

@@ -0,0 +1,194 @@
+/**
+ * Discussions attached to a diff row range: how many rows a block reserves in
+ * the row stream, and which actions the selection frame offers for a selection.
+ *
+ * Pure derivation so both rules are unit-testable without the panel — the panel
+ * itself only maps these answers onto rows and markup.
+ *
+ * @module dsh-diff-approval/client/discussion
+ */
+/** One row range in the current diff model (inclusive, 0-based row indices). */
+export interface DiscussionAnchor {
+    /** First row of the range, in the model this block is currently drawn against. */
+    start: number;
+    /** Last row of the range. */
+    end: number;
+    /** First new-file line the annotation was made on (survives model changes). */
+    startLine: number;
+    /** Last new-file line of the annotation. */
+    endLine: number;
+}
+/** One turn of a discussion: what the user said, or what the agent answered. */
+export interface DiscussionMessage {
+    /** Who spoke. */
+    role: 'user' | 'assistant';
+    /** The message text as it is rendered. */
+    text: string;
+}
+/** One discussion bound to a row range. */
+export interface Discussion {
+    /** Stable identity for keys and toggles. */
+    id: string;
+    /** The rows the block sits below. */
+    anchor: DiscussionAnchor;
+    /**
+     * The thread so far: the annotation first, then answers and follow-ups in the
+     * order they happened. A discussion is a conversation, not one question.
+     */
+    messages: readonly DiscussionMessage[];
+    /** What the user is typing into the compose row (not sent yet). */
+    draft: string;
+    /** Folded to the one-row header. */
+    collapsed: boolean;
+    /**
+     * No line of the anchor exists in the file any more (the code was changed or
+     * removed under it). The block stays where it last matched, cannot be commented
+     * on again, and is the user's to delete.
+     */
+    lost?: boolean;
+    /** The answer being streamed for the question in flight. */
+    reply?: string;
+    /** The turn for the last question is running. */
+    asking?: boolean;
+    /**
+     * The question is sent but still behind another turn of the session, so nothing
+     * streamed yet belongs to this discussion. The block says it is waiting instead
+     * of showing the other turn's answer.
+     */
+    queued?: boolean;
+    /** The answer failed (the session recorded a prompt error). */
+    failed?: boolean;
+    /**
+     * The turn for the last question was stopped before it wrote an answer. The block
+     * says so and offers the writing row again, instead of waiting on a turn that is over.
+     */
+    stopped?: boolean;
+    /**
+     * How many rows the block's body occupies, measured by the caller from what it
+     * actually renders (the thread plus the compose row). It is what keeps a
+     * discussion block's height an exact multiple of the code row.
+     */
+    bodyRows?: number;
+    /** How many older messages the row cap left out of the render. */
+    hidden?: number;
+}
+/** Rows a folded block occupies: its header line. */
+export declare const DISCUSSION_HEADER_ROWS = 1;
+/** Rows the compose area occupies: 0.3 + 1.4 + 0.3 of a code row. */
+export declare const DISCUSSION_COMPOSE_ROWS = 2;
+/** The most rows an answer may take before it would swamp the diff it annotates. */
+export declare const DISCUSSION_MAX_BODY_ROWS = 12;
+/**
+ * The newest turns that fit a size budget, and how many older ones were left out.
+ * A thread grows without bound, so the block shows its tail and says what it is
+ * hiding rather than clipping silently; the hidden note costs one row of the
+ * budget itself. Sizes are in whatever unit the caller budgets in (the panel uses
+ * code rows, fractions included, and rounds the total up once).
+ *
+ * @param messages - the whole thread, oldest first.
+ * @param sizeOf - the size one message needs when rendered (text plus its chrome).
+ * @param capRows - the body budget.
+ * @returns the messages to render, the count left out, and the size they need.
+ */
+export declare function discussionTail(messages: readonly DiscussionMessage[], sizeOf: (message: DiscussionMessage) => number, capRows: number): {
+    messages: readonly DiscussionMessage[];
+    hidden: number;
+    rows: number;
+};
+/**
+ * An answer with its blank lines dropped.
+ *
+ * The thread is plain text laid out in code rows, so a blank line between two
+ * paragraphs costs a whole row of height and reads as a gap in the code it
+ * annotates. The prompt asks the agent not to write them; this is what makes a
+ * stray one harmless, and both the render and the row measurement run the answer
+ * through it so the two can never disagree about how tall a turn is. What the user
+ * typed is shown exactly as typed.
+ *
+ * @param text - the answer text.
+ * @returns the same text without empty (or whitespace-only) lines.
+ */
+export declare function stripBlankLines(text: string): string;
+/**
+ * The text of one turn as the thread shows it: an answer loses its blank lines, a
+ * first-person turn keeps every one of them.
+ *
+ * @param message - the turn to render.
+ * @returns the text to lay out and to render.
+ */
+export declare function discussionText(message: DiscussionMessage): string;
+/**
+ * How many rows a block reserves, so the diff's height table stays exact.
+ * @param discussion - the discussion to measure.
+ * @returns the row count the block contributes.
+ */
+export declare function discussionRows(discussion: Discussion): number;
+/**
+ * Extra rows to add to each diff row's height: the block hangs below its range's
+ * last row, so a block's rows belong to that row's entry in the height table.
+ * Several blocks on one row sum up.
+ *
+ * @param discussions - the blocks currently attached to this file.
+ * @param rowCount - how many rows the diff has (clamps a stale anchor).
+ * @returns a map from row index to the rows added below it.
+ */
+export declare function discussionRowExtras(discussions: readonly Discussion[], rowCount: number): Map<number, number>;
+/**
+ * The discussion attached to exactly this range, if there is one.
+ *
+ * @param discussions - the blocks currently attached to this file.
+ * @param anchor - the range to look up.
+ * @returns the matching discussion, or `undefined`.
+ */
+export declare function discussionOnRange(discussions: readonly Discussion[], anchor: {
+    start: number;
+    end: number;
+}): Discussion | undefined;
+/**
+ * The discussion that already covers any part of this range. A row belongs to one
+ * annotation at most, so a selection that touches an existing block offers no
+ * second one - otherwise two blocks would describe the same line.
+ *
+ * @param discussions - the blocks currently attached to this file.
+ * @param anchor - the candidate range.
+ * @returns the overlapping discussion, or `undefined`.
+ */
+export declare function discussionOverlapping(discussions: readonly Discussion[], anchor: {
+    start: number;
+    end: number;
+}): Discussion | undefined;
+/**
+ * Re-anchor one discussion against the current rows: the rows whose new-file line
+ * falls inside the annotation's line range. When no line matches any more, the
+ * block keeps the rows it last matched and is marked lost, so it stays where the
+ * user last saw it and can only be deleted.
+ *
+ * @param discussion - the block to re-anchor.
+ * @param lineOf - the new-file line number of a row, or `undefined` for a row that has none.
+ * @param rowCount - how many rows the current model has.
+ * @returns the re-anchored discussion (the same object when nothing moved).
+ */
+export declare function remapDiscussion(discussion: Discussion, lineOf: (row: number) => number | undefined, rowCount: number): Discussion;
+/** What the selection frame shows for the current selection. */
+export interface SelectionFrameActions {
+    /** Whether keep/revert apply (the selection fully covers change blocks). */
+    keepRevert: boolean;
+    /** Whether a new discussion may be started on this range. */
+    comment: boolean;
+    /** Whether the frame renders at all (no visible action means no frame). */
+    visible: boolean;
+}
+/**
+ * Decide the selection frame's contents.
+ *
+ * Keep/revert needs covered change blocks; commenting needs a range that has no
+ * discussion yet. A frame with neither would be an empty floating box, so it is
+ * not rendered at all.
+ *
+ * @param options - whether change blocks are covered, and whether this range already has a discussion.
+ * @returns the three flags the caller branches on.
+ */
+export declare function selectionFrame(options: {
+    coversBlocks: boolean;
+    hasDiscussion: boolean;
+}): SelectionFrameActions;

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

@@ -48,6 +48,8 @@ export declare const zh: {
     'panel.diffDelColor': string;
     'panel.diffDelColorDesc': string;
     'panel.quickSummon': string;
+    'panel.commentMode': string;
+    'panel.commentModeDesc': string;
     'panel.quickSummonDesc': string;
     'panel.recordShortcut': string;
     'settings.keybindings': string;
@@ -61,6 +63,7 @@ export declare const zh: {
     'panel.key.jumpUp': string;
     'panel.key.jumpDown': string;
     'panel.key.copyRef': string;
+    'panel.key.addComment': string;
     'panel.key.openSearch': string;
     'panel.key.searchNext': string;
     'panel.key.searchPrev': string;
@@ -81,6 +84,20 @@ export declare const zh: {
     'row.added': string;
     'row.removed': string;
     'action.keep': string;
+    'action.comment': string;
+    'action.more': string;
+    'action.discussionExpand': string;
+    'action.discussionCollapse': string;
+    'discussion.placeholder': string;
+    'discussion.marker': string;
+    'discussion.promptRule': string;
+    'discussion.promptRuleSkill': string;
+    'discussion.thinking': string;
+    'discussion.queued': string;
+    'discussion.lost': string;
+    'discussion.hidden': string;
+    'discussion.failed': string;
+    'discussion.stopped': string;
     'action.revert': string;
     'action.delete': string;
     'action.keepAll': string;
@@ -243,6 +260,8 @@ export declare const en: {
     'panel.diffDelColor': string;
     'panel.diffDelColorDesc': string;
     'panel.quickSummon': string;
+    'panel.commentMode': string;
+    'panel.commentModeDesc': string;
     'panel.quickSummonDesc': string;
     'panel.recordShortcut': string;
     'settings.keybindings': string;
@@ -256,6 +275,7 @@ export declare const en: {
     'panel.key.jumpUp': string;
     'panel.key.jumpDown': string;
     'panel.key.copyRef': string;
+    'panel.key.addComment': string;
     'panel.key.openSearch': string;
     'panel.key.searchNext': string;
     'panel.key.searchPrev': string;
@@ -276,6 +296,20 @@ export declare const en: {
     'row.added': string;
     'row.removed': string;
     'action.keep': string;
+    'action.comment': string;
+    'action.more': string;
+    'action.discussionExpand': string;
+    'action.discussionCollapse': string;
+    'discussion.placeholder': string;
+    'discussion.marker': string;
+    'discussion.promptRule': string;
+    'discussion.promptRuleSkill': string;
+    'discussion.thinking': string;
+    'discussion.queued': string;
+    'discussion.lost': string;
+    'discussion.hidden': string;
+    'discussion.failed': string;
+    'discussion.stopped': string;
     'action.revert': string;
     'action.delete': string;
     'action.keepAll': string;

package/lib/types/client/scroll-follow.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Whether the follow animation can drive the frame, or the render has to place it.
+ *
+ * A scroller with nothing to scroll has an INACTIVE timeline. Measured in a browser: the
+ * animation reports a null current time and its transform is never applied at all, which
+ * left the frame wherever the render had put it — the wrapper's top edge, i.e. the top of
+ * the viewport — on a file short enough that the code does not scroll. There is nothing
+ * to follow in that case either, so the clamp at rest is already exact; the same holds
+ * before the box has been measured, and where the browser has no scroll timelines.
+ *
+ * @param hasTimeline - whether the browser supports scroll-driven animations.
+ * @param viewportHeight - the scroller's client height (0 before it is measured).
+ * @param maxScroll - the scroller's maximum `scrollTop` (0 when it does not scroll).
+ * @returns whether the animation, rather than the render, places the frame.
+ */
+export declare function frameFollowIsAnimated(hasTimeline: boolean, viewportHeight: number, maxScroll: number): boolean;
+/**
+ * The floating action frame's vertical position, as scroll-driven keyframes.
+ *
+ * The frame follows the row its anchor ends on — a point in the scroller's CONTENT
+ * coordinates — and is clamped into the visible area, so that it stays clickable when
+ * that row is off-screen. Written the direct way ("read `scrollTop`, subtract, clamp")
+ * it has to be recomputed on the main thread for every scroll event, which leaves it a
+ * frame behind the code the compositor has already moved. The same clamp expressed as
+ * keyframes over the scroll range becomes a scroll-driven animation, which the browser
+ * runs off the main thread: the code and the frame never disagree about the offset.
+ *
+ * The clamp is piecewise linear in the scroll offset, with exactly two corners — where
+ * the frame stops being held down by the viewport's bottom edge, and where it reaches
+ * the viewport's top edge and stays there — so listing those stops makes the animation
+ * reproduce it exactly, not approximately.
+ *
+ * @param anchorTop - the anchor's offset in the scroller's content, in px.
+ * @param maxScroll - the scroller's maximum `scrollTop` (0 when it does not scroll).
+ * @param viewportHeight - the scroller's client height, in px.
+ * @param frameHeight - the frame's own height, which the clamp has to keep on screen.
+ * @returns the keyframe stops: `offset` is the scroll progress (0-1) and `y` the frame's
+ *  position in px from the viewport's top. Ascending, deduplicated, and including the
+ *  corners; with nothing to scroll there is a single stop, the clamp being constant.
+ */
+export declare function frameFollowKeyframes(anchorTop: number, maxScroll: number, viewportHeight: number, frameHeight: number): {
+    offset: number;
+    y: number;
+}[];

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

@@ -198,6 +198,19 @@ export declare function setSplitMode(value: boolean): void;
 export declare function mdPreviewEnabled(): boolean;
 /** Persist the Markdown-preview default preference. */
 export declare function setMdPreviewEnabled(value: boolean): void;
+/**
+ * Whether commenting on a diff range is offered: the selection frame's comment button,
+ * and the chord that stands for it. Defaults to off while the mode is a preview (see
+ * {@link COMMENT_MODE_PREVIEW_KEY}); only an explicit `'1'` enables it. This gates
+ * STARTING a thread, not the threads themselves — one already written keeps rendering,
+ * so turning the mode off never hides work or interrupts an answer on its way back.
+ * @returns whether comment mode is on.
+ */
+export declare function commentModeEnabled(): boolean;
+/** Window event: comment mode was toggled (see {@link setCommentModeEnabled}). */
+export declare const COMMENT_MODE_CHANGED_EVENT = "diff-approval:comment-mode";
+/** Persist the comment-mode preference. */
+export declare function setCommentModeEnabled(value: boolean): void;
 /**
  * The Markdown-preview content max width, in pixels (single column). Defaults to
  * 800; the double-column view totals 2x this. An out-of-range or non-integer

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

@@ -2,6 +2,7 @@
 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';
 /** What the panel reads and drives: the pending list plus in-flight entries. */
 export interface PendingDiffSnapshot {
@@ -17,6 +18,12 @@ export interface PendingDiffSnapshot {
     failed?: ReadonlyMap<string, string> | undefined;
     /** The viewing session's workspace root (when it has one); enables workspace-relative references. */
     workspacePath?: string | undefined;
+    /**
+     * The answer-rules skill this host can deliver, or absent when it cannot (see the
+     * wire type). A comment prompt points at the skill when it is here, and carries the
+     * same rules inline when it is not.
+     */
+    commentSkill?: 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. */
@@ -62,6 +69,15 @@ 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. */

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

@@ -0,0 +1,39 @@
+/**
+ * The one skill this plugin offers the agent: how to answer a diff comment.
+ *
+ * The rules live here rather than in the system prompt. The harness's own `skill`
+ * tool advertises every registered skill's name and description as a context message
+ * and loads the body on demand, so the long form costs nothing until a comment is
+ * actually being answered — and nothing this plugin registers can leak into unrelated
+ * turns the way a global system-prompt section would.
+ *
+ * The comment prompt itself still carries the short version (see
+ * `discussion.promptRule` in `src/client/locales.ts`) and names this skill, so the
+ * behavior survives a build whose harness has no skill registry at all. The two are
+ * kept in step by a test in `tests/diff-approval.spec.ts`.
+ */
+/** The kebab-case name the comment prompt points the agent at. Prefixed with the whole
+ * package name: skill names share one flat namespace with no reverse-DNS scoping, so a
+ * short name like `diff-comment` is the kind of thing another plugin would also pick. */
+export declare const COMMENT_SKILL_NAME = "dsh-diff-approval-comment";
+/** Short routing line the skill catalog shows beside the name. */
+export declare const COMMENT_SKILL_DESCRIPTION: string;
+/** Extra routing guidance for the catalog. */
+export declare const COMMENT_SKILL_WHEN_TO_USE: string;
+/** The instruction body the agent loads, in the language its comments arrive in. */
+export declare const COMMENT_SKILL_CONTENT = "# \u56DE\u7B54\u4EE3\u7801\u6279\u6CE8\n\n\u6D88\u606F\u4EE5 `[\u8BC4\u8BBA] (path:lines)` \u5F00\u5934\u65F6\uFF0C\u5C31\u662F diff \u9762\u677F\u91CC\u5BF9\u90A3\u51E0\u884C\u4EE3\u7801\u63D0\u7684\u6279\u6CE8\u3002\u6309\u4E0B\u9762\u7684\u89C4\u5219\u56DE\u7B54\uFF1A\n\n- \u53EA\u8C08\u8FD9\u51E0\u884C\uFF08\u6700\u591A\u5E26\u4E0A\u76F4\u63A5\u76F8\u90BB\u7684\u4E00\u4E24\u884C\uFF09\uFF0C\u4E0D\u8981\u6269\u5230\u6574\u4E2A\u6587\u4EF6\u6216\u6574\u4E2A\u4EFB\u52A1\u3002\n- \u4E0D\u8D85\u8FC7 3 \u884C\u3002\n- \u884C\u4E0E\u884C\u4E4B\u95F4\u4E0D\u8981\u7A7A\u884C\uFF1A\u8BA8\u8BBA\u533A\u6309\u4EE3\u7801\u884C\u6392\u7248\uFF0C\u4E00\u4E2A\u7A7A\u884C\u5C31\u5360\u6389\u4E00\u6574\u884C\u9AD8\u5EA6\uFF0C\u770B\u8D77\u6765\u50CF\u4EE3\u7801\u91CC\u7684\u7A7A\u6D1E\u3002\n- \u8981\u5F15\u7528\u4EE3\u7801\u5C31\u5199 `\u6587\u4EF6:\u884C\u53F7`\uFF0C\u4E0D\u8981\u628A\u6574\u6BB5\u8D34\u56DE\u6765\u3002\n- \u56DE\u7B54\u76F4\u63A5\u663E\u793A\u5728\u6279\u6CE8\u4E0B\u65B9\u7684\u5C0F\u8BA8\u8BBA\u533A\u91CC\uFF0C\u6240\u4EE5\u4E0D\u8981\u5199\"\u5982\u4F60\u6240\u89C1\"\"\u4E0A\u9762\u63D0\u5230\"\u8FD9\u7C7B\u6307\u4EE3\u3002\n- \u4E0D\u786E\u5B9A\u5C31\u8BF4\u4E0D\u786E\u5B9A\uFF0C\u5E76\u8BF4\u6E05\u9700\u8981\u770B\u54EA\u4E00\u6BB5\u3002\n- 3 \u884C\u91CC\u8BF4\u4E0D\u6E05\uFF08\u8981\u5C55\u5F00\u3001\u8981\u770B\u66F4\u591A\u4EE3\u7801\u3001\u8981\u6765\u56DE\u51E0\u8F6E\uFF09\uFF0C\u5C31\u76F4\u8BF4\u4E00\u53E5\"\u8FD9\u6761\u5728\u6279\u6CE8\u91CC\u8BF4\u4E0D\u6E05\uFF0C\u53BB\u4E0B\u65B9\u53D1\u6D88\u606F\u7684\u8F93\u5165\u6846\u91CC\u804A\"\uFF0C\u4E0D\u8981\u5728\u6279\u6CE8\u91CC\u786C\u585E\u957F\u56DE\u7B54\u3002\n";
+/** One runtime skill contribution, in the shape `ctx.skills.register` takes. */
+export interface CommentSkillRegistration {
+    /** Kebab-case identity the agent loads by. */
+    readonly name: string;
+    /** Catalog routing line. */
+    readonly description: string;
+    /** Catalog routing guidance. */
+    readonly whenToUse: string;
+    /** Instruction body. */
+    readonly content: string;
+    /** Origin bucket: this plugin contributes it at runtime, not from disk. */
+    readonly source: 'runtime';
+}
+/** The contribution to register with the skill registry. */
+export declare const COMMENT_SKILL: CommentSkillRegistration;

package/lib/types/index.d.ts

@@ -50,6 +50,7 @@ export declare const name = "diff-approval";
 export declare const inject: string[];
 /** The connection RPC channel this plugin serves. */
 export declare const DIFF_APPROVAL_CHANNEL = "/diff-approval";
+export { COMMENT_SKILL_NAME } from './comment-skill.ts';
 /**
  * Plugin configuration overridable from the profile's `cordis.patch.yml`.
  */