@xynogen/pix-hunk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xynogen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @xynogen/pix-hunk
+
+Pi tool for driving a live [Hunk](https://github.com/modem-dev/hunk) diff review.
+One `hunk` call accepts ordered `ops[]`, so an agent can inspect, navigate,
+comment, highlight, and reload a review without repeated shell commands or
+quoting.
+
+## Requirements
+
+Install Hunk and launch its interactive TUI in another terminal. This extension
+only calls `hunk session *`; it never starts `hunk diff`, `show`, `patch`, or
+another interactive command.
+
+## Tool
+
+```ts
+hunk({
+  ops: [
+    { action: "review" },
+    { action: "navigate", file: "src/App.tsx", hunk: 2 },
+    {
+      action: "comment",
+      file: "src/App.tsx",
+      newLine: 42,
+      summary: "Handle the empty state",
+    },
+    { action: "comment_list", type: "user" },
+  ],
+});
+```
+
+Supported actions: `list`, `get`, `context`, `review`, `navigate`, `comment`,
+`comment_list`, `comment_rm`, `highlight`, `highlight_clear`, and `reload`.
+Operations execute in order and every result is returned, including failures.
+Hunk JSON is converted to compact model-facing records:
+
+```text
+review s1 Working tree
+  selected src/App.tsx:h2
+  src/App.tsx +12 -4
+    h1 old=10-14 new=10-18
+comment c17 src/App.tsx:new:42 h1
+comment_list
+note-81bc src/App.tsx:new:47 h2 @xynogen: Can this branch be removed?
+```
+
+IDs come directly from Hunk. Successful records omit redundant numbering and
+`ok`; failures use `action error: message`. TUI output auto-collapses to one
+colored summary row; expanded UI hides internal IDs and comment bodies while
+full model/audit data remains unchanged.
+
+Model-facing output defaults to 10,000 characters. Set `maxCharacters` between
+1,000 and 50,000 when more or less context is useful. Each operation receives a
+quota, so a large patch cannot hide later results. Full structured results
+remain available in tool details for inspection.
+
+## Install
+
+```bash
+pi install npm:@xynogen/pix-hunk
+```
+
+Standalone/opt-in: Hunk and a live local review session are required, so this
+package is not bundled by `@xynogen/pix-core`.
+
+## Scope ceiling
+
+`comment apply`, STML markup, and comment clearing are intentionally omitted.
+Use Hunk's CLI directly until repeated demand justifies extending the schema.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@xynogen/pix-hunk",
+	"version": "0.1.0",
+	"description": "Pi tool — drive live Hunk diff reviews with ordered bulk operations",
+	"type": "module",
+	"main": "src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"test": "bun test"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"src/index.ts"
+		]
+	},
+	"keywords": [
+		"pi",
+		"pi-package",
+		"pi-extension",
+		"hunk",
+		"code-review",
+		"diff"
+	],
+	"author": "xynogen",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/xynogen/pix-mono.git",
+		"directory": "packages/pix-hunk"
+	},
+	"homepage": "https://github.com/xynogen/pix-mono/tree/main/packages/pix-hunk#readme",
+	"bugs": {
+		"url": "https://github.com/xynogen/pix-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@xynogen/pix-pretty": "^1.19.0",
+		"@xynogen/pix-runtime": "^0.8.1",
+		"typebox": "^1.1.38"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	}
+}

package/src/index.test.ts

