@hanfani/core 0.1.1 → 0.1.2

package/README.md

@@ -13,22 +13,72 @@ proves any provider honours that at runtime.
 
 ## Exports
 
-- **Definitions:** `defineAgent`, `defineWorkflow`, `definePrompt`,
-  `defineProviders`, `AgentDefinitionSchema`.
-- **Messages:** `isAssistant`, `isToolMessage`, `toolCallsOf`,
-  `hasPendingApproval`, `pairToolResults`, `lastApprovalArgs`,
-  `resolvedApprovalCount`, `approvalResolved`.
-- **Handoffs:** `encodeHandoff`, `decodeHandoff`, `handoffNote`,
-  `HandoffPayloadSchema`, `TicketHandoffPayloadSchema`.
-- **Gates & events:** `gateOpened`, `readGateOpened`, `GATE_OPENED`,
-  `GateOpenedValueSchema`, `lifecycleNote`, `LIFECYCLE_NOTE_TEXT`,
-  `foldEventsToMessages`.
-- **Lifecycle & delivery:** `lifecycle`, `hasLiveDescendant`, `resolveDelivery`,
-  `instanceId`, `composeInstructions`.
-- **Providers & integration:** `providerConformanceChecks`, `aggregateHealth`,
-  `isOk`, `isOAuth2`.
-- Plus the full type surface (`WorkflowDescriptor`, `Outcome`, `Phase`,
-  `Provider`, `EffectFn`, `AuthSpec`, `ResolvedCredential`, …).
+### 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
+
+| 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. |
+
+Plus the full type surface: `WorkflowDescriptor`, `Outcome`, `Phase`, `Provider`,
+`EffectFn`, `AuthSpec`, `ResolvedCredential`, and more.
 
 ## Build & test
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanfani/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Headless engine and types for the Hanfani agent framework.",
   "license": "MIT",
   "author": "Aziz Mashkour",
@@ -19,10 +19,13 @@
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://github.com/fruitizz/hanfani-core#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/azizmashkour/hanfani-packages.git",
-    "directory": "packages/core"
+    "url": "git+https://github.com/fruitizz/hanfani-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fruitizz/hanfani-core/issues"
   },
   "keywords": [
     "hanfani",
@@ -35,6 +38,13 @@
     "@ag-ui/client": "^0.0.55",
     "zod": "^3.25.76"
   },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",