@namzu/sdk 2.0.0 → 3.0.0

package/src/tools/__tests__/path-containment.test.ts

@@ -0,0 +1,167 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { ToolContext } from '../../types/tool/index.js'
+import { GlobTool } from '../builtins/glob.js'
+import { GrepTool } from '../builtins/grep.js'
+import { LsTool } from '../builtins/ls.js'
+import { matchesGlob } from '../glob-match.js'
+import { resolveWithin } from '../paths.js'
+
+/**
+ * The containment rule existed — in one private function inside the local
+ * sandbox provider — and the filesystem tools never reached it. They
+ * resolved a caller-supplied path against the working directory bare, so
+ * `path: "../../.."` landed wherever that pointed and the tool read it
+ * happily.
+ *
+ * That holds with no sandbox configured at all, which is the common case,
+ * so the escape needed no misconfiguration to reach: a model that asks for
+ * a parent directory gets one. And `grep` returns file CONTENT, so what
+ * escaped was not a listing.
+ */
+
+let root: string
+let outside: string
+
+beforeEach(() => {
+	const base = mkdtempSync(join(tmpdir(), 'namzu-containment-'))
+	root = join(base, 'workspace')
+	outside = join(base, 'secrets')
+	mkdirSync(root, { recursive: true })
+	mkdirSync(outside, { recursive: true })
+	writeFileSync(join(root, 'inside.ts'), 'const inside = true\n')
+	writeFileSync(join(outside, 'credentials.txt'), 'SECRET_TOKEN=hunter2\n')
+})
+
+afterEach(() => {
+	rmSync(resolve(root, '..'), { recursive: true, force: true })
+})
+
+const context = (): ToolContext =>
+	({
+		workingDirectory: root,
+		env: {},
+		abortSignal: new AbortController().signal,
+	}) as unknown as ToolContext
+
+describe('resolveWithin', () => {
+	it('accepts a path inside the root', () => {
+		expect(resolveWithin('/work', 'src/a.ts')).toBe(resolve('/work/src/a.ts'))
+	})
+
+	it('treats an absent path as the root itself', () => {
+		expect(resolveWithin('/work', undefined)).toBe(resolve('/work'))
+	})
+
+	it('refuses a climb out', () => {
+		expect(() => resolveWithin('/work', '../../..')).toThrow(/escapes the working directory/)
+	})
+
+	it('refuses an absolute path elsewhere', () => {
+		expect(() => resolveWithin('/work', '/etc/passwd')).toThrow(/escapes the working directory/)
+	})
+
+	it('refuses a sibling that merely shares a prefix', () => {
+		// A `startsWith` test would call this inside, which is the whole
+		// reason the check uses `relative`.
+		expect(() => resolveWithin('/work', '../work-backup')).toThrow(/escapes/)
+	})
+
+	it('allows a climb that lands back inside', () => {
+		expect(resolveWithin('/work', 'src/../lib/a.ts')).toBe(resolve('/work/lib/a.ts'))
+	})
+})
+
+describe('glob', () => {
+	it('refuses a path that climbs out', async () => {
+		const result = await GlobTool.execute(
+			{ pattern: '*.txt', path: '../secrets' } as never,
+			context(),
+		)
+		// A refusal reaches the model as a failed tool result rather than a
+		// throw, so it can read WHY and correct itself.
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/escapes the working directory/)
+	})
+
+	it('refuses an escape hidden in the pattern', async () => {
+		// The base directory lifted out of a pattern is caller-supplied too.
+		const result = await GlobTool.execute({ pattern: '../secrets/**/*.txt' } as never, context())
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/escapes the working directory/)
+	})
+
+	it('still finds what is inside', async () => {
+		const result = await GlobTool.execute({ pattern: '**/*.ts' } as never, context())
+		expect(result.success).toBe(true)
+		expect(result.output).toContain('inside.ts')
+	})
+})
+
+describe('grep', () => {
+	it('refuses a path that climbs out', async () => {
+		const result = await GrepTool.execute(
+			{
+				pattern: 'SECRET',
+				path: '../secrets',
+				case_sensitive: true,
+				context_lines: 0,
+				max_results: 10,
+			} as never,
+			context(),
+		)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/escapes the working directory/)
+		expect(JSON.stringify(result)).not.toContain('hunter2')
+	})
+
+	it('never returns content from outside the working directory', async () => {
+		const result = await GrepTool.execute(
+			{ pattern: 'SECRET', case_sensitive: true, context_lines: 0, max_results: 50 } as never,
+			context(),
+		)
+		// grep returns file CONTENT, so an escape here reads rather than lists.
+		expect(result.output).not.toContain('hunter2')
+	})
+
+	it('still finds what is inside', async () => {
+		const result = await GrepTool.execute(
+			{ pattern: 'inside', case_sensitive: true, context_lines: 0, max_results: 50 } as never,
+			context(),
+		)
+		expect(result.output).toContain('inside.ts')
+	})
+})
+
+describe('ls', () => {
+	it('refuses a path that climbs out', async () => {
+		const result = await LsTool.execute({ path: '../secrets' } as never, context())
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/escapes the working directory/)
+	})
+})
+
+describe('glob matching', () => {
+	it.each([
+		['**/*.ts', 'src/a.ts', true],
+		['**/*.ts', 'a.ts', true],
+		['*.ts', 'a.ts', true],
+		['*.ts', 'src/a.ts', false],
+		['src/*.ts', 'src/a.ts', true],
+		['src/*.ts', 'src/deep/a.ts', false],
+		['**/*.ts', 'a.tsx', false],
+		['a?.ts', 'ab.ts', true],
+		['a?.ts', 'abc.ts', false],
+	])('%s vs %s', (pattern, path, expected) => {
+		expect(matchesGlob(path, pattern)).toBe(expected)
+	})
+
+	it('treats regex punctuation in a pattern as literal', () => {
+		// A pattern is not a regex; `a.b` must not match `axb`.
+		expect(matchesGlob('a.b.ts', 'a.b.ts')).toBe(true)
+		expect(matchesGlob('axb.ts', 'a.b.ts')).toBe(false)
+	})
+})

