Agent / Expose, do not reimplement

A first end-to-end agent

Start from an application with a Todo list, a Surface projection (Overview) that hides internal UI state like form drafts, and a Principal type:

ts
import { Duration, Option, Schema } from 'effect'
import { defineMessageUnion } from 'foldkit/message'
import type * as Update from 'foldkit/update'
import { Agent } from 'foldkit-agent'
import { Entity, Expr, Write } from 'foldkit-entity'
import { Mutation, Remote } from 'foldkit-remote'
import { Surface } from 'foldkit-surface'
import type { Mounted } from 'foldkit-sync'

const Todo = Schema.Struct({ id: Schema.String, title: Schema.String, completed: Schema.Boolean })
const Model = Schema.Struct({
  listTitle: Schema.String,
  todos: Schema.Array(Todo),
  filter: Schema.Literals(['all', 'active', 'done']),
  remote: Remote.Model,
})
type Model = typeof Model.Type

const Message = defineMessageUnion({
  ...Remote.messages,
  RequestedTodo: { title: Schema.String },
  SubmittedTodo: { id: Schema.String, title: Schema.String, createdAt: Schema.Number },
  ToggledTodo: { id: Schema.String },
  ClearedCompleted: {},
  RequestedDeleteTodo: { id: Schema.String },
  RequestedCompleteTask: { id: Schema.String },
})
type Message = typeof Message.Type

const initial: Model = { listTitle: 'Todos', todos: [], filter: 'all', remote: Remote.initial }
const update = (model: Model, _message: Message): Update.Return<Model, Message> => ({ model })

const App = Surface.application({ Model, Message, initial, update })

const Overview = App.surface('Overview', {
  model: ({ model }) => ({
    listTitle: model.listTitle,
    todos: model.todos,
    filter: model.filter,
  }),
})

type Principal = { readonly actorId: string; readonly canWrite: boolean }
const isOwner = (principal: Principal) => principal.actorId === 'owner'

Specialize the builder, declare the contract exposing three capabilities, and bind it to a live host (mounted from Sync.mount, or Agent.host(config) / Agent.headless(config)):

ts
const AgentBuilder = Agent.forApplication(App).withPrincipal<Principal>()

const AssistantAgent = AgentBuilder.make({
  name: 'assistant',
  context: Overview,

  messages: AgentBuilder.expose(Message, {
    RequestedTodo: Agent.variant({
      name: 'add_todo',
      description: 'Add a todo with the given title',
      input: Schema.Struct({ title: Schema.String }),
      toMessage: ({ title }) => ({ title }),
      completion: {
        success: Message.SubmittedTodo,
        correlate: (request, result) => request.title.trim() === result.title,
      },
    }),

    ToggledTodo: {
      name: 'toggle_todo',
      description: 'Mark a todo done, or undo that',
    },

    ClearedCompleted: {
      name: 'clear_completed',
      description: 'Delete every completed todo (owner only)',
      authorize: ({ principal }) => isOwner(principal),
    },
  }),
})

const host = {
  model: mounted.model,
  dispatch: (message: Message) => {
    mounted.dispatch(message)
  },
  subscribe: mounted.subscribe,
  observe: mounted.observe,
  principal: () => principal,
}

const agentRuntime = AgentBuilder.bind({ definition: AssistantAgent, host })

Notice what stays explicit:

  • context: Overview exposes only the projected fields rather than the full Model.
  • AgentBuilder.expose opts in specific Message variants (RequestedTodo, ToggledTodo, ClearedCompleted)—there is no exposeAll.
  • input / toMessage exposes a clean protocol schema ({ title }) for intents whose update generates IDs and timestamps before emitting SubmittedTodo.
  • authorize enforces caller permissions per capability.
  • completion tells the runtime which resulting fact (SubmittedTodo) ends the call.

A host only supplies the hooks your contract uses: observe for completion contracts, and subscribe when dynamic availability or state completion watches Model changes. See the package README for Agent.host and Agent.headless.