@hanfani/core 0.1.1

package/src/handoff.ts

@@ -0,0 +1,58 @@
+import { z } from 'zod'
+import type { Message, RunAgentInput } from '@ag-ui/client'
+
+export const HandoffPayloadSchema = z.object({
+  threadId: z.string(),
+  from: z.string(),
+  subject: z.string(),
+  summary: z.string(),
+  category: z.string(),
+  priority: z.string(),
+})
+export type HandoffPayload = z.infer<typeof HandoffPayloadSchema>
+
+export const TicketHandoffPayloadSchema = z.object({
+  repo: z.string(),
+  number: z.number(),
+  title: z.string(),
+  status: z.string(),
+  priority: z.string(),
+  body: z.string(),
+  lastComment: z
+    .object({
+      author: z.string(),
+      body: z.string(),
+    })
+    .nullable(),
+  recommendation: z.string(),
+  url: z.string(),
+})
+export type TicketHandoffPayload = z.infer<typeof TicketHandoffPayloadSchema>
+
+const HANDOFF_PREFIX = '[handoff]'
+
+/** Encode a payload as a user message that downstream agents can decode. */
+export function encodeHandoff(payload: unknown): Message {
+  return {
+    id: crypto.randomUUID(),
+    role: 'user',
+    content: `${HANDOFF_PREFIX} ${JSON.stringify(payload)}`,
+  }
+}
+
+/** Decode the most recent handoff payload in the run input, validated by `schema`. */
+export function decodeHandoff<T>(input: RunAgentInput, schema: z.ZodType<T>): T | null {
+  const messages = input?.messages ?? []
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]
+    if (m && m.role === 'user' && typeof m.content === 'string' && m.content.startsWith(HANDOFF_PREFIX)) {
+      try {
+        const parsed = schema.safeParse(JSON.parse(m.content.slice(HANDOFF_PREFIX.length).trim()))
+        return parsed.success ? parsed.data : null
+      } catch {
+        return null
+      }
+    }
+  }
+  return null
+}

package/src/handoffNote.ts

