@agentier/middleware 0.1.0

package/dist/cache.d.ts

@@ -0,0 +1,59 @@
+import type { Middleware, AgentAction } from '@agentier/core';
+/**
+ * Configuration options for the caching middleware.
+ */
+export interface CacheMiddlewareOptions {
+    /**
+     * Time-to-live for cached entries in milliseconds.
+     * After this duration, a cached result is considered stale and will be evicted.
+     *
+     * @default 300000 (5 minutes)
+     */
+    ttl?: number;
+    /**
+     * Maximum number of entries the cache may hold. When exceeded, the oldest
+     * entry (by insertion order) is evicted.
+     *
+     * @default 100
+     */
+    maxEntries?: number;
+    /**
+     * Custom function that derives a cache key from an action. Return `null` to
+     * skip caching for that action. When omitted, a built-in key function is used
+     * that caches `model_call` actions based on model, messages, and tools.
+     *
+     * @param action - The agent action to compute a key for.
+     * @returns A string cache key, or `null` to bypass caching.
+     *
+     * @example
+     * ```ts
+     * {
+     *   keyFn: (action) => action.type === 'tool_call'
+     *     ? `tool:${action.payload.name}:${JSON.stringify(action.payload.args)}`
+     *     : null,
+     * }
+     * ```
+     */
+    keyFn?: (action: AgentAction) => string | null;
+}
+/**
+ * Creates a middleware that caches action results in memory using a simple
+ * TTL + max-size eviction strategy. Identical actions (as determined by
+ * their cache key) that hit a live cache entry are returned immediately
+ * without invoking the downstream pipeline.
+ *
+ * @param options - Optional configuration for TTL, capacity, and key derivation.
+ * @returns A {@link Middleware} function that adds response caching to the pipeline.
+ *
+ * @example
+ * ```ts
+ * import { cacheMiddleware } from '@agentier/middleware'
+ *
+ * const agent = createAgent({
+ *   middleware: [
+ *     cacheMiddleware({ ttl: 60_000, maxEntries: 50 }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function cacheMiddleware(options?: CacheMiddlewareOptions): Middleware;

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module @agentier/middleware
+ *
+ * A collection of composable middleware functions for the Agentier agent
+ * pipeline. Each middleware wraps a specific cross-cutting concern --
+ * logging, retry, rate limiting, or caching -- and can be combined freely.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   logMiddleware,
+ *   retryMiddleware,
+ *   rateLimitMiddleware,
+ *   cacheMiddleware,
+ * } from '@agentier/middleware'
+ *
+ * const agent = createAgent({
+ *   middleware: [
+ *     logMiddleware(),
+ *     retryMiddleware({ maxRetries: 3 }),
+ *     rateLimitMiddleware({ rpm: 60 }),
+ *     cacheMiddleware({ ttl: 60_000 }),
+ *   ],
+ * })
+ * ```
+ */
+export { logMiddleware } from './log';
+export type { LogMiddlewareOptions } from './log';
+export { retryMiddleware } from './retry';
+export type { RetryMiddlewareOptions } from './retry';
+export { rateLimitMiddleware } from './rate-limit';
+export type { RateLimitMiddlewareOptions } from './rate-limit';
+export { cacheMiddleware } from './cache';
+export type { CacheMiddlewareOptions } from './cache';

package/dist/index.js

