@namzu/sdk 1.3.0 → 1.4.0

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/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,

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[]