@mcp-abap-adt/llm-agent-server 16.2.0 → 17.0.0

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

@@ -4,10 +4,11 @@
 import { randomUUID } from 'node:crypto';
 import http from 'node:http';
 import { AdapterValidationError, normalizeAndValidateExternalTools, QueryEmbedding, toToolCallDelta, } from '@mcp-abap-adt/llm-agent';
-import { ClaudeSkillManager, CodexSkillManager, ConfigWatcher, DefaultSubAgentContextBuilder, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, makeLlm, SessionLogger, SmartAgentBuilder, SmartAgentSubAgent, } from '@mcp-abap-adt/llm-agent-libs';
+import { ClaudeSkillManager, CodexSkillManager, ConfigWatcher, DefaultSubAgentContextBuilder, FileSystemPluginLoader, FileSystemSkillManager, getDefaultPluginDirs, HealthChecker, makeLlm, SessionGraphFactory, SessionLogger, SessionRegistry, SmartAgentBuilder, SmartAgentSubAgent, SubAgentStateOracle, } from '@mcp-abap-adt/llm-agent-libs';
 import { makeRag } from '@mcp-abap-adt/llm-agent-rag';
 import { PACKAGE_VERSION } from '../generated/version.js';
 import { resolveAgentEmbedder, resolveToolsStoreEmbedder, } from './resolve-agent-embedder.js';
+import { resolveSessionIdentity } from './session-identity-resolver.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -65,11 +66,198 @@ const CORS_HEADERS = {
 // ---------------------------------------------------------------------------
 // SmartServer
 // ---------------------------------------------------------------------------
-import { resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorPlanning, resolveToolSelectionStrategy, } from './config.js';
+import { buildDagCoordinatorDeps } from './build-dag-coordinator-deps.js';
+import { assertCoordinatorConfigShape, normalizeLlmConfig, resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorDispatchKind, resolveCoordinatorPlanning, resolveLlmConfig, resolveLlmConfigStrict, resolveToolSelectionStrategy, } from './config.js';
 export { generateConfigTemplate, loadYamlConfig, resolveCoordinatorActivation, resolveCoordinatorDispatch, resolveCoordinatorPlanning, resolveEnvVars, resolveSmartServerConfig, resolveToolSelectionStrategy, YAML_TEMPLATE, } from './config.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,
