Agent / foldkit-agent

Record decisions with the audit log

Attach Agent.auditLog({ capacity, principal, includeInput?, redact? }) when binding to record every accepted, refused, and unknown outcome in a bounded ring buffer:

ts
type User = { readonly id: string }
const UserAgent = Agent.forApplication(App).withPrincipal<User>()
const audit = Agent.auditLog({
  capacity: 500,
  principal: (caller: User) => caller.id,
})

const audited = UserAgent.bind({
  definition: UserAgent.make({
    messages: UserAgent.expose(Message, { RequestedCreateTodo: 'Create a new todo' }),
  }),
  host: { ...host, principal: () => ({ id: 'user-1' }) },
  audit,
})

By default the log omits raw inputs (opt in with includeInput: true and redact), requires an explicit principal projector, and never stores the Model. A failing AuditSink never breaks dispatch.

Generate manifests and inspect contracts

Contracts are inspectable data, testable without an LLM, and exportable as committed snapshots:

ts
Agent.messages(AppAgent).map(message => message.name)
// ['requested_create_todo', 'delete_todo']

const manifestJson = JSON.stringify(Agent.toManifest(AppAgent), null, 2)
const markdownDocs = Agent.toMarkdown(AppAgent)

Main exports

Why capabilities are Messages and hosts wrap config

  • Messages over Model setters: Exposing Messages keeps every transition inside update, preserving replay, validation, and side effects rather than adding a second mutation path.
  • Agent.host wrapping: Foldkit's makeApplication returns a handle without direct model() or dispatch() accessors, so Agent.host(config) instruments update and subscriptions once before run, hydrate, embed, or SSR.hydrate.
  • forApplication / forModel inference: Fixing Model upfront lets TypeScript infer model inside inline available, authorize, and applies callbacks without type annotations.

Next