Agent / foldkit-agent
Configure capabilities, authorization, and completion
Agent.expose lets you configure each exposed variant inline with name, description, available, authorize, applies, input, toMessage, and completion:
const ProtectedAgent = AuthorizedAgent.make({
messages: AuthorizedAgent.expose(DetailedMessage, {
RequestedDeleteTodo: {
name: 'delete_todo',
description: 'Delete a todo',
available: model => Option.isSome(model.selectedTodoId),
authorize: ({ principal }) => principal.canDelete,
applies: ({ input, model }) => model.todos.some(t => t.id === input.id),
input: Schema.Struct({ id: Schema.String }),
toMessage: ({ id }) => ({ id, source: 'Agent' as const }),
},
}),
})inputandtoMessagealways go together when the external tool schema differs from the internal Message payload (for example, hiding an internalsourcetag or injectinginvocation.id). Written inline,toMessage,authorize, andappliesinfer the decodedinputtype automatically.authorizereturnstrue,false,{ allowed: false, reason }, or anEffectof one. Returning areasonsets theAgentAuthorizationErrormessage shown to the caller.applieschecks row-level preconditions against the Model afterauthorizesucceeds (returningAgentCapabilityUnavailableError), preventing unauthorized callers from probing record existence.namedefaults to snake_case from the tag (RequestedDeleteTodo→requested_delete_todo) and must match[a-zA-Z0-9_-]{1,128}.
Narrow completion correlation with Agent.variant
When declaring a Message-based completion contract, wrap the entry in Agent.variant(...) so correlate narrows result to the declared success / failure Messages instead of the entire Message union:
import { Duration } from 'effect'
const CorrelatedAgent = AuthorizedAgent.make({
messages: AuthorizedAgent.expose(DetailedMessage, {
RequestedDeleteTodo: Agent.variant({
description: 'Delete a todo',
input: Schema.Struct({ id: Schema.String }),
toMessage: ({ id }) => ({ id, source: 'Agent' as const }),
completion: {
success: DetailedMessage.DeletedTodo,
failure: DetailedMessage.FailedDeleteTodo,
correlate: (request, result) => request.id === result.id,
timeout: Duration.seconds(10),
},
}),
}),
})Use Agent.variant whenever correlate reads fields on the completion Message. Dispatched by Message constructor, result.completion is typed by the contract (completed carries the success Message, failed carries the failure Message). Give correlate whenever two calls can run concurrently—pass invocation.id in toMessage and match it on the resulting Message when inputs alone cannot distinguish calls.
Waiting defaults to 30 seconds from host.dispatch. AgentCompletionTimeoutError and AgentCancelledError stop waiting without rolling back a Message that already reached update.
Complete on state with Agent.when
When success means reaching a Model condition regardless of which Message or live sync caused it, complete on a Projection instead:
const TodoSlice = Projection.of(Model)({ todos: true })
const StateCompletedAgent = TodoAgent.make({
messages: TodoAgent.expose(Message, {
RequestedCreateTodo: {
description: 'Create a todo',
completion: Agent.when({
projection: TodoSlice,
predicate: ({ todos }, _request) => todos.length > 0,
}),
},
}),
})Agent.when requires a host with subscribe, subscribes before dispatch, and checks once immediately after so synchronous updates or already-satisfied conditions resolve right away. For values outside the Model (such as Sync.mount's committed state), pass source: { get, subscribe } instead of projection.
Reuse foldkit-surface Actions
Expose an existing foldkit-surface Action under its matching Message tag with Agent.action(action, { available?, authorize?, applies? }). Using a mismatched tag fails at compile time and at dispatch.