@hazeljs/agent 0.2.0-beta.1

package/dist/utils/rate-limiter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Rate Limiter
+ * Token bucket algorithm for rate limiting agent executions
+ */
+export interface RateLimiterConfig {
+    tokensPerMinute: number;
+    burstSize?: number;
+}
+export declare class RateLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly tokensPerMinute;
+    private readonly burstSize;
+    private readonly refillRate;
+    constructor(config: RateLimiterConfig);
+    /**
+     * Try to consume a token
+     * @returns true if token was consumed, false if rate limit exceeded
+     */
+    tryConsume(): boolean;
+    /**
+     * Wait until a token is available
+     * @param timeoutMs Maximum time to wait in milliseconds
+     * @returns true if token was acquired, false if timeout
+     */
+    waitForToken(timeoutMs?: number): Promise<boolean>;
+    /**
+     * Get current token count
+     */
+    getAvailableTokens(): number;
+    /**
+     * Reset the rate limiter
+     */
+    reset(): void;
+    /**
+     * Refill tokens based on elapsed time
+     */
+    private refill;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/utils/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,iBAAiB;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,iBAAiB;IAQrC;;;OAGG;IACH,UAAU,IAAI,OAAO;IAWrB;;;;OAIG;IACG,YAAY,CAAC,SAAS,GAAE,MAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB/D;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAK5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,CAAC,MAAM;IASd;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd"}

package/dist/utils/rate-limiter.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Rate Limiter
+ * Token bucket algorithm for rate limiting agent executions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimiter = void 0;
+class RateLimiter {
+    constructor(config) {
+        this.tokensPerMinute = config.tokensPerMinute;
+        this.burstSize = config.burstSize || config.tokensPerMinute;
+        this.tokens = this.burstSize;
+        this.lastRefill = Date.now();
+        this.refillRate = this.tokensPerMinute / 60000; // tokens per millisecond
+    }
+    /**
+     * Try to consume a token
+     * @returns true if token was consumed, false if rate limit exceeded
+     */
+    tryConsume() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Wait until a token is available
+     * @param timeoutMs Maximum time to wait in milliseconds
+     * @returns true if token was acquired, false if timeout
+     */
+    async waitForToken(timeoutMs = 30000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            if (this.tryConsume()) {
+                return true;
+            }
+            // Calculate wait time until next token
+            const tokensNeeded = 1 - this.tokens;
+            const waitMs = Math.ceil(tokensNeeded / this.refillRate);
+            const remainingTimeout = timeoutMs - (Date.now() - startTime);
+            const actualWaitMs = Math.min(waitMs, remainingTimeout, 1000);
+            if (actualWaitMs > 0) {
+                await this.sleep(actualWaitMs);
+            }
+        }
+        return false;
+    }
+    /**
+     * Get current token count
+     */
+    getAvailableTokens() {
+        this.refill();
+        return Math.floor(this.tokens);
+    }
+    /**
+     * Reset the rate limiter
+     */
+    reset() {
+        this.tokens = this.burstSize;
+        this.lastRefill = Date.now();
+    }
+    /**
+     * Refill tokens based on elapsed time
+     */
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        const tokensToAdd = elapsed * this.refillRate;
+        this.tokens = Math.min(this.burstSize, this.tokens + tokensToAdd);
+        this.lastRefill = now;
+    }
+    /**
+     * Sleep utility
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.RateLimiter = RateLimiter;
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAOH,MAAa,WAAW;IAOtB,YAAY,MAAyB;QACnC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,eAAe,CAAC;QAC5D,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,CAAC,yBAAyB;IAC3E,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,IAAI,CAAC,MAAM,EAAE,CAAC;QAEd,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAAC,YAAoB,KAAK;QAC1C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,SAAS,EAAE,CAAC;YAC1C,IAAI,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;gBACtB,OAAO,IAAI,CAAC;YACd,CAAC;YAED,uCAAuC;YACvC,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;YACzD,MAAM,gBAAgB,GAAG,SAAS,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;YAC9D,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;YAE9D,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,kBAAkB;QAChB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACK,MAAM;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC;QACtC,MAAM,WAAW,GAAG,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC;QAE9C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,CAAC;QAClE,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;IACxB,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AA3FD,kCA2FC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Retry Logic with Exponential Backoff
+ * Handles transient failures with configurable retry strategies
+ */
+export interface RetryConfig {
+    maxRetries: number;
+    initialDelayMs: number;
+    maxDelayMs: number;
+    backoffMultiplier: number;
+    retryableErrors?: string[];
+    onRetry?: (attempt: number, error: Error) => void;
+}
+export declare class RetryError extends Error {
+    readonly attempts: number;
+    readonly lastError: Error;
+    constructor(message: string, attempts: number, lastError: Error);
+}
+export declare class RetryHandler {
+    private config;
+    constructor(config?: Partial<RetryConfig>);
+    /**
+     * Execute a function with retry logic
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if an error is retryable
+     */
+    private isRetryable;
+    /**
+     * Calculate delay with exponential backoff and jitter
+     */
+    private calculateDelay;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+}
+/**
+ * Decorator for automatic retry
+ */
+export declare function Retry(config?: Partial<RetryConfig>): MethodDecorator;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACnD;AAED,qBAAa,UAAW,SAAQ,KAAK;aAGjB,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,KAAK;gBAFhC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,KAAK;CAKnC;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAwB;gBAE1B,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM;IAmB7C;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAqClD;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,cAAc;IAYtB;;OAEG;IACH,OAAO,CAAC,KAAK;CAGd;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,eAAe,CAYpE"}

