@namzu/sdk 52.6.2 → 52.7.0

package/src/tools/builtins/file-write-result.ts

@@ -1,12 +1,14 @@
 import { createHash } from 'node:crypto'
-import type { ToolResult } from '../../types/tool/index.js'
+import type { ToolDiffHunk, ToolResult } from '../../types/tool/index.js'
+import { lineDiff } from './line-diff.js'
 
-/** A final newline terminates a line; it does not add an empty line. */
-function lines(text: string): string[] {
-	if (text === '') return []
-	const result = text.split('\n')
-	if (result.at(-1) === '') result.pop()
-	return result
+/** One side of a change, context included: the rows that exist before (`-`) or after (`+`). */
+function previewSide(hunks: readonly ToolDiffHunk[], changed: '+' | '-'): string {
+	return hunks
+		.flatMap((hunk) => hunk.lines)
+		.filter((row) => row.startsWith(' ') || row.startsWith(changed))
+		.map((row) => `${row.slice(1)}\n`)
+		.join('')
 }
 
 /** null means the backend could not establish the previous state. */
@@ -24,26 +26,10 @@ export function fileWriteResult(
 				: before === after
 					? 'unchanged'
 					: 'replace'
-	const oldLines = lines(before ?? '')
-	const newLines = lines(after)
-	let start = 0
-	let end = 0
-	if (typeof before === 'string') {
-		while (
-			start < oldLines.length &&
-			start < newLines.length &&
-			oldLines[start] === newLines[start]
-		)
-			start++
-		while (
-			end < oldLines.length - start &&
-			end < newLines.length - start &&
-			oldLines[oldLines.length - end - 1] === newLines[newLines.length - end - 1]
-		)
-			end++
-	}
-	const removed = oldLines.slice(start, oldLines.length - end)
-	const added = newLines.slice(start, newLines.length - end)
+	// Counted from a real line diff of the whole file, not from the span
+	// between the first and last changed line.
+	const diff = lineDiff(typeof before === 'string' ? before : '', after)
+	const known = before !== null
 	const bytes = Buffer.byteLength(after, 'utf8')
 	const label =
 		operation === 'create'
@@ -55,7 +41,7 @@ export function fileWriteResult(
 					: 'Wrote'
 	const newlineChanged =
 		typeof before === 'string' && before.endsWith('\n') !== after.endsWith('\n')
-	const summary = `${label} ${path}${before === null ? '' : ` (+${added.length} -${removed.length})`}${newlineChanged ? ' · final newline changed' : ''}`
+	const summary = `${label} ${path}${before === null ? '' : ` (+${diff.added} -${diff.removed})`}${newlineChanged ? ' · final newline changed' : ''}`
 	return {
 		success: true,
 		output: `${summary} · ${bytes} bytes`,
@@ -71,7 +57,14 @@ export function fileWriteResult(
 							? 'unchanged'
 							: 'wrote',
 			bytes,
-			...(before === null ? {} : { added: added.length, removed: removed.length }),
+			...(known
+				? {
+						added: diff.added,
+						removed: diff.removed,
+						...(diff.hunks.length > 0 ? { hunks: diff.hunks } : {}),
+						...(diff.truncated ? { hunksTruncated: true as const } : {}),
+					}
+				: {}),
 		},
 		data: {
 			path,
@@ -83,15 +76,13 @@ export function fileWriteResult(
 					? {}
 					: {
 							preview: {
-								before: removed.length ? `${removed.join('\n')}\n` : '',
-								after: added.length ? `${added.join('\n')}\n` : '',
+								before: previewSide(diff.hunks, '-'),
+								after: previewSide(diff.hunks, '+'),
 							},
 						}),
 				bytes,
 				sha256: createHash('sha256').update(after, 'utf8').digest('hex'),
-				...(before === null
-					? {}
-					: { added: added.length, removed: removed.length, newlineChanged }),
+				...(before === null ? {} : { added: diff.added, removed: diff.removed, newlineChanged }),
 			},
 		},
 	}

package/src/tools/builtins/line-diff.ts

@@ -0,0 +1,122 @@
+import { structuredPatch } from 'diff'
+import type { ToolDiffHunk } from '../../types/tool/presentation.js'
+
+/** Lines of unchanged text kept around each change, as `git diff` does. */
+const CONTEXT_LINES = 3
+/** A diff that takes longer than this is abandoned for the coarse count below. */
+const DIFF_TIMEOUT_MS = 5000
+/** Most hunk rows a result carries; the counts always cover the whole change. */
+export const MAX_CARRIED_DIFF_LINES = 400
+/** A single carried row is cut here so one minified line cannot bloat an event. */
+const MAX_CARRIED_LINE_CHARS = 500
+
+export interface LineDiff {
+	/** Lines added and removed, counted from the hunks of a real line diff. */
+	readonly added: number
+	readonly removed: number
+	/** Hunks with three lines of context; rows are ` `, `+` or `-` followed by the line. */
+	readonly hunks: readonly ToolDiffHunk[]
+	/** Rows were left out of `hunks` to keep the result small. */
+	readonly truncated: boolean
+}
+
+/** Cut a row without splitting a surrogate pair. */
+function cutRow(row: string): string {
+	if (row.length <= MAX_CARRIED_LINE_CHARS) return row
+	const cut = row.slice(0, MAX_CARRIED_LINE_CHARS - 1).replace(/[\uD800-\uDBFF]$/, '')
+	return `${cut}…`
+}
+
+function splitKeepingTerminators(text: string): string[] {
+	return text.length === 0 ? [] : (text.match(/[^\n]*\n|[^\n]+$/g) ?? [])
+}
+
+/**
+ * The coarse fallback when the diff cannot finish in time: everything between the
+ * common head and tail counts as changed. Never used when a real diff exists.
+ */
+function coarseDiff(before: string, after: string): LineDiff {
+	const a = splitKeepingTerminators(before)
+	const b = splitKeepingTerminators(after)
+	let head = 0
+	while (head < a.length && head < b.length && a[head] === b[head]) head++
+	let tail = 0
+	while (
+		tail < a.length - head &&
+		tail < b.length - head &&
+		a[a.length - 1 - tail] === b[b.length - 1 - tail]
+	)
+		tail++
+	const removed = a.slice(head, a.length - tail)
+	const added = b.slice(head, b.length - tail)
+	const rows = [
+		...removed.map((line) => `-${line.replace(/\n$/, '')}`),
+		...added.map((line) => `+${line.replace(/\n$/, '')}`),
+	]
+	const kept = rows.slice(0, MAX_CARRIED_DIFF_LINES).map(cutRow)
+	return {
+		added: added.length,
+		removed: removed.length,
+		hunks:
+			rows.length === 0
+				? []
+				: [
+						{
+							oldStart: head + 1,
+							oldLines: removed.length,
+							newStart: head + 1,
+							newLines: added.length,
+							lines: kept,
+						},
+					],
+		truncated: rows.length > kept.length,
+	}
+}
+
+/**
+ * The real line diff between two bodies, the way git counts it.
+ *
+ * A line ends at its newline, so a body whose only difference is the final
+ * newline changes one line on each side (`+1 -1`), never nothing. The counts
+ * come from the hunks of a line diff, not from the span between the first and
+ * last changed line, so two edits far apart in one file are two lines, not the
+ * whole stretch between them.
+ */
+export function lineDiff(before: string, after: string): LineDiff {
+	if (before === after) return { added: 0, removed: 0, hunks: [], truncated: false }
+	const patch = structuredPatch('a', 'a', before, after, undefined, undefined, {
+		context: CONTEXT_LINES,
+		timeout: DIFF_TIMEOUT_MS,
+	})
+	if (patch === undefined) return coarseDiff(before, after)
+	let added = 0
+	let removed = 0
+	let budget = MAX_CARRIED_DIFF_LINES
+	let truncated = false
+	const hunks: ToolDiffHunk[] = []
+	for (const hunk of patch.hunks) {
+		const rows: string[] = []
+		for (const row of hunk.lines) {
+			// "" describes the row above it; it is not a line.
+			if (row.startsWith('\\')) continue
+			if (row.startsWith('+')) added++
+			else if (row.startsWith('-')) removed++
+			if (budget > 0) {
+				rows.push(cutRow(row))
+				budget--
+			} else {
+				truncated = true
+			}
+		}
+		if (rows.length > 0) {
+			hunks.push({
+				oldStart: hunk.oldStart,
+				oldLines: hunk.oldLines,
+				newStart: hunk.newStart,
+				newLines: hunk.newLines,
+				lines: rows,
+			})
+		}
+	}
+	return { added, removed, hunks, truncated }
+}

package/src/turn/reporter.ts

@@ -442,6 +442,7 @@ export function createTurnReporter(parentLogger?: Logger): TurnReporter {
 			case 'hosted_tool':
 			case 'tool_calls_admitted':
 			case 'compaction_shed':
+			case 'compaction_started':
 				// Deliberately silent. The report is what a human reads about a
 				// run; replaying every shed message into it would bury the
 				// summary line that says the pass happened, in exactly the

package/src/types/session/events.ts

@@ -184,6 +184,28 @@ type CoreSessionEvent =
 			/** Automatic threshold, provider rejection, or a host-requested pass. */
 			reason: 'threshold' | 'overflow' | 'manual'
 	  }
+	/**
+	 * An automatic compaction pass is about to run.
+	 *
+	 * Summarising can take many seconds and every other compaction event
+	 * arrives AFTER the work, so a host had nothing to show while the turn
+	 * sat silent. This one arrives first. It is always followed by exactly
+	 * one of `compaction_completed`, `compaction_failed` or
+	 * `compaction_tool_results_cleared` (when clearing alone made room), so
+	 * a host can show a live line and drop it on any of the three.
+	 */
+	| {
+			type: 'compaction_started'
+			sessionId: SessionId
+			turnId?: TurnId
+			iteration: number
+			/** `overflow` when the provider rejected the prompt, `threshold` when the trigger fired. */
+			reason: 'threshold' | 'overflow'
+			/** Context size in tokens that the pass is trying to reduce. */
+			tokensBefore: number
+			/** The window the trigger measured against. */
+			contextWindowTokens: number
+	  }
 	| {
 			type: 'compaction_completed'
 			sessionId: SessionId
@@ -1274,6 +1296,9 @@ export type SessionEventListener = (event: SessionEvent) => void | Promise<void>
  * runtime-context message or tool result that carried it, and a noisy watch
  * would write tens of megabytes an hour of raw process output a second time.
  * `background_job_exited.monitor` is the durable record of how a watch ended.
+ * `compaction_started` is ephemeral too: it only says a pass is about to run,
+ * and the `compaction` record or `compaction_failed` that ends it is the
+ * durable fact.
  */
 export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<SessionEventType>([
 	'text_delta',
@@ -1281,14 +1306,20 @@ export const EPHEMERAL_EVENT_TYPES: ReadonlySet<SessionEventType> = new Set<Sess
 	'reasoning_delta',
 	'tool_progress',
 	'monitor_event',
+	'compaction_started',
 ])
 
 export function isEphemeralEvent(event: { readonly type: string }): boolean {
 	return EPHEMERAL_EVENT_TYPES.has(event.type as SessionEventType)
 }
 
-/** The event types a session log records: every literal except the ephemeral five. */
+/** The event types a session log records: every literal except the ephemeral six. */
 export type PersistedSessionEventType = Exclude<
 	SessionEventType,
-	'text_delta' | 'tool_input_delta' | 'reasoning_delta' | 'tool_progress' | 'monitor_event'
+	| 'text_delta'
+	| 'tool_input_delta'
+	| 'reasoning_delta'
+	| 'tool_progress'
+	| 'monitor_event'
+	| 'compaction_started'
 >

package/src/types/session/records.ts

@@ -629,6 +629,7 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	approval_policy_changed: true,
 	request_envelope: true,
 	iteration_completed: true,
+	compaction_started: true,
 	compaction_shed: true,
 	compaction_completed: true,
 	compaction_tool_results_cleared: true,
@@ -688,12 +689,12 @@ const SESSION_EVENT_TYPE_TABLE: Record<SessionEventType, true> = {
 	child_session_idled: true,
 }
 
-/** All 63 live event type literals. */
+/** All 64 live event type literals. */
 export const SESSION_EVENT_TYPES: readonly SessionEventType[] = Object.freeze(
 	Object.keys(SESSION_EVENT_TYPE_TABLE) as SessionEventType[],
 )
 
-/** The 58 event types a session log records: all 63 but the five ephemeral ones. */
+/** The 58 event types a session log records: all 64 but the six ephemeral ones. */
 export const PERSISTED_SESSION_EVENT_TYPES: readonly PersistedSessionEventType[] = Object.freeze(
 	SESSION_EVENT_TYPES.filter(
 		(type) => !EPHEMERAL_EVENT_TYPES.has(type),

package/src/types/tool/index.ts

@@ -1331,6 +1331,7 @@ export * from './repair.js'
 
 export type {
 	ToolCallView,
+	ToolDiffHunk,
 	ToolFacts,
 	ToolFailureReason,
 	ToolPresentation,

package/src/types/tool/presentation.ts

@@ -82,6 +82,19 @@ export interface ToolTextWindow {
 	readonly totalBytes: number
 }
 
+/**
+ * One hunk of a line diff: the changed lines with up to three unchanged lines
+ * around them. Every row of `lines` is a space, `+` or `-` followed by the
+ * line's text, without its newline. Line numbers start at 1.
+ */
+export interface ToolDiffHunk {
+	readonly oldStart: number
+	readonly oldLines: number
+	readonly newStart: number
+	readonly newLines: number
+	readonly lines: readonly string[]
+}
+
 /** Why a call did not do what it was asked, as a kind a host can phrase for a person. */
 export type ToolFailureReason =
 	| 'not_found'
@@ -154,6 +167,13 @@ export type ToolFacts =
 			readonly kind: 'edit'
 			readonly path?: string
 			readonly replacements?: number
+			/** Lines added and removed, counted from a real line diff of the whole file. */
+			readonly added?: number
+			readonly removed?: number
+			/** The change as hunks with three lines of context. Capped; see `hunksTruncated`. */
+			readonly hunks?: readonly ToolDiffHunk[]
+			/** Some rows of the change are not in `hunks`; `added` and `removed` still cover all of it. */
+			readonly hunksTruncated?: true
 	  }
 	| {
 			readonly kind: 'write'
@@ -163,6 +183,9 @@ export type ToolFacts =
 			readonly bytes?: number
 			readonly added?: number
 			readonly removed?: number
+			/** The change as hunks; a created file is one hunk of added lines. Capped; see `hunksTruncated`. */
+			readonly hunks?: readonly ToolDiffHunk[]
+			readonly hunksTruncated?: true
 	  }
 	| {
 			readonly kind: 'failure'