agent-tool-forge 0.3.0

package/lib/runner/cli.js

@@ -0,0 +1,156 @@
+/**
+ * CLI handler for `node lib/index.js run`.
+ *
+ * Usage:
+ *   node lib/index.js run --eval <path> [--record] [--replay] [--suite <name>]
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runEvalSuite } from './index.js';
+
+function parseArgs(args) {
+  const opts = { record: false, replay: false, evalPath: null, suite: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--eval' && args[i + 1]) { opts.evalPath = args[++i]; continue; }
+    if (args[i] === '--record') { opts.record = true; continue; }
+    if (args[i] === '--replay') { opts.replay = true; continue; }
+    if (args[i] === '--suite' && args[i + 1]) { opts.suite = args[++i]; continue; }
+  }
+  return opts;
+}
+
+function loadConfig() {
+  const configPath = resolve(process.cwd(), 'forge.config.json');
+  if (!existsSync(configPath)) return {};
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    console.error(`Warning: forge.config.json is invalid JSON: ${err.message}`);
+    return {};
+  }
+}
+
+async function buildAgentFn(config) {
+  const agentConfig = config.agent ?? {};
+  const endpoint = agentConfig.endpoint;
+  if (!endpoint) {
+    throw new Error('No agent.endpoint configured in forge.config.json.\nAdd: { "agent": { "endpoint": "http://localhost:8001/agent-api/chat-sync" } }');
+  }
+
+  const method = agentConfig.method ?? 'POST';
+  const headers = { 'Content-Type': 'application/json', ...(agentConfig.headers ?? {}) };
+  const inputField = agentConfig.inputField ?? 'message';
+  const outputField = agentConfig.outputField ?? 'text';
+
+  return async (message) => {
+    const t0 = Date.now();
+    const body = JSON.stringify({ [inputField]: message });
+    let res;
+    try {
+      res = await fetch(endpoint, { method, headers, body });
+    } catch (err) {
+      throw new Error(`Agent request failed: ${err.message}`);
+    }
+    if (!res.ok) throw new Error(`Agent returned ${res.status}`);
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new Error(`Agent at ${endpoint} returned non-JSON response (status ${res.status})`);
+    }
+    const latencyMs = Date.now() - t0;
+    return {
+      responseText: data[outputField] ?? '',
+      toolsCalled: data.toolsCalled ?? [],
+      latencyMs,
+    };
+  };
+}
+
+export async function runCli(args) {
+  const opts = parseArgs(args);
+
+  if (!opts.evalPath) {
+    console.error('Usage: node lib/index.js run --eval <path> [--record] [--replay] [--suite <name>]');
+    process.exit(1);
+  }
+
+  const evalPath = resolve(process.cwd(), opts.evalPath);
+  if (!existsSync(evalPath)) {
+    console.error(`Eval file not found: ${evalPath}`);
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+  const gates = config.gates ?? {};
+  const fixturesDir = resolve(process.cwd(), config.fixtures?.dir ?? '.forge-fixtures');
+  const ttlDays = config.fixtures?.ttlDays ?? 30;
+
+  console.log(`\nRunning evals: ${opts.evalPath}`);
+  if (opts.record) console.log('  [record mode] Saving fixtures');
+  if (opts.replay) console.log('  [replay mode] Using cached fixtures where available');
+
+  let agentFn;
+  try {
+    agentFn = await buildAgentFn(config);
+  } catch (err) {
+    console.error(`\nConfiguration error: ${err.message}`);
+    process.exit(1);
+  }
+
+  let summary;
+  try {
+    summary = await runEvalSuite(evalPath, agentFn, {
+      record: opts.record,
+      replay: opts.replay,
+      fixturesDir,
+      ttlDays,
+      gates,
+      suiteName: opts.suite,
+    });
+  } catch (err) {
+    console.error(`\nEval run failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Print results
+  const { total, passed, failed, skipped, passRate, p95LatencyMs, totalCost, suiteName } = summary;
+  const ran = passed + failed;
+  const passRatePct = (passRate * 100).toFixed(1);
+  const icon = failed === 0 ? '✓' : '✗';
+
+  console.log(`\n${suiteName ? `[${suiteName}] ` : ''}${icon} ${passed}/${ran} passed (${passRatePct}%)` +
+    (skipped > 0 ? `, ${skipped} skipped` : '') +
+    (p95LatencyMs > 0 ? `, p95 latency: ${p95LatencyMs}ms` : '') +
+    (totalCost > 0 ? `, est. cost: $${totalCost.toFixed(6)}` : ''));
+
+  // Print failing cases (shown regardless of gate outcome)
+  const failures = summary.cases.filter(c => c.status === 'failed');
+  if (failures.length > 0) {
+    console.log('\nFailing cases:');
+    for (const f of failures) {
+      console.log(`  ✗ ${f.id ?? '(unnamed)'}: ${f.reason}`);
+    }
+  }
+
+  if (summary.gates) {
+    console.log('\nGate results:');
+    for (const r of summary.gates.results) {
+      const gateIcon = r.pass ? '  ✓' : '  ✗';
+      console.log(`${gateIcon} ${r.gate}: ${r.actual} (threshold: ${r.threshold})`);
+    }
+    if (!summary.gates.pass) {
+      console.log('\n✗ Gates failed — build should be blocked');
+      process.exit(1);
+    } else {
+      console.log('\n✓ All gates passed');
+    }
+  }
+
+  if (failures.length > 0) {
+    process.exit(1);
+  }
+
+  process.exit(0);
+}

package/lib/runner/cost-estimator.js

@@ -0,0 +1,71 @@
+// Adapted from agent-eval-kit by FlanaganSe (https://github.com/FlanaganSe/agent-eval-kit)
+// MIT License — see LICENSE
+
+/**
+ * Per-million-token costs for common models.
+ * Format: { input: $/M tokens, output: $/M tokens }
+ */
+const MODEL_COSTS = {
+  'claude-opus-4-6': { input: 15, output: 75 },
+  'claude-sonnet-4-6': { input: 3, output: 15 },
+  'claude-haiku-4-5-20251001': { input: 0.8, output: 4 },
+  'claude-3-5-sonnet-20241022': { input: 3, output: 15 },
+  'claude-3-5-haiku-20241022': { input: 0.8, output: 4 },
+  'claude-3-opus-20240229': { input: 15, output: 75 },
+  'gpt-4o': { input: 2.5, output: 10 },
+  'gpt-4o-mini': { input: 0.15, output: 0.6 },
+  'gemini-2.0-flash': { input: 0.1, output: 0.4 },
+  'gemini-1.5-pro': { input: 1.25, output: 5 },
+  'deepseek-chat': { input: 0.27, output: 1.1 },
+};
+
+/**
+ * Compute the actual cost of a single LLM call from observed token counts.
+ *
+ * @param {number} inputTokens
+ * @param {number} outputTokens
+ * @param {string} modelName
+ * @returns {number} cost in USD
+ */
+export function computeActualCost(inputTokens, outputTokens, modelName) {
+  const costs = MODEL_COSTS[modelName] ?? { input: 3, output: 15 };
+  return (inputTokens / 1_000_000) * costs.input + (outputTokens / 1_000_000) * costs.output;
+}
+
+/**
+ * Estimate the cost of running an eval suite.
+ * Assumes ~500 input tokens and ~200 output tokens per call (conservative estimate).
+ * @param {number} caseCount - number of eval cases
+ * @param {number} trialCount - number of trials per case
+ * @param {string} modelName - model name (used for cost lookup)
+ * @param {{avgInputTokens?: number, avgOutputTokens?: number}} [options]
+ * @returns {{totalCalls: number, estimatedCostUsd: number, perCallCostUsd: number, modelName: string, summary: string}}
+ */
+export function estimateCost(caseCount, trialCount, modelName, options = {}) {
+  const { avgInputTokens = 500, avgOutputTokens = 200 } = options;
+  const totalCalls = caseCount * trialCount;
+
+  const costs = MODEL_COSTS[modelName] ?? { input: 3, output: 15 }; // default to claude-sonnet-4-6 pricing
+
+  const inputCostPer1M = costs.input;
+  const outputCostPer1M = costs.output;
+
+  const totalInputTokens = totalCalls * avgInputTokens;
+  const totalOutputTokens = totalCalls * avgOutputTokens;
+
+  const estimatedCostUsd =
+    (totalInputTokens / 1_000_000) * inputCostPer1M +
+    (totalOutputTokens / 1_000_000) * outputCostPer1M;
+
+  const perCallCostUsd = totalCalls > 0 ? estimatedCostUsd / totalCalls : 0;
+
+  const summary = `${totalCalls} calls × ${modelName} ≈ $${estimatedCostUsd.toFixed(4)} USD (est. ${avgInputTokens}in/${avgOutputTokens}out tokens/call)`;
+
+  return {
+    totalCalls,
+    estimatedCostUsd,
+    perCallCostUsd,
+    modelName,
+    summary,
+  };
+}

