Agent / Expose, do not reimplement

Availability, authorization, and applies

Capabilities separate three distinct checks evaluated in order on a single Model snapshot:

  1. available(model): Is this action currently valid in the app's state? Unavailable tools drop from discovery and fail before authorize runs so disabled features leak no permission info.
  2. authorize({ principal, input, model }): May this principal call this action?
  3. applies({ model, input, principal }): Does the specific decoded input match the row state in model? Runs after authorize (and marks the capability inputDependent), returning AgentCapabilityUnavailableError with reason.
ts
const GatedAgent = AgentBuilder.make({
  name: 'gated',
  context: Overview,
  messages: AgentBuilder.expose(Message, {
    ClearedCompleted: {
      name: 'clear_completed',
      description: 'Delete every completed todo',
      available: model => model.todos.some(todo => todo.completed),
      authorize: ({ principal }) => isOwner(principal),
    },
  }),
})

A capability over a declared write

For capabilities backed by a declared Mutation.write (foldkit-remote), Data.capability reuses your Entity's held may flags (authorize), when preconditions, and invariants (applies) automatically—judged as the page's current viewer. Spread ...completeTask and compose your agent's own principal check afterward:

ts
const Task = Entity.define(
  'Task',
  Schema.Struct({ id: Schema.String, status: Schema.Literals(['open', 'done']) }),
)
const CompleteTask = Mutation.write(
  'CompleteTask',
  Write.update(
    Entity.input(Task, Schema.Struct({ id: Schema.String, status: Schema.Literal('done') })),
    { id: 'id' },
  ),
)
const Data = Remote.make({
  model: App.model.remote,
  entities: [Task],
  mutations: [CompleteTask],
})

const completeTask = Data.capability(CompleteTask, ({ input }: { input: { readonly id: string } }) => ({
  id: input.id,
  status: 'done' as const,
}))

const TaskAgent = AgentBuilder.make({
  name: 'tasks',
  context: Overview,
  messages: AgentBuilder.expose(Message, {
    RequestedCompleteTask: {
      name: 'complete_task',
      description: 'Complete an open task',
      input: Schema.Struct({ id: Schema.String }),
      toMessage: input => input,
      ...completeTask,
      authorize: request => (request.principal.canWrite ? completeTask.authorize(request) : false),
    },
  }),
})

Annotate toInput's request parameter so TypeScript preserves the input type across the object spread. When a row or field is missing locally, both authorize and applies let the request proceed so the server decides authoritatively.

If the target row is already named in Model (such as a selected task), pass Data.available(mutation, model => Option<Partial<Input>>) as available so tools that Data.can already rejects disappear from discovery—only expose Data.available when callers are permitted to know whether the viewer's write applies.