@namzu/sdk 1.2.0 → 1.4.0

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

package/src/tools/coordinator/index.ts

@@ -227,28 +227,6 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	const cancelTask = defineTool({
-		name: 'cancel_task',
-		description:
-			'Cancel a running agent task. Only use this with a task_id from a previous create_task.',
-		inputSchema: z.object({
-			task_id: z.string().describe('Agent task ID from a previous create_task'),
-		}),
-		category: 'custom',
-		permissions: [],
-		readOnly: false,
-		destructive: false,
-		concurrencySafe: true,
-		async execute({ task_id }) {
-			gateway.cancelTask(task_id as TaskId)
-			return {
-				success: true,
-				output: `Task ${task_id} cancelled`,
-				data: { task_id },
-			}
-		},
-	})
-
 	const agentTaskList = defineTool({
 		name: 'agent_task_list',
 		description:
@@ -305,19 +283,18 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	// `continue_task` was a follow-up channel for a still-alive worker
-	// task. With `create_task` now blocking + tool_result returning
-	// the worker's final output, every worker reaches a terminal
-	// state by the time the supervisor wants to follow up — and the
-	// agent manager rejects `continue` on terminal tasks. The
-	// industrial pattern is to issue a fresh `create_task` that
-	// references the prior worker's output path, so we drop
-	// `continue_task` from the registered surface entirely. The
-	// definition stays in this file for now in case a future
-	// non-default gateway (one that keeps the worker process alive
-	// for follow-ups) wants to re-register it.
+	// `continue_task` and model-facing per-task cancellation both
+	// belonged to the old non-blocking worker protocol. With
+	// `create_task` now blocking + tool_result returning the worker's
+	// final output, every worker is terminal by the time a later model
+	// turn learns its task id. The old cancel tool additionally called
+	// a void/no-op gateway method and manufactured "cancelled" even for
+	// a missing id. Host-owned run interruption still uses the gateway
+	// cancellation contract directly; it does not need a model tool.
+	// Keep only the follow-up definition for a future non-default
+	// gateway that deliberately preserves live workers between turns.
 	void continueTask
-	const tools: ToolDefinition[] = [createTask, cancelTask, agentTaskList]
+	const tools: ToolDefinition[] = [createTask, agentTaskList]
 
 	if (getPlanManager) {
 		const approvePlan = defineTool({

package/src/tools/defineTool.ts

@@ -11,6 +11,7 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	name: string
 	description: string
 	inputSchema: S
+	validationErrorHint?: string
 	category: ToolDefinition['category']
 	permissions: ToolPermission[]
 	readOnly: boolean
@@ -29,6 +30,7 @@ export function defineTool<S extends z.ZodType>(
 		name: options.name,
 		description: options.description,
 		inputSchema: options.inputSchema,
+		validationErrorHint: options.validationErrorHint,
 		tier: options.tier,
 		category: options.category,
 		permissions: options.permissions,

package/src/types/provider/config.ts

@@ -70,4 +70,40 @@ export interface RegisterOptions {
 	replace?: boolean
 }
 
+/**
+ * What a lazy loader must resolve to: a factory that constructs the
+ * provider, plus (optionally) the provider package's authoritative
+ * capability declaration resolved at load time.
+ *
+ * Designed so a host can map a dynamic import in one line:
+ *
+ * ```ts
+ * ProviderRegistry.registerLazy('anthropic', async () => {
+ *   const m = await import('@namzu/anthropic')
+ *   return { create: (c) => new m.AnthropicProvider(c), capabilities: m.ANTHROPIC_CAPABILITIES }
+ * })
+ * ```
+ */
+export interface LazyProviderModule<C = unknown> {
+	create: (config: C) => LLMProvider
+	/**
+	 * Authoritative type-level capabilities shipped by the loaded module.
+	 * When present, replaces any registration-time hint in the registry.
+	 */
+	capabilities?: ProviderCapabilities
+}
+
+export type LazyProviderLoader<C = unknown> = () => Promise<LazyProviderModule<C>>
+
+export interface RegisterLazyOptions extends RegisterOptions {
+	/**
+	 * Pre-load capability HINT so `ProviderRegistry.getCapabilities(type)`
+	 * can answer without triggering the loader. Precedence (weakest first):
+	 * this hint → the loaded module's `capabilities` → the constructed
+	 * instance's own `LLMProvider.capabilities` (what the query runtime
+	 * resolves via `resolveProviderCapabilities` and actually respects).
+	 */
+	capabilities?: ProviderCapabilities
+}
+
 export type LLMProviderConstructor<C = unknown> = new (config: C) => LLMProvider

package/src/types/provider/error.ts

@@ -0,0 +1,29 @@
+/** What went wrong, at the coarsest granularity a caller can act on. */
+export type ProviderErrorKind =
+	| 'throttle'
+	| 'network'
+	| 'auth'
+	| 'context_overflow'
+	| 'bad_request'
+	| 'server'
+
+/**
+ * Serializable provider-failure metadata carried by failed runs and events.
+ *
+ * No response body, vendor message, URL, or `cause` belongs here.
+ */
+export interface ProviderErrorInfo {
+	readonly kind: ProviderErrorKind
+	readonly providerId: string
+	readonly status?: number
+	readonly retryAfterMs?: number
+}
+
+export interface ProviderRequestErrorInit extends ProviderErrorInfo {
+	/**
+	 * Optional extra clause for the message. MUST be text this codebase
+	 * authored — never a fragment of a response body, a header, or a vendor
+	 * error.
+	 */
+	readonly detail?: string
+}

package/src/types/provider/index.ts

@@ -8,6 +8,11 @@ export type {
 export type { StreamChunk } from './stream.js'
 export type { ModelInfo } from './model.js'
 export type { LLMProvider } from './interface.js'
+export type {
+	ProviderErrorInfo,
+	ProviderErrorKind,
+	ProviderRequestErrorInit,
+} from './error.js'
 export type {
 	ProviderConfigRegistry,
 	ProviderType,
@@ -16,5 +21,8 @@ export type {
 	ProviderCapabilities,
 	ProviderFactoryResult,
 	RegisterOptions,
+	LazyProviderModule,
+	LazyProviderLoader,
+	RegisterLazyOptions,
 	LLMProviderConstructor,
 } from './config.js'

package/src/types/run/entity.ts

@@ -1,6 +1,7 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { ProviderErrorInfo } from '../provider/index.js'
 import type { AgentRunConfig } from './config.js'
 import type { ReplayAttribution } from './replay.js'
 import type { StopReason } from './stop-reason.js'
@@ -37,6 +38,7 @@ export interface Run {
 	endedAt?: number
 	stopReason?: StopReason
 	lastError?: string
+	lastProviderError?: ProviderErrorInfo
 	result?: string
 
 	parentRunId?: RunId

package/src/types/run/events.ts

@@ -14,6 +14,7 @@ import type {
 } from '../ids/index.js'
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
+import type { ProviderErrorInfo } from '../provider/index.js'
 import type { TaskStatus } from '../task/index.js'
 import type { Lineage } from './lineage.js'
 import type { MessageStopReason } from './stop-reason.js'
@@ -98,7 +99,12 @@ type CoreRunEvent =
 			fromCheckpointId: CheckpointId
 	  }
 	| { type: 'run_completed'; runId: RunId; result: string }
-	| { type: 'run_failed'; runId: RunId; error: string }
+	| {
+			type: 'run_failed'
+			runId: RunId
+			error: string
+			providerError?: ProviderErrorInfo
+	  }
 	// Additive 2026-07 (provider capability negotiation): emitted once per
 	// run when the request asks for something the provider DRIVER declared
 	// it cannot do — tools registered against a no-tools driver (tool

package/src/types/tool/index.ts

@@ -64,6 +64,12 @@ export interface ToolDefinition<TInput = unknown> {
 	name: string
 	description: string
 	inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>
+	/**
+	 * Concise, model-readable recovery guidance appended when inputSchema
+	 * rejects a call. Use for conditional schemas whose required shapes
+	 * cannot be reconstructed from JSON Schema's top-level `required` list.
+	 */
+	validationErrorHint?: string
 	execute(input: TInput, context: ToolContext): Promise<ToolResult>
 	tier?: string
 	permissions?: ToolPermission[]