@namzu/sdk 3.0.0 → 3.2.0

package/src/telemetry/__tests__/span-closure.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+/**
+ * A span that never ends is a trace that never closes, and the export is
+ * incomplete for exactly the run that failed.
+ *
+ * Both sites had the same shape: an `end()` call at every exit the author
+ * could see. The iteration loop had seventeen of them and the tool executor
+ * three plus a `finally` that opened below them. That is a rule every future
+ * edit has to remember, and it was already broken — anything throwing between
+ * the span's creation and the `try` left it open, and a generator abandoned
+ * by its consumer reached no exit at all.
+ */
+
+const ended: string[] = []
+const started: string[] = []
+
+function fakeSpan(name: string) {
+	return {
+		setAttributes: () => undefined,
+		setAttribute: () => undefined,
+		setStatus: () => undefined,
+		recordException: () => undefined,
+		addEvent: () => undefined,
+		end: () => ended.push(name),
+		spanContext: () => ({ traceId: 't', spanId: 's', traceFlags: 1 }),
+		isRecording: () => true,
+		updateName: () => undefined,
+	}
+}
+
+vi.mock('../runtime-accessors.js', () => ({
+	getTracer: () => ({
+		startSpan: (name: string) => {
+			started.push(name)
+			return fakeSpan(name)
+		},
+		startActiveSpan: (
+			name: string,
+			_opts: unknown,
+			_ctx: unknown,
+			fn: (span: ReturnType<typeof fakeSpan>) => unknown,
+		) => {
+			started.push(name)
+			return fn(fakeSpan(name))
+		},
+	}),
+	getMeter: () => ({
+		createCounter: () => ({ add: () => undefined }),
+		createHistogram: () => ({ record: () => undefined }),
+	}),
+}))
+
+function toolContext() {
+	return {
+		runId: 'run_span',
+		workingDirectory: '.',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => undefined,
+	} as never
+}
+
+beforeEach(() => {
+	started.length = 0
+	ended.length = 0
+})
+
+afterEach(() => {
+	vi.clearAllMocks()
+})
+
+describe('a tool span closes however the call leaves', () => {
+	it('closes on the ordinary path', async () => {
+		const { ToolRegistry } = await import('../../registry/tool/execute.js')
+		const tools = new ToolRegistry()
+		tools.register({
+			name: 'echo',
+			description: 'echo',
+			inputSchema: z.object({}),
+			execute: async () => ({ success: true, output: 'ok' }),
+		})
+
+		await tools.execute('echo', {}, toolContext())
+
+		expect(started).toHaveLength(1)
+		expect(ended).toEqual(started)
+	})
+
+	it('closes when the tool throws', async () => {
+		const { ToolRegistry } = await import('../../registry/tool/execute.js')
+		const tools = new ToolRegistry()
+		tools.register({
+			name: 'boom',
+			description: 'boom',
+			inputSchema: z.object({}),
+			execute: async () => {
+				throw new Error('kaboom')
+			},
+		})
+
+		await tools.execute('boom', {}, toolContext())
+
+		expect(ended).toEqual(started)
+	})
+
+	it('closes when input validation refuses the call', async () => {
+		const { ToolRegistry } = await import('../../registry/tool/execute.js')
+		const tools = new ToolRegistry()
+		tools.register({
+			name: 'strict',
+			description: 'strict',
+			inputSchema: z.object({ required: z.string() }),
+			execute: async () => ({ success: true, output: 'ok' }),
+		})
+
+		await tools.execute('strict', { wrong: 1 }, toolContext())
+
+		expect(ended).toEqual(started)
+	})
+
+	it('closes when the tool is not active', async () => {
+		const { ToolRegistry } = await import('../../registry/tool/execute.js')
+		const tools = new ToolRegistry()
+		tools.register(
+			{
+				name: 'later',
+				description: 'later',
+				inputSchema: z.object({}),
+				execute: async () => ({ success: true, output: 'ok' }),
+			},
+			'deferred',
+		)
+
+		await tools.execute('later', {}, toolContext())
+
+		expect(ended).toEqual(started)
+	})
+
+	it('closes when the registry does not hold the name at all', async () => {
+		const { ToolRegistry } = await import('../../registry/tool/execute.js')
+		const tools = new ToolRegistry()
+
+		// `getOrThrow` sat OUTSIDE the try that owned the finally, so this
+		// path — the one where the model invents a tool name — opened a span
+		// and never closed it.
+		await expect(tools.execute('nonexistent', {}, toolContext())).rejects.toThrow()
+
+		expect(started).toHaveLength(1)
+		expect(ended).toEqual(started)
+	})
+})

