@namzu/sdk 27.0.0 → 28.0.0

package/src/tools/builtins/web.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod'
+
+import { WebFetchRefusedError } from '../../connector/web/types.js'
+import { defineTool } from '../defineTool.js'
+
+/**
+ * The two web tools, and the reason they are one file.
+ *
+ * Both declare `category: 'network'`, which is not decoration: the
+ * authorization presets route `network` to human review and only the
+ * `unattended` preset — the one that requires the sandbox to enforce
+ * network isolation — auto-approves it. Getting that category wrong would
+ * quietly hand every sandboxed run outbound reach, so the two tools that
+ * most need it are written where the reason is visible once.
+ *
+ * `web_search` was already a name in this tree before either tool existed:
+ * two fixtures invented it, one to have a deferred-loading tool in a
+ * catalog test and one to have a network tool for a gate test. Neither was
+ * wrong, and both were describing a tool nobody had written — so the name
+ * had a meaning in the tests and none in the runtime.
+ */
+
+const fetchInput = z.object({
+	url: z.string().min(1).describe('The absolute http(s) URL to fetch.'),
+})
+
+const searchInput = z.object({
+	query: z.string().min(1).describe('What to search for.'),
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(25)
+		.optional()
+		.describe('How many results to return. The provider may return fewer.'),
+})
+
+export const WEB_FETCH_TOOL_NAME = 'web_fetch'
+export const WEB_SEARCH_TOOL_NAME = 'web_search'
+
+export const WebFetchTool = defineTool({
+	name: WEB_FETCH_TOOL_NAME,
+	description:
+		'Fetches an http(s) URL and returns its body as text. Requests to addresses inside the host, and non-web schemes, are refused.',
+	inputSchema: fetchInput,
+	// The load-bearing line. `network` is what the presets branch on, and a
+	// tool that claimed `analysis` would auto-approve under every sandboxed
+	// preset — handing outbound reach to runs whose sandbox was never asked
+	// to confine the network.
+	category: 'network',
+	permissions: ['network_access'],
+	// Reads a page and changes nothing HERE. That is not the same as
+	// harmless — a GET can still act on a remote system — which is why the
+	// category, not this flag, is what the presets use.
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+
+	async execute(input, context) {
+		if (!context.web?.fetch) {
+			return {
+				success: false,
+				output: '',
+				error: 'This run has no web fetch provider configured, so no URL can be fetched.',
+			}
+		}
+
+		try {
+			const result = await context.web.fetch.fetch({
+				url: input.url,
+				...(context.abortSignal ? { signal: context.abortSignal } : {}),
+			})
+
+			// The chain, when there was one. A model citing the URL it asked
+			// for after three redirects is citing a page it did not read.
+			const arrivedAt = result.redirects.length > 1 ? `\n[redirected to ${result.url}]` : ''
+			const cut = result.truncated
+				? '\n[the page was longer than the fetch limit and was cut here]'
+				: ''
+
+			return {
+				success: true,
+				output: `${result.body}${arrivedAt}${cut}`,
+				data: {
+					url: result.url,
+					status: result.status,
+					truncated: result.truncated,
+					redirects: result.redirects,
+					...(result.contentType === undefined ? {} : { contentType: result.contentType }),
+				},
+			}
+		} catch (err) {
+			if (err instanceof WebFetchRefusedError) {
+				// The refusal reaches the model in its own words, because the
+				// reason is actionable: a wrong scheme is a mistake it can fix,
+				// and a private address is one it should stop trying.
+				return { success: false, output: '', error: err.message }
+			}
+			return {
+				success: false,
+				output: '',
+				error: `Fetching "${input.url}" failed: ${err instanceof Error ? err.message : String(err)}`,
+			}
+		}
+	},
+})
+
+export const WebSearchTool = defineTool({
+	name: WEB_SEARCH_TOOL_NAME,
+	description:
+		"Searches the web and returns titles, URLs and the provider's own snippets. Fetch a result with web_fetch before relying on its contents.",
+	inputSchema: searchInput,
+	category: 'network',
+	permissions: ['network_access'],
+	readOnly: true,
+	destructive: false,
+	concurrencySafe: true,
+
+	async execute(input, context) {
+		if (!context.web?.search) {
+			// This kernel ships no search backend, so "not configured" is the
+			// ordinary case rather than an error state — and saying which
+			// piece is missing is what tells an operator it is a wiring
+			// decision and not a failure.
+			return {
+				success: false,
+				output: '',
+				error:
+					'This run has no web search provider configured. Namzu ships no search backend; a host supplies one.',
+			}
+		}
+
+		const result = await context.web.search.search({
+			query: input.query,
+			...(input.limit === undefined ? {} : { limit: input.limit }),
+			...(context.abortSignal ? { signal: context.abortSignal } : {}),
+		})
+
+		if (result.hits.length === 0) {
+			// A real answer, and distinct from the refusal above: the search
+			// happened and found nothing.
+			return { success: true, output: `No results for "${input.query}".`, data: { hits: [] } }
+		}
+
+		return {
+			success: true,
+			output: result.hits
+				.map(
+					(hit, i) =>
+						`${i + 1}. ${hit.title}\n   ${hit.url}${hit.snippet ? `\n   ${hit.snippet}` : ''}`,
+				)
+				.join('\n'),
+			data: { query: result.query, hits: result.hits },
+		}
+	},
+})

