@hanfani/core 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,158 @@
+import type { BaseEvent, Message, RunAgentInput, ToolCall } from '@ag-ui/client';
+import type { z } from 'zod';
+import type { AgentDefinition } from './defineAgent.js';
+export type { Message, ToolCall };
+/** Lifecycle phase of a work item. */
+export type Phase = 'queued' | 'active' | 'awaiting_human' | 'terminal';
+/** Terminal (and running) outcome of a work item. */
+export type Outcome = 'running' | 'done' | 'stopped' | 'rejected' | 'error' | 'superseded' | 'reset' | 'dismissed';
+/** Whether an agent accepts external input or only runs as a downstream worker. */
+export type AgentRole = 'input' | 'worker';
+/** Result of a health probe. */
+export type HealthCheck = {
+    ok: true;
+    detail?: string;
+} | {
+    ok: false;
+    error: string;
+    hint: string;
+};
+/** How an integration authenticates. */
+export type AuthSpec = {
+    kind: 'none';
+} | {
+    kind: 'apiKey';
+} | {
+    kind: 'oauth2';
+    provider: string;
+    scopes: string[];
+} | {
+    kind: string;
+    [key: string]: unknown;
+};
+/** A credential resolved for a given integration + connection. */
+export type ResolvedCredential = {
+    kind: 'apiKey';
+    apiKey: string;
+} | {
+    kind: 'oauth2';
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    raw?: unknown;
+} | {
+    kind: string;
+    [key: string]: unknown;
+};
+export type CredentialResolver = (ctx: {
+    integration: string;
+    connectionId: string;
+    auth: AuthSpec;
+}) => Promise<ResolvedCredential | null>;
+/** What a prompt strategy decides to do when a gate resolves. */
+export type ResumeOutcome = {
+    kind: 'prompt';
+    text: string;
+} | {
+    kind: 'message';
+    text: string;
+} | null;
+export interface ResumeHandle {
+    runId: string;
+    input: RunAgentInput;
+}
+export interface GateResolution {
+    gateId: string;
+    decision: 'approved' | 'rejected';
+    form?: Record<string, unknown>;
+    comment?: string;
+    executedResult?: Record<string, unknown>;
+}
+export interface PromptStrategy {
+    buildFirst(input: RunAgentInput): string;
+    buildResume?(args: Record<string, unknown>, executedResult?: Record<string, unknown>): ResumeOutcome;
+}
+export interface Provider {
+    run(input: RunAgentInput): AsyncIterable<BaseEvent>;
+    resume?(handle: ResumeHandle, resolution: GateResolution): AsyncIterable<BaseEvent>;
+}
+export interface ProviderConfig {
+    approvalNames: readonly string[];
+    surfaceTools: readonly string[];
+    allowedTools: readonly string[];
+    prompts: PromptStrategy;
+    instructions: string;
+    agentId: string;
+}
+export type ProviderFactory = (config: ProviderConfig) => Provider;
+export interface ProviderRegistry {
+    resolve(name: string): ProviderFactory;
+}
+export interface Lifecycle {
+    phase: Phase;
+    outcome: Outcome;
+    isLive: boolean;
+    isVisible: boolean;
+    covers: boolean;
+}
+/** Where a produced payload should be delivered. */
+export type Destination = {
+    kind: 'agent';
+    agentId: string;
+} | {
+    kind: 'contract';
+    workflow: string;
+    input: string;
+};
+export type DeliveryResult = {
+    ok: true;
+    instanceId: string;
+    targetWorkflow?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** The consequential side effect bound to an approved tool. Runs on the server only. */
+export type EffectFn = (form: Record<string, unknown>, ctx: {
+    workItemId: string;
+    gateId: string;
+}) => Promise<Record<string, unknown>>;
+export type WorkflowAgent = {
+    agent: AgentDefinition;
+    role: AgentRole;
+};
+export type WorkflowConnection = {
+    integration: string;
+    connection?: string;
+    provider: string;
+};
+export type WorkflowInput = {
+    name: string;
+    schema: z.ZodTypeAny;
+    agentId: string;
+};
+export type WorkflowDescriptor = {
+    id: string;
+    label: string;
+    iconName: string;
+    agents: WorkflowAgent[];
+    entryAgentId: string;
+    inputs: WorkflowInput[];
+    prompt?: string;
+    connections?: WorkflowConnection[];
+    rerun?: 'refresh' | 'history';
+    resetOnStart?: boolean;
+};
+export type ReadResult<T> = T | {
+    error: string;
+};
+export type BatchActionResult = {
+    done: string[];
+    failed: {
+        messageId: string;
+        error: string;
+    }[];
+} | {
+    error: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hanfani/core",
+  "version": "0.1.1",
+  "description": "Headless engine and types for the Hanfani agent framework.",
+  "license": "MIT",
+  "author": "Aziz Mashkour",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/azizmashkour/hanfani-packages.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "hanfani",
+    "agent",
+    "workflow",
+    "ai",
+    "human-in-the-loop"
+  ],
+  "dependencies": {
+    "@ag-ui/client": "^0.0.55",
+    "zod": "^3.25.76"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/conformance.ts

@@ -0,0 +1,118 @@
+import { EventType } from '@ag-ui/client'
+import type { BaseEvent, RunAgentInput } from '@ag-ui/client'
+import { readGateOpened, type GateOpenedValue } from './gate.js'
+import type { GateResolution, Provider, ResumeHandle } from './types.js'
+
+export interface ConformanceScenario {
+  approvalNames: readonly string[]
+  surfaceTools: readonly string[]
+  turn1Input: RunAgentInput
+  approved: { handle: ResumeHandle; resolution: GateResolution }
+  rejected: { handle: ResumeHandle; resolution: GateResolution }
+}
+
+export interface ConformanceCheck {
+  name: string
+  run(makeProvider: () => Provider, scenario: ConformanceScenario): Promise<void>
+}
+
+async function collect(events: AsyncIterable<BaseEvent>): Promise<BaseEvent[]> {
+  const out: BaseEvent[] = []
+  for await (const e of events) out.push(e)
+  return out
+}
+
+function gatesIn(events: readonly BaseEvent[]): GateOpenedValue[] {
+  const out: GateOpenedValue[] = []
+  for (const e of events) {
+    const gate = readGateOpened(e)
+    if (gate) out.push(gate)
+  }
+  return out
+}
+
+function assert(cond: unknown, message: string): asserts cond {
+  if (!cond) throw new Error(`conformance: ${message}`)
+}
+
+type WithToolCall = BaseEvent & { toolCallId?: string; toolCallName?: string }
+
+/**
+ * A provider-agnostic conformance suite: any Provider implementation can be run
+ * against these checks to prove it honours the framework's gate/effect contract.
+ */
+export const providerConformanceChecks: ConformanceCheck[] = [
+  {
+    name: 'turn 1 opens exactly one approval gate matching an approval tool',
+    async run(makeProvider, scenario) {
+      const events = await collect(makeProvider().run(scenario.turn1Input))
+      const gates = gatesIn(events)
+      assert(gates.length === 1, `expected 1 GATE_OPENED, got ${gates.length}`)
+      const gate = gates[0]!
+      assert(
+        scenario.approvalNames.includes(gate.toolName),
+        `gate toolName "${gate.toolName}" is not an approval`,
+      )
+      const startIds = events
+        .filter((e) => e.type === EventType.TOOL_CALL_START)
+        .map((e) => (e as WithToolCall).toolCallId)
+      assert(startIds.includes(gate.toolCallId), 'gate toolCallId has no matching TOOL_CALL_START')
+    },
+  },
+  {
+    name: 'resume(approved) completes and re-opens no gate',
+    async run(makeProvider, scenario) {
+      const provider = makeProvider()
+      assert(typeof provider.resume === 'function', 'provider does not implement resume()')
+      const events = await collect(provider.resume!(scenario.approved.handle, scenario.approved.resolution))
+      assert(gatesIn(events).length === 0, 'resume(approved) re-opened a gate')
+      assert(events.length > 0, 'resume(approved) produced no events')
+    },
+  },
+  {
+    name: 'resume(rejected) terminates and re-opens no gate',
+    async run(makeProvider, scenario) {
+      const provider = makeProvider()
+      assert(typeof provider.resume === 'function', 'provider does not implement resume()')
+      const events = await collect(provider.resume!(scenario.rejected.handle, scenario.rejected.resolution))
+      assert(gatesIn(events).length === 0, 'resume(rejected) re-opened a gate')
+      assert(events.length > 0, 'resume(rejected) produced no events')
+      assert(
+        events.filter((e) => e.type === EventType.TOOL_CALL_START).length === 0,
+        'resume(rejected) emitted a tool call (possible effect)',
+      )
+    },
+  },
+  {
+    name: 'only surfaced tools appear as tool calls on turn 1',
+    async run(makeProvider, scenario) {
+      const events = await collect(makeProvider().run(scenario.turn1Input))
+      const toolNames = events
+        .filter((e) => e.type === EventType.TOOL_CALL_START)
+        .map((e) => (e as WithToolCall).toolCallName)
+      for (const name of toolNames) {
+        assert(
+          name !== undefined && scenario.surfaceTools.includes(name),
+          `surfaced an undeclared tool: "${name}"`,
+        )
+      }
+    },
+  },
+  {
+    name: 'every TOOL_CALL_START on turn 1 has a matching TOOL_CALL_END with the same toolCallId',
+    async run(makeProvider, scenario) {
+      const events = await collect(makeProvider().run(scenario.turn1Input))
+      const startIds = events
+        .filter((e) => e.type === EventType.TOOL_CALL_START)
+        .map((e) => (e as WithToolCall).toolCallId)
+      const endIds = new Set(
+        events
+          .filter((e) => e.type === EventType.TOOL_CALL_END)
+          .map((e) => (e as WithToolCall).toolCallId),
+      )
+      for (const id of startIds) {
+        assert(endIds.has(id), `TOOL_CALL_START id "${id}" has no matching TOOL_CALL_END`)
+      }
+    },
+  },
+]

package/src/defineAgent.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod'
+
+/**
+ * The agent contract. `superRefine` enforces the framework's structural rules:
+ * approvals/renders/dispatches must be declared tools, and every effect must be
+ * an approval (so a side effect can never fire without a human gate).
+ */
+export const AgentDefinitionSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    provider: z.string(),
+    instructions: z.string(),
+    tools: z.array(z.string()),
+    approvals: z.array(z.string()),
+    renders: z.record(z.string()),
+    handoffs: z.array(z.string()).optional(),
+    maxInstances: z.number().int().positive().default(1),
+    effects: z.array(z.string()).default([]),
+    readonly: z.array(z.string()).default([]),
+    dispatches: z.array(z.string()).default([]),
+  })
+  .superRefine((def, ctx) => {
+    for (const approval of def.approvals) {
+      if (!def.tools.includes(approval)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `approval "${approval}" is not declared in tools`,
+        })
+      }
+    }
+    for (const renderKey of Object.keys(def.renders)) {
+      if (!def.tools.includes(renderKey)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `render key "${renderKey}" is not declared in tools`,
+        })
+      }
+    }
+    for (const effect of def.effects) {
+      if (!def.approvals.includes(effect)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `effect "${effect}" is not an approval`,
+        })
+      }
+    }
+    for (const dispatch of def.dispatches) {
+      if (!def.tools.includes(dispatch)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `dispatch "${dispatch}" is not declared in tools`,
+        })
+      }
+    }
+  })
+
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>
+export type AgentDefinitionInput = z.input<typeof AgentDefinitionSchema>
+
+export function defineAgent(def: AgentDefinitionInput): AgentDefinition {
+  return AgentDefinitionSchema.parse(def)
+}

