@namzu/sdk 0.6.0 → 1.1.0

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

@@ -1,10 +1,16 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { extname, resolve } from 'node:path'
 import { z } from 'zod'
 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'],
@@ -29,14 +35,27 @@ export const ReadFileTool = defineTool({
 		// Sandbox-aware: route through sandbox.readFile() when available
 		if (context.sandbox) {
 			const buffer = await context.sandbox.readFile(input.path)
+			const binaryGuidance = describeStructuredBinaryRead(input.path, buffer)
+			if (binaryGuidance) {
+				return {
+					success: false,
+					output: binaryGuidance,
+					data: {
+						path: input.path,
+						sandboxed: true,
+						binary: true,
+					},
+				}
+			}
 			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,
@@ -51,14 +70,27 @@ export const ReadFileTool = defineTool({
 		}
 
 		const filePath = resolve(context.workingDirectory, input.path)
-		const content = await readFile(filePath, 'utf-8')
+		const buffer = await readFile(filePath)
+		const binaryGuidance = describeStructuredBinaryRead(filePath, buffer)
+		if (binaryGuidance) {
+			return {
+				success: false,
+				output: binaryGuidance,
+				data: {
+					path: filePath,
+					binary: true,
+				},
+			}
+		}
+		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(filePath)
 
 		return {
 			success: true,
@@ -71,3 +103,42 @@ export const ReadFileTool = defineTool({
 		}
 	},
 })
+
+function describeStructuredBinaryRead(path: string, buffer: Buffer): string | null {
+	const ext = extname(path).toLowerCase()
+	if (ext === '.docx') return buildStructuredBinaryGuidance(path, 'DOCX', 'python-docx')
+	if (ext === '.pptx') return buildStructuredBinaryGuidance(path, 'PPTX', 'python-pptx')
+	if (ext === '.xlsx') return buildStructuredBinaryGuidance(path, 'XLSX', 'openpyxl')
+	if (ext === '.pdf' || startsWithPdfHeader(buffer)) {
+		return buildStructuredBinaryGuidance(path, 'PDF', 'pdftotext or PyMuPDF')
+	}
+	return null
+}
+
+function startsWithPdfHeader(buffer: Buffer): boolean {
+	return buffer.length >= 4 && buffer.subarray(0, 4).toString('utf8') === '%PDF'
+}
+
+function buildStructuredBinaryGuidance(path: string, format: string, extractor: string): string {
+	return [
+		`The file "${path}" is a ${format} document package, not UTF-8 text.`,
+		'Do not use the read/cat tools as evidence for this raw file.',
+		`Extract its text with shell/Python tooling already available in the sandbox (${extractor}), write the extracted text or summary under scratch, then read that text file.`,
+		'If extraction fails, report the exact filename and extraction error instead of claiming the attachment is unavailable.',
+	].join('\n')
+}
+
+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

@@ -1,10 +1,22 @@
 import { z } from 'zod'
+import { toolDiscoveryHint } from '../../registry/tool/execute.js'
 import { defineTool } from '../defineTool.js'
 
 const inputSchema = z.object({
 	query: z.string().describe('Tool name or capability keyword to search for'),
 })
 
+// Activate only the best-ranked matches. Top-5 is the literature's sweet
+// spot (retrieval at k=5 matches oracle toolsets) and bounds how much
+// schema weight a single search can add to every subsequent iteration —
+// each activation also busts the prompt-cache prefix once.
+const ACTIVATION_TOP_K = 5
+
+// Near-misses are reported name+hint WITHOUT activating, so a retrieval
+// miss becomes one cheap re-query instead of a dead end (the fixed-top-k
+// hard-tail failure mode: the right tool ranked 6th-10th).
+const NEAR_MISS_LIMIT = 5
+
 export const SearchToolsTool = defineTool({
 	name: 'search_tools',
 	description:
@@ -26,25 +38,48 @@ export const SearchToolsTool = defineTool({
 			}
 		}
 
-		const matches = context.toolRegistry.searchDeferred(input.query)
+		const allowed =
+			context.allowedTools && context.allowedTools.length > 0 ? new Set(context.allowedTools) : null
+		// `searchDeferred` returns a ranked list (score-descending), so slicing
+		// the head is a true top-k activation, not an arbitrary subset.
+		const ranked = context.toolRegistry
+			.searchDeferred(input.query)
+			.filter((tool) => !allowed || allowed.has(tool.name))
 
-		if (matches.length === 0) {
+		if (ranked.length === 0) {
 			return {
 				success: true,
 				output: `No deferred tools matching "${input.query}". All matching tools are already active.`,
 			}
 		}
 
-		context.toolRegistry.activate(matches.map((t) => t.name))
+		const activated = ranked.slice(0, ACTIVATION_TOP_K)
+		const nearMisses = ranked.slice(ACTIVATION_TOP_K, ACTIVATION_TOP_K + NEAR_MISS_LIMIT)
+
+		context.toolRegistry.activate(activated.map((t) => t.name))
 
-		const descriptions = matches.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+		const descriptions = activated.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+		const sections = [`Activated ${activated.length} tool(s):\n${descriptions}`]
+
+		if (nearMisses.length > 0) {
+			const hints = nearMisses
+				.map((t) => {
+					const hint = toolDiscoveryHint(t.description)
+					return hint.length > 0 ? `- ${t.name}: ${hint}` : `- ${t.name}`
+				})
+				.join('\n')
+			sections.push(
+				`Also matched but NOT loaded (search again with a more specific query, e.g. the tool name, to load one of these):\n${hints}`,
+			)
+		}
 
 		return {
 			success: true,
-			output: `Activated ${matches.length} tool(s):\n${descriptions}`,
+			output: sections.join('\n\n'),
 			data: {
-				activated: matches.map((t) => t.name),
-				count: matches.length,
+				activated: activated.map((t) => t.name),
+				count: activated.length,
+				nearMisses: nearMisses.map((t) => t.name),
 			},
 		}
 	},

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)
+	})
+})