@hanfani/core 0.1.2 → 0.1.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Aziz Mashkour
+Copyright (c) 2026 Fruitizz
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,96 +2,40 @@
 
 Headless engine and types for the Hanfani agent framework.
 
-Pure logic — no I/O, no server, no React. This is the layer that defines what a
-workflow and an agent *are* and enforces the framework's one safety invariant:
+Pure logic — no I/O, no server, no UI. It defines what a workflow and an agent
+*are* and enforces one rule:
 
-> An agent proposes, a human approves, the server acts.
+> **The agent proposes, a human approves, the server acts.**
 
-`defineAgent` refuses any `effect` that isn't also an `approval`, so a side
-effect can never be wired to fire without a human gate. `providerConformanceChecks`
-proves any provider honours that at runtime.
+`defineAgent` refuses any side effect that isn't behind a human-approval gate,
+and `providerConformanceChecks` proves any model provider honors that at runtime.
 
-## Exports
+## Install
 
-### Definitions
-
-| Export | Description |
-| --- | --- |
-| `defineAgent` | Validate and construct an agent definition; enforces that every `effect` is a gated `approval`. |
-| `defineWorkflow` | Validate a workflow descriptor (unique agent ids, role:input entry agent, in-workflow handoffs, unique inputs) and return it. |
-| `definePrompt` | Build a prompt strategy from `onStart` / `onInput` / `onResume` handlers. |
-| `defineProviders` | Build a provider registry that resolves provider factories by name. |
-| `AgentDefinitionSchema` | The Zod schema backing `defineAgent`. |
-
-### Messages
-
-| Export | Description |
-| --- | --- |
-| `isAssistant` | Type guard for assistant messages. |
-| `isToolMessage` | Type guard for tool-result messages. |
-| `toolCallsOf` | Extract the tool calls from a message. |
-| `hasPendingApproval` | True when an approval tool was called but has no tool result yet. |
-| `pairToolResults` | Map each tool result to the `toolCallId` it answers. |
-| `lastApprovalArgs` | Parsed arguments of the most recent approval tool call, or `null`. |
-| `resolvedApprovalCount` | How many approval calls have a matching tool result. |
-| `approvalResolved` | True when at least one approval call has resolved. |
-
-### Handoffs
-
-| Export | Description |
-| --- | --- |
-| `encodeHandoff` | Encode a payload as a user message downstream agents can decode. |
-| `decodeHandoff` | Decode and validate the latest handoff payload from run input. |
-| `handoffNote` | Emit a handoff note event. |
-| `HandoffPayloadSchema` | Zod schema for a generic thread/email handoff payload. |
-| `TicketHandoffPayloadSchema` | Zod schema for a ticket/issue handoff payload. |
-
-### Gates & events
-
-| Export | Description |
-| --- | --- |
-| `gateOpened` | Emit the custom event that opens a human-approval gate. |
-| `readGateOpened` | Read a `GATE_OPENED` value off an event, or `null`. |
-| `GATE_OPENED` | The gate-opened custom event name constant. |
-| `GateOpenedValueSchema` | Zod schema for a gate-opened value. |
-| `lifecycleNote` | Emit a lifecycle note event. |
-| `LIFECYCLE_NOTE_TEXT` | Human-readable label for each terminal outcome. |
-| `foldEventsToMessages` | Fold an ag-ui event stream into a flat list of messages. |
-
-### Lifecycle & delivery
-
-| Export | Description |
-| --- | --- |
-| `lifecycle` | Derive display lifecycle (`isLive` / `isVisible` / `covers`) from phase + outcome. |
-| `hasLiveDescendant` | Set of ids that have a live descendant in a parent/child tree. |
-| `resolveDelivery` | Resolve where a payload should be delivered (agent or contract). |
-| `instanceId` | Stable `workflow__agent` instance id. |
-| `composeInstructions` | Prepend the workflow prompt to an agent's instructions. |
-
-### Providers & integration
+```bash
+pnpm add @hanfani/core
+```
 
-| Export | Description |
-| --- | --- |
-| `providerConformanceChecks` | Provider-agnostic suite proving a provider honours the gate/effect contract. |
-| `aggregateHealth` | Return the first failing health check, or an ok result. |
-| `isOk` | Narrow a `HealthCheck` to its ok variant. |
-| `isOAuth2` | Narrow an `AuthSpec` to its oauth2 variant. |
+## Quick look
 
-Plus the full type surface: `WorkflowDescriptor`, `Outcome`, `Phase`, `Provider`,
-`EffectFn`, `AuthSpec`, `ResolvedCredential`, and more.
+```ts
+import { defineAgent } from '@hanfani/core'
 
-## Build & test
+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' },
+})
+```
 
-Built with the native TypeScript 7 compiler (`tsc` / tsgo) — no bundler, no
-compiler-API tooling, so nothing here breaks on the TS 7 upgrade.
+## Docs
 
-```bash
-pnpm build       # tsc -p tsconfig.build.json → dist/*.js + dist/*.d.ts
-pnpm typecheck   # tsc -p tsconfig.json --noEmit
-pnpm test        # vitest smoke suite
-```
+Full API reference and guides are coming soon in the Hanfani framework docs.
 
-## Peer runtime
+## License
 
-Depends on `@ag-ui/client` (event/message types) and `zod` (schemas). Both are
-declared as regular dependencies.
+[MIT](./LICENSE) License © [Fruitizz](https://github.com/fruitizz)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@hanfani/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Headless engine and types for the Hanfani agent framework.",
   "license": "MIT",
-  "author": "Aziz Mashkour",
+  "author": "Fruitizz",
   "type": "module",
   "sideEffects": false,
   "files": [