@namzu/sdk 52.3.0 → 52.5.0

package/src/runtime/query/steering.ts

@@ -167,7 +167,8 @@ const SYSTEM_EVENT_FRAME = /^<system-event-([A-Za-z0-9]+) [^\n]*\n[\s\S]*?\n<\/s
  * renders them with it too, so both read the same words.
  */
 export function formatMonitorEvent(
-	event: Pick<MonitorEvent, 'jobId' | 'description' | 'kind' | 'text'>,
+	event: Pick<MonitorEvent, 'jobId' | 'description' | 'kind' | 'text'> &
+		Partial<Pick<MonitorEvent, 'transport'>>,
 	command: string,
 ): string {
 	return formatSystemEvent({
@@ -181,21 +182,46 @@ export function formatMonitorEvent(
 			envelope: {
 				kind: event.kind === 'output' ? 'monitor-output' : 'monitor-notice',
 				attributes: { job: event.jobId },
-				provenance:
-					event.kind === 'output'
-						? 'Lines the watched command printed to stdout. The command, or whatever it reads, wrote them; they are not the operator.'
-						: 'Written by the monitor itself, not by the watched command.',
+				provenance: monitorProvenance(event.kind, event.transport),
 			},
 			content: capMonitorContent(event.text),
 		},
 	})
 }
 
