@hanfani/core

Headless engine and types for the Hanfani agent framework.

Pure logic — no I/O, no server, no UI. It defines what a workflow and an agent are and enforces one rule:

The agent proposes, a human approves, the server acts.

defineAgent refuses any side effect that isn't behind a human-approval gate, and providerConformanceChecks proves any model provider honors that at runtime.

Architecture

@hanfani/core is the shared contract between three layers — definitions and pure logic live here; execution and rendering live in consuming apps.

defineAgent and defineWorkflow declare what agents and workflows are — tools, approvals, effects, handoffs, and published input contracts. A provider calls run() and emits a GATE_OPENED event when an approval tool fires; the UI renders the proposed artifact and the human approves or rejects. On approve, the server runs the bound effect; on reject, no side effects run. providerConformanceChecks certifies that any provider adapter honors this two-phase contract.

Install

pnpm add @hanfani/core

Quick look

import { defineAgent } from '@hanfani/core'

const reply = defineAgent({
  id: 'reply',
  name: 'Reply',
  provider: 'claude',
  instructions: 'Draft a reply for the human to approve.',
  tools: ['saveDraft'],
  approvals: ['saveDraft'], // saveDraft only fires after a human approves
  renders: { saveDraft: 'DraftCard' },
})

Dependencies

Depends on @ag-ui/client (event/message types) and zod (schemas), both declared as regular dependencies.

Docs

An auto-generated API reference is available at jsdocs.io. Full guides are coming soon in the Hanfani framework docs.

License

MIT License © Fruitizz