@namzu/sdk 0.6.0 → 1.1.0

package/src/runtime/query/__tests__/executor-concurrency.test.ts

@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { ActivityStore } from '../../../store/activity/memory.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { ChatCompletionResponse } from '../../../types/provider/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import type { ToolRegistryContract } from '../../../types/tool/index.js'
+import type { Logger } from '../../../utils/logger.js'
+import { ToolExecutor } from '../executor.js'
+
+const mockRunId = 'run_test' as RunId
+
+function makeLogger(): Logger {
+	const stub = { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+	return { ...stub, child: vi.fn(() => ({ ...stub, child: vi.fn() })) } as unknown as Logger
+}
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+/** Two tool calls in one assistant message (one batch). */
+function twoCallResponse(name: string, a: object, b: object): ChatCompletionResponse {
+	return {
+		message: {
+			role: 'assistant',
+			content: null,
+			toolCalls: [
+				{ id: 'c1', type: 'function', function: { name, arguments: JSON.stringify(a) } },
+				{ id: 'c2', type: 'function', function: { name, arguments: JSON.stringify(b) } },
+			],
+		},
+		finishReason: 'tool_calls',
+		usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+	} as ChatCompletionResponse
+}
+
+describe('ToolExecutor — concurrencySafe batching', () => {
+	let activityStore: ActivityStore
+	let emitEvent: (e: RunEvent) => Promise<void>
+
+	beforeEach(() => {
+		activityStore = new ActivityStore(mockRunId, {
+			enabled: true,
+			trackToolCalls: true,
+			trackLlmTurns: true,
+		})
+		emitEvent = async () => {}
+	})
+
+	it('serializes concurrency-unsafe tools so read-modify-write does not race', async () => {
+		// Shared mutable state, mutated via read → await → write (like `edit`).
+		let file = 'A'
+		const execute = vi.fn(async (_name: string, input: unknown) => {
+			const current = file // read
+			await delay(10) // window a parallel run would exploit
+			file = current + (input as { add: string }).add // write
+			return { success: true, output: 'ok' }
+		})
+		const tools = {
+			register: vi.fn(),
+			unregister: vi.fn(),
+			execute,
+			// edit/write/bash declare concurrencySafe:false → isConcurrencySafe()=>false
+			get: vi.fn(() => ({ isConcurrencySafe: () => false })),
+			has: vi.fn(() => true),
+			listNames: vi.fn(() => []),
+			getAvailability: vi.fn(),
+		} as unknown as ToolRegistryContract
+
+		const exec = new ToolExecutor(
+			{
+				tools,
+				runId: mockRunId,
+				workingDirectory: '/tmp',
+				permissionMode: 'auto',
+				env: {},
+				abortSignal: new AbortController().signal,
+			},
+			activityStore,
+			emitEvent,
+			makeLogger(),
+		)
+		await exec.executeBatch(twoCallResponse('edit', { add: 'B' }, { add: 'C' }))
+		// Serialized: A→AB→ABC. A racing run would lose one append (e.g. 'AC').
+		expect(file).toBe('ABC')
+	})
+
+	it('runs concurrency-safe tools in parallel', async () => {
+		let active = 0
+		let maxActive = 0
+		const execute = vi.fn(async () => {
+			active++
+			maxActive = Math.max(maxActive, active)
+			await delay(10)
+			active--
+			return { success: true, output: 'ok' }
+		})
+		const tools = {
+			register: vi.fn(),
+			unregister: vi.fn(),
+			execute,
+			get: vi.fn(() => ({ isConcurrencySafe: () => true })),
+			has: vi.fn(() => true),
+			listNames: vi.fn(() => []),
+			getAvailability: vi.fn(),
+		} as unknown as ToolRegistryContract
+
+		const exec = new ToolExecutor(
+			{
+				tools,
+				runId: mockRunId,
+				workingDirectory: '/tmp',
+				permissionMode: 'auto',
+				env: {},
+				abortSignal: new AbortController().signal,
+			},
+			activityStore,
+			emitEvent,
+			makeLogger(),
+		)
+		await exec.executeBatch(twoCallResponse('grep', { p: '1' }, { p: '2' }))
+		expect(maxActive).toBe(2) // both ran at once
+	})
+})

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__/long-document-flow.test.ts

@@ -0,0 +1,180 @@
+import { readFile, rm } from 'node:fs/promises'
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import { EditTool, WriteFileTool } from '../../../tools/builtins/index.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,
+}
+
+interface ToolStep {
+	readonly name: string
+	readonly input: Record<string, unknown>
+}
+
+class ScriptedLongDocumentProvider implements LLMProvider {
+	readonly id = 'scripted-long-document'
+	readonly name = 'Scripted Long Document Provider'
+	calls = 0
+
+	constructor(private readonly steps: readonly ToolStep[]) {}
+
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		const step = this.steps[this.calls]
+		this.calls += 1
+
+		if (!step) {
+			yield {
+				id: 'msg_done',
+				delta: { content: 'Long document created and verified.' },
+				finishReason: 'stop',
+				usage: ZERO_USAGE,
+			}
+			return
+		}
+
+		yield {
+			id: `msg_${this.calls}`,
+			delta: {
+				toolCalls: [
+					{
+						index: 0,
+						id: `toolu_${this.calls}`,
+						type: 'function',
+						function: { name: step.name },
+					},
+				],
+			},
+		}
+		yield {
+			id: `msg_${this.calls}`,
+			delta: {
+				toolCalls: [
+					{
+						index: 0,
+						id: `toolu_${this.calls}`,
+						function: { arguments: JSON.stringify(step.input) },
+					},
+				],
+			},
+		}
+		yield {
+			id: `msg_${this.calls}`,
+			delta: {},
+			finishReason: 'tool_calls',
+			usage: ZERO_USAGE,
+		}
+	}
+}
+
+describe('query long-document tool flow', () => {
+	const workdirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+		workdirs.length = 0
+	})
+
+	it('executes the canonical write skeleton plus bounded edit chunks flow end to end', async () => {
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-query-long-doc-'))
+		workdirs.push(workingDirectory)
+
+		const chunks = Array.from({ length: 4 }, (_, sectionIndex) => {
+			const lines = Array.from({ length: 40 }, (_, lineIndex) => {
+				return `Section ${sectionIndex + 1}.${lineIndex + 1}: this content is intentionally long enough to require repeated bounded edit calls.`
+			})
+			const chunk = [`## Section ${sectionIndex + 1}`, ...lines, ''].join('\n')
+			expect(chunk.length).toBeLessThan(12_000)
+			return chunk
+		})
+
+		const provider = new ScriptedLongDocumentProvider([
+			{
+				name: 'write',
+				input: {
+					path: 'outputs/long-document-flow.md',
+					content: '# Long document flow\n\n{{BODY}}\n',
+				},
+			},
+			{
+				name: 'edit',
+				input: {
+					path: 'outputs/long-document-flow.md',
+					oldStr: '{{BODY}}',
+					newStr: chunks[0],
+					replace_all: false,
+				},
+			},
+			...chunks.slice(1).map((chunk) => ({
+				name: 'edit',
+				input: {
+					path: 'outputs/long-document-flow.md',
+					insertLine: 'end',
+					newStr: chunk,
+					replace_all: false,
+				},
+			})),
+		])
+		const tools = new ToolRegistry()
+		tools.register(WriteFileTool)
+		tools.register(EditTool)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				provider,
+				tools,
+				runConfig: {
+					model: 'mock-model',
+					timeoutMs: 5_000,
+					tokenBudget: 100_000,
+					maxIterations: 8,
+					maxResponseTokens: 256,
+				},
+				agentId: 'agent_long_doc',
+				agentName: 'Long Document Agent',
+				messages: [createUserMessage('create a long document')],
+				workingDirectory,
+				sessionId: 'ses_long_document_flow' as SessionId,
+				threadId: 'thd_long_document_flow' as ThreadId,
+				projectId: 'prj_long_document_flow' as ProjectId,
+				tenantId: 'tnt_long_document_flow' as TenantId,
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		const final = await readFile(join(workingDirectory, 'outputs/long-document-flow.md'), 'utf-8')
+		const executingTools = events
+			.filter(
+				(event): event is Extract<RunEvent, { type: 'tool_executing' }> =>
+					event.type === 'tool_executing',
+			)
+			.map((event) => event.toolName)
+
+		expect(run.status).toBe('completed')
+		expect(run.result).toBe('Long document created and verified.')
+		expect(provider.calls).toBe(6)
+		expect(executingTools).toEqual(['write', 'edit', 'edit', 'edit', 'edit'])
+		expect(final).not.toContain('{{BODY}}')
+		expect(final.split('\n').length).toBeGreaterThan(160)
+		expect(final).toContain('## Section 1')
+		expect(final).toContain('## Section 4')
+		expect(final).toContain('Section 4.40')
+	})
+})

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,59 @@ 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: 'delivery-briefing',
+						description: 'Draft and edit delivery briefings from grounded inputs.',
+					},
+					dirPath: '/repo/.agents/skills/delivery-briefing',
+				},
+			],
+		}).build('full', '/tmp/work')
+
+		expect(prompt).toContain('You are a project assistant.')
+		expect(prompt).toContain('## Available Skills')
+		expect(prompt).toContain('<available_skills>')
+		expect(prompt).toContain('delivery-briefing')
+		expect(prompt).toContain('Draft and edit delivery briefings')
+		expect(prompt).toContain('<location>/repo/.agents/skills/delivery-briefing/SKILL.md</location>')
+		expect(prompt).toContain('The following block is a manifest')
+		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: 'structured-file-authoring',
+						description: 'Create structured 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/structured-file-authoring',
+				},
+			],
+		}).build('full', '/tmp/work')
+
+		expect(prompt).toContain('## Available Skills')
+		expect(prompt).toContain('<license>MIT</license>')
+		expect(prompt).toContain('<compatibility>Requires file tools</compatibility>')
+		expect(prompt).toContain('<allowed_tools>read write edit</allowed_tools>')
+		expect(prompt).toContain('read the SKILL.md at its <location> before writing code')
+		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.'