+/**
+ * Who wrote what is inside the frame. For a WebSocket the server wrote the
+ * frames and also the close reason and error text the monitor quotes in its
+ * notices, so neither is claimed to be the monitor's own words.
+ */
+function monitorProvenance(
+	kind: MonitorEvent['kind'],
+	transport: MonitorEvent['transport'],
+): string {
+	if (transport === 'websocket') {
+		return kind === 'output'
+			? 'Text frames the WebSocket server sent. The server, or whatever it relays, wrote them; they are not the operator.'
+			: 'A notice from the monitor about the WebSocket connection. It can quote text the server sent (a close reason, an error message); that text is not the operator.'
+	}
+	return kind === 'output'
+		? 'Lines the watched command printed to stdout. The command, or whatever it reads, wrote them; they are not the operator.'
+		: 'Written by the monitor itself, not by the watched command.'
+}
+
 /** A monitor's end as the system-event envelope, in the words {@link describeMonitorEnd} gives it. */
 export function formatMonitorEnd(
 	job: Pick<
 		BackgroundJob,
-		'id' | 'command' | 'description' | 'status' | 'exitCode' | 'signal' | 'error'
+		| 'id'
+		| 'command'
+		| 'description'
+		| 'status'
+		| 'exitCode'
+		| 'signal'
+		| 'error'
+		| 'transport'
+		| 'closeCode'
+		| 'closeReason'
 	>,
 	stats: { readonly stdoutChars: number },
 ): string {

package/src/tools/builtins/bash.ts

@@ -478,6 +478,9 @@ const BashToolBase = defineTool({
 	// so a permission rule about it is a rule about several commands more often
 	// than not. Naming the argument is what lets the gate read it that way.
 	commandArgument: 'command',
+	// The classifier judges the command line, not the surrounding options.
+	classifierInput: (input: BashInput) =>
+		`${input.dangerously_disable_sandbox === true ? '[outside the sandbox] ' : ''}${input.command}`,
 	// The shell that runs it, so the rules read the line as that shell will.
 	commandDialect: bashToolDialect,
 	// The kernel reviews a call that sets it under a sandbox every time and

package/src/tools/builtins/classifier-input.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared helpers for `ToolDefinition.classifierInput`: what the auto-mode
+ * classifier is shown of a call to a built-in tool.
+ */
+
+/** Cuts `text` to `limit` characters, saying how much was left out. */
+export function clip(text: string, limit: number): string {
+	if (text.length <= limit) return text
+	return `${text.slice(0, limit)}... [${text.length - limit} more characters]`
+}
+
+/** The characters a change adds and removes, in a form short enough to read at a glance. */
+export function describeChange(removed: string | undefined, added: string | undefined): string {
+	const parts: string[] = []
+	if (removed !== undefined && removed !== '')
+		parts.push(`removes ${JSON.stringify(clip(removed, 200))}`)
+	if (added !== undefined && added !== '') parts.push(`adds ${JSON.stringify(clip(added, 300))}`)
+	return parts.length > 0 ? parts.join(', ') : 'no text change'
+}

package/src/tools/builtins/code-analysis.ts

@@ -1,4 +1,5 @@
 import { realpath, stat } from 'node:fs/promises'
+import { isAbsolute, relative, sep } from 'node:path'
 import { z } from 'zod'
 
 import type {
@@ -112,7 +113,14 @@ const functionSourceOp = z.object({
 		),
 	function_id: z.number().int().min(0).optional(),
 	path: z.string().optional(),
-	name: z.string().min(1).optional(),
+	name: z.string().min(1).optional().describe('`name` or `Class.method`.'),
+	line: z
+		.number()
+		.int()
+		.min(1)
+		.optional()
+		.describe('With `column`: cut a long function around this position, not at its end.'),
+	column: z.number().int().min(1).optional(),
 	max_chars: maxChars,
 	...paging,
 })
@@ -123,7 +131,10 @@ const callersOp = z.object({
 		.describe(
 			'Call sites of a callee TEXT (not scope-aware), each with its caller. Per file by default.',
 		),
-	name: z.string().min(1).describe('Callee text: `foo`, `obj.foo`, `this.foo`.'),
+	name: z
+		.string()
+		.min(1)
+		.describe('Callee text: `foo`, `obj.foo`, `this.foo`; or a method as `Class.method`.'),
 	scope: z
 		.enum(['file', 'workspace'])
 		.optional()
@@ -207,122 +218,176 @@ export const CodeAnalysisTool = defineTool({
 		}
 		const root = owner.root
 
-		switch (input.operation) {
-			case 'index': {
-				const result = await provider.index({
-					root,
-					// A narrower path indexes just that part of the root, which is
-					// how a root too big to index whole is covered in steps.
-					...(target !== root ? { scope: target } : {}),
-					...(input.force ? { force: true } : {}),
-					...signalOf(context),
-				})
-				return render(result, (value) => {
-					const f = value.files
-					const lines = [
-						`Indexed ${value.root}: ${f.indexed} files (${f.parsed} parsed, ${f.unchanged} unchanged, ${f.removed} removed, ${f.skipped} skipped, ${f.withParseErrors} with parse errors) in ${value.durationMs} ms.`,
-						`${value.functions} functions, ${value.strings} string literals, ${value.calls} calls. ${value.persisted ? 'Cached on disk.' : 'Held in memory only; it is gone when this process exits.'}`,
-					]
-					if (value.truncated) lines.push(value.truncated)
-					const reasons = Object.entries(value.skippedReasons)
-					if (reasons.length > 0) {
-						lines.push(`Skipped: ${reasons.map(([why, n]) => `${n} ${why}`).join(', ')}.`)
-					}
-					return lines
-				})
-			}
-			case 'find_literal': {
-				const result = await provider.findLiteral({
-					root,
-					text: input.text,
-					path: target,
-					...(input.case_sensitive === false ? { caseSensitive: false } : {}),
-					...pageArgs(input),
-					...signalOf(context),
-				})
-				return renderPage(result, (hit) => {
-					const where = `${hit.path}:${hit.line}:${hit.column}`
-					const shown = JSON.stringify(hit.value) + (hit.valueTruncated ? ' (cut)' : '')
-					const inside = hit.function ? ` in ${describeFunction(hit.function)}` : ' at top level'
-					return `${where}  ${hit.kind} ${shown}${inside}${staleMark(hit.stale)}`
-				})
-			}
-			case 'enclosing_function': {
-				const result = await provider.enclosingFunction({
-					root,
-					path: target,
-					line: input.line,
-					...(input.column !== undefined ? { column: input.column } : {}),
-					maxChars: input.max_chars ?? DEFAULT_MAX_CHARS,
-					...signalOf(context),
-				})
-				return render(result, (value) => {
-					if (!value.function) {
-						return [`${target}:${input.line}:${input.column ?? 1} is not inside any function.`]
+		const outcome = await (async (): Promise<ToolResult> => {
+			switch (input.operation) {
+				case 'index': {
+					const result = await provider.index({
+						root,
+						// A narrower path indexes just that part of the root, which is
+						// how a root too big to index whole is covered in steps.
+						...(target !== root ? { scope: target } : {}),
+						...(input.force ? { force: true } : {}),
+						...signalOf(context),
+					})
+					return render(result, (value) => {
+						const f = value.files
+						const lines = [
+							`Indexed ${value.root}: ${f.indexed} files (${f.parsed} parsed, ${f.unchanged} unchanged, ${f.removed} removed, ${f.skipped} skipped, ${f.withParseErrors} with parse errors) in ${value.durationMs} ms.`,
+							`${value.functions} functions, ${value.strings} string literals, ${value.calls} calls. ${value.persisted ? 'Cached on disk.' : 'Held in memory only; it is gone when this process exits.'}`,
+						]
+						if (value.truncated) lines.push(value.truncated)
+						const reasons = Object.entries(value.skippedReasons)
+						if (reasons.length > 0) {
+							lines.push(`Skipped: ${reasons.map(([why, n]) => `${n} ${why}`).join(', ')}.`)
+						}
+						return lines
+					})
+				}
+				case 'find_literal': {
+					const result = await provider.findLiteral({
+						root,
+						text: input.text,
+						path: target,
+						...(input.case_sensitive === false ? { caseSensitive: false } : {}),
+						...pageArgs(input),
+						...signalOf(context),
+					})
+					return renderPage(
+						result,
+						(hit) => {
+							const shown = JSON.stringify(hit.value) + (hit.valueTruncated ? ' (cut)' : '')
+							const kind = hit.kind === 'string' ? '' : ` (${hit.kind})`
+							const inside = hit.function ? ` in ${shortFunction(hit.function)}` : ' at top level'
+							return `${hit.line}:${hit.column}  ${shown}${kind}${inside}${staleMark(hit.stale)}`
+						},
+						(hit) => relativeTo(root, hit.path),
+					)
+				}
+				case 'enclosing_function': {
+					const result = await provider.enclosingFunction({
+						root,
+						path: target,
+						line: input.line,
+						...(input.column !== undefined ? { column: input.column } : {}),
+						maxChars: input.max_chars ?? DEFAULT_MAX_CHARS,
+						...signalOf(context),
+					})
+					return render(result, (value) => {
+						if (!value.function) {
+							const place = `${relativeTo(root, target)}:${input.line}:${input.column ?? 1}`
+							return [
+								value.inClass !== undefined
+									? `${place} is in the body of class ${value.inClass}, outside every method; not inside any function.`
+									: `${place} is not inside any function.`,
+							]
+						}
+						const lines = [describeFunction(value.function, root)]
+						if (value.parents.length > 0) {
+							lines.push(`parents: ${value.parents.map(shortFunction).join(' < ')}`)
+						}
+						if (value.source) lines.push(...sourceLines(value.source))
+						return lines
+					})
+				}
+				case 'function_source': {
+					if (input.function_id === undefined && !(input.path !== undefined && input.name)) {
+						return fail('function_source needs `function_id`, or `path` together with `name`.')
 					}
-					const lines = [`${describeFunction(value.function)}`]
-					if (value.parents.length > 0) {
-						lines.push(`parents: ${value.parents.map(describeFunction).join(' < ')}`)
+					const result = await provider.functionSource({
+						root,
+						...(input.function_id !== undefined ? { id: input.function_id } : {}),
+						...(input.name ? { name: input.name, path: target } : {}),
+						...(input.line !== undefined
+							? {
+									around: {
+										line: input.line,
+										...(input.column !== undefined ? { column: input.column } : {}),
+									},
+								}
+							: {}),
+						maxChars: input.max_chars ?? DEFAULT_MAX_CHARS,
+						...pageArgs(input),
+						...signalOf(context),
+					})
+					return renderPage(result, (item) =>
+						[
+							describeFunction(item.function, root),
+							item.parents.length > 0
+								? `parents: ${item.parents.map(shortFunction).join(' < ')}`
+								: undefined,
+							...sourceLines(item.source),
+						]
+							.filter((l): l is string => l !== undefined)
+							.join('\n'),
+					)
+				}
+				case 'callers_of': {
+					const scope = input.scope ?? 'file'
+					if (scope === 'file' && input.path === undefined) {
+						return fail(
+							'callers_of looks in one file by default, so it needs `path`. Pass `scope: "workspace"` to search the whole index; it matches by name only and will mix unrelated functions that share one.',
+						)
 					}
-					if (value.source) lines.push(...sourceLines(value.source))
-					return lines
-				})
-			}
-			case 'function_source': {
-				if (input.function_id === undefined && !(input.path !== undefined && input.name)) {
-					return fail('function_source needs `function_id`, or `path` together with `name`.')
+					const result = await provider.callersOf({
+						root,
+						name: input.name,
+						scope,
+						...(input.path !== undefined ? { path: target } : {}),
+						...(input.match ? { match: input.match } : {}),
+						...pageArgs(input),
+						...signalOf(context),
+					})
+					return renderPage(
+						result,
+						(site) => {
+							const inside = site.caller ? ` in ${shortFunction(site.caller)}` : ' at top level'
+							const how = site.kind === 'new' ? 'new ' : ''
+							const tag =
+								site.kind === 'call-via'
+									? ' [call/apply/bind]'
+									: site.kind === 'tagged'
+										? ' [tagged template]'
+										: ''
+							const label = site.resolution === 'text-only' ? ' [text-only]' : ''
+							return `${site.line}:${site.column}  ${how}${site.callee}(${site.argumentCount} arg${site.argumentCount === 1 ? '' : 's'})${tag}${label}${inside}${staleMark(site.stale)}`
+						},
+						(site) => relativeTo(root, site.path),
+					)
 				}
-				const result = await provider.functionSource({
-					root,
-					...(input.function_id !== undefined ? { id: input.function_id } : {}),
-					...(input.name ? { name: input.name, path: target } : {}),
-					maxChars: input.max_chars ?? DEFAULT_MAX_CHARS,
-					...pageArgs(input),
-					...signalOf(context),
-				})
-				return renderPage(result, (item) =>
-					[
-						describeFunction(item.function),
-						item.parents.length > 0
-							? `parents: ${item.parents.map(describeFunction).join(' < ')}`
-							: undefined,
-						...sourceLines(item.source),
-					]
-						.filter((l): l is string => l !== undefined)
-						.join('\n'),
-				)
-			}
-			case 'callers_of': {
-				const scope = input.scope ?? 'file'
-				if (scope === 'file' && input.path === undefined) {
-					return fail(
-						'callers_of looks in one file by default, so it needs `path`. Pass `scope: "workspace"` to search the whole index; it matches by name only and will mix unrelated functions that share one.',
+				case 'imports': {
+					const result = await provider.imports({
+						root,
+						path: target,
+						...pageArgs(input),
+						...signalOf(context),
+					})
+					return render(
+						result,
+						(page) =>
+							page.items.length === 0
+								? [page.total === 0 ? 'No results.' : 'No results on this page.']
+								: [
+										relativeTo(root, target),
+										...page.items.map((edge) => `  ${describeEdge(edge)}`),
+										page.nextCursor !== undefined
+											? `-- ${page.items.length} of ${page.total} shown. next cursor: ${page.nextCursor}`
+											: `-- ${page.items.length} of ${page.total} shown. last page.`,
+									],
+						(page) => ({
+							total: page.total,
+							count: page.items.length,
+							items: page.items,
+							...(page.nextCursor !== undefined ? { nextCursor: page.nextCursor } : {}),
+						}),
 					)
 				}
-				const result = await provider.callersOf({
-					root,
-					name: input.name,
-					scope,
-					...(input.path !== undefined ? { path: target } : {}),
-					...(input.match ? { match: input.match } : {}),
-					...pageArgs(input),
-					...signalOf(context),
-				})
-				return renderPage(result, (site) => {
-					const inside = site.caller ? ` in ${describeFunction(site.caller)}` : ' at top level'
-					return `${site.path}:${site.line}:${site.column}  ${site.kind === 'new' ? 'new ' : ''}${site.callee}(${site.argumentCount} arg${site.argumentCount === 1 ? '' : 's'})${inside}${staleMark(site.stale)}`
-				})
-			}
-			case 'imports': {
-				const result = await provider.imports({
-					root,
-					path: target,
-					...pageArgs(input),
-					...signalOf(context),
-				})
-				return renderPage(result, (edge) => describeEdge(edge, target))
 			}
-		}
+		})()
+		// With one root, a relative path is unambiguous. With several, the same
+		// `src/a.ts` could be in any of them, so the reader is told which this is.
+		return roots.length > 1 && outcome.success
+			? { ...outcome, output: `paths are relative to ${root}\n${outcome.output}` }
+			: outcome
 	},
 })
 
@@ -381,13 +446,27 @@ async function owningRoot(roots: readonly string[], target: string): Promise<Own
 	return sawFile ? { kind: 'file' } : { kind: 'none' }
 }
 
-function describeFunction(fn: AnalysisFunction): string {
-	const lines = fn.endLine === fn.line ? `line ${fn.line}` : `lines ${fn.line}-${fn.endLine}`
-	return `${fn.name ?? '(anonymous)'} [${fn.kind}, id ${fn.id}] ${fn.path}:${fn.line}:${fn.column} (${lines})`
+/** `path` relative to the root (POSIX separators), or `path` itself when it is not under it. */
+function relativeTo(root: string, path: string): string {
+	const rel = relative(root, path)
+	// `..` as a whole segment is outside the root; `..x` is a directory named so.
+	if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return path
+	return sep === '/' ? rel : rel.split(sep).join('/')
 }
 
-function describeEdge(edge: AnalysisModuleEdge, path: string): string {
-	const where = `${path}:${edge.line}:${edge.column}`
+/** `Svc.init#12 L10-40`: enough to cite and to ask for by id, no repeated path or kind. */
+function shortFunction(fn: AnalysisFunction): string {
+	const lines = fn.endLine === fn.line ? `L${fn.line}` : `L${fn.line}-${fn.endLine}`
+	return `${fn.qualifiedName ?? fn.name ?? '(anonymous)'}#${fn.id} ${lines}`
+}
+
+/** The full line a single function gets: kind and place included. */
+function describeFunction(fn: AnalysisFunction, root: string): string {
+	return `${shortFunction(fn)} [${fn.kind}] ${relativeTo(root, fn.path)}:${fn.line}:${fn.column}`
+}
+
+function describeEdge(edge: AnalysisModuleEdge): string {
+	const where = `${edge.line}:${edge.column}`
 	if (edge.direction === 'import') {
 		const names = edge.names.length > 0 ? ` { ${edge.names.join(', ')} }` : ''
 		return `${where}  import (${edge.kind})${names} from ${JSON.stringify(edge.source)}`
@@ -400,7 +479,9 @@ function sourceLines(slice: AnalysisSourceSlice): string[] {
 	const lines = ['--- source ---', slice.text]
 	if (slice.truncated) {
 		lines.push(
-			`--- cut: showing ${slice.text.length} of ${slice.chars} characters; raise max_chars to see more ---`,
+			slice.window
+				? `--- cut: showing ${slice.text.length} of ${slice.chars} characters, the function's first ${slice.window.headerChars} and the part around the position; raise max_chars to see more ---`
+				: `--- cut: showing ${slice.text.length} of ${slice.chars} characters; raise max_chars to see more ---`,
 		)
 	}
 	return lines
@@ -449,6 +530,8 @@ function render<T>(
 function renderPage<T>(
 	result: CodeAnalysisResult<AnalysisPage<T>>,
 	line: (item: T) => string,
+	/** Groups consecutive items of one file under a single heading. */
+	fileOf?: (item: T) => string,
 ): ToolResult {
 	return render(
 		result,
@@ -456,7 +539,16 @@ function renderPage<T>(
 			if (page.items.length === 0) {
 				return [page.total === 0 ? 'No results.' : 'No results on this page.']
 			}
-			const lines = page.items.map(line)
+			const lines: string[] = []
+			let current: string | undefined
+			for (const item of page.items) {
+				const file = fileOf?.(item)
+				if (file !== undefined && file !== current) {
+					lines.push(file)
+					current = file
+				}
+				lines.push(file === undefined ? line(item) : `  ${line(item)}`)
+			}
 			lines.push(
 				page.nextCursor !== undefined
 					? `-- ${page.items.length} of ${page.total} shown. next cursor: ${page.nextCursor}`

package/src/tools/builtins/edit.ts

@@ -5,6 +5,7 @@ import type { ToolContext, ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
+import { clip, describeChange } from './classifier-input.js'
 import { fingerprintContent, staleFileError, unreadFileError } from './content-fingerprint.js'
 import { type NormalizedEditInput, applyEdit, normalizeEditInput } from './edit-apply.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
@@ -393,6 +394,18 @@ export const EditTool = defineTool({
 	// Declared so a path outside the turn's roots can be reviewed before the
 	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.
 	pathArgument: 'path',
+	// The classifier judges which file changes and in what way, in a line.
+	classifierInput: (input: EditInput) => {
+		if (input.edits !== undefined) {
+			const shown = input.edits.slice(0, 5).map((e) => describeChange(e.old_string, e.new_string))
+			const more =
+				input.edits.length > shown.length ? `; ${input.edits.length - shown.length} more` : ''
+			return clip(`${input.path}: ${input.edits.length} edits: ${shown.join('; ')}${more}`, 1500)
+		}
+		const removed = input.old_string ?? input.oldStr
+		const added = input.new_string ?? input.newStr
+		return clip(`${input.path}: ${describeChange(removed, added)}`, 1500)
+	},
 	permissions: ['file_write'],
 	readOnly: false,
 	destructive: false,