@namzu/sdk 1.3.0 → 1.4.0

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

@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { z } from 'zod'
 
+import { ProviderRequestError } from '../../../provider/errors.js'
 import { ToolRegistry } from '../../../registry/tool/execute.js'
 import type { SessionId, TenantId } from '../../../types/ids/index.js'
 import { createUserMessage } from '../../../types/message/index.js'
@@ -72,6 +73,22 @@ class IdleDuringToolInputProvider implements LLMProvider {
 	}
 }
 
+class ClassifiedFailureProvider implements LLMProvider {
+	readonly id = 'classified-failure'
+	readonly name = 'Classified Failure Provider'
+
+	async *chatStream(): AsyncIterable<StreamChunk> {
+		yield await Promise.reject(
+			new ProviderRequestError({
+				kind: 'throttle',
+				providerId: 'classified-failure',
+				status: 429,
+				retryAfterMs: 2000,
+			}),
+		)
+	}
+}
+
 describe('query stream recovery', () => {
 	let workdirs: string[] = []
 
@@ -82,7 +99,10 @@ describe('query stream recovery', () => {
 
 	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 actualWrite = vi.fn(async () => ({
+			success: true,
+			output: 'should not run',
+		}))
 		const tools = new ToolRegistry()
 		tools.register({
 			name: 'write_file',
@@ -153,4 +173,47 @@ describe('query stream recovery', () => {
 			'extend it with edit using insertLine',
 		)
 	})
+
+	it('preserves classified provider metadata through the primary run boundary', async () => {
+		const workingDirectory = await mkdtemp(join(tmpdir(), 'namzu-provider-error-'))
+		workdirs.push(workingDirectory)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				provider: new ClassifiedFailureProvider(),
+				tools: new ToolRegistry(),
+				runConfig: {
+					model: 'mock-model',
+					timeoutMs: 5_000,
+					tokenBudget: 100_000,
+					maxIterations: 1,
+					maxResponseTokens: 256,
+				},
+				agentId: 'agent_test',
+				agentName: 'Test Agent',
+				messages: [createUserMessage('fail with classified metadata')],
+				workingDirectory,
+				sessionId: 'ses_provider_error' as SessionId,
+				threadId: 'thd_provider_error' as ThreadId,
+				projectId: 'prj_provider_error' as ProjectId,
+				tenantId: 'tnt_provider_error' as TenantId,
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('failed')
+		expect(run.lastProviderError).toEqual({
+			kind: 'throttle',
+			providerId: 'classified-failure',
+			status: 429,
+			retryAfterMs: 2000,
+		})
+		expect(events.find((event) => event.type === 'run_failed')).toMatchObject({
+			type: 'run_failed',
+			providerError: run.lastProviderError,
+		})
+	})
 })

package/src/runtime/query/iteration/phases/compaction-safe-cut.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The UNBOUNDED CUT.
+ *
+ * `runCompactionCheck` snaps the naive recent-window boundary
+ * (`messages.length - keepRecentMessages`) FORWARD via `findSafeTrimIndex` so a
+ * tool pair is never split. But `findSafeTrimIndex` only ever walks forward, and
+ * its leading-`tool`-message skip has no stop short of `messages.length` — so
+ * whenever the whole suffix from the naive index to the end is `tool` messages,
+ * the cut lands ON `messages.length`, `recentMessages` comes back EMPTY, and
+ * `[...preservedSystem, compactionMessage]` replaces the ENTIRE recent window.
+ * What is left is a transcript with no non-system message at all.
+ *
+ * The shape that produces it: ONE assistant turn that fans out
+ * `>= keepRecentMessages` parallel tool calls, measured at the START of the next
+ * iteration — which is exactly where `runCompactionCheck` runs (iteration/index.ts,
+ * after `refreshWorkingMemory`, before the model call), i.e. immediately after
+ * those results were appended.
+ *
+ * The `olderMessages.length < 1` guard at :117 cannot fire: `olderMessages` is
+ * the whole transcript in exactly this situation.
+ *
+ * Symmetrically, when the naive index lands BELOW `systemMessages.length` the
+ * cut sits inside the system prefix and the leading prompts are duplicated into
+ * `recentMessages`.
+ *
+ * The invariant these tests pin is the one a cut taken AT OR BELOW naive gives
+ * for free: a pass never removes more than the naive cut would, so at least
+ * `keepRecentMessages` original messages survive verbatim — or, when no safe cut
+ * exists at all, the pass is skipped and the transcript is untouched.
+ */
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { WorkingStateManager } from '../../../../compaction/manager.js'
+import { CompactionConfigSchema } from '../../../../config/runtime.js'
+import type { RunId } from '../../../../types/ids/index.js'
+import {
+	type Message,
+	createAssistantMessage,
+	createSystemMessage,
+	createToolMessage,
+	createUserMessage,
+} from '../../../../types/message/index.js'
+import type { Logger } from '../../../../utils/logger.js'
+import { runCompactionCheck } from './compaction.js'
+import type { IterationContext } from './context.js'
+
+function makeLogger(): Logger {
+	const self = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: vi.fn(),
+	} as unknown as Logger
+	;(self as { child: (ctx: unknown) => Logger }).child = vi.fn(() => self)
+	return self
+}
+
+/** Long enough that a handful of messages overflow a tiny budget. */
+const FILLER = 'x'.repeat(200)
+
+const KEEP_RECENT = 4
+
+function makeCtx(opts: {
+	messages: Message[]
+	contextWindowTokens?: number
+	tokenBudget?: number
+}): IterationContext {
+	const config = CompactionConfigSchema.parse({
+		strategy: 'structured',
+		llmVerification: false,
+		keepRecentMessages: KEEP_RECENT,
+		...(opts.contextWindowTokens !== undefined
+			? { contextWindowTokens: opts.contextWindowTokens }
+			: {}),
+	})
+	const manager = new WorkingStateManager(config)
+	manager.addDecision('built the report as .docx')
+
+	return {
+		runConfig: { tokenBudget: opts.tokenBudget ?? 0 },
+		compactionConfig: config,
+		workingStateManager: manager,
+		log: makeLogger(),
+		runMgr: {
+			id: 'run_1' as RunId,
+			currentIteration: 3,
+			messages: opts.messages,
+		},
+	} as unknown as IterationContext
+}
+
+function toolCall(id: string) {
+	return { id, type: 'function' as const, function: { name: 'read', arguments: '{}' } }
+}
+
+/** How many of the ORIGINAL messages survived the pass, by identity. */
+function survivorCount(before: readonly Message[], after: readonly Message[]): number {
+	const kept = new Set<Message>(after)
+	return before.filter((m) => kept.has(m)).length
+}
+
+/**
+ * The exact shape the iteration loop holds when `runCompactionCheck` runs: the
+ * user's turn, one assistant that fanned out four parallel tool calls, and the
+ * four results that just landed. The next thing that happens is the model call —
+ * with whatever this function leaves behind.
+ */
+function buildParallelFanOutTail(): Message[] {
+	return [
+		createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache'),
+		createUserMessage(`please rename the heading to Q3 ${FILLER}`),
+		createAssistantMessage(`reading the sources ${FILLER}`, [
+			toolCall('a'),
+			toolCall('b'),
+			toolCall('c'),
+			toolCall('d'),
+		]),
+		createToolMessage(`result a ${FILLER}`, 'a'),
+		createToolMessage(`result b ${FILLER}`, 'b'),
+		createToolMessage(`result c ${FILLER}`, 'c'),
+		createToolMessage(`result d ${FILLER}`, 'd'),
+	]
+}
+
+describe('compaction — the unbounded cut', () => {
+	it('keeps at least keepRecentMessages messages verbatim when the tail is a parallel tool fan-out', async () => {
+		const messages = buildParallelFanOutTail()
+		const before = [...messages]
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		expect(survivorCount(before, messages)).toBeGreaterThanOrEqual(KEEP_RECENT)
+	})
+
+	it('never leaves a system-only transcript (nothing for the next turn to answer)', async () => {
+		const messages = buildParallelFanOutTail()
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		const nonSystem = messages.filter((m) => m.role !== 'system')
+		expect(nonSystem.length).toBeGreaterThan(0)
+	})
+
+	it('skips the pass, leaving the transcript intact, when no safe cut exists at or below naive', async () => {
+		// System prefix, then a single assistant fanning out six parallel calls.
+		// Every candidate boundary at or below naive splits that one pair-set, so
+		// there is nothing safe to cut to — skipping beats deleting the turn.
+		const ids = ['a', 'b', 'c', 'd', 'e', 'f']
+		const messages: Message[] = [
+			createSystemMessage(`STATIC SYSTEM PROMPT ${FILLER}`, 'cache'),
+			createAssistantMessage(`fanning out ${FILLER}`, ids.map(toolCall)),
+			...ids.map((id) => createToolMessage(`result ${id} ${FILLER}`, id)),
+		]
+		const before = [...messages]
+		const ctx = makeCtx({ messages, contextWindowTokens: 100 })
+
+		await runCompactionCheck(ctx)
+
+		expect(messages).toEqual(before)
+	})
+
+	it('does not duplicate the leading system prompts when the naive cut lands inside them', async () => {
+		// Legacy (tokenBudget) path: five leading system messages and only three
+		// conversational ones, so naive = 8 - 4 = 4 < systemMessages.length = 5.
+		const messages: Message[] = [
+			createSystemMessage(`SYS-1 ${FILLER}`, 'cache'),
+			createSystemMessage(`SYS-2 ${FILLER}`),
+			createSystemMessage(`SYS-3 ${FILLER}`),
+			createSystemMessage(`SYS-4 ${FILLER}`),
+			createSystemMessage(`SYS-5 UNIQUE-MARKER ${FILLER}`),
+			createUserMessage(`user 0 ${FILLER}`),
+			createAssistantMessage(`assistant 0 ${FILLER}`),
+			createUserMessage(`user 1 ${FILLER}`),
+		]
+		const ctx = makeCtx({ messages, tokenBudget: 100 })
+
+		await runCompactionCheck(ctx)
+
+		const marker = messages.filter((m) => m.content?.includes('UNIQUE-MARKER'))
+		expect(marker).toHaveLength(1)
+	})
+})

package/src/runtime/query/iteration/phases/compaction.ts

@@ -94,18 +94,60 @@ export async function runCompactionCheck(ctx: IterationContext): Promise<void> {
 	}
 	if (systemMessages.length === 0) return
 
-	// Tool-pair atomicity guard. A naive cut at `length - keepRecentMessages`
-	// can land BETWEEN an assistant-with-toolCalls (which would be dropped into
-	// `olderMessages`) and its `tool` results (kept in `recentMessages`),
-	// leaving orphaned `tool_result` blocks at the head of the recent window.
-	// The Anthropic provider then emits a `tool_result` with no matching
-	// `tool_use` and the API rejects the next turn with a 400 — so compaction,
-	// whose whole job is to keep a long run alive, instead kills it. Snap the
-	// boundary FORWARD to a safe point (existing `findSafeTrimIndex`, previously
-	// only wired to the unused ConversationManager strategy classes) so no pair
-	// is split. Any message this moves out of the recent window is already
-	// represented in the extracted WorkingState the summary is built from.
-	const keepStart = findSafeTrimIndex(messages, messages.length - config.keepRecentMessages)
+	// Tool-pair atomicity guard, taken DOWNWARD.
+	//
+	// A naive cut at `length - keepRecentMessages` can land BETWEEN an
+	// assistant-with-toolCalls (dropped into `olderMessages`) and its `tool`
+	// results (kept in `recentMessages`), leaving orphaned `tool_result` blocks at
+	// the head of the recent window. The Anthropic provider then emits a
+	// `tool_result` with no matching `tool_use` and the API rejects the next turn
+	// with a 400 — so compaction, whose whole job is to keep a long run alive,
+	// instead kills it.
+	//
+	// Snapping FORWARD via `findSafeTrimIndex` fixes the orphan and introduces a
+	// worse failure. That walk skips leading `tool` messages with no stop short of
+	// `messages.length`, so whenever the entire suffix from the naive index is
+	// `tool` messages, the boundary lands ON `messages.length`: `recentMessages`
+	// comes back EMPTY and `[...preservedSystem, compactionMessage]` replaces the
+	// whole recent window. The model is then asked to answer a conversation whose
+	// last turn — including the user's own message — was deleted, and it answers a
+	// question nobody asked. The shape is routine, not exotic: one assistant turn
+	// fanning out `>= keepRecentMessages` parallel tool calls, measured at the
+	// start of the very next iteration, which is exactly where this runs. The
+	// `olderMessages` floor guard below cannot catch it either — in that shape
+	// `olderMessages` is the whole transcript.
+	//
+	// So take the LARGEST safe boundary AT OR BELOW naive instead. A cut that low
+	// removes no more than the naive cut would, so at least `keepRecentMessages`
+	// original messages always survive verbatim, and the transcript can never be
+	// reduced to system messages alone. `findSafeTrimIndex(m, k) === k` is the
+	// safety predicate — reused rather than reimplemented, so the function itself
+	// (public API, other callers) is untouched.
+	const naiveKeepStart = messages.length - config.keepRecentMessages
+	let keepStart = -1
+	for (let candidate = naiveKeepStart; candidate > systemMessages.length; candidate--) {
+		if (findSafeTrimIndex(messages, candidate) === candidate) {
+			keepStart = candidate
+			break
+		}
+	}
+
+	// No safe boundary at or below naive. Either every candidate splits a pair-set
+	// (one assistant fanning out more calls than the recent window holds), or naive
+	// itself sits inside the leading system prefix — which would otherwise
+	// duplicate those prompts into `recentMessages`. Skipping costs one iteration's
+	// worth of context headroom; cutting anyway costs the live turn. The condition
+	// is self-clearing: the next assistant message moves naive past the tool block.
+	if (keepStart < 0) {
+		ctx.log.debug('Skipping compaction — no safe cut at or below the naive boundary', {
+			runId: ctx.runMgr.id,
+			naiveKeepStart,
+			systemMessages: systemMessages.length,
+			messageCount: messages.length,
+		})
+		return
+	}
+
 	const recentMessages = messages.slice(keepStart)
 	const olderMessages = messages.slice(systemMessages.length, keepStart)
 

package/src/runtime/query/iteration/stream-turn.ts

@@ -1,3 +1,4 @@
+import { isProviderRequestError } from '../../../provider/errors.js'
 import { mergeTokenUsage } from '../../../types/common/index.js'
 import type { ToolUseId } from '../../../types/ids/index.js'
 import type {
@@ -111,9 +112,12 @@ export async function* streamProviderTurn(
 			inputTruncated: boolean
 		}
 	>()
-	let streamError: string | undefined
+	let streamError: Error | undefined
 
-	const stream = provider.chatStream({ ...params, stream: true }) as AsyncIterable<StreamChunk>
+	const stream = provider.chatStream({
+		...params,
+		stream: true,
+	}) as AsyncIterable<StreamChunk>
 
 	// Drive the stream manually so each `.next()` can be RACED against the run
 	// abort: a Stop tears the in-flight model request down (the provider got
@@ -145,7 +149,7 @@ export async function* streamProviderTurn(
 			if (res.done) break
 			const chunk = res.value
 			if (chunk.error) {
-				streamError = chunk.error
+				streamError = new Error(`Provider stream error: ${chunk.error}`)
 				break
 			}
 			if (!id && chunk.id) id = chunk.id
@@ -252,7 +256,7 @@ export async function* streamProviderTurn(
 		// run as cancelled rather than recording a normal (errored) turn. Any
 		// other stream error is captured into the synthesized response as before.
 		if (signal?.aborted) throw err
-		streamError = err instanceof Error ? err.message : String(err)
+		streamError = err instanceof Error ? err : new Error(String(err))
 	} finally {
 		if (onAbort) signal?.removeEventListener('abort', onAbort)
 		// Release the underlying connection on every exit (natural end, error,
@@ -355,7 +359,7 @@ export async function* streamProviderTurn(
 		log.warn('provider stream failed after tool input; surfacing tool call to executor', {
 			runId,
 			iteration,
-			error: streamError,
+			error: streamError?.message ?? 'provider stream failed',
 			toolCallCount: toolCalls.length,
 		})
 	}
@@ -378,7 +382,8 @@ export async function* streamProviderTurn(
 	yield* drainPending()
 
 	if (streamError && !recoveredToolInputFromStreamError) {
-		throw new Error(`Provider stream error: ${streamError}`)
+		if (isProviderRequestError(streamError)) throw streamError
+		throw new Error(`Provider stream error: ${streamError.message}`)
 	}
 
 	const response: ChatCompletionResponse = {

package/src/runtime/query/result.ts

@@ -1,6 +1,7 @@
 import { type Span, SpanStatusCode } from '@opentelemetry/api'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
+import { isProviderRequestError } from '../../provider/errors.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
 import type { Run, RunEvent } from '../../types/run/index.js'
@@ -61,7 +62,15 @@ export class ResultAssembler {
 	async *handleError(err: unknown, rootSpan: Span): AsyncGenerator<RunEvent> {
 		const { runMgr, planManager, log, emitEvent, drainPending } = this.config
 		const errorMessage = toErrorMessage(err)
-		runMgr.markFailed(errorMessage)
+		const providerError = isProviderRequestError(err)
+			? {
+					kind: err.kind,
+					providerId: err.providerId,
+					...(err.status !== undefined ? { status: err.status } : {}),
+					...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+				}
+			: undefined
+		runMgr.markFailed(errorMessage, providerError)
 
 		if (planManager.isActive) {
 			planManager.failPlan(errorMessage)
@@ -71,6 +80,7 @@ export class ResultAssembler {
 			type: 'run_failed',
 			runId: runMgr.id,
 			error: errorMessage,
+			...(providerError ? { providerError } : {}),
 		})
 		yield* drainPending()
 

package/src/tools/builtins/__tests__/edit.test.ts

@@ -2,6 +2,8 @@ import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
 import type { ToolContext } from '../../../types/tool/index.js'
 import { EditTool } from '../edit.js'
 
@@ -54,4 +56,78 @@ describe('EditTool', () => {
 		expect(result.success).toBe(true)
 		expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nomega\n')
 	})
+
+	it('publishes only the insertLine values the executor can apply', () => {
+		for (const insertLine of ['## Progress', null, '', '1', -1]) {
+			const parsed = EditTool.inputSchema.safeParse({
+				path: 'doc.md',
+				insertLine,
+				newStr: 'inserted',
+			})
+			expect(parsed.success, JSON.stringify(insertLine)).toBe(false)
+		}
+
+		for (const insertLine of [0, 1, 'end']) {
+			const parsed = EditTool.inputSchema.safeParse({
+				path: 'doc.md',
+				insertLine,
+				newStr: 'inserted',
+			})
+			expect(parsed.success, JSON.stringify(insertLine)).toBe(true)
+		}
+
+		const json = zodToJsonSchema(EditTool.inputSchema, {
+			target: 'jsonSchema7',
+			$refStrategy: 'none',
+		}) as {
+			properties?: {
+				insertLine?: {
+					anyOf?: Record<string, unknown>[]
+				}
+			}
+		}
+		expect(json.properties?.insertLine?.anyOf).toEqual([
+			{ type: 'integer', minimum: 0 },
+			{ type: 'string', const: 'end' },
+		])
+	})
+
+	it('refuses invalid insertLine values even when a caller bypasses the schema', async () => {
+		for (const insertLine of ['## Progress', null, '', '1']) {
+			const dir = mkdtempSync(join(tmpdir(), 'namzu-edit-'))
+			writeFileSync(join(dir, 'doc.md'), 'alpha\nbeta\n')
+
+			const result = await EditTool.execute(
+				{
+					path: 'doc.md',
+					insertLine,
+					newStr: 'inserted',
+					replace_all: false,
+				} as never,
+				makeContext(dir),
+			)
+
+			expect(result.success, JSON.stringify(insertLine)).toBe(false)
+			expect(result.error).toBe('insertLine must be a non-negative line number or "end".')
+			expect(readFileSync(join(dir, 'doc.md'), 'utf-8')).toBe('alpha\nbeta\n')
+		}
+	})
+
+	it('returns complete recovery shapes when path is missing and insertLine is invalid', async () => {
+		const registry = new ToolRegistry()
+		registry.register(EditTool)
+
+		const result = await registry.execute(
+			'edit',
+			{ insertLine: '## Progress' },
+			makeContext('/tmp'),
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('Validation failed for "edit":')
+		expect(result.error).toContain('insertLine: Invalid input')
+		expect(result.error).toContain('Required: path: string — Path to the file to edit.')
+		expect(result.error).toContain('{"path":"file.md","insertLine":"end","new_string":"text"}')
+		expect(result.error).toContain('{"path":"file.md","old_string":"old","new_string":"new"}')
+	})
 })

package/src/tools/builtins/edit.ts

@@ -29,10 +29,10 @@ const inputSchema = z
 				'Alias for new_string. Also used as inserted content when insertLine is provided. Self-budget this payload under 12000 characters before calling.',
 			),
 		insertLine: z
-			.union([z.coerce.number().int().min(0), z.string().min(1)])
+			.union([z.number().int().min(0), z.literal('end')])
 			.optional()
 			.describe(
-				'Optional line insertion target. Inserts the replacement after this 1-indexed line; 0 inserts before the first line; "end" appends to the file.',
+				'Optional line insertion target. Pass a JSON integer to insert after that 1-indexed line, 0 to insert before the first line, or the exact string "end" to append. Headings, anchors, numeric strings, null, and empty strings are invalid.',
 			),
 		replace_all: z
 			.boolean()
@@ -71,6 +71,8 @@ export const EditTool = defineTool({
 	description:
 		'Makes targeted edits to a file using exact string find-and-replace or line insertion. THIS IS THE PREFERRED WAY TO MODIFY AN EXISTING FILE — never reach for `write` to change a file that already exists, because `write` overwrites the whole body and discards earlier work on partial failure. `edit` keeps the rest of the file byte-for-byte intact and is recoverable: if a single edit fails (old_string/oldStr ambiguous, broader restructuring needed), follow up with another `edit` instead of re-emitting the entire file via `write`. The old_string/oldStr must be unique in the file unless replace_all is true. For insertions, pass insertLine plus new_string/newStr; use insertLine: "end" to extend a file at the end. Self-budget new_string/newStr under 12000 characters before emitting the tool call; use repeated bounded edits for long sections. Preserves file formatting and indentation.',
 	inputSchema,
+	validationErrorHint:
+		'Accepted shapes: {"path":"file.md","insertLine":"end","new_string":"text"} or {"path":"file.md","old_string":"old","new_string":"new"}. Always include path; insertLine accepts only a non-negative JSON integer or the exact string "end".',
 	category: 'filesystem',
 	permissions: ['file_write'],
 	readOnly: false,
@@ -166,18 +168,16 @@ function normalizeEditInput(
 }
 
 function normalizeInsertLine(
-	value: string | number,
+	value: unknown,
 ): { success: true; value: number | 'end' } | { success: false; error: string } {
-	if (typeof value === 'string') {
-		if (value.trim().toLowerCase() === 'end') return { success: true, value: 'end' }
-		const parsed = Number(value)
-		if (Number.isInteger(parsed) && parsed >= 0) return { success: true, value: parsed }
-		return {
-			success: false,
-			error: 'insertLine must be a non-negative line number or "end".',
-		}
+	if (value === 'end') return { success: true, value: 'end' }
+	if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+		return { success: true, value }
+	}
+	return {
+		success: false,
+		error: 'insertLine must be a non-negative line number or "end".',
 	}
-	return { success: true, value }
 }
 
 function applyEdit(

package/src/tools/coordinator/__tests__/task-list.test.ts

@@ -179,4 +179,20 @@ describe('coordinator agent_task_list tool', () => {
 		expect(names).toContain('agent_task_list')
 		expect(names).not.toContain('task_list')
 	})
+
+	it('does not advertise per-task cancellation on the blocking coordinator surface', () => {
+		const coordinatorTools = buildCoordinatorTools({
+			gateway: gatewayWith([]),
+			workingDirectory: '/tmp/test',
+			allowedAgentIds: ['solution-architecture'],
+		})
+		const names = coordinatorTools.map((tool) => tool.name)
+
+		// create_task returns only after the worker is terminal, so the
+		// supervisor cannot know a live task id in a later model turn.
+		// Keeping cancel_task here only manufactured success for missing
+		// or terminal ids because every gateway cancellation is a void
+		// no-op in those states.
+		expect(names).not.toContain('cancel_task')
+	})
 })

package/src/tools/coordinator/agent.ts

@@ -19,14 +19,12 @@ import type { TaskLaunchedCallback } from './index.js'
  * subagent tool calls are isolated — only the summary surfaces to
  * the parent.
  *
- * This is **NOT** the same shape as the legacy `create_task` /
- * `continue_task` / `cancel_task` trio that this package ships
- * alongside it: those are non-blocking and use a `<task-notification>`
- * callback model. The async pattern is useful for hosts that want a
- * work-queue surface, but it is not what Claude Code trained against.
- * For free agentic alignment, prefer the canonical `Agent` tool; keep
- * the legacy coordinator tools only when you genuinely need
- * fire-and-forget multi-task fan-out.
+ * This is **NOT** the same shape as the coordinator `create_task`
+ * tool that this package ships alongside it. That tool exposes
+ * Namzu's task IDs and optional planning integration, while still
+ * returning results synchronously. For free agentic alignment,
+ * prefer the canonical `Agent` tool; use the coordinator tool when
+ * the host needs task tracking.
  */
 export interface AgentToolOptions {
 	gateway: TaskGateway