agent-tool-forge 0.4.1 → 0.4.5

package/lib/drift-background.js

@@ -1,8 +1,9 @@
 /**
  * Background Drift Monitor — periodically checks all promoted tools for drift.
  *
- * Reuses checkDrift() and computeSuspects() from cli/drift-monitor.js.
- * Started in forge-service.js when --mode=sidecar.
+ * Reuses checkDrift() and computeSuspects() from drift-monitor.js for the
+ * SQLite path. When Postgres is configured, uses an async Postgres path that
+ * reads from PostgresEvalStore and PostgresStore instead.
  */
 
 import { getAllToolRegistry, insertDriftAlert } from './db.js';
@@ -14,16 +15,65 @@ const DEFAULT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
  * Create a background drift monitor.
  *
  * @param {object} config — forge config (drift.threshold, drift.windowSize)
- * @param {import('better-sqlite3').Database} db
+ * @param {import('better-sqlite3').Database} db — SQLite db (used when pgCtx is null)
  * @param {number} [intervalMs] — check interval (default 5 min)
- * @returns {{ start(): void, stop(): void, runOnce(): void }}
+ * @param {{ pgStore: object, evalStore: object, _pgPool: object } | null} [pgCtx]
+ *   — Postgres context; when provided, the Postgres async path is used instead of SQLite.
+ * @returns {{ start(): void, stop(): void, runOnce(): Promise<void> }}
  */
