@namzu/sdk 0.6.0 → 1.0.0

package/src/tools/builtins/index.ts

@@ -6,6 +6,7 @@ export { GlobTool } from './glob.js'
 export { GrepTool } from './grep.js'
 export { LsTool } from './ls.js'
 export { SearchToolsTool } from './search-tools.js'
+export { VerifyOutputsTool } from './verify-outputs.js'
 export { createStructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME } from './structuredOutput.js'
 export { createComputerUseTool, COMPUTER_USE_TOOL_NAME } from './computer-use.js'
 
@@ -14,22 +15,21 @@ import { BashTool } from './bash.js'
 import { EditTool } from './edit.js'
 import { GlobTool } from './glob.js'
 import { GrepTool } from './grep.js'
-import { LsTool } from './ls.js'
 import { ReadFileTool } from './read-file.js'
-import { SearchToolsTool } from './search-tools.js'
+import { VerifyOutputsTool } from './verify-outputs.js'
 import { WriteFileTool } from './write-file.js'
 // Note: createStructuredOutputTool is not included in getBuiltinTools()
-// because it requires a schema parameter and is created per-use case
+// because it requires a schema parameter and is created per-use case.
+//
+// `LsTool` and `SearchToolsTool` are still exported for direct use but are
+// NOT in the default builtin set. Claude Code's training distribution (per
+// `code.claude.com/docs/en/tools-reference`) does NOT include `LS` —
+// directory listing is canonical `Bash` + `Glob`. `search_tools` has no
+// Claude analogue at all. Including these in the defaults gives the model
+// tools that look right but degrade alignment. File extension is canonical
+// `edit` with `insertLine: "end"` — the legacy `Append` tool is gone.
+// Hosts that genuinely want LS/search can still register them explicitly.
 
 export function getBuiltinTools(): ToolDefinition[] {
-	return [
-		ReadFileTool,
-		WriteFileTool,
-		EditTool,
-		BashTool,
-		GlobTool,
-		GrepTool,
-		LsTool,
-		SearchToolsTool,
-	]
+	return [BashTool, EditTool, GlobTool, GrepTool, ReadFileTool, VerifyOutputsTool, WriteFileTool]
 }

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