package/dist/utils/retry.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Retry Logic with Exponential Backoff
+ * Handles transient failures with configurable retry strategies
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryHandler = exports.RetryError = void 0;
+exports.Retry = Retry;
+class RetryError extends Error {
+    constructor(message, attempts, lastError) {
+        super(message);
+        this.attempts = attempts;
+        this.lastError = lastError;
+        this.name = 'RetryError';
+    }
+}
+exports.RetryError = RetryError;
+class RetryHandler {
+    constructor(config = {}) {
+        this.config = {
+            maxRetries: config.maxRetries ?? 3,
+            initialDelayMs: config.initialDelayMs ?? 1000,
+            maxDelayMs: config.maxDelayMs ?? 30000,
+            backoffMultiplier: config.backoffMultiplier ?? 2,
+            retryableErrors: config.retryableErrors ?? [
+                'ECONNRESET',
+                'ETIMEDOUT',
+                'ENOTFOUND',
+                'ECONNREFUSED',
+                'RATE_LIMIT',
+                'SERVICE_UNAVAILABLE',
+                'TIMEOUT',
+            ],
+            onRetry: config.onRetry ?? (() => { }),
+        };
+    }
+    /**
+     * Execute a function with retry logic
+     */
+    async execute(fn) {
+        let lastError;
+        let attempt = 0;
+        while (attempt <= this.config.maxRetries) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                attempt++;
+                if (attempt > this.config.maxRetries) {
+                    throw new RetryError(`Failed after ${attempt} attempts: ${lastError.message}`, attempt, lastError);
+                }
+                if (!this.isRetryable(lastError)) {
+                    throw lastError;
+                }
+                const delay = this.calculateDelay(attempt);
+                this.config.onRetry(attempt, lastError);
+                await this.sleep(delay);
+            }
+        }
+        throw new RetryError(`Failed after ${attempt} attempts: ${lastError.message}`, attempt, lastError);
+    }
+    /**
+     * Check if an error is retryable
+     */
+    isRetryable(error) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const errorCode = error.code || error.name;
+        const errorMessage = error.message.toUpperCase();
+        return this.config.retryableErrors.some((retryableError) => errorCode === retryableError || errorMessage.includes(retryableError.toUpperCase()));
+    }
+    /**
+     * Calculate delay with exponential backoff and jitter
+     */
+    calculateDelay(attempt) {
+        const exponentialDelay = this.config.initialDelayMs * Math.pow(this.config.backoffMultiplier, attempt - 1);
+        const delayWithCap = Math.min(exponentialDelay, this.config.maxDelayMs);
+        // Add jitter (±25%)
+        const jitter = delayWithCap * 0.25 * (Math.random() * 2 - 1);
+        return Math.max(0, delayWithCap + jitter);
+    }
+    /**
+     * Sleep utility
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.RetryHandler = RetryHandler;
+/**
+ * Decorator for automatic retry
+ */
+function Retry(config) {
+    const retryHandler = new RetryHandler(config);
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            return retryHandler.execute(() => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hazeljs/agent",
+  "version": "0.2.0-beta.1",
+  "description": "AI-native Agent Runtime for HazelJS - stateful, long-running agents with tools, memory, and human-in-the-loop",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "test": "jest --coverage --passWithNoTests",
+    "test:watch": "jest --watch",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix"
+  },
+  "keywords": [
+    "hazeljs",
+    "agent",
+    "ai-agent",
+    "llm",
+    "agentic",
+    "agent-runtime",
+    "tools",
+    "memory",
+    "human-in-the-loop"
+  ],
+  "author": "HazelJS Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hazeljs/hazeljs",
+    "directory": "packages/agent"
+  },
+  "dependencies": {
+    "@hazeljs/core": "file:../core",
+    "@hazeljs/rag": "file:../rag",
+    "reflect-metadata": "^0.2.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.10.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@hazeljs/core": ">=0.2.0",
+    "@hazeljs/rag": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "redis": {
+      "optional": true,
+      "description": "Required for RedisStateManager"
+    },
+    "@prisma/client": {
+      "optional": true,
+      "description": "Required for DatabaseStateManager"
+    }
+  }
+}