+    });
+    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,
+    };
+}
 export class SmartServer {
     cfg;
     noop = () => { };
+    /**
+     * GLOBAL per-worker LLM/embedder cache. 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).
+     */
+    _workerLlmCache = new Map();
+    /** Lifecycle handle wired in `start()`; consumed by `_handle`. */
+    _lifecycle;
+    /** Hoisted globals used by `buildSessionAgent` to re-wire fresh per-session workers. */
+    _mainLlm;
+    _classifierLlm;
+    _helperLlm;
+    _fileLogger;
+    _mergedEmbedderFactories;
+    /**
+     * Captured DAG coordinator template — `deps` are stateless or LLM-bound and
+     * are reused across sessions; only `workers` + `stateOracle` are re-wired per
+     * session (review HIGH #1).
+     */
+    _dagCoordinatorTemplate;
     constructor(config) {
         this.cfg = config;
     }
@@ -78,38 +266,63 @@ export class SmartServer {
         const fileLogger = {
             log: (e) => log(e),
         };
+        this._fileLogger = fileLogger;
         const pipeline = this.cfg.pipeline;
         // ---- Composition root: resolve config → interfaces --------------------
-        // LLM resolution
-        const mainTemp = Number(pipeline?.llm?.main?.temperature ?? this.cfg.llm.temperature ?? 0.7);
+        // LLM resolution — normalize flat/map cfg.llm and derive pipeline fallback.
+        const llmMap = normalizeLlmConfig(this.cfg.llm);
+        // Adapt pipeline.llm.main (uses `baseURL`) → SmartServerLlmConfig (uses
+        // `url`) so resolveLlmConfig's pipelineFallback parameter speaks one
+        // shape. Returns undefined when no pipeline.llm.main is configured.
+        const pipelineFallback = (() => {
+            const pm = pipeline?.llm?.main;
+            if (!pm)
+                return undefined;
+            return {
+                provider: pm.provider,
+                apiKey: pm.apiKey ?? '',
+                url: pm.baseURL,
+                model: pm.model,
+                temperature: pm.temperature,
+            };
+        })();
+        const topMain = resolveLlmConfig(llmMap, 'main', pipelineFallback);
+        const mainTemp = Number(pipeline?.llm?.main?.temperature ?? topMain?.temperature ?? 0.7);
         const mainLlm = pipeline?.llm?.main
             ? await makeLlm(pipeline.llm.main, mainTemp)
-            : await makeLlm({
-                // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                // rejects a missing flat-schema provider before this runs.
-                provider: this.cfg.llm.provider ?? 'deepseek',
-                apiKey: this.cfg.llm.apiKey,
-                baseURL: this.cfg.llm.url,
-                model: this.cfg.llm.model,
-            }, mainTemp);
+            : topMain
+                ? await makeLlm({
+                    provider: topMain.provider ?? 'deepseek',
+                    apiKey: topMain.apiKey,
+                    baseURL: topMain.url,
+                    model: topMain.model,
+                }, mainTemp)
+                : (() => {
+                    throw new Error('no LLM configured: provide top-level llm.main or pipeline.llm.main');
+                })();
         const classifierTemp = Number(pipeline?.llm?.classifier?.temperature ??
-            this.cfg.llm.classifierTemperature ??
+            topMain?.classifierTemperature ??
             0.1);
         const classifierLlm = pipeline?.llm?.classifier
             ? await makeLlm(pipeline.llm.classifier, classifierTemp)
             : pipeline?.llm?.main
                 ? await makeLlm(pipeline.llm.main, classifierTemp)
-                : await makeLlm({
-                    // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                    // rejects a missing flat-schema provider before this runs.
-                    provider: this.cfg.llm.provider ?? 'deepseek',
-                    apiKey: this.cfg.llm.apiKey,
-                    baseURL: this.cfg.llm.url,
-                    model: this.cfg.llm.model,
-                }, classifierTemp);
+                : topMain
+                    ? await makeLlm({
+                        provider: topMain.provider ?? 'deepseek',
+                        apiKey: topMain.apiKey,
+                        baseURL: topMain.url,
+                        model: topMain.model,
+                    }, classifierTemp)
+                    : (() => {
+                        throw new Error('no LLM configured: provide top-level llm.main or pipeline.llm.main');
+                    })();
         const helperLlm = pipeline?.llm?.helper
             ? await makeLlm(pipeline.llm.helper, Number(pipeline.llm.helper.temperature ?? 0.1))
             : undefined;
+        this._mainLlm = mainLlm;
+        this._classifierLlm = classifierLlm;
+        this._helperLlm = helperLlm;
         // ---- Plugin loader -------------------------------------------------------
         const pluginLoader = this.cfg.pluginLoader ??
             (() => {
@@ -143,6 +356,7 @@ export class SmartServer {
             ...plugins.embedderFactories,
             ...this.cfg.embedderFactories, // config takes precedence over plugins
         };
+        this._mergedEmbedderFactories = mergedEmbedderFactories;
         // Resolve the embedder ONCE so the same instance feeds both makeRag and the
         // subagent context-builder's toolSource (#137). See resolve-agent-embedder.
         let resolvedEmbedder = await resolveAgentEmbedder(this.cfg.rag, this.cfg.embedder, mergedEmbedderFactories);
@@ -267,8 +481,9 @@ export class SmartServer {
         // 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.
+        // Hoisted so the DAG branch below can reuse the same instances.
+        const registry = new Map();
         if (this.cfg.subAgentConfigs && this.cfg.subAgentConfigs.length > 0) {
-            const registry = new Map();
             for (const sub of this.cfg.subAgentConfigs) {
                 const subAgent = await this.buildSubAgent(sub.name, sub.config, fileLogger, mergedEmbedderFactories);
                 registry.set(sub.name, new SmartAgentSubAgent(sub.name, subAgent, {
@@ -285,51 +500,128 @@ export class SmartServer {
         // ---- Coordinator (autonomous plan-execute loop) ------------------------
         const coordCfg = this.cfg.coordinatorYaml;
         if (coordCfg) {
-            // Pick the planner LLM. Default 'main' → reuse mainLlm; 'planner' or
-            // 'helper' → helperLlm if present, else fall back to mainLlm.
-            const plannerLlm = coordCfg.plannerLlm === 'main' ? mainLlm : (helperLlm ?? mainLlm);
-            // For 'skill-steps' planning the default dispatch is 'hybrid' rather
-            // than 'subagent': skill-step `agent:` is optional, so steps without
-            // an explicit agent need a self-LLM fallback. Users can still pin
-            // dispatch: subagent explicitly when every step declares `agent:`.
-            const planningKind = coordCfg.planning ?? 'one-shot';
-            const dispatchKind = coordCfg.dispatch ??
-                (planningKind === 'skill-steps' ? 'hybrid' : 'subagent');
-            // Build the same kind of context builder SmartAgentBuilder uses, so
-            // YAML-configured deployments get the same default behavior. Uses the
-            // embedder resolved above — DI-injected (this.cfg.embedder) when present,
-            // otherwise constructed from `rag.embedder` (#137). Stays undefined for
-            // bare in-memory BM25 stores (no embedder), in which case toolSource is
-            // skipped and constrained subagents fall back to empty context.
-            const mainEmbedder = resolvedEmbedder;
-            const toolSource = mainEmbedder && toolsRag
-                ? async (text, k, signal) => {
-                    const embedding = new QueryEmbedding(text, mainEmbedder, {
-                        signal,
-                    });
-                    const r = await toolsRag.query(embedding, k, { signal });
-                    return r.ok ? r.value : [];
+            // Fail loud if the config mixes DAG and linear fields.
+            assertCoordinatorConfigShape(coordCfg);
+            if (coordCfg.planner !== undefined) {
+                // DAG mode: `planner` field present → use DagCoordinatorHandler.
+                // planner shape/type already validated by assertCoordinatorConfigShape.
+                // Validate interpreter.type if present — only 'dag' is supported.
+                const interpKind = coordCfg.interpreter?.type;
+                if (interpKind !== undefined && interpKind !== 'dag') {
+                    throw new Error(`coordinator.interpreter: unknown type '${interpKind}' (only 'dag' is supported)`);
                 }
-                : undefined;
-            const contextBuilder = new DefaultSubAgentContextBuilder({ toolSource });
-            builder = builder.withCoordinator({
-                planning: resolveCoordinatorPlanning(planningKind, plannerLlm),
-                dispatch: resolveCoordinatorDispatch(dispatchKind, plannerLlm, contextBuilder),
-                // Default to 'explicit' — the presence of a `coordinator:` block in
-                // YAML is itself the opt-in signal. Users that want the auto-fallback
-                // semantics (no subagents and no skill steps → tool-loop) must set
-                // `activation: auto` explicitly.
-                activation: resolveCoordinatorActivation(coordCfg.activation ?? 'explicit'),
-                plannerLlm,
-                maxSteps: coordCfg.maxSteps,
-                maxRetriesPerStep: coordCfg.maxRetriesPerStep,
-                failPolicy: coordCfg.failPolicy,
-                maxLayer: coordCfg.maxLayer,
-            });
-            log({ event: 'coordinator_configured', config: coordCfg });
+                const built = await buildDagCoordinatorDeps({
+                    coordCfg: coordCfg,
+                    llmMap,
+                    pipelineFallback,
+                    mainLlm,
+                    helperLlm,
+                    mainTemp,
+                    registry,
+                    makeLlm: async (lc) => makeLlm({
+                        provider: lc.provider ?? 'deepseek',
+                        apiKey: lc.apiKey,
+                        baseURL: lc.url,
+                        model: lc.model,
+                    }, Number(lc.temperature ?? mainTemp)),
+                    warn: (m) => log({ event: 'config_warning', message: m }),
+                });
+                // built is defined when coordCfg.planner !== undefined.
+                if (!built) {
+                    throw new Error('internal: buildDagCoordinatorDeps returned undefined despite planner present');
+                }
+                const { oracleName, ...deps } = built;
+                builder = builder.withDagCoordinator(deps);
+                // Capture template for per-session re-wire (workers + stateOracle are
+                // re-wired per session; everything else is stateless or LLM-bound).
+                this._dagCoordinatorTemplate = {
+                    deps: {
+                        planner: deps.planner,
+                        interpreter: deps.interpreter,
+                        activation: deps.activation,
+                        reviewer: deps.reviewer,
+                        errorStrategy: deps.errorStrategy,
+                        finalizer: deps.finalizer,
+                        maxRoundTrips: deps.maxRoundTrips,
+                    },
+                    oracleName,
+                };
+                log({ event: 'dag_coordinator_configured', config: coordCfg });
+            }
+            else {
+                // Linear mode: route plannerLlm through the normalized map chain.
+                // Priority: map[name] → 'helper'/'planner' alias (helperLlm) →
+                //   pipelineFallback → mainLlm.
+                const linearPlannerName = coordCfg.plannerLlm;
+                // Role-resolution order:
+                //   1. explicit map[name]            → build from that entry
+                //   2. name === 'helper' | 'planner' → reuse prebuilt helperLlm
+                //   3. unknown name                  → resolveLlmConfig fallback chain (map.main → pipelineFallback)
+                //   4. no name                       → mainLlm
+                const linearPlannerCfgStrict = resolveLlmConfigStrict(llmMap, linearPlannerName);
+                const plannerLlm = linearPlannerCfgStrict
+                    ? await makeLlm({
+                        provider: linearPlannerCfgStrict.provider ?? 'deepseek',
+                        apiKey: linearPlannerCfgStrict.apiKey,
+                        baseURL: linearPlannerCfgStrict.url,
+                        model: linearPlannerCfgStrict.model,
+                    }, Number(linearPlannerCfgStrict.temperature ?? mainTemp))
+                    : linearPlannerName === 'helper' || linearPlannerName === 'planner'
+                        ? (helperLlm ?? mainLlm)
+                        : linearPlannerName
+                            ? // Unknown name, not an alias — try pipelineFallback last.
+                                await (async () => {
+                                    const fb = resolveLlmConfig(llmMap, linearPlannerName, pipelineFallback);
+                                    return fb
+                                        ? makeLlm({
+                                            provider: fb.provider ?? 'deepseek',
+                                            apiKey: fb.apiKey,
+                                            baseURL: fb.url,
+                                            model: fb.model,
+                                        }, Number(fb.temperature ?? mainTemp))
+                                        : mainLlm;
+                                })()
+                            : mainLlm;
+                const planningKind = coordCfg.planning ?? 'one-shot';
+                const dispatchKind = resolveCoordinatorDispatchKind(coordCfg.dispatch);
+                // Build the same kind of context builder SmartAgentBuilder uses, so
+                // YAML-configured deployments get the same default behavior. Uses the
+                // embedder resolved above — DI-injected (this.cfg.embedder) when present,
+                // otherwise constructed from `rag.embedder` (#137). Stays undefined for
+                // bare in-memory BM25 stores (no embedder), in which case toolSource is
+                // skipped and constrained subagents fall back to empty context.
+                const mainEmbedder = resolvedEmbedder;
+                const toolSource = mainEmbedder && toolsRag
+                    ? async (text, k, signal) => {
+                        const embedding = new QueryEmbedding(text, mainEmbedder, {
+                            signal,
+                        });
+                        const r = await toolsRag.query(embedding, k, { signal });
+                        return r.ok ? r.value : [];
+                    }
+                    : undefined;
+                const contextBuilder = new DefaultSubAgentContextBuilder({
+                    toolSource,
+                });
+                builder = builder.withCoordinator({
+                    planning: resolveCoordinatorPlanning(planningKind, plannerLlm),
+                    dispatch: resolveCoordinatorDispatch(dispatchKind, plannerLlm, contextBuilder),
+                    // Default to 'explicit' — the presence of a `coordinator:` block in
+                    // YAML is itself the opt-in signal. Users that want the auto-fallback
+                    // semantics (no subagents and no skill steps → tool-loop) must set
+                    // `activation: auto` explicitly.
+                    activation: resolveCoordinatorActivation(coordCfg.activation ?? 'explicit'),
+                    plannerLlm,
+                    maxSteps: coordCfg.maxSteps,
+                    maxRetriesPerStep: coordCfg.maxRetriesPerStep,
+                    failPolicy: coordCfg.failPolicy,
+                });
+                log({ event: 'coordinator_configured', config: coordCfg });
+            }
         }
         const agentHandle = await builder.build();
         const { agent: smartAgent, chat, streamChat, close: closeAgent, circuitBreakers, ragStores, modelProvider, } = agentHandle;
+        const { ragRegistry: globalRagRegistry, mcpClients: globalMcpClients } = agentHandle;
         // ---- API adapter map (built-in → config DI; DI wins) --------------------
         const { OpenAiApiAdapter, AnthropicApiAdapter } = await import('@mcp-abap-adt/llm-agent');
         const adapterMap = new Map();
@@ -345,6 +637,35 @@ export class SmartServer {
             }
         }
         const closeFns = [closeAgent];
+        // ---- Per-session lifecycle (cookie identity + graph factory + registry) ----
+        const sessionCfg = this.cfg.session ?? {};
+        const idleTtlMs = sessionCfg.idleTtlMs ?? 7_200_000;
+        const lifecycle = buildSessionLifecycle({
+            idleTtlMs,
+            maxSessions: sessionCfg.maxSessions ?? 1000,
+            cookieName: sessionCfg.cookieName ?? 'sid',
+            mcpClients: globalMcpClients,
+            toolsRag,
+            ragRegistry: globalRagRegistry,
+            buildAgent: (parts) => this.buildSessionAgent(parts),
+            logger: fileLogger,
+        });
+        this._lifecycle = lifecycle;
+        const sweepMs = Math.min(idleTtlMs, 60_000);
+        const sweep = setInterval(() => {
+            void lifecycle.evictIdle();
+        }, sweepMs);
+        sweep.unref?.();
+        closeFns.push(async () => {
+            clearInterval(sweep);
+            await lifecycle.disposeAll();
+            // Fix #21: per-session graphs may reference worker MCP clients, so
+            // dispose them FIRST (above), THEN drain per-worker handle.close so the
+            // 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);
+        });
         const startTime = Date.now();
         const healthChecker = new HealthChecker({
             agent: smartAgent,
@@ -383,7 +704,59 @@ export class SmartServer {
                     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];
+                        }
+                    }
+                    if (Object.keys(agentPatch).length > 0) {
+                        const mergedAgent = {
+                            ...(this.cfg.agent ??
+                                {}),
+                            ...agentPatch,
+                        };
+                        this.cfg.agent =
+                            mergedAgent;
+                    }
+                    if (update.prompts?.ragTranslate !== undefined ||
+                        update.prompts?.historySummary !== undefined) {
+                        const mergedPrompts = {
+                            ...(this.cfg.prompts ??
+                                {}),
+                        };
+                        if (update.prompts?.ragTranslate !== undefined) {
+                            mergedPrompts.ragTranslate = update.prompts.ragTranslate;
+                        }
+                        if (update.prompts?.historySummary !== undefined) {
+                            mergedPrompts.historySummary = update.prompts.historySummary;
+                        }
+                        this.cfg.prompts =
+                            mergedPrompts;
+                    }
                 }
+                // 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) {
@@ -422,9 +795,17 @@ export class SmartServer {
                 resolve({
                     port: actualPort,
                     close: async () => {
+                        // 1. Stop accepting new connections AND wait for in-flight HTTP
+                        //    requests to drain. Until server.close() resolves, requests
+                        //    accepted before shutdown may still be running and pinning
+                        //    per-session graphs — disposing those graphs first would
+                        //    violate the active-request pinning guarantee.
+                        await new Promise((res, rej) => server.close((e) => (e ? rej(e) : res())));
+                        // 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();
-                        await new Promise((res, rej) => server.close((e) => (e ? rej(e) : res())));
                     },
                     requestLogger,
                 });
@@ -447,37 +828,93 @@ export class SmartServer {
      * rejected at config-parse time, so `subCfg.subAgentConfigs` is
      * always undefined here.
      */
-    async buildSubAgent(name, subCfg, parentLogger, embedderFactories) {
-        if (!subCfg.llm?.apiKey && !subCfg.pipeline?.llm?.main) {
+    async buildSubAgent(name, subCfg, parentLogger, embedderFactories, injected) {
+        // Normalize subagent llm: either flat { provider, apiKey, ... } or a map
+        // { main: {...}, planner: {...} }. normalizeLlmConfig wraps flat shape as
+        // { main: flat } so downstream code always reads from .main.
+        const subLlmMap = normalizeLlmConfig(subCfg.llm);
+        const subLlmMain = subLlmMap?.main;
+        if (!subLlmMain?.apiKey &&
+            subLlmMain?.provider !== 'sap-ai-sdk' &&
+            subLlmMain?.provider !== 'ollama' &&
+            !subCfg.pipeline?.llm?.main) {
             throw new Error(`subagent '${name}': LLM API key is required`);
         }
         const subPipeline = subCfg.pipeline;
-        const mainTemp = Number(subPipeline?.llm?.main?.temperature ?? subCfg.llm.temperature ?? 0.7);
-        const mainLlm = subPipeline?.llm?.main
-            ? await makeLlm(subPipeline.llm.main, mainTemp)
-            : await makeLlm({
-                // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                // rejects a missing flat-schema provider before this runs.
-                provider: subCfg.llm.provider ?? 'deepseek',
-                apiKey: subCfg.llm.apiKey,
-                baseURL: subCfg.llm.url,
-                model: subCfg.llm.model,
-            }, mainTemp);
+        // LLM/embedder clients: when the per-session re-wire injected them, use
+        // those cached instances by reference (NEVER reconstruct). Otherwise (the
+        // primary build()), build-once via the cache so the global agent build
+        // also populates it and later per-session re-wires reuse the SAME
+        // instances.
+        // Note: a per-worker embedder slot is carried in WorkerLlmSet and the
+        // injected record for forward-compat with Task A8/A10 per-session wiring.
+        // Today's buildSubAgent does not separately resolve an embedder here —
+        // embedders are carried by the worker's own store via makeRag's
+        // `injectedEmbedder` — so we ignore the embedder field below.
+        // Resolve (build-once or load from cache) the worker's own LLMs +
+        // toolsRag/historyRag/mcpClients. The cache is keyed by worker name; the
+        // primary build() populates it (no `injected` arg), and per-session
+        // re-wires (`injected` set) read from it via the same call below — the
+        // cache hit short-circuits all factories. This keeps the worker's
+        // declared RAG/MCP intact across per-session re-wires (review HIGH #1).
+        const subFlatLlm = subLlmMain;
+        const mainTemp = Number(subPipeline?.llm?.main?.temperature ?? subFlatLlm?.temperature ?? 0.7);
         const classifierTemp = Number(subPipeline?.llm?.classifier?.temperature ??
-            subCfg.llm.classifierTemperature ??
+            subFlatLlm?.classifierTemperature ??
             0.1);
-        const classifierLlm = subPipeline?.llm?.classifier
-            ? await makeLlm(subPipeline.llm.classifier, classifierTemp)
-            : subPipeline?.llm?.main
-                ? await makeLlm(subPipeline.llm.main, classifierTemp)
-                : await makeLlm({
-                    // ?? 'deepseek' is a TS type-narrowing net only; the config validator
-                    // rejects a missing flat-schema provider before this runs.
-                    provider: subCfg.llm.provider ?? 'deepseek',
-                    apiKey: subCfg.llm.apiKey,
-                    baseURL: subCfg.llm.url,
-                    model: subCfg.llm.model,
-                }, classifierTemp);
+        const cached = await resolveWorkerLlmSet({
+            name,
+            cache: this._workerLlmCache,
+            // Preserve the existing makeLlm derivation exactly.
+            makeMain: () => subPipeline?.llm?.main
+                ? makeLlm(subPipeline.llm.main, mainTemp)
+                : makeLlm({
+                    // ?? 'deepseek' is a TS type-narrowing net only; the config
+                    // validator rejects a missing flat-schema provider before
+                    // this runs.
+                    provider: subFlatLlm?.provider ?? 'deepseek',
+                    apiKey: subFlatLlm?.apiKey ?? '',
+                    baseURL: subFlatLlm?.url,
+                    model: subFlatLlm?.model,
+                }, mainTemp),
+            makeClassifier: () => subPipeline?.llm?.classifier
+                ? makeLlm(subPipeline.llm.classifier, classifierTemp)
+                : subPipeline?.llm?.main
+                    ? makeLlm(subPipeline.llm.main, classifierTemp)
+                    : makeLlm({
+                        provider: subFlatLlm?.provider ?? 'deepseek',
+                        apiKey: subFlatLlm?.apiKey ?? '',
+                        baseURL: subFlatLlm?.url,
+                        model: subFlatLlm?.model,
+                    }, classifierTemp),
+            makeHelper: subPipeline?.llm?.helper
+                ? ((h) => () => makeLlm(h, Number(h.temperature ?? 0.1)))(subPipeline.llm.helper)
+                : undefined,
+            // Worker-OWN tools RAG (from subCfg.rag, if declared). Built once;
+            // re-wired per-session by reference — never re-vectorized.
+            makeToolsRag: subCfg.rag
+                ? () => makeRag(subCfg.rag, {
+                    injectedEmbedder: subCfg.embedder,
+                    extraFactories: embedderFactories,
+                })
+                : undefined,
+            makeHistoryRag: subCfg.rag
+                ? () => makeRag({ ...subCfg.rag }, {
+                    injectedEmbedder: subCfg.embedder,
+                    extraFactories: embedderFactories,
+                })
+                : undefined,
+            // Worker-OWN MCP clients. DI list (subCfg.mcpClients) wins; otherwise
+            // SmartAgentBuilder's own MCP-connect path handles `subCfg.mcp` — we
+            // don't pre-build those here (connection is the builder's job and is
+            // not safe to invoke twice). The cache stores the DI clients only.
+            makeMcpClients: subCfg.mcpClients && subCfg.mcpClients.length > 0
+                ? async () => subCfg.mcpClients
+                : undefined,
+        });
+        const mainLlm = cached.mainLlm;
+        const classifierLlm = cached.classifierLlm;
+        const helperLlm = cached.helperLlm;
         let subBuilder = new SmartAgentBuilder({
             mcp: subPipeline?.mcp ?? subCfg.mcp,
             agent: subCfg.agent,
@@ -488,27 +925,184 @@ export class SmartServer {
             .withClassifierLlm(classifierLlm)
             .withLogger(parentLogger)
             .withMode(subCfg.mode ?? 'smart');
-        if (subPipeline?.llm?.helper) {
-            const helperLlm = await makeLlm(subPipeline.llm.helper, Number(subPipeline.llm.helper.temperature ?? 0.1));
+        if (helperLlm) {
             subBuilder = subBuilder.withHelperLlm(helperLlm);
         }
-        if (subCfg.rag) {
-            const ragOptions = {
-                injectedEmbedder: subCfg.embedder,
-                extraFactories: embedderFactories,
-            };
-            subBuilder = subBuilder.setToolsRag(await makeRag(subCfg.rag, ragOptions));
-            subBuilder = subBuilder.setHistoryRag(await makeRag({ ...subCfg.rag }, ragOptions));
+        // SHARE the parent RAG registry + session logger when injected (per-session
+        // worker re-wire). The per-call scope filter isolates by ctx.sessionId.
+        const sharedReg = resolveSubAgentRagRegistry({
+            parentRagRegistry: injected?.ragRegistry,
+        });
+        if (sharedReg)
+            subBuilder = subBuilder.setRagRegistry(sharedReg);
+        if (injected?.requestLogger) {
+            subBuilder = subBuilder.withRequestLogger(injected.requestLogger);
+        }
+        // Tools/History RAG priority (review HIGH #1):
+        //   1) worker's OWN cached toolsRag (from subCfg.rag) — built once, reused
+        //      by reference across per-session re-wires (never re-vectorized);
+        //   2) parent's injected toolsRag (fallback for workers that did not
+        //      declare their own store).
+        // History RAG: only when the worker has its own cached instance — the
+        // parent's history RAG is owned by the parent agent and is not shared.
+        if (cached.toolsRag) {
+            subBuilder = subBuilder.setToolsRag(cached.toolsRag);
+            if (cached.historyRag) {
+                subBuilder = subBuilder.setHistoryRag(cached.historyRag);
+            }
+        }
+        else if (injected?.toolsRag) {
+            subBuilder = subBuilder.setToolsRag(injected.toolsRag);
         }
         if (subCfg.skillManager) {
             subBuilder = subBuilder.withSkillManager(subCfg.skillManager);
         }
-        if (subCfg.mcpClients && subCfg.mcpClients.length > 0) {
-            subBuilder = subBuilder.withMcpClients(subCfg.mcpClients);
+        // MCP clients priority (review HIGH #1):
+        //   1) worker's OWN cached MCP clients (from subCfg.mcpClients DI) — keeps
+        //      the worker pointed at its own upstream when the parent has none;
+        //   2) parent's injected GLOBAL MCP clients (fallback) — skips re-connect.
+        // If neither is set, fall through to the builder's own MCP-connect path
+        // (which honours `subCfg.mcp`).
+        if (cached.mcpClients && cached.mcpClients.length > 0) {
+            subBuilder = subBuilder.withMcpClients(cached.mcpClients);
+        }
+        else if (injected?.mcpClients && injected.mcpClients.length > 0) {
+            subBuilder = subBuilder.withMcpClients(injected.mcpClients);
         }
         const handle = await subBuilder.build();
+        // Backfill the per-worker cache from the BUILT handle (review HIGH #7).
+        // Only runs on the primary build path (no `injected`) so per-session
+        // re-wires never overwrite the cache. See backfillWorkerCacheFromHandle's
+        // doc-comment for the rationale.
+        if (!injected) {
+            const entry = this._workerLlmCache.get(name);
+            if (entry)
+                await backfillWorkerCacheFromHandle(entry, handle);
+        }
+        return handle.agent;
+    }
+    /**
+     * Builds a per-session SmartAgent from injected globals (review HIGH #1 +
+     * MEDIUM #3). Re-wires the SubAgent registry + DAG coordinator deps FRESH per
+     * session, sharing this session's logger + the global ragRegistry/toolsRag/
+     * mcpClients + the CACHED per-worker LLM/embedder (this._workerLlmCache). It
+     * NEVER reuses the primary build()'s global `registry`/DAG-deps and NEVER
+     * constructs new LLM clients.
+     */
+    async buildSessionAgent(parts) {
+        // Guard: globals must already be captured by the primary build() before any
+        // session graph is built (the registry calls this lazily on first acquire).
+        if (!this._mainLlm || !this._classifierLlm || !this._fileLogger) {
+            throw new Error('buildSessionAgent invoked before primary build() captured globals');
+        }
+        let b = new SmartAgentBuilder({
+            agent: this.cfg.agent,
+            prompts: this.cfg.prompts,
+            skipModelValidation: this.cfg.skipModelValidation,
+        })
+            .withMainLlm(this._mainLlm)
+            .withClassifierLlm(this._classifierLlm)
+            .withLogger(this._fileLogger)
+            .withMode(this.cfg.mode ?? 'smart')
+            .withMcpClients(parts.mcpClients) // skips connect + re-vectorize
+            .setRagRegistry(parts.ragRegistry)
+            .withRequestLogger(parts.logger); // per-session token-logger
+        if (this._helperLlm)
+            b = b.withHelperLlm(this._helperLlm);
+        if (parts.toolsRag)
+            b = b.setToolsRag(parts.toolsRag);
+        // FRESH per-session workers — re-wire the registry from the SAME subagent
+        // configs the primary build() used, injecting globals + this session's
+        // logger + the CACHED per-worker LLM/embedder. No LLM reconstruction.
+        if (this.cfg.subAgentConfigs && this.cfg.subAgentConfigs.length > 0) {
+            const registry = new Map();
+            for (const sub of this.cfg.subAgentConfigs) {
+                // Lazy build-on-miss (Fix #18). After PUT /v1/config or hot-reload
+                // clears `_workerLlmCache`, the next buildSessionAgent 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,
+                }));
+            }
+            b = b.withSubAgents(registry);
+            if (this._dagCoordinatorTemplate) {
+                const tpl = this._dagCoordinatorTemplate;
+                const workers = new Map([...registry].filter(([name]) => name !== tpl.oracleName));
+                const raw = tpl.oracleName ? registry.get(tpl.oracleName) : undefined;
+                b = b.withDagCoordinator({
+                    ...tpl.deps,
+                    workers,
+                    stateOracle: raw ? new SubAgentStateOracle(raw) : undefined,
+                });
+            }
+        }
+        const handle = await b.build();
         return handle.agent;
     }
+    /**
+     * Resolve identity (mint cookie when needed), acquire the per-session graph,
+     * run `fn` pinned, and release in `finally`. Order in `finally`:
+     *   1. drop the per-traceId logger delta (server-owned free, review HIGH #2)
+     *   2. release the refcount pin
+     */
+    async _withSession(req, res, fn) {
+        const lifecycle = this._lifecycle;
+        if (!lifecycle) {
+            throw new Error('SmartServer lifecycle not initialized');
+        }
+        const traceId = randomUUID();
+        const isHttps = req.socket.encrypted === true ||
+            req.headers['x-forwarded-proto'] === 'https';
+        const resolved = lifecycle.resolve(req.headers['cookie'], isHttps);
+        const sessionId = resolved.identity.sessionId;
+        if (resolved.minted && resolved.setCookie) {
+            res.setHeader('Set-Cookie', resolved.setCookie);
+        }
+        const graph = await lifecycle.acquire(sessionId);
+        try {
+            await fn(graph, sessionId, traceId);
+        }
+        finally {
+            graph.logger.dropRequest(traceId);
+            // Pass the graph instance — `invalidateAll()` may have detached this
+            // graph into the draining map while the request was in flight; we must
+            // release THIS specific instance, not whatever currently lives under
+            // `sessionId` in the registry.
+            lifecycle.release(sessionId, graph);
+        }
+    }
     async _handle(req, res, requestLogger, smartAgent, chat, streamChat, log, healthChecker, modelProvider, adapterMap) {
         const rawUrl = req.url ?? '/';
         const urlPath = rawUrl.split('?')[0].replace(/\/$/, '') || '/';
@@ -581,8 +1175,27 @@ export class SmartServer {
             return;
         }
         if (req.method === 'GET' && urlPath === '/v1/usage') {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify(requestLogger.getSummary()));
+            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;
         }
         // /v1/config or /config
@@ -622,18 +1235,22 @@ export class SmartServer {
                 res.end(jsonError('Anthropic adapter not registered', 'not_found'));
                 return;
             }
-            await this._handleAdapterRequest(req, res, smartAgent, anthropicAdapter);
+            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._handleChat(req, res, requestLogger, smartAgent, chat, streamChat, log, modelProvider);
+            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) {
+    async _handleAdapterRequest(req, res, agent, adapter, session) {
         const raw = await readBody(req);
         let body;
         try {
@@ -656,13 +1273,22 @@ export class SmartServer {
             }
             throw err;
         }
+        const augmentedOptions = session
+            ? {
+                ...normalized.options,
+                sessionId: session.sessionId,
+                trace: { traceId: session.traceId },
+                toolAvailability: session.graph.toolAvailability,
+                pendingToolResults: session.graph.pendingToolResults,
+            }
+            : normalized.options;
         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(normalized.messages, normalized.options), normalized.context)) {
+            for await (const event of adapter.transformStream(agent.streamProcess(normalized.messages, augmentedOptions), normalized.context)) {
                 const eventLine = event.event ? `event: ${event.event}\n` : '';
                 res.write(`${eventLine}data: ${event.data}\n\n`);
             }
@@ -670,7 +1296,7 @@ export class SmartServer {
             return;
         }
         // Non-streaming
-        const result = await agent.process(normalized.messages, normalized.options);
+        const result = await agent.process(normalized.messages, augmentedOptions);
         res.setHeader('Content-Type', 'application/json');
         if (!result.ok) {
             res.writeHead(500);
@@ -685,7 +1311,7 @@ export class SmartServer {
         res.writeHead(200);
         res.end(JSON.stringify(adapter.formatResult(result.value, normalized.context)));
     }
-    async _handleChat(req, res, _requestLogger, smartAgent, _chat, _streamChat, log, modelProvider) {
+    async _handleChat(req, res, _requestLogger, smartAgent, _chat, _streamChat, log, modelProvider, session) {
         const rawBody = await readBody(req);
         let parsed;
         try {
@@ -725,8 +1351,13 @@ export class SmartServer {
             res.end(jsonError('at least one message with role "user" is required', 'invalid_request_error'));
             return;
         }
-        const traceId = randomUUID();
-        const sessionId = req.headers['x-session-id'] || 'default';
+        // 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);
@@ -761,6 +1392,12 @@ export class SmartServer {
             trace: { traceId },
             sessionLogger,
             model: body.model,
+            ...(session
+                ? {
+                    toolAvailability: session.graph.toolAvailability,
+                    pendingToolResults: session.graph.pendingToolResults,
+                }
+                : {}),
             ...(body.temperature !== undefined
                 ? { temperature: body.temperature }
                 : {}),
@@ -1085,9 +1722,48 @@ export class SmartServer {
         // --- 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) {
-            smartAgent.applyConfigUpdate(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();