@@ -5,6 +5,12 @@ import { defineTool } from '../defineTool.js'
 
 const inputSchema = z.object({
 	path: z.string().describe('Path to the file to read (absolute or relative)'),
+	readRange: z
+		.tuple([z.coerce.number().int().min(1), z.coerce.number().int().min(1)])
+		.optional()
+		.describe(
+			'Optional 1-indexed inclusive line range, e.g. [10, 40]. When provided it takes precedence over offset/limit.',
+		),
 	offset: z.coerce
 		.number()
 		.int()
@@ -15,9 +21,9 @@ const inputSchema = z.object({
 })
 
 export const ReadFileTool = defineTool({
-	name: 'read_file',
+	name: 'read',
 	description:
-		'Reads a file and returns its contents with line numbers. Supports offset and limit parameters for large files.',
+		'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files.',
 	inputSchema,
 	category: 'filesystem',
 	permissions: ['file_read'],
@@ -32,11 +38,12 @@ export const ReadFileTool = defineTool({
 			const content = buffer.toString('utf-8')
 			const lines = content.split('\n')
 
-			const start = Math.max(0, input.offset ?? 0)
-			const end = input.limit ? start + input.limit : lines.length
+			const { start, end } = resolveReadWindow(input, lines.length)
 			const selectedLines = lines.slice(start, end)
 
-			const numberedLines = selectedLines.map((line, i) => `${start + i}\t${line}`).join('\n')
+			const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
+
+			context.fileReadTracker?.recordRead(input.path)
 
 			return {
 				success: true,
@@ -54,11 +61,12 @@ export const ReadFileTool = defineTool({
 		const content = await readFile(filePath, 'utf-8')
 		const lines = content.split('\n')
 
-		const start = Math.max(0, input.offset ?? 0)
-		const end = input.limit ? start + input.limit : lines.length
+		const { start, end } = resolveReadWindow(input, lines.length)
 		const selectedLines = lines.slice(start, end)
 
-		const numberedLines = selectedLines.map((line, i) => `${start + i}\t${line}`).join('\n')
+		const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n')
+
+		context.fileReadTracker?.recordRead(filePath)
 
 		return {
 			success: true,
@@ -71,3 +79,18 @@ export const ReadFileTool = defineTool({
 		}
 	},
 })
+
+function resolveReadWindow(
+	input: z.infer<typeof inputSchema>,
+	totalLines: number,
+): { start: number; end: number } {
+	if (input.readRange) {
+		const [first, last] = input.readRange
+		const start = Math.max(0, first - 1)
+		const end = Math.min(totalLines, Math.max(start, last))
+		return { start, end }
+	}
+	const start = Math.max(0, input.offset ?? 0)
+	const end = input.limit ? start + input.limit : totalLines
+	return { start, end }
+}

package/src/tools/builtins/search-tools.ts

@@ -26,7 +26,11 @@ export const SearchToolsTool = defineTool({
 			}
 		}
 
-		const matches = context.toolRegistry.searchDeferred(input.query)
+		const allowed =
+			context.allowedTools && context.allowedTools.length > 0 ? new Set(context.allowedTools) : null
+		const matches = context.toolRegistry
+			.searchDeferred(input.query)
+			.filter((tool) => !allowed || allowed.has(tool.name))
 
 		if (matches.length === 0) {
 			return {

package/src/tools/builtins/verify-outputs.ts

@@ -0,0 +1,126 @@
+import { stat } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { z } from 'zod'
+import type { ToolContext } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+const inputSchema = z.object({
+	paths: z
+		.array(z.string().min(1))
+		.min(1)
+		.describe('Expected output file paths to verify. Each path is checked for existence and size.'),
+	min_bytes: z
+		.number()
+		.int()
+		.min(0)
+		.optional()
+		.describe(
+			'Minimum acceptable file size in bytes. A file under this size counts as missing. Default: 1 (any non-empty file passes).',
+		),
+})
+
+type Result = {
+	path: string
+	exists: boolean
+	size_bytes?: number
+	ok: boolean
+	error?: string
+}
+
+export const VerifyOutputsTool = defineTool({
+	name: 'verify_outputs',
+	description:
+		"Verify that a set of expected output files actually exist on disk and are non-empty. Use this BEFORE declaring multi-worker work done — pass every expected output path the workers were supposed to produce. Returns a per-path report (exists, size_bytes, ok) plus an overall pass/fail summary. If any path fails, spawn a fresh `create_task` on the responsible specialist with a brief that names the missing path and the prior worker's output location — do NOT paper over a missing file in prose.",
+	inputSchema,
+	category: 'filesystem',
+	permissions: ['file_read'],
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+
+	async execute(input, context) {
+		const minBytes = input.min_bytes ?? 1
+		const results: Result[] = await Promise.all(
+			input.paths.map((path) => verifyOne({ path, minBytes, context })),
+		)
+
+		const passed = results.filter((r) => r.ok).length
+		const failed = results.filter((r) => !r.ok)
+		const summary = {
+			total: results.length,
+			passed,
+			failed: failed.length,
+			min_bytes: minBytes,
+		}
+		const lines = results.map((r) =>
+			r.ok
+				? `- OK   ${r.path}${typeof r.size_bytes === 'number' ? ` (${r.size_bytes}B)` : ''}`
+				: `- FAIL ${r.path} — ${r.error ?? (r.exists ? `size ${r.size_bytes ?? 0}B < min ${minBytes}B` : 'missing')}`,
+		)
+		const header = `Verify outputs: ${passed}/${results.length} passed (min ${minBytes}B)`
+		return {
+			success: failed.length === 0,
+			output: [header, '', ...lines].join('\n'),
+			error:
+				failed.length > 0
+					? `${failed.length} of ${results.length} expected outputs failed verification`
+					: undefined,
+			data: { results, summary },
+		}
+	},
+})
+
+async function verifyOne(input: {
+	path: string
+	minBytes: number
+	context: ToolContext
+}): Promise<Result> {
+	const { path, minBytes, context } = input
+	if (context.sandbox) {
+		try {
+			const buffer = await context.sandbox.readFile(path)
+			const size = buffer.byteLength
+			return {
+				path,
+				exists: true,
+				size_bytes: size,
+				ok: size >= minBytes,
+			}
+		} catch (err) {
+			return {
+				path,
+				exists: false,
+				ok: false,
+				error: err instanceof Error ? err.message : String(err),
+			}
+		}
+	}
+
+	const filePath = resolve(context.workingDirectory, path)
+	try {
+		const info = await stat(filePath)
+		if (!info.isFile()) {
+			return {
+				path,
+				exists: true,
+				ok: false,
+				error: 'not a regular file',
+			}
+		}
+		return {
+			path,
+			exists: true,
+			size_bytes: info.size,
+			ok: info.size >= minBytes,
+		}
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException)?.code
+		if (code === 'ENOENT') return { path, exists: false, ok: false }
+		return {
+			path,
+			exists: false,
+			ok: false,
+			error: err instanceof Error ? err.message : String(err),
+		}
+	}
+}

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

@@ -1,17 +1,40 @@
-import { mkdir, writeFile } from 'node:fs/promises'
+import { access, mkdir, writeFile } from 'node:fs/promises'
 import { dirname, resolve } from 'node:path'
 import { z } from 'zod'
+import type { ToolContext } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 
-const inputSchema = z.object({
-	path: z.string().describe('Path to the file to write'),
-	content: z.string().describe('Content to write to the file'),
-})
+const inputSchema = z
+	.object({
+		path: z
+			.string()
+			.min(1)
+			.describe(
+				'Relative path to the file to write (e.g. "outputs/report.md"). Required. Must be a non-empty string.',
+			),
+		content: z
+			.string()
+			.optional()
+			.describe(
+				'Full file body to write. Required (use "" only for an intentionally empty file). The file is fully overwritten — pass the COMPLETE intended content for this bounded chunk, not a diff. Self-budget content under 12000 characters before calling; if the intended body is longer, write a smaller opening section here, then use `edit` with insertLine: "end" to extend the file section by section. Do NOT try to chain multiple `write` calls, since each one overwrites the previous.',
+			),
+		newStr: z
+			.string()
+			.optional()
+			.describe(
+				'Alias for content. Useful for hosts that expose create/write operations as newStr. Self-budget this payload under 12000 characters before calling.',
+			),
+	})
+	.refine((value) => typeof value.content === 'string' || typeof value.newStr === 'string', {
+		message: 'Either content or newStr is required.',
+	})
+
+type WriteInput = z.infer<typeof inputSchema>
 
 export const WriteFileTool = defineTool({
-	name: 'write_file',
+	name: 'write',
 	description:
-		'Writes content to a file. Creates the file if it does not exist, overwrites if it does. Creates intermediate directories as needed.',
+		'Writes a file to the local filesystem. Overwrites the existing file at the path if there is one.\n\n- If the file already exists, you must use the `read` tool on it first in this conversation, or this call will fail.\n- Prefer the `edit` tool for modifying existing files — it only sends the diff and preserves the rest of the file byte-for-byte.\n- Use `write` to create a new file or to perform a deliberate full rewrite of a file you have already read.\n- Self-budget content/newStr under 12000 characters before emitting the tool call. For long content, write a smaller opening section, then use `edit` with insertLine: "end" to extend the file section by section. Do not chain multiple `write` calls — each one overwrites the previous.',
 	inputSchema,
 	category: 'filesystem',
 	permissions: ['file_write'],
@@ -19,26 +42,72 @@ export const WriteFileTool = defineTool({
 	destructive: true,
 	concurrencySafe: false,
 
-	async execute(input, context) {
+	async execute(input: WriteInput, context) {
+		const content = input.content ?? input.newStr ?? ''
 		// Sandbox-aware: route through sandbox.writeFile() when available
 		if (context.sandbox) {
-			await context.sandbox.writeFile(input.path, input.content)
+			const sandboxExists = await sandboxFileExists(context, input.path)
+			if (sandboxExists) {
+				const guard = enforceReadBeforeOverwrite(context, input.path)
+				if (guard) return guard
+			}
+			await context.sandbox.writeFile(input.path, content)
+			context.fileReadTracker?.recordRead(input.path)
 			return {
 				success: true,
-				output: `File written successfully: ${input.path} (${input.content.length} chars) [sandboxed]`,
-				data: { path: input.path, size: input.content.length, sandboxed: true },
+				output: `File written successfully: ${input.path} (${content.length} chars) [sandboxed]`,
+				data: { path: input.path, size: content.length, sandboxed: true },
 			}
 		}
 
 		const filePath = resolve(context.workingDirectory, input.path)
 
+		const localExists = await pathExists(filePath)
+		if (localExists) {
+			const guard = enforceReadBeforeOverwrite(context, filePath)
+			if (guard) return guard
+		}
+
 		await mkdir(dirname(filePath), { recursive: true })
-		await writeFile(filePath, input.content, 'utf-8')
+		await writeFile(filePath, content, 'utf-8')
+		context.fileReadTracker?.recordRead(filePath)
 
 		return {
 			success: true,
-			output: `File written successfully: ${filePath} (${input.content.length} chars)`,
-			data: { path: filePath, size: input.content.length },
+			output: `File written successfully: ${filePath} (${content.length} chars)`,
+			data: { path: filePath, size: content.length },
 		}
 	},
 })
+
+function enforceReadBeforeOverwrite(
+	context: ToolContext,
+	key: string,
+): { success: false; output: ''; error: string } | null {
+	if (!context.fileReadTracker) return null
+	if (context.fileReadTracker.hasRead(key)) return null
+	return {
+		success: false,
+		output: '',
+		error: `${key} already exists. Use the \`read\` tool on it first in this conversation, then call \`write\` again — or prefer \`edit\` for a targeted change.`,
+	}
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+	try {
+		await access(filePath)
+		return true
+	} catch {
+		return false
+	}
+}
+
+async function sandboxFileExists(context: ToolContext, path: string): Promise<boolean> {
+	if (!context.sandbox) return false
+	try {
+		await context.sandbox.readFile(path)
+		return true
+	} catch {
+		return false
+	}
+}

package/src/tools/coordinator/__tests__/agent.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Behavioural contract for `buildAgentTool`:
+ *
+ * - Reports `success: true` only when BOTH the gateway task state and
+ *   the underlying `BaseAgentResult.status` say completed.
+ * - Reports `success: false` and surfaces `lastError` when either
+ *   layer disagrees — the canonical bug Codex caught was that a
+ *   failed subagent could be reported as successful when the gateway
+ *   forwarded `state: 'completed'` from a manager that did not
+ *   propagate the run's `status: 'failed'`.
+ * - Returns the subagent's `result` string as the tool output on
+ *   success.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { TaskGateway, TaskHandle } from '../../../types/agent/gateway.js'
+import type { TaskId } from '../../../types/ids/index.js'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { buildAgentTool } from '../agent.js'
+
+function makeContext(): ToolContext {
+	return {
+		runId: 'run_test' as never,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+function fakeGateway(handle: TaskHandle, completed: TaskHandle): TaskGateway {
+	return {
+		async createTask() {
+			return handle
+		},
+		async waitForTask() {
+			return completed
+		},
+		async continueTask() {},
+		cancelTask() {},
+		getTask() {
+			return completed
+		},
+		listTasks() {
+			return [completed]
+		},
+		onTaskCompleted() {
+			return () => {}
+		},
+	}
+}
+
+const taskId = 'task_subagent' as TaskId
+
+const launched: TaskHandle = {
+	taskId,
+	agentId: 'sales-strategy',
+	state: 'running',
+	createdAt: 0,
+}
+
+describe('buildAgentTool', () => {
+	it('reports success when both task state and run status say completed', async () => {
+		const gateway = fakeGateway(launched, {
+			...launched,
+			state: 'completed',
+			result: {
+				runId: 'run_inner' as never,
+				status: 'completed',
+				usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } as never,
+				cost: { inputCostUsd: 0, outputCostUsd: 0, totalCostUsd: 0 } as never,
+				iterations: 1,
+				durationMs: 10,
+				messages: [],
+				result: 'final report text',
+			},
+			completedAt: 10,
+		})
+
+		const tool = buildAgentTool({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['sales-strategy'],
+		})
+
+		const result = await tool.execute(
+			{ description: 'plan', prompt: 'go', subagent_type: 'sales-strategy' },
+			makeContext(),
+		)
+
+		expect(result.success).toBe(true)
+		expect(result.output).toBe('final report text')
+	})
+
+	it('reports failure when run status is failed even though task state is completed', async () => {
+		const gateway = fakeGateway(launched, {
+			...launched,
+			state: 'completed',
+			result: {
+				runId: 'run_inner' as never,
+				status: 'failed',
+				usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } as never,
+				cost: { inputCostUsd: 0, outputCostUsd: 0, totalCostUsd: 0 } as never,
+				iterations: 1,
+				durationMs: 10,
+				messages: [],
+				lastError: 'tool budget exceeded',
+			},
+			completedAt: 10,
+		})
+
+		const tool = buildAgentTool({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['sales-strategy'],
+		})
+
+		const result = await tool.execute(
+			{ description: 'plan', prompt: 'go', subagent_type: 'sales-strategy' },
+			makeContext(),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('tool budget exceeded')
+		expect(result.error).toContain('failed')
+	})
+
+	it('reports failure when task state itself is failed', async () => {
+		const gateway = fakeGateway(launched, {
+			...launched,
+			state: 'failed',
+			result: undefined,
+			completedAt: 10,
+		})
+
+		const tool = buildAgentTool({
+			gateway,
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['sales-strategy'],
+		})
+
+		const result = await tool.execute(
+			{ description: 'plan', prompt: 'go', subagent_type: 'sales-strategy' },
+			makeContext(),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('failed')
+	})
+
+	it("does not accept a taskStore or runId — plan-task lifecycle is the parent's job", () => {
+		// Compile-time pin: AgentToolOptions must NOT include `taskStore`
+		// or `runId`. The Agent tool used to manage a per-call plan task
+		// internally and Codex caught a leak: when the subagent failed,
+		// the plan task stayed `'in_progress'` forever because
+		// `TaskStatus` has no `'failed'` value to flip to. Drop the
+		// integration entirely; if a host wants to track delegations as
+		// plan tasks, it does so via `TaskCreate` / `TaskUpdate` on its
+		// own side, where it owns the status semantics. This test
+		// freezes that decision.
+		const allowedOpts: Parameters<typeof buildAgentTool>[0] = {
+			gateway: fakeGateway(launched, launched),
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['sales-strategy'],
+			runtimeContext: undefined,
+			onTaskLaunched: undefined,
+		}
+		expect('taskStore' in allowedOpts).toBe(false)
+		expect('runId' in allowedOpts).toBe(false)
+	})
+})