@namzu/sdk 37.0.0 → 38.0.0

package/src/sandbox/file-walk.ts

@@ -227,6 +227,15 @@ async function* executeWalk(
 		}
 		if (canonicalRoot !== path.resolve(plan.root))
 			throw new Error('File walk root follows a symbolic link; use its authorized real directory')
+		// A named regular file is a one-entry search, not an empty directory.
+		const rootInfo = await wait(fs.lstat(plan.root))
+		check()
+		if (rootInfo.isFile()) {
+			noteVisit()
+			if (matchers.some((matcher) => matcher.test(path.basename(plan.root))))
+				yield { path: plan.root, size: rootInfo.size }
+			return
+		}
 		let start = plan.root
 		// Never follow a static-prefix symlink to speed up a pattern: traversal
 		// and its optimized starting point must have the same link policy.

package/src/scheduler/completion-inbox.ts

@@ -464,6 +464,9 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 			`task_id: ${handle.taskId}`,
 			`agent: ${handle.agentId}`,
 			`state: ${handle.state}`,
+			...(handle.state === 'completed' && run?.stopReason && run.stopReason !== 'end_turn'
+				? ['outcome: incomplete — execution stopped; this does not establish task completion.']
+				: []),
 			...(handle.result?.stopReason ? [`stop_reason: ${handle.result.stopReason}`] : []),
 			...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
 			'',

package/src/store/run/token-budget-disk.ts

@@ -227,6 +227,9 @@ function assertSameRoot(before: TokenBudgetSnapshot, after: TokenBudgetSnapshot)
 			!current ||
 			current.accountId !== previous.accountId ||
 			current.runId !== previous.runId ||
