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:

ts
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 }),
    },
  }),
})
  • input and toMessage always go together when the external tool schema differs from the internal Message payload (for example, hiding an internal source tag or injecting invocation.id). Written inline, toMessage, authorize, and applies infer the decoded input type automatically.
  • authorize returns true, false, { allowed: false, reason }, or an Effect of one. Returning a reason sets the AgentAuthorizationError message shown to the caller.
  • applies checks row-level preconditions against the Model after authorize succeeds (returning AgentCapabilityUnavailableError), preventing unauthorized callers from probing record existence.
  • name defaults 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:

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

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