@@ -0,0 +1,413 @@
+import { expect, test } from "bun:test";
+import registerHunk, { type HunkRunner } from "./index.ts";
+
+type RenderTheme = {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+};
+
+type RenderContext = {
+	expanded: boolean;
+	isError: boolean;
+	state: Record<string, unknown>;
+	invalidate: () => void;
+};
+
+type ToolDef = {
+	renderShell?: "self";
+	renderCall: (
+		args: { ops: Array<Record<string, unknown>> },
+		theme: RenderTheme,
+		context: RenderContext,
+	) => { render: (width: number) => string[] };
+	renderResult: (
+		result: { content: Array<{ type: "text"; text: string }>; details: unknown },
+		options: { expanded: boolean; isPartial: boolean },
+		theme: RenderTheme,
+		context: RenderContext,
+	) => { render: (width: number) => string[] };
+	execute: (
+		id: string,
+		params: { ops: Array<Record<string, unknown>>; maxCharacters?: number },
+		signal: AbortSignal | undefined,
+		onUpdate: undefined,
+		ctx: { cwd: string },
+	) => Promise<{ content: Array<{ type: "text"; text: string }>; details: unknown }>;
+};
+
+const taggedTheme: RenderTheme = {
+	fg: (color, text) => `[${color}]${text}[/${color}]`,
+	bold: (text) => `[bold]${text}[/bold]`,
+};
+
+const renderContext = (expanded = false, collapsed = false): RenderContext => ({
+	expanded,
+	isError: false,
+	state: collapsed ? { collapsed: true } : {},
+	invalidate: () => {},
+});
+
+function rendered(component: { render: (width: number) => string[] }): string {
+	return component.render(240).join("\n");
+}
+
+function capture(runner: HunkRunner): ToolDef {
+	let tool: ToolDef | undefined;
+	const pi = {
+		registerTool(def: ToolDef) {
+			tool = def;
+		},
+	} as never;
+	registerHunk(pi, runner);
+	if (!tool) throw new Error("hunk tool not registered");
+	return tool;
+}
+
+test("renders a compact colored summary and hides internal ids from expanded UI", async () => {
+	let call = 0;
+	const runner: HunkRunner = async () => {
+		call++;
+		if (call === 1) {
+			return {
+				stdout: JSON.stringify({
+					result: { filePath: "src/a.ts", hunkIndex: 0, selectedHunk: { newRange: [10, 20] } },
+				}),
+				stderr: "",
+				code: 0,
+			};
+		}
+		return {
+			stdout: JSON.stringify({
+				result: {
+					commentId: "mcp:3681add-very-long-internal-id",
+					filePath: "src/a.ts",
+					hunkIndex: 0,
+					side: "new",
+					line: 13,
+				},
+			}),
+			stderr: "",
+			code: 0,
+		};
+	};
+	const tool = capture(runner);
+	const args = {
+		ops: [
+			{ action: "navigate", file: "src/a.ts", hunk: 1 },
+			{ action: "comment", file: "src/a.ts", newLine: 13, summary: "Long body hidden" },
+		],
+	};
+	const result = await tool.execute("render", args, undefined, undefined, { cwd: "/repo" });
+
+	expect(tool.renderShell).toBe("self");
+	expect(rendered(tool.renderCall(args, taggedTheme, renderContext()))).toContain(
+		"[toolTitle][bold]hunk[/bold][/toolTitle] [dim]navigate +1[/dim]",
+	);
+	const compactContext = renderContext(false, true);
+	expect(rendered(tool.renderCall(args, taggedTheme, compactContext))).toBe("");
+	const compact = rendered(
+		tool.renderResult(result, { expanded: false, isPartial: false }, taggedTheme, compactContext),
+	);
+	expect(compact).toContain("[toolTitle][bold]hunk[/bold][/toolTitle]");
+	expect(compact).toContain("[dim]navigate +1[/dim]");
+	expect(compact).toContain("[muted]2 ops · 1 comment[/muted]");
+	expect(compact).not.toContain("mcp:3681add");
+	expect(compact).not.toContain("─");
+
+	const expanded = rendered(
+		tool.renderResult(
+			result,
+			{ expanded: true, isPartial: false },
+			taggedTheme,
+			renderContext(true, true),
+		),
+	);
+	expect(expanded).toContain("[success]────────────────────────────────");
+	expect(expanded).toContain("[dim]src/a.ts:h1[/dim] [muted]· 1 comment[/muted]");
+	expect(expanded).not.toContain("[text]navigate");
+	expect(expanded).not.toContain("[text]comment");
+	expect(expanded).not.toContain("[toolTitle]navigate");
+	expect(expanded).not.toContain("[toolTitle]comment");
+	expect(expanded).not.toContain("src/a.ts:new:13");
+	expect(expanded).not.toContain("mcp:3681add");
+	expect(expanded).not.toContain("Long body hidden");
+
+	const partial = rendered(
+		tool.renderResult(
+			result,
+			{ expanded: true, isPartial: true },
+			taggedTheme,
+			renderContext(true, true),
+		),
+	);
+	expect(partial).not.toContain("─");
+
+	const failed = await capture(async () => ({
+		stdout: "",
+		stderr: "session gone",
+		code: 1,
+	})).execute("render-error", { ops: [{ action: "list" }] }, undefined, undefined, {
+		cwd: "/repo",
+	});
+	const failedExpanded = rendered(
+		tool.renderResult(
+			failed,
+			{ expanded: true, isPartial: false },
+			taggedTheme,
+			renderContext(true, true),
+		),
+	);
+	expect(failedExpanded).toContain("[error]────────────────────────────────");
+	expect(failedExpanded).toContain("[error]list: session gone[/error]");
+});
+
+test("executes bulk operations in order and returns every parsed result", async () => {
+	const calls: string[][] = [];
+	const runner: HunkRunner = async (args) => {
+		calls.push(args);
+		return calls.length === 1
+			? { stdout: '{"sessions":[]}', stderr: "", code: 0 }
+			: { stdout: "", stderr: "No active Hunk sessions", code: 1 };
+	};
+
+	const result = await capture(runner).execute(
+		"t1",
+		{ ops: [{ action: "list" }, { action: "review", repo: "/work" }] },
+		undefined,
+		undefined,
+		{ cwd: "/cwd" },
+	);
+
+	expect(calls).toEqual([
+		["session", "list", "--json"],
+		["session", "review", "--repo", "/work", "--json"],
+	]);
+	expect(result.content[0]?.text).toBe("list sessions=0\nreview error: No active Hunk sessions");
+	expect(result.details).toEqual({
+		_type: "hunkResult",
+		outcome: "error",
+		results: [
+			{ action: "list", ok: true, data: { sessions: [] } },
+			{ action: "review", ok: false, error: "No active Hunk sessions" },
+		],
+	});
+});
+
+test("summarizes review JSON as files and hunks instead of dumping it", async () => {
+	const runner: HunkRunner = async () => ({
+		stdout: JSON.stringify({
+			review: {
+				sessionId: "s1",
+				title: "Working tree",
+				selectedFile: { path: "src/a.ts" },
+				files: [
+					{
+						path: "src/a.ts",
+						additions: 5,
+						deletions: 2,
+						patch: "@@ -10,2 +10,3 @@\n-old\n+new",
+						hunks: [
+							{
+								index: 0,
+								header: "@@ -10,2 +10,3 @@",
+								oldRange: [10, 11],
+								newRange: [10, 12],
+							},
+						],
+					},
+				],
+			},
+		}),
+		stderr: "",
+		code: 0,
+	});
+	const result = await capture(runner).execute(
+		"t-review",
+		{ ops: [{ action: "review" }] },
+		undefined,
+		undefined,
+		{ cwd: "/repo" },
+	);
+
+	expect(result.content[0]?.text).toBe(
+		"review s1 Working tree\n" +
+			"  selected src/a.ts\n" +
+			"  src/a.ts +5 -2\n" +
+			"    h1 old=10-11 new=10-12\n" +
+			"    patch\n" +
+			"      @@ -10,2 +10,3 @@\n" +
+			"      -old\n" +
+			"      +new",
+	);
+	expect(result.content[0]?.text).not.toContain("sessionId");
+});
+
+test("returns exact comment ids and locations for follow-up actions", async () => {
+	let call = 0;
+	const runner: HunkRunner = async () => {
+		call++;
+		if (call === 1) {
+			return {
+				stdout: JSON.stringify({
+					result: {
+						commentId: "c17",
+						filePath: "src/a.ts",
+						hunkIndex: 0,
+						side: "new",
+						line: 12,
+					},
+				}),
+				stderr: "",
+				code: 0,
+			};
+		}
+		if (call === 2) {
+			return {
+				stdout: JSON.stringify({
+					comments: [
+						{
+							noteId: "note-81bc",
+							filePath: "src/a.ts",
+							hunkIndex: 0,
+							newRange: [13, 13],
+							author: "xynogen",
+							body: "Can this be simpler?",
+						},
+					],
+				}),
+				stderr: "",
+				code: 0,
+			};
+		}
+		return {
+			stdout: JSON.stringify({
+				result: { commentId: "c17", removed: true, remainingCommentCount: 1 },
+			}),
+			stderr: "",
+			code: 0,
+		};
+	};
+	const result = await capture(runner).execute(
+		"t-comments",
+		{
+			ops: [
+				{ action: "comment", file: "src/a.ts", newLine: 12, summary: "Fix this" },
+				{ action: "comment_list", type: "user" },
+				{ action: "comment_rm", commentId: "c17" },
+			],
+		},
+		undefined,
+		undefined,
+		{ cwd: "/repo" },
+	);
+
+	expect(result.content[0]?.text).toBe(
+		"comment c17 src/a.ts:new:12 h1\n" +
+			"comment_list\n" +
+			"note-81bc src/a.ts:new:13 h1 @xynogen: Can this be simpler?\n" +
+			"comment_rm c17 remaining=1",
+	);
+});
+
+test("budgets each operation so a large patch cannot hide later results", async () => {
+	let call = 0;
+	const runner: HunkRunner = async () => {
+		call++;
+		return call === 1
+			? {
+					stdout: JSON.stringify({
+						review: {
+							title: "Large review",
+							files: [
+								{
+									path: "src/large.ts",
+									additions: 1,
+									deletions: 0,
+									hunks: [],
+									patch: `+${"x".repeat(60_000)}`,
+								},
+							],
+						},
+					}),
+					stderr: "",
+					code: 0,
+				}
+			: {
+					stdout: JSON.stringify({
+						result: {
+							commentId: "c-final",
+							filePath: "src/final.ts",
+							hunkIndex: 2,
+							side: "new",
+							line: 44,
+						},
+					}),
+					stderr: "",
+					code: 0,
+				};
+	};
+	const result = await capture(runner).execute(
+		"t2",
+		{
+			ops: [
+				{ action: "review", includePatch: true },
+				{ action: "comment", file: "src/final.ts", newLine: 44, summary: "Fix" },
+			],
+		},
+		undefined,
+		undefined,
+		{ cwd: "/repo" },
+	);
+
+	expect(result.content[0]?.text.length).toBeLessThanOrEqual(10_000);
+	expect(result.content[0]?.text).toContain("review Large review");
+	expect(result.content[0]?.text).toContain("[truncated; full result in tool details]");
+	expect(result.content[0]?.text).toContain("comment c-final src/final.ts:new:44 h3");
+	expect(JSON.stringify(result.details).length).toBeGreaterThan(60_000);
+});
+
+test("allows a bounded model-output override", async () => {
+	const huge = JSON.stringify({
+		review: {
+			title: "Large review",
+			files: [
+				{
+					path: "src/large.ts",
+					additions: 1,
+					deletions: 0,
+					hunks: [],
+					patch: `+${"x".repeat(30_000)}`,
+				},
+			],
+		},
+	});
+	const runner: HunkRunner = async () => ({ stdout: huge, stderr: "", code: 0 });
+	const result = await capture(runner).execute(
+		"t-limit",
+		{ ops: [{ action: "review", includePatch: true }], maxCharacters: 20_000 },
+		undefined,
+		undefined,
+		{ cwd: "/repo" },
+	);
+
+	expect(result.content[0]?.text.length).toBeGreaterThan(10_500);
+	expect(result.content[0]?.text.length).toBeLessThanOrEqual(20_000);
+	expect(result.content[0]?.text).toContain("[truncated; full result in tool details]");
+});
+
+test("reports a missing Hunk executable clearly", async () => {
+	const runner: HunkRunner = async () => ({
+		stdout: "",
+		stderr: "spawn hunk ENOENT",
+		code: 1,
+	});
+	const result = await capture(runner).execute(
+		"t3",
+		{ ops: [{ action: "list" }] },
+		undefined,
+		undefined,
+		{ cwd: "/repo" },
+	);
+
+	expect(result.content[0]?.text).toContain("Hunk CLI not found");
+});