@@ -0,0 +1,145 @@
+// src/log.ts
+function logMiddleware(options) {
+  const { actions, logger = console } = options ?? {};
+  return async (action, next) => {
+    if (actions && !actions.includes(action.type)) {
+      return next();
+    }
+    const start = Date.now();
+    const summary = formatAction(action);
+    logger.log(`[agentier] ${action.type} ${summary}`);
+    try {
+      const result = await next();
+      logger.log(`[agentier] ${action.type} done (${Date.now() - start}ms)`);
+      return result;
+    } catch (error) {
+      logger.error(`[agentier] ${action.type} failed (${Date.now() - start}ms)`, error);
+      throw error;
+    }
+  };
+}
+function formatAction(action) {
+  const p = action.payload;
+  switch (action.type) {
+    case "model_call":
+      return `model=${p.model}`;
+    case "tool_call":
+      return `tool=${p.name}`;
+    case "tool_result":
+      return `tool=${p.name} duration=${p.duration}ms`;
+    case "error":
+      return `source=${p.source} ${p.name ? `tool=${p.name}` : ""}`;
+    default:
+      return "";
+  }
+}
+// src/retry.ts
+function retryMiddleware(options) {
+  const {
+    maxRetries = 3,
+    retryOn = ["model_call"],
+    backoff = "exponential",
+    baseDelay = 1000
+  } = options ?? {};
+  return async (action, next) => {
+    if (!retryOn.includes(action.type)) {
+      return next();
+    }
+    let lastError = null;
+    for (let attempt = 0;attempt <= maxRetries; attempt++) {
+      try {
+        return await next();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt === maxRetries)
+          break;
+        const delay = backoff === "exponential" ? baseDelay * Math.pow(2, attempt) : baseDelay;
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    throw lastError;
+  };
+}
+// src/rate-limit.ts
+function rateLimitMiddleware(options) {
+  const { rpm, limitOn = ["model_call"] } = options;
+  const windowMs = 60000;
+  const timestamps = [];
+  return async (action, next) => {
+    if (!limitOn.includes(action.type)) {
+      return next();
+    }
+    const now = Date.now();
+    while (timestamps.length > 0 && timestamps[0] <= now - windowMs) {
+      timestamps.shift();
+    }
+    if (timestamps.length >= rpm) {
+      const waitUntil = timestamps[0] + windowMs;
+      const waitMs = waitUntil - now;
+      if (waitMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+      }
+      while (timestamps.length > 0 && timestamps[0] <= Date.now() - windowMs) {
+        timestamps.shift();
+      }
+    }
+    timestamps.push(Date.now());
+    return next();
+  };
+}
+// src/cache.ts
+function cacheMiddleware(options) {
+  const { ttl = 5 * 60 * 1000, maxEntries = 100, keyFn } = options ?? {};
+  const cache = new Map;
+  function defaultKeyFn(action) {
+    if (action.type !== "model_call")
+      return null;
+    const payload = action.payload;
+    const key = JSON.stringify({
+      model: payload.model,
+      messages: payload.messages,
+      tools: payload.tools
+    });
+    return key;
+  }
+  function evictExpired() {
+    const now = Date.now();
+    for (const [key, entry] of cache) {
+      if (entry.expiresAt <= now) {
+        cache.delete(key);
+      }
+    }
+  }
+  function evictOldest() {
+    if (cache.size <= maxEntries)
+      return;
+    const firstKey = cache.keys().next().value;
+    if (firstKey !== undefined) {
+      cache.delete(firstKey);
+    }
+  }
+  return async (action, next) => {
+    const key = keyFn ? keyFn(action) : defaultKeyFn(action);
+    if (!key) {
+      return next();
+    }
+    evictExpired();
+    const cached = cache.get(key);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.result;
+    }
+    const result = await next();
+    cache.set(key, {
+      result,
+      expiresAt: Date.now() + ttl
+    });
+    evictOldest();
+    return result;
+  };
+}
+export {
+  retryMiddleware,
+  rateLimitMiddleware,
+  logMiddleware,
+  cacheMiddleware
+};

package/dist/log.d.ts