package/src/tools/advisory/index.ts

@@ -104,7 +104,7 @@ export function buildAdvisoryTools(opts: AdvisoryToolsOptions): ToolDefinition[]
 			const executionResult = await advisoryCtx.executor.consult(
 				advisor,
 				{ advisorId: advisor.id, question, domain, urgency, includeContext: include_context },
-				{ messages: [], iteration: 0 },
+				advisoryCtx.callContext(),
 			)
 
 			advisoryCtx.recordCall({

package/src/tools/builtins/__tests__/edit-commits-atomically.test.ts

@@ -0,0 +1,103 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+
+import type { ToolContext } from '../../../types/tool/index.js'
+
+/**
+ * That the atomic writer works is tested next door. This tests the thing
+ * that actually regressed: whether the TOOL goes through it.
+ *
+ * `edit` and `write` were reverted to a bare `writeFile`, and the existing
+ * atomicity test kept passing because it called `atomicWriteFile` directly —
+ * proving the module, never the caller. A write that fails partway then
+ * truncates the user's file, which is the one outcome `edit` exists to
+ * avoid.
+ */
+
+const atomicWriteFile = vi.fn(async () => {})
+vi.mock('../atomic-write-file.js', () => ({ atomicWriteFile }))
+
+function makeContext(workingDirectory: string): ToolContext {
+	return {
+		runId: 'run_atomic' as ToolContext['runId'],
+		workingDirectory,
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+describe('the file-mutating tools commit through the atomic writer', () => {
+	it('edit routes its local write through it', async () => {
+		const { EditTool } = await import('../edit.js')
+		atomicWriteFile.mockClear()
+
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-atomic-tool-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(atomicWriteFile).toHaveBeenCalledTimes(1)
+		expect(atomicWriteFile).toHaveBeenCalledWith(resolve(dir, 'doc.md'), 'alpha\ngamma\n')
+		// The mock swallowed the write, so the file is untouched — which is
+		// itself the proof that nothing else wrote it.
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nbeta\n')
+	})
+
+	it('write routes its local write through it', async () => {
+		const { WriteFileTool } = await import('../write-file.js')
+		atomicWriteFile.mockClear()
+
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-atomic-tool-'))
+
+		const result = await WriteFileTool.execute(
+			{ path: 'out.md', content: 'a complete body' },
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(atomicWriteFile).toHaveBeenCalledTimes(1)
+		expect(atomicWriteFile).toHaveBeenCalledWith(resolve(dir, 'out.md'), 'a complete body')
+	})
+
+	it('edit does not use it for a sandboxed write, which the sandbox owns', async () => {
+		const { EditTool } = await import('../edit.js')
+		atomicWriteFile.mockClear()
+
+		let body = 'alpha\nbeta\n'
+		const sandbox = {
+			id: 'sbx',
+			status: 'ready',
+			rootDir: '/workspace',
+			environment: 'basic',
+			async readFile() {
+				return Buffer.from(body)
+			},
+			async writeFile(_path: string, content: string | Buffer) {
+				body = content.toString()
+			},
+			async exec() {
+				throw new Error('not used')
+			},
+			async listFiles() {
+				return []
+			},
+			async destroy() {},
+		}
+
+		const result = await EditTool.execute(
+			{ path: 'doc.md', old_string: 'beta', new_string: 'gamma', replace_all: false },
+			{ ...makeContext('/workspace'), sandbox } as ToolContext,
+		)
+
+		expect(result.success).toBe(true)
+		expect(body).toBe('alpha\ngamma\n')
+		expect(atomicWriteFile).not.toHaveBeenCalled()
+	})
+})

package/src/tools/builtins/__tests__/edit.test.ts

@@ -1,8 +1,11 @@
-import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { Sandbox } from '../../../types/sandbox/index.js'
 import type { ToolContext } from '../../../types/tool/index.js'
+import { atomicWriteFile } from '../atomic-write-file.js'
 import { EditTool } from '../edit.js'
 
 function makeContext(workingDirectory: string): ToolContext {
@@ -16,6 +19,326 @@ function makeContext(workingDirectory: string): ToolContext {
 }
 
 describe('EditTool', () => {
+	it('publishes one closed canonical replacement contract', () => {
+		const schema = EditTool.modelInputSchema
+		expect(schema).toEqual({
+			type: 'object',
+			properties: {
+				path: {
+					type: 'string',
+					description: 'Path to the file to edit. Must not be empty.',
+				},
+				old_string: {
+					type: 'string',
+					description:
+						'Exact unique text from the file, without read-tool line-number prefixes. Must not be empty.',
+				},
+				new_string: {
+					type: 'string',
+					description:
+						'Exact replacement text. May be empty to delete old_string. Keep under 12000 characters.',
+				},
+				replace_all: {
+					type: 'boolean',
+					description: 'Replace every occurrence instead of requiring one unique match.',
+				},
+			},
+			required: ['path', 'old_string', 'new_string'],
+			additionalProperties: false,
+		})
+
+		expect(
+			EditTool.inputSchema.safeParse({
+				path: 'doc.md',
+				old_string: 'old',
+				new_string: 'new',
+				replace_all: true,
+			}).success,
+		).toBe(true)
+
+		// The MODEL schema above is the closed canonical one. The HOST schema
+		// is wider on purpose — aliases and line insertion are declared — and
+		// the point of `.strict()` is that wider still is not open.
+		for (const supported of [
+			{ path: 'doc.md', oldStr: 'old', newStr: 'new' },
+			{ path: 'doc.md', insertLine: 'end', new_string: 'append' },
+			{ path: 'doc.md', old_string: 'old', new_string: 'new', newStr: 'legacy' },
+		]) {
+			expect(EditTool.inputSchema.safeParse(supported).success, JSON.stringify(supported)).toBe(
+				true,
+			)
+		}
+
+		for (const unknown of [
+			{ path: 'doc.md', old_str: 'old', new_string: 'new' },
+			{ path: 'doc.md', old_string: 'old', new_string: 'new', replaceAll: true },
+		]) {
+			expect(EditTool.inputSchema.safeParse(unknown).success, JSON.stringify(unknown)).toBe(false)
+		}
+		expect(
+			EditTool.inputSchema.safeParse({
+				path: '   ',
+				old_string: 'old',
+				new_string: 'new',
+			}).success,
+		).toBe(false)
+	})
+
+	it('replaces one exact unique string', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+		const result = await EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'beta',
+				new_string: 'gamma',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\ngamma\n')
+	})
+
+	it('validates a path without rewriting edge whitespace', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, ' doc.md '), 'alpha\n')
+
+		const result = await EditTool.execute(
+			{
+				path: ' doc.md ',
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, ' doc.md '), 'utf-8')).toBe('beta\n')
+		expect(existsSync(join(dir, 'doc.md'))).toBe(false)
+	})
+
+	it('allows deletion with an empty new_string', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nremove me\nomega\n')
+
+		const result = await EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'remove me\n',
+				new_string: '',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nomega\n')
+	})
+
+	it('replaces every exact occurrence only when replace_all is true', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha alpha alpha')
+
+		const result = await EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: true,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(result.data).toMatchObject({ replacements: 3 })
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('beta beta beta')
+	})
+
+	it('refuses ambiguous exact matches instead of guessing', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\nalpha\n')
+
+		const result = await EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('is not unique')
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nalpha\n')
+	})
+
+	it('normalizes consistent CRLF/LF boundaries without fuzzy matching', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\r\nbeta\r\nomega\r\n')
+
+		const result = await EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'alpha\nbeta',
+				new_string: 'gamma\ndelta',
+				replace_all: false,
+			},
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('gamma\r\ndelta\r\nomega\r\n')
+	})
+
+	it('rejects a field it does not accept, even when execute is called directly', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\n')
+
+		// Without `.strict()` zod STRIPS an unrecognised key, so each of these
+		// would run as if the caller had never written it — a misspelling
+		// becomes a silent no-op rather than an error anyone can act on.
+		for (const input of [
+			{ path: 'doc.md', old_str: 'alpha', new_string: 'beta' },
+			{ path: 'doc.md', old_string: 'alpha', new_string: 'beta', overwrite: true },
+			{ path: 'doc.md', old_string: 'alpha', new_string: 'beta', replaceAll: true },
+		]) {
+			const result = await EditTool.execute(input as never, makeContext(dir))
+			expect(result.success, JSON.stringify(input)).toBe(false)
+			expect(result.error).toContain('Invalid edit input')
+		}
+
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\n')
+	})
+
+	it('accepts the host aliases the schema does declare', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+		writeFileSync(join(dir, 'doc.md'), 'alpha\n')
+
+		// The contract is closed, not narrow. `oldStr`/`newStr` and
+		// `insertLine` are in the schema for hosts that speak those names, so
+		// strictness must reject the unknown without rejecting these.
+		const result = await EditTool.execute(
+			{ path: 'doc.md', oldStr: 'alpha', newStr: 'beta' } as never,
+			makeContext(dir),
+		)
+
+		expect(result.success).toBe(true)
+		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('beta\n')
+	})
+
+	it('returns one canonical recovery shape after registry validation fails', async () => {
+		const registry = new ToolRegistry()
+		registry.register(EditTool)
+
+		const result = await registry.execute(
+			'edit',
+			{ insertLine: '"end"', newStr: 'content' },
+			makeContext('/tmp'),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Validation failed for "edit":')
+		expect(result.error).toContain('Required: path: string')
+		expect(result.error).toContain(
+			'{"path":"file.md","old_string":"exact unique text","new_string":"replacement text"}',
+		)
+		expect(result.error).not.toContain('Accepted shapes')
+	})
+
+	it('serializes independent EditTool read-modify-write cycles for one sandbox path', async () => {
+		let body = Buffer.from('alpha')
+		let reads = 0
+		let writes = 0
+		let releaseFirstWrite = () => {}
+		let markFirstWriteStarted = () => {}
+		const firstWriteStarted = new Promise<void>((resolve) => {
+			markFirstWriteStarted = resolve
+		})
+		const firstWriteGate = new Promise<void>((resolve) => {
+			releaseFirstWrite = resolve
+		})
+		const sandbox = {
+			id: 'sbx_edit_lock',
+			status: 'ready',
+			rootDir: '/workspace',
+			environment: 'basic',
+			async readFile() {
+				reads += 1
+				return Buffer.from(body)
+			},
+			async writeFile(_path: string, content: string | Buffer) {
+				writes += 1
+				if (writes === 1) {
+					markFirstWriteStarted()
+					await firstWriteGate
+				}
+				body = Buffer.isBuffer(content) ? Buffer.from(content) : Buffer.from(content)
+			},
+			async exec() {
+				throw new Error('not used')
+			},
+			async listFiles() {
+				return []
+			},
+			async destroy() {},
+		} as Sandbox
+		const firstContext = { ...makeContext('/workspace'), sandbox }
+		const secondContext = { ...makeContext('/workspace'), sandbox }
+
+		const first = EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'alpha',
+				new_string: 'beta',
+				replace_all: false,
+			},
+			firstContext,
+		)
+		await firstWriteStarted
+		const second = EditTool.execute(
+			{
+				path: 'doc.md',
+				old_string: 'beta',
+				new_string: 'gamma',
+				replace_all: false,
+			},
+			secondContext,
+		)
+		await Promise.resolve()
+		expect(reads).toBe(1)
+
+		releaseFirstWrite()
+		const results = await Promise.all([first, second])
+		expect(results.every((result) => result.success)).toBe(true)
+		expect(reads).toBe(2)
+		expect(writes).toBe(2)
+		expect(body.toString('utf-8')).toBe('gamma')
+	})
+
+	it('leaves the original intact when an atomic local write fails before commit', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-atomic-write-'))
+		const filePath = join(dir, 'doc.md')
+		writeFileSync(filePath, 'original')
+
+		await expect(
+			atomicWriteFile(filePath, 'replacement', {
+				beforeCommit: async () => {
+					throw new Error('injected pre-commit failure')
+				},
+			}),
+		).rejects.toThrow('injected pre-commit failure')
+
+		expect(readFileSync(filePath, 'utf-8')).toBe('original')
+		expect(readdirSync(dir).filter((entry) => entry.includes('.namzu-'))).toEqual([])
+	})
+
+	// ── the alias + insertion surface this build adds on top ──────────
+
 	it('accepts oldStr/newStr aliases for string replacement', async () => {
 		const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
 		writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')