package/src/index.ts

@@ -0,0 +1,539 @@
+import { execFile } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+	dotJoin,
+	formatCollapsedToolRow,
+	frameToolResult,
+	hideCollapsedToolCall,
+} from "@xynogen/pix-pretty/utils";
+import { type CollapseState, tickCollapse } from "@xynogen/pix-runtime/collapse";
+import { Type } from "typebox";
+import {
+	buildHunkArgs,
+	type CommentType,
+	type HighlightTone,
+	type HunkAction,
+	type HunkOp,
+} from "./lib.ts";
+
+const MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+const DEFAULT_MODEL_CHARS = 10_000;
+
+export interface HunkRunResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+}
+
+export type HunkRunner = (args: string[], signal?: AbortSignal) => Promise<HunkRunResult>;
+
+export const runHunk: HunkRunner = (args, signal) =>
+	new Promise((resolve, reject) => {
+		execFile("hunk", args, { maxBuffer: MAX_OUTPUT_BYTES, signal }, (error, stdout, stderr) => {
+			if (error && signal?.aborted) {
+				reject(error);
+				return;
+			}
+			resolve({
+				stdout,
+				stderr: stderr || error?.message || "",
+				code: typeof error?.code === "number" ? error.code : error ? 1 : 0,
+			});
+		});
+	});
+
+type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+interface HunkOperationResult {
+	action: HunkAction;
+	ok: boolean;
+	data?: JsonValue;
+	error?: string;
+}
+
+interface HunkResultDetails {
+	_type: "hunkResult";
+	outcome: "success" | "error";
+	results: HunkOperationResult[];
+}
+
+type HunkTheme = {
+	fg: (color: string, text: string) => string;
+	bold: (text: string) => string;
+};
+
+function parseOutput(text: string): JsonValue {
+	const trimmed = text.trim();
+	if (!trimmed) return {};
+	try {
+		return JSON.parse(trimmed) as JsonValue;
+	} catch {
+		return trimmed;
+	}
+}
+
+const ActionSchema = Type.Enum(
+	[
+		"list",
+		"get",
+		"context",
+		"review",
+		"navigate",
+		"comment",
+		"comment_list",
+		"comment_rm",
+		"highlight",
+		"highlight_clear",
+		"reload",
+	] as const,
+	{ type: "string" },
+);
+
+const OpSchema = Type.Object({
+	action: ActionSchema,
+	repo: Type.Optional(Type.String({ description: "Session repo root (default: cwd)." })),
+	sessionId: Type.Optional(Type.String({ description: "Exact session id." })),
+	file: Type.Optional(Type.String({ description: "File path within the review." })),
+	hunk: Type.Optional(Type.Integer({ minimum: 1, description: "1-based hunk index." })),
+	newLine: Type.Optional(Type.Integer({ minimum: 1, description: "1-based new-side line." })),
+	oldLine: Type.Optional(Type.Integer({ minimum: 1, description: "1-based old-side line." })),
+	summary: Type.Optional(Type.String({ description: "Inline comment summary." })),
+	rationale: Type.Optional(Type.String({ description: "Inline comment rationale." })),
+	commentId: Type.Optional(Type.String({ description: "Comment id to remove." })),
+	type: Type.Optional(
+		Type.Enum(["live", "all", "ai", "agent", "user"] as const, {
+			type: "string",
+			description: "Comment-list filter.",
+		}),
+	),
+	start: Type.Optional(Type.Integer({ minimum: 0, description: "Highlight start offset." })),
+	end: Type.Optional(Type.Integer({ minimum: 1, description: "Highlight end offset." })),
+	tone: Type.Optional(
+		Type.Enum(["match", "info", "warning", "error", "current"] as const, {
+			type: "string",
+		}),
+	),
+	nextComment: Type.Optional(Type.Boolean()),
+	prevComment: Type.Optional(Type.Boolean()),
+	includePatch: Type.Optional(Type.Boolean()),
+	focus: Type.Optional(Type.Boolean()),
+	reloadArgs: Type.Optional(
+		Type.Array(Type.String(), { description: 'Reload command, e.g. ["diff","main...HEAD"].' }),
+	),
+});
+
+type ToolOp = HunkOp & { type?: CommentType; tone?: HighlightTone };
+
+type JsonObject = { [key: string]: JsonValue };
+
+function object(value: JsonValue | undefined): JsonObject | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+
+function string(value: JsonValue | undefined): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function number(value: JsonValue | undefined): number | undefined {
+	return typeof value === "number" ? value : undefined;
+}
+
+function array(value: JsonValue | undefined): JsonValue[] {
+	return Array.isArray(value) ? value : [];
+}
+
+function range(value: JsonValue | undefined): string | undefined {
+	const values = array(value);
+	const start = number(values[0]);
+	const end = number(values[1]);
+	return start !== undefined && end !== undefined ? `${start}-${end}` : undefined;
+}
+
+function boolean(value: JsonValue | undefined): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+
+function inline(value: string | undefined, fallback = "-"): string {
+	return value?.replace(/\s+/g, " ").trim() || fallback;
+}
+
+function selection(file: string | undefined, hunk: number | undefined): string {
+	return file ? `${inline(file)}${hunk === undefined ? "" : `:h${hunk + 1}`}` : "none";
+}
+
+function ranges(value: JsonObject | undefined): string {
+	const oldRange = range(value?.oldRange);
+	const newRange = range(value?.newRange);
+	return [oldRange && `old=${oldRange}`, newRange && `new=${newRange}`].filter(Boolean).join(" ");
+}
+
+function formatList(data: JsonObject): string[] {
+	const sessions = array(data.sessions);
+	if (sessions.length === 0) return ["list sessions=0"];
+	const lines = ["list"];
+	for (const rawSession of sessions) {
+		const session = object(rawSession);
+		if (!session) continue;
+		const state = object(object(object(session.snapshot)?.state));
+		const selected = selection(string(state?.selectedFilePath), number(state?.selectedHunkIndex));
+		lines.push(
+			`  ${inline(string(session.sessionId))} ${inline(string(session.title), "")}`.trimEnd(),
+			`    repo=${inline(string(session.repoRoot) ?? string(session.cwd))} selected=${selected} files=${number(session.fileCount) ?? array(session.files).length} comments=${number(state?.liveCommentCount) ?? 0}`,
+		);
+	}
+	return lines;
+}
+
+function formatGet(data: JsonObject): string[] {
+	const session = object(data.session) ?? data;
+	const state = object(object(object(session.snapshot)?.state));
+	return [
+		`get ${inline(string(session.sessionId))} ${inline(string(session.title), "")}`.trimEnd(),
+		`  cwd=${inline(string(session.cwd))} repo=${inline(string(session.repoRoot))} source=${inline(string(session.sourceLabel))}`,
+		`  selected ${selection(string(state?.selectedFilePath), number(state?.selectedHunkIndex))}`,
+	];
+}
+
+function formatContext(data: JsonObject): string[] {
+	const context = object(data.context) ?? data;
+	const selectedFile = object(context.selectedFile);
+	const selectedHunk = object(context.selectedHunk);
+	const detail = ranges(selectedHunk);
+	return [
+		`context ${inline(string(context.sessionId))} ${inline(string(context.title), "")}`.trimEnd(),
+		`  selected ${selection(string(selectedFile?.path), number(selectedHunk?.index))}${detail ? ` ${detail}` : ""} comments=${number(context.liveCommentCount) ?? 0}`,
+	];
+}
+
+function formatReview(data: JsonObject): string[] {
+	const review = object(data.review) ?? data;
+	const selectedFile = object(review.selectedFile);
+	const selectedHunk = object(review.selectedHunk);
+	const sessionId = string(review.sessionId);
+	const lines = [
+		`review${sessionId ? ` ${inline(sessionId)}` : ""} ${inline(string(review.title), "live review")}`,
+		`  selected ${selection(string(selectedFile?.path), number(selectedHunk?.index))}`,
+	];
+	for (const rawFile of array(review.files)) {
+		const file = object(rawFile);
+		if (!file) continue;
+		lines.push(
+			`  ${inline(string(file.path), "(unknown file)")} +${number(file.additions) ?? 0} -${number(file.deletions) ?? 0}`,
+		);
+		for (const rawHunk of array(file.hunks)) {
+			const hunk = object(rawHunk);
+			if (!hunk) continue;
+			const detail = ranges(hunk);
+			lines.push(`    h${(number(hunk.index) ?? 0) + 1}${detail ? ` ${detail}` : ""}`);
+		}
+		const patch = string(file.patch);
+		if (patch) lines.push("    patch", ...patch.split("\n").map((line) => `      ${line}`));
+	}
+	return lines;
+}
+
+function target(result: JsonObject): string {
+	const file = inline(string(result.filePath), "(unknown file)");
+	const side = string(result.side);
+	const line = number(result.line);
+	const location = side && line !== undefined ? `${file}:${side}:${line}` : file;
+	const hunk = number(result.hunkIndex);
+	return `${location}${hunk === undefined ? "" : ` h${hunk + 1}`}`;
+}
+
+function formatComment(data: JsonObject): string[] {
+	const result = object(data.result) ?? data;
+	return [`comment ${inline(string(result.commentId))} ${target(result)}`];
+}
+
+function noteTarget(comment: JsonObject): string {
+	const file = inline(string(comment.filePath), "(unknown file)");
+	const hunk = number(comment.hunkIndex);
+	const suffix = hunk === undefined ? "" : ` h${hunk + 1}`;
+	const oldRange = array(comment.oldRange);
+	const newRange = array(comment.newRange);
+	const oldStart = number(oldRange[0]);
+	const oldEnd = number(oldRange[1]);
+	const newStart = number(newRange[0]);
+	const newEnd = number(newRange[1]);
+	if (newStart !== undefined && newStart === newEnd && oldStart === undefined) {
+		return `${file}:new:${newStart}${suffix}`;
+	}
+	if (oldStart !== undefined && oldStart === oldEnd && newStart === undefined) {
+		return `${file}:old:${oldStart}${suffix}`;
+	}
+	const detail = ranges(comment);
+	return `${file}${suffix}${detail ? ` ${detail}` : ""}`;
+}
+
+function formatCommentList(data: JsonObject): string[] {
+	const comments = array(data.comments);
+	if (comments.length === 0) return ["comment_list none"];
+	const lines = ["comment_list"];
+	for (const rawComment of comments) {
+		const comment = object(rawComment);
+		if (!comment) continue;
+		const id = inline(string(comment.commentId) ?? string(comment.noteId));
+		const detail = target(comment);
+		const location = string(comment.side) ? detail : noteTarget(comment);
+		const author = string(comment.author);
+		const body = string(comment.summary) ?? string(comment.body) ?? "";
+		const prefix = `${id} ${location}${author ? ` @${inline(author)}` : ""}:`;
+		const bodyLines = body.split(/\r?\n/);
+		lines.push(`${prefix} ${bodyLines[0] ?? ""}`.trimEnd());
+		lines.push(...bodyLines.slice(1).map((line) => `  ${line}`));
+	}
+	return lines;
+}
+
+function formatResultAction(action: HunkAction, data: JsonObject, op: ToolOp): string[] {
+	const result = object(data.result) ?? data;
+	switch (action) {
+		case "list":
+			return formatList(data);
+		case "get":
+			return formatGet(data);
+		case "context":
+			return formatContext(data);
+		case "review":
+			return formatReview(data);
+		case "navigate": {
+			const detail = ranges(object(result.selectedHunk));
+			return [
+				`navigate ${selection(string(result.filePath), number(result.hunkIndex))}${detail ? ` ${detail}` : ""}`,
+			];
+		}
+		case "comment":
+			return formatComment(data);
+		case "comment_list":
+			return formatCommentList(data);
+		case "comment_rm":
+			return [
+				`comment_rm ${inline(string(result.commentId) ?? op.commentId)}${boolean(result.removed) === false ? " removed=false" : ""} remaining=${number(result.remainingCommentCount) ?? "-"}`,
+			];
+		case "highlight": {
+			const side = op.newLine === undefined ? "old" : "new";
+			const line = op.newLine ?? op.oldLine;
+			return [
+				`highlight ${inline(op.file)}:${side}:${line ?? "-"} chars=${op.start}-${op.end}${op.tone ? ` tone=${op.tone}` : ""}${op.focus ? " focus" : ""}`,
+			];
+		}
+		case "highlight_clear":
+			return [`highlight_clear ${op.file ? inline(op.file) : "session"}`];
+		case "reload":
+			return [
+				`reload ${inline(string(result.title))} files=${number(result.fileCount) ?? 0} selected=${selection(string(result.selectedFilePath), number(result.selectedHunkIndex))}`,
+			];
+	}
+}
+
+function formatOperation(result: HunkOperationResult, op: ToolOp): string {
+	if (!result.ok) return `${result.action} error: ${result.error ?? "failed"}`;
+	const data = object(result.data);
+	return data
+		? formatResultAction(result.action, data, op).join("\n")
+		: `${result.action} complete`;
+}
+
+function truncateRecord(text: string, limit: number): string {
+	if (text.length <= limit) return text;
+	const marker = "\n  [truncated; full result in tool details]";
+	const header = text.split("\n", 1)[0] ?? text;
+	if (header.length + marker.length > limit) return header.slice(0, limit);
+	return `${text.slice(0, limit - marker.length).trimEnd()}${marker}`;
+}
+
+function modelText(results: HunkOperationResult[], ops: ToolOp[], maxCharacters: number): string {
+	const separators = Math.max(0, results.length - 1);
+	const available = maxCharacters - separators;
+	const quota = Math.floor(available / results.length);
+	let remainder = available % results.length;
+	return results
+		.map((result, index) => {
+			const limit = quota + (remainder-- > 0 ? 1 : 0);
+			return truncateRecord(
+				formatOperation(result, ops[index] ?? { action: result.action }),
+				limit,
+			);
+		})
+		.join("\n");
+}
+
+function executionError(run: HunkRunResult): string {
+	const raw = (run.stderr || run.stdout || `hunk exited ${run.code}`).trim();
+	return /(?:^|\s)(?:spawn\s+)?hunk\s+ENOENT(?:\s|$)/i.test(raw)
+		? "Hunk CLI not found. Install Hunk, launch a review session, then retry."
+		: raw;
+}
+
+function actionSummary(actions: HunkAction[]): string {
+	if (actions.length === 0) return "empty";
+	return `${actions[0]}${actions.length > 1 ? ` +${actions.length - 1}` : ""}`;
+}
+
+function listedCommentCount(result: HunkOperationResult): number | undefined {
+	if (result.action !== "comment_list" || !result.ok) return undefined;
+	return array(object(result.data)?.comments).length;
+}
+
+function commentCount(results: HunkOperationResult[]): number {
+	const listed = results.map(listedCommentCount).find((count) => count !== undefined);
+	return listed ?? results.filter((result) => result.action === "comment" && result.ok).length;
+}
+
+function renderSummary(details: HunkResultDetails, theme: HunkTheme): string {
+	const actions = details.results.map((result) => result.action);
+	const comments = commentCount(details.results);
+	const meta = dotJoin([
+		`${details.results.length} ops`,
+		comments > 0 && `${comments} comment${comments === 1 ? "" : "s"}`,
+	]);
+	return formatCollapsedToolRow(
+		theme,
+		"hunk",
+		actionSummary(actions),
+		meta,
+		details.outcome === "error" ? "error" : "success",
+	);
+}
+
+function resultTarget(result: HunkOperationResult): string {
+	const data = object(result.data);
+	const value = object(data?.result) ?? data;
+	if (!value) return result.ok ? "complete" : (result.error ?? "failed");
+	if (result.action === "comment_list") {
+		const count = array(data?.comments).length;
+		return count === 0 ? "none" : `${count} comment${count === 1 ? "" : "s"}`;
+	}
+	if (result.action === "list") return `sessions=${array(data?.sessions).length}`;
+	if (result.action === "comment_rm") {
+		return `remaining=${number(value.remainingCommentCount) ?? "-"}`;
+	}
+	const file = string(value.filePath) ?? string(object(value.selectedFile)?.path);
+	const hunk = number(value.hunkIndex) ?? number(object(value.selectedHunk)?.index);
+	const side = string(value.side);
+	const line = number(value.line);
+	if (file && side && line !== undefined) {
+		return `${file}:${side}:${line}${hunk === undefined ? "" : ` h${hunk + 1}`}`;
+	}
+	if (file) return selection(file, hunk);
+	return "complete";
+}
+
+function renderExpanded(details: HunkResultDetails, theme: HunkTheme): string {
+	const targetResult =
+		details.results.find((result) => result.ok && result.action === "navigate") ??
+		details.results.find(
+			(result) => result.ok && !["comment_list", "comment_rm"].includes(result.action),
+		);
+	const target = targetResult ? resultTarget(targetResult) : "complete";
+	const comments = commentCount(details.results);
+	const meta = comments > 0 ? `${comments} comment${comments === 1 ? "" : "s"}` : "";
+	const summary = `${theme.fg("dim", target)}${meta ? ` ${theme.fg("muted", `· ${meta}`)}` : ""}`;
+	const errors = details.results
+		.filter((result) => !result.ok)
+		.map((result) => theme.fg("error", `${result.action}: ${result.error ?? "failed"}`));
+	return [summary, ...errors].join("\n");
+}
+
+export default function registerHunk(pi: ExtensionAPI, runner: HunkRunner = runHunk): void {
+	pi.registerTool({
+		name: "hunk",
+		label: "Hunk",
+		renderShell: "self",
+		description:
+			"Drive a live Hunk diff review through `hunk session *`. Runs ordered `ops` in one call and returns every result. Supports inspection, navigation, comments, highlights, and reload. Never launches the interactive TUI.",
+		promptSnippet: "Drive a live Hunk diff review with an ordered batch of session operations",
+		promptGuidelines: [
+			"hunk: start with `review` (raw patch only via `includePatch:true`); use `navigate`, `comment`, and `highlight` to guide the live review. If no session exists, ask the user to launch Hunk.",
+		],
+		parameters: Type.Object({
+			ops: Type.Array(OpSchema, {
+				minItems: 1,
+				maxItems: 20,
+				description: "Operations executed in order; all results are returned.",
+			}),
+			maxCharacters: Type.Optional(
+				Type.Integer({
+					minimum: 1_000,
+					maximum: 50_000,
+					description: "Maximum model-facing result characters (default 10000).",
+				}),
+			),
+		}),
+		renderCall(args, theme, context) {
+			const text = new Text("", 0, 0);
+			if (
+				hideCollapsedToolCall(context.state as CollapseState, context.expanded, (value) =>
+					text.setText(value),
+				)
+			)
+				return text;
+			const actions = ((args as { ops?: ToolOp[] }).ops ?? []).map((op) => op.action);
+			text.setText(
+				`${theme.fg("toolTitle", theme.bold("hunk"))} ${theme.fg("dim", actionSummary(actions))}`,
+			);
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			const text = new Text("", 0, 0);
+			const details = result.details as HunkResultDetails | undefined;
+			if (!details) {
+				text.setText(
+					result.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n"),
+				);
+				return text;
+			}
+			const collapsed = tickCollapse(
+				"hunk",
+				context.state as CollapseState,
+				context.invalidate,
+				options.expanded,
+			);
+			if (collapsed) {
+				text.setText(renderSummary(details, theme as HunkTheme));
+				return text;
+			}
+			text.setText(renderExpanded(details, theme as HunkTheme));
+			return options.isPartial
+				? text
+				: frameToolResult(text, theme, context.isError || details.outcome === "error");
+		},
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const ops = params.ops as ToolOp[];
+			const results: HunkOperationResult[] = [];
+			for (const op of ops) {
+				try {
+					const run = await runner(buildHunkArgs(op, ctx.cwd), signal);
+					results.push(
+						run.code === 0
+							? { action: op.action, ok: true, data: parseOutput(run.stdout || run.stderr) }
+							: { action: op.action, ok: false, error: executionError(run) },
+					);
+				} catch (error) {
+					if (signal?.aborted) throw error;
+					results.push({
+						action: op.action,
+						ok: false,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}
+			const details: HunkResultDetails = {
+				_type: "hunkResult",
+				outcome: results.every((result) => result.ok) ? "success" : "error",
+				results,
+			};
+			return {
+				content: [
+					{
+						type: "text" as const,
+						text: modelText(results, ops, params.maxCharacters ?? DEFAULT_MODEL_CHARS),
+					},
+				],
+				details,
+			};
+		},
+	});
+}

package/src/lib.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import { buildHunkArgs, type HunkOp } from "./lib.ts";
+
+describe("buildHunkArgs", () => {
+	test("lists sessions as JSON", () => {
+		expect(buildHunkArgs({ action: "list" }, "/repo")).toEqual(["session", "list", "--json"]);
+	});
+
+	test("builds documented argv for every review operation", () => {
+		const cases: Array<[HunkOp, string[]]> = [
+			[{ action: "get" as const }, ["session", "get", "--repo", "/repo", "--json"]],
+			[{ action: "context" as const, sessionId: "s1" }, ["session", "context", "s1", "--json"]],
+			[
+				{ action: "review" as const, includePatch: true },
+				["session", "review", "--repo", "/repo", "--include-patch", "--json"],
+			],
+			[
+				{ action: "navigate" as const, file: "src/a.ts", hunk: 2 },
+				["session", "navigate", "--repo", "/repo", "--file", "src/a.ts", "--hunk", "2", "--json"],
+			],
+			[
+				{ action: "navigate" as const, nextComment: true },
+				["session", "navigate", "--repo", "/repo", "--next-comment", "--json"],
+			],
+			[
+				{
+					action: "comment" as const,
+					file: "src/a.ts",
+					newLine: 42,
+					summary: "Fix this",
+					rationale: "It breaks",
+					focus: true,
+				},
+				[
+					"session",
+					"comment",
+					"add",
+					"--repo",
+					"/repo",
+					"--file",
+					"src/a.ts",
+					"--new-line",
+					"42",
+					"--summary",
+					"Fix this",
+					"--rationale",
+					"It breaks",
+					"--focus",
+					"--json",
+				],
+			],
+			[
+				{ action: "comment_list" as const, file: "src/a.ts", type: "user" as const },
+				[
+					"session",
+					"comment",
+					"list",
+					"--repo",
+					"/repo",
+					"--file",
+					"src/a.ts",
+					"--type",
+					"user",
+					"--json",
+				],
+			],
+			[
+				{ action: "comment_rm" as const, commentId: "c1" },
+				["session", "comment", "rm", "--repo", "/repo", "c1", "--json"],
+			],
+			[
+				{
+					action: "highlight" as const,
+					file: "src/a.ts",
+					oldLine: 9,
+					start: 1,
+					end: 4,
+					tone: "warning" as const,
+				},
+				[
+					"session",
+					"highlight",
+					"add",
+					"--repo",
+					"/repo",
+					"--file",
+					"src/a.ts",
+					"--old-line",
+					"9",
+					"--start",
+					"1",
+					"--end",
+					"4",
+					"--tone",
+					"warning",
+					"--json",
+				],
+			],
+			[
+				{ action: "highlight_clear" as const, file: "src/a.ts" },
+				["session", "highlight", "clear", "--repo", "/repo", "--file", "src/a.ts", "--json"],
+			],
+			[
+				{ action: "reload" as const, reloadArgs: ["diff", "main...HEAD", "--", "src"] },
+				[
+					"session",
+					"reload",
+					"--repo",
+					"/repo",
+					"--json",
+					"--",
+					"diff",
+					"main...HEAD",
+					"--",
+					"src",
+				],
+			],
+		];
+
+		for (const [op, expected] of cases) {
+			expect(buildHunkArgs(op, "/repo")).toEqual(expected);
+		}
+	});
+
+	test("rejects invalid action fields before execution", () => {
+		const invalid = [
+			[{ action: "navigate" as const, file: "a.ts" }, "navigation target"],
+			[
+				{ action: "navigate" as const, nextComment: true, prevComment: true },
+				"one comment direction",
+			],
+			[{ action: "comment" as const, file: "a.ts", newLine: 1 }, "summary"],
+			[
+				{ action: "highlight" as const, file: "a.ts", newLine: 1, start: 4, end: 4 },
+				"greater than start",
+			],
+			[{ action: "comment_rm" as const }, "commentId"],
+		] as const;
+
+		for (const [op, message] of invalid) {
+			expect(() => buildHunkArgs(op, "/repo")).toThrow(message);
+		}
+	});
+});

package/src/lib.ts

@@ -0,0 +1,142 @@
+export type HunkAction =
+	| "list"
+	| "get"
+	| "context"
+	| "review"
+	| "navigate"
+	| "comment"
+	| "comment_list"
+	| "comment_rm"
+	| "highlight"
+	| "highlight_clear"
+	| "reload";
+
+export type CommentType = "live" | "all" | "ai" | "agent" | "user";
+export type HighlightTone = "match" | "info" | "warning" | "error" | "current";
+
+export interface HunkOp {
+	action: HunkAction;
+	repo?: string;
+	sessionId?: string;
+	file?: string;
+	hunk?: number;
+	newLine?: number;
+	oldLine?: number;
+	summary?: string;
+	rationale?: string;
+	commentId?: string;
+	type?: CommentType;
+	start?: number;
+	end?: number;
+	tone?: HighlightTone;
+	nextComment?: boolean;
+	prevComment?: boolean;
+	includePatch?: boolean;
+	focus?: boolean;
+	reloadArgs?: string[];
+}
+
+function selector(op: HunkOp, cwd: string): string[] {
+	return op.sessionId ? [op.sessionId] : ["--repo", op.repo ?? cwd];
+}
+
+function lineTarget(op: HunkOp): string[] {
+	if (op.newLine !== undefined) return ["--new-line", String(op.newLine)];
+	if (op.oldLine !== undefined) return ["--old-line", String(op.oldLine)];
+	return [];
+}
+
+function hasOneLineTarget(op: HunkOp): boolean {
+	return (op.newLine !== undefined ? 1 : 0) + (op.oldLine !== undefined ? 1 : 0) === 1;
+}
+
+function validateOp(op: HunkOp): void {
+	if (op.action === "navigate") {
+		const directions = (op.nextComment ? 1 : 0) + (op.prevComment ? 1 : 0);
+		if (directions > 1) throw new Error("navigate accepts one comment direction");
+		const absoluteTargets =
+			(op.hunk !== undefined ? 1 : 0) +
+			(op.newLine !== undefined ? 1 : 0) +
+			(op.oldLine !== undefined ? 1 : 0);
+		if (directions === 0 && (!op.file || absoluteTargets !== 1)) {
+			throw new Error("navigate requires file and exactly one navigation target");
+		}
+	}
+	if (op.action === "comment" && (!op.file || !op.summary || !hasOneLineTarget(op))) {
+		throw new Error("comment requires file, summary, and exactly one line target");
+	}
+	if (op.action === "comment_rm" && !op.commentId) {
+		throw new Error("comment_rm requires commentId");
+	}
+	if (op.action === "highlight") {
+		if (!op.file || !hasOneLineTarget(op) || op.start === undefined || op.end === undefined) {
+			throw new Error("highlight requires file, one line target, start, and end");
+		}
+		if (op.end <= op.start) throw new Error("highlight end must be greater than start");
+	}
+}
+
+export function buildHunkArgs(op: HunkOp, cwd: string): string[] {
+	validateOp(op);
+	const args = ["session"];
+
+	switch (op.action) {
+		case "list":
+			args.push("list");
+			break;
+		case "get":
+		case "context":
+			args.push(op.action, ...selector(op, cwd));
+			break;
+		case "review":
+			args.push("review", ...selector(op, cwd));
+			if (op.includePatch) args.push("--include-patch");
+			break;
+		case "navigate":
+			args.push("navigate", ...selector(op, cwd));
+			if (op.nextComment) args.push("--next-comment");
+			else if (op.prevComment) args.push("--prev-comment");
+			else {
+				if (op.file) args.push("--file", op.file);
+				if (op.hunk !== undefined) args.push("--hunk", String(op.hunk));
+				else args.push(...lineTarget(op));
+			}
+			break;
+		case "comment":
+			args.push("comment", "add", ...selector(op, cwd));
+			if (op.file) args.push("--file", op.file);
+			args.push(...lineTarget(op));
+			if (op.summary) args.push("--summary", op.summary);
+			if (op.rationale) args.push("--rationale", op.rationale);
+			if (op.focus) args.push("--focus");
+			break;
+		case "comment_list":
+			args.push("comment", "list", ...selector(op, cwd));
+			if (op.file) args.push("--file", op.file);
+			if (op.type) args.push("--type", op.type);
+			break;
+		case "comment_rm":
+			args.push("comment", "rm", ...selector(op, cwd));
+			if (op.commentId) args.push(op.commentId);
+			break;
+		case "highlight":
+			args.push("highlight", "add", ...selector(op, cwd));
+			if (op.file) args.push("--file", op.file);
+			args.push(...lineTarget(op));
+			if (op.start !== undefined) args.push("--start", String(op.start));
+			if (op.end !== undefined) args.push("--end", String(op.end));
+			if (op.tone) args.push("--tone", op.tone);
+			if (op.focus) args.push("--focus");
+			break;
+		case "highlight_clear":
+			args.push("highlight", "clear", ...selector(op, cwd));
+			if (op.file) args.push("--file", op.file);
+			break;
+		case "reload":
+			args.push("reload", ...selector(op, cwd), "--json", "--", ...(op.reloadArgs ?? ["diff"]));
+			return args;
+	}
+
+	args.push("--json");
+	return args;
+}