package/src/tools/__tests__/posix-path.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+
+import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js'
+
+/**
+ * A sandbox is a POSIX filesystem whatever the host runs, so resolving its
+ * paths with the host's path module rewrites them whenever the two
+ * disagree — on a Windows host `resolve('/workspace')` becomes
+ * `C:\workspace`, and a container path stops being a container path. The
+ * tool then hands the model a string its own sandbox cannot open.
+ *
+ * Found while testing the sandboxed search: the fake sandbox returned
+ * nothing at all, because the paths it was asked for had been rewritten
+ * into host shape on the way through.
+ */
+
+describe('joinPosix', () => {
+	it('joins and keeps the leading slash', () => {
+		expect(joinPosix('/work', 'src', 'a.ts')).toBe('/work/src/a.ts')
+	})
+
+	it('normalises . and ..', () => {
+		expect(joinPosix('/work', 'src/../lib/a.ts')).toBe('/work/lib/a.ts')
+	})
+
+	it('collapses repeated separators', () => {
+		expect(joinPosix('/work//', '/src//a.ts')).toBe('/work/src/a.ts')
+	})
+
+	it('leaves a relative base relative', () => {
+		expect(joinPosix('work', 'a.ts')).toBe('work/a.ts')
+	})
+
+	it('never produces a host-shaped path', () => {
+		// The whole point: this must not become `C:\work\a.ts` anywhere.
+		expect(joinPosix('/work', 'a.ts')).not.toContain('\\')
+	})
+})
+
+describe('relativePosix', () => {
+	it('strips a shared prefix', () => {
+		expect(relativePosix('/work', '/work/src/a.ts')).toBe('src/a.ts')
+	})
+
+	it('returns empty for the root itself', () => {
+		expect(relativePosix('/work', '/work')).toBe('')
+	})
+
+	it('climbs out when it has to', () => {
+		expect(relativePosix('/work/src', '/work/lib/a.ts')).toBe('../lib/a.ts')
+	})
+
+	it('does not treat a prefix-sharing sibling as inside', () => {
+		expect(relativePosix('/work', '/work-backup/a.ts').startsWith('..')).toBe(true)
+	})
+})
+
+describe('resolveWithinPosix', () => {
+	it('accepts a path inside the root', () => {
+		expect(resolveWithinPosix('/work', 'src/a.ts')).toBe('/work/src/a.ts')
+	})
+
+	it('treats an absent path as the root', () => {
+		expect(resolveWithinPosix('/work', undefined)).toBe('/work')
+	})
+
+	it('refuses a climb out', () => {
+		expect(() => resolveWithinPosix('/work', '../../etc')).toThrow(/escapes the working directory/)
+	})
+
+	it('refuses a prefix-sharing sibling', () => {
+		expect(() => resolveWithinPosix('/work', '../work-backup')).toThrow(/escapes/)
+	})
+
+	it('takes an absolute candidate as sandbox-absolute', () => {
+		expect(resolveWithinPosix('/work', '/work/src')).toBe('/work/src')
+		expect(() => resolveWithinPosix('/work', '/etc/passwd')).toThrow(/escapes/)
+	})
+
+	it('allows a climb that lands back inside', () => {
+		expect(resolveWithinPosix('/work', 'src/../lib')).toBe('/work/lib')
+	})
+})