package/src/definePrompt.ts

@@ -0,0 +1,33 @@
+import type { RunAgentInput } from '@ag-ui/client'
+import type { z } from 'zod'
+import { decodeHandoff } from './handoff.js'
+import type { PromptStrategy, ResumeOutcome } from './types.js'
+
+export interface PromptSpec<T> {
+  input?: z.ZodType<T>
+  onInput?: (payload: T) => string
+  onStart: () => string
+  onResume?: (result: Record<string, unknown>) => ResumeOutcome
+}
+
+/**
+ * Build a prompt strategy: on the first turn, decode any handoff payload and
+ * route it through `onInput`, else `onStart`; on resume, hand the executed
+ * result to `onResume`.
+ */
+export function definePrompt<T>(spec: PromptSpec<T>): PromptStrategy {
+  const { onResume } = spec
+  return {
+    buildFirst(input: RunAgentInput): string {
+      if (spec.input && spec.onInput) {
+        const payload = decodeHandoff(input, spec.input)
+        if (payload) return spec.onInput(payload)
+      }
+      return spec.onStart()
+    },
+    buildResume: onResume
+      ? (_args: Record<string, unknown>, executedResult?: Record<string, unknown>) =>
+          onResume(executedResult ?? {})
+      : undefined,
+  }
+}