package/lib/runner/gate.js

@@ -0,0 +1,46 @@
+// Adapted from agent-eval-kit by FlanaganSe (https://github.com/FlanaganSe/agent-eval-kit)
+// MIT License — see LICENSE
+
+/**
+ * Evaluate gate thresholds against a run summary.
+ *
+ * @param {{passRate: number, totalCost: number, p95LatencyMs: number, totalCases: number}} summary
+ * @param {{passRate?: number, maxCost?: number, p95LatencyMs?: number}} gates
+ * @returns {{pass: boolean, results: Array<{gate: string, threshold: number, actual: number, pass: boolean}>}}
+ */
+export function evaluateGates(summary, gates) {
+  const results = [];
+
+  if (gates.passRate !== undefined) {
+    const pass = summary.passRate >= gates.passRate;
+    results.push({
+      gate: 'passRate',
+      threshold: gates.passRate,
+      actual: summary.passRate,
+      pass,
+    });
+  }
+
+  if (gates.maxCost !== undefined) {
+    const pass = summary.totalCost <= gates.maxCost;
+    results.push({
+      gate: 'maxCost',
+      threshold: gates.maxCost,
+      actual: summary.totalCost,
+      pass,
+    });
+  }
+
+  if (gates.p95LatencyMs !== undefined) {
+    const pass = summary.p95LatencyMs <= gates.p95LatencyMs;
+    results.push({
+      gate: 'p95LatencyMs',
+      threshold: gates.p95LatencyMs,
+      actual: summary.p95LatencyMs,
+      pass,
+    });
+  }
+
+  const pass = results.length === 0 || results.every(r => r.pass);
+  return { pass, results };
+}