package/src/tools/__tests__/sandboxed-search.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { Sandbox } from '../../types/sandbox/index.js'
+import type { ToolContext } from '../../types/tool/index.js'
+import { GlobTool } from '../builtins/glob.js'
+import { GrepTool } from '../builtins/grep.js'
+
+/**
+ * Both tools reached `node:fs` directly and referenced `context.sandbox`
+ * nowhere, so with a container backend wired in the sandbox was not a read
+ * boundary at all — every sibling builtin already remembered the branch.
+ *
+ * The paths they returned were host-relative too, while `read` resolves
+ * what it is handed INSIDE the sandbox, so every search-to-read handoff
+ * either failed or opened a different file. The two roots genuinely
+ * diverge: the executor passes `workingDirectory` unchanged alongside the
+ * sandbox and never re-points it at `sandbox.rootDir`.
+ */
+
+const SANDBOX_ROOT = '/sandbox/workspace'
+const HOST_ROOT = '/host/elsewhere'
+
+function fakeSandbox(files: Record<string, string>): Sandbox & { reads: string[] } {
+	const reads: string[] = []
+	return {
+		id: 'sbx_test' as never,
+		rootDir: SANDBOX_ROOT,
+		reads,
+		exec: vi.fn(),
+		writeFile: vi.fn(),
+		readFile: vi.fn(async (path: string) => {
+			reads.push(path)
+			const key = path.startsWith(SANDBOX_ROOT) ? path.slice(SANDBOX_ROOT.length + 1) : path
+			const content = files[key.split('\\').join('/')]
+			if (content === undefined) throw new Error(`no such file: ${path}`)
+			return Buffer.from(content, 'utf-8')
+		}),
+		listFiles: vi.fn(async () =>
+			Object.keys(files).map((path) => ({ path, size: files[path]?.length ?? 0 })),
+		),
+		destroy: vi.fn(),
+		status: vi.fn(),
+	} as unknown as Sandbox & { reads: string[] }
+}
+
+const context = (sandbox: Sandbox): ToolContext =>
+	({
+		// Deliberately different from the sandbox root: the executor passes
+		// the host working directory through unchanged, so a tool that
+		// reads this one is reading the wrong filesystem.
+		workingDirectory: HOST_ROOT,
+		sandbox,
+		env: {},
+		abortSignal: new AbortController().signal,
+	}) as unknown as ToolContext
+
+describe('glob inside a sandbox', () => {
+	it('enumerates through the sandbox, not the host', async () => {
+		const sandbox = fakeSandbox({ 'src/a.ts': 'a', 'src/b.js': 'b' })
+		const result = await GlobTool.execute({ pattern: '**/*.ts' } as never, context(sandbox))
+
+		expect(sandbox.listFiles).toHaveBeenCalled()
+		expect(result.output).toContain('src/a.ts')
+		expect(result.output).not.toContain('b.js')
+	})
+
+	it('returns paths the sandbox-side reader can actually open', async () => {
+		const sandbox = fakeSandbox({ 'src/a.ts': 'a' })
+		const result = await GlobTool.execute({ pattern: '**/*.ts' } as never, context(sandbox))
+
+		// A host-relative path here is a string `read` resolves somewhere
+		// else, so the handoff between the two tools has to agree on a
+		// coordinate system.
+		expect(result.output).not.toContain(HOST_ROOT)
+		expect(result.output.trim()).toBe('./src/a.ts')
+	})
+
+	it('says it searched the sandbox', async () => {
+		const sandbox = fakeSandbox({ 'a.ts': 'a' })
+		const result = await GlobTool.execute({ pattern: '**/*.ts' } as never, context(sandbox))
+		expect((result.data as { sandboxed?: boolean }).sandboxed).toBe(true)
+	})
+
+	it('refuses a path that climbs out of the sandbox root', async () => {
+		const sandbox = fakeSandbox({ 'a.ts': 'a' })
+		const result = await GlobTool.execute(
+			{ pattern: '*.ts', path: '../../etc' } as never,
+			context(sandbox),
+		)
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/escapes the working directory/)
+	})
+})
+
+describe('grep inside a sandbox', () => {
+	const args = (extra: object = {}) =>
+		({
+			pattern: 'needle',
+			case_sensitive: true,
+			context_lines: 0,
+			max_results: 50,
+			...extra,
+		}) as never
+
+	it('reads through the sandbox, not the host', async () => {
+		const sandbox = fakeSandbox({ 'src/a.ts': 'a needle here\n' })
+		const result = await GrepTool.execute(args(), context(sandbox))
+
+		expect(sandbox.readFile).toHaveBeenCalled()
+		// Asserted on the MATCH line, not on the word. The no-matches
+		// message quotes the pattern back, so checking for "needle" alone
+		// passed on a search that found nothing — which is exactly what this
+		// test existed to catch.
+		expect(result.output).toContain('a needle here')
+		expect(result.output).toContain('Found 1 match')
+	})
+
+	it('reports paths relative to the sandbox root', async () => {
+		const sandbox = fakeSandbox({ 'src/a.ts': 'a needle here\n' })
+		const result = await GrepTool.execute(args(), context(sandbox))
+
+		expect(result.output).toContain('./src/a.ts')
+		expect(result.output).not.toContain(HOST_ROOT)
+	})
+
+	it('honours the include filter through the sandbox listing', async () => {
+		const sandbox = fakeSandbox({ 'a.ts': 'needle\n', 'b.md': 'needle\n' })
+		const result = await GrepTool.execute(args({ include: '*.ts' }), context(sandbox))
+
+		expect(result.output).toContain('a.ts')
+		expect(result.output).not.toContain('b.md')
+	})
+
+	it('refuses a path that climbs out of the sandbox root', async () => {
+		const sandbox = fakeSandbox({ 'a.ts': 'needle\n' })
+		const result = await GrepTool.execute(args({ path: '../../etc' }), context(sandbox))
+		expect(result.success).toBe(false)
+		expect(result.error).toMatch(/escapes the working directory/)
+	})
+})

