agent-tool-forge 0.4.5 → 0.4.7

package/README.md

@@ -40,10 +40,10 @@ See [docs/tui-workflow.md](docs/tui-workflow.md) for a start-to-finish walkthrou
 
 ```bash
 # Global install (available in all projects)
-cp -r tool-forge/skills/forge-tool     ~/.claude/skills/
-cp -r tool-forge/skills/forge-eval     ~/.claude/skills/
-cp -r tool-forge/skills/forge-mcp      ~/.claude/skills/
-cp -r tool-forge/skills/forge-verifier ~/.claude/skills/
+cp -r node_modules/agent-tool-forge/skills/forge-tool     ~/.claude/skills/
+cp -r node_modules/agent-tool-forge/skills/forge-eval     ~/.claude/skills/
+cp -r node_modules/agent-tool-forge/skills/forge-mcp      ~/.claude/skills/
+cp -r node_modules/agent-tool-forge/skills/forge-verifier ~/.claude/skills/
 ```
 
 Then in any Claude Code session:
@@ -123,23 +123,23 @@ All subpaths ship with TypeScript declarations.
 
 ```js
 import { createSidecar }      from 'agent-tool-forge'               // main entry
-import { reactLoop }           from 'tool-forge/react-engine'
-import { createAuth }          from 'tool-forge/auth'
-import { makeConversationStore } from 'tool-forge/conversation-store'
-import { mergeDefaults }       from 'tool-forge/config'
-import { makeHitlEngine }      from 'tool-forge/hitl-engine'
-import { makePromptStore }     from 'tool-forge/prompt-store'
-import { makePreferenceStore } from 'tool-forge/preference-store'
-import { makeRateLimiter }     from 'tool-forge/rate-limiter'
-import { getDb }               from 'tool-forge/db'
-import { initSSE }             from 'tool-forge/sse'
+import { reactLoop }           from 'agent-tool-forge/react-engine'
+import { createAuth }          from 'agent-tool-forge/auth'
+import { makeConversationStore } from 'agent-tool-forge/conversation-store'
+import { mergeDefaults }       from 'agent-tool-forge/config'
+import { makeHitlEngine }      from 'agent-tool-forge/hitl-engine'
+import { makePromptStore }     from 'agent-tool-forge/prompt-store'
+import { makePreferenceStore } from 'agent-tool-forge/preference-store'
+import { makeRateLimiter }     from 'agent-tool-forge/rate-limiter'
+import { getDb }               from 'agent-tool-forge/db'
+import { initSSE }             from 'agent-tool-forge/sse'
 import {
   PostgresStore,
   PostgresEvalStore,
   PostgresChatAuditStore,
   PostgresVerifierStore
-}                              from 'tool-forge/postgres-store'
-import { buildSidecarContext, createSidecarRouter } from 'tool-forge/forge-service'
+}                              from 'agent-tool-forge/postgres-store'
+import { buildSidecarContext, createSidecarRouter } from 'agent-tool-forge/forge-service'
 ```
 
 ---

package/config/api-endpoints.template.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "_comment": "Manual endpoint manifest. Add endpoints here when OpenAPI discovery is unavailable. Forge uses this to propose tools.",
+  "baseUrl": "${API_BASE_URL}",
+  "endpoints": [
+    {
+      "path": "/api/v1/example",
+      "method": "GET",
+      "name": "get_example",
+      "description": "Retrieves example data from the API. Use when the user asks for examples.",
+      "params": {
+        "id": { "type": "string", "description": "Optional filter by ID" }
+      },
+      "requiresConfirmation": false
+    }
+  ]
+}