package/prisma-schema.example.prisma

@@ -0,0 +1,76 @@
+// Example Prisma schema for Agent State Persistence
+// 
+// INSTRUCTIONS:
+// 1. Copy the models below into your existing prisma/schema.prisma file
+// 2. Run: npx prisma migrate dev --name add_agent_state_models
+// 3. Run: npx prisma generate
+// 4. See PRISMA_INTEGRATION.md for detailed instructions
+//
+// NOTE: This is an example file. You need to add these models to your actual schema.prisma
+
+model AgentContext {
+  id                String   @id @default(uuid())
+  executionId      String   @unique
+  agentId          String
+  sessionId        String
+  userId           String?
+  input            String
+  state            String   // AgentState enum as string
+  steps            Json     // AgentStep[]
+  conversationHistory Json   // ConversationMessage[]
+  workingMemory    Json     // Record<string, unknown>
+  facts            Json     // string[]
+  entities         Json     // Entity[]
+  ragContext       Json?    // string[]
+  metadata         Json     // Record<string, unknown>
+  createdAt        DateTime @default(now())
+  updatedAt        DateTime @updatedAt
+  deletedAt        DateTime? // For soft deletes
+  agentSteps       AgentStep[]? // Optional: relation to steps table
+
+  @@index([sessionId])
+  @@index([userId])
+  @@index([agentId])
+  @@index([state])
+  @@index([createdAt])
+  @@index([deletedAt])
+  @@map("agent_contexts")
+}
+
+// Optional: Separate table for execution steps (for better querying)
+model AgentStep {
+  id            String   @id @default(uuid())
+  executionId   String
+  stepNumber    Int
+  state         String
+  action        Json?
+  result        Json?
+  error         String?
+  timestamp     DateTime @default(now())
+  duration      Int?
+
+  context       AgentContext @relation(fields: [executionId], references: [executionId], onDelete: Cascade)
+  
+  // Note: If you don't want a separate steps table, remove this model
+  // and store steps as JSON in AgentContext.steps field
+
+  @@index([executionId])
+  @@index([timestamp])
+  @@map("agent_steps")
+}
+
+// Optional: Session tracking
+model AgentSession {
+  id            String   @id @default(uuid())
+  sessionId     String   @unique
+  userId        String?
+  agentId       String
+  createdAt     DateTime @default(now())
+  updatedAt     DateTime @updatedAt
+  completedAt   DateTime?
+
+  @@index([userId])
+  @@index([agentId])
+  @@index([createdAt])
+  @@map("agent_sessions")
+}