package/src/defineWorkflow.ts

@@ -0,0 +1,52 @@
+import type { WorkflowDescriptor } from './types.js'
+
+/** Stable instance id for an agent within a workflow. */
+export function instanceId(workflowId: string, agentId: string): string {
+  return `${workflowId}__${agentId}`
+}
+
+/**
+ * Validate a workflow descriptor's internal consistency: unique agent ids, a
+ * role:input entry agent, handoffs that point inside the workflow, unique input
+ * names, and inputs bound to input-role agents. Returns the descriptor as-is.
+ */
+export function defineWorkflow(def: WorkflowDescriptor): WorkflowDescriptor {
+  const agentIds = def.agents.map((a) => a.agent.id)
+  const dupAgent = agentIds.find((id, i) => agentIds.indexOf(id) !== i)
+  if (dupAgent) throw new Error(`workflow "${def.id}": duplicate agent id "${dupAgent}"`)
+
+  const inputAgentIds = new Set(
+    def.agents.filter((a) => a.role === 'input').map((a) => a.agent.id),
+  )
+  const allAgentIds = new Set(agentIds)
+
+  if (!inputAgentIds.has(def.entryAgentId)) {
+    throw new Error(
+      `workflow "${def.id}": entry agent "${def.entryAgentId}" is not a role:input agent`,
+    )
+  }
+
+  for (const a of def.agents) {
+    for (const target of a.agent.handoffs ?? []) {
+      if (!allAgentIds.has(target)) {
+        throw new Error(
+          `workflow "${def.id}": agent "${a.agent.id}" hands off to "${target}" which is not in this workflow`,
+        )
+      }
+    }
+  }
+
+  const inputNames = def.inputs.map((i) => i.name)
+  const dupInput = inputNames.find((n, i) => inputNames.indexOf(n) !== i)
+  if (dupInput) throw new Error(`workflow "${def.id}": duplicate published input name "${dupInput}"`)
+
+  for (const input of def.inputs) {
+    if (!inputAgentIds.has(input.agentId)) {
+      throw new Error(
+        `workflow "${def.id}": input "${input.name}" is bound to "${input.agentId}" which is not a role:input agent`,
+      )
+    }
+  }
+
+  return def
+}