package/config/forge.config.template.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "_comment": "Optional configuration that front-loads answers to common skill questions. Delete fields you don't need — all are optional. The skills work via dialogue alone without this file.",
+
+  "project": {
+    "name": "my-project",
+    "toolsDir": "src/tools",
+    "testsDir": "src/tools/__tests__",
+    "evalsDir": "evals/dataset",
+    "barrelsFile": "src/tools/tools.exports.ts"
+  },
+
+  "api": {
+    "baseUrl": "http://localhost:3000",
+    "_baseUrlComment": "Base URL for MCP tool routing. Tool mcpRouting.endpoint paths are appended to this.",
+    "discovery": {
+      "type": "openapi",
+      "url": "http://localhost:3333/api-json",
+      "_comment": "Or file: { \"type\": \"openapi\", \"file\": \"openapi.json\" }"
+    },
+    "manifestPath": "api-endpoints.json"
+  },
+
+  "language": "typescript",
+
+  "validation": {
+    "library": "zod",
+    "_alternatives": ["pydantic", "joi", "json-schema", "struct-tags"]
+  },
+
+  "testing": {
+    "framework": "jest",
+    "_alternatives": ["vitest", "pytest", "go-test", "mocha"],
+    "command": "npx jest --passWithNoTests"
+  },
+
+  "typeCheck": {
+    "command": "npx tsc --noEmit",
+    "_comment": "Set to null if your stack doesn't have a type checker"
+  },
+
+  "auth": {
+    "contextField": "context.auth",
+    "type": "jwt",
+    "_alternatives": ["api-key", "oauth", "service-account"]
+  },
+
+  "client": {
+    "contextField": "context.client",
+    "type": "http",
+    "_comment": "The API client your tools use. Could be HTTP, gRPC, SDK wrapper, etc."
+  },
+
+  "hitl": {
+    "enabled": false,
+    "framework": null,
+    "_comment": "Set to true and specify framework (e.g., 'langgraph') if you use human-in-the-loop confirmation for write tools"
+  },
+
+  "mcp": {
+    "defaultTransport": "stdio",
+    "_alternatives": ["streamable-http"],
+    "serverPrefix": "my-project",
+    "_comment": "Used by /forge-mcp to name the generated MCP server"
+  },
+
+  "evals": {
+    "goldenDir": "evals/dataset/golden",
+    "labeledDir": "evals/dataset/labeled",
+    "overlapMapFile": "evals/tool-overlap-map.json",
+    "seedManifestFile": "evals/seed-manifest.json",
+    "_comment": "Paths are relative to project root",
+    "defaultMix": {
+      "golden": { "total": 10 },
+      "labeled": { "straightforward": 3, "ambiguous": 3, "edge": 2, "adversarial": 2 }
+    },
+    "multiPass": { "passes": 3 },
+    "randomSample": { "aggression": "standard" }
+  },
+  "drift": {
+    "threshold": 0.1,
+    "windowSize": 5
+  },
+  "modelMatrix": [],
+  "_modelMatrixComment": "Add model names to compare during eval runs, e.g. ['gpt-4o-mini', 'gemini-2.0-flash', 'claude-haiku-4-5-20251001']",
+  "costs": {
+    "claude-haiku-4-5-20251001":  { "input": 0.80,  "output": 4.00  },
+    "claude-sonnet-4-6":          { "input": 3.00,  "output": 15.00 },
+    "claude-opus-4-6":            { "input": 15.00, "output": 75.00 },
+    "gpt-4o":                     { "input": 2.50,  "output": 10.00 },
+    "gpt-4o-mini":                { "input": 0.15,  "output": 0.60  },
+    "o1":                         { "input": 15.00, "output": 60.00 },
+    "o3-mini":                    { "input": 1.10,  "output": 4.40  },
+    "gemini-2.0-flash":           { "input": 0.10,  "output": 0.40  },
+    "gemini-2.5-pro-exp":         { "input": 1.25,  "output": 10.00 },
+    "deepseek-chat":              { "input": 0.27,  "output": 1.10  }
+  },
+
+  "verification": {
+    "enabled": true,
+    "verifiersDir": "src/verification",
+    "barrelsFile": "src/verification/verifiers.exports.ts",
+    "orderPrefix": "A-",
+    "_comment": "Order categories: A=attribution, C=compliance, I=interface, R=risk, U=uncertainty"
+  }
+}