package/src/tools/builtins/__tests__/computer-use.test.ts

@@ -133,16 +133,29 @@ describe('createComputerUseTool', () => {
 		expect(calls).toHaveLength(0)
 	})
 
-	it('returns base64 PNG output for screenshot', async () => {
+	it('returns the screenshot as an image BLOCK, not as base64 text', async () => {
 		const { host } = makeHost()
 		const tool = createComputerUseTool(host)
 
 		const result = await tool.execute({ type: 'screenshot' }, makeContext())
 
 		expect(result.success).toBe(true)
-		expect(Buffer.from(result.output, 'base64').slice(0, 4)).toEqual(
+
+		// `output` used to BE the base64 payload, so the model received
+		// hundreds of thousands of tokens of undecodable characters and
+		// could not see the screen at all. It is now a short description.
+		expect(result.output).toContain('1920x1080')
+		expect(result.output.length).toBeLessThan(200)
+
+		const blocks = result.content
+		expect(Array.isArray(blocks)).toBe(true)
+		const image = (blocks as Array<{ type: string; data?: string; mediaType?: string }>)[0]
+		expect(image?.type).toBe('image')
+		expect(image?.mediaType).toBe('image/png')
+		expect(Buffer.from(image?.data ?? '', 'base64').subarray(0, 4)).toEqual(
 			Buffer.from([0x89, 0x50, 0x4e, 0x47]),
 		)
+
 		expect(result.data).toMatchObject({
 			mimeType: 'image/png',
 			width: 1920,