-export function createDriftMonitor(config, db, intervalMs = DEFAULT_INTERVAL_MS) {
+export function createDriftMonitor(config, db, intervalMs = DEFAULT_INTERVAL_MS, pgCtx = null) {
   let timer = null;
   const threshold = config.drift?.threshold ?? 0.1;
   const windowSize = config.drift?.windowSize ?? 5;
 
-  function runOnce() {
+  async function runOncePg({ pgStore, evalStore, _pgPool }) {
+    const allTools = await pgStore.getAllToolRegistry();
+    const promoted = allTools.filter(r => r.lifecycle_state === 'promoted');
+
+    for (const tool of promoted) {
+      const baseline = tool.baseline_pass_rate;
+      if (baseline == null) continue;
+
+      const history = await evalStore.getPerToolRunHistory(tool.tool_name, windowSize);
+      if (!history.length) continue;
+
+      const avg = history.reduce((s, r) => s + (r.pass_rate || 0), 0) / history.length;
+      const delta = baseline - avg;
+      if (delta < threshold) continue;
+
+      // Skip if an open alert already exists
+      const { rows: [existing] } = await _pgPool.query(
+        `SELECT id FROM drift_alerts WHERE tool_name = $1 AND status = 'open' LIMIT 1`,
+        [tool.tool_name]
+      );
+      if (existing) continue;
+
+      const now = new Date().toISOString();
+      const client = await _pgPool.connect();
+      try {
+        await client.query('BEGIN');
+        await client.query(
+          `INSERT INTO drift_alerts
+             (tool_name, detected_at, trigger_tools, baseline_rate, current_rate, delta, status)
+           VALUES ($1,$2,$3,$4,$5,$6,'open')`,
+          [tool.tool_name, now, '[]', baseline, avg, delta]
+        );
+        await client.query(
+          `UPDATE tool_registry SET lifecycle_state = 'flagged', flagged_at = $1
+           WHERE tool_name = $2 AND lifecycle_state != 'flagged'`,
+          [now, tool.tool_name]
+        );
+        await client.query('COMMIT');
+      } catch (e) {
+        await client.query('ROLLBACK');
+        process.stderr.write(`[drift-monitor] Postgres alert insert failed for ${tool.tool_name}: ${e.message}\n`);
+      } finally {
+        client.release();
+      }
+    }
+  }
+
+  function runOnceSqlite() {
     try {
       const tools = getAllToolRegistry(db).filter(r => r.lifecycle_state === 'promoted');
       for (const tool of tools) {
@@ -44,10 +94,22 @@ export function createDriftMonitor(config, db, intervalMs = DEFAULT_INTERVAL_MS)
     }
   }
 
+  async function runOnce() {
+    if (pgCtx) {
+      try {
+        await runOncePg(pgCtx);
+      } catch (err) {
+        process.stderr.write(`[drift-monitor] Postgres error during check: ${err.message}\n`);
+      }
+    } else {
+      runOnceSqlite();
+    }
+  }
+
   return {
     start() {
       if (timer) return;
-      timer = setInterval(runOnce, intervalMs);
+      timer = setInterval(() => { runOnce().catch(() => {}); }, intervalMs);
       timer.unref(); // Don't block process exit
     },
     stop() {

package/lib/forge-service.js

@@ -135,7 +135,7 @@ export async function buildSidecarContext(config, db, env = {}, opts = {}) {
   const conversationStore = makeConversationStore(config, db, pgPool);
   const hitlEngine = makeHitlEngine(config, db, redisClient, pgPool);
   const verifierRunner = new VerifierRunner(db, config, pgPool ?? null);
-  const rateLimiter = makeRateLimiter(config, redisClient);
+  const rateLimiter = makeRateLimiter(config, redisClient, pgPool);
 
   // configPath — used by admin handler to persist overlay changes.
   // Defaults to process.cwd() so library consumers write config to their own
@@ -207,11 +207,14 @@ function serveWidgetFile(req, res, widgetDir, errorFn) {
  * @param {object} [options]
  * @param {string} [options.widgetDir] — directory for /widget/* static files (defaults to <project>/widget)
  * @param {function} [options.mcpHandler] — optional async (req, res) handler for /mcp route
+ * @param {function} [options.customRoutes] — optional async (req, res, ctx) => boolean; called before
+ *   the 404 fallback. Return true if the request was handled, false to fall through to 404.
  * @returns {function(import('http').IncomingMessage, import('http').ServerResponse): Promise<void>}
  */
 export function createSidecarRouter(ctx, options = {}) {
   const widgetDir = options.widgetDir || resolve(__dirname, '..', 'widget');
   const mcpHandler = options.mcpHandler || null;
+  const customRoutes = options.customRoutes || null;
 
   return async (req, res) => {
     const url = new URL(req.url, 'http://localhost');
@@ -261,12 +264,65 @@ export function createSidecarRouter(ctx, options = {}) {
       return handleAdminConfig(req, res, ctx);
     }
 
+    // ── Eval endpoints ─────────────────────────────────────────────────────
+    if (sidecarPath === '/agent-api/evals/summary' && req.method === 'GET') {
+      if (ctx.evalStore) {
+        try {
+          sendJson(res, 200, await ctx.evalStore.getEvalSummary());
+        } catch (err) {
+          sendJson(res, 500, { error: 'Failed to fetch eval summary' });
+        }
+      } else if (ctx.db) {
+        try {
+          const rows = ctx.db.prepare(
+            `SELECT tool_name, MAX(run_at) AS last_run,
+                    SUM(total_cases) AS total_cases, SUM(passed) AS passed,
+                    SUM(failed) AS failed,
+                    ROUND(CAST(SUM(passed) AS REAL) / NULLIF(SUM(passed)+SUM(failed),0) * 100, 1) AS pass_rate
+             FROM eval_runs GROUP BY tool_name ORDER BY tool_name`
+          ).all();
+          sendJson(res, 200, rows);
+        } catch { sendJson(res, 500, { error: 'Failed to fetch eval summary' }); }
+      } else {
+        sendJson(res, 200, []);
+      }
+      return;
+    }
+
+    if (sidecarPath === '/agent-api/evals/runs' && req.method === 'GET') {
+      const limit  = parseInt(url.searchParams.get('limit')  || '50', 10);
+      const offset = parseInt(url.searchParams.get('offset') || '0',  10);
+      if (ctx.evalStore) {
+        try {
+          sendJson(res, 200, await ctx.evalStore.listRuns(limit, offset));
+        } catch (err) {
+          sendJson(res, 500, { error: 'Failed to fetch eval runs' });
+        }
+      } else if (ctx.db) {
+        try {
+          const rows = ctx.db.prepare(
+            'SELECT * FROM eval_runs ORDER BY run_at DESC LIMIT ? OFFSET ?'
+          ).all(limit, offset);
+          sendJson(res, 200, rows);
+        } catch { sendJson(res, 500, { error: 'Failed to fetch eval runs' }); }
+      } else {
+        sendJson(res, 200, []);
+      }
+      return;
+    }
+
     // ── Widget static file serving ─────────────────────────────────────────
     if (url.pathname.startsWith('/widget/')) {
       serveWidgetFile(req, res, widgetDir, sendJson);
       return;
     }
 
+    // ── Custom routes (consumer-provided) ─────────────────────────────────
+    if (customRoutes) {
+      const handled = await customRoutes(req, res, ctx);
+      if (handled) return;
+    }
+
     // ── 404 fallback ───────────────────────────────────────────────────────
     sendJson(res, 404, { error: 'not found' });
   };

package/lib/postgres-store.d.ts

@@ -1,31 +1,276 @@
 /**
- * Postgres-backed storage adapter for horizontal scaling.
+ * Postgres-backed storage adapters for horizontal scaling (0.4.x).
  *
- * Mirrors the SQLite query function signatures from `db.js` but uses a `pg` Pool.
- * Only loaded when `conversation.store === 'postgres'` (or `database.type === 'postgres'`) in config.
+ * This module exports seven classes that mirror the SQLite-backed store
+ * interfaces from db.js, prompt-store.js, preference-store.js,
+ * agent-registry.js, and the eval/audit/verifier sub-systems.  All classes
+ * accept an existing `pg.Pool` (or create one internally) so they can share
+ * a single connection pool in sidecar deployments.
  *
  * Requires: `npm install pg`
+ * Optional — only loaded when `database.type === 'postgres'` (or
+ * `conversation.store === 'postgres'`) in forge config.
+ */
+
+// ── PostgresStore ─────────────────────────────────────────────────────────
+
+/**
+ * Base store that owns the pg.Pool lifecycle and hosts the tool-registry
+ * methods.  Call `connect()` before using any other method.
  */
 export class PostgresStore {
   constructor(pgConfig: { connectionString: string });
 
   /**
-   * Connect to Postgres and run schema migrations.
+   * Connect to Postgres, run schema migrations, and return `this`.
    * Must be called before any other method.
    */
   connect(): Promise<this>;
 
-  /** Close the connection pool. */
+  /** Drain and close the connection pool. */
   close(): Promise<void>;
 
-  // ── Prompt versions ───────────────────────────────────────────────────────
+  // ── Tool registry ────────────────────────────────────────────────────────
+
+  /** Return all tool_registry rows where lifecycle_state = 'promoted'. */
+  getPromotedTools(): Promise<object[]>;
+
+  /** Insert or update a tool_registry row. */
+  upsertToolRegistry(row: object): Promise<void>;
+
+  /** Return the tool_registry row for `toolName`, or null if not found. */
+  getToolRegistry(toolName: string): Promise<object | null>;
+
+  /** Return all tool_registry rows. */
+  getAllToolRegistry(): Promise<object[]>;
+
+  /**
+   * Apply lifecycle column updates (lifecycle_state, promoted_at,
+   * flagged_at, retired_at, replaced_by, baseline_pass_rate) to a single
+   * tool row.  Unknown keys in `updates` are silently ignored.
+   */
+  updateToolLifecycle(toolName: string, updates: Record<string, unknown>): Promise<void>;
+}
+
+// ── PostgresPromptStore ────────────────────────────────────────────────────
+
+/**
+ * Postgres-backed PromptStore — same interface as PromptStore in
+ * prompt-store.js.  Accepts an existing pg.Pool created by
+ * buildSidecarContext.
+ */
+export class PostgresPromptStore {
+  constructor(pool: object);
+
+  /** Return the content of the currently active prompt, or '' if none. */
+  getActivePrompt(): Promise<string>;
+
+  /** Return all prompt_versions rows ordered by id DESC. */
+  getAllVersions(): Promise<object[]>;
+
+  /** Return a single prompt_versions row by id, or null if not found. */
+  getVersion(id: number): Promise<object | null>;
+
+  /**
+   * Insert a new prompt version (inactive) and return its generated id,
+   * or null on failure.
+   */
+  createVersion(version: string, content: string, notes?: string | null): Promise<number | null>;
+
+  /**
+   * Deactivate all other versions and activate the row with the given id.
+   * Runs inside a transaction.
+   */
+  activate(id: number | string): Promise<void>;
+}
+
+// ── PostgresPreferenceStore ────────────────────────────────────────────────
 
-  getActivePrompt(): Promise<object | null>;
-  insertPromptVersion(row: { version: string; content: string; notes?: string | null }): Promise<number | null>;
-  activatePromptVersion(id: number): Promise<void>;
+/**
+ * Postgres-backed PreferenceStore — same interface as PreferenceStore in
+ * preference-store.js.
+ */
+export class PostgresPreferenceStore {
+  constructor(pool: object, config?: object, env?: Record<string, string>);
+
+  /**
+   * Return the stored preferences for a user as `{ model, hitlLevel }`,
+   * or null if the user has no row.
+   */
+  getUserPreferences(userId: string): Promise<object | null>;
+
+  /** Insert or update the user_preferences row for `userId`. */
+  setUserPreferences(userId: string, prefs: object): Promise<void>;
+
+  /**
+   * Resolve the effective runtime settings (model, hitlLevel, provider,
+   * apiKey) for a user, merging config defaults with any stored preferences.
+   */
+  resolveEffective(userId: string, config: object, env: object): Promise<object>;
+}
 
-  // ── User preferences ──────────────────────────────────────────────────────
+// ── PostgresAgentRegistry ──────────────────────────────────────────────────
 
-  getUserPreferences(userId: string): Promise<{ model: string | null; hitl_level: string | null } | null>;
-  upsertUserPreferences(userId: string, prefs: { model?: string; hitlLevel?: string }): Promise<void>;
+/**
+ * Postgres-backed AgentRegistry — same interface as AgentRegistry in
+ * agent-registry.js.
+ */
+export class PostgresAgentRegistry {
+  constructor(config: object, pool: object);
+
+  /**
+   * Return the default agent when `agentId` is null/undefined, or look up
+   * by id.  Returns null when the agent is disabled or not found.
+   */
+  resolveAgent(agentId: string | null): Promise<object | null>;
+
+  /** Return the agent_registry row for `agentId`, or null. */
+  getAgent(agentId: string): Promise<object | null>;
+
+  /** Return all agent_registry rows ordered by display_name. */
+  getAllAgents(): Promise<object[]>;
+
+  /** Insert or update an agent_registry row. */
+  upsertAgent(agent: object): Promise<void>;
+
+  /** Delete the agent_registry row for `agentId`. */
+  deleteAgent(agentId: string): Promise<void>;
+
+  /**
+   * Clear is_default on all agents and set it on `agentId`.
+   * No-ops (with implicit rollback) if the target agent is disabled.
+   * Runs inside a transaction.
+   */
+  setDefault(agentId: string): Promise<void>;
+
+  /**
+   * Merge agent-level overrides (model, hitlLevel, tool policy, turn/token
+   * limits) on top of the base forge config and return the merged object.
+   */
+  buildAgentConfig(config: object, agent: object | null): object;
+
+  /**
+   * Resolve the system prompt for a request: agent.system_prompt >
+   * promptStore active prompt > config.systemPrompt > fallback string.
+   */
+  resolveSystemPrompt(agent: object | null, promptStore: object, config: object): Promise<string>;
+
+  /**
+   * Upsert all agents declared in `config.agents` that are either new or
+   * were previously seeded from config.  Sets the default agent when
+   * `isDefault` is provided.
+   */
+  seedFromConfig(): Promise<void>;
+}
+
+// ── PostgresEvalStore ──────────────────────────────────────────────────────
+
+/** Postgres-backed store for eval run results and per-case records. */
+export class PostgresEvalStore {
+  constructor(pool: object);
+
+  /** Insert an eval_runs header row and return its generated id, or null. */
+  insertEvalRun(row: object): Promise<number | null>;
+
+  /**
+   * Bulk-insert eval_run_cases rows inside a single transaction.
+   * No-ops when `rows` is empty.
+   */
+  insertEvalRunCases(rows: object[]): Promise<void>;
+
+  /**
+   * Return an aggregated summary (last_run, total_cases, passed, failed,
+   * pass_rate) grouped by tool_name.
+   */
+  getEvalSummary(): Promise<object[]>;
+
+  /**
+   * Return the most recent `windowSize` eval_runs rows for a single tool,
+   * ordered newest-first.
+   */
+  getPerToolRunHistory(toolName: string, windowSize?: number): Promise<object[]>;
+
+  /**
+   * Return a paginated list of eval_runs rows ordered by run_at DESC.
+   */
+  listRuns(limit?: number, offset?: number): Promise<object[]>;
+}
+
+// ── PostgresChatAuditStore ─────────────────────────────────────────────────
+
+/** Postgres-backed store for per-request chat audit records. */
+export class PostgresChatAuditStore {
+  constructor(pool: object);
+
+  /**
+   * Insert a chat_audit row and return its generated id, or null on
+   * failure.
+   */
+  insertChatAudit(row: object): Promise<number | null>;
+
+  /**
+   * Return aggregate statistics across all chat_audit rows:
+   * total sessions, average duration, error rate, and messages in the
+   * last 24 hours.
+   */
+  getStats(): Promise<{
+    totalSessions: number;
+    avgDurationMs: number;
+    errorRate: number;
+    messagesToday: number;
+  }>;
+
+  /** Return a paginated list of chat_audit rows ordered by created_at DESC. */
+  getSessions(limit?: number, offset?: number): Promise<object[]>;
+}
+
+// ── PostgresVerifierStore ──────────────────────────────────────────────────
+
+/**
+ * Postgres-backed store for verifier registry entries, tool bindings, and
+ * per-invocation results.
+ */
+export class PostgresVerifierStore {
+  constructor(pool: object);
+
+  /** Insert or update a verifier_registry row. */
+  upsertVerifier(row: object): Promise<void>;
+
+  /** Return the verifier_registry row for `name`, or null. */
+  getVerifier(name: string): Promise<object | null>;
+
+  /** Return all enabled verifier_registry rows ordered by aciru_order. */
+  getAllVerifiers(): Promise<object[]>;
+
+  /**
+   * Delete a verifier and all of its tool bindings inside a transaction.
+   */
+  deleteVerifier(name: string): Promise<void>;
+
+  /** Insert or update a verifier_tool_bindings row. */
+  upsertVerifierBinding(binding: object): Promise<void>;
+
+  /** Delete the binding between a verifier and a specific tool. */
+  removeVerifierBinding(verifierName: string, toolName: string): Promise<void>;
+
+  /**
+   * Return all enabled verifier_registry rows that are bound to
+   * `toolName`, ordered by aciru_order.
+   */
+  getVerifiersForTool(toolName: string): Promise<object[]>;
+
+  /** Return all verifier_tool_bindings rows for a given verifier. */
+  getBindingsForVerifier(verifierName: string): Promise<object[]>;
+
+  /**
+   * Insert a verifier_results row and return its generated id, or null on
+   * failure.
+   */
+  insertVerifierResult(row: object): Promise<number | null>;
+
+  /**
+   * Return verifier_results rows ordered by created_at DESC.  When
+   * `toolName` is provided, results are filtered to that tool.
+   */
+  getResults(toolName?: string | null, limit?: number): Promise<object[]>;
 }

package/lib/postgres-store.js

@@ -149,6 +149,29 @@ CREATE TABLE IF NOT EXISTS verifier_tool_bindings (
 );
 CREATE INDEX IF NOT EXISTS idx_vtb_tool_name
   ON verifier_tool_bindings(tool_name, verifier_name);
+
+-- drift_alerts (mirrors SQLite schema in db.js)
+CREATE TABLE IF NOT EXISTS drift_alerts (
+  id SERIAL PRIMARY KEY,
+  tool_name TEXT NOT NULL,
+  detected_at TEXT NOT NULL,
+  trigger_tools TEXT,
+  baseline_rate REAL,
+  current_rate REAL,
+  delta REAL,
+  status TEXT NOT NULL DEFAULT 'open',
+  resolved_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_drift_alerts_tool_status
+  ON drift_alerts(tool_name, status);
+
+-- rate_limit_buckets (for PostgresRateLimiter)
+CREATE TABLE IF NOT EXISTS rate_limit_buckets (
+  key TEXT NOT NULL,
+  window_start BIGINT NOT NULL,
+  count INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (key, window_start)
+);
 `;
 
 export class PostgresStore {
@@ -241,21 +264,6 @@ export class PostgresStore {
       `UPDATE tool_registry SET ${sets.join(', ')} WHERE tool_name = $${i}`, vals);
   }
 
-  // ── Verifier results ──────────────────────────────────────────────────
-
-  async insertVerifierResult(row) {
-    const { rows } = await this._pool.query(
-      `INSERT INTO verifier_results
-         (session_id, tool_name, verifier_name, outcome, message, tool_call_input, tool_call_output, created_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8) RETURNING id`,
-      [
-        row.session_id ?? null, row.tool_name, row.verifier_name, row.outcome,
-        row.message ?? null, row.tool_call_input ?? null, row.tool_call_output ?? null,
-        new Date().toISOString()
-      ]
-    );
-    return rows[0]?.id ?? null;
-  }
 }
 
 // ── PostgresPromptStore ────────────────────────────────────────────────────
@@ -611,6 +619,14 @@ export class PostgresEvalStore {
     );
     return rows;
   }
+
+  async listRuns(limit = 50, offset = 0) {
+    const { rows } = await this._pool.query(
+      `SELECT * FROM eval_runs ORDER BY run_at DESC LIMIT $1 OFFSET $2`,
+      [limit, offset]
+    );
+    return rows;
+  }
 }
 
 // ── PostgresChatAuditStore ─────────────────────────────────────────────────
@@ -636,6 +652,35 @@ export class PostgresChatAuditStore {
     );
     return rows[0]?.id ?? null;
   }
+
+  async getStats() {
+    const { rows } = await this._pool.query(`
+      SELECT
+        COALESCE(COUNT(*), 0) AS total_sessions,
+        COALESCE(AVG(duration_ms), 0) AS avg_duration_ms,
+        COALESCE(
+          COUNT(*) FILTER (WHERE status_code >= 400)::float / NULLIF(COUNT(*), 0),
+          0
+        ) AS error_rate,
+        COALESCE(COUNT(*) FILTER (WHERE created_at >= NOW() - INTERVAL '24 hours'), 0) AS messages_today
+      FROM chat_audit
+    `);
+    const row = rows[0] ?? {};
+    return {
+      totalSessions: parseInt(row.total_sessions ?? '0', 10),
+      avgDurationMs: Math.round(parseFloat(row.avg_duration_ms ?? '0')),
+      errorRate: parseFloat(row.error_rate ?? '0'),
+      messagesToday: parseInt(row.messages_today ?? '0', 10)
+    };
+  }
+
+  async getSessions(limit = 20, offset = 0) {
+    const { rows } = await this._pool.query(
+      `SELECT * FROM chat_audit ORDER BY created_at DESC LIMIT $1 OFFSET $2`,
+      [limit, offset]
+    );
+    return rows;
+  }
 }
 
 // ── PostgresVerifierStore ──────────────────────────────────────────────────
@@ -724,4 +769,31 @@ export class PostgresVerifierStore {
       `SELECT * FROM verifier_tool_bindings WHERE verifier_name = $1`, [verifierName]);
     return rows;
   }
+
+  async insertVerifierResult(row) {
+    const { rows } = await this._pool.query(
+      `INSERT INTO verifier_results
+         (session_id, tool_name, verifier_name, outcome, message, tool_call_input, tool_call_output, created_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8) RETURNING id`,
+      [row.session_id ?? null, row.tool_name, row.verifier_name, row.outcome,
+       row.message ?? null, row.tool_call_input ?? null, row.tool_call_output ?? null,
+       new Date().toISOString()]
+    );
+    return rows[0]?.id ?? null;
+  }
+
+  async getResults(toolName = null, limit = 100) {
+    if (toolName) {
+      const { rows } = await this._pool.query(
+        `SELECT * FROM verifier_results WHERE tool_name = $1 ORDER BY created_at DESC LIMIT $2`,
+        [toolName, limit]
+      );
+      return rows;
+    }
+    const { rows } = await this._pool.query(
+      `SELECT * FROM verifier_results ORDER BY created_at DESC LIMIT $1`,
+      [limit]
+    );
+    return rows;
+  }
 }

package/lib/rate-limiter.d.ts

@@ -7,8 +7,9 @@ export interface RateLimitResult {
 /**
  * Fixed-window per-user per-route rate limiter.
  *
- * Backend is selected automatically:
- * - Redis — if a Redis client is provided (uses INCR + EXPIRE per window key)
+ * Backend is selected automatically by `makeRateLimiter`:
+ * - Redis — if a Redis client is provided
+ * - Postgres — if a pg.Pool is provided as the third argument
  * - Memory — in-process Map fallback, resets on window boundary
  *
  * Only counts authenticated requests — limits by `userId`, not IP.
@@ -24,7 +25,23 @@ export class RateLimiter {
 }
 
 /**
- * Factory — creates a RateLimiter from forge config.
+ * Postgres-backed rate limiter. Uses an atomic `INSERT … ON CONFLICT DO UPDATE`
+ * on the `rate_limit_buckets` table for horizontal-scale durability.
+ */
+export class PostgresRateLimiter {
+  constructor(config?: object, pgPool?: object | null);
+
+  /**
+   * Check whether a request is within the rate limit and increment the counter.
+   * Always returns `{ allowed: true }` when rate limiting is disabled.
+   * Rejects if the database is unavailable.
+   */
+  check(userId: string, route: string): Promise<RateLimitResult>;
+}
+
+/**
+ * Factory — creates a rate limiter from forge config.
  * Reads `config.rateLimit` for `enabled`, `windowMs`, and `maxRequests`.
+ * Priority: Redis > Postgres > in-memory.
  */
-export function makeRateLimiter(config: object, redis?: object | null): RateLimiter;
+export function makeRateLimiter(config: object, redis?: object | null, pgPool?: object | null): RateLimiter | PostgresRateLimiter;

package/lib/rate-limiter.js

@@ -97,14 +97,78 @@ export class RateLimiter {
   }
 }
 
+/**
+ * Postgres-backed fixed-window rate limiter.
+ * Uses an atomic INSERT ... ON CONFLICT DO UPDATE to count requests.
+ * Requires the rate_limit_buckets table (created by postgres-store.js SCHEMA).
+ *
+ * @param {object} config — forge rateLimit config block
+ * @param {object} pgPool — pg.Pool instance
+ */
+export class PostgresRateLimiter {
+  constructor(config = {}, pgPool) {
+    this._enabled = config.enabled ?? false;
+    this._windowMs = config.windowMs ?? 60_000;
+    this._maxRequests = config.maxRequests ?? 60;
+    this._pgPool = pgPool;
+    // Cleanup stale windows every 5 minutes
+    if (this._enabled) {
+      this._cleanupTimer = setInterval(async () => {
+        const cutoff = Math.floor(Date.now() / this._windowMs) * this._windowMs - this._windowMs;
+        try {
+          await this._pgPool.query(
+            'DELETE FROM rate_limit_buckets WHERE window_start < $1', [cutoff]);
+        } catch { /* non-fatal */ }
+      }, 5 * 60 * 1000).unref();
+    }
+  }
+
+  async check(userId, route) {
+    if (!this._enabled) return { allowed: true };
+    if (!userId || !route) return { allowed: true };
+
+    const windowMs = this._windowMs;
+    const maxRequests = this._maxRequests;
+    const now = Date.now();
+    const windowStart = Math.floor(now / windowMs) * windowMs;
+    const key = `\x00${userId}\x00${route}`;
+
+    let rows;
+    try {
+      ({ rows } = await this._pgPool.query(
+        `INSERT INTO rate_limit_buckets (key, window_start, count)
+         VALUES ($1, $2, 1)
+         ON CONFLICT (key, window_start) DO UPDATE
+           SET count = rate_limit_buckets.count + 1
+         RETURNING count`,
+        [key, windowStart]
+      ));
+    } catch (err) {
+      console.error('[forge-rate-limiter] pgPool.query failed:', err.message ?? err);
+      return { allowed: true }; // fail open on DB error
+    }
+    const count = rows[0]?.count ?? 1;
+    if (count > maxRequests) {
+      const retryAfter = Math.max(1, Math.ceil((windowStart + windowMs - now) / 1000));
+      return { allowed: false, retryAfter };
+    }
+    return { allowed: true };
+  }
+}
+
 /**
  * Factory — creates a RateLimiter from forge config.
  * Auto-passes Redis client if available (set by buildSidecarContext).
  *
  * @param {object} config — merged forge config
  * @param {object} [redis] — optional Redis client
- * @returns {RateLimiter}
+ * @param {object} [pgPool] — optional pg.Pool instance
+ * @returns {RateLimiter|PostgresRateLimiter}
  */
-export function makeRateLimiter(config, redis = null) {
-  return new RateLimiter(config.rateLimit ?? {}, redis);
+export function makeRateLimiter(config, redis = null, pgPool = null) {
+  const rlConfig = config.rateLimit ?? {};
+  if (!redis && pgPool) {
+    return new PostgresRateLimiter(rlConfig, pgPool);
+  }
+  return new RateLimiter(rlConfig, redis);
 }

package/lib/sidecar.d.ts

@@ -12,6 +12,7 @@ export interface SidecarOptions {
   autoListen?: boolean;
   enableDrift?: boolean;
   widgetDir?: string;
+  customRoutes?: (req: object, res: object, ctx: SidecarContext) => Promise<boolean> | boolean;
 }
 
 export interface SidecarContext {
@@ -27,6 +28,11 @@ export interface SidecarContext {
   config: SidecarConfig;
   env: Record<string, string>;
   configPath?: string;
+  evalStore: object | null;
+  chatAuditStore: object | null;
+  verifierStore: object | null;
+  pgStore: object | null;
+  _pgPool: object | null;
   [key: string]: unknown;
 }
 

package/lib/sidecar.js

@@ -29,6 +29,8 @@ import { createDriftMonitor } from './drift-background.js';
  * @param {boolean} [options.autoListen=true] — start listening immediately
  * @param {boolean} [options.enableDrift=false] — start background drift monitor
  * @param {string} [options.widgetDir] — custom widget directory
+ * @param {function} [options.customRoutes] — async (req, res, ctx) => boolean; inject custom routes
+ *   before the built-in 404 handler. Return true if the request was handled, false to fall through.
  * @returns {Promise<{ server: import('http').Server, ctx: object, close: () => void }>}
  */
 export async function createSidecar(config = {}, options = {}) {
@@ -40,6 +42,7 @@ export async function createSidecar(config = {}, options = {}) {
     autoListen = true,
     enableDrift = false,
     widgetDir,
+    customRoutes,
   } = options;
 
   // Merge defaults first so validateConfig sees a fully-populated object (M1).
@@ -69,15 +72,19 @@ export async function createSidecar(config = {}, options = {}) {
   // Build request handler
   const routerOpts = {};
   if (widgetDir) routerOpts.widgetDir = widgetDir;
+  if (customRoutes) routerOpts.customRoutes = customRoutes;
   const router = createSidecarRouter(ctx, routerOpts);
 
   // Create HTTP server
   const server = createHttpServer(router);
 
-  // Optional drift monitor
+  // Optional drift monitor — passes Postgres context when available
   let driftMonitor = null;
   if (enableDrift) {
-    driftMonitor = createDriftMonitor(merged, db);
+    const pgCtx = (ctx._pgPool && ctx.pgStore && ctx.evalStore)
+      ? { pgStore: ctx.pgStore, evalStore: ctx.evalStore, _pgPool: ctx._pgPool }
+      : null;
+    driftMonitor = createDriftMonitor(merged, db, undefined, pgCtx);
     driftMonitor.start();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tool-forge",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "description": "Production LLM agent sidecar + Claude Code skill library for building, testing, and running tool-calling agents.",
   "keywords": [
     "llm",