@mcp-abap-adt/llm-agent-server-libs 20.0.0 → 20.5.0

package/dist/smart-agent/smart-server.js

@@ -6,46 +6,28 @@ import http from 'node:http';
 import { createRequire } from 'node:module';
 import { resolve as pathResolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { AdapterValidationError, buildExternalResults, normalizeAndValidateExternalTools, QueryEmbedding, toToolCallDelta, } from '@mcp-abap-adt/llm-agent';
-import { ClaudeSkillManager, CodexSkillManager, ConfigWatcher, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, InMemoryKnowledgeBackend, KnowledgeRag, makeLlm, mergePluginExports, SessionGraphFactory, SessionLogger, SessionRegistry, SmartAgentBuilder, SmartAgentSubAgent, } from '@mcp-abap-adt/llm-agent-libs';
-import { MCPClientWrapper, McpClientAdapter, } from '@mcp-abap-adt/llm-agent-mcp';
+import { isReadinessReporter, } from '@mcp-abap-adt/llm-agent';
+import { ClaudeSkillManager, CodexSkillManager, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, InMemoryKnowledgeBackend, KnowledgeRag, makeLlm, mergePluginExports, SessionRequestLogger, SmartAgentBuilder, SmartAgentSubAgent, WindowContextStrategy, } from '@mcp-abap-adt/llm-agent-libs';
+import { DefaultMcpFailureClassifier, MCPClientWrapper, McpClientAdapter, } from '@mcp-abap-adt/llm-agent-mcp';
 import { makeRag, prefetchEmbedderFactories, resolveEmbedder, } from '@mcp-abap-adt/llm-agent-rag';
 import { PACKAGE_VERSION } from '../generated/version.js';
+import { ConfigReloadWatcher } from './config-reload-watcher.js';
+import { handleAdapterRequest } from './http/adapter-route-handler.js';
+import { handleChat } from './http/chat-route-handler.js';
+import { handleConfigUpdate, } from './http/config-route-handler.js';
+import { handleHealthRoute } from './http/health-route-handler.js';
+import { handleEmbeddingModelsList, handleModelsList, } from './http/models-route-handler.js';
+import { CORS_HEADERS, jsonError, writeNotReady, } from './http/response-helpers.js';
+import { HttpRouteTable } from './http/route-table.js';
+import { handleSessionDelete, handleSessionResume, handleSessionsList, } from './http/sessions-route-handler.js';
+import { handleUsageRoute } from './http/usage-route-handler.js';
+import { makeDefaultRoleLlm, RoleLlmResolver, } from './llm/role-llm-resolver.js';
 import { resolveAgentEmbedder } from './resolve-agent-embedder.js';
-import { resolveSessionIdentity } from './session-identity-resolver.js';
+import { makeToolsRagHandle } from './tools-rag-handle.js';
+export { writeNotReady } from './http/response-helpers.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function mapStopReason(r) {
-    if (r === 'stop')
-        return 'stop';
-    if (r === 'tool_calls')
-        return 'tool_calls';
-    return 'length';
-}
-function jsonError(message, type, code) {
-    return JSON.stringify({
-        error: { message, type, ...(code ? { code } : {}) },
-    });
-}
-function jsonValidationError(message, code, param) {
-    return JSON.stringify({
-        error: {
-            message,
-            type: 'invalid_request_error',
-            code,
-            param,
-        },
-    });
-}
-function readBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on('data', (c) => chunks.push(c));
-        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
-        req.on('error', reject);
-    });
-}
 function resolveSkillManager(cfg) {
     if (!cfg)
         return undefined;
@@ -62,11 +44,6 @@ function resolveSkillManager(cfg) {
             return undefined;
     }
 }
-const CORS_HEADERS = {
-    'Access-Control-Allow-Origin': '*',
-    'Access-Control-Allow-Methods': 'GET, POST, PUT, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-};
 // ---------------------------------------------------------------------------
 // SmartServer
 // ---------------------------------------------------------------------------
@@ -77,8 +54,7 @@ import { LinearPipelinePlugin } from '../pipelines/linear.js';
 import { createServerPipelineContext, } from '../pipelines/server-context.js';
 import { StepperPipelinePlugin } from '../pipelines/stepper.js';
 import { normalizeLlmConfig, resolveLlmConfig, resolveLlmConfigStrict, resolveToolSelectionStrategy, } from './config.js';
-import { makeKnowledgeSemanticIndex } from './embedder-knowledge-index.js';
-import { JsonlKnowledgeBackend } from './jsonl-knowledge-backend.js';
+import { makeKnowledgeBackend } from './knowledge/make-knowledge-backend.js';
 import { makePgPool, makePgReadPool } from './pg-pool.js';
 import { InMemorySessionMetaStore } from './session-meta-store.js';
 import { buildSkillHostFromConfig, initSkillHost, } from './skill-plugins-host-factory.js';
@@ -86,267 +62,18 @@ export { generateConfigTemplate, loadYamlConfig, resolveCoordinatorActivation, r
 export { makePgPool, makePgReadPool } from './pg-pool.js';
 export { parseSkillPluginsConfig, } from './skill-plugins-config.js';
 export { buildSkillHostFromConfig, initSkillHost, validateServedGroups, } from './skill-plugins-host-factory.js';
-/**
- * Drain every cached worker's `close` (if any), then clear the cache map.
- * Used by config-reload (PUT /v1/config + hot-reload — Fix #14/18/21) and by
- * server `close()` to release per-worker MCP connections that were attached
- * to the discarded `SmartAgentHandle`s.
- *
- * IMPORTANT — in-flight caveat: this aborts any request that is mid-call on
- * a worker's MCP client. That is acceptable for an admin action (config
- * reload, server shutdown) where the alternative is leaking connections.
- * Server `close()` calls this AFTER `lifecycle.disposeAll()` so per-session
- * graphs that reference worker clients are torn down first.
- *
- * Uses `Promise.allSettled` so one failing close cannot block the others.
- */
-export async function drainWorkerCache(cache) {
-    const closers = [];
-    for (const entry of cache.values()) {
-        if (entry.close) {
-            try {
-                closers.push(entry.close());
-            }
-            catch {
-                // sync throw (defensive — close is async by contract)
-            }
-        }
-    }
-    cache.clear();
-    if (closers.length > 0) {
-        await Promise.allSettled(closers);
-    }
-}
-/**
- * Build-once-per-worker resolver. The first time a worker name is seen, it
- * constructs the worker's main/classifier/(optional helper) LLM + embedder and
- * caches the set; every later call (e.g. each per-session worker re-wire)
- * returns the SAME set by reference — never reconstructing LLM clients
- * (locked invariant: LLM/embedder clients are global, built once).
- *
- * Accepts optional `makeToolsRag`/`makeHistoryRag`/`makeMcpClients` factories;
- * when provided, the resolver builds them ONCE on the first miss and caches
- * them on the returned set. Subsequent calls return the cached resources by
- * reference — never re-vectorizing or re-connecting MCP.
- */
-export async function resolveWorkerLlmSet(input) {
-    const hit = input.cache.get(input.name);
-    if (hit)
-        return hit;
-    const mainLlm = await input.makeMain();
-    const classifierLlm = await input.makeClassifier();
-    const helperLlm = input.makeHelper ? await input.makeHelper() : undefined;
-    const embedder = input.makeEmbedder ? await input.makeEmbedder() : undefined;
-    const toolsRag = input.makeToolsRag ? await input.makeToolsRag() : undefined;
-    const historyRag = input.makeHistoryRag
-        ? await input.makeHistoryRag()
-        : undefined;
-    const mcpClients = input.makeMcpClients
-        ? await input.makeMcpClients()
-        : undefined;
-    const set = {
-        mainLlm,
-        classifierLlm,
-        helperLlm,
-        embedder,
-        toolsRag,
-        historyRag,
-        mcpClients,
-    };
-    input.cache.set(input.name, set);
-    return set;
-}
-/**
- * Backfill the per-worker cache entry from the BUILT handle (review HIGH #7).
- *
- * The primary `buildSubAgent` populates `cached.mcpClients`/`toolsRag`/
- * `historyRag` only when the worker config provided DI factories. Workers
- * configured with `subCfg.mcp: ...` (regular config that triggers the
- * builder's own auto-connect) or with `subCfg.rag: ...` whose RAG is owned
- * by the builder leave those slots empty — so per-session re-wires would
- * fall back to the PARENT's MCP/RAG, losing the worker's own connection.
- *
- * After the builder finishes, this helper captures what the handle actually
- * holds and stores it BY REFERENCE on the cache entry. Subsequent per-session
- * re-wires read the same slots and find the worker's own resources.
- *
- * Pure helper, mutates `entry` in place. No-op when the corresponding slot
- * is already populated (DI path wins) or when the handle has no resource for
- * that slot (worker simply didn't declare one).
- */
-export async function backfillWorkerCacheFromHandle(entry, handle) {
-    if ((!entry.mcpClients || entry.mcpClients.length === 0) &&
-        handle.mcpClients &&
-        handle.mcpClients.length > 0) {
-        entry.mcpClients = handle.mcpClients;
-    }
-    if (!entry.toolsRag) {
-        const t = handle.ragRegistry.get('tools');
-        if (t)
-            entry.toolsRag = t;
-    }
-    if (!entry.historyRag) {
-        const h = handle.ragRegistry.get('history');
-        if (h)
-            entry.historyRag = h;
-    }
-    // Capture the per-worker shutdown function (Fix #21). If the entry already
-    // had a close from a previous build (e.g. the same worker name was rebuilt
-    // WITHOUT going through `drainWorkerCache` first — defence in depth), await
-    // the prior close before overwriting so its MCP connections do not leak.
-    if (handle.close) {
-        if (entry.close) {
-            try {
-                await entry.close();
-            }
-            catch {
-                // Best-effort; never block the new build on a stale close failure.
-            }
-        }
-        entry.close = handle.close;
-    }
-}
-/**
- * Share the parent RAG registry with subagents (per-session worker re-wire).
- * Session/user/global collections written at the top level become visible to
- * workers; the per-call scope filter (`rag-query.ts`) isolates by
- * `ctx.sessionId` / `ctx.options.userId`. A worker's own declared store is
- * registered INTO this same registry under its namespace. When the parent
- * registry is undefined (no top-level registry yet — e.g. unit test seam),
- * return undefined so the builder allocates its own SimpleRagRegistry.
- */
-export function resolveSubAgentRagRegistry(input) {
-    return input.parentRagRegistry;
-}
-/**
- * Composes the cookie identity resolver + SessionGraphFactory + SessionRegistry
- * into one lifecycle object the server's `_handle` consumes. The default MCP
- * factory returns the shared GLOBAL clients by reference (one upstream
- * connection); a creds-aware build swaps it out (out of scope here).
- */
-export function buildSessionLifecycle(opts) {
-    const factory = new SessionGraphFactory({
-        mcpClientFactory: (_identity) => opts.mcpClients,
-        toolsRag: opts.toolsRag,
-        ragRegistry: opts.ragRegistry,
-        buildAgent: opts.buildAgent,
-        logger: opts.logger,
-        onDispose: opts.onDispose,
-    });
-    const registry = new SessionRegistry({
-        idleTtlMs: opts.idleTtlMs,
-        maxSessions: opts.maxSessions,
-        factory,
-    });
-    return {
-        resolve: (cookieHeader, isHttps) => resolveSessionIdentity({
-            cookieHeader,
-            cookieName: opts.cookieName,
-            maxAgeSeconds: Math.max(1, Math.floor(opts.idleTtlMs / 1000)),
-            isHttps,
-        }),
-        acquire: (sessionId) => registry.acquire(sessionId),
-        release: (sessionId, graph) => registry.release(sessionId, graph),
-        evictIdle: () => registry.evictIdle(),
-        disposeAll: () => registry.disposeAll(),
-        invalidateAll: () => registry.invalidateAll(),
-        registry,
-    };
-}
-/**
- * Seed session-scope guidance entries into a BRAND-NEW session's knowledge-RAG
- * (deployment-supplied tool-usage guidance the planner/executor read in "Known
- * facts"). Idempotent: rehydrates via init() and writes ONLY when the session is
- * empty (`fingerprint() === 'n=0'`), so resumes never duplicate. Entries are
- * config DATA — the runtime stays MCP-agnostic (no tool knowledge in agent code).
- */
-export async function seedSessionKnowledge(kr, seeds, nowIso) {
-    if (seeds.length === 0)
-        return;
-    await kr.init?.();
-    if (kr.fingerprint?.() !== 'n=0')
-        return; // not a brand-new session → skip
-    for (const s of seeds) {
-        await kr.write({
-            content: s.content,
-            metadata: {
-                traceId: 'seed',
-                turnId: 'seed',
-                stepperId: 'seed',
-                task: 'session-seed',
-                artifactType: s.artifactType,
-                createdAt: nowIso,
-            },
-        });
-    }
-}
-/**
- * Record that a request for `sessionId` STARTED — create the meta row on first
- * sight, else touch it and mark in-progress. Called from the live request path
- * (`_withSession`) so GET /v1/sessions, resume and delete actually see sessions
- * produced by normal chat/stream traffic (review Finding 3). `userIdentity` is
- * the sessionId itself in the default no-auth build — matching how the
- * /v1/sessions endpoints resolve identity (`resolved.identity.sessionId`).
- */
-export async function recordSessionStart(store, sessionId, nowIso) {
-    const existing = await store.get(sessionId);
-    if (!existing) {
-        await store.create({
-            sessionId,
-            userIdentity: sessionId,
-            createdAt: nowIso,
-            lastUsedAt: nowIso,
-            status: 'in-progress',
-        });
-        return;
-    }
-    await store.touch(sessionId, nowIso);
-    await store.setStatus(sessionId, 'in-progress');
-}
-/**
- * Record that a request for `sessionId` FINISHED — touch + mark idle (so it can
- * be resumed). No-op if the row was deleted mid-flight.
- */
-export async function recordSessionEnd(store, sessionId, nowIso) {
-    const existing = await store.get(sessionId);
-    if (!existing)
-        return;
-    await store.touch(sessionId, nowIso);
-    await store.setStatus(sessionId, 'idle');
-}
-/**
- * List all sessions for a given user identity.
- * Extracted for unit-testability (mirrors the /v1/usage handler pattern).
- */
-export async function handleListSessions(store, identity) {
-    const sessions = await store.listForUser(identity);
-    return { sessions };
-}
-/**
- * Resume (claim) a session by ID for a user identity.
- * Sets the session status to 'idle' so it can be re-entered.
- */
-export async function handleResumeSession(store, identity, id) {
-    const row = await store.get(id);
-    if (!row || row.userIdentity !== identity) {
-        return { ok: false, error: 'session not found' };
-    }
-    await store.setStatus(id, 'idle');
-    const updated = await store.get(id);
-    return { ok: true, session: updated };
-}
-/**
- * Delete a session by ID for a user identity, and evict its RAG state.
- */
-export async function handleDeleteSession(store, identity, id, evictFn) {
-    const row = await store.get(id);
-    if (!row || row.userIdentity !== identity) {
-        return { ok: false, error: 'session not found' };
-    }
-    await store.delete(id);
-    await evictFn(id);
-    return { ok: true };
-}
+// ---------------------------------------------------------------------------
+// Worker-LLM cache + RAG-registry sharing (Task A7) — relocated to workers/
+// ---------------------------------------------------------------------------
+export { backfillWorkerCacheFromHandle, drainWorkerCache, resolveWorkerLlmSet, } from './workers/worker-registry.js';
+import { backfillWorkerCacheFromHandle, resolveWorkerLlmSet, WorkerRegistry, } from './workers/worker-registry.js';
+// ---------------------------------------------------------------------------
+// Session-lifecycle helpers — relocated to session-lifecycle/ (R3)
+// Internal callers (SmartServer methods) import the value symbols they call;
+// re-export the full public surface for the package barrel.
+// ---------------------------------------------------------------------------
+import { buildSessionLifecycle, recordSessionEnd, recordSessionStart, resolveSubAgentRagRegistry, seedSessionKnowledge, } from './session-lifecycle/index.js';
+export { buildSessionLifecycle, handleDeleteSession, handleListSessions, handleResumeSession, recordSessionEnd, recordSessionStart, resolveSubAgentRagRegistry, seedSessionKnowledge, } from './session-lifecycle/index.js';
 // ---------------------------------------------------------------------------
 // MCP bridge for the Stepper path (B-1)
 // ---------------------------------------------------------------------------
@@ -385,6 +112,8 @@ export async function connectMcpClientsFromConfig(mcpCfg) {
                 transport: 'stdio',
                 command: cfg.command,
                 args: cfg.args ?? [],
+                ...(cfg.timeout !== undefined ? { timeout: cfg.timeout } : {}),
+                ...(cfg.toolTimeouts ? { toolTimeouts: cfg.toolTimeouts } : {}),
             });
         }
         else {
@@ -392,6 +121,8 @@ export async function connectMcpClientsFromConfig(mcpCfg) {
                 transport: 'auto',
                 url: cfg.url,
                 headers: cfg.headers,
+                ...(cfg.timeout !== undefined ? { timeout: cfg.timeout } : {}),
+                ...(cfg.toolTimeouts ? { toolTimeouts: cfg.toolTimeouts } : {}),
             });
         }
         await wrapper.connect();
