@namzu/sdk 2.0.0 → 3.1.0

package/src/runtime/query/tool-output-budget.ts

@@ -0,0 +1,183 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Model-visible size cap for a single tool result.
+ *
+ * ~40k characters is roughly 10k tokens: large enough that ordinary reads,
+ * greps and command output pass through untouched, small enough that one
+ * oversized result cannot consume a fifth of a 200k window.
+ *
+ * Nothing capped tool output before this. `read` returned a whole file when
+ * `limit` was omitted, `bash` allowed a 100 MB buffer, and the MCP adapter
+ * joined every text block uncapped — so a 2 MB lockfile became ~500k tokens
+ * in a single `tool_result` and the run died on a provider error with
+ * everything lost.
+ */
+export const DEFAULT_MAX_TOOL_OUTPUT_CHARS = 40_000
+
+/**
+ * Opening of the line that points at a spilled output.
+ *
+ * A constant rather than a phrase repeated in two files, because the line
+ * has to survive later editing: compaction clears stale tool results, and
+ * clearing a spilled one destroys the only route back to the content this
+ * budget deliberately kept. Whatever clears a result has to be able to
+ * recognise this line and keep it.
+ */
+export const SPILL_MARKER = 'The full output was written to:'
+
+/**
+ * Share of the budget spent on the head. The rest goes to the tail.
+ *
+ * Weighted toward the head because that is where a document's structure
+ * lives, but never all of it: the tail is where a command's error message
+ * is, and a preview that drops it is useless for the most common reason a
+ * result is being read at all.
+ */
+const HEAD_SHARE = 0.75
+
+export interface ToolOutputBudgetResult {
+	/** What the model sees. */
+	readonly output: string
+	/** Size before any reduction, for telemetry. */
+	readonly originalLength: number
+	readonly truncated: boolean
+	/** Where the full output was written, when it was. */
+	readonly spillPath?: string
+}
+
+/**
+ * Name what a truncated result took with it.
+ *
+ * Returns `undefined` when there was nothing but text to lose, so the
+ * ordinary case adds no noise.
+ *
+ * The model is the reader here, and it is reasoning about a result it can
+ * no longer fully see. "An image was returned and is not shown" is a fact
+ * it can act on — ask for a smaller region, re-run against a file — where
+ * silence looks exactly like a tool that only ever returns text.
+ */
+export function describeDroppedContent(
+	content: readonly { type?: string }[] | unknown,
+): string | undefined {
+	if (!Array.isArray(content)) return undefined
+
+	const counts = new Map<string, number>()
+	for (const block of content as readonly { type?: unknown }[]) {
+		const kind = typeof block?.type === 'string' ? block.type : 'content'
+		if (kind === 'text') continue
+		counts.set(kind, (counts.get(kind) ?? 0) + 1)
+	}
+	if (counts.size === 0) return undefined
+
+	const parts = [...counts].map(([kind, n]) => (n === 1 ? `1 ${kind}` : `${n} ${kind} blocks`))
+	return `[${parts.join(', ')} omitted: this result was truncated, and the preview above no longer describes them.]`
+}
+
+/**
+ * Total size of the rich channel, in base64 characters.
+ *
+ * Measured on the payload rather than the block count, because one block
+ * is the whole cost: a single screenshot is the largest thing a tool
+ * result can carry.
+ */
+export function measureContentBytes(content: readonly unknown[] | unknown): number {
+	if (!Array.isArray(content)) return 0
+	let total = 0
+	for (const block of content as readonly Record<string, unknown>[]) {
+		if (typeof block?.data === 'string') total += block.data.length
+		else if (typeof block?.text === 'string') total += block.text.length
+	}
+	return total
+}
+
+export interface ApplyToolOutputBudgetOptions {
+	readonly toolName: string
+	readonly toolUseId: string
+	readonly output: string
+	readonly maxChars: number
+	/**
+	 * Directory to spill overflow into. When absent the output is
+	 * middle-elided instead — degraded, but never unbounded.
+	 */
+	readonly spillDir?: string | undefined
+	readonly onError?: (message: string) => void
+}
+
+/**
+ * Bound a tool result to the model-visible budget.
+ *
+ * Spilling beats truncating on every axis that matters: nothing is lost,
+ * tokens are paid only if the agent decides the rest is worth re-reading,
+ * and retrieval uses `read`/`grep` — tools it already has — rather than a
+ * new affordance. A hosted agent runtime does the same thing above 100k
+ * characters. Middle-elision is the fallback for a run with no directory
+ * to write to.
+ *
+ * The preview keeps head AND tail because the two ends carry different
+ * information: the head has the schema/opening of a document, the tail has
+ * the error a command died on.
+ */
+export function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolOutputBudgetResult {
+	const { output, maxChars } = opts
+	const originalLength = output.length
+
+	if (!Number.isFinite(maxChars) || maxChars <= 0 || originalLength <= maxChars) {
+		return { output, originalLength, truncated: false }
+	}
+
+	// Both slices are derived from `maxChars` so the preview honours the
+	// budget it is enforcing. `slice(-0)` returns the WHOLE string, so the
+	// zero-tail case must be branched, not computed.
+	const headChars = Math.max(1, Math.floor(maxChars * HEAD_SHARE))
+	const tailChars = Math.max(0, maxChars - headChars)
+	const head = output.slice(0, headChars)
+	const tail = tailChars > 0 ? output.slice(-tailChars) : ''
+	const omitted = originalLength - head.length - tail.length
+
+	const spillPath = opts.spillDir
+		? spill(opts.spillDir, opts.toolUseId, output, opts.onError)
+		: undefined
+
+	const recovery = spillPath
+		? [
+				`${SPILL_MARKER} ${spillPath}`,
+				'Read a specific window with `read` (offset/limit) or search it with `grep`. Do NOT read it whole — that is what exceeded the budget.',
+			].join('\n')
+		: 'The full output was not retained. Re-run with a narrower query, a line range, or a filter.'
+
+	return {
+		output: [
+			head,
+			'',
+			`[... ${omitted.toLocaleString()} characters omitted — "${opts.toolName}" returned ${originalLength.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
+			recovery,
+			'',
+			tail,
+		].join('\n'),
+		originalLength,
+		truncated: true,
+		...(spillPath ? { spillPath } : {}),
+	}
+}
+
+function spill(
+	dir: string,
+	toolUseId: string,
+	content: string,
+	onError?: (message: string) => void,
+): string | undefined {
+	try {
+		mkdirSync(dir, { recursive: true })
+		// The tool_use id is already unique per call and safe as a filename.
+		const path = join(dir, `${toolUseId}.txt`)
+		writeFileSync(path, content, 'utf-8')
+		return path
+	} catch (err) {
+		// A spill failure must never fail the tool call — the model still
+		// gets the preview, just without a path to recover the rest.
+		onError?.(err instanceof Error ? err.message : String(err))
+		return undefined
+	}
+}

package/src/runtime/query/tool-pause.ts

@@ -0,0 +1,119 @@
+import type { HITLResumeDecision, ResumeHandler, UserQuestionData } from '../../types/hitl/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { RequestToolPause, ToolPauseRequest } from '../../types/tool/index.js'
+import type { PendingAnswers, QuestionParkRecorder } from './question-park.js'
+
+/**
+ * The durable pause, made reachable from any tool.
+ *
+ * The machinery was excellent and reachable from exactly four
+ * kernel-owned points: the plan gate, the tool-review gate, the iteration
+ * cadence, and one built-in question tool. A host-authored tool — the
+ * spend, the outbound post, the destructive migration, the operations
+ * that most want their OWN confirmation with their OWN wording — had no
+ * seam to it. The only route was to hand-thread a recorder and a resume
+ * callback into a private tool builder, mirroring what the coordinator
+ * does, and nothing in the type a tool author is handed suggested that
+ * was possible.
+ *
+ * This is that same machinery behind a function on `ToolContext`. Nothing
+ * new is invented: the park is a real checkpoint, the answer routes back
+ * on resume, and a pause is inert outside a run that supports one.
+ */
+
+/**
+ * Identity of one pause.
+ *
+ * `<toolUseId>:<name>` rather than the tool-use id alone, because the id
+ * identifies the CALL and a call may pause more than once — "which
+ * environment" then "are you sure". Keying on the call would make the
+ * second answer arrive against the first question. The name is the tool
+ * author's, so a resume payload can name what it is answering.
+ */
+export const pauseId = (toolUseId: string, name: string): string => `${toolUseId}:${name}`
+
+interface ToolPauseDeps {
+	readonly runId: RunId
+	readonly toolUseId: string
+	readonly parkHandler: ResumeHandler
+	readonly recorder?: QuestionParkRecorder
+	readonly pendingAnswers?: PendingAnswers
+}
+
+function toQuestion(request: ToolPauseRequest, id: string): UserQuestionData {
+	return {
+		questionId: id,
+		question: request.prompt,
+		...(request.header !== undefined ? { header: request.header } : {}),
+		options: (request.options ?? []).map((option) => ({
+			id: option.id,
+			label: option.label,
+			...(option.description !== undefined ? { description: option.description } : {}),
+		})),
+		multiSelect: request.multiSelect ?? false,
+		allowFreeText: request.allowFreeText ?? true,
+	}
+}
+
+/**
+ * An unanswered pause is NOT consent.
+ *
+ * The same rule the built-in question tool follows, and for the same
+ * reason: a tool that pauses to ask "may I charge this card" and reads
+ * silence as yes is worse than one that never asked.
+ */
+const unanswered = (reason: string) => ({ status: 'unanswered' as const, reason })
+
+export function createToolPause(deps: ToolPauseDeps): RequestToolPause {
+	return async (request) => {
+		const id = pauseId(deps.toolUseId, request.name)
+
+		// An answer carried in from a resumed run, checked BEFORE parking.
+		// Re-entering the tool is how the answer gets delivered — the batch
+		// re-executes — so without this the resume would ask a human
+		// something they already answered, or headlessly discard it.
+		const carried = deps.pendingAnswers?.take(id)
+
+		const question = toQuestion(request, id)
+		const parkedAt =
+			carried === undefined && deps.recorder ? await deps.recorder.record(question) : null
+
+		const decision: HITLResumeDecision =
+			carried ??
+			(await deps.parkHandler({
+				type: 'user_question',
+				runId: deps.runId,
+				checkpointId: parkedAt ?? `cp_pause_${id}`,
+				question,
+			}))
+
+		if (parkedAt !== null && deps.recorder) {
+			await deps.recorder.resolve(parkedAt, decision)
+		}
+
+		if (decision.action === 'abort') return { status: 'aborted' }
+		if (decision.action !== 'answer_question') {
+			return unanswered('the pause was resolved without an answer')
+		}
+		if (decision.questionId !== undefined && decision.questionId !== id) {
+			// Misdirection guard. Host queues are keyed by run, so a stale
+			// client can answer pause N after pause N+1 opened under the same
+			// run. Answering the wrong question is worse than not answering.
+			return unanswered('the answer was addressed to a different pause')
+		}
+
+		const known = new Set((request.options ?? []).map((option) => option.id))
+		const selectedOptionIds = decision.selectedOptionIds.filter((selected) => known.has(selected))
+		const freeText = decision.freeText
+
+		if (selectedOptionIds.length === 0 && (freeText === undefined || freeText.length === 0)) {
+			return unanswered('the answer selected nothing and said nothing')
+		}
+
+		return {
+			status: 'answered',
+			selectedOptionIds,
+			...(freeText !== undefined && freeText.length > 0 ? { text: freeText } : {}),
+		}
+	}
+}

package/src/runtime/query/tooling.ts

@@ -4,7 +4,8 @@ import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { RunEvent } from '../../types/run/index.js'
-import type { ToolRegistryContract } from '../../types/tool/index.js'
+import type { RequestToolPause, ToolRegistryContract } from '../../types/tool/index.js'
+import type { RepairToolCall } from '../../types/tool/repair.js'
 import type { Logger } from '../../utils/logger.js'
 import { ToolExecutor } from './executor.js'
 
@@ -20,6 +21,14 @@ export interface ToolingBootstrapConfig {
 	allowedTools?: readonly string[]
 	invocationState?: InvocationState
 	pluginManager?: PluginLifecycleManager
+	toolTimeoutMs?: number
+	maxToolConcurrency?: number
+	maxToolOutputChars?: number
+	maxToolContentBytes?: number
+	toolOutputDir?: string
+	repairToolCall?: RepairToolCall
+	/** Builds the durable-pause seam for one tool call; see ToolContext.requestPause. */
+	toolPause?: (toolUseId: string) => RequestToolPause
 }
 
 export class ToolingBootstrap {
@@ -40,6 +49,19 @@ export class ToolingBootstrap {
 				allowedTools: config.allowedTools,
 				invocationState: config.invocationState,
 				pluginManager: config.pluginManager,
+				...(config.toolTimeoutMs !== undefined ? { toolTimeoutMs: config.toolTimeoutMs } : {}),
+				...(config.maxToolConcurrency !== undefined
+					? { maxToolConcurrency: config.maxToolConcurrency }
+					: {}),
+				...(config.maxToolOutputChars !== undefined
+					? { maxToolOutputChars: config.maxToolOutputChars }
+					: {}),
+				...(config.maxToolContentBytes !== undefined
+					? { maxToolContentBytes: config.maxToolContentBytes }
+					: {}),
+				...(config.toolOutputDir !== undefined ? { toolOutputDir: config.toolOutputDir } : {}),
+				...(config.repairToolCall !== undefined ? { repairToolCall: config.repairToolCall } : {}),
+				...(config.toolPause !== undefined ? { toolPause: config.toolPause } : {}),
 			},
 			activityStore,
 			emitEvent,

package/src/sandbox/__tests__/isolation.test.ts

@@ -0,0 +1,164 @@
+import { afterAll, describe, expect, it, vi } from 'vitest'
+
+import type { SandboxEnvironment } from '../../types/sandbox/index.js'
+import { SANDBOX_ISOLATION_CONTROLS } from '../../types/sandbox/index.js'
+import { assertIsolation, describeIsolation, isolationOf, missingIsolation } from '../isolation.js'
+
+/**
+ * The provider reported `id = 'local'` / `name = 'Local Sandbox'` at every
+ * tier, and construction logged at `info` regardless. A host that turned
+ * isolation on deliberately got a tier-dependent amount of it under one
+ * undifferentiated name, with no signal saying which controls were live.
+ *
+ * These tests pin the honest table and the refusal. What must NOT hold is
+ * as important as what must: the tier that unshares a mount namespace
+ * without remounting anything does not confine the filesystem, and saying
+ * it does here would reintroduce exactly the defect being fixed.
+ */
+
+describe('what each tier actually enforces', () => {
+	it('reports full enforcement only where a deny-default profile is installed', () => {
+		expect(isolationOf('macos-seatbelt')).toEqual({
+			filesystem: true,
+			network: true,
+			process: true,
+		})
+	})
+
+	it('does not claim filesystem confinement from an unshared mount namespace', () => {
+		// A private mount table is not confinement: nothing is remounted, so
+		// the child still sees the whole host filesystem.
+		expect(isolationOf('linux-namespace').filesystem).toBe(false)
+		expect(isolationOf('linux-namespace').process).toBe(true)
+	})
+
+	it('claims nothing at all for the unconfined tier', () => {
+		const report = isolationOf('basic')
+		expect(Object.values(report)).toEqual([false, false, false])
+	})
+
+	it('covers every environment the type admits', () => {
+		const environments: SandboxEnvironment[] = ['linux-namespace', 'macos-seatbelt', 'basic']
+		for (const environment of environments) {
+			const report = isolationOf(environment)
+			for (const control of SANDBOX_ISOLATION_CONTROLS) {
+				expect(typeof report[control]).toBe('boolean')
+			}
+		}
+	})
+})
+
+describe('requiring a control', () => {
+	it('lets through what the tier can enforce', () => {
+		expect(() => assertIsolation('macos-seatbelt', ['filesystem', 'network'])).not.toThrow()
+		expect(() => assertIsolation('linux-namespace', ['network', 'process'])).not.toThrow()
+	})
+
+	it('refuses rather than downgrading', () => {
+		expect(() => assertIsolation('linux-namespace', ['filesystem'])).toThrow(
+			/cannot enforce filesystem/,
+		)
+		expect(() => assertIsolation('basic', ['network'])).toThrow(/cannot enforce network/)
+	})
+
+	it('says what it does enforce, so the refusal is actionable', () => {
+		expect(() => assertIsolation('linux-namespace', ['filesystem'])).toThrow(
+			/Enforced here: network, process/,
+		)
+		expect(() => assertIsolation('basic', ['process'])).toThrow(/Enforced here: nothing/)
+	})
+
+	it('names every missing control, not just the first', () => {
+		expect(missingIsolation('basic', ['filesystem', 'network', 'process'])).toEqual([
+			'filesystem',
+			'network',
+			'process',
+		])
+	})
+
+	it('requires nothing by default, so best-effort callers are unaffected', () => {
+		expect(() => assertIsolation('basic', [])).not.toThrow()
+	})
+})
+
+describe('describing a tier', () => {
+	it.each([
+		['macos-seatbelt', 'filesystem, network, process'],
+		['linux-namespace', 'network, process'],
+		['basic', 'nothing'],
+	] as const)('%s enforces %s', (environment, expected) => {
+		expect(describeIsolation(environment)).toBe(expected)
+	})
+})
+
+describe('the provider', () => {
+	// `process.platform` is a per-worker global, and vitest reuses workers
+	// across files — leaving it patched would make an unrelated file's
+	// platform check answer for this one.
+	const realPlatform = Object.getOwnPropertyDescriptor(process, 'platform')
+
+	afterAll(() => {
+		if (realPlatform) Object.defineProperty(process, 'platform', realPlatform)
+		vi.doUnmock('node:child_process')
+		vi.resetModules()
+	})
+
+	async function providerWith(environment: SandboxEnvironment) {
+		vi.resetModules()
+		vi.doMock('node:child_process', async () => {
+			const actual =
+				await vi.importActual<typeof import('node:child_process')>('node:child_process')
+			return {
+				...actual,
+				execSync: (command: string) => {
+					const wanted = environment === 'linux-namespace' ? 'unshare' : 'sandbox-exec'
+					if (environment !== 'basic' && command.startsWith(wanted)) return Buffer.alloc(0)
+					throw new Error('not available')
+				},
+			}
+		})
+		Object.defineProperty(process, 'platform', {
+			value: environment === 'macos-seatbelt' ? 'darwin' : 'linux',
+			configurable: true,
+		})
+		return await import('../provider/local.js')
+	}
+
+	const logger = () => {
+		const calls: Array<{ level: string; message: string }> = []
+		const log = {
+			calls,
+			child: () => log,
+			debug: () => {},
+			info: (message: string) => calls.push({ level: 'info', message }),
+			warn: (message: string) => calls.push({ level: 'warn', message }),
+			error: () => {},
+		}
+		return log
+	}
+
+	it('warns, not informs, when it confines nothing', async () => {
+		const { LocalSandboxProvider } = await providerWith('basic')
+		const log = logger()
+		new LocalSandboxProvider(log as never)
+
+		// `info` here reads as "sandbox created" to anyone scanning a log.
+		expect(log.calls.some((c) => c.level === 'warn' && /unconfined/.test(c.message))).toBe(true)
+		expect(log.calls.some((c) => c.level === 'info')).toBe(false)
+	})
+
+	it('throws at construction when a required control is unavailable', async () => {
+		const { LocalSandboxProvider } = await providerWith('basic')
+		expect(
+			() => new LocalSandboxProvider(logger() as never, { requireIsolation: ['filesystem'] }),
+		).toThrow(/cannot enforce filesystem/)
+	})
+
+	it('constructs when the tier supplies what was asked for', async () => {
+		const { LocalSandboxProvider } = await providerWith('macos-seatbelt')
+		const provider = new LocalSandboxProvider(logger() as never, {
+			requireIsolation: ['filesystem', 'network'],
+		})
+		expect(provider.environment).toBe('macos-seatbelt')
+	})
+})

package/src/sandbox/__tests__/output-truncation.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+
+import { CappedStream } from '../provider/local.js'
+
+/**
+ * `SandboxExecResult` carries `stdoutTruncated` / `stderrTruncated`, added
+ * when the other backend needed to report a clipped stream. The local
+ * backend clipped at the same cap and never set them, so the model read a
+ * complete-looking result whose tail was gone — against the contract's own
+ * note that the kernel does not truncate silently. The tool layer already
+ * renders the flag; nothing ever raised it.
+ */
+
+function push(stream: CappedStream, text: string): void {
+	stream.push(Buffer.from(text, 'utf-8'))
+}
+
+describe('a clipped stream says it was clipped', () => {
+	it('reports nothing truncated while under the cap', () => {
+		const stream = new CappedStream(10)
+		push(stream, 'abc')
+
+		expect(stream.text).toBe('abc')
+		expect(stream.truncated).toBe(false)
+	})
+
+	it('reports nothing truncated at exactly the cap', () => {
+		const stream = new CappedStream(4)
+		push(stream, 'abcd')
+
+		expect(stream.text).toBe('abcd')
+		// Everything arrived and everything was kept. A boundary that
+		// reported truncation here would cry wolf on every exact fit.
+		expect(stream.truncated).toBe(false)
+	})
+
+	it('reports truncated on the first byte past the cap', () => {
+		const stream = new CappedStream(4)
+		push(stream, 'abcde')
+
+		expect(stream.text).toBe('abcd')
+		expect(stream.truncated).toBe(true)
+	})
+
+	it('keeps the head across chunks and clips the rest', () => {
+		const stream = new CappedStream(5)
+		push(stream, 'abc')
+		push(stream, 'def')
+		push(stream, 'ghi')
+
+		expect(stream.text).toBe('abcde')
+		expect(stream.truncated).toBe(true)
+	})
+
+	it('stays truncated once it has been, however quiet the stream goes', () => {
+		const stream = new CappedStream(2)
+		push(stream, 'abcdef')
+		push(stream, '')
+
+		expect(stream.truncated).toBe(true)
+	})
+
+	it('is empty and untruncated before anything arrives', () => {
+		const stream = new CappedStream(8)
+
+		expect(stream.text).toBe('')
+		expect(stream.truncated).toBe(false)
+	})
+})
+
+describe('the sandbox hands the flag to its caller', () => {
+	it('marks a real over-cap run as truncated', async () => {
+		const { LocalSandboxProvider } = await import('../provider/local.js')
+		const { getRootLogger } = await import('../../utils/logger.js')
+		const { SANDBOX_MAX_OUTPUT_BYTES } = await import('../../constants/sandbox/index.js')
+
+		const sandbox = await new LocalSandboxProvider(getRootLogger()).create()
+		try {
+			const over = SANDBOX_MAX_OUTPUT_BYTES + 1024
+			const result = await sandbox.exec('node', ['-e', `process.stdout.write('a'.repeat(${over}))`])
+
+			expect(result.stdoutTruncated).toBe(true)
+			expect(result.stdout.length).toBe(SANDBOX_MAX_OUTPUT_BYTES)
+			// The other stream is untouched, so a clip on one must not be
+			// reported on both.
+			expect(result.stderrTruncated).toBe(false)
+		} finally {
+			await sandbox.destroy()
+		}
+	}, 30_000)
+
+	it('leaves an under-cap run unflagged', async () => {
+		const { LocalSandboxProvider } = await import('../provider/local.js')
+		const { getRootLogger } = await import('../../utils/logger.js')
+
+		const sandbox = await new LocalSandboxProvider(getRootLogger()).create()
+		try {
+			const result = await sandbox.exec('node', ['-e', "process.stdout.write('small')"])
+
+			expect(result.stdout).toBe('small')
+			expect(result.stdoutTruncated).toBe(false)
+		} finally {
+			await sandbox.destroy()
+		}
+	}, 30_000)
+})