+			(previous.unresolved === true &&
+				current.unresolved !== true &&
+				(active.has(previous.id) || current.usage === undefined)) ||
 			(reconciled && current.usage === undefined) ||
 			!usageAtLeast(current.usage, previous.usage)
 		) {

package/src/tools/builtins/edit.ts

@@ -362,12 +362,18 @@ export const EditTool = defineTool({
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
 				const buffer = await context.sandbox.readFile(parsed.data.path)
-				const result = applyEdit(buffer.toString('utf-8'), normalized.operations)
+				const content = buffer.toString('utf-8')
+				const seen = context.fileReadTracker?.fingerprint?.(parsed.data.path)
+				if (seen !== undefined && seen !== fingerprintContent(content)) {
+					return { success: false as const, output: '', error: staleFileError(parsed.data.path) }
+				}
+				const result = applyEdit(content, normalized.operations)
 				if (!result.success) {
 					return { success: false as const, output: '', error: result.error }
 				}
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
+				context.fileReadTracker?.recordRead(parsed.data.path, result.content)
 				return {
 					success: true as const,
 					output: `Edited ${parsed.data.path}: ${result.replacements} replacement(s) [sandboxed]`,
@@ -378,33 +384,12 @@ export const EditTool = defineTool({
 			const hostPath = filePath as string
 			const content = await readFile(hostPath, 'utf-8')
 
-			const result = applyEdit(content, normalized.operations)
-			if (!result.success) {
-				// The anchor did not match what is on disk. Two very different
-				// situations produce that, and the difference is the whole
-				// value of the fingerprint:
-				//
-				// The file is as the agent left it, and the anchor is simply
-				// wrong — "not found, match the whitespace exactly" is the
-				// right thing to say.
-				//
-				// Or the file moved after the read — a person in an editor,
-				// another process, a second agent — and the same message is a
-				// lie that sends the agent to re-check text that was never the
-				// problem, so it retries the identical edit against the same
-				// moved file.
-				//
-				// Deliberately NOT a gate on the successful path. An anchor
-				// that still matches uniquely is well defined however much
-				// changed elsewhere in the file, and refusing there would
-				// reject safe edits every time anyone touched an unrelated
-				// line.
-				const seen = context.fileReadTracker?.fingerprint?.(hostPath)
-				if (seen !== undefined && seen !== fingerprintContent(content)) {
-					return { success: false as const, output: '', error: staleFileError(hostPath) }
-				}
-				return { success: false as const, output: '', error: result.error }
+			const seen = context.fileReadTracker?.fingerprint?.(hostPath)
+			if (seen !== undefined && seen !== fingerprintContent(content)) {
+				return { success: false as const, output: '', error: staleFileError(hostPath) }
 			}
+			const result = applyEdit(content, normalized.operations)
+			if (!result.success) return { success: false as const, output: '', error: result.error }
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

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

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto'
+import type { ToolResult } from '../../types/tool/index.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
+}
+
+/** null means the backend could not establish the previous state. */
+export function fileWriteResult(
+	path: string,
+	before: string | undefined | null,
+	after: string,
+	sandboxed = false,
+): ToolResult {
+	const operation =
+		before === null
+			? 'write'
+			: before === undefined
+				? 'create'
+				: 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)
+	const bytes = Buffer.byteLength(after, 'utf8')
+	const label =
+		operation === 'create'
+			? 'Created'
+			: operation === 'replace'
+				? 'Updated'
+				: operation === 'unchanged'
+					? 'Unchanged'
+					: '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' : ''}`
+	return {
+		success: true,
+		output: `${summary} · ${bytes} bytes`,
+		data: {
+			path,
+			size: after.length,
+			...(sandboxed ? { sandboxed: true } : {}),
+			fileChange: {
+				operation,
+				...(before === null
+					? {}
+					: {
+							preview: {
+								before: removed.length ? `${removed.join('\n')}\n` : '',
+								after: added.length ? `${added.join('\n')}\n` : '',
+							},
+						}),
+				bytes,
+				sha256: createHash('sha256').update(after, 'utf8').digest('hex'),
+				...(before === null
+					? {}
+					: { added: added.length, removed: removed.length, newlineChanged }),
+			},
+		},
+	}
+}

package/src/tools/builtins/glob.ts

@@ -68,7 +68,13 @@ export const GlobTool = defineTool({
 	timeoutMs: 15_000,
 
 	presentCall(input) {
-		return { kind: 'generic', label: `${input.pattern} in ${input.path ?? '.'}` }
+		if (typeof input.pattern !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Find ${input.pattern} in ${input.path ?? '.'}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
 	},
 
 	async execute(input, context) {

package/src/tools/builtins/grep.ts

@@ -98,6 +98,16 @@ export const GrepTool = defineTool({
 	readOnly: true,
 	destructive: false,
 	concurrencySafe: true,
+
+	presentCall(input) {
+		if (typeof input.pattern !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Search ${input.pattern} in ${input.path ?? '.'}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
+	},
 	timeoutMs: 15_000,
 
 	async execute(input, context) {

package/src/tools/builtins/job.ts

@@ -54,6 +54,14 @@ export const JobTool = defineTool({
 	destructive: (input: JobInput) => input.action === 'kill',
 	concurrencySafe: true,
 
+	presentCall(input) {
+		const label =
+			input.action === 'list'
+				? 'List background jobs'
+				: `${input.action === 'kill' ? 'Stop background job' : 'Read background output'} · ${input.id ?? '(missing id)'}`
+		return { kind: 'generic', presentation: 'activity', label }
+	},
+
 	async execute(input, context) {
 		if (!context.backgroundJobs) {
 			return {

package/src/tools/builtins/read-file.ts

@@ -32,6 +32,16 @@ export const ReadFileTool = defineTool({
 	destructive: false,
 	concurrencySafe: true,
 
+	presentCall(input) {
+		if (typeof input.path !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Read ${input.path}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
+	},
+
 	async execute(input, context) {
 		// Sandbox-aware: route through sandbox.readFile() when available
 		if (context.sandbox) {

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

@@ -7,6 +7,7 @@ import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
+import { fileWriteResult } from './file-write-result.js'
 
 const inputSchema = z
 	.object({
@@ -81,40 +82,35 @@ export const WriteFileTool = defineTool({
 	destructive: true,
 	concurrencySafe: false,
 
-	/**
-	 * The whole file body, described by the tool.
-	 *
-	 * A `diff` with an EMPTY `before`, which is what a write actually is:
-	 * whatever was there is gone and this is what replaces it. `edit`
-	 * declines to do that for an insert — there, an empty `before` would
-	 * claim the whole file was added and it was not. Here it is true.
-	 *
-	 * A host with nothing to contrast against renders the `after` plainly
-	 * rather than as `+` lines, which is the row a reader wants: they are
-	 * approving a file, not reviewing a patch.
-	 */
+	// Input alone cannot establish whether this replaces an existing file.
 	presentCall(input: WriteInput) {
-		const content = input.content ?? input.newStr
-		if (typeof content !== 'string') return undefined
-		return {
-			kind: 'diff' as const,
-			...(input.path ? { path: input.path } : {}),
-			before: '',
-			after: content,
-		}
+		return { kind: 'generic' as const, label: input.path }
 	},
 
-	/**
-	 * A label, deliberately — which is what suppresses the detail block.
-	 *
-	 * The content was already shown under the CALL, where the user could
-	 * act on it. Repeating it under the result doubles the longest rows in
-	 * the transcript to say nothing new. A host used to decide this by
-	 * matching `name === 'write' || name === 'edit'`; it is the tool's to
-	 * say, and now it says it.
-	 */
+	/** The receipt names the observed operation; failures retain their error output. */
 	presentResult(_input: WriteInput, result: ToolResult) {
-		return { kind: 'generic' as const, label: result.output?.split('\n')[0] ?? '' }
+		const data = result.data as
+			| { fileChange?: { preview?: { before?: unknown; after?: unknown } } }
+			| undefined
+		const preview = data?.fileChange?.preview
+		if (
+			result.success &&
+			typeof preview?.before === 'string' &&
+			typeof preview.after === 'string'
+		) {
+			return {
+				kind: 'diff' as const,
+				path: _input.path,
+				label: result.output?.split('\n')[0],
+				before: preview.before,
+				after: preview.after,
+			}
+		}
+		return {
+			kind: 'generic' as const,
+			label: result.output?.split('\n')[0] ?? '',
+			...(result.success ? { presentation: 'activity' as const } : {}),
+		}
 	},
 
 	async execute(input: WriteInput, context) {
@@ -146,7 +142,7 @@ export const WriteFileTool = defineTool({
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
 				const current = await readSandboxFileIfPresent(context, valid.path)
-				if (current !== undefined) {
+				if (current !== undefined && current !== null) {
 					const guard = enforceFreshOverwrite(context, valid.path, current.toString('utf-8'))
 					if (guard) return guard
 				}
@@ -155,11 +151,12 @@ export const WriteFileTool = defineTool({
 				// the boolean would leave an older content fingerprint in place and
 				// make the next same-run write refuse its own predecessor as drift.
 				context.fileReadTracker?.recordRead(valid.path, content)
-				return {
-					success: true as const,
-					output: `File written successfully: ${valid.path} (${content.length} chars) [sandboxed]`,
-					data: { path: valid.path, size: content.length, sandboxed: true },
-				}
+				return fileWriteResult(
+					valid.path,
+					current === null ? null : current?.toString('utf-8'),
+					content,
+					true,
+				)
 			}
 
 			const hostPath = filePath as string
@@ -176,11 +173,7 @@ export const WriteFileTool = defineTool({
 			await atomicWriteFile(hostPath, content)
 			context.fileReadTracker?.recordRead(hostPath, content)
 
-			return {
-				success: true as const,
-				output: `File written successfully: ${hostPath} (${content.length} chars)`,
-				data: { path: hostPath, size: content.length },
-			}
+			return fileWriteResult(hostPath, current, content)
 		})
 	},
 })
@@ -237,14 +230,16 @@ function isMissingFileError(error: unknown): boolean {
 async function readSandboxFileIfPresent(
 	context: ToolContext,
 	path: string,
-): Promise<Buffer | undefined> {
+): Promise<Buffer | undefined | null> {
 	if (!context.sandbox) return undefined
 	try {
 		return await context.sandbox.readFile(path)
-	} catch {
+	} catch (error) {
+		if (isMissingFileError(error)) return undefined
 		// `Sandbox` currently has no typed missing-file result. Preserve the
 		// existing create behavior for all backends; when a read succeeds, the
 		// exact body above is still a real admission-time freshness check.
-		return undefined
+		// An untyped read failure does not prove that the target was absent.
+		return null
 	}
 }

package/src/tools/file-read-tracker.ts

@@ -0,0 +1,16 @@
+import type { FileReadTracker } from '../types/tool/index.js'
+import { fingerprintContent } from './builtins/content-fingerprint.js'
+
+/** Host-owned observation ledger. Share only across turns of the same conversation and filesystem. */
+export function createFileReadTracker(): FileReadTracker {
+	const paths = new Set<string>()
+	const fingerprints = new Map<string, string>()
+	return {
+		recordRead(key, content) {
+			paths.add(key)
+			if (content !== undefined) fingerprints.set(key, fingerprintContent(content))
+		},
+		hasRead: (key) => paths.has(key),
+		fingerprint: (key) => fingerprints.get(key),
+	}
+}

package/src/tools/task/list.ts

@@ -8,7 +8,7 @@ export function buildTaskListTool(taskStore: TaskStore, runId: RunId): ToolDefin
 	return defineTool({
 		name: 'task_list',
 		description:
-			'List all tasks for the current run. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
+			'List planning items for the current run, not delegated agent invocations. Use agent_task_list, when available, to inspect agent execution. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
 		inputSchema: z.object({}),
 		category: 'custom',
 		permissions: [],
@@ -46,7 +46,7 @@ export function buildTaskListTool(taskStore: TaskStore, runId: RunId): ToolDefin
 				success: true,
 				output:
 					tasks.length === 0
-						? 'No tasks yet.'
+						? 'No planning tasks yet. This list does not report delegated agent status; use agent_task_list when available.'
 						: `${stats.total} tasks: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending.`,
 				data: { tasks: summary, stats },
 			}

package/src/types/plugin/index.ts

@@ -8,6 +8,10 @@ import {
 	MAX_TOOLS_PER_PLUGIN,
 	PLUGIN_NAME_MAX_LENGTH,
 } from '../../constants/plugin/index.js'
+import type {
+	RequestContextChange,
+	RequestContextSnapshot,
+} from '../../runtime/query/request-context.js'
 import type { PluginId, RunId, SessionId } from '../ids/index.js'
 import type { Message, ToolResultContent } from '../message/index.js'
 import type { CancelCause } from '../run/cancel-cause.js'
@@ -142,6 +146,12 @@ export function assertPluginHookEvent(event: PluginHookEvent): void {
  * contract by accident.
  */
 export interface PluginModelRequest {
+	/** SDK provider-input content inventory; excludes adapter/server-private transformations. */
+	readonly context?: {
+		readonly snapshot: RequestContextSnapshot
+		/** Compared with the preceding pre_llm_call in this run; absent on the first. */
+		readonly change?: RequestContextChange
+	}
 	readonly model: string
 	readonly messages: readonly Message[]
 	/** Names only. A hook auditing tool exposure needs the set, not the schemas. */

package/src/types/provider/chat.ts

@@ -34,6 +34,8 @@ export interface ChatCompletionParams {
 	 * calls may omit it; a provider then uses its own id, `model`, and index 0.
 	 */
 	providerRoute?: ProviderRoute
+	/** Opt in to provider-hosted web search. Absent means no hosted search. */
+	webSearch?: { mode: 'cached' | 'live' }
 	tools?: LLMToolSchema[]
 	/**
 	 * Provider hint naming tools whose model-facing JSON Schema should be

package/src/types/provider/config.ts

@@ -121,6 +121,8 @@ export interface MockProviderConfig extends MockScript {
  * degradation is loud instead of silent.
  */
 export interface ProviderCapabilities {
+	/** Explicit provider-hosted web search support; absent means unsupported. */
+	supportsHostedWebSearch?: boolean
 	/** Native JSON Schema response-format mapping. Absent means unsupported. */
 	supportsNativeStructuredOutput?: boolean
 	supportsTools: boolean

package/src/types/provider/stream.ts

@@ -9,6 +9,13 @@ export interface StreamChunk {
 	 */
 	replayState?: unknown
 	delta: {
+		/** Activity executed by the provider, never a local function-call request. */
+		hostedTool?: {
+			id: string
+			name: 'web_search'
+			status: 'running' | 'completed' | 'failed'
+		}
+
 		content?: string
 		toolCalls?: Array<{
 			index: number

package/src/types/run/config.ts

@@ -65,6 +65,8 @@ export interface AgentRunConfig {
 	 * high-effort and silently was not is worse than a startup error.
 	 */
 	effort?: import('../provider/index.js').ReasoningEffort
+	/** Provider-hosted search for this run. Explicit opt-in; no local network permission. */
+	webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch']
 	tokenBudget: number
 	costLimitUsd?: number
 	maxIterations?: number

package/src/types/run/events.ts

@@ -17,6 +17,7 @@ import type { Message } from '../message/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
+import type { ToolResultView } from '../tool/presentation.js'
 import type { CancelCause } from './cancel-cause.js'
 import type { FencingToken } from './checkpoint-store.js'
 import type { Lineage } from './lineage.js'
@@ -367,6 +368,13 @@ type CoreRunEvent =
 			/** Optional completion in [0,1] when the tool genuinely knows it. */
 			fraction?: number
 	  }
+	/** Provider-executed activity, retained as evidence rather than a local tool request. */
+	| {
+			type: 'hosted_tool'
+			runId: RunId
+			iteration: number
+			tool: NonNullable<import('../provider/index.js').StreamChunk['delta']['hostedTool']>
+	  }
 	/**
 	 * A model call failed transiently and is being retried after a backoff.
 	 *
@@ -426,6 +434,8 @@ type CoreRunEvent =
 	  }
 	| {
 			type: 'tool_completed'
+			/** Bounded result view; omitted when output was overridden or truncated. */
+			presentation?: ToolResultView
 			runId: RunId
 			toolUseId: ToolUseId
 			toolName: string

package/src/types/sandbox/index.ts

@@ -310,6 +310,7 @@ export interface Sandbox {
 	listFiles(rootPath: string): Promise<readonly SandboxFileEntry[]>
 	/**
 	 * Lazily enumerate regular files as absolute paths, without following symlinks.
+	 * A regular-file root yields that file if its basename matches the pattern.
 	 * Cancellation and iterator return stop traversal. Exceeding the examined-entry
 	 * budget throws an error with code `ERR_FILE_WALK_LIMIT`; it is not an empty or
 	 * complete listing. Hosts requiring bounded search must refuse an absent method.

package/src/types/tool/presentation.ts

@@ -22,6 +22,8 @@ export type ToolCallView =
 			readonly label: string
 			/** Render this complete authored label without adding the registry name. */
 			readonly presentation?: 'activity'
+			/** Successful observations may be grouped by hosts without discarding output. */
+			readonly activity?: 'exploration'
 			/** A successful result may add no information beyond the completed call row. */
 			readonly visibility?: 'hidden'
 	  }
@@ -32,6 +34,8 @@ export type ToolCallView =
 	 */
 	| {
 			readonly kind: 'diff'
+			/** Optional operation summary, distinct from the file path. */
+			readonly label?: string
 			readonly path?: string
 			readonly before: string
 			readonly after: string