@@ -0,0 +1,15 @@
+import { EventType } from '@ag-ui/client'
+import type { BaseEvent } from '@ag-ui/client'
+
+export interface HandoffNoteValue {
+  kind: 'handoff'
+  targetAgentId: string
+  childWorkItemId: string
+  deduped: boolean
+  at: number
+}
+
+/** Emit a handoff note event. */
+export function handoffNote(value: HandoffNoteValue): BaseEvent {
+  return { type: EventType.CUSTOM, name: 'handoff', value } as unknown as BaseEvent
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+// @hanfani/core — headless engine and types for the Hanfani agent framework.
+//
+// The one invariant this package encodes: an agent proposes, a human approves,
+// the server acts. `defineAgent` refuses any effect that isn't gated behind an
+// approval; the conformance suite proves providers honour that at runtime.
+
+// Re-export the two @ag-ui/client types that appear in the public API.
+export type { Message, ToolCall } from '@ag-ui/client'
+
+export {
+  AgentDefinitionSchema,
+  defineAgent,
+  type AgentDefinition,
+  type AgentDefinitionInput,
+} from './defineAgent.js'
+
+export { defineWorkflow, instanceId } from './defineWorkflow.js'
+
+export { definePrompt, type PromptSpec } from './definePrompt.js'
+
+export { defineProviders } from './providers.js'
+
+export { composeInstructions } from './prompt.js'
+
+export {
+  approvalResolved,
+  hasPendingApproval,
+  isAssistant,
+  isToolMessage,
+  lastApprovalArgs,
+  pairToolResults,
+  resolvedApprovalCount,
+  toolCallsOf,
+  type AssistantMessage,
+  type ToolMessage,
+} from './messages.js'
+
+export {
+  decodeHandoff,
+  encodeHandoff,
+  HandoffPayloadSchema,
+  TicketHandoffPayloadSchema,
+  type HandoffPayload,
+  type TicketHandoffPayload,
+} from './handoff.js'
+
+export { handoffNote, type HandoffNoteValue } from './handoffNote.js'
+
+export {
+  GATE_OPENED,
+  gateOpened,
+  GateOpenedValueSchema,
+  readGateOpened,
+  type GateOpenedValue,
+} from './gate.js'
+
+export { LIFECYCLE_NOTE_TEXT, lifecycleNote, type LifecycleNoteValue } from './lifecycleNote.js'
+
+export { hasLiveDescendant, lifecycle } from './lifecycle.js'
+
+export { foldEventsToMessages } from './fold.js'
+
+export { resolveDelivery } from './delivery.js'
+
+export {
+  providerConformanceChecks,
+  type ConformanceCheck,
+  type ConformanceScenario,
+} from './conformance.js'
+
+export { aggregateHealth, isOk } from './integration.js'
+
+export { isOAuth2 } from './integrationAuth.js'
+
+export type {
+  AgentRole,
+  AuthSpec,
+  BatchActionResult,
+  CredentialResolver,
+  DeliveryResult,
+  Destination,
+  EffectFn,
+  GateResolution,
+  HealthCheck,
+  Lifecycle,
+  Outcome,
+  Phase,
+  PromptStrategy,
+  Provider,
+  ProviderConfig,
+  ProviderFactory,
+  ProviderRegistry,
+  ReadResult,
+  ResolvedCredential,
+  ResumeHandle,
+  ResumeOutcome,
+  WorkflowAgent,
+  WorkflowConnection,
+  WorkflowDescriptor,
+  WorkflowInput,
+} from './types.js'

package/src/integration.ts

@@ -0,0 +1,14 @@
+import type { HealthCheck } from './types.js'
+
+/** Narrow a HealthCheck to its ok variant. */
+export function isOk(h: HealthCheck): h is { ok: true; detail?: string } {
+  return h.ok
+}
+
+/** Return the first failing check, or an ok result if all pass. */
+export function aggregateHealth(checks: HealthCheck[]): HealthCheck {
+  for (const check of checks) {
+    if (!check.ok) return check
+  }
+  return { ok: true }
+}

package/src/integrationAuth.ts

@@ -0,0 +1,8 @@
+import type { AuthSpec } from './types.js'
+
+/** Narrow an AuthSpec to its oauth2 variant. */
+export function isOAuth2(
+  auth: AuthSpec,
+): auth is { kind: 'oauth2'; provider: string; scopes: string[] } {
+  return auth.kind === 'oauth2'
+}

package/src/lifecycle.ts

@@ -0,0 +1,61 @@
+import type { Lifecycle, Outcome, Phase } from './types.js'
+
+const LIVE_PHASES = new Set<Phase>(['queued', 'active', 'awaiting_human'])
+const SILENT_OUTCOMES = new Set<Outcome>(['superseded', 'reset', 'dismissed'])
+const FAILED_OUTCOMES = new Set<Outcome>(['stopped', 'rejected', 'error'])
+const COVERING_OUTCOMES = new Set<Outcome>(['done', 'stopped', 'rejected'])
+
+/**
+ * Derive display lifecycle from a work item's phase/outcome plus whether it has
+ * a render card and whether it has a live descendant.
+ */
+export function lifecycle(
+  phase: Phase,
+  outcome: Outcome,
+  hasCard: boolean,
+  hasLiveDescendant: boolean,
+): Lifecycle {
+  const isLive = LIVE_PHASES.has(phase)
+  let isVisible: boolean
+  if (phase === 'queued') isVisible = false
+  else if (isLive) isVisible = true
+  else if (SILENT_OUTCOMES.has(outcome)) isVisible = false
+  else isVisible = hasCard || FAILED_OUTCOMES.has(outcome) || hasLiveDescendant
+  const covers = isLive || COVERING_OUTCOMES.has(outcome)
+  return { phase, outcome, isLive, isVisible, covers }
+}
+
+/**
+ * Given flat parent/child rows, return the set of ids that have at least one
+ * live descendant (a queued/active/awaiting_human node somewhere below them).
+ */
+export function hasLiveDescendant<T extends { id: string; parentId: string | null; phase: Phase }>(
+  rows: readonly T[],
+): Set<string> {
+  const childrenByParent = new Map<string, T[]>()
+  for (const row of rows) {
+    if (!row.parentId) continue
+    const siblings = childrenByParent.get(row.parentId) ?? []
+    siblings.push(row)
+    childrenByParent.set(row.parentId, siblings)
+  }
+
+  const memo = new Map<string, boolean>()
+  const visit = (id: string): boolean => {
+    const cached = memo.get(id)
+    if (cached !== undefined) return cached
+    memo.set(id, false) // guard against cycles
+    let live = false
+    for (const child of childrenByParent.get(id) ?? []) {
+      if (LIVE_PHASES.has(child.phase) || visit(child.id)) live = true
+    }
+    memo.set(id, live)
+    return live
+  }
+
+  const result = new Set<string>()
+  for (const row of rows) {
+    if (visit(row.id)) result.add(row.id)
+  }
+  return result
+}

package/src/lifecycleNote.ts

@@ -0,0 +1,27 @@
+import { EventType } from '@ag-ui/client'
+import type { BaseEvent } from '@ag-ui/client'
+import type { Outcome } from './types.js'
+
+export interface LifecycleNoteValue {
+  kind: 'lifecycle'
+  outcome: Outcome
+  actor: string | null
+  at: number
+}
+
+/** Emit a lifecycle note event. */
+export function lifecycleNote(value: LifecycleNoteValue): BaseEvent {
+  return { type: EventType.CUSTOM, name: 'lifecycle', value } as unknown as BaseEvent
+}
+
+/** Human-readable label shown for each terminal outcome. */
+export const LIFECYCLE_NOTE_TEXT: Record<Outcome, string> = {
+  running: '',
+  done: 'Done',
+  stopped: 'Stopped — cancelled',
+  rejected: 'Rejected',
+  error: 'Error',
+  superseded: 'Superseded by a re-run',
+  reset: 'Cleared from board',
+  dismissed: 'Error acknowledged — dismissed',
+}

package/src/messages.ts

@@ -0,0 +1,99 @@
+import type { Message, ToolCall } from '@ag-ui/client'
+
+export type AssistantMessage = Extract<Message, { role: 'assistant' }>
+export type ToolMessage = Extract<Message, { role: 'tool' }>
+
+export function isAssistant(m: Message): m is AssistantMessage {
+  return m.role === 'assistant'
+}
+
+export function isToolMessage(m: Message): m is ToolMessage {
+  return m.role === 'tool'
+}
+
+export function toolCallsOf(m: Message): ToolCall[] {
+  return isAssistant(m) && Array.isArray(m.toolCalls) ? m.toolCalls : []
+}
+
+/** True when an approval tool has been called but has no tool result yet. */
+export function hasPendingApproval(
+  messages: readonly Message[],
+  approvalNames: readonly string[],
+): boolean {
+  const resolvedIds = new Set<string>()
+  for (const m of messages) {
+    if (isToolMessage(m) && typeof m.toolCallId === 'string') resolvedIds.add(m.toolCallId)
+  }
+  for (const m of messages) {
+    for (const call of toolCallsOf(m)) {
+      if (
+        approvalNames.includes(call.function.name) &&
+        typeof call.id === 'string' &&
+        !resolvedIds.has(call.id)
+      ) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+/** Map each tool result message by the toolCallId it answers. */
+export function pairToolResults(messages: readonly Message[]): Map<string, ToolMessage> {
+  const byCallId = new Map<string, ToolMessage>()
+  for (const m of messages) {
+    if (isToolMessage(m) && typeof m.toolCallId === 'string') byCallId.set(m.toolCallId, m)
+  }
+  return byCallId
+}
+
+/** Parsed arguments of the most recent approval tool call, or null. */
+export function lastApprovalArgs(
+  messages: readonly Message[],
+  approvalNames: readonly string[],
+): Record<string, unknown> | null {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i]
+    if (!m) continue
+    for (const call of toolCallsOf(m)) {
+      if (approvalNames.includes(call.function.name)) {
+        try {
+          return JSON.parse(call.function.arguments)
+        } catch {
+          return null
+        }
+      }
+    }
+  }
+  return null
+}
+
+/** How many approval tool calls have a matching tool result. */
+export function resolvedApprovalCount(
+  messages: readonly Message[],
+  approvalNames: readonly string[],
+): number {
+  const approvalCallIds = new Set<string>()
+  for (const m of messages) {
+    for (const call of toolCallsOf(m)) {
+      if (approvalNames.includes(call.function.name) && typeof call.id === 'string') {
+        approvalCallIds.add(call.id)
+      }
+    }
+  }
+  const resolved = new Set<string>()
+  for (const m of messages) {
+    if (isToolMessage(m) && typeof m.toolCallId === 'string' && approvalCallIds.has(m.toolCallId)) {
+      resolved.add(m.toolCallId)
+    }
+  }
+  return resolved.size
+}
+
+/** True when at least one approval call has resolved. */
+export function approvalResolved(
+  messages: readonly Message[],
+  approvalNames: readonly string[],
+): boolean {
+  return resolvedApprovalCount(messages, approvalNames) > 0
+}

package/src/prompt.ts

@@ -0,0 +1,8 @@
+/** Prepend the workflow-level prompt (if any) to an agent's own instructions. */
+export function composeInstructions(
+  workflowPrompt: string | undefined,
+  agentInstructions: string,
+): string {
+  const prefix = workflowPrompt?.trim()
+  return prefix ? `${prefix}\n\n${agentInstructions}` : agentInstructions
+}

package/src/providers.ts

@@ -0,0 +1,12 @@
+import type { ProviderFactory, ProviderRegistry } from './types.js'
+
+/** Build a registry that resolves provider factories by name. */
+export function defineProviders(map: Record<string, ProviderFactory>): ProviderRegistry {
+  return {
+    resolve(name: string): ProviderFactory {
+      const factory = map[name]
+      if (!factory) throw new Error(`Unknown provider: ${name}`)
+      return factory
+    },
+  }
+}

package/src/types.ts

@@ -0,0 +1,151 @@
+import type { BaseEvent, Message, RunAgentInput, ToolCall } from '@ag-ui/client'
+import type { z } from 'zod'
+import type { AgentDefinition } from './defineAgent.js'
+
+// Re-export the two @ag-ui/client types that appear in this package's public API,
+// so consumers can import them from @hanfani/core directly.
+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 }