package/lib/auth.d.ts

@@ -6,9 +6,11 @@ export interface AuthResult {
 }
 
 export interface AuthConfig {
-  mode?: 'trust' | 'verify';
+  mode?: 'trust' | 'verify' | 'none';
   signingKey?: string;
   claimsPath?: string;
+  adminToken?: string | null;
+  metricsToken?: string | null;
 }
 
 export interface Authenticator {
@@ -22,4 +24,9 @@ export interface AdminAuthResult {
   error: string | null;
 }
 
-export function authenticateAdmin(req: object, adminKey: string): AdminAuthResult;
+export function authenticateAdmin(req: object, adminKey: string | null): AdminAuthResult;
+
+export function resolveSecret(
+  value: string | null | undefined,
+  env?: Record<string, string>
+): string | null;

package/lib/auth.js

@@ -130,6 +130,21 @@ export function authenticateAdmin(req, adminKey) {
   return { authenticated: true, error: null };
 }
 
+/**
+ * Resolve a secret value, expanding ${VAR} references against the given env object.
+ * @param {string|null|undefined} value
+ * @param {Record<string, string>} [env]
+ * @returns {string|null}
+ */
+export function resolveSecret(value, env = {}) {
+  if (typeof value !== 'string' || !value) return null;
+  const e = env ?? {};
+  if (value.startsWith('${') && value.endsWith('}')) {
+    return e[value.slice(2, -1)] ?? null;
+  }
+  return value;
+}
+
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
 function base64UrlDecode(str) {

package/lib/config-schema.js

@@ -6,7 +6,7 @@
  */
 
 export const CONFIG_DEFAULTS = {
-  auth: { mode: 'trust', signingKey: null, claimsPath: 'sub' },
+  auth: { mode: 'trust', signingKey: null, claimsPath: 'sub', adminToken: null, metricsToken: null },
   defaultModel: 'claude-sonnet-4-6',
   defaultHitlLevel: 'cautious',
   allowUserModelSelect: false,
@@ -14,7 +14,7 @@ export const CONFIG_DEFAULTS = {
   adminKey: null,
   database: { type: 'sqlite', url: null },
   conversation: { store: 'sqlite', window: 25, redis: {} },
-  sidecar: { enabled: false, port: 8001 },
+  sidecar: { port: 8001 },  // port: used in direct-run mode only (node lib/forge-service.js)
   agents: [],
   rateLimit: {
     enabled: false,
@@ -47,7 +47,7 @@ export const CONFIG_DEFAULTS = {
   }
 };
 
-const VALID_AUTH_MODES = ['verify', 'trust'];
+const VALID_AUTH_MODES = ['verify', 'trust', 'none'];
 const VALID_HITL_LEVELS = ['autonomous', 'cautious', 'standard', 'paranoid'];
 const VALID_STORE_TYPES = ['sqlite', 'redis', 'postgres'];
 const VALID_DB_TYPES = ['sqlite', 'postgres'];

package/lib/config.d.ts

@@ -23,9 +23,13 @@ export interface DatabaseConfig {
 }
 
 export interface AuthConfig {
-  mode?: 'trust' | 'verify';
-  signingKey?: string;
+  mode?: 'trust' | 'verify' | 'none';
+  signingKey?: string | null;
   claimsPath?: string;
+  /** Admin Bearer token. Replaces top-level `adminKey`. Supports `${VAR}` env references. */
+  adminToken?: string | null;
+  /** Metrics scrape token for /metrics. Supports `${VAR}` env references. */
+  metricsToken?: string | null;
 }
 
 export interface AgentConfig {
@@ -43,6 +47,26 @@ export interface AgentConfig {
   enabled?: number;
 }
 
+export interface AgentRouterConfig {
+  endpoint?: string | null;
+  method?: string;
+  headers?: Record<string, string>;
+  inputField?: string;
+  outputField?: string;
+  sessionField?: string;
+}
+
+export interface GatesConfig {
+  passRate?: number | null;
+  maxCost?: number | null;
+  p95LatencyMs?: number | null;
+}
+
+export interface FixturesConfig {
+  dir?: string;
+  ttlDays?: number;
+}
+
 export interface SidecarConfig {
   auth?: AuthConfig;
   defaultModel?: string;
@@ -50,14 +74,19 @@ export interface SidecarConfig {
   allowUserModelSelect?: boolean;
   allowUserHitlConfig?: boolean;
   systemPrompt?: string;
-  adminKey?: string;
+  /** @deprecated Use `auth.adminToken` instead. */
+  adminKey?: string | null;
   conversation?: ConversationConfig;
   rateLimit?: RateLimitConfig;
   verification?: VerificationConfig;
   database?: DatabaseConfig;
-  sidecar?: { enabled?: boolean; port?: number };
+  /** `port` is used in direct-run mode only (`node lib/forge-service.js`). `createSidecar()` uses `SidecarOptions.port`. */
+  sidecar?: { port?: number };
   agents?: AgentConfig[];
   costs?: Record<string, { input: number; output: number }>;
+  agent?: AgentRouterConfig;
+  gates?: GatesConfig;
+  fixtures?: FixturesConfig;
 }
 
 export const CONFIG_DEFAULTS: SidecarConfig;

package/lib/forge-service.js

@@ -28,7 +28,7 @@ import { getDb } from './db.js';
 import { createMcpServer } from './mcp-server.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { mergeDefaults } from './config-schema.js';
-import { createAuth } from './auth.js';
+import { createAuth, resolveSecret, authenticateAdmin } from './auth.js';
 import { makePromptStore } from './prompt-store.js';
 import { makePreferenceStore } from './preference-store.js';
 import { makeConversationStore } from './conversation-store.js';
@@ -67,7 +67,14 @@ const PROJECT_ROOT = resolve(__dirname, '..');
  * @returns {Promise<{ auth, promptStore, preferenceStore, conversationStore, hitlEngine, verifierRunner, agentRegistry, db, config, env, rateLimiter, configPath, evalStore, chatAuditStore, verifierStore, pgStore, _redisClient, _pgPool }>}
  */
 export async function buildSidecarContext(config, db, env = {}, opts = {}) {
-  const auth = createAuth(config.auth);
+  // Resolve ${VAR} references in auth token fields at startup, not per-request
+  const resolvedAuth = config.auth ? {
+    ...config.auth,
+    signingKey: resolveSecret(config.auth.signingKey, env) ?? config.auth.signingKey ?? null,
+    adminToken: resolveSecret(config.auth.adminToken, env),
+    metricsToken: resolveSecret(config.auth.metricsToken, env),
+  } : config.auth;
+  const auth = createAuth(resolvedAuth);
 
   let redisClient = null;
   let pgPool = null;
@@ -103,6 +110,7 @@ export async function buildSidecarContext(config, db, env = {}, opts = {}) {
       idleTimeoutMillis: 30000,
       max: 10
     });
+    pgPool.on('error', err => process.stderr.write(`[forge] pg pool error: ${err.message}\n`));
     await pgPool.query(SCHEMA);  // ensure all tables exist
   }
 
@@ -142,9 +150,14 @@ export async function buildSidecarContext(config, db, env = {}, opts = {}) {
   // project directory, not into the installed package.
   const configPath = opts?.configPath ?? resolve(process.cwd(), 'forge.config.json');
 
+  // Return resolved auth config so applyRouteAuth sees literal tokens (not ${VAR})
+  const resolvedConfig = resolvedAuth !== config.auth
+    ? { ...config, auth: resolvedAuth }
+    : config;
+
   return {
     auth, promptStore, preferenceStore, conversationStore, hitlEngine, verifierRunner,
-    agentRegistry, db, config, env, rateLimiter, configPath,
+    agentRegistry, db, config: resolvedConfig, env, rateLimiter, configPath,
     evalStore, chatAuditStore, verifierStore, pgStore,
     _redisClient: redisClient, _pgPool: pgPool
   };
@@ -200,6 +213,53 @@ function serveWidgetFile(req, res, widgetDir, errorFn) {
   }
 }
 
+/**
+ * Determine the auth tier for a given request path.
+ * 0 = open, 1 = app (JWT), 2 = admin (Bearer token), 3 = scrape (metrics token)
+ * @param {string} path — normalized sidecarPath
+ * @returns {0|1|2|3}
+ */
+function getRouteTier(path) {
+  if (path === '/health') return 0;
+  if (path.startsWith('/forge-admin/') || path.startsWith('/agent-api/evals/')) return 2;
+  if (path === '/metrics') return 3;
+  return 1; // widget, mcp, agent-api/* → app tier
+}
+
+/**
+ * Apply tier-based auth to a request.
+ * @param {import('http').IncomingMessage} req
+ * @param {object} ctx — sidecar context
+ * @param {0|1|2|3} tier
+ * @returns {{ ok: boolean, status?: number, error?: string, userId?: string, claims?: object }}
+ */
+function applyRouteAuth(req, ctx, tier) {
+  const { config, env, auth } = ctx;
+  if (config?.auth?.mode === 'none') return { ok: true };
+  if (tier === 0) return { ok: true };
+
+  if (tier === 2) {
+    const token = resolveSecret(config?.auth?.adminToken, env)
+               ?? resolveSecret(config?.adminKey, env);
+    if (!token) return { ok: false, status: 503, error: 'Admin credentials not configured' };
+    const r = authenticateAdmin(req, token);
+    return r.authenticated ? { ok: true } : { ok: false, status: 401, error: r.error };
+  }
+
+  if (tier === 3) {
+    const token = resolveSecret(config?.auth?.metricsToken, env);
+    if (!token) return { ok: true }; // open when metricsToken not set
+    const r = authenticateAdmin(req, token);
+    return r.authenticated ? { ok: true } : { ok: false, status: 401, error: r.error };
+  }
+
+  // tier 1 — JWT
+  const r = auth.authenticate(req);
+  return r.authenticated
+    ? { ok: true, userId: r.userId, claims: r.claims }
+    : { ok: false, status: 401, error: r.error };
+}
+
 /**
  * Create an HTTP request handler for all sidecar routes.
  *
@@ -219,23 +279,31 @@ export function createSidecarRouter(ctx, options = {}) {
   return async (req, res) => {
     const url = new URL(req.url, 'http://localhost');
 
+    // ── Normalise /agent-api/v1/* → /agent-api/* ──────────────────────────
+    const sidecarPath = url.pathname.startsWith('/agent-api/v1/')
+      ? '/agent-api/' + url.pathname.slice('/agent-api/v1/'.length)
+      : url.pathname;
+
+    // ── Auth gate ──────────────────────────────────────────────────────────
+    const tier = getRouteTier(sidecarPath);
+    const authCheck = applyRouteAuth(req, ctx, tier);
+    if (!authCheck.ok) {
+      if (authCheck.status === 401) res.setHeader('WWW-Authenticate', 'Bearer');
+      return sendJson(res, authCheck.status, { error: authCheck.error });
+    }
+
     // ── /mcp route (optional) ──────────────────────────────────────────────
-    if (mcpHandler && url.pathname.startsWith('/mcp')) {
+    if (mcpHandler && sidecarPath.startsWith('/mcp')) {
       return mcpHandler(req, res);
     }
 
     // ── /health ────────────────────────────────────────────────────────────
-    if (req.method === 'GET' && url.pathname === '/health') {
+    if (req.method === 'GET' && sidecarPath === '/health') {
       sendJson(res, 200, { status: 'ok' });
       return;
     }
 
     // ── Sidecar API routes ─────────────────────────────────────────────────
-    // Normalise /agent-api/v1/* → /agent-api/* so versioned paths hit
-    // the same handlers without a proxy rewrite rule.
-    const sidecarPath = url.pathname.startsWith('/agent-api/v1/')
-      ? '/agent-api/' + url.pathname.slice('/agent-api/v1/'.length)
-      : url.pathname;
 
     if (sidecarPath === '/agent-api/chat' && req.method === 'POST') {
       return handleChat(req, res, ctx);
@@ -249,7 +317,8 @@ export function createSidecarRouter(ctx, options = {}) {
     if (sidecarPath === '/agent-api/user/preferences') {
       if (req.method === 'GET') return handleGetPreferences(req, res, ctx);
       if (req.method === 'PUT') return handlePutPreferences(req, res, ctx);
-      else { sendJson(res, 405, { error: 'Method not allowed' }); return; }
+      sendJson(res, 405, { error: 'Method not allowed' });
+      return;
     }
     if (sidecarPath.startsWith('/agent-api/conversations')) {
       return handleConversations(req, res, ctx);
@@ -319,8 +388,14 @@ export function createSidecarRouter(ctx, options = {}) {
 
     // ── Custom routes (consumer-provided) ─────────────────────────────────
     if (customRoutes) {
-      const handled = await customRoutes(req, res, ctx);
-      if (handled) return;
+      try {
+        const handled = await customRoutes(req, res, ctx);
+        if (handled) return;
+      } catch (err) {
+        process.stderr.write(`[forge] customRoutes error: ${err.message}\n`);
+        sendJson(res, 500, { error: 'Internal server error' });
+        return;
+      }
     }
 
     // ── 404 fallback ───────────────────────────────────────────────────────

package/lib/handlers/admin.js

@@ -4,13 +4,12 @@
  * PUT /forge-admin/config/:section — update a config section
  * GET /forge-admin/config          — read current effective config
  *
- * Protected by adminKey (Bearer token).
+ * Protected by router-level admin auth (tier 2 — see forge-service.js).
  * Runtime overlay: in-memory Map merged on top of file config.
  * NOT written back to forge.config.json.
  */
 
 import { readFileSync, writeFileSync, renameSync } from 'fs';
-import { authenticateAdmin } from '../auth.js';
 import { readBody, sendJson } from '../http-utils.js';
 
 const VALID_SECTIONS = ['model', 'hitl', 'permissions', 'conversation'];
@@ -24,18 +23,6 @@ const runtimeOverlay = new Map();
 export async function handleAdminConfig(req, res, ctx) {
   const url = new URL(req.url, 'http://localhost');
 
-  // Admin auth
-  const adminKey = ctx.config.adminKey;
-  if (!adminKey) {
-    sendJson(res, 503, { error: 'No adminKey configured' });
-    return;
-  }
-  const authResult = authenticateAdmin(req, adminKey);
-  if (!authResult.authenticated) {
-    sendJson(res, 403, { error: authResult.error ?? 'Forbidden' });
-    return;
-  }
-
   if (req.method === 'GET') {
     return handleAdminConfigGet(req, res, ctx);
   }

package/lib/handlers/agents.js

@@ -1,7 +1,7 @@
 /**
  * Admin Agent API — CRUD for multi-agent registry.
  *
- * All routes require adminKey (Bearer token).
+ * All routes protected by router-level admin auth (tier 2 — see forge-service.js).
  *
  * Routes:
  *   GET    /forge-admin/agents              — list all agents
@@ -12,7 +12,6 @@
  *   POST   /forge-admin/agents/:agentId/set-default — set default
  */
 
-import { authenticateAdmin } from '../auth.js';
 import { readBody, sendJson } from '../http-utils.js';
 
 const AGENT_ID_RE = /^[a-z0-9_-]{1,64}$/;
@@ -24,20 +23,7 @@ const VALID_HITL_LEVELS = new Set(['autonomous', 'cautious', 'standard', 'parano
  * @param {object} ctx — { config, agentRegistry }
  */
 export async function handleAgents(req, res, ctx) {
-  const { config, agentRegistry } = ctx;
-
-  // Admin auth
-  const adminKey = config.adminKey;
-  if (!adminKey) {
-    sendJson(res, 503, { error: 'No adminKey configured' });
-    return;
-  }
-  const authResult = authenticateAdmin(req, adminKey);
-  if (!authResult.authenticated) {
-    res.setHeader('WWW-Authenticate', 'Bearer');
-    sendJson(res, 401, { error: 'Unauthorized' });
-    return;
-  }
+  const { agentRegistry } = ctx;
 
   if (!agentRegistry) {
     sendJson(res, 501, { error: 'Agent registry not initialized' });

package/lib/hitl-engine.d.ts

@@ -37,9 +37,15 @@ export class HitlEngine {
 
   /**
    * Retrieve and consume the paused state for a resume token.
-   * Throws if the token has expired or does not exist.
+   * Returns null if the token has expired or does not exist (does not throw).
    */
-  resume(resumeToken: string): Promise<unknown>;
+  resume(resumeToken: string): Promise<unknown | null>;
+
+  /**
+   * Tear down any backend connections (Redis subscriber, Postgres pool, etc.).
+   * Call on graceful shutdown.
+   */
+  destroy(): Promise<void>;
 }
 
 /**

package/lib/sidecar.d.ts

@@ -44,9 +44,18 @@ export interface SidecarInstance {
 
 export function createSidecar(config?: Partial<SidecarConfig>, options?: SidecarOptions): Promise<SidecarInstance>;
 
+export interface SidecarRouterOptions {
+  /** Absolute path to serve static files from for /widget/* routes. Defaults to package widget/. */
+  widgetDir?: string;
+  /** Optional async handler for /mcp routes. */
+  mcpHandler?: (req: object, res: object) => Promise<void> | void;
+  /** Called before the 404 fallback. Return true if the request was handled. */
+  customRoutes?: (req: object, res: object, ctx: SidecarContext) => Promise<boolean> | boolean;
+}
+
 // Advanced consumers
-export function buildSidecarContext(config: SidecarConfig, db: object, env?: Record<string, string>, opts?: object): Promise<SidecarContext>;
-export function createSidecarRouter(ctx: SidecarContext, opts?: object): (req: object, res: object) => void;
+export function buildSidecarContext(config: SidecarConfig, db: object, env?: Record<string, string>, opts?: { configPath?: string }): Promise<SidecarContext>;
+export function createSidecarRouter(ctx: SidecarContext, opts?: SidecarRouterOptions): (req: object, res: object) => Promise<void>;
 
 export { createAuth } from './auth.js';
 export type { AuthResult, AuthConfig, Authenticator } from './auth.js';
@@ -82,7 +91,7 @@ export class AgentRegistry {
 }
 
 export class VerifierRunner {
-  constructor(db: object, config?: object, workerPool?: object);
+  constructor(db: object, config?: object, pgPool?: object | null, workerPool?: object | null);
   loadFromDb(db: object): Promise<void>;
   run(toolName: string, args: object, result: unknown): Promise<Array<{ outcome: 'pass' | 'warn' | 'block'; message: string | null; verifier: string }>>;
   destroy(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tool-forge",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Production LLM agent sidecar + Claude Code skill library for building, testing, and running tool-calling agents.",
   "keywords": [
     "llm",
@@ -29,6 +29,7 @@
   "files": [
     "lib",
     "widget",
+    "config",
     "!lib/**/*.test.js",
     "!lib/__fixtures__",
     "!widget/**/*.test.js"