package/lib/runner/index.js

@@ -0,0 +1,165 @@
+/**
+ * Programmatic eval runner API.
+ *
+ * Usage:
+ *   import { runEvalSuite } from './lib/runner/index.js';
+ *   const summary = await runEvalSuite('./evals/my-tool.golden.json', async (message) => {
+ *     const res = await fetch('http://localhost:8001/agent-api/chat', { ... });
+ *     return { responseText: ..., toolsCalled: [], latencyMs: ... };
+ *   });
+ */
+
+import { readFile } from 'node:fs/promises';
+import { runChecks } from '../checks/run-checks.js';
+import { checkAdapter, checkResponseContainsAnyGroups, checkToolsAcceptable } from '../checks/check-adapter.js';
+import { evaluateGates } from './gate.js';
+import { writeFixture, readFixture, sortKeysDeep } from '../fixtures/fixture-store.js';
+
+/**
+ * Run an eval suite programmatically.
+ *
+ * @param {string} evalFilePath - path to eval JSON file
+ * @param {(message: string) => Promise<{responseText: string, toolsCalled: string[], latencyMs?: number, cost?: number}>} agentFn
+ * @param {{
+ *   record?: boolean,
+ *   replay?: boolean,
+ *   fixturesDir?: string,
+ *   ttlDays?: number,
+ *   gates?: {passRate?: number, maxCost?: number, p95LatencyMs?: number},
+ *   suiteName?: string,
+ * }} [opts]
+ * @returns {Promise<{total: number, passed: number, failed: number, skipped: number, passRate: number, cases: object[], gates?: object}>}
+ */
+export async function runEvalSuite(evalFilePath, agentFn, opts = {}) {
+  const { record = false, replay = false, fixturesDir = '.forge-fixtures', ttlDays = 30, gates = {}, suiteName } = opts;
+
+  // Load eval cases
+  let cases;
+  try {
+    const raw = await readFile(evalFilePath, 'utf8');
+    cases = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Failed to load eval file ${evalFilePath}: ${err.message}`);
+  }
+
+  if (!Array.isArray(cases)) {
+    throw new Error(`Eval file must contain a JSON array of cases`);
+  }
+
+  let passed = 0, failed = 0, skipped = 0;
+  const caseResults = [];
+  const allLatencies = [];
+  let totalCost = 0;
+
+  for (const evalCase of cases) {
+    const message = evalCase.input?.message ?? '';
+    if (!message) {
+      skipped++;
+      caseResults.push({ id: evalCase.id, status: 'skipped', reason: 'no input message' });
+      continue;
+    }
+
+    // Fixture replay
+    if (replay) {
+      const caseId = evalCase.id ?? message.slice(0, 40);
+      const configHash = JSON.stringify(sortKeysDeep(evalCase.expect ?? {}));
+      const hit = await readFixture(fixturesDir, caseId, configHash, { ttlDays });
+      if (hit.status === 'hit') {
+        const { responseText, toolsCalled } = hit.output;
+        const failures = checkCase(evalCase, { responseText, toolsCalled });
+        const casePassed = failures.length === 0;
+        if (casePassed) passed++; else failed++;
+        // Note: fixture hits do not contribute latency or cost — p95LatencyMs and totalCost
+        // reflect live-only cases. Latency/cost gates trivially pass on fully-cached runs.
+        caseResults.push({ id: evalCase.id, status: casePassed ? 'passed' : 'failed', reason: failures.join('; ') || null, fromFixture: true });
+        continue;
+      }
+    }
+
+    // Call agent
+    let result;
+    try {
+      result = await agentFn(message);
+    } catch (err) {
+      failed++;
+      caseResults.push({ id: evalCase.id, status: 'failed', reason: `Agent error: ${err.message}` });
+      continue;
+    }
+
+    const { responseText = '', toolsCalled = [], latencyMs, cost } = result;
+
+    // Record fixture
+    if (record) {
+      const caseId = evalCase.id ?? message.slice(0, 40);
+      const configHash = JSON.stringify(sortKeysDeep(evalCase.expect ?? {}));
+      await writeFixture(fixturesDir, caseId, configHash, { responseText, toolsCalled }).catch((err) => {
+        console.warn(`[forge] Failed to write fixture for case "${caseId}": ${err.message}`);
+      });
+    }
+
+    if (latencyMs !== undefined) allLatencies.push(latencyMs);
+    if (cost !== undefined) totalCost += cost;
+
+    const failures = checkCase(evalCase, { responseText, toolsCalled, latencyMs, cost });
+    const casePassed = failures.length === 0;
+    if (casePassed) passed++; else failed++;
+    caseResults.push({ id: evalCase.id, status: casePassed ? 'passed' : 'failed', reason: failures.join('; ') || null });
+  }
+
+  const total = cases.length;
+  const ran = passed + failed;
+  const passRate = ran > 0 ? passed / ran : 0;
+
+  // Compute p95 latency
+  const sortedLatencies = [...allLatencies].sort((a, b) => a - b);
+  const p95Index = Math.floor((sortedLatencies.length - 1) * 0.95);
+  const p95LatencyMs = sortedLatencies[p95Index] ?? 0;
+
+  const summary = { passRate, totalCost, p95LatencyMs, totalCases: total };
+
+  // Gate evaluation
+  let gateResult;
+  if (Object.keys(gates).some(k => gates[k] != null)) {
+    const activeGates = Object.fromEntries(Object.entries(gates).filter(([, v]) => v != null));
+    gateResult = evaluateGates(summary, activeGates);
+  }
+
+  return {
+    total,
+    passed,
+    failed,
+    skipped,
+    passRate,
+    p95LatencyMs,
+    totalCost,
+    cases: caseResults,
+    ...(suiteName ? { suiteName } : {}),
+    ...(gateResult ? { gates: gateResult } : {}),
+  };
+}
+
+/**
+ * Internal assertion runner for a single case.
+ * @param {object} evalCase
+ * @param {{responseText: string, toolsCalled: string[], latencyMs?: number, cost?: number}} meta
+ * @returns {string[]}
+ */
+function checkCase(evalCase, { responseText, toolsCalled, latencyMs, cost }) {
+  const failures = [];
+  const input = checkAdapter(evalCase, { toolsCalled, responseText, latencyMs, cost });
+  const result = runChecks(input);
+  for (const [checkName, checkResult] of Object.entries(result.checks)) {
+    if (!checkResult.pass) failures.push(checkResult.reason ?? `${checkName} failed`);
+  }
+
+  const expect = evalCase.expect ?? {};
+  if (expect.responseContainsAny?.length) {
+    const anyResult = checkResponseContainsAnyGroups(responseText, expect.responseContainsAny);
+    if (!anyResult.pass) failures.push(anyResult.reason);
+  }
+  if (expect.toolsAcceptable !== undefined) {
+    const acceptResult = checkToolsAcceptable(toolsCalled, expect.toolsAcceptable);
+    if (!acceptResult.pass) failures.push(acceptResult.reason);
+  }
+  return failures;
+}

package/lib/sidecar.d.ts

@@ -0,0 +1,83 @@
+import type { Server } from 'http';
+import type { SidecarConfig } from './config-schema.js';
+import type { AuthResult, AuthConfig, Authenticator } from './auth.js';
+import type { ConversationMessage, SessionSummary, ConversationStore } from './conversation-store.js';
+import type { ReactEvent, ReactLoopParams } from './react-engine.js';
+
+export interface SidecarOptions {
+  port?: number;
+  host?: string;
+  dbPath?: string;
+  env?: Record<string, string>;
+  autoListen?: boolean;
+  enableDrift?: boolean;
+  widgetDir?: string;
+}
+
+export interface SidecarContext {
+  auth: Authenticator;
+  promptStore: object;
+  preferenceStore: object;
+  conversationStore: ConversationStore;
+  agentRegistry: object;
+  verifierRunner: object | null;
+  hitlEngine: object | null;
+  rateLimiter: object | null;
+  db: object;
+  config: SidecarConfig;
+  env: Record<string, string>;
+  configPath?: string;
+  [key: string]: unknown;
+}
+
+export interface SidecarInstance {
+  server: Server;
+  ctx: SidecarContext;
+  close(): Promise<void>;
+}
+
+export function createSidecar(config?: Partial<SidecarConfig>, options?: SidecarOptions): Promise<SidecarInstance>;
+
+// 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 { createAuth } from './auth.js';
+export type { AuthResult, AuthConfig, Authenticator } from './auth.js';
+
+export { reactLoop } from './react-engine.js';
+export type { ReactEvent, ReactLoopParams, TextEvent, TextDeltaEvent, ToolCallEvent, ToolResultEvent, ToolWarningEvent, HitlEvent, ErrorEvent, DoneEvent } from './react-engine.js';
+
+export { mergeDefaults, validateConfig, CONFIG_DEFAULTS } from './config-schema.js';
+export type { SidecarConfig, AgentConfig, RateLimitConfig, VerificationConfig } from './config-schema.js';
+
+export { makeConversationStore } from './conversation-store.js';
+export type { ConversationMessage, SessionSummary, ConversationStore } from './conversation-store.js';
+
+export function getDb(path: string): object;
+export function initSSE(res: object): { write(event: string, data: unknown): void; close(): void };
+export function makePromptStore(config: object, db: object): object;
+export function makePreferenceStore(config: object, db: object): object;
+export function makeHitlEngine(config: object, db: object, redis?: object, pgPool?: object): object;
+export function makeAgentRegistry(config: object, db: object): object;
+
+export class AgentRegistry {
+  constructor(config: object, db: object);
+  resolveAgent(agentId: string | null): Promise<object | null>;
+  getAgent(agentId: string): Promise<object | null>;
+  getAllAgents(): Promise<object[]>;
+  upsertAgent(agent: object): Promise<void>;
+  setDefault(agentId: string): Promise<void>;
+  deleteAgent(agentId: string): Promise<void>;
+  seedFromConfig(): Promise<void>;
+  filterTools(tools: object[]): object[];
+  buildAgentConfig(config: object, agent: object | null): object;
+  resolveSystemPrompt(agent: object | null, promptStore: object, config: object): Promise<string>;
+}
+
+export class VerifierRunner {
+  constructor(db: object, config?: object, workerPool?: object);
+  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/lib/sidecar.js

@@ -0,0 +1,161 @@
+/**
+ * Sidecar — Library entry point for agent-tool-forge.
+ *
+ * Usage:
+ *   import { createSidecar } from 'agent-tool-forge';
+ *   const sidecar = await createSidecar({ ... }, { port: 8001 });
+ *   // sidecar.server, sidecar.ctx, sidecar.close()
+ *
+ * Advanced:
+ *   import { buildSidecarContext, createSidecarRouter, mergeDefaults, getDb } from 'agent-tool-forge';
+ */
+
+import { createServer as createHttpServer } from 'http';
+import { resolve } from 'path';
+import { getDb } from './db.js';
+import { mergeDefaults, validateConfig } from './config-schema.js';
+import { buildSidecarContext, createSidecarRouter } from './forge-service.js';
+import { createDriftMonitor } from './drift-background.js';
+
+/**
+ * Create a fully configured sidecar instance.
+ *
+ * @param {object} config — sidecar configuration (auth, agents, model, etc.)
+ * @param {object} [options]
+ * @param {number} [options.port=8001] — port to listen on
+ * @param {string} [options.host='0.0.0.0'] — bind address
+ * @param {string} [options.dbPath=':memory:'] — SQLite database path
+ * @param {Record<string, string>} [options.env] — environment variables (defaults to process.env)
+ * @param {boolean} [options.autoListen=true] — start listening immediately
+ * @param {boolean} [options.enableDrift=false] — start background drift monitor
+ * @param {string} [options.widgetDir] — custom widget directory
+ * @returns {Promise<{ server: import('http').Server, ctx: object, close: () => void }>}
+ */
+export async function createSidecar(config = {}, options = {}) {
+  const {
+    port = 8001,
+    host = '0.0.0.0',
+    dbPath = ':memory:',
+    env = process.env,
+    autoListen = true,
+    enableDrift = false,
+    widgetDir,
+  } = options;
+
+  // Merge defaults first so validateConfig sees a fully-populated object (M1).
+  // Validating the raw user config risks false positives on missing-but-defaulted
+  // fields (e.g. auth.mode absent in raw → would fail "must be one of" if
+  // validateConfig checked before defaults were applied).
+  const merged = mergeDefaults(config);
+  const { valid, errors } = validateConfig(merged);
+  if (!valid) {
+    throw new Error(`Invalid sidecar config: ${errors.join('; ')}`);
+  }
+
+  // Initialize database with WAL mode
+  const db = getDb(dbPath);
+  try {
+    db.pragma('journal_mode = WAL');
+  } catch {
+    // WAL not supported on all platforms — continue without it
+  }
+
+  // Build sidecar context (async — may create Redis/Postgres clients)
+  const ctx = await buildSidecarContext(merged, db, env);
+
+  // Seed agents from config
+  await ctx.agentRegistry.seedFromConfig();
+
+  // Build request handler
+  const routerOpts = {};
+  if (widgetDir) routerOpts.widgetDir = widgetDir;
+  const router = createSidecarRouter(ctx, routerOpts);
+
+  // Create HTTP server
+  const server = createHttpServer(router);
+
+  // Optional drift monitor
+  let driftMonitor = null;
+  if (enableDrift) {
+    driftMonitor = createDriftMonitor(merged, db);
+    driftMonitor.start();
+  }
+
+  // One-time guard to prevent double teardown if close() is called twice (M2).
+  let _closing = false;
+
+  // close() tears down everything cleanly
+  function close() {
+    if (_closing) return Promise.resolve();
+    _closing = true;
+
+    if (driftMonitor) {
+      driftMonitor.stop();
+      driftMonitor = null;
+    }
+
+    async function teardownConnections() {
+      try { if (ctx.verifierRunner?.destroy) ctx.verifierRunner.destroy(); } catch { /* ignore */ }
+      try { if (ctx._redisClient) await ctx._redisClient.quit(); } catch { /* ignore */ }
+      try { if (ctx._pgPool) await ctx._pgPool.end(); } catch { /* ignore */ }
+      try { db.close(); } catch { /* already closed */ }
+    }
+
+    return new Promise((res) => {
+      let resolved = false;
+      let t;
+      const finish = async () => {
+        if (resolved) return;
+        resolved = true;
+        clearTimeout(t);
+        await teardownConnections();
+        res();
+      };
+      server.close(() => finish());
+      // Force-resolve after 2s if connections linger — do NOT call process.exit()
+      // in a library module as it would kill the host application (M2).
+      t = setTimeout(async () => {
+        if (!resolved) {
+          console.error('[forge-sidecar] close() timed out after 2s — forcing resolve');
+          resolved = true;
+          clearTimeout(t);
+          await teardownConnections();
+          res();
+        }
+      }, 2000);
+      // Ensure the timeout doesn't keep the event loop alive if finish() runs first
+      if (t.unref) t.unref();
+    });
+  }
+
+  // Optionally start listening
+  if (autoListen) {
+    await new Promise((res, rej) => {
+      // Use once() so the error listener is removed after firing and doesn't
+      // become a ghost listener that fires on unrelated future errors.
+      server.once('error', rej);
+      server.listen(port, host, () => {
+        // Remove the one-time error listener if listen succeeded, so it doesn't
+        // linger as a ghost listener on the now-live server.
+        server.removeListener('error', rej);
+        res();
+      });
+    });
+  }
+
+  return { server, ctx, close };
+}
+
+// Re-exports for advanced consumers
+export { buildSidecarContext, createSidecarRouter } from './forge-service.js';
+export { createAuth } from './auth.js';
+export { reactLoop } from './react-engine.js';
+export { mergeDefaults, validateConfig, CONFIG_DEFAULTS } from './config-schema.js';
+export { getDb } from './db.js';
+export { initSSE } from './sse.js';
+export { VerifierRunner } from './verifier-runner.js';
+export { makePromptStore } from './prompt-store.js';
+export { makePreferenceStore } from './preference-store.js';
+export { makeConversationStore } from './conversation-store.js';
+export { makeHitlEngine } from './hitl-engine.js';
+export { makeAgentRegistry, AgentRegistry } from './agent-registry.js';