@namzu/sdk 52.4.0 → 52.5.0

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,

package/src/tools/builtins/monitor.ts

@@ -178,6 +178,10 @@ export function createMonitorTool(options: MonitorToolOptions = {}) {
 		// has no `command`, so a rule written for commands has nothing to match
 		// and cannot allow it; `requiresApproval` below is what asks.
 		commandArgument: 'command',
+		classifierInput: (input: MonitorInput) =>
+			input.command !== undefined
+				? `[long-running watch] ${input.command}`
+				: `[long-running WebSocket watch] ${JSON.stringify(input.ws)}`,
 		commandDialect: bashToolDialect,
 		// `network_access` too: a WebSocket call reaches the network. The gate
 		// reads a tool's `category`, not this list, to route a call, so declaring

package/src/tools/builtins/web.ts

@@ -11,6 +11,7 @@ import {
 import { WebFetchRefusedError } from '../../connector/web/types.js'
 import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { clip } from './classifier-input.js'
 
 /**
  * The two web tools, and the reason they are one file.
@@ -151,6 +152,8 @@ export const WebFetchTool = defineTool({
 	// preset — handing outbound reach to runs whose sandbox was never asked
 	// to confine the network.
 	category: 'network',
+	// The classifier judges the address and what is asked of it.
+	classifierInput: (input) => `${clip(input.url, 1000)}: ${clip(input.prompt, 300)}`,
 	permissions: ['network_access'],
 	// Reads a page and changes nothing HERE. That is not the same as
 	// harmless — a GET can still act on a remote system — which is why the

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

@@ -6,6 +6,7 @@ import type { ToolFacts } from '../../types/tool/presentation.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
+import { clip } from './classifier-input.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { fileWriteResult } from './file-write-result.js'
@@ -93,6 +94,11 @@ export const WriteFileTool = 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 where a file is written and how much, not the body.
+	classifierInput: (input: WriteInput) => {
+		const body = input.content ?? input.newStr ?? ''
+		return `${input.path}: writes ${body.length} characters, starting ${JSON.stringify(clip(body, 300))}`
+	},
 	permissions: ['file_write'],
 	readOnly: false,
 	destructive: true,

package/src/tools/defineTool.ts

@@ -33,6 +33,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	capturesScreen?: boolean | ((input: z.infer<S>) => boolean)
 	/** Whether this exact call always needs a person's approval; see {@link ToolDefinition.requiresApproval}. */
 	requiresApproval?: boolean | ((input: z.infer<S>) => boolean)
+	/** What the auto-mode classifier is shown of this call; see {@link ToolDefinition.classifierInput}. */
+	classifierInput?: (input: z.infer<S>) => string
 	/** Free-form filtering data, never sent to the model; see {@link ToolDefinition.metadata}. */
 	metadata?: Readonly<Record<string, unknown>>
 	/** Batch ordering boundary; see {@link ToolDefinition.executionBarrier}. */
@@ -186,6 +188,7 @@ export function defineTool<S extends z.ZodType>(
 							: () => options.requiresApproval as boolean,
 				}
 			: {}),
+		...(options.classifierInput !== undefined ? { classifierInput: options.classifierInput } : {}),
 		...(options.metadata !== undefined ? { metadata: options.metadata } : {}),
 
 		async execute(input: TInput, context: ToolContext): Promise<ToolResult> {

package/src/types/acp/index.ts

@@ -43,6 +43,13 @@ export interface AcpInitializeResult {
 	readonly promptAttachments?: boolean
 	/** True only when this host applies captured effort and review settings per prompt. */
 	readonly promptOptions?: boolean
+	/**
+	 * The review modes beyond the original five (`prompt`, `plan`,
+	 * `accept-edits`, `auto`, `strict`) that this host applies per prompt:
+	 * `bypass` and `classify`, when it supports them. Absent: it accepts only
+	 * the original five, and refuses the others before a turn starts.
+	 */
+	readonly promptPermissionModes?: readonly ('bypass' | 'classify')[]
 	/** Optional, explicitly installed Namzu host methods; core ACP peers can ignore them. */
 	readonly extensions?: readonly string[]
 	readonly protocolVersion: number

package/src/types/code-analysis/index.ts

@@ -119,6 +119,14 @@ export interface AnalysisFunction {
 	readonly id: number
 	/** `null` for an anonymous function with nothing to infer a name from. */
 	readonly name: string | null
+	/**
+	 * `name` qualified by what holds it, when it is a member: `Svc.init` for a
+	 * method of the class `Svc` (a class expression assigned to a variable takes
+	 * the variable's name), `obj.run` for a method of an object literal assigned
+	 * to `obj`. Absent for a function that is not a member. `functionSource`
+	 * accepts either spelling.
+	 */
+	readonly qualifiedName?: string
 	readonly kind: AnalysisFunctionKind
 	/** Absolute path. */
 	readonly path: string
@@ -136,6 +144,17 @@ export interface AnalysisSourceSlice {
 	readonly chars: number
 	/** `true` when `text` is shorter than `chars` because of the size cap. */
 	readonly truncated: boolean
+	/**
+	 * Present when the cut was made around a position rather than at the end:
+	 * `text` is the function's first `headerChars` characters, a marker for
+	 * what was left out, then the file's own characters `from` to `to`, which
+	 * contain the position asked about. `from` and `to` are offsets into the file.
+	 */
+	readonly window?: {
+		readonly headerChars: number
+		readonly from: number
+		readonly to: number
+	}
 }
 
 export interface IndexRequest extends AnalysisCallOptions {
@@ -222,6 +241,11 @@ export interface EnclosingFunctionRequest extends AnalysisCallOptions {
 export interface AnalysisEnclosingFunction {
 	/** `null` when the position is not inside any function — a real answer. */
 	readonly function: AnalysisFunction | null
+	/**
+	 * When `function` is `null` because the position is in a class body outside
+	 * every method (a field initializer, a `static {}` block): that class.
+	 */
+	readonly inClass?: string
 	/** The function's parents, innermost first. */
 	readonly parents: readonly AnalysisFunction[]
 	readonly source?: AnalysisSourceSlice
@@ -235,6 +259,11 @@ export interface FunctionSourceRequest extends AnalysisPaging {
 	readonly path?: string
 	readonly name?: string
 	readonly maxChars?: number
+	/**
+	 * A position in the function. When the source is longer than `maxChars`, the
+	 * slice is cut around it instead of at the end, and always contains it.
+	 */
+	readonly around?: { readonly line: number; readonly column?: number }
 }
 
 export interface AnalysisFunctionSource {
@@ -245,7 +274,11 @@ export interface AnalysisFunctionSource {
 
 export interface CallersOfRequest extends AnalysisPaging {
 	readonly root: string
-	/** The callee text: `foo`, `obj.foo`, `this.foo`. */
+	/**
+	 * The callee text: `foo`, `obj.foo`, `this.foo`. A method's qualified name
+	 * (`Svc.init`, as `functionSource` shows it) finds `this.init()` inside
+	 * `Svc` as a resolved call, and every other `<expr>.init()` as `text-only`.
+	 */
 	readonly name: string
 	/**
 	 * `file` looks in `path` only and is the default, because a callee matched
@@ -266,8 +299,19 @@ export interface AnalysisCallSite {
 	readonly line: number
 	readonly column: number
 	readonly callee: string
-	readonly kind: 'call' | 'new'
+	/**
+	 * `call-via` is `f.call(…)`, `f.apply(…)` or `f.bind(…)` of the callee (a
+	 * use, not necessarily a call); `tagged` is a tagged template.
+	 */
+	readonly kind: 'call' | 'new' | 'call-via' | 'tagged'
 	readonly argumentCount: number
+	/**
+	 * Only when the request named a method by its qualified name: `resolved`
+	 * for `this.m()` inside the class that declares it and for the qualified
+	 * text itself, `text-only` for any other receiver, which may be an
+	 * unrelated method of the same name.
+	 */
+	readonly resolution?: 'resolved' | 'text-only'
 	/** The function the call sits in; absent at the top level of a file. */
 	readonly caller?: AnalysisFunction
 	/** See {@link AnalysisLiteralHit.stale}. */
@@ -290,7 +334,11 @@ export type AnalysisModuleEdge =
 	  }
 	| {
 			readonly direction: 'export'
-			readonly kind: 'named' | 'default' | 'reexport' | 'star'
+			/**
+			 * `type` is a type-only export, `commonjs` is `module.exports` or
+			 * `exports.x`, `assign` is `export =`.
+			 */
+			readonly kind: 'named' | 'default' | 'reexport' | 'star' | 'type' | 'commonjs' | 'assign'
 			readonly name: string
 			readonly source?: string
 			readonly line: number