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: Overviewexposes only the projected fields rather than the fullModel.AgentBuilder.exposeopts in specificMessagevariants (RequestedTodo,ToggledTodo,ClearedCompleted)—there is noexposeAll.input/toMessageexposes a clean protocol schema ({ title }) for intents whoseupdategenerates IDs and timestamps before emittingSubmittedTodo.authorizeenforces caller permissions per capability.completiontells 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.