@namzu/sdk 0.6.0 → 1.0.0

package/src/runtime/query/__tests__/executor-plugin-hooks.test.ts

@@ -18,7 +18,10 @@ function makeLogger(): Logger {
 		error: vi.fn(),
 		debug: vi.fn(),
 	}
-	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+	return {
+		...stub,
+		child: vi.fn(() => ({ ...stub, child: vi.fn() })),
+	} as unknown as Logger
 }
 
 function makeToolRegistry(execute: ToolRegistryContract['execute']): ToolRegistryContract {
@@ -93,6 +96,42 @@ describe('ToolExecutor plugin hooks', () => {
 		expect(batch.results[0]?.output).toBe('ok')
 	})
 
+	it('preserves tool stdout/stderr when a tool exits unsuccessfully', async () => {
+		const tools = makeToolRegistry(
+			vi.fn(async () => ({
+				success: false,
+				output: 'STDOUT:\npartial result\n\nSTDERR:\nboom',
+				error: 'Command exited with code 1',
+			})),
+		)
+		const exec = new ToolExecutor(
+			{
+				tools,
+				runId: mockRunId,
+				workingDirectory: '/tmp',
+				permissionMode: 'auto',
+				env: {},
+				abortSignal: new AbortController().signal,
+			},
+			activityStore,
+			emitEvent,
+			makeLogger(),
+		)
+
+		const batch = await exec.executeBatch(buildResponse('bash', { command: 'false' }))
+		expect(batch.results[0]?.output).toContain('STDOUT:\npartial result')
+		expect(batch.results[0]?.output).toContain('STDERR:\nboom')
+		expect(batch.results[0]?.output).toContain('Error: Command exited with code 1')
+
+		const completed = emitted.find((e) => e.type === 'tool_completed')
+		expect(completed).toMatchObject({
+			type: 'tool_completed',
+			toolName: 'bash',
+			result: expect.stringContaining('STDOUT:\npartial result'),
+			isError: true,
+		})
+	})
+
 	it('replaces input on pre_tool_use modify', async () => {
 		const executeMock = vi.fn(async () => ({ success: true, output: 'ok' }))
 		const tools = makeToolRegistry(executeMock)
@@ -120,7 +159,10 @@ describe('ToolExecutor plugin hooks', () => {
 	})
 
 	it('skips registry execution and synthesizes output on pre_tool_use skip', async () => {
-		const executeMock = vi.fn(async () => ({ success: true, output: 'should-not-run' }))
+		const executeMock = vi.fn(async () => ({
+			success: true,
+			output: 'should-not-run',
+		}))
 		const tools = makeToolRegistry(executeMock)
 		const pluginManager = makePluginManager(async (event) =>
 			event === 'pre_tool_use'
@@ -223,7 +265,10 @@ describe('ToolExecutor plugin hooks', () => {
 	})
 
 	it('carries modified input into synthetic skip outcome (modify -> skip chain)', async () => {
-		const executeMock = vi.fn(async () => ({ success: true, output: 'should-not-run' }))
+		const executeMock = vi.fn(async () => ({
+			success: true,
+			output: 'should-not-run',
+		}))
 		const tools = makeToolRegistry(executeMock)
 		const { PluginLifecycleManager } = await import('../../../plugin/lifecycle.js')
 		const realManager = new PluginLifecycleManager({

package/src/runtime/query/__tests__/prompt.test.ts

@@ -25,7 +25,7 @@ describe('PromptBuilder runtime context', () => {
 				label: 'test runtime',
 				outputDirectory: 'outputs/',
 				outputFileMarker: 'OUTPUT_FILE: <filename> - <description>',
-				notes: ['Mirror generated files after the turn.'],
+				notes: ['Register generated files after the turn.'],
 			},
 		}).build('full', '/tmp/work')
 
@@ -33,6 +33,55 @@ describe('PromptBuilder runtime context', () => {
 		expect(prompt).toContain('Working directory: /tmp/work')
 		expect(prompt).toContain('Output directory: outputs/')
 		expect(prompt).toContain('OUTPUT_FILE: <filename> - <description>')
-		expect(prompt).toContain('Mirror generated files after the turn.')
+		expect(prompt).toContain('Register generated files after the turn.')
+	})
+
+	it('discloses available skills even when the host supplies a systemPrompt', () => {
+		const prompt = new PromptBuilder({
+			systemPrompt: 'You are a project assistant.',
+			tools: makeToolRegistry(),
+			skills: [
+				{
+					metadata: {
+						name: 'project-documents',
+						description: 'Draft and edit project documents from grounded inputs.',
+					},
+					dirPath: '/repo/.agents/skills/project-documents',
+				},
+			],
+		}).build('full', '/tmp/work')
+
+		expect(prompt).toContain('You are a project assistant.')
+		expect(prompt).toContain('## Available Skills')
+		expect(prompt).toContain('project-documents')
+		expect(prompt).toContain('Draft and edit project documents')
+		expect(prompt).not.toContain('## Loaded Skills')
+	})
+
+	it('includes loaded skill bodies with systemPrompt while preserving the metadata catalogue', () => {
+		const prompt = new PromptBuilder({
+			systemPrompt: 'You are a cowork supervisor.',
+			tools: makeToolRegistry(),
+			skills: [
+				{
+					metadata: {
+						name: 'long-form-files',
+						description: 'Create long files with bounded edit chunks.',
+						license: 'MIT',
+						compatibility: 'Requires file tools',
+						allowedTools: 'read write edit',
+					},
+					body: 'Use skeleton-first writes and bounded edit chunks.',
+					dirPath: '/repo/.agents/skills/long-form-files',
+				},
+			],
+		}).build('full', '/tmp/work')
+
+		expect(prompt).toContain('## Available Skills')
+		expect(prompt).toContain('license: MIT')
+		expect(prompt).toContain('compatibility: Requires file tools')
+		expect(prompt).toContain('allowed-tools: read write edit')
+		expect(prompt).toContain('## Loaded Skills')
+		expect(prompt).toContain('Use skeleton-first writes')
 	})
 })

package/src/runtime/query/__tests__/stream-recovery.test.ts

@@ -0,0 +1,156 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type { LLMProvider, StreamChunk } from '../../../types/provider/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+class IdleDuringToolInputProvider implements LLMProvider {
+	readonly id = 'idle-during-tool-input'
+	readonly name = 'Idle During Tool Input Provider'
+	calls = 0
+
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		this.calls += 1
+
+		if (this.calls === 1) {
+			yield {
+				id: 'msg_1',
+				delta: {
+					toolCalls: [
+						{
+							index: 0,
+							id: 'toolu_write_1',
+							type: 'function',
+							function: { name: 'write_file' },
+						},
+					],
+				},
+			}
+			yield {
+				id: 'msg_1',
+				delta: {
+					toolCalls: [
+						{
+							index: 0,
+							id: 'toolu_write_1',
+							function: {
+								arguments: '{"path":"/tmp/out.md","content":"partial',
+							},
+						},
+					],
+				},
+			}
+			throw new Error('Anthropic stream idle for 90s')
+		}
+
+		yield {
+			id: 'msg_2',
+			delta: { content: 'Recovered after retry guidance.' },
+		}
+		yield {
+			id: 'msg_2',
+			delta: {},
+			finishReason: 'stop',
+			usage: ZERO_USAGE,
+		}
+	}
+}
+
+describe('query stream recovery', () => {
+	let workdirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+		workdirs = []
+	})
+
+	it('turns an idle stream with partial tool JSON into retryable tool feedback', async () => {
+		const provider = new IdleDuringToolInputProvider()
+		const actualWrite = vi.fn(async () => ({ success: true, output: 'should not run' }))
+		const tools = new ToolRegistry()
+		tools.register({
+			name: 'write_file',
+			description: 'write a file',
+			inputSchema: z.object({
+				path: z.string(),
+				content: z.string(),
+			}),
+			execute: actualWrite,
+		})
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-stream-recovery-'))
+		workdirs.push(workingDirectory)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				provider,
+				tools,
+				runConfig: {
+					model: 'mock-model',
+					timeoutMs: 5_000,
+					tokenBudget: 100_000,
+					maxIterations: 3,
+					maxResponseTokens: 256,
+				},
+				agentId: 'agent_test',
+				agentName: 'Test Agent',
+				messages: [createUserMessage('write the file')],
+				workingDirectory,
+				sessionId: 'ses_stream_recovery' as SessionId,
+				threadId: 'thd_stream_recovery' as ThreadId,
+				projectId: 'prj_stream_recovery' as ProjectId,
+				tenantId: 'tnt_stream_recovery' as TenantId,
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('completed')
+		expect(run.result).toBe('Recovered after retry guidance.')
+		expect(provider.calls).toBe(2)
+		expect(actualWrite).not.toHaveBeenCalled()
+
+		expect(events.some((event) => event.type === 'run_failed')).toBe(false)
+		expect(
+			events.some(
+				(event) =>
+					event.type === 'tool_input_completed' &&
+					event.inputTruncated === true &&
+					JSON.stringify(event.input) === '{}',
+			),
+		).toBe(true)
+		expect(JSON.stringify(events)).not.toContain('__namzuTruncated')
+
+		const completedTool = events.find(
+			(event) => event.type === 'tool_completed' && event.toolUseId === 'toolu_write_1',
+		)
+		expect(completedTool).toMatchObject({
+			type: 'tool_completed',
+			toolName: 'write_file',
+			isError: true,
+		})
+		expect(completedTool?.type === 'tool_completed' ? completedTool.result : '').toContain(
+			'call was cut off',
+		)
+		expect(completedTool?.type === 'tool_completed' ? completedTool.result : '').toContain(
+			'extend it with edit using insertLine',
+		)
+	})
+})

package/src/runtime/query/continuation.ts

@@ -0,0 +1,16 @@
+/**
+ * Synthetic user prompt injected by the iteration loop when a turn
+ * ends with `stop_reason: max_tokens` AND no tool_use. Mirrors
+ * Claude.ai's "Continue" affordance: the loop pushes this message
+ * back into the conversation and fires another iteration, letting
+ * the model pick up where it was cut off.
+ *
+ * The exact string is the marker used by `resolveResult` (in
+ * `manager/run/persistence.ts`) to detect auto-continuation
+ * boundaries: when walking the message tail it skips user messages
+ * that match this constant verbatim, so the run's `result` field
+ * concatenates the full multi-turn assistant output instead of only
+ * surfacing the trailing continuation chunk.
+ */
+export const AUTO_CONTINUATION_USER_MESSAGE =
+	'Continue exactly where you left off. Do not repeat content you already wrote — pick up at the next token.'

package/src/runtime/query/executor.ts

@@ -7,13 +7,18 @@ import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/r
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { InvocationState } from '../../types/invocation/index.js'
-import { type Message, createToolMessage } from '../../types/message/index.js'
+import { type Message, type ToolCall, createToolMessage } from '../../types/message/index.js'
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { PluginHookResult } from '../../types/plugin/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { Sandbox } from '../../types/sandbox/index.js'
-import type { ToolContext, ToolRegistryContract, ToolResult } from '../../types/tool/index.js'
+import type {
+	FileReadTracker,
+	ToolContext,
+	ToolRegistryContract,
+	ToolResult,
+} from '../../types/tool/index.js'
 import type { Logger } from '../../utils/logger.js'
 import { compressShellOutput } from '../../utils/shell-compress.js'
 
@@ -26,6 +31,7 @@ export interface ToolExecutorConfig {
 	permissionMode: PermissionMode
 	env: Record<string, string>
 	abortSignal: AbortSignal
+	allowedTools?: readonly string[]
 	sandbox?: Sandbox
 	invocationState?: InvocationState
 	pluginManager?: PluginLifecycleManager
@@ -48,6 +54,13 @@ export class ToolExecutor {
 	private log: Logger
 	private workingStateManager?: WorkingStateManager
 	private probes: ProbeRegistry
+	private readonly readPaths: Set<string> = new Set()
+	private readonly fileReadTracker: FileReadTracker = {
+		recordRead: (key: string) => {
+			this.readPaths.add(key)
+		},
+		hasRead: (key: string) => this.readPaths.has(key),
+	}
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -83,11 +96,38 @@ export class ToolExecutor {
 			tools: toolCalls.map((tc) => tc.function.name),
 		})
 
-		const toolContext = this.buildToolContext()
-
-		const results = await Promise.all(
-			toolCalls.map((toolCall) => this.executeSingle(toolCall, toolContext)),
-		)
+		// One context per call so each execution can see its own
+		// `toolUseId`. The base context is built once; we spread + add
+		// per-call to keep allocations cheap.
+		const baseContext = this.buildToolContext()
+
+		// Respect each tool's `concurrencySafe` flag. Read-only tools
+		// (ls/grep/glob/…) run in parallel; tools that mutate shared state
+		// (edit/write/append/bash — `concurrencySafe: false`) are serialized in
+		// a single chain, so e.g. several `edit` calls to the SAME file in one
+		// turn apply one-after-another instead of racing read→modify→write
+		// (which let the last writer clobber the rest). Results are written by
+		// index to preserve the original tool-call order.
+		const results: Array<{ toolCallId: string; output: string }> = new Array(toolCalls.length)
+		const parallel: Promise<void>[] = []
+		let serial: Promise<void> = Promise.resolve()
+		toolCalls.forEach((toolCall, i) => {
+			const ctx = { ...baseContext, toolUseId: toolCall.id }
+			const run = async () => {
+				results[i] = await this.executeSingle(toolCall, ctx)
+			}
+			let input: unknown = {}
+			try {
+				input = JSON.parse(toolCall.function.arguments || '{}')
+			} catch {
+				// non-JSON args → treat as unsafe (serialize), the conservative path
+			}
+			const safe =
+				this.config.tools.get(toolCall.function.name)?.isConcurrencySafe?.(input) === true
+			if (safe) parallel.push(run())
+			else serial = serial.then(run)
+		})
+		await Promise.all([...parallel, serial])
 
 		const messages: Message[] = results.map((r) => createToolMessage(r.output, r.toolCallId))
 
@@ -108,19 +148,38 @@ export class ToolExecutor {
 			},
 			invocationState: this.config.invocationState,
 			toolRegistry: this.config.tools,
+			allowedTools: this.config.allowedTools,
 			sandbox: this.config.sandbox,
+			fileReadTracker: this.fileReadTracker,
 		}
 	}
 
 	private async executeSingle(
-		toolCall: {
-			id: string
-			type: string
-			function: { name: string; arguments: string }
-		},
+		toolCall: ToolCall,
 		toolContext: ToolContext,
 	): Promise<{ toolCallId: string; output: string }> {
 		const toolName = toolCall.function.name
+
+		if (toolCall.metadata?.inputTruncated === true) {
+			const message = truncatedToolInputMessage(toolName)
+			await this.emitEvent({
+				type: 'tool_executing',
+				runId: this.config.runId,
+				toolUseId: toolCall.id,
+				toolName,
+				input: {},
+			})
+			await this.emitEvent({
+				type: 'tool_completed',
+				runId: this.config.runId,
+				toolUseId: toolCall.id,
+				toolName,
+				result: message,
+				isError: true,
+			})
+			return { toolCallId: toolCall.id, output: message }
+		}
+
 		let input: unknown
 
 		try {
@@ -238,7 +297,7 @@ export class ToolExecutor {
 
 		const rawOutput = result.success
 			? result.output
-			: `Error: ${result.error ?? 'Tool execution failed'}`
+			: formatFailedToolOutput(result.output, result.error)
 
 		let output = result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput
 
@@ -430,3 +489,13 @@ export class ToolExecutor {
 		return compressed
 	}
 }
+
+function formatFailedToolOutput(output: string | undefined, error: string | undefined): string {
+	const errorText = `Error: ${error ?? 'Tool execution failed'}`
+	if (!output || output.trim().length === 0) return errorText
+	return `${output}\n\n${errorText}`
+}
+
+function truncatedToolInputMessage(toolName: string): string {
+	return `Error: Tool "${toolName}" call was cut off while the model was streaming JSON arguments. The tool was NOT executed. Retry with a much shorter input. Self-budget any content/newStr payload under 12000 characters before calling file tools. For long files, create a short opening with write, then extend it with edit using insertLine: "end" in bounded section chunks; for delegated work, pass a shared workspace filename/reference instead of embedding the content in the tool call.`
+}

package/src/runtime/query/index.ts

@@ -224,6 +224,8 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		}
 	}
 
+	const effectiveAllowedTools = withDeferredDiscoveryTool(params.tools, params.allowedTools)
+
 	const toolExecutor = ToolingBootstrap.init(
 		{
 			tools: params.tools,
@@ -232,6 +234,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			permissionMode: ctx.permissionMode,
 			env: params.runConfig.env ?? {},
 			abortSignal: ctx.abortController.signal,
+			allowedTools: effectiveAllowedTools,
 			invocationState: params.invocationState,
 			pluginManager: params.pluginManager,
 		},
@@ -252,7 +255,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 		skills: params.skills,
 		basePrompt: params.basePrompt,
 		tools: params.tools,
-		allowedTools: params.allowedTools,
+		allowedTools: effectiveAllowedTools,
 		runtimeContext: params.runtimeContext,
 	})
 
@@ -312,7 +315,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 			provider: params.provider,
 			runConfig: params.runConfig,
 			tools: params.tools,
-			allowedTools: params.allowedTools,
+			allowedTools: effectiveAllowedTools,
 			taskGateway: params.taskGateway,
 			taskStore: params.taskStore,
 			launchedTasks: params.launchedTasks,
@@ -370,7 +373,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 				skills: params.skills,
 				basePrompt: contextLevel === 'full' ? params.basePrompt : undefined,
 				tools: params.tools,
-				allowedTools: params.allowedTools,
+				allowedTools: effectiveAllowedTools,
 				runtimeContext: params.runtimeContext,
 			}
 
@@ -536,3 +539,21 @@ export async function drainQuery(
 
 	return result.value
 }
+
+function withDeferredDiscoveryTool(
+	tools: ToolRegistryContract,
+	allowedTools?: string[],
+): string[] | undefined {
+	if (!allowedTools) return undefined
+	if (allowedTools.includes(SearchToolsTool.name)) return allowedTools
+
+	const allowedHasDeferred = allowedTools.some(
+		(name) => tools.has(name) && tools.getAvailability(name) === 'deferred',
+	)
+	if (!allowedHasDeferred) return allowedTools
+
+	if (!tools.has(SearchToolsTool.name)) return allowedTools
+	if (tools.getAvailability(SearchToolsTool.name) !== 'active') return allowedTools
+
+	return [...allowedTools, SearchToolsTool.name]
+}