@hazeljs/agent 0.2.0-beta.1

package/README.md

@@ -0,0 +1,427 @@
+# @hazeljs/agent
+
+**AI-native Agent Runtime for HazelJS** - Build stateful, long-running agents with tools, memory, and human-in-the-loop workflows.
+
+## Overview
+
+The Agent Runtime is a core primitive in HazelJS designed for building production-grade AI agents. Unlike stateless request handlers, agents are:
+
+- **Stateful** - Maintain context across multiple steps
+- **Long-running** - Execute complex workflows over time
+- **Tool-using** - Call functions safely with approval workflows
+- **Memory-enabled** - Integrate with persistent memory systems
+- **Observable** - Full event system for monitoring and debugging
+- **Resumable** - Support pause/resume and human-in-the-loop
+
+## Installation
+
+```bash
+npm install @hazeljs/agent @hazeljs/core @hazeljs/rag
+```
+
+## Quick Start
+
+### 1. Define an Agent
+
+```typescript
+import { Agent, Tool } from '@hazeljs/agent';
+
+@Agent({
+  name: 'support-agent',
+  description: 'Customer support agent',
+  systemPrompt: 'You are a helpful customer support agent.',
+  enableMemory: true,
+  enableRAG: true,
+})
+export class SupportAgent {
+  @Tool({
+    description: 'Look up order information by order ID',
+    parameters: [
+      {
+        name: 'orderId',
+        type: 'string',
+        description: 'The order ID to lookup',
+        required: true,
+      },
+    ],
+  })
+  async lookupOrder(input: { orderId: string }) {
+    // Your implementation
+    return {
+      orderId: input.orderId,
+      status: 'shipped',
+      trackingNumber: 'TRACK123',
+    };
+  }
+
+  @Tool({
+    description: 'Process a refund for an order',
+    requiresApproval: true, // Requires human approval
+    parameters: [
+      {
+        name: 'orderId',
+        type: 'string',
+        description: 'The order ID to refund',
+        required: true,
+      },
+      {
+        name: 'amount',
+        type: 'number',
+        description: 'Refund amount',
+        required: true,
+      },
+    ],
+  })
+  async processRefund(input: { orderId: string; amount: number }) {
+    // Your implementation
+    return {
+      success: true,
+      refundId: 'REF123',
+      amount: input.amount,
+    };
+  }
+}
+```
+
+### 2. Set Up the Runtime
+
+```typescript
+import { AgentRuntime } from '@hazeljs/agent';
+import { MemoryManager } from '@hazeljs/rag';
+import { AIService } from '@hazeljs/ai';
+
+// Initialize dependencies
+const memoryManager = new MemoryManager(/* ... */);
+const aiService = new AIService({ provider: 'openai' });
+
+// Create runtime
+const runtime = new AgentRuntime({
+  memoryManager,
+  llmProvider: aiService,
+  defaultMaxSteps: 10,
+  enableObservability: true,
+});
+
+// Register agent
+const supportAgent = new SupportAgent();
+runtime.registerAgent(SupportAgent);
+runtime.registerAgentInstance('support-agent', supportAgent);
+```
+
+### 3. Execute the Agent
+
+```typescript
+// Execute agent
+const result = await runtime.execute(
+  'support-agent',
+  'I need to check my order status for order #12345',
+  {
+    sessionId: 'user-session-123',
+    userId: 'user-456',
+    enableMemory: true,
+    enableRAG: true,
+  }
+);
+
+console.log(result.response);
+console.log(`Completed in ${result.steps.length} steps`);
+```
+
+### 4. Handle Human-in-the-Loop
+
+```typescript
+// Subscribe to approval requests
+runtime.on('tool.approval.requested', async (event) => {
+  console.log('Approval needed:', event.data);
+  
+  // Approve or reject
+  runtime.approveToolExecution(event.data.requestId, 'admin-user');
+  // or
+  // runtime.rejectToolExecution(event.data.requestId);
+});
+
+// Resume after approval
+const resumedResult = await runtime.resume(result.executionId);
+```
+
+## Core Concepts
+
+### Agent State Machine
+
+Every agent execution follows a deterministic state machine:
+
+```
+idle → thinking → using_tool → thinking → ... → completed
+                    ↓
+              waiting_for_input
+                    ↓
+              waiting_for_approval
+                    ↓
+                 failed
+```
+
+### Execution Loop
+
+The agent runtime implements a controlled execution loop:
+
+1. **Load State** - Restore agent context and memory
+2. **Load Memory** - Retrieve conversation history
+3. **Retrieve RAG** - Get relevant context (optional)
+4. **Ask LLM** - Decide next action
+5. **Execute Action** - Call tool, ask user, or respond
+6. **Persist State** - Save state and memory
+7. **Repeat or Finish** - Continue or complete
+
+### Tools
+
+Tools are explicit, auditable capabilities:
+
+```typescript
+@Tool({
+  description: 'Send an email',
+  requiresApproval: true,
+  timeout: 30000,
+  retries: 2,
+  parameters: [
+    { name: 'to', type: 'string', required: true },
+    { name: 'subject', type: 'string', required: true },
+    { name: 'body', type: 'string', required: true },
+  ],
+})
+async sendEmail(input: { to: string; subject: string; body: string }) {
+  // Implementation
+}
+```
+
+**Tool Features:**
+- Automatic parameter validation
+- Timeout and retry logic
+- Approval workflows
+- Execution logging
+- Error handling
+
+### Memory Integration
+
+Agents automatically integrate with HazelJS Memory:
+
+```typescript
+// Memory is automatically persisted
+const result = await runtime.execute('agent-name', 'Hello', {
+  sessionId: 'session-123',
+  enableMemory: true,
+});
+
+// Conversation history is maintained
+const result2 = await runtime.execute('agent-name', 'What did I just say?', {
+  sessionId: 'session-123', // Same session
+  enableMemory: true,
+});
+```
+
+### RAG Integration
+
+Agents can query RAG before reasoning:
+
+```typescript
+@Agent({
+  name: 'docs-agent',
+  enableRAG: true,
+  ragTopK: 5,
+})
+export class DocsAgent {
+  // Agent automatically retrieves relevant docs
+}
+```
+
+## Event System
+
+Subscribe to agent events for observability:
+
+```typescript
+import { AgentEventType } from '@hazeljs/agent';
+
+// Execution events
+runtime.on(AgentEventType.EXECUTION_STARTED, (event) => {
+  console.log('Agent started:', event.data);
+});
+
+runtime.on(AgentEventType.EXECUTION_COMPLETED, (event) => {
+  console.log('Agent completed:', event.data);
+});
+
+// Step events
+runtime.on(AgentEventType.STEP_STARTED, (event) => {
+  console.log('Step started:', event.data);
+});
+
+// Tool events
+runtime.on(AgentEventType.TOOL_EXECUTION_STARTED, (event) => {
+  console.log('Tool executing:', event.data);
+});
+
+runtime.on(AgentEventType.TOOL_APPROVAL_REQUESTED, (event) => {
+  console.log('Approval needed:', event.data);
+});
+
+// Subscribe to all events
+runtime.onAny((event) => {
+  console.log('Event:', event.type, event.data);
+});
+```
+
+## HazelJS Module Integration
+
+Use with HazelJS modules:
+
+```typescript
+import { HazelModule } from '@hazeljs/core';
+import { AgentModule } from '@hazeljs/agent';
+import { RagModule } from '@hazeljs/rag';
+
+@HazelModule({
+  imports: [
+    RagModule.forRoot({ /* ... */ }),
+    AgentModule.forRoot({
+      runtime: {
+        defaultMaxSteps: 10,
+        enableObservability: true,
+      },
+      agents: [SupportAgent, SalesAgent],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Advanced Usage
+
+### Pause and Resume
+
+```typescript
+// Execute agent
+const result = await runtime.execute('agent', 'Start task');
+
+if (result.state === 'waiting_for_input') {
+  // Agent is waiting for user input
+  const resumed = await runtime.resume(result.executionId, 'User response');
+}
+```
+
+### Custom Context
+
+```typescript
+const result = await runtime.execute('agent', 'Process order', {
+  initialContext: {
+    userId: '123',
+    orderData: { /* ... */ },
+  },
+});
+```
+
+### Tool Policies
+
+```typescript
+@Tool({
+  description: 'Delete user data',
+  requiresApproval: true,
+  policy: 'admin-only', // Custom policy
+})
+async deleteUserData(input: { userId: string }) {
+  // Implementation
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              Agent Runtime                       │
+├─────────────────────────────────────────────────┤
+│  ┌──────────────┐  ┌──────────────┐            │
+│  │   Registry   │  │  State Mgr   │            │
+│  └──────────────┘  └──────────────┘            │
+│  ┌──────────────┐  ┌──────────────┐            │
+│  │   Executor   │  │ Tool Executor│            │
+│  └──────────────┘  └──────────────┘            │
+│  ┌──────────────┐  ┌──────────────┐            │
+│  │    Events    │  │   Context    │            │
+│  └──────────────┘  └──────────────┘            │
+├─────────────────────────────────────────────────┤
+│         Memory Module    │    RAG Module        │
+└─────────────────────────────────────────────────┘
+```
+
+## Best Practices
+
+### 1. Keep Agents Declarative
+
+```typescript
+// ✅ Good - Declarative
+@Agent({ name: 'support-agent' })
+export class SupportAgent {
+  @Tool()
+  async lookupOrder(input: { orderId: string }) {
+    return this.orderService.find(input.orderId);
+  }
+}
+
+// ❌ Bad - Business logic in decorator
+@Agent({ 
+  name: 'support-agent',
+  onExecute: async () => { /* complex logic */ }
+})
+```
+
+### 2. Use Approval for Destructive Actions
+
+```typescript
+@Tool({ requiresApproval: true })
+async deleteAccount(input: { userId: string }) {
+  // Destructive action
+}
+```
+
+### 3. Design Idempotent Tools
+
+```typescript
+@Tool()
+async createOrder(input: { orderId: string; items: any[] }) {
+  // Check if order exists first
+  const existing = await this.findOrder(input.orderId);
+  if (existing) return existing;
+  
+  return this.createNewOrder(input);
+}
+```
+
+### 4. Handle Errors Gracefully
+
+```typescript
+@Tool()
+async externalAPICall(input: any) {
+  try {
+    return await this.api.call(input);
+  } catch (error) {
+    // Return structured error
+    return {
+      success: false,
+      error: error.message,
+    };
+  }
+}
+```
+
+## API Reference
+
+See [API Documentation](./docs/api.md) for complete API reference.
+
+## Examples
+
+- [Customer Support Agent](./examples/support-agent.ts)
+- [Sales Agent with Approval](./examples/sales-agent.ts)
+- [Multi-Agent System](./examples/multi-agent.ts)
+- [RAG-Powered Agent](./examples/rag-agent.ts)
+
+## License
+
+MIT

package/STATE_VS_MEMORY.md

@@ -0,0 +1,243 @@
+# Agent State vs Memory: Understanding the Difference
+
+There are **two separate persistence layers** in the agent system that serve different purposes:
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Agent Execution                      │
+└─────────────────────────────────────────────────────────┘
+           │                          │
+           ▼                          ▼
+┌──────────────────────┐  ┌──────────────────────────────┐
+│  Agent State         │  │  Memory (RAG)                │
+│  Persistence         │  │  Persistence                  │
+│                      │  │                              │
+│  - Execution flow    │  │  - Conversation history      │
+│  - Steps             │  │  - Entities                  │
+│  - State transitions │  │  - Facts                     │
+│  - Execution context │  │  - Working memory            │
+│  - Metadata          │  │  - Long-term knowledge        │
+└──────────────────────┘  └──────────────────────────────┘
+```
+
+## Agent State Persistence
+
+**Purpose**: Track the **execution flow** and **state machine** of agent runs
+
+**What it stores**:
+- ✅ Execution ID and context
+- ✅ Current state (IDLE, THINKING, WAITING_FOR_APPROVAL, etc.)
+- ✅ Execution steps (what the agent did)
+- ✅ Step results and errors
+- ✅ Execution metadata
+- ✅ **Temporary** conversation history (during execution)
+
+**Lifetime**: 
+- **Short-lived** - typically minutes to hours
+- Ephemeral - deleted after execution completes (or TTL expires)
+
+**Use cases**:
+- Resume paused executions
+- Track execution progress
+- Debug failed executions
+- Monitor active agent runs
+- State machine transitions
+
+**Backends**:
+- In-Memory (default)
+- Redis (production)
+- Database/Prisma (audit)
+
+**Example**:
+```typescript
+// Agent State tracks: "Agent executed step 1, 2, 3, now waiting for approval"
+{
+  executionId: "abc-123",
+  state: "WAITING_FOR_APPROVAL",
+  steps: [
+    { stepNumber: 1, action: "think", result: {...} },
+    { stepNumber: 2, action: "use_tool", result: {...} },
+    { stepNumber: 3, action: "ask_user", result: {...} }
+  ]
+}
+```
+
+## Memory Persistence (RAG MemoryManager)
+
+**Purpose**: Store **long-term knowledge** and **context** across sessions
+
+**What it stores**:
+- ✅ Conversation history (across all sessions)
+- ✅ Entities (people, places, things mentioned)
+- ✅ Facts (learned information)
+- ✅ Working memory (user preferences, session state)
+- ✅ Events (important occurrences)
+
+**Lifetime**:
+- **Long-lived** - days, weeks, months
+- Persistent - survives agent restarts
+- Cross-session - shared across multiple agent runs
+
+**Use cases**:
+- Build context for new conversations
+- Remember entities across sessions
+- Store learned facts
+- Maintain user preferences
+- Semantic search of past conversations
+
+**Backends**:
+- BufferMemory (in-memory)
+- VectorMemory (Pinecone, Weaviate, Qdrant, ChromaDB)
+- HybridMemory (combination)
+
+**Example**:
+```typescript
+// Memory stores: "User's name is John, likes coffee, mentioned Paris last week"
+{
+  entities: [
+    { name: "John", type: "person", attributes: {...} },
+    { name: "Paris", type: "location", attributes: {...} }
+  ],
+  facts: ["User prefers coffee over tea"],
+  workingMemory: { "user_preferences": { "drink": "coffee" } }
+}
+```
+
+## Key Differences
+
+| Aspect | Agent State | Memory (RAG) |
+|--------|-------------|--------------|
+| **Purpose** | Execution flow tracking | Long-term knowledge |
+| **Lifetime** | Minutes to hours | Days to months |
+| **Scope** | Single execution | Cross-session |
+| **Data** | Steps, state, metadata | Conversations, entities, facts |
+| **Query** | By executionId | Semantic search, by sessionId |
+| **Backend** | Redis/DB | Vector stores (Pinecone, etc.) |
+| **When used** | During execution | Before/after execution |
+
+## How They Work Together
+
+```typescript
+// 1. Agent starts execution
+const context = stateManager.createContext(...);
+
+// 2. Load memory (conversation history, entities) into context
+await contextBuilder.buildWithMemory(context);
+// ↑ This reads from Memory (RAG), populates context.memory
+
+// 3. Agent executes (state tracked in Agent State)
+await runtime.execute(...);
+// ↑ State manager tracks steps, state transitions
+
+// 4. After execution, persist to Memory
+await contextBuilder.persistToMemory(context);
+// ↑ This writes conversation history, entities to Memory (RAG)
+```
+
+## Data Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Execution Start                                        │
+└─────────────────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Agent State         │  ← Create execution context
+│  (Redis/DB)          │
+└──────────────────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Memory (RAG)        │  ← Load conversation history, entities
+│  (Vector Store)      │     into execution context
+└──────────────────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Agent Executes      │  ← State manager tracks steps
+│                      │     Memory provides context
+└──────────────────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Memory (RAG)        │  ← Persist conversation, entities
+│  (Vector Store)      │     for future sessions
+└──────────────────────┘
+           │
+           ▼
+┌──────────────────────┐
+│  Agent State         │  ← Archive execution (optional)
+│  (Redis/DB)          │
+└──────────────────────┘
+```
+
+## Overlap: Conversation History
+
+**Both** store conversation history, but for different reasons:
+
+### Agent State Conversation History
+- **Purpose**: Track messages **during** execution
+- **Scope**: Single execution only
+- **Lifetime**: Until execution completes
+- **Use**: Resume paused executions, debug current run
+
+### Memory Conversation History
+- **Purpose**: Build context for **future** conversations
+- **Scope**: All sessions for a user/session
+- **Lifetime**: Long-term (weeks/months)
+- **Use**: Semantic search, context building, continuity
+
+## When to Use Which
+
+### Use Agent State Persistence when:
+- ✅ You need to resume paused executions
+- ✅ You want to track execution progress
+- ✅ You need to debug failed runs
+- ✅ You want to monitor active agents
+- ✅ You need execution audit trails
+
+### Use Memory Persistence when:
+- ✅ You want agents to remember past conversations
+- ✅ You need entity tracking across sessions
+- ✅ You want to store learned facts
+- ✅ You need semantic search of conversations
+- ✅ You want to maintain user preferences
+
+## Recommended Setup
+
+### Development
+```typescript
+// In-memory for both (default)
+const runtime = new AgentRuntime({
+  // stateManager: default (in-memory)
+  // memoryManager: default (BufferMemory)
+});
+```
+
+### Production
+```typescript
+// Redis for agent state (fast, distributed)
+// Vector store (Pinecone) for memory (semantic search)
+const stateManager = new RedisStateManager({ client: redisClient });
+const memoryStore = new VectorMemory(pineconeStore, embeddings);
+const memoryManager = new MemoryManager(memoryStore);
+
+const runtime = new AgentRuntime({
+  stateManager,      // ← Agent execution state
+  memoryManager,     // ← Long-term memory
+});
+```
+
+## Summary
+
+- **Agent State** = "What is the agent doing right now?"
+- **Memory** = "What does the agent know from past conversations?"
+
+They complement each other:
+- **State** enables resumable, trackable executions
+- **Memory** enables context-aware, continuous conversations
+
+Both are needed for a production-ready agent system!

package/dist/agent.module.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Agent Module
+ * HazelJS module for Agent Runtime
+ */
+import { AgentRuntime, AgentRuntimeConfig } from './runtime/agent.runtime';
+import { AgentEventType } from './types/event.types';
+type NewableFunction = new (...args: unknown[]) => unknown;
+/**
+ * Agent Module Options
+ */
+export interface AgentModuleOptions {
+    runtime?: AgentRuntimeConfig;
+    agents?: NewableFunction[];
+}
+/**
+ * Agent Service
+ * Injectable service for agent runtime
+ */
+export declare class AgentService {
+    private runtime;
+    constructor(config?: AgentRuntimeConfig);
+    getRuntime(): AgentRuntime;
+    execute(agentName: string, input: string, options?: Record<string, unknown>): Promise<unknown>;
+    resume(executionId: string, input?: string): Promise<unknown>;
+    getContext(executionId: string): unknown;
+    on(type: AgentEventType, handler: (event: unknown) => void): void;
+    getAgents(): unknown[];
+    approveToolExecution(requestId: string, approvedBy: string): void;
+    rejectToolExecution(requestId: string): void;
+    getPendingApprovals(): unknown[];
+}
+/**
+ * Agent Module
+ * Uses static configuration pattern compatible with HazelJS DI
+ */
+export declare class AgentModule {
+    private static options;
+    static forRoot(options?: AgentModuleOptions): typeof AgentModule;
+    static getOptions(): AgentModuleOptions;
+}
+export {};
+//# sourceMappingURL=agent.module.d.ts.map

package/dist/agent.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.module.d.ts","sourceRoot":"","sources":["../src/agent.module.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,KAAK,eAAe,GAAG,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,MAAM,CAAC,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,qBACa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAe;gBAElB,MAAM,GAAE,kBAAuB;IAa3C,UAAU,IAAI,YAAY;IAIpB,OAAO,CACX,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,OAAO,CAAC;IAIb,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAInE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIxC,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAIjE,SAAS,IAAI,OAAO,EAAE;IAItB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAIjE,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAI5C,mBAAmB,IAAI,OAAO,EAAE;CAGjC;AAED;;;GAGG;AACH,qBAIa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAC,OAAO,CAA0B;IAEhD,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,WAAW;IAKpE,MAAM,CAAC,UAAU,IAAI,kBAAkB;CAGxC"}