@@ -399,20 +130,33 @@ export async function connectMcpClientsFromConfig(mcpCfg) {
     }
     return connected;
 }
-export function buildMcpBridge(clients) {
-    return async (name, args, _signal) => {
+export function buildMcpBridge(clients, classifier = new DefaultMcpFailureClassifier()) {
+    return async (name, args, signal) => {
         const safeArgs = args != null && typeof args === 'object' && !Array.isArray(args)
             ? args
             : {};
+        const opts = signal ? { signal } : undefined;
         for (const client of clients) {
-            const listed = await client.listTools();
-            if (!listed.ok)
+            const probe = client.healthCheck
+                ? () => client.healthCheck(opts).then((r) => (r.ok ? r.value : false))
+                : undefined;
+            const listed = await client.listTools(opts);
+            if (!listed.ok) {
+                // FAIL LOUD on an availability failure: a transient listTools() outage must
+                // NOT make the tool look merely absent (→ "Tool not found"/tool-blind). A
+                // benign error (this client genuinely can't list) falls through to the next.
+                if ((await classifier.classify(listed.error, probe)) === 'unavailable')
+                    throw listed.error;
                 continue;
+            }
             const owns = listed.value.some((t) => t.name === name);
             if (!owns)
                 continue;
-            const result = await client.callTool(name, safeArgs);
+            const result = await client.callTool(name, safeArgs, opts);
             if (!result.ok) {
+                // Availability failure → fail loud; a tool-level error → LLM feedback text.
+                if ((await classifier.classify(result.error, probe)) === 'unavailable')
+                    throw result.error;
                 return result.error.message;
             }
             const { content } = result.value;
@@ -425,11 +169,17 @@ export class SmartServer {
     cfg;
     noop = () => { };
     /**
-     * GLOBAL per-worker LLM/embedder cache. Populated lazily by `buildSubAgent`
+     * GLOBAL per-worker LLM/embedder cache registry. Populated lazily by `buildSubAgent`
      * the first time each worker name is seen; subsequent per-session re-wires
-     * pull from this cache by reference (never reconstructing LLM clients).
+     * pull from the cache by reference (never reconstructing LLM clients).
+     * Constructed in `_buildInfra` after embedder factories are resolved.
+     */
+    _workers;
+    /**
+     * Declarative HTTP route table built once; `_handle` delegates to its
+     * `dispatch`. Replaces the former ~300-line if/else route chain.
      */
-    _workerLlmCache = new Map();
+    _routeTable = this._buildRouteTable();
     /** Lifecycle handle wired in `start()`; consumed by `_handle`. */
     _lifecycle;
     /** Hoisted globals used by `buildSessionAgent` to re-wire fresh per-session workers. */
@@ -464,6 +214,7 @@ export class SmartServer {
     _llmMap;
     _pipelineFallback;
     _mainTemp;
+    _roleLlm;
     _requestLogger;
     /** ToolsRag handle built by `buildSharedPipelineInfra`; handed to every
      *  pipeline's context (factory defaults to EMPTY_TOOLS_RAG if unset). */
@@ -486,6 +237,15 @@ export class SmartServer {
      * yaml). Disposed via the server's `closeFns` on shutdown.
      */
     _stepperMcpClients;
+    /**
+     * True when the consumer injected an MCP seam (`BuildAgentDeps.mcpClients` or
+     * `connectMcp`). In that case MCP is provisioned ONLY through the seam (the
+     * embeddable path must never force a real connect / builder self-connect). When
+     * false (default), the YAML `mcp:` path keeps the builder-owned connect so the
+     * builder VECTORIZES the tools into `toolsRag` (the ToolSelect ranking contract;
+     * see mcp-yaml-vectorization.test.ts).
+     */
+    _mcpSeamInjected;
     /**
      * The MCP clients the pipeline `callMcp` bridge dispatches over — resolved
      * UNCONDITIONALLY in `start()` as DI/plugin clients (`mcpClients`) ?? the
@@ -520,8 +280,50 @@ export class SmartServer {
      * handles owned by the plugin) are freed on eviction / shutdown / reconfigure.
      */
     _sessionCloseFns = new Map();
-    constructor(config) {
+    /**
+     * Instance-level MCP failure classifier (DI/programmatic only — not from YAML).
+     * Populated from BuildAgentDeps in the constructor; defaults to DefaultMcpFailureClassifier.
+     * Passed to buildMcpBridge (Route B) and threaded into every pipeline ctx (Route A).
+     */
+    _mcpFailureClassifier;
+    _toolLoopContextStrategyFactory;
+    _stepExecutionControl;
+    _runExecutionControl;
+    _auxiliaryMcpTools;
+    /**
+     * Defaulted construction deps (the BuildAgentDeps DI seam). Required members
+     * always resolve to the real implementation when not injected; `skillHost`
+     * and `embedder` stay optional (present only when injected).
+     */
+    _deps;
+    constructor(config, deps = {}) {
         this.cfg = config;
+        this._mcpSeamInjected =
+            deps.mcpClients !== undefined || deps.connectMcp !== undefined;
+        this._mcpFailureClassifier =
+            deps.mcpFailureClassifier ?? new DefaultMcpFailureClassifier();
+        // The DI seam carries the CONSUMER-injected factory ONLY (undefined when not
+        // injected). It is threaded verbatim onto the pipeline ctx so a consumer
+        // override wins on EVERY pipeline — including the controller, which resolves
+        // `ctx.toolLoopContextStrategyFactory ?? <its own RagRecall>`. The server's
+        // Window default for the NON-controller pipelines is applied ONLY on the
+        // builder channel (buildBaseBuilder), so it never leaks into the controller's
+        // ctx read. A bare library consumer of DefaultPipeline/SmartAgent (no
+        // SmartServer) still falls back to Legacy at point-of-use.
+        this._toolLoopContextStrategyFactory = deps.toolLoopContextStrategyFactory;
+        this._stepExecutionControl = deps.stepExecutionControl;
+        this._runExecutionControl = deps.runExecutionControl;
+        this._auxiliaryMcpTools = deps.auxiliaryMcpTools;
+        this._deps = {
+            makeLlm: deps.makeLlm ?? ((cfg) => this._makeLlmDefault(cfg)),
+            resolveEmbedder: deps.resolveEmbedder ?? resolveEmbedder,
+            prefetchEmbedderFactories: deps.prefetchEmbedderFactories ?? prefetchEmbedderFactories,
+            buildSkillHost: deps.buildSkillHost ?? buildSkillHostFromConfig,
+            connectMcp: deps.connectMcp ?? connectMcpClientsFromConfig,
+            ...(deps.skillHost ? { skillHost: deps.skillHost } : {}),
+            ...(deps.embedder ? { embedder: deps.embedder } : {}),
+            ...(deps.mcpClients ? { mcpClients: deps.mcpClients } : {}),
+        };
     }
     async start() {
         // Startup pg-pool cleanup must span the ENTIRE start(): host.load() (via
@@ -547,7 +349,17 @@ export class SmartServer {
             }
         }
     }
-    async _start() {
+    /**
+     * Assemble and return the server INFRA bundle ONLY — every shared resource
+     * needed by both the HTTP `_start()` path and the embeddable
+     * `_buildEmbeddedAgent()` path: the infra/passthrough `smartAgent`, the
+     * server-only locals (`chat`/`streamChat`/`requestLogger`/etc.), the resolved
+     * `globalMcpClients`/`globalRagRegistry`, and the `closeFns` loop (exposed as
+     * `close`). It does NOT build the `'embedded'` pipeline instance — that idle
+     * coordinator is built only on the embeddable path (see `_buildEmbeddedAgent`),
+     * so a plain `start()` no longer pays for a coordinator it never serves.
+     */
+    async _buildInfra() {
         const log = this.cfg.log ?? this.noop;
         const fileLogger = {
             log: (e) => log(e),
@@ -564,23 +376,13 @@ export class SmartServer {
         const topMain = resolveLlmConfig(llmMap, 'main', pipelineFallback);
         const mainTemp = Number(topMain?.temperature ?? 0.7);
         const mainLlm = topMain
-            ? await makeLlm({
-                provider: topMain.provider ?? 'deepseek',
-                apiKey: topMain.apiKey,
-                baseURL: topMain.url,
-                model: topMain.model,
-            }, mainTemp)
+            ? await this._deps.makeLlm({ ...topMain, temperature: mainTemp })
             : (() => {
                 throw new Error('no LLM configured: provide top-level llm.main');
             })();
         const classifierTemp = Number(topMain?.classifierTemperature ?? 0.1);
         const classifierLlm = topMain
-            ? await makeLlm({
-                provider: topMain.provider ?? 'deepseek',
-                apiKey: topMain.apiKey,
-                baseURL: topMain.url,
-                model: topMain.model,
-            }, classifierTemp)
+            ? await this._deps.makeLlm({ ...topMain, temperature: classifierTemp })
             : (() => {
                 throw new Error('no LLM configured: provide top-level llm.main');
             })();
@@ -588,12 +390,10 @@ export class SmartServer {
         // (built only when an explicit map entry exists).
         const helperCfg = resolveLlmConfigStrict(llmMap, 'helper');
         const helperLlm = helperCfg
-            ? await makeLlm({
-                provider: helperCfg.provider ?? 'deepseek',
-                apiKey: helperCfg.apiKey,
-                baseURL: helperCfg.url,
-                model: helperCfg.model,
-            }, Number(helperCfg.temperature ?? 0.1))
+            ? await this._deps.makeLlm({
+                ...helperCfg,
+                temperature: Number(helperCfg.temperature ?? 0.1),
+            })
             : undefined;
         this._mainLlm = mainLlm;
         this._classifierLlm = classifierLlm;
@@ -601,6 +401,14 @@ export class SmartServer {
         this._llmMap = llmMap;
         this._pipelineFallback = pipelineFallback;
         this._mainTemp = mainTemp;
+        this._roleLlm = new RoleLlmResolver({
+            getMain: () => this._mainLlm,
+            getHelper: () => this._helperLlm,
+            getClassifier: () => this._classifierLlm,
+            getLlmMap: () => this._llmMap,
+            getPipelineFallback: () => this._pipelineFallback,
+            makeLlm: (lc) => this._deps.makeLlm(lc),
+        });
         // ---- Plugin loader -------------------------------------------------------
         const pluginLoader = this.cfg.pluginLoader ??
             (() => {
@@ -682,9 +490,19 @@ export class SmartServer {
             ...this.cfg.embedderFactories, // config takes precedence over plugins
         };
         this._mergedEmbedderFactories = mergedEmbedderFactories;
+        // Construct the WorkerRegistry (owns the per-worker LLM cache + build loop).
+        // Both _fileLogger (set at the top of _buildInfra) and _mergedEmbedderFactories
+        // (set above) are captured lazily via the accessor callbacks, so construction
+        // here precedes the first use of this._workers.
+        this._workers = new WorkerRegistry({
+            subAgentConfigs: this.cfg.subAgentConfigs,
+            getFileLogger: () => this._fileLogger,
+            getEmbedderFactories: () => this._mergedEmbedderFactories ?? {},
+            buildSubAgent: (name, subCfg, parentLogger, factories, injected) => this.buildSubAgent(name, subCfg, parentLogger, factories, injected),
+        });
         // Resolve the embedder ONCE so the same instance feeds both makeRag and the
         // subagent context-builder's toolSource (#137). See resolve-agent-embedder.
-        const resolvedEmbedder = await resolveAgentEmbedder(this.cfg.rag, this.cfg.embedder, mergedEmbedderFactories);
+        const resolvedEmbedder = await resolveAgentEmbedder(this.cfg.rag, this._deps.embedder ?? this.cfg.embedder, mergedEmbedderFactories);
         // Hold the resolved embedder so buildServerCtx can thread it onto every
         // pipeline context (the controller pipeline needs it for target-state).
         this._resolvedEmbedder = resolvedEmbedder;
@@ -695,11 +513,15 @@ export class SmartServer {
         // llm-agent-rag). Absent `skillPlugins:` → no host, behaviour unchanged.
         if (this.cfg.skillPlugins) {
             const skillCfg = this.cfg.skillPlugins;
-            const reuseAgentEmbedder = skillCfg.embedder === undefined && resolvedEmbedder !== undefined;
+            // An injected embedder short-circuits ALL embedder I/O for the skill host
+            // (no dedicated build, no prefetch) — the seam owns the embedder.
+            const injectedEmbedder = this._deps.embedder;
+            const reuseAgentEmbedder = injectedEmbedder !== undefined ||
+                (skillCfg.embedder === undefined && resolvedEmbedder !== undefined);
             // Prefetch the named embedder factory only when we will actually build a
             // dedicated one (the agent embedder is already prefetched + wrapped).
             if (!reuseAgentEmbedder) {
-                await prefetchEmbedderFactories([
+                await this._deps.prefetchEmbedderFactories([
                     skillCfg.embedder?.provider ?? 'ollama',
                 ]);
             }
@@ -707,33 +529,36 @@ export class SmartServer {
             // captured pg pools are ended INSIDE initSkillHost (the later closeFns
             // cleanup never runs when start() rejects before returning a handle), so
             // the pools cannot leak open sockets on a startup failure.
-            this._skillHost = await initSkillHost(() => buildSkillHostFromConfig(skillCfg, {
-                resolveEmbedder: (ec) => reuseAgentEmbedder
-                    ? resolvedEmbedder
-                    : resolveEmbedder(ec, {
-                        extraFactories: mergedEmbedderFactories,
-                    }),
-                // Real pg `Pool` provider for a `postgres` catalog (qdrant
-                // deployment). Lazily imports `pg` and ensures the catalog table
-                // exists on first use; pass the configured table so the DDL targets
-                // the SAME table the catalog store reads/writes. Absent
-                // skillPlugins.catalog.type:postgres this is never invoked.
-                makePgPool: (connectionString) => {
-                    const pool = makePgPool(connectionString, skillCfg.catalog.type === 'postgres'
-                        ? skillCfg.catalog.table
-                        : undefined);
-                    this._skillPgPools.push(pool);
-                    return pool;
-                },
-                // READ-ONLY pg pool for the recall-only path — NEVER runs DDL, so a
-                // recall-only process with read-only pg credentials does not crash
-                // attempting to CREATE the catalog table it only reads.
-                makePgReadPool: (connectionString) => {
-                    const pool = makePgReadPool(connectionString);
-                    this._skillPgPools.push(pool);
-                    return pool;
-                },
-            }), skillCfg, this._skillPgPools);
+            const buildHost = this._deps.skillHost
+                ? async () => this._deps.skillHost
+                : () => this._deps.buildSkillHost(skillCfg, {
+                    resolveEmbedder: (ec) => reuseAgentEmbedder
+                        ? (injectedEmbedder ?? resolvedEmbedder)
+                        : this._deps.resolveEmbedder(ec, {
+                            extraFactories: mergedEmbedderFactories,
+                        }),
+                    // Real pg `Pool` provider for a `postgres` catalog (qdrant
+                    // deployment). Lazily imports `pg` and ensures the catalog table
+                    // exists on first use; pass the configured table so the DDL targets
+                    // the SAME table the catalog store reads/writes. Absent
+                    // skillPlugins.catalog.type:postgres this is never invoked.
+                    makePgPool: (connectionString) => {
+                        const pool = makePgPool(connectionString, skillCfg.catalog.type === 'postgres'
+                            ? skillCfg.catalog.table
+                            : undefined);
+                        this._skillPgPools.push(pool);
+                        return pool;
+                    },
+                    // READ-ONLY pg pool for the recall-only path — NEVER runs DDL, so a
+                    // recall-only process with read-only pg credentials does not crash
+                    // attempting to CREATE the catalog table it only reads.
+                    makePgReadPool: (connectionString) => {
+                        const pool = makePgReadPool(connectionString);
+                        this._skillPgPools.push(pool);
+                        return pool;
+                    },
+                });
+            this._skillHost = await initSkillHost(buildHost, skillCfg, this._skillPgPools);
         }
         // ---- RAG resolution (interface-only) ----------------------------------
         // Resolve the tools/history stores and any named collections HERE so the
@@ -758,9 +583,12 @@ export class SmartServer {
         // block above is the single source of truth for the tools/history stores.
         // Deployments that previously declared `pipeline.rag.{name}` collections must
         // move them to top-level `rag:` (or register them as plugin RAG).
-        // MCP clients (DI > plugin > YAML). The YAML `mcp:` block is NOT pre-connected
-        // here — see the branch below.
-        const diOrPluginMcpClients = this.cfg.mcpClients ??
+        // MCP clients (BuildAgentDeps.mcpClients > DI cfg.mcpClients > plugin > YAML).
+        // P1b: `this._deps.mcpClients` is the embeddable seam's ready-client override —
+        // when present it short-circuits ALL connect paths (parallel to skillHost). The
+        // YAML `mcp:` block is otherwise NOT pre-connected here — see the branch below.
+        const diOrPluginMcpClients = this._deps.mcpClients ??
+            this.cfg.mcpClients ??
             (plugins.mcpClients.length > 0 ? plugins.mcpClients : undefined);
         // ---- Knowledge backend (no MCP dependency) ----------------------------
         // The remaining shared pipeline infra (`_sharedMcpClients` + the
@@ -769,48 +597,65 @@ export class SmartServer {
         // connects + vectorizes (the builder owns that single connection).
         this.buildKnowledgeBackend();
         // ---- MCP connection strategy (exactly ONE connection) -----------------
-        // Two client sources, two orderings — both keep ONE MCP connection AND a
-        // vectorized `toolsRag`:
+        // P1b: MCP is ALWAYS provisioned through the injected `BuildAgentDeps` seam so
+        // the embeddable `buildAgent(cfg)` path never forces a real connect. Two
+        // sources, ONE provisioning point:
+        //
+        //   • Ready clients present (`_deps.mcpClients` / `cfg.mcpClients` / plugin
+        //     clients, captured as `diOrPluginMcpClients`) → inject them into the
+        //     startup builder via `withMcpClients` (builder short-circuits its own
+        //     `cfg.mcp` auto-connect). `_sharedMcpClients` = that exact set, and the
+        //     `_toolsRagHandle` catalog is built now over them.
         //
-        //   • DI/plugin clients present → inject them into the startup builder via
-        //     `withMcpClients` (builder.ts:923 short-circuits its own `cfg.mcp`
-        //     auto-connect). These pre-built clients were never vectorized by the
-        //     builder (unchanged behavior). `_sharedMcpClients` = that exact set,
-        //     and the `_toolsRagHandle` catalog is built now over them.
+        //   • No ready clients but a YAML `mcp:` block → provision ONCE via the seam
+        //     (`this._deps.connectMcp(this.cfg.mcp)`; default = real connect, an
+        //     embedded host can inject a stub) and inject those clients too, so the
+        //     builder does NOT self-connect from `cfg.mcp` (single provisioning
+        //     point). The `_toolsRagHandle` catalog is built over the connected set.
+        //     (Tool ranking falls back to the MCP catalog, same as the ready-client
+        //     path; the builder no longer vectorizes the YAML `mcp:` block itself.)
         //
-        //   • YAML-only (no DI/plugin) → do NOT pre-connect and do NOT inject. The
-        //     startup builder receives `cfg.mcp` (via buildBaseBuilder, since
-        //     `mcpClients` is undefined) so `build()` CONNECTS the YAML block AND
-        //     VECTORIZES the tools into `toolsRag` (the `IRag`). AFTER `build()` we
-        //     harvest its connected set into `_sharedMcpClients` so `ctx.callMcp`
-        //     and per-session agents reuse the SAME single connection, then build
-        //     the `_toolsRagHandle` catalog over them. (Restores the
-        //     tool-vectorization the inject-skip regressed, with no double-connect.)
-        // DI precedence semantics: an explicitly-provided client set (even an EMPTY
-        // array) overrides YAML `mcp:`. `cfg.mcpClients: []` is a deliberate "disable
-        // MCP / override plugin+YAML" signal — it must take the DI branch (inject `[]`
-        // → builder short-circuits via withMcpClients([]) → no YAML auto-connect), NOT
-        // fall through to the YAML branch. So gate on presence (`!== undefined`), not
-        // length. (`diOrPluginMcpClients` is already undefined when neither DI nor a
-        // non-empty plugin set was provided — see its resolution above.)
-        const hasDiOrPlugin = diOrPluginMcpClients !== undefined;
+        //   • No clients and no `mcp:` block → undefined; no MCP wiring at all.
+        // Precedence: a ready client set (even an EMPTY array) overrides YAML `mcp:`.
+        // `cfg.mcpClients: []` (or `_deps.mcpClients: []`) is a deliberate "disable
+        // MCP / override plugin+YAML" signal — it takes the inject branch (inject `[]`
+        // → builder short-circuits → no YAML connect), NOT the YAML connect branch. So
+        // gate on presence (`!== undefined`), not length.
+        const hasReadyClients = diOrPluginMcpClients !== undefined;
+        // YAML `mcp:` with NO ready clients AND NO injected seam → keep the legacy
+        // builder-owned connect so the builder VECTORIZES the tools (the ToolSelect
+        // ranking contract). `_sharedMcpClients` + the tools-RAG handle are harvested
+        // from the built handle AFTER `build()` (see the harvest block below). When
+        // the seam IS injected we provision through it instead (no builder connect).
+        const yamlBuilderConnect = !hasReadyClients && !!this.cfg.mcp && !this._mcpSeamInjected;
         let mcpClients;
-        if (hasDiOrPlugin) {
-            // DI/plugin branch — resolve `_sharedMcpClients` + tools-RAG handle NOW
-            // (knowledge backend is idempotent; already built above).
-            await this.buildSharedPipelineInfra({
-                toolsRag,
-                resolvedEmbedder,
-                mcpClients: diOrPluginMcpClients,
-            });
+        if (hasReadyClients) {
             mcpClients = diOrPluginMcpClients;
         }
+        else if (this.cfg.mcp && this._mcpSeamInjected) {
+            // Injected seam + YAML `mcp:` → the seam is the SINGLE provisioning point
+            // (the embeddable path must never force a real connect). Stash on
+            // `_stepperMcpClients` so the idempotent guard inside
+            // buildSharedPipelineInfra does not connect a second time.
+            this._stepperMcpClients = await this._deps.connectMcp(this.cfg.mcp);
+            mcpClients = this._stepperMcpClients;
+        }
         else {
-            // YAML-only / no-mcp branch — let the builder connect + vectorize from
-            // `cfg.mcp`; `_sharedMcpClients` + the tools-RAG handle are resolved from
-            // the built handle AFTER `build()` (see below).
+            // No MCP, or the YAML-builder-connect path (mcpClients stays undefined so
+            // the builder receives `cfg.mcp` and connects + vectorizes itself).
             mcpClients = undefined;
         }
+        // Resolve `_sharedMcpClients` + the tools-RAG handle catalog over the
+        // provisioned set for every path EXCEPT yamlBuilderConnect, which resolves
+        // them AFTER `build()` from the harvested handle (knowledge backend is
+        // idempotent; already built above).
+        if (!yamlBuilderConnect) {
+            await this.buildSharedPipelineInfra({
+                toolsRag,
+                resolvedEmbedder,
+                mcpClients,
+            });
+        }
         // Build SubAgentRegistry from `subagents:` YAML block (if present).
         // Each sub-agent is a minimal SmartAgent reusing the parent's plugin
         // outputs (embedder factories, plugins) but with its own LLM/RAG/MCP/etc.
@@ -861,13 +706,14 @@ export class SmartServer {
         const agentHandle = await builder.build();
         const { agent: smartAgent, chat, streamChat, close: closeAgent, circuitBreakers, ragStores, modelProvider, } = agentHandle;
         const { ragRegistry: globalRagRegistry, mcpClients: globalMcpClients } = agentHandle;
-        // ---- YAML-only MCP harvest (single-connect + restored vectorization) ----
-        // For the YAML-only branch the startup builder connected the `mcp:` block
-        // AND vectorized its tools into `toolsRag`. Harvest the builder's connected
-        // set into `_sharedMcpClients` so `ctx.callMcp` and per-session agents reuse
-        // the SAME single connection (no second connect), then build the tools-RAG
-        // handle catalog over it. The DI/plugin branch already did this earlier.
-        if (!hasDiOrPlugin) {
+        // ---- YAML-builder-connect MCP harvest (single-connect + vectorization) ----
+        // Only on the `yamlBuilderConnect` path (YAML `mcp:`, no ready clients, no
+        // injected seam) did the startup builder OWN the connection AND vectorize the
+        // tools into `toolsRag`. Harvest its connected set into `_sharedMcpClients` so
+        // `ctx.callMcp` + per-session agents reuse the SAME single connection (no
+        // second connect), then build the tools-RAG handle catalog over it. Every
+        // other path already resolved these in buildSharedPipelineInfra before build().
+        if (yamlBuilderConnect) {
             this._sharedMcpClients = globalMcpClients ?? [];
             await this.buildToolsRagHandle({ toolsRag, resolvedEmbedder });
         }
@@ -942,7 +788,7 @@ export class SmartServer {
             // worker-owned MCP clients themselves disconnect. Ordering matters —
             // closing MCP clients while a session graph is mid-use would cut its
             // request short.
-            await drainWorkerCache(this._workerLlmCache);
+            await this._workers.drain();
         });
         const startTime = Date.now();
         const healthChecker = new HealthChecker({
@@ -956,106 +802,131 @@ export class SmartServer {
         // with tool vectorization (146+ embedding calls).
         // ---- Config hot-reload (optional) ------------------------------------
         if (this.cfg.configFile) {
-            const watcher = new ConfigWatcher(this.cfg.configFile);
-            watcher.on('reload', (update) => {
-                log({ event: 'config_reload', update });
-                // Apply agent config updates
-                const agentUpdate = {};
-                if (update.maxIterations !== undefined)
-                    agentUpdate.maxIterations = update.maxIterations;
-                if (update.maxToolCalls !== undefined)
-                    agentUpdate.maxToolCalls = update.maxToolCalls;
-                if (update.ragQueryK !== undefined)
-                    agentUpdate.ragQueryK = update.ragQueryK;
-                if (update.toolUnavailableTtlMs !== undefined)
-                    agentUpdate.toolUnavailableTtlMs = update.toolUnavailableTtlMs;
-                if (update.showReasoning !== undefined)
-                    agentUpdate.showReasoning = update.showReasoning;
-                if (update.historyAutoSummarizeLimit !== undefined)
-                    agentUpdate.historyAutoSummarizeLimit =
-                        update.historyAutoSummarizeLimit;
-                if (update.prompts?.ragTranslate !== undefined)
-                    agentUpdate.ragTranslatePrompt = update.prompts.ragTranslate;
-                if (update.prompts?.historySummary !== undefined)
-                    agentUpdate.historySummaryPrompt = update.prompts.historySummary;
-                if (update.classificationEnabled !== undefined)
-                    agentUpdate.classificationEnabled = update.classificationEnabled;
-                if (Object.keys(agentUpdate).length > 0) {
-                    smartAgent.applyConfigUpdate(agentUpdate);
-                    // Mirror onto `this.cfg.agent` so freshly-built session graphs
-                    // (which read `this.cfg.agent` in `buildSessionAgent`) observe the
-                    // update. Deep-merge to preserve untouched startup fields.
-                    // Note: `agentUpdate` includes flat fields ONLY whitelisted by
-                    // `AGENT_CONFIG_FIELDS` plus the two prompt fields, which we route
-                    // into `this.cfg.prompts` separately below.
-                    const agentPatch = {};
-                    for (const k of Object.keys(agentUpdate)) {
-                        if (k !== 'ragTranslatePrompt' && k !== 'historySummaryPrompt') {
-                            agentPatch[k] = agentUpdate[k];
-                        }
-                    }
+            const reloadWatcher = new ConfigReloadWatcher({
+                configFile: this.cfg.configFile,
+                log,
+                applyAgentUpdate: (u) => smartAgent.applyConfigUpdate(u),
+                mirrorCfg: (agentPatch, prompts) => {
                     if (Object.keys(agentPatch).length > 0) {
-                        const mergedAgent = {
+                        this.cfg.agent = {
                             ...(this.cfg.agent ??
                                 {}),
                             ...agentPatch,
                         };
-                        this.cfg.agent =
-                            mergedAgent;
                     }
-                    if (update.prompts?.ragTranslate !== undefined ||
-                        update.prompts?.historySummary !== undefined) {
-                        const mergedPrompts = {
+                    if (prompts.ragTranslate !== undefined ||
+                        prompts.historySummary !== undefined) {
+                        const merged = {
                             ...(this.cfg.prompts ??
                                 {}),
                         };
-                        if (update.prompts?.ragTranslate !== undefined) {
-                            mergedPrompts.ragTranslate = update.prompts.ragTranslate;
-                        }
-                        if (update.prompts?.historySummary !== undefined) {
-                            mergedPrompts.historySummary = update.prompts.historySummary;
-                        }
+                        if (prompts.ragTranslate !== undefined)
+                            merged.ragTranslate = prompts.ragTranslate;
+                        if (prompts.historySummary !== undefined)
+                            merged.historySummary = prompts.historySummary;
                         this.cfg.prompts =
-                            mergedPrompts;
+                            merged;
                     }
-                }
-                // Per-session graphs (built by SessionGraphFactory) captured the OLD
-                // config and the OLD cached worker LLM set. Without invalidation,
-                // existing sessions keep the stale SmartAgent and a fresh acquire on a
-                // cookie-known sessionId still returns it. Clear the worker cache so
-                // the next build reads from the just-applied config, then drop every
-                // session graph. Failures are non-fatal — log and continue.
-                // Fix #21: drain per-worker SmartAgentHandle.close() BEFORE clearing
-                // the cache. Hot-reload runs from a synchronous emitter callback, so
-                // fire-and-forget here — same async-tolerance as the invalidateAll
-                // call below.
-                drainWorkerCache(this._workerLlmCache).catch((err) => {
-                    log({ event: 'config_reload_drain_error', error: String(err) });
-                });
-                this._lifecycle?.invalidateAll().catch((err) => {
-                    log({ event: 'config_reload_invalidate_error', error: String(err) });
-                });
-                // Apply RAG weight updates
-                if (update.vectorWeight !== undefined ||
-                    update.keywordWeight !== undefined) {
-                    for (const store of Object.values(ragStores)) {
-                        if (store &&
-                            typeof store.updateWeights === 'function') {
-                            store.updateWeights({
-                                vectorWeight: update.vectorWeight,
-                                keywordWeight: update.keywordWeight,
-                            });
-                        }
-                    }
-                }
-            });
-            watcher.on('error', (err) => {
-                log({ event: 'config_reload_error', error: String(err) });
+                },
+                drainWorkers: () => this._workers.drain(),
+                invalidateSessions: () => this._lifecycle?.invalidateAll() ?? Promise.resolve(),
+                ragStores,
             });
-            watcher.start();
-            closeFns.push(() => watcher.stop());
+            reloadWatcher.start();
+            closeFns.push(() => reloadWatcher.stop());
         }
         const { requestLogger } = agentHandle;
+        return {
+            close: async () => {
+                for (const fn of closeFns)
+                    await fn();
+            },
+            chat,
+            streamChat,
+            requestLogger,
+            // Infra/passthrough startup agent — `_start()` serves infra endpoints
+            // (HealthChecker / /v1/models) from this.
+            smartAgent,
+            // Resolved globals the embeddable path needs to assemble the `'embedded'`
+            // SessionAgentParts (the HTTP path serves per-session graphs instead).
+            globalMcpClients,
+            globalRagRegistry,
+            log,
+            healthChecker,
+            modelProvider,
+            adapterMap,
+        };
+    }
+    /**
+     * Build the embeddable COORDINATED agent for the free `buildAgent(cfg)` path.
+     *
+     * `_buildInfra().smartAgent` is the INFRA/passthrough startup agent — it has
+     * NO coordinator, so it would never run the configured pipeline. The HTTP
+     * `start()` path serves the PER-SESSION `graph.agent` (built lazily via
+     * buildSessionAgent → buildPipelineInstance) and keeps using `smartAgent` for
+     * infra endpoints (/v1/models, health). But the embeddable `buildAgent(cfg)`
+     * consumer has no session lifecycle, so it must receive a fully COORDINATED
+     * agent. Build ONE pipeline instance via the SAME path a session uses — an
+     * `'embedded'` session — over the shared infra, and return ITS agent. This is
+     * the ONLY caller that builds the embedded instance, so `start()` no longer
+     * pays for an idle coordinator it never serves.
+     *
+     * @internal — reached only by the same-module free `buildAgent(cfg)`; not part
+     * of the documented public API. Public (not `private`) solely so that seam can
+     * call it by name (a `private` reached only via an external cast trips
+     * `noUnusedLocals`).
+     */
+    async _buildEmbeddedAgent() {
+        const infra = await this._buildInfra();
+        // If the pipeline-instance build throws, the infra (LLM clients, MCP, skill
+        // host, pg pools) is already live — tear it down before propagating so a
+        // failed embedded build never leaks the infra.
+        let inst;
+        try {
+            inst = await this.buildPipelineInstance({
+                sessionId: 'embedded',
+                parts: this._embeddedSessionParts(infra.globalMcpClients, infra.globalRagRegistry),
+            });
+        }
+        catch (e) {
+            await infra.close().catch(() => { });
+            throw e;
+        }
+        return {
+            // PUBLIC embeddable agent = the coordinated pipeline instance's agent.
+            agent: inst.agent,
+            // Dispose the pipeline instance FIRST, then the shared infra. `finally`
+            // guarantees `infra.close()` runs even if `inst.close()` throws.
+            close: async () => {
+                try {
+                    await inst.close();
+                }
+                finally {
+                    await infra.close();
+                }
+            },
+        };
+    }
+    /**
+     * Assemble the `SessionAgentParts` for the single `'embedded'` pipeline
+     * instance returned by `_buildEmbeddedAgent` (the embeddable `buildAgent(cfg)`
+     * path).
+     * Mirrors EXACTLY what the session lifecycle passes to `buildSessionAgent`:
+     * the global mcpClients + the global ragRegistry + the global tools store,
+     * with a fresh per-(embedded-)session request logger.
+     */
+    _embeddedSessionParts(mcpClients, ragRegistry) {
+        return {
+            sessionId: 'embedded',
+            mcpClients: mcpClients ?? this._sharedMcpClients ?? [],
+            toolsRag: this._toolsRag,
+            ragRegistry,
+            logger: new SessionRequestLogger(),
+        };
+    }
+    async _start() {
+        const built = await this._buildInfra();
+        const { chat, streamChat, requestLogger, smartAgent, log, healthChecker, modelProvider, adapterMap, } = built;
         const server = http.createServer((req, res) => this._handle(req, res, requestLogger, smartAgent, chat, streamChat, log, healthChecker, modelProvider, adapterMap).catch((err) => {
             if (!res.headersSent) {
                 res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -1082,8 +953,9 @@ export class SmartServer {
                         // 2. Now run lifecycle cleanup: sweep timer, lifecycle.disposeAll,
                         //    config watcher stop, agent close. By this point no HTTP
                         //    request is in flight, so disposing session graphs is safe.
-                        for (const fn of closeFns)
-                            await fn();
+                        //    `built.close()` runs the same `closeFns` loop the original
+                        //    inline close did — order preserved.
+                        await built.close();
                     },
                     requestLogger,
                 });
@@ -1140,7 +1012,7 @@ export class SmartServer {
         const classifierTemp = Number(subFlatLlm?.classifierTemperature ?? 0.1);
         const cached = await resolveWorkerLlmSet({
             name,
-            cache: this._workerLlmCache,
+            cache: this._workers.cache,
             // Preserve the existing makeLlm derivation exactly.
             makeMain: () => makeLlm({
                 // ?? 'deepseek' is a TS type-narrowing net only; the config
@@ -1250,7 +1122,7 @@ export class SmartServer {
         // re-wires never overwrite the cache. See backfillWorkerCacheFromHandle's
         // doc-comment for the rationale.
         if (!injected) {
-            const entry = this._workerLlmCache.get(name);
+            const entry = this._workers.cache.get(name);
             if (entry)
                 await backfillWorkerCacheFromHandle(entry, handle);
         }
@@ -1258,32 +1130,24 @@ export class SmartServer {
     }
     // -- Pipeline-context dep sources (promoted from the inline coordinator-gate
     //    closures; consumed by buildServerCtx, which later tasks call) ----------
-    /** Build an LLM from a SmartServerLlmConfig (mirrors stepperMakeLlm/DAG). */
+    /** Build an LLM from a SmartServerLlmConfig (mirrors stepperMakeLlm/DAG).
+     *  Routes through the BuildAgentDeps seam so an injected `makeLlm` overrides
+     *  the real builder. */
     _makeLlm(lc) {
-        return makeLlm({
-            provider: lc.provider ?? 'deepseek',
-            apiKey: lc.apiKey,
-            baseURL: lc.url,
-            model: lc.model,
-        }, Number(lc.temperature ?? this._mainTemp ?? 0.7));
+        return this._deps.makeLlm(lc);
+    }
+    /** The real `makeLlm`-backed construction (the seam's default). */
+    _makeLlmDefault(lc) {
+        return makeDefaultRoleLlm(lc, this._mainTemp);
     }
     /** Resolve a per-role LLM through the normalized map → pipelineFallback chain.
      *  'main' returns the captured mainLlm; 'helper'/'classifier' return the
      *  prebuilt instances when present; otherwise the map/fallback config is built. */
     async resolveRoleLlm(role) {
-        if (role === 'main' && this._mainLlm)
-            return this._mainLlm;
-        if ((role === 'helper' || role === 'planner') && this._helperLlm) {
-            return this._helperLlm;
+        if (!this._roleLlm) {
+            throw new Error('resolveRoleLlm invoked before _buildInfra built the resolver');
         }
-        if (role === 'classifier' && this._classifierLlm)
-            return this._classifierLlm;
-        const cfg = resolveLlmConfig(this._llmMap, role, this._pipelineFallback);
-        if (cfg)
-            return this._makeLlm(cfg);
-        if (this._mainLlm)
-            return this._mainLlm;
-        throw new Error(`cannot resolve LLM for role '${role}': no config`);
+        return this._roleLlm.resolve(role);
     }
     /**
      * Session-scoped knowledge RAG over the shared knowledge backend (built
@@ -1312,7 +1176,7 @@ export class SmartServer {
     }
     /** callMcp bridge over the shared connected MCP clients (empty when none). */
     callMcp(name, args, signal) {
-        return buildMcpBridge(this._sharedMcpClients ?? [])(name, args, signal);
+        return buildMcpBridge(this._sharedMcpClients ?? [], this._mcpFailureClassifier)(name, args, signal);
     }
     _mintStepperId() {
         return randomUUID();
@@ -1347,7 +1211,7 @@ export class SmartServer {
         // connect the YAML `mcp:` block ONCE (connect is not safe to invoke twice
         // on the same wrapper — guard via the cache field).
         if (!mcpClients && !this._stepperMcpClients) {
-            this._stepperMcpClients = await connectMcpClientsFromConfig(this.cfg.mcp);
+            this._stepperMcpClients = await this._deps.connectMcp(this.cfg.mcp);
         }
         this._sharedMcpClients = mcpClients ?? this._stepperMcpClients ?? [];
         await this.buildToolsRagHandle({ toolsRag, resolvedEmbedder });
@@ -1362,19 +1226,10 @@ export class SmartServer {
     buildKnowledgeBackend() {
         if (this._stepperKnowledgeBackend)
             return;
-        const logDir = this.cfg.logDir;
-        // Attach an embedder-backed semantic index whenever an embedder is resolved —
-        // for ANY pipeline. Do NOT throw here: buildKnowledgeBackend runs
-        // unconditionally at startup and a flat/stepper deployment without an embedder
-        // is valid; only the CONTROLLER mandates embedding recall, enforced at the
-        // ControllerFactory boundary, not globally. With an index, the controller's
-        // results-RAG recall ranks by meaning instead of recency.
-        const semantic = this._resolvedEmbedder
-            ? makeKnowledgeSemanticIndex(this._resolvedEmbedder)
-            : undefined;
-        this._stepperKnowledgeBackend = logDir
-            ? new JsonlKnowledgeBackend(logDir, semantic)
-            : new InMemoryKnowledgeBackend(semantic);
+        this._stepperKnowledgeBackend = makeKnowledgeBackend({
+            logDir: this.cfg.logDir,
+            embedder: this._resolvedEmbedder,
+        });
     }
     /**
      * Build `_toolsRagHandle` — a real IToolsRagHandle over the tools RAG store +
@@ -1388,71 +1243,7 @@ export class SmartServer {
      */
     async buildToolsRagHandle(input) {
         const { toolsRag, resolvedEmbedder } = input;
-        // Tools RAG handle over the tools store + MCP catalog.
-        const stepperMcpClients = this._sharedMcpClients ?? [];
-        let catalogCache;
-        const ensureCatalog = async () => {
-            if (catalogCache)
-                return catalogCache;
-            const catalog = new Map();
-            await Promise.allSettled(stepperMcpClients.map(async (client) => {
-                const result = await client.listTools();
-                if (result.ok) {
-                    for (const t of result.value) {
-                        if (!catalog.has(t.name))
-                            catalog.set(t.name, t);
-                    }
-                }
-            }));
-            catalogCache = catalog;
-            return catalog;
-        };
-        this._toolsRagHandle = {
-            async query(text, k, options) {
-                const limit = k ?? 20;
-                const catalog = await ensureCatalog();
-                if (toolsRag && resolvedEmbedder) {
-                    // Pass options (requestLogger + trace) so the wrapped embedder logs
-                    // this query-embedding against the request.
-                    const embedding = new QueryEmbedding(text, resolvedEmbedder, options);
-                    const ragResult = await toolsRag.query(embedding, limit);
-                    if (ragResult.ok) {
-                        const hits = [];
-                        for (const r of ragResult.value) {
-                            const id = r.metadata.id;
-                            if (id?.startsWith('tool:')) {
-                                const name = id.slice(5).replace(/:.*$/, '');
-                                const tool = catalog.get(name);
-                                if (tool)
-                                    hits.push(tool);
-                            }
-                        }
-                        if (hits.length > 0)
-                            return hits;
-                    }
-                }
-                return [...catalog.values()].slice(0, limit);
-            },
-            lookup(name) {
-                return catalogCache?.get(name);
-            },
-        };
-        // F2: eagerly populate the MCP tool catalog at startup (MCP is connected
-        // above), so the SYNC `lookup(name)` contract (IToolsRagHandle.lookup) returns
-        // a tool schema BEFORE any `query()` runs. `ensureCatalog` is idempotent —
-        // later `query()` calls reuse the cached map. Guard against a catalog-load
-        // failure so startup never crashes: on failure `catalogCache` stays unset and
-        // `lookup` returns undefined (today's worst case), while the happy path works.
-        try {
-            await ensureCatalog();
-        }
-        catch (err) {
-            this.cfg.log?.({
-                event: 'tools_catalog_eager_load_failed',
-                message: 'tools catalog eager-load failed; lookup() returns undefined until first query()',
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
+        this._toolsRagHandle = await makeToolsRagHandle(this._sharedMcpClients ?? [], toolsRag, resolvedEmbedder, this.cfg.log);
     }
     /**
      * Build the per-session pipeline instance from the registry. Selects the
@@ -1478,62 +1269,13 @@ export class SmartServer {
     /**
      * Build the FRESH per-session worker (sub-agent) registry from the SAME
      * `subagents:` configs the primary build() used, injecting globals + this
-     * session's logger + the CACHED per-worker LLM/embedder (this._workerLlmCache).
+     * session's logger + the CACHED per-worker LLM/embedder (this._workers.cache).
      * NEVER reconstructs LLM clients; NEVER reuses the global registry.
      *
-     * Extracted from buildSessionAgent so both the legacy session re-wire and the
-     * pipeline-plugin context (`buildServerCtx` / `partsToBaseInput`) feed a real
-     * per-session worker map to `buildBaseBuilder` instead of an empty `new Map()`.
+     * Delegates to `this._workers.build(parts)` (WorkerRegistry).
      */
     async buildWorkerRegistry(parts) {
-        const registry = new Map();
-        if (!this.cfg.subAgentConfigs || this.cfg.subAgentConfigs.length === 0) {
-            return registry;
-        }
-        if (!this._fileLogger) {
-            throw new Error('buildWorkerRegistry invoked before primary build() captured globals');
-        }
-        for (const sub of this.cfg.subAgentConfigs) {
-            // Lazy build-on-miss (Fix #18). After PUT /v1/config or hot-reload
-            // clears `_workerLlmCache`, the next session build used to throw
-            // "worker LLM set not cached" because the cache was assumed
-            // pre-populated by the primary build(). buildSubAgent itself routes
-            // through `resolveWorkerLlmSet` which is build-on-miss, so calling
-            // it without an `injected` arg rebuilds the cache entry. We then
-            // re-read the entry to honour the per-worker slot priority below.
-            if (!this._workerLlmCache.has(sub.name)) {
-                await this.buildSubAgent(sub.name, sub.config, this._fileLogger, this._mergedEmbedderFactories ?? {});
-            }
-            const cached = this._workerLlmCache.get(sub.name);
-            if (!cached) {
-                // Defence in depth — should be impossible after the lazy build
-                // above unless buildSubAgent's contract changes.
-                throw new Error(`worker LLM set not cached for '${sub.name}'`);
-            }
-            // Per-worker injected slot priority (review HIGH #7):
-            //   worker-cached (from the primary build, includes backfilled
-            //   subCfg.mcp / subCfg.rag results) → parent's session-scoped
-            //   fallback. Encoded HERE so buildSubAgent does not need to know
-            //   the difference; it just consumes injected.mcpClients/toolsRag.
-            const injectedMcpClients = cached.mcpClients && cached.mcpClients.length > 0
-                ? cached.mcpClients
-                : parts.mcpClients;
-            const injectedToolsRag = cached.toolsRag ?? parts.toolsRag;
-            const subAgent = await this.buildSubAgent(sub.name, sub.config, this._fileLogger, this._mergedEmbedderFactories ?? {}, {
-                ragRegistry: parts.ragRegistry,
-                toolsRag: injectedToolsRag,
-                mcpClients: injectedMcpClients,
-                requestLogger: parts.logger,
-                mainLlm: cached.mainLlm,
-                classifierLlm: cached.classifierLlm,
-                helperLlm: cached.helperLlm,
-                embedder: cached.embedder,
-            });
-            registry.set(sub.name, new SmartAgentSubAgent(sub.name, subAgent, {
-                description: sub.description,
-            }));
-        }
-        return registry;
+        return this._workers.build(parts);
     }
     /**
      * Map SessionAgentParts → buildBaseBuilder input. `workerRegistry` is the
@@ -1622,6 +1364,21 @@ export class SmartServer {
             ragRegistry: scope.parts.ragRegistry,
             callMcp: (n, a, s) => this.callMcp(n, a, s),
             mcpClients: scope.parts.mcpClients,
+            mcpFailureClassifier: this._mcpFailureClassifier,
+            ...(this._toolLoopContextStrategyFactory
+                ? {
+                    toolLoopContextStrategyFactory: this._toolLoopContextStrategyFactory,
+                }
+                : {}),
+            ...(this._stepExecutionControl
+                ? { stepExecutionControl: this._stepExecutionControl }
+                : {}),
+            ...(this._runExecutionControl
+                ? { runExecutionControl: this._runExecutionControl }
+                : {}),
+            ...(this._auxiliaryMcpTools
+                ? { auxiliaryMcpTools: this._auxiliaryMcpTools }
+                : {}),
             subagents: (this.cfg.subAgentConfigs ?? []).map((s) => ({
                 name: s.name,
                 description: s.description,
@@ -1752,6 +1509,16 @@ export class SmartServer {
         if (parts.workerRegistry.size > 0) {
             builder = builder.withSubAgents(parts.workerRegistry);
         }
+        // Thread the instance-level MCP failure classifier (DI/programmatic only).
+        builder = builder.withMcpFailureClassifier(this._mcpFailureClassifier);
+        // Tool-loop context strategy for the NON-controller pipelines (default / flat /
+        // linear / dag / direct SmartAgent). Honor a consumer-injected factory; else
+        // default to a bounded RAG-less Window (a strict improvement over Legacy's
+        // unbounded growing transcript). This Window default is applied ONLY on this
+        // builder channel — NOT on the ctx seam — so it never reaches the controller's
+        // own `ctx.toolLoopContextStrategyFactory ?? RagRecall` resolution.
+        builder = builder.withToolLoopContextStrategyFactory(this._toolLoopContextStrategyFactory ??
+            (() => new WindowContextStrategy()));
         return builder;
     }
     /**
@@ -1760,7 +1527,7 @@ export class SmartServer {
      * session-scoped pipeline context (`buildServerCtx`) supplies the FRESH
      * per-session worker registry + session logger + the global
      * ragRegistry/toolsRag/mcpClients + the CACHED per-worker LLM/embedder
-     * (this._workerLlmCache) via `createAgentBuilder`. It NEVER reuses the primary
+     * (this._workers.cache) via `createAgentBuilder`. It NEVER reuses the primary
      * build()'s global registry/coordinator and NEVER constructs new LLM clients.
      *
      * The pipeline returns `{ agent, close }`; we register `close` under the
@@ -1858,758 +1625,173 @@ export class SmartServer {
             url: rawUrl,
             normalizedPath: urlPath,
         });
-        if (req.method === 'GET' &&
-            (urlPath === '/v1/models' || urlPath === '/models')) {
-            const queryString = rawUrl.includes('?') ? rawUrl.split('?')[1] : '';
-            const queryParams = new URLSearchParams(queryString);
-            const excludeEmbedding = queryParams.get('exclude_embedding') === 'true';
-            let data = [
-                { id: 'smart-agent', object: 'model', owned_by: 'smart-agent' },
-            ];
-            if (modelProvider) {
-                const result = await modelProvider.getModels({ excludeEmbedding });
-                if (result.ok) {
-                    data = result.value.map((m) => ({
-                        id: m.id,
-                        object: 'model',
-                        owned_by: m.owned_by ?? 'unknown',
-                        ...(m.displayName ? { display_name: m.displayName } : {}),
-                        ...(m.provider ? { provider: m.provider } : {}),
-                        ...(m.capabilities ? { capabilities: m.capabilities } : {}),
-                        ...(m.contextLength ? { context_length: m.contextLength } : {}),
-                        ...(m.streamingSupported !== undefined
-                            ? { streaming_supported: m.streamingSupported }
-                            : {}),
-                        ...(m.deprecated !== undefined ? { deprecated: m.deprecated } : {}),
-                    }));
-                }
-            }
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ object: 'list', data }));
-            return;
-        }
-        if (req.method === 'GET' &&
-            (urlPath === '/v1/embedding-models' || urlPath === '/embedding-models')) {
-            let data = [];
-            if (modelProvider?.getEmbeddingModels) {
-                const result = await modelProvider.getEmbeddingModels();
-                if (result.ok) {
-                    data = result.value.map((m) => ({
-                        id: m.id,
-                        object: 'model',
-                        owned_by: m.owned_by ?? 'unknown',
-                        ...(m.displayName ? { display_name: m.displayName } : {}),
-                        ...(m.provider ? { provider: m.provider } : {}),
-                        ...(m.capabilities ? { capabilities: m.capabilities } : {}),
-                        ...(m.contextLength ? { context_length: m.contextLength } : {}),
-                        ...(m.streamingSupported !== undefined
-                            ? { streaming_supported: m.streamingSupported }
-                            : {}),
-                        ...(m.deprecated !== undefined ? { deprecated: m.deprecated } : {}),
-                    }));
-                }
-            }
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ object: 'list', data }));
-            return;
-        }
-        if (req.method === 'GET' && urlPath === '/v1/usage') {
-            const lifecycle = this._lifecycle;
-            if (!lifecycle) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(jsonError('Session lifecycle not initialized', 'server_error'));
-                return;
-            }
-            const isHttps = req.socket.encrypted === true ||
-                req.headers['x-forwarded-proto'] === 'https';
-            const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
-            if (resolved.minted && resolved.setCookie) {
-                res.setHeader('Set-Cookie', resolved.setCookie);
-            }
-            const sessionId = resolved.identity.sessionId;
-            const graph = await lifecycle.acquire(sessionId);
-            try {
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(graph.logger.getSummary()));
-            }
-            finally {
-                lifecycle.release(sessionId, graph);
-            }
-            return;
-        }
+        // Server readiness: derived from the agent's MCP connection strategy (it
+        // implements IReadinessReporter). No strategy / non-reporting ⇒ ready
+        // (readiness unknown). Computed ONCE here and reused by /health and the
+        // pre-dispatch request gate (messages/chat) via `rc.ready`.
+        const ready = isReadinessReporter(smartAgent) ? smartAgent.isReady() : true;
+        const rc = {
+            req,
+            res,
+            rawUrl,
+            urlPath,
+            method: req.method ?? 'GET',
+            ready,
+            server: this,
+            requestLogger,
+            smartAgent,
+            chat,
+            streamChat,
+            log,
+            healthChecker,
+            modelProvider,
+            adapterMap,
+        };
+        await this._routeTable.dispatch(rc);
+    }
+    /**
+     * Declarative route table replacing `_handle`'s if/else chain. Routes are
+     * registered in the EXACT order the original chain checked them (first
+     * method+path match wins), so dispatch is behaviour-identical. Each handler
+     * body is the corresponding original branch moved verbatim, with `this`
+     * accessed through `rc.server` and the request locals read from `rc`.
+     */
+    _buildRouteTable() {
+        const table = new HttpRouteTable();
+        table.add({
+            method: 'GET',
+            match: (p) => p === '/v1/models' || p === '/models',
+            handle: (rc) => handleModelsList(rc),
+        });
+        table.add({
+            method: 'GET',
+            match: (p) => p === '/v1/embedding-models' || p === '/embedding-models',
+            handle: (rc) => handleEmbeddingModelsList(rc),
+        });
+        table.add({
+            method: 'GET',
+            match: (p) => p === '/v1/usage',
+            handle: (rc) => handleUsageRoute(rc, rc.server._lifecycle),
+        });
         // GET /v1/sessions — list sessions for the current identity
-        if (req.method === 'GET' && urlPath === '/v1/sessions') {
-            const lifecycle = this._lifecycle;
-            if (!lifecycle) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(jsonError('Session lifecycle not initialized', 'server_error'));
-                return;
-            }
-            const isHttps = req.socket.encrypted === true ||
-                req.headers['x-forwarded-proto'] === 'https';
-            const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
-            if (resolved.minted && resolved.setCookie) {
-                res.setHeader('Set-Cookie', resolved.setCookie);
-            }
-            const identity = resolved.identity.sessionId;
-            const body = await handleListSessions(this._sessionMetaStore, identity);
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(body));
-            return;
-        }
+        table.add({
+            method: 'GET',
+            match: (p) => p === '/v1/sessions',
+            handle: (rc) => handleSessionsList(rc, rc.server._lifecycle, rc.server._sessionMetaStore),
+        });
         // POST /v1/sessions/:id/resume — resume a session
-        {
-            const resumeMatch = urlPath.match(/^\/v1\/sessions\/([^/]+)\/resume$/);
-            if (req.method === 'POST' && resumeMatch) {
-                const sessionId = resumeMatch[1];
-                const lifecycle = this._lifecycle;
-                if (!lifecycle) {
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(jsonError('Session lifecycle not initialized', 'server_error'));
-                    return;
-                }
-                const isHttps = req.socket.encrypted === true ||
-                    req.headers['x-forwarded-proto'] === 'https';
-                const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
-                if (resolved.minted && resolved.setCookie) {
-                    res.setHeader('Set-Cookie', resolved.setCookie);
-                }
-                const identity = resolved.identity.sessionId;
-                const body = await handleResumeSession(this._sessionMetaStore, identity, sessionId);
-                const status = body.ok ? 200 : 404;
-                res.writeHead(status, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(body));
-                return;
-            }
-        }
+        table.add({
+            method: 'POST',
+            match: (p) => p.match(/^\/v1\/sessions\/([^/]+)\/resume$/) ?? false,
+            handle: (rc) => handleSessionResume(rc, rc.server._lifecycle, rc.server._sessionMetaStore),
+        });
         // DELETE /v1/sessions/:id — delete a session
-        {
-            const deleteMatch = urlPath.match(/^\/v1\/sessions\/([^/]+)$/);
-            if (req.method === 'DELETE' && deleteMatch) {
-                const sessionId = deleteMatch[1];
-                const lifecycle = this._lifecycle;
-                if (!lifecycle) {
-                    res.writeHead(500, { 'Content-Type': 'application/json' });
-                    res.end(jsonError('Session lifecycle not initialized', 'server_error'));
+        table.add({
+            method: 'DELETE',
+            match: (p) => p.match(/^\/v1\/sessions\/([^/]+)$/) ?? false,
+            handle: (rc) => handleSessionDelete(rc, rc.server._lifecycle, rc.server._sessionMetaStore, rc.server._stepperKnowledgeBackend),
+        });
+        // /v1/config or /config — any method (dispatches GET/PUT/405 internally)
+        table.add({
+            method: '*',
+            match: (p) => p === '/v1/config' || p === '/config',
+            handle: async (rc) => {
+                if (rc.method === 'GET') {
+                    const models = rc.smartAgent.getActiveConfig();
+                    const agent = rc.smartAgent.getAgentConfig();
+                    const body = { models, agent };
+                    rc.res.writeHead(200, { 'Content-Type': 'application/json' });
+                    rc.res.end(JSON.stringify(body));
                     return;
                 }
-                const isHttps = req.socket.encrypted === true ||
-                    req.headers['x-forwarded-proto'] === 'https';
-                const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
-                if (resolved.minted && resolved.setCookie) {
-                    res.setHeader('Set-Cookie', resolved.setCookie);
+                if (rc.method === 'PUT') {
+                    await handleConfigUpdate(rc.req, rc.res, rc.smartAgent, this._configUpdateTarget());
+                    return;
                 }
-                const identity = resolved.identity.sessionId;
-                const evictFn = async (sid) => {
-                    // (a) Evict/dispose this session's graph from the registry.
-                    await lifecycle.registry.evictOne(sid);
-                    // (b) Evict the session's knowledge from the shared backend. This
-                    // clears the long-lived in-memory backend AND removes the JSONL files
-                    // (JsonlKnowledgeBackend.deleteSession), so a same-id re-entry never
-                    // rehydrates stale entries — matching the README "evicts its
-                    // knowledge-RAG entries" contract.
-                    await this._stepperKnowledgeBackend?.deleteSession(sid);
-                };
-                const body = await handleDeleteSession(this._sessionMetaStore, identity, sessionId, evictFn);
-                const status = body.ok ? 200 : 404;
-                res.writeHead(status, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(body));
-                return;
-            }
-        }
-        // /v1/config or /config
-        if (urlPath === '/v1/config' || urlPath === '/config') {
-            if (req.method === 'GET') {
-                const models = smartAgent.getActiveConfig();
-                const agent = smartAgent.getAgentConfig();
-                const body = { models, agent };
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(body));
-                return;
-            }
-            if (req.method === 'PUT') {
-                await this._handleConfigUpdate(req, res, smartAgent);
-                return;
-            }
-            // 405 for other methods
-            res.setHeader('Allow', 'GET, PUT, OPTIONS');
-            res.writeHead(405, { 'Content-Type': 'application/json' });
-            res.end(jsonError(`Method ${req.method} not allowed on ${urlPath}`, 'invalid_request_error'));
-            return;
-        }
-        if (req.method === 'GET' &&
-            (urlPath === '/health' || urlPath === '/v1/health')) {
-            const status = await healthChecker.check();
-            const httpCode = status.status === 'unhealthy' ? 503 : 200;
-            res.writeHead(httpCode, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(status));
-            return;
-        }
+                // 405 for other methods
+                rc.res.setHeader('Allow', 'GET, PUT, OPTIONS');
+                rc.res.writeHead(405, { 'Content-Type': 'application/json' });
+                rc.res.end(jsonError(`Method ${rc.req.method} not allowed on ${rc.urlPath}`, 'invalid_request_error'));
+            },
+        });
+        table.add({
+            method: 'GET',
+            match: (p) => p === '/health' || p === '/v1/health',
+            handle: (rc) => handleHealthRoute(rc),
+        });
         // POST /v1/messages or /messages → Anthropic adapter
-        if (req.method === 'POST' &&
-            (urlPath === '/v1/messages' || urlPath === '/messages')) {
-            const anthropicAdapter = adapterMap?.get('anthropic');
-            if (!anthropicAdapter) {
-                res.writeHead(404, { 'Content-Type': 'application/json' });
-                res.end(jsonError('Anthropic adapter not registered', 'not_found'));
-                return;
-            }
-            await this._withSession(req, res, async (graph, sessionId, traceId) => {
-                await this._handleAdapterRequest(req, res, graph.agent ?? smartAgent, anthropicAdapter, { sessionId, traceId, graph });
-            });
-            return;
-        }
-        if (req.method === 'POST' &&
-            (urlPath === '/v1/chat/completions' || urlPath === '/chat/completions')) {
-            await this._withSession(req, res, async (graph, sessionId, traceId) => {
-                await this._handleChat(req, res, requestLogger, graph.agent ?? smartAgent, chat, streamChat, log, modelProvider, { sessionId, traceId, graph });
-            });
-            return;
-        }
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(jsonError(`Cannot ${req.method} ${urlPath}`, 'invalid_request_error'));
-    }
-    async _handleAdapterRequest(req, res, agent, adapter, session) {
-        const raw = await readBody(req);
-        let body;
-        try {
-            body = JSON.parse(raw);
-        }
-        catch {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(jsonError('Invalid JSON', 'invalid_request_error'));
-            return;
-        }
-        let normalized;
-        try {
-            normalized = adapter.normalizeRequest(body);
-        }
-        catch (err) {
-            if (err instanceof AdapterValidationError) {
-                res.writeHead(err.statusCode, { 'Content-Type': 'application/json' });
-                res.end(jsonError(err.message, 'invalid_request_error'));
-                return;
-            }
-            throw err;
-        }
-        // #171 (review#8): the adapter has already normalized Anthropic
-        // tool_use/tool_result blocks into the OpenAI-shaped Message[]
-        // (assistant.tool_calls + role:'tool' with tool_call_id). Run the same
-        // external-results extraction the OpenAI path uses so Anthropic clients get
-        // identical stateless-resume behaviour: consumed external turns are stripped
-        // and their results threaded to the agent keyed by deterministic `ext:` id.
-        const { results: externalResults, sanitizedMessages } = buildExternalResults(normalized.messages);
-        const augmentedOptions = session
-            ? {
-                ...normalized.options,
-                sessionId: session.sessionId,
-                trace: { traceId: session.traceId },
-                toolAvailability: session.graph.toolAvailability,
-                pendingToolResults: session.graph.pendingToolResults,
-                externalResults,
-            }
-            : { ...normalized.options, externalResults };
-        if (normalized.stream) {
-            res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                Connection: 'keep-alive',
-            });
-            for await (const event of adapter.transformStream(agent.streamProcess(sanitizedMessages, augmentedOptions), normalized.context)) {
-                const eventLine = event.event ? `event: ${event.event}\n` : '';
-                res.write(`${eventLine}data: ${event.data}\n\n`);
-            }
-            res.end();
-            return;
-        }
-        // Non-streaming
-        const result = await agent.process(sanitizedMessages, augmentedOptions);
-        res.setHeader('Content-Type', 'application/json');
-        if (!result.ok) {
-            res.writeHead(500);
-            res.end(JSON.stringify(adapter.formatError?.(result.error, normalized.context) ?? {
-                error: {
-                    message: result.error.message,
-                    type: result.error.code,
-                },
-            }));
-            return;
-        }
-        res.writeHead(200);
-        res.end(JSON.stringify(adapter.formatResult(result.value, normalized.context)));
-    }
-    async _handleChat(req, res, _requestLogger, smartAgent, _chat, _streamChat, log, modelProvider, session) {
-        const rawBody = await readBody(req);
-        let parsed;
-        try {
-            parsed = JSON.parse(rawBody);
-        }
-        catch {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(jsonError('Invalid JSON body', 'invalid_request_error'));
-            return;
-        }
-        if (typeof parsed !== 'object' ||
-            parsed === null ||
-            !Array.isArray(parsed.messages)) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(jsonError('messages must be a non-empty array', 'invalid_request_error'));
-            return;
-        }
-        const body = parsed;
-        const extractText = (c) => {
-            if (c === null || c === undefined)
-                return '';
-            if (typeof c === 'string')
-                return c;
-            if (!Array.isArray(c))
-                return '';
-            return c
-                .filter((b) => typeof b === 'object' &&
-                b !== null &&
-                b.type === 'text' &&
-                typeof b.text === 'string')
-                .map((b) => b.text)
-                .join('\n');
-        };
-        const userMessages = body.messages.filter((m) => m.role === 'user');
-        if (userMessages.length === 0) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(jsonError('at least one message with role "user" is required', 'invalid_request_error'));
-            return;
-        }
-        // Prefer the session injected by `_withSession` (cookie identity); fall
-        // back to the legacy x-session-id header / 'default' bucket only when no
-        // session was wired (defensive — production routes always inject one).
-        const traceId = session?.traceId ?? randomUUID();
-        const sessionId = session?.sessionId ??
-            req.headers['x-session-id'] ??
-            'default';
-        const sessionLogger = new SessionLogger(this.cfg.logDir || null, sessionId, traceId);
-        const toolsValidationMode = this.cfg.agent?.externalToolsValidationMode ?? 'permissive';
-        const externalToolsValidation = normalizeAndValidateExternalTools(body.tools);
-        const externalTools = externalToolsValidation.tools;
-        if (externalToolsValidation.errors.length > 0) {
-            log({
-                event: 'invalid_external_tools_detected',
-                traceId,
-                sessionId,
-                mode: toolsValidationMode,
-                count: externalToolsValidation.errors.length,
-                errors: externalToolsValidation.errors,
-            });
-            sessionLogger.logStep('invalid_external_tools_detected', {
-                mode: toolsValidationMode,
-                count: externalToolsValidation.errors.length,
-                errors: externalToolsValidation.errors,
-            });
-            if (toolsValidationMode === 'strict') {
-                const firstError = externalToolsValidation.errors[0];
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(jsonValidationError(firstError.message, firstError.code, firstError.param));
-                return;
-            }
-        }
-        const t0 = Date.now();
-        log({ event: 'request_start', stream: body.stream ?? false, traceId });
-        const opts = {
-            stream: body.stream,
-            externalTools,
-            sessionId,
-            trace: { traceId },
-            sessionLogger,
-            model: body.model,
-            ...(session
-                ? {
-                    toolAvailability: session.graph.toolAvailability,
-                    pendingToolResults: session.graph.pendingToolResults,
-                }
-                : {}),
-            ...(body.temperature !== undefined
-                ? { temperature: body.temperature }
-                : {}),
-            ...(body.max_tokens !== undefined ? { maxTokens: body.max_tokens } : {}),
-            ...(body.top_p !== undefined ? { topP: body.top_p } : {}),
-            ...(body.stop !== undefined
-                ? { stop: Array.isArray(body.stop) ? body.stop : [body.stop] }
-                : {}),
-        };
-        const responseModel = body.model ?? modelProvider?.getModel() ?? 'smart-agent';
-        const normalizedMessages = body.messages
-            .map((m) => {
-            const role = m.role;
-            const normalizedMessage = {
-                role,
-                content: extractText(m.content),
-            };
-            if (role === 'tool') {
-                if (typeof m.tool_call_id === 'string' && m.tool_call_id.trim()) {
-                    normalizedMessage.tool_call_id = m.tool_call_id;
-                }
-                else {
-                    sessionLogger.logStep('drop_orphan_tool_message', {
-                        reason: 'missing_tool_call_id',
-                    });
-                    return null;
-                }
-            }
-            if (role === 'assistant' && Array.isArray(m.tool_calls)) {
-                const toolCalls = m.tool_calls
-                    .filter((tc) => typeof tc === 'object' &&
-                    tc !== null &&
-                    typeof tc.id === 'string' &&
-                    tc.type === 'function' &&
-                    typeof tc.function
-                        ?.name === 'string' &&
-                    typeof tc.function
-                        ?.arguments === 'string')
-                    .map((tc) => ({
-                    id: tc.id,
-                    type: 'function',
-                    function: {
-                        name: tc.function.name,
-                        arguments: tc.function.arguments,
-                    },
-                }));
-                if (toolCalls.length > 0) {
-                    normalizedMessage.tool_calls = toolCalls;
-                    if (!normalizedMessage.content)
-                        normalizedMessage.content = null;
-                }
-            }
-            return normalizedMessage;
-        })
-            .filter((m) => m !== null);
-        // #171 (review#11): consume external (client-executed) tool result turns
-        // from the incoming history into a validated `extId → result` map and strip
-        // those raw turns from the messages forwarded to the agent (so no internal
-        // LLM call ever sees an unmatched assistant tool_calls). On a normal request
-        // with no external history this returns the messages unchanged + an empty
-        // map — a safe no-op. The map is threaded via options.externalResults.
-        const { results: externalResults, sanitizedMessages } = buildExternalResults(normalizedMessages);
-        const invalidToolsHeader = externalToolsValidation.errors.length > 0
-            ? {
-                'x-smartagent-invalid-tools': String(externalToolsValidation.errors.length),
-            }
-            : {};
-        if (body.stream) {
-            res.writeHead(200, {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                Connection: 'keep-alive',
-                ...invalidToolsHeader,
-            });
-            const id = `chatcmpl-${randomUUID()}`;
-            const created = Math.floor(Date.now() / 1000);
-            const stream = smartAgent.streamProcess(sanitizedMessages, {
-                ...opts,
-                externalResults,
-            });
-            let firstChunk = true;
-            let finishReasonSent = false;
-            let lastUsage = null;
-            for await (const chunk of stream) {
-                if (!chunk.ok) {
-                    const errorChunk = {
-                        id,
-                        object: 'chat.completion.chunk',
-                        created,
-                        model: responseModel,
-                        choices: [
-                            {
-                                index: 0,
-                                delta: { content: `[Error] ${chunk.error.message}` },
-                                finish_reason: 'stop',
-                            },
-                        ],
-                    };
-                    res.write(`data: ${JSON.stringify(errorChunk)}\n\n`);
-                    finishReasonSent = true;
-                    break;
-                }
-                // SSE heartbeat comment — keeps connection alive, ignored by clients
-                if (chunk.value.heartbeat) {
-                    const hb = chunk.value.heartbeat;
-                    res.write(`: heartbeat tool=${hb.tool} elapsed=${hb.elapsed}ms\n\n`);
-                    continue;
-                }
-                // SSE timing breakdown comment — sent with the final chunk
-                if (chunk.value.timing) {
-                    const parts = chunk.value.timing.map((t) => `${t.phase}=${t.duration}ms`);
-                    res.write(`: timing ${parts.join(' ')}\n\n`);
-                }
-                if (chunk.value.usage) {
-                    lastUsage = {
-                        prompt_tokens: chunk.value.usage.promptTokens,
-                        completion_tokens: chunk.value.usage.completionTokens,
-                        total_tokens: chunk.value.usage.totalTokens,
-                    };
-                }
-                const baseResponse = {
-                    id,
-                    object: 'chat.completion.chunk',
-                    created,
-                    model: responseModel,
-                    usage: null,
-                };
-                if (firstChunk) {
-                    res.write(`data: ${JSON.stringify({ ...baseResponse, choices: [{ index: 0, delta: { role: 'assistant', content: chunk.value.content || '' }, finish_reason: null }] })}\n\n`);
-                    firstChunk = false;
-                    if (!chunk.value.finishReason && !chunk.value.toolCalls)
-                        continue;
-                }
-                if (chunk.value.content || chunk.value.toolCalls) {
-                    const delta = {};
-                    if (chunk.value.content)
-                        delta.content = chunk.value.content;
-                    if (chunk.value.toolCalls) {
-                        delta.tool_calls = chunk.value.toolCalls.map((call, index) => {
-                            const tc = toToolCallDelta(call, index);
-                            return {
-                                index: tc.index,
-                                id: tc.id,
-                                type: 'function',
-                                function: {
-                                    name: tc.name,
-                                    arguments: tc.arguments || '',
-                                },
-                            };
-                        });
-                    }
-                    res.write(`data: ${JSON.stringify({ ...baseResponse, choices: [{ index: 0, delta, finish_reason: null }] })}\n\n`);
+        table.add({
+            method: 'POST',
+            match: (p) => p === '/v1/messages' || p === '/messages',
+            handle: async (rc) => {
+                // Pre-dispatch readiness gate: fail loud (503) BEFORE opening any stream.
+                if (!rc.ready) {
+                    writeNotReady(rc.res);
+                    return;
                 }
-                if (chunk.value.finishReason) {
-                    res.write(`data: ${JSON.stringify({ ...baseResponse, choices: [{ index: 0, delta: {}, finish_reason: mapStopReason(chunk.value.finishReason) }] })}\n\n`);
-                    finishReasonSent = true;
+                const anthropicAdapter = rc.adapterMap?.get('anthropic');
+                if (!anthropicAdapter) {
+                    rc.res.writeHead(404, { 'Content-Type': 'application/json' });
+                    rc.res.end(jsonError('Anthropic adapter not registered', 'not_found'));
+                    return;
                 }
-            }
-            if (!finishReasonSent) {
-                const baseResponse = {
-                    id,
-                    object: 'chat.completion.chunk',
-                    created,
-                    model: responseModel,
-                    usage: null,
-                };
-                res.write(`data: ${JSON.stringify({ ...baseResponse, choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] })}\n\n`);
-            }
-            if ((this.cfg.reportUsage !== false ||
-                body.stream_options?.include_usage) &&
-                lastUsage) {
-                res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created, model: responseModel, choices: [], usage: lastUsage })}\n\n`);
-            }
-            res.write('data: [DONE]\n\n');
-            res.end();
-            log({
-                event: 'request_done',
-                ok: true,
-                stream: true,
-                finishReason: finishReasonSent ? 'sent' : 'fallback_stop',
-                durationMs: Date.now() - t0,
-            });
-            return;
-        }
-        const result = await smartAgent.process(sanitizedMessages, {
-            ...opts,
-            externalResults,
-        });
-        log({ event: 'request_done', ok: result.ok, durationMs: Date.now() - t0 });
-        const finalContent = result.ok
-            ? result.value.content ||
-                (result.value.toolCalls ? null : '(no response)')
-            : `Error: ${result.error.message}`;
-        const finalFinishReason = result.ok
-            ? mapStopReason(result.value.stopReason)
-            : 'stop';
-        let finalUsage = null;
-        if (result.ok && result.value.usage) {
-            finalUsage = {
-                prompt_tokens: result.value.usage.promptTokens,
-                completion_tokens: result.value.usage.completionTokens,
-                total_tokens: result.value.usage.totalTokens,
-            };
-        }
-        const message = {
-            role: 'assistant',
-            content: finalContent,
-        };
-        if (result.ok && result.value.toolCalls) {
-            message.tool_calls = result.value.toolCalls;
-        }
-        res.writeHead(200, {
-            'Content-Type': 'application/json',
-            ...invalidToolsHeader,
+                await rc.server._withSession(rc.req, rc.res, async (graph, sessionId, traceId) => {
+                    await handleAdapterRequest(rc.req, rc.res, graph.agent ?? rc.smartAgent, anthropicAdapter, { sessionId, traceId, graph });
+                });
+            },
         });
-        res.end(JSON.stringify({
-            id: `chatcmpl-${randomUUID()}`,
-            object: 'chat.completion',
-            created: Math.floor(Date.now() / 1000),
-            model: responseModel,
-            choices: [
-                {
-                    index: 0,
-                    message,
-                    finish_reason: finalFinishReason,
-                },
-            ],
-            usage: finalUsage || {
-                prompt_tokens: 0,
-                completion_tokens: 0,
-                total_tokens: 0,
+        table.add({
+            method: 'POST',
+            match: (p) => p === '/v1/chat/completions' || p === '/chat/completions',
+            handle: async (rc) => {
+                // Pre-dispatch readiness gate: fail loud (503) BEFORE opening any SSE stream.
+                if (!rc.ready) {
+                    writeNotReady(rc.res);
+                    return;
+                }
+                await rc.server._withSession(rc.req, rc.res, async (graph, sessionId, traceId) => {
+                    await handleChat(rc.req, rc.res, rc.requestLogger, graph.agent ?? rc.smartAgent, rc.chat, rc.streamChat, rc.log, rc.modelProvider, { sessionId, traceId, graph }, this.cfg);
+                });
             },
-        }));
+        });
+        return table;
     }
-    /** Whitelisted agent config fields allowed via PUT /v1/config. */
-    static AGENT_CONFIG_FIELDS = new Set([
-        'maxIterations',
-        'maxToolCalls',
-        'ragQueryK',
-        'toolUnavailableTtlMs',
-        'showReasoning',
-        'historyAutoSummarizeLimit',
-        'classificationEnabled',
-    ]);
-    async _handleConfigUpdate(req, res, smartAgent) {
-        const raw = await readBody(req);
-        let parsed;
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(jsonError('Invalid JSON body', 'invalid_request_error'));
-            return;
-        }
-        if (typeof parsed !== 'object' ||
-            parsed === null ||
-            Array.isArray(parsed)) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(jsonError('Request body must be a JSON object', 'invalid_request_error'));
-            return;
-        }
-        const body = parsed;
-        // --- Validate agent fields against whitelist ---
-        if (body.agent !== undefined) {
-            if (typeof body.agent !== 'object' ||
-                body.agent === null ||
-                Array.isArray(body.agent)) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(jsonError('"agent" must be a JSON object', 'invalid_request_error'));
-                return;
-            }
-            const agentFields = body.agent;
-            const unsupported = Object.keys(agentFields).filter((k) => !SmartServer.AGENT_CONFIG_FIELDS.has(k));
-            if (unsupported.length > 0) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(jsonError(`Unsupported agent config fields: ${unsupported.join(', ')}`, 'invalid_request_error'));
-                return;
-            }
-        }
-        // --- Validate and resolve models (atomic: resolve ALL before mutating) ---
-        let resolvedModels;
-        if (body.models !== undefined) {
-            if (typeof body.models !== 'object' ||
-                body.models === null ||
-                Array.isArray(body.models)) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(jsonError('"models" must be a JSON object', 'invalid_request_error'));
-                return;
-            }
-            if (!this.cfg.modelResolver) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(jsonError('model resolver not configured', 'invalid_request_error'));
-                return;
-            }
-            const modelFields = body.models;
-            const validKeys = new Set([
-                'mainModel',
-                'classifierModel',
-                'helperModel',
-            ]);
-            const unknownKeys = Object.keys(modelFields).filter((k) => !validKeys.has(k));
-            if (unknownKeys.length > 0) {
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(jsonError(`Unknown model fields: ${unknownKeys.join(', ')}`, 'invalid_request_error'));
-                return;
-            }
-            try {
-                const resolver = this.cfg.modelResolver;
-                const [mainLlm, classifierLlm, helperLlm] = await Promise.all([
-                    modelFields.mainModel
-                        ? resolver.resolve(String(modelFields.mainModel), 'main')
-                        : undefined,
-                    modelFields.classifierModel
-                        ? resolver.resolve(String(modelFields.classifierModel), 'classifier')
-                        : undefined,
-                    modelFields.helperModel
-                        ? resolver.resolve(String(modelFields.helperModel), 'helper')
-                        : undefined,
-                ]);
-                resolvedModels = {};
-                if (mainLlm)
-                    resolvedModels.mainLlm = mainLlm;
-                if (classifierLlm)
-                    resolvedModels.classifierLlm = classifierLlm;
-                if (helperLlm)
-                    resolvedModels.helperLlm = helperLlm;
-            }
-            catch (err) {
-                res.writeHead(500, { 'Content-Type': 'application/json' });
-                res.end(jsonError(String(err), 'server_error'));
-                return;
-            }
-        }
-        // --- All validation passed — apply mutations ---
-        if (resolvedModels) {
-            smartAgent.reconfigure(resolvedModels);
-            // Mirror onto the hoisted globals consumed by `buildSessionAgent` so
-            // freshly-built session graphs pick up the new LLMs by reference
-            // (otherwise `this._mainLlm` etc. would keep pointing at the originals
-            // captured during `start()`).
-            if (resolvedModels.mainLlm)
-                this._mainLlm = resolvedModels.mainLlm;
-            if (resolvedModels.classifierLlm)
-                this._classifierLlm = resolvedModels.classifierLlm;
-            if (resolvedModels.helperLlm)
-                this._helperLlm = resolvedModels.helperLlm;
-        }
-        if (body.agent) {
-            const patch = body.agent;
-            smartAgent.applyConfigUpdate(patch);
-            // Mirror onto `this.cfg.agent` so freshly-built session graphs (which
-            // read `this.cfg.agent` in `buildSessionAgent`) observe the update.
-            // Deep-merge to preserve untouched startup fields; replacing the whole
-            // `agent` block would drop YAML defaults the validator already applied.
-            const merged = {
-                ...(this.cfg.agent ?? {}),
-                ...patch,
-            };
-            this.cfg.agent = merged;
-        }
-        // Invalidate per-session SmartAgents + the worker-LLM cache so the next
-        // request mints a session graph that observes the just-applied config.
-        // Without this, chat routes dispatch to `graph.agent` (the per-session
-        // SmartAgent) which was built with the OLD config, and the PUT is a
-        // no-op from the consumer's perspective. Failures are non-fatal so the
-        // 200 response isn't blocked by a dispose hiccup.
-        if (resolvedModels || body.agent) {
-            // Fix #21: drain per-worker SmartAgentHandle.close() BEFORE clearing the
-            // cache so MCP clients owned by the discarded handles disconnect.
-            await drainWorkerCache(this._workerLlmCache);
-            try {
-                await this._lifecycle?.invalidateAll();
-            }
-            catch {
-                // Swallow: cleanup errors must not turn a successful config update
-                // into a 500. The next request will still get a fresh build because
-                // `_workerLlmCache` is already cleared and dispose is idempotent.
-            }
-        }
-        // --- Return updated config ---
-        const models = smartAgent.getActiveConfig();
-        const agent = smartAgent.getAgentConfig();
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ models, agent }));
+    /**
+     * Build the PUT /v1/config hot-swap seam over this server's private state.
+     * The setters write the SAME `_mainLlm`/`_classifierLlm`/`_helperLlm` fields
+     * RoleLlmResolver's live accessors read, so the hot-swap stays observable.
+     * A private object literal — NOT `implements` — so the public class shape is
+     * unchanged (byte-stable public API).
+     */
+    _configUpdateTarget() {
+        return {
+            modelResolver: this.cfg.modelResolver,
+            setMainLlm: (llm) => {
+                this._mainLlm = llm;
+            },
+            setClassifierLlm: (llm) => {
+                this._classifierLlm = llm;
+            },
+            setHelperLlm: (llm) => {
+                this._helperLlm = llm;
+            },
+            mirrorAgentCfg: (patch) => {
+                const merged = {
+                    ...(this.cfg.agent ?? {}),
+                    ...patch,
+                };
+                this.cfg.agent = merged;
+            },
+            drainWorkers: () => this._workers.drain(),
+            invalidateSessions: () => this._lifecycle?.invalidateAll() ?? Promise.resolve(),
+        };
     }
 }
+/** Build a runnable agent for any configured pipeline WITHOUT binding a port.
+ *  `SmartServer.start()` is the default impl that adds HTTP `listen` on top. */
+export async function buildAgent(cfg, deps) {
+    const server = new SmartServer(cfg, deps);
+    const built = await server._buildEmbeddedAgent();
+    return { agent: built.agent, close: built.close };
+}
 //# sourceMappingURL=smart-server.js.map