package/src/delivery.ts

@@ -0,0 +1,28 @@
+import { instanceId } from './defineWorkflow.js'
+import type { DeliveryResult, Destination, WorkflowDescriptor } from './types.js'
+
+/**
+ * Resolve where a payload should be delivered. Agent destinations resolve
+ * directly; contract destinations validate the payload against the target
+ * workflow's published input schema before resolving.
+ */
+export function resolveDelivery(
+  workflows: WorkflowDescriptor[],
+  origin: string,
+  dest: Destination,
+  payload: unknown,
+): DeliveryResult {
+  if (dest.kind === 'agent') {
+    return { ok: true, instanceId: instanceId(origin, dest.agentId) }
+  }
+
+  const workflow = workflows.find((w) => w.id === dest.workflow)
+  if (!workflow) return { ok: false, error: `unknown workflow "${dest.workflow}"` }
+
+  const input = workflow.inputs.find((i) => i.name === dest.input)
+  if (!input) return { ok: false, error: `workflow "${dest.workflow}" has no input "${dest.input}"` }
+
+  return input.schema.safeParse(payload).success
+    ? { ok: true, instanceId: instanceId(workflow.id, input.agentId), targetWorkflow: workflow.id }
+    : { ok: false, error: `payload does not match contract "${dest.workflow}.${dest.input}"` }
+}

package/src/fold.ts

