@lucianfialho/hooklaw-core

@lucianfialho/hooklaw-core

Core engine for HookLaw — event-driven AI agents with native MCP tools.

What's inside

• Config loader — YAML config with ${ENV_VAR} substitution and Zod validation
• HTTP server — webhook receiver (POST /h/:slug), REST API, and dashboard hosting
• Router — recipe matcher with conditional routing via lightweight LLM evaluation
• Agent — agentic tool loop (max 10 iterations) with observability traces
• MCP Pool — persistent MCP client connections (stdio + SSE transports)
• SQLite DB — executions, traces, agent memory, approvals (WAL mode)
• Feed poller — RSS/Atom/JSON feed watcher with content-hash deduplication
• Queue — per-recipe async queue with concurrency control
• Provider registry — pluggable LLM providers (OpenAI, Anthropic, Ollama, OpenRouter)

Key Features

• Multi-agent chains — recipes trigger other recipes on success/error with depth tracking
• Human-in-the-loop — executions pause at pending_approval status for review
• Agent memory — conversation context persists across executions per recipe
• Conditional routing — LLM evaluates conditions to decide which recipe handles an event
• Agent observability — traces capture every LLM call, tool call, tool result, and error

Install

npm install @lucianfialho/hooklaw-core

Usage

import { bootstrap } from '@lucianfialho/hooklaw-core';

const { server, config } = await bootstrap({
  configPath: './hooklaw.config.yaml',
  dashboardDir: './dashboard/dist',
});

API Endpoints

Method	Path	Description
POST	/h/:slug	Receive webhook
GET	/api/recipes	List recipes
GET	/api/executions	List executions (filterable)
GET	/api/executions/:id/traces	Agent reasoning traces
GET	/api/executions/:id/chain	Child executions in a chain
GET	/api/recipes/:id/memory	Agent memory for a recipe
DELETE	/api/recipes/:id/memory	Clear agent memory
GET	/api/approvals	Pending approval queue
POST	/api/executions/:id/approve	Approve/reject execution
GET	/api/mcp-servers	List MCP servers
GET	/api/mcp-servers/health	Health check all MCP servers
GET	/api/stats	Execution statistics
GET	/api/feeds	Active feed pollers
GET	/api/config	Redacted config

Architecture

hooklaw.config.yaml
        |
        v
┌──────────────┐     ┌──────────┐     ┌───────────┐     ┌──────────┐
│  HTTP Server │────>│  Router  │────>│   Agent   │────>│ MCP Pool │
│  /h/:slug    │     │  Routing │     │  Tool Loop│     │  stdio   │
│  /api/*      │     │  Chains  │     │  Traces   │     │  sse     │
│  /dashboard  │     │  Memory  │     │  Memory   │     │          │
└──────────────┘     └──────────┘     └───────────┘     └──────────┘
        ^                  |                                   |
        |                  v                                   v
┌──────────────┐     ┌──────────┐                        ┌──────────┐
│  RSS/Atom    │     │  SQLite  │                        │ External │
│  Feed Poller │     │  (WAL)   │                        │ MCP Svrs │
└──────────────┘     └──────────┘                        └──────────┘

License

MIT