Agent / foldkit-agent
How dispatch executes and fails
Every invocation runs six steps against a single Model snapshot captured at the start of dispatch:
- Resolve the capability by Message constructor or protocol name (
AgentUnknownCapabilityError). - Check
available(model)beforeauthorizeso unavailable tools report as unavailable rather than leaking authorization status (AgentCapabilityUnavailableError). - Decode input strictly through the capability's Effect Schema, rejecting excess fields (
AgentInvalidInputError). - Check
authorize(AgentAuthorizationError). - Check
appliesagainst the snapshot and decoded input (AgentCapabilityUnavailableError). - Construct and dispatch the Message into
host.dispatch.
Because available, authorize, and toMessage share one immutable Model snapshot, contextual checks like reading Option.getOrThrow(model.selectedTodoId) after checking Option.isSome(model.selectedTodoId) stay consistent across async authorize calls.
All failures are tagged, Schema-backed errors (AgentUnknownCapabilityError, AgentCapabilityUnavailableError, AgentInvalidInputError, AgentAuthorizationError, AgentCancelledError, AgentCompletionTimeoutError, AgentResourceError) narrowable with Effect.catchTag:
agentRuntime.messages
.dispatch(Message.RequestedCreateTodo, { title: 'x' })
.pipe(
Effect.catchTag('AgentCapabilityUnavailableError', error =>
Effect.succeed(`${error.capability} is not available`),
),
)Dispatch also accepts a third invocation argument ({ id, transport, signal }) and exposes dispatchUnknown(name, payload, invocation) for protocol adapters reading unvalidated wire payloads. Input types reflect the encoded side of the Schema so transforming codecs (such as Schema.NumberFromString) accept wire strings.