package/src/tools/builtins/write-file.ts

@@ -1,7 +1,7 @@
 import { access, mkdir } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { z } from 'zod'
-import type { ToolContext } from '../../types/tool/index.js'
+import type { ToolContext, ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
@@ -80,6 +80,42 @@ export const WriteFileTool = defineTool({
 	destructive: true,
 	concurrencySafe: false,
 
+	/**
+	 * The whole file body, described by the tool.
+	 *
+	 * A `diff` with an EMPTY `before`, which is what a write actually is:
+	 * whatever was there is gone and this is what replaces it. `edit`
+	 * declines to do that for an insert — there, an empty `before` would
+	 * claim the whole file was added and it was not. Here it is true.
+	 *
+	 * A host with nothing to contrast against renders the `after` plainly
+	 * rather than as `+` lines, which is the row a reader wants: they are
+	 * approving a file, not reviewing a patch.
+	 */
+	presentCall(input: WriteInput) {
+		const content = input.content ?? input.newStr
+		if (typeof content !== 'string') return undefined
+		return {
+			kind: 'diff' as const,
+			...(input.path ? { path: input.path } : {}),
+			before: '',
+			after: content,
+		}
+	},
+
+	/**
+	 * A label, deliberately — which is what suppresses the detail block.
+	 *
+	 * The content was already shown under the CALL, where the user could
+	 * act on it. Repeating it under the result doubles the longest rows in
+	 * the transcript to say nothing new. A host used to decide this by
+	 * matching `name === 'write' || name === 'edit'`; it is the tool's to
+	 * say, and now it says it.
+	 */
+	presentResult(_input: WriteInput, result: ToolResult) {
+		return { kind: 'generic' as const, label: result.output?.split('\n')[0] ?? '' }
+	},
+
 	async execute(input: WriteInput, context) {
 		// `execute` is reachable without going through the registry, so the
 		// closed contract has to be enforced on this path too or it is not

package/src/tools/coordinator/agent.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod'
 
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
-import type { TaskGateway } from '../../types/agent/gateway.js'
+import type { TaskScheduler } from '../../types/agent/scheduler.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
@@ -44,7 +44,7 @@ import type { TaskLaunchedCallback } from './index.js'
  * Neither is legacy. Pick by how much of the coordinator surface you want.
  */
 export interface AgentToolOptions {
-	gateway: TaskGateway
+	gateway: TaskScheduler
 	workingDirectory: string
 	runtimeContext?: AgentRuntimeContext
 	allowedAgentIds: string[]

package/src/tools/coordinator/index.ts

@@ -1,13 +1,15 @@
 import { z } from 'zod'
-import type { CompletionInbox } from '../../gateway/completion-inbox.js'
 import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { PendingAnswers, QuestionParkRecorder } from '../../runtime/query/question-park.js'
+import type { CompletionInbox } from '../../scheduler/completion-inbox.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
-import type { TaskGateway } from '../../types/agent/gateway.js'
+import type { TaskScheduler } from '../../types/agent/scheduler.js'
 import type { ResumeHandler, UserQuestionOption } from '../../types/hitl/index.js'
 import type { RunId, TaskId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { asCheckpointId, asTaskId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
 import { wrapUntrusted } from '../untrusted-envelope.js'
 import { failureLabel, taskSucceeded } from './outcome.js'
@@ -31,7 +33,7 @@ export type TaskLaunchedCallback = (
 ) => void
 
 export interface CoordinatorToolsOptions {
-	gateway: TaskGateway
+	gateway: TaskScheduler
 	workingDirectory: string
 	runtimeContext?: AgentRuntimeContext
 	allowedAgentIds: string[]
@@ -48,6 +50,16 @@ export interface CoordinatorToolsOptions {
 
 	taskStore?: TaskStore
 
+	/**
+	 * Called when a plan is APPROVED, so the run can leave plan mode.
+	 *
+	 * A callback rather than a store handle, because what "leaving plan
+	 * mode" means belongs to whoever owns the mode — a run flipping its own
+	 * box, a host persisting to a topic record, both, or neither. This file
+	 * knows only that approval happened.
+	 */
+	onPlanApproved?: () => Promise<void> | void
+
 	runId?: RunId
 
 	getPlanManager?: () => PlanManager | undefined
@@ -409,7 +421,7 @@ export const DELEGATION_TIMEOUT_MS = 60 * 60 * 1000
  * `NAMZU_DELEGATION_IDLE_MS` to change it.
  *
  * Only armed when the gateway can report progress at all; see
- * `TaskGateway.onTaskProgress`.
+ * `TaskScheduler.onTaskProgress`.
  */
 export const DELEGATION_IDLE_MS = readPositiveIntEnv('NAMZU_DELEGATION_IDLE_MS', 5 * 60 * 1000)
 
@@ -446,6 +458,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		allowedAgentIds: agentIds,
 		allowDelegation,
 		taskStore,
+		onPlanApproved,
 		runId,
 		getPlanManager,
 		resumeHandler,
@@ -464,7 +477,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	/**
 	 * The tasks THIS surface launched — the scope of everything it will read back.
 	 *
-	 * A `TaskGateway` is shared on purpose: `SupervisorAgentConfig.gateway`
+	 * A `TaskScheduler` is shared on purpose: `SupervisorAgentConfig.scheduler`
 	 * exists so a host can hand the same one to several runs. `listTasks()` is
 	 * therefore gateway-wide by design, and `agent_task_list` used to hand that
 	 * straight to the model — so a supervisor could read a sibling run's worker
@@ -612,7 +625,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 
 			if (taskStore) {
 				if (resolvedPlanTaskId) {
-					await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
+					await taskStore.update(asTaskId(resolvedPlanTaskId), {
 						status: 'in_progress',
 						owner: agent_id,
 					})
@@ -673,7 +686,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				// worker behind it — indefinitely, since nothing later will
 				// close a task whose launch never happened.
 				if (resolvedPlanTaskId && taskStore) {
-					await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
+					await taskStore.update(asTaskId(resolvedPlanTaskId), {
 						status: 'failed',
 						description: 'Failed: the launch was refused before any worker started',
 					})
@@ -776,7 +789,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				// statuses saw work that had been done; only a reader of every
 				// description saw otherwise — and a dependent unit had no way
 				// to tell at all.
-				await taskStore.update(resolvedPlanTaskId as `task_${string}`, {
+				await taskStore.update(asTaskId(resolvedPlanTaskId), {
 					status: success ? 'completed' : 'failed',
 					description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
 				})
@@ -849,10 +862,17 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		// waiting. Same bound as the launch it is waiting on.
 		timeoutMs: DELEGATION_TIMEOUT_MS,
 		async execute({ task_id }, _context) {
+			// ONE cast, hoisted, and deliberately not `asTaskId`. The membership
+			// gate below is a strictly stronger check than the prefix: a
+			// `task_` spelling proves nothing about ownership, and
+			// `launchedHere` proves both that the id is real and that this run
+			// owns it. A prefix check in front of it would be a check whose
+			// every failure the next line already catches.
+			const taskId = task_id as TaskId
 			// Same scope as the listing — see `launchedHere`. Asked FIRST, so a
 			// task belonging to a sibling run on a shared gateway is refused
 			// here rather than waited on and then read.
-			if (!launchedHere.has(task_id as TaskId)) {
+			if (!launchedHere.has(taskId)) {
 				// Deliberately does not distinguish "never existed" from
 				// "belongs to someone else". The second answer is itself the
 				// leak in miniature: it confirms a task id a run was not
@@ -864,7 +884,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
-			const known = gateway.getTask(task_id as TaskId)
+			const known = gateway.getTask(taskId)
 			if (!known) {
 				return {
 					success: false,
@@ -873,7 +893,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
-			const outcome = await waitForTaskWithBounds(gateway, task_id as TaskId, {
+			const outcome = await waitForTaskWithBounds(gateway, taskId, {
 				runMs: DELEGATION_TIMEOUT_MS,
 				idleMs: DELEGATION_IDLE_MS,
 			})
@@ -888,11 +908,11 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			if (_context.abortSignal?.aborted) {
 				return {
 					success: false,
-					output: `This wait was abandoned before task ${task_id} finished; ${whereTheResultWillTurnUp(task_id as TaskId)}`,
+					output: `This wait was abandoned before task ${task_id} finished; ${whereTheResultWillTurnUp(taskId)}`,
 					data: { task_id, abandoned: true },
 				}
 			}
-			completionInbox?.claim(task_id as TaskId)
+			completionInbox?.claim(taskId)
 
 			const success = completed.state === 'completed'
 			const resultText =
@@ -932,13 +952,17 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		destructive: false,
 		concurrencySafe: true,
 		async execute({ task_id }) {
-			gateway.cancelTask(task_id as TaskId)
+			// One cast at the boundary. `cancelTask` is idempotent on an id it
+			// does not know, so a malformed one is a no-op rather than a fault —
+			// which is why this is a cast and not a throwing constructor.
+			const taskId = task_id as TaskId
+			gateway.cancelTask(taskId)
 			// Stop holding the run open for it. `expect` put this task on the
 			// inbox's outstanding list at launch and only a completion takes it
 			// off — so without this a cancelled worker kept `hasPendingWork`
 			// true and every attempt to settle paid the full grace period
 			// waiting for a result that had just been called off.
-			completionInbox?.forget(task_id as TaskId)
+			completionInbox?.forget(taskId)
 			return {
 				success: true,
 				output: `Task ${task_id} cancelled`,
@@ -947,6 +971,78 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
+	const continueTaskTool = defineTool({
+		name: 'continue_task',
+		description:
+			"Send a further instruction to a running agent task you launched with create_task. Use it to redirect a background worker that is heading the wrong way, instead of cancelling it and losing everything it has done. Does not block: the worker's result still arrives the way it already would.",
+		inputSchema: z.object({
+			task_id: z.string().describe('Agent task ID from a previous create_task'),
+			message: z.string().describe('The instruction to hand the worker'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ task_id, message }) {
+			// ONE cast, hoisted, and deliberately not `asTaskId`. The membership
+			// gate below is a strictly stronger check than the prefix: a
+			// `task_` spelling proves nothing about ownership, and
+			// `launchedHere` proves both that the id is real and that this run
+			// owns it. A prefix check in front of it would be a check whose
+			// every failure the next line already catches.
+			const taskId = task_id as TaskId
+			// Same fencing as the listing and the wait — see `launchedHere`.
+			// Asked FIRST, so a task belonging to a sibling run on a shared
+			// gateway is refused before anything is delivered to it.
+			if (!launchedHere.has(taskId)) {
+				// Does not distinguish "never existed" from "belongs to someone
+				// else", for the reason `wait_for_task` gives: the second answer
+				// confirms a task id this run was not supposed to know.
+				return {
+					success: false,
+					output: `No task ${task_id} was launched by this run. Call agent_task_list to see the tasks you can steer.`,
+					data: { task_id },
+				}
+			}
+
+			const known = gateway.getTask(taskId)
+			if (!known) {
+				return {
+					success: false,
+					output: `Task ${task_id} is no longer tracked, so there is nothing to send it.`,
+					data: { task_id },
+				}
+			}
+
+			try {
+				await gateway.continueTask(taskId, message)
+			} catch (err) {
+				// The manager refuses a terminal task by throwing, and a throw
+				// out of `execute` is a tool ERROR — which reads to the model as
+				// "the platform broke" rather than "that worker has finished".
+				// Named as a refusal with the state in it, so the next move is
+				// obvious: read its result instead of steering it.
+				return {
+					success: false,
+					output: `Could not send to task ${task_id} (state: ${known.state}): ${toErrorMessage(err)}`,
+					data: { task_id, state: known.state },
+				}
+			}
+
+			// Deliberately does not wait. The worker's result arrives the way it
+			// already would — as this call's `tool_result` for a blocking
+			// launch, or as a completion notification for a background one — and
+			// blocking here would turn a redirect into a second `wait_for_task`
+			// the supervisor did not ask for.
+			return {
+				success: true,
+				output: `Sent to task ${task_id}. It will see this at its next turn; its result still arrives the way it already would.`,
+				data: { task_id },
+			}
+		},
+	})
+
 	const agentTaskList = defineTool({
 		name: 'agent_task_list',
 		description: `Inspect the live state of the agent tasks YOU launched with create_task: returns each task's id, agent, state (pending/running/completed/failed/canceled), and timing. Tasks launched by another run are not listed, even when it shares this gateway. Distinct from the plan-task store's \`task_list\` (which lists planning tasks): this tool lists running/completed worker invocations. ${listingAdvice}`,
@@ -1047,32 +1143,27 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 		},
 	})
 
-	// `continue_task` is gone, and the reasoning is worth keeping because
-	// the obvious argument for bringing it back does not survive contact.
-	//
-	// It was dropped on the grounds that a blocking `create_task` leaves every
-	// worker terminal before a later turn learns its id, and the manager
-	// refuses `continue` on a terminal task. `background: true` reinstated that
-	// precondition — a live id is reachable now — so the question was reopened.
+	// `continue_task` is registered again, and the reasoning that dropped it
+	// is kept because it was correct and has expired rather than been wrong.
 	//
-	// Measured rather than assumed, and it fails on the other side. On a LIVE
-	// task the manager accepts the call and pushes onto `pendingMessages`,
-	// and NOTHING drains that queue during a run. This codebase already
-	// knows: `runtime/query/steering.ts` says in as many words that
-	// `queueMessage`/`drainMessages` were never read by the iteration loop,
-	// and `SteeringChannel` exists BECAUSE of that — it delivers guidance on a
-	// tool result instead, since a `tool_use` must be answered by a
-	// `tool_result` with the same id and there is no legal slot for a user
-	// message mid-batch.
+	// It read: on a LIVE task the manager accepts the call and pushes onto
+	// `pendingMessages`, and NOTHING drains that queue during a run — so the
+	// tool had no state it worked in. Terminal tasks refused it; live ones
+	// accepted it into a queue nobody read. Registering it would have handed
+	// the model a call that silently does nothing, which is worse than an
+	// unregistered definition, because a tool that cannot be called at least
+	// cannot fail quietly.
 	//
-	// So the tool had no state it worked in: terminal tasks refuse it, live
-	// tasks accept it into a queue nobody reads. Registering it would have
-	// handed the model a call that silently does nothing — worse than the
-	// unregistered definition it replaced, because a defined-but-unreachable
-	// tool at least cannot be called.
+	// The comment named its own expiry condition: "if follow-ups on a live
+	// worker are wanted, the work is a consumer for the queue". That consumer
+	// exists — `BaseAgentConfig.inboundMessages`, drained at the iteration
+	// boundary — so the precondition the tool needed is met and the argument
+	// against it no longer holds.
 	//
-	// If follow-ups on a live worker are wanted, the work is a consumer for
-	// the queue or a steering channel that reaches a child, not this tool.
+	// A supervisor whose background worker is heading the wrong way could
+	// previously only wait for it or kill it, and killing it throws away
+	// everything it has done.
+
 	// `cancel_task` is registered again, and the reasoning that dropped it is
 	// worth keeping because it was sound at the time and is not any more.
 	//
@@ -1128,7 +1219,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	// behaviour exactly.
 	const canDelegate = agentIds.length > 0 && allowDelegation !== false
 	const tools: ToolDefinition[] = canDelegate
-		? [createTask, waitForTaskTool, cancelTask, agentTaskList]
+		? [createTask, waitForTaskTool, continueTaskTool, cancelTask, agentTaskList]
 		: [agentTaskList]
 
 	if (getPlanManager) {
@@ -1265,6 +1356,19 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					const output = response.feedback
 						? `Plan approved by user with required edits — apply them during execution:\n${response.feedback}\nProceed with execution — launch workers via create_task.${howToReport}`
 						: `Plan approved by user. Proceed with execution — launch workers via create_task.${howToReport}`
+					// An approved plan LEAVES plan mode, in this conversation and
+					// durably. That flow — look around under plan mode, propose,
+					// get approval, continue in the SAME run — is what the mode's
+					// per-run lifetime made impossible: leaving it meant ending
+					// the run and discarding the step and tool-schema context.
+					//
+					// Failures are swallowed with a log rather than turning an
+					// approval into a refusal. The user said yes; a state store
+					// that cannot record it is an operator's problem to see in the
+					// logs, not a reason to tell the model its approved plan was
+					// rejected.
+					await onPlanApproved?.()
+
 					return {
 						success: true,
 						output,
@@ -1480,7 +1584,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					(await parkHandler({
 						type: 'user_question',
 						runId: parkRunId,
-						checkpointId: parkedAt ?? `cp_question_${toolUseId}`,
+						checkpointId: parkedAt ?? asCheckpointId(`cp_question_${toolUseId}`),
 						question: questionData,
 					}))
 

package/src/tools/coordinator/outcome.ts

@@ -1,4 +1,4 @@
-import type { TaskHandle } from '../../types/agent/gateway.js'
+import type { TaskHandle } from '../../types/agent/scheduler.js'
 
 /**
  * Did this worker actually succeed?
@@ -48,7 +48,7 @@ export function taskSucceeded(handle: Pick<TaskHandle, 'state' | 'result'>): boo
  * the gateway state would never see it fail.
  *
  * Third copy of this knowledge, now in the one place `taskSucceeded` already
- * lives — it was written independently in `LocalTaskGateway`, which got it
+ * lives — it was written independently in `LocalTaskScheduler`, which got it
  * right, but a rule that each caller has to remember is a rule one of them
  * eventually forgets. That has already happened once with `taskSucceeded`.
  */

package/src/tools/coordinator/wait-with-idle-bound.ts

@@ -1,4 +1,4 @@
-import type { TaskGateway, TaskHandle } from '../../types/agent/gateway.js'
+import type { TaskHandle, TaskScheduler } from '../../types/agent/scheduler.js'
 import type { TaskId } from '../../types/ids/index.js'
 
 /**
@@ -22,7 +22,7 @@ import type { TaskId } from '../../types/ids/index.js'
  *
  * The idle bound is only armed when the gateway can report progress.
  * `onTaskProgress` is optional on the contract, because hosts implement
- * `TaskGateway` and not all of them can observe their children — so a gateway
+ * `TaskScheduler` and not all of them can observe their children — so a gateway
  * without it is bounded by the wall clock alone, exactly as before. That is a
  * real degradation and it is deliberately visible in the result rather than
  * silent: `idleBoundArmed` says whether the quieter half was ever watching.
@@ -61,7 +61,7 @@ export interface WaitBounds {
  * been unpicking.
  */
 export async function waitForTaskWithBounds(
-	gateway: TaskGateway,
+	gateway: TaskScheduler,
 	taskId: TaskId,
 	bounds: WaitBounds,
 	now: () => number = Date.now,

package/src/tools/defineTool.ts

@@ -5,6 +5,7 @@ import type {
 	ToolPermission,
 	ToolResult,
 } from '../types/tool/index.js'
+import type { ToolPresentation } from '../types/tool/presentation.js'
 import { toErrorMessage } from '../utils/error.js'
 
 export interface DefineToolOptions<S extends z.ZodType> {
@@ -20,6 +21,17 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
 	tier?: string
+	/**
+	 * How this tool's call and result should be shown; see
+	 * {@link ToolPresentation}.
+	 *
+	 * Here rather than only on `ToolDefinition` for the reason `maxRetries`
+	 * is: this builder is the sanctioned way to author a tool, and a field
+	 * the executor reads that the builder cannot set is a field only
+	 * hand-written definitions can use.
+	 */
+	presentCall?: ToolPresentation<z.infer<S>>['presentCall']
+	presentResult?: ToolPresentation<z.infer<S>>['presentResult']
 	/** Per-execution deadline; see {@link ToolDefinition.timeoutMs}. */
 	timeoutMs?: number
 	/**
@@ -54,6 +66,8 @@ export function defineTool<S extends z.ZodType>(
 		tier: options.tier,
 		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
 		...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
+		...(options.presentCall ? { presentCall: options.presentCall } : {}),
+		...(options.presentResult ? { presentResult: options.presentResult } : {}),
 		...(options.outputSchema !== undefined ? { outputSchema: options.outputSchema } : {}),
 		...(options.terminal !== undefined ? { terminal: options.terminal } : {}),
 		category: options.category,