@namzu/sdk 51.1.0 → 52.1.0

package/src/runtime/query/iteration/stream-turn.ts

@@ -42,7 +42,11 @@ import { generateMessageId, generateToolCallId } from '../../../utils/id.js'
 import type { Logger } from '../../../utils/logger.js'
 import type { EmitEvent } from '../events.js'
 import type { RequestImageIdentity } from '../request-rich-content.js'
-import { streamWithProviderRejectedImageRecovery } from './provider-rejected-image.js'
+import {
+	type TextOnlyModelRecovery,
+	streamWithProviderRejectedImageRecovery,
+} from './provider-rejected-image.js'
+import type { RequestRepair } from './request-repair.js'
 import {
 	type ParsedToolArguments,
 	capPartialArguments,
@@ -237,6 +241,10 @@ export async function* streamProviderTurn(
 	announceAs?: import('../../../types/ids/index.js').MessageId,
 	imageRecovery?: {
 		readonly onAccepted: (identity: RequestImageIdentity) => Promise<void>
+		/** A model refused the request for holding an image it cannot read; the retry sent none. */
+		readonly textOnly?: TextOnlyModelRecovery
+		/** Repairs and resends a request the provider rejects as invalid. */
+		readonly repair?: RequestRepair
 	},
 	captureRequest = false,
 	/** The session the turn belongs to, named on the chat span as `gen_ai.conversation.id`. */
@@ -363,6 +371,8 @@ export async function* streamProviderTurn(
 					streamParams,
 					imageRecovery.onAccepted,
 					observeRequest,
+					imageRecovery.textOnly,
+					imageRecovery.repair,
 				)
 			: provider.chatStream(streamParams)
 	) as AsyncIterable<StreamChunk>

package/src/runtime/query/path-escalation.ts

@@ -0,0 +1,204 @@
+/**
+ * What a call writes or removes that no mode may approve in advance.
+ *
+ * Three questions the kernel answers about a prepared call before it runs, all
+ * of them about the call's own arguments and none about the model's intent:
+ *
+ * - does it write a protected path (a git hook, a shell rc file, editor or
+ *   tool configuration, the project's `.namzu` directory)?
+ * - does its shell line remove something catastrophic?
+ * - does its shell line reach a path outside the turn's roots, through a
+ *   command whose operands are paths or through a redirection?
+ *
+ * The first two are floors: they hold in every mode, the way a sandbox escape
+ * does. The third is the existing outside-root boundary, extended from the
+ * file tools' one declared argument to the paths a shell line names.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, relative, resolve } from 'node:path'
+
+import { isProtectedPath } from '../../authorization/protected-paths.js'
+import { dangerousRemoval } from '../../authorization/removal.js'
+import type { ShellDialect } from '../../authorization/shell-lexer.js'
+import { readShellLine, shellPathAccess } from '../../authorization/shell-paths.js'
+import { canonicalize, pathOutsideRoots } from '../../tools/paths.js'
+
+/** What the escalation records carry. */
+export interface PathEscalations {
+	readonly outsidePaths: readonly string[]
+	readonly protectedPaths: readonly string[]
+	readonly dangerousRemoval?: string
+}
+
+export interface PathEscalationContext {
+	/** The working directory first, then the added directories. */
+	readonly roots: readonly string[]
+	/** Whether to report paths outside the roots (`outsideRootAccess: 'review'`, no sandbox). */
+	readonly reviewOutside: boolean
+}
+
+/**
+ * The part of `absolute` that protected names are looked for in.
+ *
+ * Inside a root (the working directory or an added directory) that is the part
+ * below the root, not the whole path: the root is where the turn was put, and
+ * a root that itself sits under a protected name is not a reason to ask about
+ * every file in it. The case that matters is the managed worktree a sub-agent
+ * runs in, `~/.namzu/projects/<slug>/worktrees/<name>`, which lies under
+ * `.namzu` by construction; the reference terminal makes the same exception
+ * for its own worktrees directory. A path in no root is looked at whole.
+ */
+function protectedScope(absolute: string, roots: readonly string[]): string {
+	let best: string | undefined
+	for (const root of roots) {
+		const base = resolve(root)
+		const below = relative(base, absolute)
+		if (below === '' || below.startsWith('..') || isAbsolute(below)) continue
+		if (best === undefined || below.length < best.length) best = below
+	}
+	return best ?? absolute
+}
+
+/** A write is protected when its spelling, or the place a link leads to, is. */
+async function isProtectedWrite(
+	spelled: string,
+	absolute: string,
+	roots: readonly string[],
+): Promise<boolean> {
+	if (isProtectedPath(isAbsolute(spelled) ? protectedScope(absolute, roots) : spelled)) return true
+	if (isProtectedPath(protectedScope(absolute, roots))) return true
+	const real = await canonicalize(absolute)
+	const realRoots = await Promise.all(roots.map((root) => canonicalize(resolve(root))))
+	return isProtectedPath(protectedScope(real, [...roots, ...realRoots]))
+}
+
+/** `{a,b}` with plain comma lists, one level at a time, bounded. */
+export function expandBraces(value: string, limit = 16): string[] {
+	const open = value.indexOf('{')
+	if (open < 0) return [value]
+	let depth = 0
+	let close = -1
+	const commas: number[] = []
+	for (let i = open; i < value.length; i += 1) {
+		const c = value[i]
+		if (c === '{') depth += 1
+		else if (c === '}') {
+			depth -= 1
+			if (depth === 0) {
+				close = i
+				break
+			}
+		} else if (c === ',' && depth === 1) commas.push(i)
+	}
+	if (close < 0 || commas.length === 0) return [value]
+	const head = value.slice(0, open)
+	const tail = value.slice(close + 1)
+	const parts: string[] = []
+	let start = open + 1
+	for (const comma of [...commas, close]) {
+		parts.push(value.slice(start, comma))
+		start = comma + 1
+	}
+	const out: string[] = []
+	for (const part of parts) {
+		for (const rest of expandBraces(head + part + tail, limit)) {
+			out.push(rest)
+			if (out.length >= limit) return out
+		}
+	}
+	return out
+}
+
+/** The path a use names with `~` and `$HOME` read as the home directory, or why it cannot be. */
+function settle(
+	value: string,
+	home: string,
+): { readonly path: string } | { readonly unresolved: true } {
+	if (value === '~') return { path: home }
+	if (value.startsWith('~/')) return { path: resolve(home, value.slice(2)) }
+	if (value.startsWith('~')) return { unresolved: true }
+	const variable = /^\$(?:\{HOME\}|HOME)(?=\/|$)/.exec(value)
+	if (variable !== null) return { path: resolve(home, `.${value.slice(variable[0].length)}`) }
+	if (/[$`]/.test(value)) return { unresolved: true }
+	return { path: value }
+}
+
+/** The part of a glob path before the first segment that holds a glob character. */
+function beforeGlob(path: string): string {
+	const at = path.search(/[*?[]/)
+	if (at < 0) return path
+	const cut = path.lastIndexOf('/', at)
+	return cut <= 0 ? '/' : path.slice(0, cut)
+}
+
+/** A write the file tool's own declared path argument names. */
+export async function declaredWriteEscalation(
+	roots: readonly string[],
+	value: string,
+): Promise<string | undefined> {
+	const [first] = roots
+	if (first === undefined || value === '') return undefined
+	const absolute = resolve(resolve(first), value)
+	return (await isProtectedWrite(value, absolute, roots)) ? absolute : undefined
+}
+
+/** What a shell line reaches. */
+export async function shellEscalations(
+	line: string,
+	dialect: ShellDialect,
+	context: PathEscalationContext,
+): Promise<PathEscalations> {
+	const reading = readShellLine(line, dialect)
+	const access = shellPathAccess(reading)
+	const [cwd, ...added] = context.roots
+	const outside = new Set<string>()
+	const protectedPaths = new Set<string>()
+	const home = homedir()
+	if (cwd !== undefined) {
+		for (const use of access.uses) {
+			for (const spelled of expandBraces(use.path)) {
+				const settled = settle(spelled, home)
+				const unresolved = use.unresolved || 'unresolved' in settled
+				const base = 'path' in settled ? settled.path : spelled
+				const absolute = isAbsolute(base) ? resolve(base) : resolve(cwd, base)
+				if (use.access === 'write' && (await isProtectedWrite(spelled, absolute, context.roots))) {
+					protectedPaths.add(absolute)
+				}
+				if (!context.reviewOutside) continue
+				if (unresolved) {
+					// A write whose target is decided at runtime cannot be checked; a
+					// read of one is left, as the reference leaves it.
+					if (use.access === 'write') outside.add(spelled)
+					continue
+				}
+				if (
+					access.changesDirectory &&
+					use.access === 'write' &&
+					!isAbsolute(base) &&
+					!spelled.startsWith('~')
+				) {
+					// A `cd` earlier in the line moves a relative target somewhere the
+					// roots cannot be compared with.
+					outside.add(spelled)
+					continue
+				}
+				const reached = await pathOutsideRoots(context.roots, beforeGlob(absolute))
+				if (reached !== undefined) outside.add(reached)
+			}
+		}
+	}
+	const removal =
+		cwd === undefined
+			? undefined
+			: dangerousRemoval(reading, access.changesDirectory, {
+					cwd,
+					additionalDirectories: added,
+					home,
+				})
+	return {
+		outsidePaths: [...outside],
+		protectedPaths: [...protectedPaths],
+		...(removal !== undefined ? { dangerousRemoval: removal } : {}),
+	}
+}

package/src/runtime/query/plugin-hooks.ts

@@ -27,6 +27,14 @@ export function applyLifecycleHookResults(
 				if (result.text.trim().length > 0) annotations.push(result.text.trim())
 				continue
 			case 'skip':
+				// `turn_end`, `subagent_stop` and `pre_compact` answer with `skip`
+				// to keep the turn going or to cancel a pass. The sites that can act
+				// on that read the results themselves; a site that cannot (the
+				// final `turn_end` of a turn that already ended) has nothing to
+				// refuse and carries on.
+				if (event === 'turn_end' || event === 'subagent_stop' || event === 'pre_compact') {
+					continue
+				}
 				// The one lifecycle event with a verdict: a hook may refuse the
 				// prompt before the model sees it, and the turn ends there.
 				if (event === 'user_prompt_submit') {

package/src/runtime/query/reminders.ts

@@ -0,0 +1,45 @@
+import type { SessionId, TurnId } from '../../types/ids/index.js'
+import type { Message } from '../../types/message/index.js'
+
+/**
+ * What a reminder source is told when the kernel asks it for hidden reminders.
+ */
+export interface ReminderContext {
+	readonly sessionId: SessionId
+	readonly turnId: TurnId
+	/** The model request about to be made; 1 for the first of the turn. */
+	readonly iteration: number
+	/**
+	 * The conversation as it stands, reminders included. Read-only: a source
+	 * derives its cadence from this (how many assistant turns since it last
+	 * spoke), so a resumed or compacted conversation needs no counter of its own.
+	 */
+	readonly messages: readonly Message[]
+}
+
+/**
+ * A host's hidden reminders for the next model request.
+ *
+ * The kernel calls it once at the start of every model request of a turn
+ * (never the closing one) and appends each returned text to the conversation
+ * as a user-role message with provenance `{ type: 'runtime-context', kind:
+ * 'reminder' }`. The message is part of the durable history, so it is not
+ * operator input, never counts as the latest user request, and is not shown as
+ * something the operator typed. The channel is opt-in
+ * (`QueryParams.reminders`): a turn without a source behaves as before.
+ *
+ * A source that throws is treated as having nothing to say; a reminder is
+ * context, and a fault in one must not end a turn.
+ */
+export type ReminderSource = (
+	context: ReminderContext,
+) => readonly string[] | undefined | Promise<readonly string[] | undefined>
+
+/** Whether a message is a reminder the kernel appended for a {@link ReminderSource}. */
+export function isReminderMessage(message: Message): boolean {
+	return (
+		message.role === 'user' &&
+		message.source?.type === 'runtime-context' &&
+		message.source.kind === 'reminder'
+	)
+}

package/src/runtime/query/request-rich-content.ts

@@ -34,7 +34,8 @@ interface RichOccurrence {
 	readonly source: 'user' | 'tool'
 	readonly kind: RichKind
 	readonly bytes: number
-	readonly reason: 'budget' | 'provider-rejected' | 'invalid-image'
+	readonly mediaType?: string
+	readonly reason: 'budget' | 'provider-rejected' | 'invalid-image' | 'model-text-only'
 }
 
 export interface RequestImageIdentity {
@@ -65,6 +66,24 @@ const invalidUserImageMarker = (): string =>
 const invalidToolImageMarker = (): string =>
 	`[image omitted from this model request because the producing tool returned encoded bytes that are not a complete supported raster matching the declared media type. ${toolRecovery} Correct the image source before presenting it again.]`
 
+/** `12 KB`-style size of an encoded payload, so the model can tell a thumbnail from a full screenshot. */
+function describeEncodedSize(base64Length: number): string {
+	const bytes = Math.floor((base64Length * 3) / 4)
+	if (bytes < 1024) return `${bytes} B`
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+	return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/**
+ * What stands in for an image the current model cannot read. It says so, and
+ * what the image was, because the model otherwise sees a tool that reported
+ * success next to nothing and tends to retry it or claim to have seen the screen.
+ */
+const textOnlyImageMarker = (mediaType: string | undefined, base64Length: number): string =>
+	`[image omitted: the current model cannot read images${
+		mediaType ? ` (${mediaType}, ${describeEncodedSize(base64Length)})` : ''
+	}]`
+
 function assertInlineAttachment(
 	attachment: MessageAttachment,
 ): asserts attachment is Exclude<MessageAttachment, { readonly type: 'stored' }> {
@@ -75,7 +94,10 @@ function assertInlineAttachment(
 	}
 }
 
-function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[] {
+function collectRichOccurrences(
+	messages: readonly Message[],
+	imagesReadable: boolean,
+): RichOccurrence[] {
 	const occurrences: RichOccurrence[] = []
 
 	for (const [messageIndex, message] of messages.entries()) {
@@ -88,13 +110,17 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 					source: 'user',
 					kind: attachment.type === 'document' ? 'document' : 'image',
 					bytes: attachment.data.length,
+					mediaType: attachment.mediaType,
 					reason:
-						attachment.type !== 'document' && attachment.modelOmission?.reason === 'invalid-image'
-							? 'invalid-image'
+						attachment.type !== 'document' && !imagesReadable
+							? 'model-text-only'
 							: attachment.type !== 'document' &&
-									attachment.modelOmission?.reason === 'provider-rejected'
-								? 'provider-rejected'
-								: 'budget',
+									attachment.modelOmission?.reason === 'invalid-image'
+								? 'invalid-image'
+								: attachment.type !== 'document' &&
+										attachment.modelOmission?.reason === 'provider-rejected'
+									? 'provider-rejected'
+									: 'budget',
 				})
 			}
 			continue
@@ -109,12 +135,15 @@ function collectRichOccurrences(messages: readonly Message[]): RichOccurrence[]
 				source: 'tool',
 				kind: block.type,
 				bytes: block.data.length,
+				mediaType: block.mediaType,
 				reason:
-					block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
-						? 'invalid-image'
-						: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
-							? 'provider-rejected'
-							: 'budget',
+					block.type === 'image' && !imagesReadable
+						? 'model-text-only'
+						: block.type === 'image' && block.modelOmission?.reason === 'invalid-image'
+							? 'invalid-image'
+							: block.type === 'image' && block.modelOmission?.reason === 'provider-rejected'
+								? 'provider-rejected'
+								: 'budget',
 			})
 		}
 	}
@@ -130,11 +159,13 @@ function appendTextMarkers(content: string, markers: readonly string[]): string
 
 function appendMarkers(content: string, occurrences: readonly RichOccurrence[]): string {
 	const markers = occurrences.map((occurrence) =>
-		occurrence.reason === 'provider-rejected'
-			? rejectedUserImageMarker()
-			: occurrence.reason === 'invalid-image'
-				? invalidUserImageMarker()
-				: userMarker(occurrence.kind),
+		occurrence.reason === 'model-text-only'
+			? textOnlyImageMarker(occurrence.mediaType, occurrence.bytes)
+			: occurrence.reason === 'provider-rejected'
+				? rejectedUserImageMarker()
+				: occurrence.reason === 'invalid-image'
+					? invalidUserImageMarker()
+					: userMarker(occurrence.kind),
 	)
 	return appendTextMarkers(content, markers)
 }
@@ -148,8 +179,12 @@ function appendMarkers(content: string, occurrences: readonly RichOccurrence[]):
  * original array when nothing is omitted makes the no-op and exact-boundary
  * cases observable and keeps the common path allocation-free.
  */
-export function projectRequestRichContent(messages: Message[], maxBytes: number): Message[] {
-	const occurrences = collectRichOccurrences(messages)
+export function projectRequestRichContent(
+	messages: Message[],
+	maxBytes: number,
+	options: { readonly imagesReadable?: boolean } = {},
+): Message[] {
+	const occurrences = collectRichOccurrences(messages, options.imagesReadable ?? true)
 	if (occurrences.length === 0) return messages
 
 	const omitted = new Map<number, Map<number, RichOccurrence>>()
@@ -163,9 +198,7 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 	}
 
 	for (const occurrence of occurrences) {
-		if (occurrence.reason === 'provider-rejected' || occurrence.reason === 'invalid-image') {
-			omit(occurrence)
-		}
+		if (occurrence.reason !== 'budget') omit(occurrence)
 	}
 
 	let total = occurrences.reduce(
@@ -206,11 +239,13 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 					? {
 							type: 'text',
 							text:
-								occurrence.reason === 'provider-rejected'
-									? rejectedToolImageMarker()
-									: occurrence.reason === 'invalid-image'
-										? invalidToolImageMarker()
-										: toolMarker(occurrence.kind),
+								occurrence.reason === 'model-text-only'
+									? textOnlyImageMarker(occurrence.mediaType, occurrence.bytes)
+									: occurrence.reason === 'provider-rejected'
+										? rejectedToolImageMarker()
+										: occurrence.reason === 'invalid-image'
+											? invalidToolImageMarker()
+											: toolMarker(occurrence.kind),
 						}
 					: block
 			})
@@ -221,6 +256,21 @@ export function projectRequestRichContent(messages: Message[], maxBytes: number)
 	})
 }
 
+/** Whether the provider-bound request carries an image anywhere, in a user attachment or a tool result. */
+export function requestHasImages(messages: readonly Message[]): boolean {
+	for (const message of messages) {
+		if (message.role === 'user') {
+			for (const attachment of message.attachments ?? []) {
+				if (attachment.type !== 'stored' && attachment.type !== 'document') return true
+			}
+			continue
+		}
+		if (message.role !== 'tool' || !Array.isArray(message.content)) continue
+		if (message.content.some((block) => block.type === 'image')) return true
+	}
+	return false
+}
+
 function sameImage(
 	image: { readonly data: string; readonly mediaType: string },
 	identity: RequestImageIdentity,

package/src/runtime/query/resume-pending.ts

@@ -517,6 +517,24 @@ export async function applyPendingResume(
 				reason: "the turn's review approved this call, answered across a restart",
 			})
 		}
+		for (const path of call.escalation?.protectedPaths ?? []) {
+			await recorder.recordAudit({
+				what: { action: 'protected_path_write', tool: call.name, resource: path },
+				outcome: 'approved',
+				reason: "the turn's review approved this call, answered across a restart",
+			})
+		}
+		if (call.escalation?.dangerousRemoval !== undefined) {
+			await recorder.recordAudit({
+				what: {
+					action: 'dangerous_removal',
+					tool: call.name,
+					resource: call.escalation.dangerousRemoval,
+				},
+				outcome: 'approved',
+				reason: "the turn's review approved this call, answered across a restart",
+			})
+		}
 	}
 
 	// The parked assistant message is already in the log: it goes back into
@@ -562,6 +580,15 @@ export function escalationRefusal(
 	for (const path of escalation.outsidePaths ?? []) {
 		if (!shown?.outsidePaths?.includes(path)) return refusal
 	}
+	for (const path of escalation.protectedPaths ?? []) {
+		if (!shown?.protectedPaths?.includes(path)) return refusal
+	}
+	if (
+		escalation.dangerousRemoval !== undefined &&
+		shown?.dangerousRemoval !== escalation.dangerousRemoval
+	) {
+		return refusal
+	}
 	if (escalation.sandboxEscape && (!shown?.sandboxEscape || !confirmed?.includes(id))) {
 		return 'Refused after resume: running this command outside the sandbox needs a person to confirm it for this call, and the durable approval did not.'
 	}