@@ -0,0 +1,44 @@
+import type { Middleware, AgentActionType } from '@agentier/core';
+/**
+ * Configuration options for the logging middleware.
+ */
+export interface LogMiddlewareOptions {
+    /**
+     * Action types to log. When provided, only matching actions are logged.
+     * If omitted, all actions are logged.
+     *
+     * @example
+     * ```ts
+     * { actions: ['model_call', 'tool_call'] }
+     * ```
+     */
+    actions?: AgentActionType[];
+    /**
+     * Logger instance to use for output. Must implement `log` and `error` methods.
+     * Defaults to the global `console`.
+     *
+     * @default console
+     */
+    logger?: Pick<Console, 'log' | 'error'>;
+}
+/**
+ * Creates a middleware that logs agent actions with timing information.
+ *
+ * Each action is logged at the start and on completion (or failure) with
+ * elapsed time in milliseconds. Output is prefixed with `[agentier]`.
+ *
+ * @param options - Optional configuration for filtering and logger selection.
+ * @returns A {@link Middleware} function that logs actions passing through the pipeline.
+ *
+ * @example
+ * ```ts
+ * import { logMiddleware } from '@agentier/middleware'
+ *
+ * const agent = createAgent({
+ *   middleware: [
+ *     logMiddleware({ actions: ['model_call', 'tool_call'] }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function logMiddleware(options?: LogMiddlewareOptions): Middleware;

package/dist/rate-limit.d.ts

@@ -0,0 +1,37 @@
+import type { Middleware, AgentActionType } from '@agentier/core';
+/**
+ * Configuration options for the rate-limiting middleware.
+ */
+export interface RateLimitMiddlewareOptions {
+    /**
+     * Maximum number of requests permitted per minute (rolling window).
+     */
+    rpm: number;
+    /**
+     * Action types subject to rate limiting.
+     * Actions whose type is not in this list pass through without throttling.
+     *
+     * @default ['model_call']
+     */
+    limitOn?: AgentActionType[];
+}
+/**
+ * Creates a middleware that enforces a per-minute request rate limit using a
+ * sliding window. When the limit is reached, subsequent calls are delayed
+ * until the oldest tracked request falls outside the 60-second window.
+ *
+ * @param options - Configuration specifying the rate cap and target action types.
+ * @returns A {@link Middleware} function that throttles actions in the pipeline.
+ *
+ * @example
+ * ```ts
+ * import { rateLimitMiddleware } from '@agentier/middleware'
+ *
+ * const agent = createAgent({
+ *   middleware: [
+ *     rateLimitMiddleware({ rpm: 60, limitOn: ['model_call'] }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function rateLimitMiddleware(options: RateLimitMiddlewareOptions): Middleware;

package/dist/retry.d.ts

@@ -0,0 +1,57 @@
+import type { Middleware, AgentActionType } from '@agentier/core';
+/**
+ * Configuration options for the retry middleware.
+ */
+export interface RetryMiddlewareOptions {
+    /**
+     * Maximum number of retry attempts after the initial call fails.
+     *
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Action types that should be retried on failure.
+     * Actions whose type is not in this list pass through without retry logic.
+     *
+     * @default ['model_call']
+     */
+    retryOn?: AgentActionType[];
+    /**
+     * Backoff strategy used to calculate the delay between retries.
+     *
+     * - `'fixed'` -- waits `baseDelay` ms between every attempt.
+     * - `'exponential'` -- waits `baseDelay * 2^attempt` ms, doubling each time.
+     *
+     * @default 'exponential'
+     */
+    backoff?: 'fixed' | 'exponential';
+    /**
+     * Base delay in milliseconds used for backoff calculation.
+     *
+     * @default 1000
+     */
+    baseDelay?: number;
+}
+/**
+ * Creates a middleware that automatically retries failed actions.
+ *
+ * When an action whose type is listed in `retryOn` throws an error, the
+ * middleware re-invokes the downstream pipeline up to `maxRetries` times,
+ * waiting between attempts according to the chosen `backoff` strategy.
+ * If all attempts fail, the last error is re-thrown.
+ *
+ * @param options - Optional configuration for retry behaviour.
+ * @returns A {@link Middleware} function that adds retry logic to the pipeline.
+ *
+ * @example
+ * ```ts
+ * import { retryMiddleware } from '@agentier/middleware'
+ *
+ * const agent = createAgent({
+ *   middleware: [
+ *     retryMiddleware({ maxRetries: 5, backoff: 'exponential', baseDelay: 500 }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function retryMiddleware(options?: RetryMiddlewareOptions): Middleware;

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@agentier/middleware",
+    "version": "0.1.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "bun build ./src/index.ts --outdir ./dist --target node",
+        "test": "bun test",
+        "typecheck": "tsc --noEmit"
+    },
+    "peerDependencies": {
+        "@agentier/core": "^0.1.0"
+    },
+    "devDependencies": {
+        "@agentier/core": "workspace:*",
+        "typescript": "^5.5.0",
+        "@types/bun": "latest"
+    }
+}