Agent / foldkit-agent

How dispatch executes and fails

Every invocation runs six steps against a single Model snapshot captured at the start of dispatch:

  1. Resolve the capability by Message constructor or protocol name (AgentUnknownCapabilityError).
  2. Check available(model) before authorize so unavailable tools report as unavailable rather than leaking authorization status (AgentCapabilityUnavailableError).
  3. Decode input strictly through the capability's Effect Schema, rejecting excess fields (AgentInvalidInputError).
  4. Check authorize (AgentAuthorizationError).
  5. Check applies against the snapshot and decoded input (AgentCapabilityUnavailableError).
  6. 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:

ts
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.