@@ -0,0 +1,129 @@
+import { EventType } from '@ag-ui/client'
+import type { BaseEvent, Message } from '@ag-ui/client'
+import type { Outcome } from './types.js'
+import { LIFECYCLE_NOTE_TEXT } from './lifecycleNote.js'
+
+type FoldToolCall = {
+  id: string
+  type: 'function'
+  function: { name: string; arguments: string }
+}
+
+type FoldMessage = {
+  id: string
+  role: string
+  content?: string
+  toolCalls?: FoldToolCall[]
+  toolCallId?: string
+  targetAgentId?: string
+  childWorkItemId?: string
+  deduped?: boolean
+}
+
+type StreamEvent = BaseEvent & {
+  messageId?: string
+  delta?: string
+  toolCallId?: string
+  parentMessageId?: string
+  toolCallName?: string
+  content?: string
+  name?: string
+  value?: {
+    outcome?: Outcome
+    at?: number
+    targetAgentId?: string
+    childWorkItemId?: string
+    deduped?: boolean
+  }
+}
+
+/**
+ * Fold an ag-ui event stream into a flat list of messages: text chunks merge by
+ * messageId, tool calls attach to their parent assistant message, tool results
+ * become tool messages, and lifecycle/handoff custom events become notes.
+ */
+export function foldEventsToMessages(events: readonly BaseEvent[]): Message[] {
+  const messages = new Map<string, FoldMessage>()
+  const parentByToolCall = new Map<string, string>()
+
+  for (const raw of events) {
+    const e = raw as StreamEvent
+    switch (e.type) {
+      case EventType.TEXT_MESSAGE_CHUNK: {
+        const id = e.messageId
+        if (!id) break
+        const existing = messages.get(id)
+        if (existing && existing.role === 'assistant') {
+          existing.content = (existing.content ?? '') + (e.delta ?? '')
+        } else {
+          messages.set(id, { id, role: 'assistant', content: e.delta ?? '' })
+        }
+        break
+      }
+      case EventType.TOOL_CALL_START: {
+        const id = e.toolCallId
+        if (!id) break
+        const parentId = e.parentMessageId ?? `tc-${id}`
+        let parent = messages.get(parentId)
+        if (!parent || parent.role !== 'assistant') {
+          parent = { id: parentId, role: 'assistant', content: '', toolCalls: [] }
+          messages.set(parentId, parent)
+        }
+        parent.toolCalls ||= []
+        parent.toolCalls.push({
+          id,
+          type: 'function',
+          function: { name: e.toolCallName ?? '', arguments: '' },
+        })
+        parentByToolCall.set(id, parentId)
+        break
+      }
+      case EventType.TOOL_CALL_ARGS: {
+        const id = e.toolCallId
+        if (!id) break
+        const parentId = parentByToolCall.get(id)
+        if (!parentId) break
+        const call = messages.get(parentId)?.toolCalls?.find((c) => c.id === id)
+        if (call) call.function.arguments += e.delta ?? ''
+        break
+      }
+      case EventType.TOOL_CALL_END:
+        break
+      case EventType.TOOL_CALL_RESULT: {
+        const id = e.toolCallId
+        const msgId = e.messageId ?? (id ? `result-${id}` : undefined)
+        if (!msgId || !id) break
+        messages.set(msgId, { id: msgId, role: 'tool', toolCallId: id, content: e.content ?? '' })
+        break
+      }
+      case EventType.CUSTOM: {
+        if (e.name === 'lifecycle') {
+          const v = e.value
+          if (v && v.outcome !== undefined) {
+            const text = LIFECYCLE_NOTE_TEXT[v.outcome] || v.outcome
+            const id = `lifecycle-${v.at}`
+            messages.set(id, { id, role: 'system', content: text })
+          }
+          break
+        }
+        if (e.name === 'handoff' && e.value) {
+          const v = e.value
+          const id = `handoff-${v.childWorkItemId}`
+          messages.set(id, {
+            id,
+            role: 'handoff',
+            targetAgentId: v.targetAgentId,
+            childWorkItemId: v.childWorkItemId,
+            deduped: v.deduped,
+          })
+          break
+        }
+        break
+      }
+      default:
+        break
+    }
+  }
+
+  return [...messages.values()] as unknown as Message[]
+}

package/src/gate.ts

@@ -0,0 +1,26 @@
+import { EventType } from '@ag-ui/client'
+import type { BaseEvent, CustomEvent as AguiCustomEvent } from '@ag-ui/client'
+import { z } from 'zod'
+
+export const GATE_OPENED = 'GATE_OPENED' as const
+
+export const GateOpenedValueSchema = z.object({
+  gateKind: z.literal('approval'),
+  toolName: z.string(),
+  toolCallId: z.string(),
+  proposedArtifact: z.record(z.unknown()),
+})
+export type GateOpenedValue = z.infer<typeof GateOpenedValueSchema>
+
+/** Emit the custom event that opens a human-approval gate. */
+export function gateOpened(value: GateOpenedValue): AguiCustomEvent {
+  return { type: EventType.CUSTOM, name: GATE_OPENED, value } as AguiCustomEvent
+}
+
+/** Read a GATE_OPENED value off an event, or null if it isn't one. */
+export function readGateOpened(event: BaseEvent): GateOpenedValue | null {
+  const e = event as AguiCustomEvent
+  if (e.type !== EventType.CUSTOM || e.name !== GATE_OPENED) return null
+  const parsed = GateOpenedValueSchema.safeParse(e.value)
+  return parsed.success ? parsed.data : null
+}