Tools

Typed tool definitions, execution context, interactions, and normalized outcomes.

`tool`

Access: @nylorun/harness → tool

Prepares a typed tool definition for model-visible JSON Schema and runtime argument validation.

Name	Type	Required	Description
`value`	`ToolDefinition<Parameters, State>`	Yes	The tool declaration to prepare. `Parameters` must be a synchronous Zod object schema.
Returns	`ToolDefinition<Parameters, State>`	—	The prepared definition with TypeScript inference preserved.

Access: @nylorun/harness → ToolDefinition, ToolObjectSchema

Name	Type	Required	Description
`name`	`string`	Yes	Stable tool name exposed to the model.
`description`	`string`	No	Model-visible purpose of the tool.
`parameters`	`ToolObjectSchema`	Yes	Synchronous Zod object schema for arguments.
`execute(args, context)`	Async function	Yes	Performs host-owned work and resolves to a `ToolOutcome`.

Access: @nylorun/harness → ToolExecutionContext, ToolExecutionResume

Name	Type	Required	Description
`sessionId`	`string`	Yes	Owning session id.
`turnId`	`string`	Yes	Owning turn id.
`stepId`	`string`	Yes	Owning model-step id.
`callId`	`string`	Yes	Validated model tool-call id.
`invocationId`	`string`	Yes	Unique execution invocation id.
`signal`	`AbortSignal`	Yes	Cancellation signal for the host service call.
`state`	`Promise<State>`	Capability state only	Session-local state created by the capability.
`resume`	`ToolExecutionResume`	No	Correlated approval or response when a paused tool resumes.

Access: @nylorun/harness → ToolOutcome, ToolResult, DeferredOutcome

`kind`	Additional fields	Description
`completed`	`output: JsonValue`	Emits a completed `ToolResult` to the model loop.
`denied`	`reason: string`	Emits a denied `ToolResult`.
`failed`	`code: string`, `message: string`	Emits a failed `ToolResult`.
`interaction-required`	`interaction: Interaction`, optional `token`	Pauses the session for approval or a response.
`deferred`	optional `token: JsonValue`	Leaves an active record for the host to persist and later continue.

Access: @nylorun/harness → Interaction, RequiredInteraction, SealedToolCall, BoundToolDefinition, BoundToolSchema, ToolOwner

Type	Fields	Description
`Interaction`	optional `id`, `kind`, `prompt`, optional `metadata`	Request for `approval` or `response` before a tool can continue.
`RequiredInteraction`	`Interaction` plus required `id`	Interaction after Harness has assigned its id.
`SealedToolCall`	`callId`, `toolName`, `args`	Validated, executable model tool call.
`BoundToolDefinition`	Prepared `parameters`, `execute`, `owner`	Tool definition after capability binding.
`ToolOwner`	`middlewareId`, `slot`	Capability location that supplied the tool.