@relayplane/proxy 1.8.35 → 1.8.38

package/dist/standalone-proxy.js

@@ -94,6 +94,11 @@ const estimateRateMap = new Map();
 // Without this, IPs that make one request and disappear stay in the map forever.
 setInterval(() => (0, estimate_js_1.purgeExpiredRateLimitEntries)(estimateRateMap, Date.now()), 5 * 60 * 1000);
 const osmosis_store_js_1 = require("./osmosis-store.js");
+const episode_writer_js_1 = require("./episode-writer.js");
+const session_tracker_js_1 = require("./session-tracker.js");
+const trace_writer_js_1 = require("./trace-writer.js");
+const tool_router_js_1 = require("./tool-router.js");
+const node_crypto_1 = require("node:crypto");
 const PROXY_VERSION = (() => {
     try {
         const pkgPath = path.join(__dirname, '..', 'package.json');
@@ -938,6 +943,18 @@ let _activeOllamaConfig;
 function isContentLoggingEnabled() {
     return _activeProxyConfig.dashboard?.showRequestContent !== false;
 }
+/**
+ * Whether procedural knowledge hints should be injected into system prompts.
+ * Default: false — no system prompt modification occurs.
+ * Config file: memory.proceduralInjectionEnabled
+ * Env override: RELAYPLANE_PROCEDURAL_INJECTION=true
+ */
+function isProceduralInjectionEnabled() {
+    const envVal = process.env['RELAYPLANE_PROCEDURAL_INJECTION'];
+    if (envVal !== undefined)
+        return envVal === 'true';
+    return _activeProxyConfig.memory?.proceduralInjectionEnabled === true;
+}
 function getProxyConfigPath() {
     const customPath = process.env['RELAYPLANE_CONFIG_PATH'];
     if (customPath && customPath.trim())
@@ -2532,7 +2549,7 @@ th{text-align:left;color:#64748b;font-weight:500;padding:8px 12px;border-bottom:
 td{padding:8px 12px;border-bottom:1px solid #111318}
 .section{margin-bottom:32px}.section h2{font-size:1rem;font-weight:600;margin-bottom:12px;color:#94a3b8}
 .dot{display:inline-block;width:8px;height:8px;border-radius:50%;margin-right:6px}.dot.up{background:#34d399}.dot.warn{background:#fbbf24}.dot.down{background:#ef4444}
-.section.collapsible h2{cursor:pointer;user-select:none;display:flex;align-items:center;gap:8px}.section.collapsible h2::after{content:'▾';font-size:.8rem;color:#475569;transition:transform .2s}.section.collapsed h2::after{transform:rotate(-90deg)}.section.collapsed>*:not(h2){display:none}
+.section.collapsible h2{cursor:pointer;user-select:none;display:flex;align-items:center;gap:8px}.section.collapsible h2::after{content:'▾';font-size:.8rem;color:#475569;transition:transform .2s}.section.collapsed h2::after{transform:rotate(-90deg)}.section.collapsed>*:not(h2){display:none!important}
 .badge{display:inline-block;padding:2px 8px;border-radius:6px;font-size:.75rem;font-weight:500}
 .badge.ok{background:#052e1633;color:#34d399}.badge.err{background:#2d0a0a;color:#ef4444}.badge.err-auth{background:#2d0a0a;color:#ef4444}.badge.err-rate{background:#2d2a0a;color:#fbbf24}.badge.err-timeout{background:#2d1a0a;color:#fb923c}
 .badge.tt-code{background:#1e3a5f;color:#60a5fa}.badge.tt-analysis{background:#3b1f6e;color:#a78bfa}.badge.tt-summarization{background:#1a3a2a;color:#6ee7b7}.badge.tt-qa{background:#3a2f1e;color:#fbbf24}.badge.tt-general{background:#1e293b;color:#94a3b8}
@@ -2557,7 +2574,10 @@ td{padding:8px 12px;border-bottom:1px solid #111318}
 <div class="section collapsible collapsed"><h2>Agent Cost Breakdown</h2>
 <table><thead><tr><th>Agent</th><th>Requests</th><th>Total Cost</th><th>Last Active</th><th></th></tr></thead><tbody id="agents"></tbody></table></div>
 <div class="section"><h2>Provider Status</h2><div class="prov" id="providers"></div></div>
-<div class="section collapsible collapsed"><h2>Learning</h2><div id="learning-panel" style="display:flex;flex-direction:column;gap:12px"><div id="learning-stats" style="display:flex;gap:12px;flex-wrap:wrap"></div><div id="learning-recent"></div><div style="margin-top:8px;padding:10px 14px;background:#0f1720;border:1px solid #1e3a5f;border-radius:8px;font-size:.8rem;color:#60a5fa">Network: Join the network to share with 1,000+ agent installations &rarr; <a href="https://relayplane.com/pricing" style="color:#34d399">Upgrade</a></div></div></div>
+<div class="section collapsible collapsed"><h2>Learning</h2><div id="learning-panel" style="display:flex;flex-direction:column;gap:12px"><div id="learning-stats" style="display:flex;gap:12px;flex-wrap:wrap"></div><div id="learning-recent"></div></div></div>
+<div class="section collapsible collapsed" id="sessions-section"><h2>Sessions <span id="sessionsLabel" style="font-size:.75rem;color:#64748b;font-weight:400">(last 7d)</span></h2>
+<table><thead><tr><th>Session ID</th><th>Source</th><th>Started</th><th>Duration</th><th>Requests</th><th>Tokens In</th><th>Tokens Out</th><th>Cost</th><th>Models</th><th>Status</th></tr></thead><tbody id="sessions"></tbody></table>
+</div>
 <div class="section"><h2>Recent Runs <span id="historyLabel" style="font-size:.75rem;color:#64748b;font-weight:400">(7d window, history-capped)</span></h2>
 <table><thead><tr><th>Time</th><th>Agent</th><th>Model</th><th class="col-tt">Task Type</th><th class="col-cx">Complexity</th><th>Tokens In</th><th>Tokens Out</th><th class="col-cache">Cache Create</th><th class="col-cache">Cache Read</th><th>Cost</th><th>Latency</th><th>Status</th></tr></thead><tbody id="runs"></tbody></table></div>
 <script>
@@ -2566,6 +2586,28 @@ document.querySelectorAll('.section.collapsible h2').forEach(h2=>h2.addEventList
 function fmt(n,d=2){return typeof n==='number'?n.toFixed(d):'-'}
 function fmtTime(s){const d=new Date(s);return d.toLocaleTimeString()}
 function dur(s){const h=Math.floor(s/3600),m=Math.floor(s%3600/60);return h?h+'h '+m+'m':m+'m'}
+async function loadSessions(){
+  try{
+    const [sessR,activeR]=await Promise.all([
+      fetch('/v1/sessions?limit=20&days=7').then(r=>r.json()).catch(()=>({sessions:[]})),
+      fetch('/v1/sessions/active').then(r=>r.json()).catch(()=>({sessions:[]}))
+    ]);
+    const activeIds=new Set((activeR.sessions||[]).map(s=>s.id));
+    const sessions=sessR.sessions||[];
+    const el=$('sessions');
+    if(!el)return;
+    el.innerHTML=sessions.length?sessions.map(s=>{
+      const isActive=activeIds.has(s.id)||s.active;
+      const dur=s.duration_ms>0?Math.round(s.duration_ms/1000)+'s':'—';
+      const badge=isActive?'<span class="badge ok" style="font-size:.7rem">LIVE</span>':'<span style="color:#64748b;font-size:.75rem">idle</span>';
+      const srcBadge=s.session_source==='claude-code'?'<span style="color:#60a5fa;font-size:.75rem">claude-code</span>':'<span style="color:#94a3b8;font-size:.75rem">synthetic</span>';
+      const sid=s.id.length>20?s.id.slice(0,20)+'…':s.id;
+      const mix=s.model_mix&&Object.keys(s.model_mix).length?Object.entries(s.model_mix).map(([m,c])=>{const short=m.replace('claude-','').replace(/-\d{8}$/,'').replace('sonnet','Sonnet').replace('opus','Opus').replace('haiku','Haiku');return '<span style="font-size:.72rem;color:#94a3b8">'+short+'<span style="color:#475569">×</span>'+c+'</span>';}).join(' '):'<span style="color:#475569;font-size:.72rem">—</span>';
+      return '<tr><td style="font-family:monospace;font-size:.8rem" title="'+esc(s.id)+'">'+sid+'</td><td>'+srcBadge+'</td><td>'+fmtTime(new Date(s.started_at).toISOString())+'</td><td>'+dur+'</td><td>'+s.request_count+'</td><td>'+(s.total_tokens_in||0)+'</td><td>'+(s.total_tokens_out||0)+'</td><td>$'+fmt(s.total_cost_usd,4)+'</td><td>'+mix+'</td><td>'+badge+'</td></tr>';
+    }).join(''):'<tr><td colspan=10 style="color:#64748b">No sessions recorded yet</td></tr>';
+    const totalCost=sessions.reduce((s,r)=>s+(r.total_cost_usd||0),0);
+  }catch(e){console.error('sessions load error',e)}
+}
 async function load(){
   try{
     const [health,stats,runsR,sav,provH,agentsR]=await Promise.all([
@@ -2710,7 +2752,7 @@ async function loadLearning(){
     }
   }catch(e){console.error('learning load error',e)}
 }
-load();loadLearning();setInterval(load,5000);setInterval(loadLearning,30000);
+load();loadLearning();loadSessions();setInterval(load,5000);setInterval(loadLearning,30000);setInterval(loadSessions,10000);
 </script><footer style="text-align:center;padding:20px 0;color:#475569;font-size:.75rem;border-top:1px solid #1e293b;margin-top:20px">🔒 Request content stays on your machine. Never sent to cloud.</footer></body></html>`;
 }
 async function getKnowledgeStats() {
@@ -2873,12 +2915,20 @@ async function startProxy(config = {}) {
         (0, agent_tracker_js_1.flushAgentRegistry)();
         meshHandle.stop();
         shutdownHistory();
+        trace_writer_js_1.TraceWriter.getInstance().shutdown();
         process.exit(0);
     };
     process.on('SIGINT', handleShutdown);
     process.on('SIGTERM', handleShutdown);
     const configPath = getProxyConfigPath();
     let proxyConfig = await loadProxyConfig(configPath, log);
+    // ── Deterministic Traces: initialise TraceWriter with loaded config ──
+    trace_writer_js_1.TraceWriter.getInstance({
+        ...((0, trace_writer_js_1.defaultTracesConfig)()),
+        ...(proxyConfig.traces ?? {}),
+    });
+    // ── Tool Router: initialise deny-by-default tool authorization ──
+    (0, tool_router_js_1.getToolRouter)();
     // Auto-config on startup: detect available auth and set optimal routing.
     //
     // Bug fix: `configExists` was always true because loadConfig() (CLI init) creates
@@ -3243,6 +3293,12 @@ async function startProxy(config = {}) {
         }
         // === Control endpoints ===
         if (pathname.startsWith('/control/')) {
+            const remoteAddr = req.socket.remoteAddress;
+            if (remoteAddr !== '127.0.0.1' && remoteAddr !== '::1' && remoteAddr !== '::ffff:127.0.0.1') {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Control endpoints are localhost-only' }));
+                return;
+            }
             if (req.method === 'POST' && pathname === '/control/enable') {
                 proxyConfig = normalizeProxyConfig({ ...proxyConfig, enabled: true });
                 await saveProxyConfig(configPath, proxyConfig);
@@ -3306,6 +3362,224 @@ async function startProxy(config = {}) {
                 }
                 return;
             }
+            // === Budget endpoints ===
+            if (req.method === 'GET' && pathname === '/control/budget') {
+                const status = budgetManager.getStatus();
+                const cfg = budgetManager.getConfig();
+                const now = Date.now();
+                const weekCutoff = now - 7 * 86400000;
+                const monthCutoff = now - 30 * 86400000;
+                const weekCost = requestHistory
+                    .filter(r => new Date(r.timestamp).getTime() >= weekCutoff)
+                    .reduce((s, r) => s + r.costUsd, 0);
+                const monthCost = requestHistory
+                    .filter(r => new Date(r.timestamp).getTime() >= monthCutoff)
+                    .reduce((s, r) => s + r.costUsd, 0);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    today_usd: Math.round(status.dailySpend * 10000) / 10000,
+                    limit_usd: status.dailyLimit,
+                    pct_used: Math.round(status.dailyPercent * 10) / 10,
+                    remaining_usd: Math.max(0, Math.round((status.dailyLimit - status.dailySpend) * 10000) / 10000),
+                    this_week_usd: Math.round(weekCost * 10000) / 10000,
+                    this_month_usd: Math.round(monthCost * 10000) / 10000,
+                    enabled: cfg.enabled,
+                    on_breach: cfg.onBreach,
+                    alert_thresholds: cfg.alertThresholds,
+                    hourly_usd: Math.round(status.hourlySpend * 10000) / 10000,
+                    hourly_limit_usd: status.hourlyLimit,
+                    hourly_pct_used: Math.round(status.hourlyPercent * 10) / 10,
+                    breached: status.breached,
+                    breach_type: status.breachType,
+                }));
+                return;
+            }
+            if (req.method === 'POST' && pathname === '/control/budget/set') {
+                try {
+                    const body = await readJsonBody(req);
+                    const amount = Number(body.dailyUsd);
+                    if (!body.dailyUsd || isNaN(amount) || amount <= 0) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'dailyUsd must be a positive number' }));
+                        return;
+                    }
+                    budgetManager.setLimits({ dailyUsd: amount });
+                    budgetManager.updateConfig({ enabled: true });
+                    proxyConfig = normalizeProxyConfig({
+                        ...proxyConfig,
+                        budget: { ...proxyConfig.budget, dailyUsd: amount, enabled: true },
+                    });
+                    await saveProxyConfig(configPath, proxyConfig);
+                    startConfigWatcher();
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, dailyUsd: amount }));
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                }
+                return;
+            }
+            if (req.method === 'POST' && pathname === '/control/budget/set-alert') {
+                try {
+                    const body = await readJsonBody(req);
+                    const pct = Number(body.threshold);
+                    if (!body.threshold || isNaN(pct) || pct <= 0 || pct > 100) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'threshold must be 1-100' }));
+                        return;
+                    }
+                    const current = budgetManager.getConfig();
+                    const thresholds = [...new Set([...current.alertThresholds, pct])].sort((a, b) => a - b);
+                    budgetManager.updateConfig({ alertThresholds: thresholds });
+                    proxyConfig = normalizeProxyConfig({
+                        ...proxyConfig,
+                        budget: { ...proxyConfig.budget, alertThresholds: thresholds },
+                    });
+                    await saveProxyConfig(configPath, proxyConfig);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, alertThresholds: thresholds }));
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                }
+                return;
+            }
+            if (req.method === 'POST' && pathname === '/control/budget/reset') {
+                budgetManager.reset();
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, message: 'Daily spend counter reset' }));
+                return;
+            }
+            // === Session Budget endpoints ===
+            if (req.method === 'GET' && pathname === '/control/session-budget') {
+                const sbQs = url.includes('?') ? url.split('?')[1] ?? '' : '';
+                const sbParams = new URLSearchParams(sbQs);
+                const sessionId = sbParams.get('sessionId');
+                if (!sessionId) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'sessionId query parameter required' }));
+                    return;
+                }
+                const record = budgetManager.getSessionBudget(sessionId);
+                if (!record) {
+                    const cap = budgetManager.getConfig().sessionCapUsd;
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        sessionId,
+                        capUsd: cap,
+                        spentUsd: 0,
+                        remainingUsd: cap,
+                        pctUsed: 0,
+                        modelUsed: '',
+                        status: 'ok',
+                    }));
+                    return;
+                }
+                const remaining = Math.max(0, record.capUsd - record.spentUsd);
+                const pctUsed = record.capUsd > 0 ? (record.spentUsd / record.capUsd) * 100 : 0;
+                const status = pctUsed >= 100 ? 'exceeded' : pctUsed >= 80 ? 'warning' : 'ok';
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    sessionId: record.sessionId,
+                    capUsd: record.capUsd,
+                    spentUsd: record.spentUsd,
+                    remainingUsd: remaining,
+                    pctUsed: Math.round(pctUsed * 10) / 10,
+                    modelUsed: record.modelUsed,
+                    createdAt: new Date(record.createdAt).toISOString(),
+                    updatedAt: new Date(record.updatedAt).toISOString(),
+                    status,
+                }));
+                return;
+            }
+            if (req.method === 'POST' && pathname === '/control/session-budget/set') {
+                try {
+                    const body = await readJsonBody(req);
+                    if (!body.sessionId || typeof body.capUsd !== 'number' || !isFinite(body.capUsd) || body.capUsd <= 0) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'sessionId (string) and capUsd (positive number) required' }));
+                        return;
+                    }
+                    budgetManager.setSessionCap(body.sessionId, body.capUsd);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, sessionId: body.sessionId, capUsd: body.capUsd }));
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                }
+                return;
+            }
+            if (req.method === 'GET' && pathname === '/control/session-budgets') {
+                const slQs = url.includes('?') ? url.split('?')[1] ?? '' : '';
+                const slParams = new URLSearchParams(slQs);
+                const limitParam = slParams.get('limit');
+                const limit = limitParam ? Math.min(50, Math.max(1, parseInt(limitParam, 10) || 50)) : 50;
+                const records = budgetManager.listSessionBudgets(limit);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    sessions: records.map(r => ({
+                        sessionId: r.sessionId,
+                        capUsd: r.capUsd,
+                        spentUsd: r.spentUsd,
+                        remainingUsd: Math.max(0, r.capUsd - r.spentUsd),
+                        pctUsed: r.capUsd > 0 ? Math.round((r.spentUsd / r.capUsd) * 1000) / 10 : 0,
+                        modelUsed: r.modelUsed,
+                        createdAt: new Date(r.createdAt).toISOString(),
+                        updatedAt: new Date(r.updatedAt).toISOString(),
+                        status: r.spentUsd >= r.capUsd ? 'exceeded' : (r.spentUsd / r.capUsd) >= 0.8 ? 'warning' : 'ok',
+                    })),
+                    count: records.length,
+                }));
+                return;
+            }
+            if (req.method === 'POST' && pathname === '/control/model') {
+                try {
+                    const body = await readJsonBody(req);
+                    if (!body.model) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'model required' }));
+                        return;
+                    }
+                    if (body.model.length > 128 || !/^[a-zA-Z0-9._:/-]+$/.test(body.model)) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'model must be ≤128 characters and contain only [a-zA-Z0-9._:/-]' }));
+                        return;
+                    }
+                    const previousRouting = proxyConfig.routing;
+                    const target = body.model;
+                    // Update all complexity tiers to the requested model
+                    proxyConfig = normalizeProxyConfig({
+                        ...proxyConfig,
+                        routing: {
+                            ...proxyConfig.routing,
+                            complexity: {
+                                enabled: proxyConfig.routing?.complexity?.enabled ?? true,
+                                simple: target,
+                                moderate: target,
+                                complex: target,
+                            },
+                        },
+                    });
+                    await saveProxyConfig(configPath, proxyConfig);
+                    startConfigWatcher();
+                    const prevModel = previousRouting?.complexity?.complex ?? previousRouting?.complexity?.moderate ?? 'unknown';
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        switched: true,
+                        previous: prevModel,
+                        current: target,
+                        reason: body.reason ?? '',
+                    }));
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                }
+                return;
+            }
         }
         if (req.method === 'POST' && pathname === '/control/kill') {
             try {
@@ -3677,6 +3951,228 @@ async function startProxy(config = {}) {
             }
             return;
         }
+        // === Session Intelligence endpoints ===
+        if (req.method === 'GET' && (pathname === '/v1/sessions' || pathname === '/v1/sessions/active')) {
+            const remoteAddr = req.socket.remoteAddress;
+            if (remoteAddr !== '127.0.0.1' && remoteAddr !== '::1' && remoteAddr !== '::ffff:127.0.0.1') {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Session endpoints are localhost-only' }));
+                return;
+            }
+        }
+        if (req.method === 'GET' && pathname === '/v1/sessions') {
+            const queryString = url.includes('?') ? url.split('?')[1] ?? '' : '';
+            const params = new URLSearchParams(queryString);
+            const rawLimit = parseInt(params.get('limit') || '20', 10);
+            const rawDays = parseInt(params.get('days') || '7', 10);
+            const limit = Math.min(Number.isFinite(rawLimit) && rawLimit > 0 ? rawLimit : 20, 100);
+            const days = Number.isFinite(rawDays) && rawDays > 0 ? rawDays : 7;
+            const sessions = (0, session_tracker_js_1.getSessions)({ limit, days });
+            const now = Date.now();
+            const activeCutoff = now - 5 * 60 * 1000;
+            // Build model_mix per session from episodic_events in osmosis.db
+            const modelMixMap = new Map();
+            try {
+                const osmDb = (0, osmosis_store_js_1.getOsmosisDb)();
+                if (osmDb && sessions.length > 0) {
+                    const placeholders = sessions.map(() => '?').join(',');
+                    const sessionIds = sessions.map(s => s.id);
+                    const rows = osmDb.prepare(`SELECT session_id, model_used, COUNT(*) as cnt
+             FROM episodic_events
+             WHERE session_id IN (${placeholders})
+             GROUP BY session_id, model_used`).all(...sessionIds);
+                    for (const row of rows) {
+                        if (!modelMixMap.has(row.session_id))
+                            modelMixMap.set(row.session_id, {});
+                        modelMixMap.get(row.session_id)[row.model_used] = row.cnt;
+                    }
+                }
+            }
+            catch { /* best-effort */ }
+            const result = sessions.map(s => ({
+                ...s,
+                active: s.last_seen_at >= activeCutoff,
+                duration_ms: s.last_seen_at - s.started_at,
+                model_mix: modelMixMap.get(s.id) ?? {},
+            }));
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ sessions: result, total: result.length }));
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/v1/sessions/active') {
+            const active = (0, session_tracker_js_1.getActiveSessions)();
+            const now = Date.now();
+            const result = active.map(s => ({
+                ...s,
+                active: true,
+                duration_ms: s.last_seen_at - s.started_at,
+            }));
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ sessions: result, total: result.length }));
+            return;
+        }
+        // === Trace endpoints (CAP 3) ===
+        if ((req.method === 'GET' || req.method === 'POST') && (pathname === '/v1/traces' || (pathname ?? '').startsWith('/v1/traces/'))) {
+            const remoteAddr = req.socket.remoteAddress;
+            if (remoteAddr !== '127.0.0.1' && remoteAddr !== '::1' && remoteAddr !== '::ffff:127.0.0.1') {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Trace endpoints are localhost-only' }));
+                return;
+            }
+        }
+        if (req.method === 'GET' && pathname === '/v1/traces') {
+            const queryString = url.includes('?') ? url.split('?')[1] ?? '' : '';
+            const params = new URLSearchParams(queryString);
+            const limit = Math.min(parseInt(params.get('limit') ?? '20', 10) || 20, 100);
+            const traceWriter = trace_writer_js_1.TraceWriter.getInstance();
+            const traces = traceWriter.getRecentTraces(limit);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ traces, total: traces.length }));
+            return;
+        }
+        if (req.method === 'GET' && (pathname ?? '').match(/^\/v1\/traces\/([^/]+)\/graph$/)) {
+            const sessionId = (pathname ?? '').split('/')[3] ?? '';
+            const traceWriter = trace_writer_js_1.TraceWriter.getInstance();
+            const graph = traceWriter.getSessionGraph(sessionId);
+            if (!graph) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: `No graph found for session: ${sessionId}` }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(graph));
+            return;
+        }
+        if (req.method === 'GET' && (pathname ?? '').match(/^\/v1\/traces\/([^/]+)\/events$/)) {
+            const traceId = (pathname ?? '').split('/')[3] ?? '';
+            const tw = trace_writer_js_1.TraceWriter.getInstance();
+            const events = tw.getTraceEvents(traceId);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ traceId, events, total: events.length }));
+            return;
+        }
+        if (req.method === 'POST' && pathname === '/v1/traces/export') {
+            try {
+                const exportOptions = await readJsonBody(req);
+                const format = exportOptions.format ?? 'jsonl';
+                if (!['jsonl', 'csv', 'markdown', 'traceops'].includes(format)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'format must be one of: jsonl, csv, markdown, traceops' }));
+                    return;
+                }
+                const tw = trace_writer_js_1.TraceWriter.getInstance();
+                const exported = await tw.export({
+                    format: format,
+                    sessionIds: exportOptions.sessionIds,
+                    fromTimestamp: exportOptions.fromTimestamp,
+                    toTimestamp: exportOptions.toTimestamp,
+                    includeToolInputs: exportOptions.includeToolInputs,
+                });
+                const contentType = format === 'markdown' ? 'text/markdown' : 'application/x-ndjson';
+                res.writeHead(200, { 'Content-Type': contentType });
+                res.end(exported);
+            }
+            catch {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Invalid JSON body' }));
+            }
+            return;
+        }
+        // === Memory endpoints (Session 4 — localhost-only) ===
+        if ((pathname ?? '').startsWith('/v1/memory')) {
+            const remoteAddr = req.socket.remoteAddress;
+            if (remoteAddr !== '127.0.0.1' && remoteAddr !== '::1' && remoteAddr !== '::ffff:127.0.0.1') {
+                res.writeHead(403, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Memory endpoints are localhost-only' }));
+                return;
+            }
+        }
+        if (req.method === 'GET' && pathname === '/v1/memory/semantic') {
+            const queryString = url.includes('?') ? url.split('?')[1] ?? '' : '';
+            const params = new URLSearchParams(queryString);
+            const sessionId = params.get('session_id') ?? undefined;
+            const limit = Math.min(parseInt(params.get('limit') ?? '20', 10) || 20, 100);
+            try {
+                const db = (0, osmosis_store_js_1.getOsmosisDb)();
+                if (!db) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ atoms: [], total: 0 }));
+                    return;
+                }
+                let atoms;
+                if (sessionId) {
+                    atoms = db.prepare(`SELECT id, type, model, task_type, latency_ms, input_tokens, output_tokens, confidence, observation_count, timestamp, session_id
+             FROM knowledge_atoms WHERE session_id = ? ORDER BY confidence DESC, timestamp DESC LIMIT ?`).all(sessionId, limit);
+                }
+                else {
+                    atoms = db.prepare(`SELECT id, type, model, task_type, latency_ms, input_tokens, output_tokens, confidence, observation_count, timestamp, session_id
+             FROM knowledge_atoms ORDER BY confidence DESC, timestamp DESC LIMIT ?`).all(limit);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ atoms, total: atoms.length }));
+            }
+            catch {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Memory query failed' }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/v1/memory/episodic') {
+            const queryString = url.includes('?') ? url.split('?')[1] ?? '' : '';
+            const params = new URLSearchParams(queryString);
+            const sessionId = params.get('session_id') ?? undefined;
+            const limit = Math.min(parseInt(params.get('limit') ?? '50', 10) || 50, 200);
+            try {
+                const db = (0, osmosis_store_js_1.getOsmosisDb)();
+                if (!db) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ events: [], total: 0 }));
+                    return;
+                }
+                let events;
+                if (sessionId) {
+                    events = db.prepare(`SELECT id, session_id, event_type, timestamp, duration_ms, model_used, tokens_in, tokens_out, cost_usd, outcome, outcome_detail, trace_id
+             FROM episodic_events WHERE session_id = ? ORDER BY timestamp DESC LIMIT ?`).all(sessionId, limit);
+                }
+                else {
+                    events = db.prepare(`SELECT id, session_id, event_type, timestamp, duration_ms, model_used, tokens_in, tokens_out, cost_usd, outcome, outcome_detail, trace_id
+             FROM episodic_events ORDER BY timestamp DESC LIMIT ?`).all(limit);
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ events, total: events.length }));
+            }
+            catch {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Memory query failed' }));
+            }
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/v1/memory/procedural') {
+            const queryString = url.includes('?') ? url.split('?')[1] ?? '' : '';
+            const params = new URLSearchParams(queryString);
+            const limit = Math.min(parseInt(params.get('limit') ?? '10', 10) || 10, 50);
+            try {
+                // Read from mesh.db (procedural atom store)
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const Database = require('better-sqlite3');
+                const meshDbPath = require('node:path').join((0, osmosis_store_js_1.getRelayplaneDir)(), 'mesh.db');
+                let atoms = [];
+                try {
+                    const meshDb = new Database(meshDbPath, { readonly: true });
+                    atoms = meshDb.prepare(`SELECT id, type, observation, confidence, fitness_score, trust_tier, evidence_count, created_at, updated_at
+             FROM atoms ORDER BY fitness_score DESC, confidence DESC LIMIT ?`).all(limit);
+                    meshDb.close();
+                }
+                catch { /* mesh.db may not exist yet */ }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ atoms, total: atoms.length }));
+            }
+            catch {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Procedural memory query failed' }));
+            }
+            return;
+        }
         // Extract auth context from incoming request
         const ctx = extractRequestContext(req);
         const anthropicEnvKey = process.env['ANTHROPIC_API_KEY'];
@@ -3716,6 +4212,8 @@ async function startProxy(config = {}) {
                 res.end(JSON.stringify({ error: 'Invalid JSON' }));
                 return;
             }
+            // Extract session ID (X-Claude-Code-Session-Id or synthetic)
+            const { sessionId: nativeSessionId, sessionSource: nativeSessionSource } = (0, session_tracker_js_1.getSessionId)(req, requestBody['model']);
             // Extract agent fingerprint and explicit agent ID
             const nativeSystemPrompt = (0, agent_tracker_js_1.extractSystemPromptFromBody)(requestBody);
             const nativeExplicitAgentId = getHeaderValue(req, 'x-relayplane-agent') || undefined;
@@ -3732,6 +4230,29 @@ async function startProxy(config = {}) {
             const parsedModel = parseModelSuffix(requestedModel);
             let routingSuffix = parsedModel.suffix;
             requestedModel = parsedModel.baseModel;
+            // ── CAP 3: Deterministic Traces — allocate traceId + emit request.start ──
+            const nativeTraceId = (0, node_crypto_1.randomUUID)();
+            {
+                const tw = trace_writer_js_1.TraceWriter.getInstance();
+                if (tw.isEnabled() && recordTelemetry) {
+                    const sysHash = nativeSystemPrompt ? (0, trace_writer_js_1.sha256Hex)(nativeSystemPrompt) : undefined;
+                    const messages = requestBody['messages'];
+                    const reqTools = Array.isArray(requestBody['tools'])
+                        ? requestBody['tools'].map(t => t?.name ?? '').filter(Boolean)
+                        : undefined;
+                    void tw.write(nativeSessionId, nativeTraceId, {
+                        eventType: 'request.start',
+                        parentTraceId: getHeaderValue(req, 'x-parent-trace-id') || undefined,
+                        agentId: getHeaderValue(req, 'x-agent-id') || nativeExplicitAgentId || undefined,
+                        payload: {
+                            model: requestedModel,
+                            messageCount: messages?.length,
+                            requestedTools: reqTools,
+                            systemPromptHash: sysHash,
+                        },
+                    });
+                }
+            }
             if (relayplaneEnabled && !relayplaneBypass && requestedModel) {
                 const override = proxyConfig.modelOverrides?.[requestedModel];
                 if (override) {
@@ -3990,6 +4511,109 @@ async function startProxy(config = {}) {
                 Object.assign(budgetExtraHeaders, budgetCheck.headers);
             }
             // ── End budget check ──
+            // ── Session budget check (only when X-Claude-Code-Session-Id is present) ──
+            let nativeSessionBudgetResult = null;
+            if (nativeSessionSource === 'claude-code') {
+                nativeSessionBudgetResult = budgetManager.checkSessionBudget(nativeSessionId, targetModel || requestedModel);
+                if (!nativeSessionBudgetResult.allowed) {
+                    res.writeHead(429, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        error: 'session_budget_exceeded',
+                        spent: nativeSessionBudgetResult.spent,
+                        cap: nativeSessionBudgetResult.cap,
+                        type: 'session_budget_exceeded',
+                    }));
+                    return;
+                }
+                if (nativeSessionBudgetResult.model !== (targetModel || requestedModel)) {
+                    log(`Session budget downgrade: ${targetModel || requestedModel} → ${nativeSessionBudgetResult.model}`);
+                    // CAP 3: emit model.switch before we overwrite targetModel
+                    {
+                        const tw = trace_writer_js_1.TraceWriter.getInstance();
+                        if (tw.isEnabled() && recordTelemetry) {
+                            void tw.write(nativeSessionId, nativeTraceId, {
+                                eventType: 'model.switch',
+                                payload: {
+                                    fromModel: targetModel || requestedModel,
+                                    toModel: nativeSessionBudgetResult.model,
+                                    switchReason: 'session_budget',
+                                },
+                            });
+                        }
+                    }
+                    targetModel = nativeSessionBudgetResult.model;
+                    if (requestBody)
+                        requestBody['model'] = targetModel;
+                }
+                // CAP 3: emit budget.checkpoint after every budget check
+                {
+                    const tw = trace_writer_js_1.TraceWriter.getInstance();
+                    if (tw.isEnabled() && recordTelemetry) {
+                        void tw.write(nativeSessionId, nativeTraceId, {
+                            eventType: 'budget.checkpoint',
+                            payload: {
+                                sessionCostUsd: nativeSessionBudgetResult.spent,
+                                sessionCapUsd: nativeSessionBudgetResult.cap,
+                                sessionPct: nativeSessionBudgetResult.cap > 0
+                                    ? nativeSessionBudgetResult.spent / nativeSessionBudgetResult.cap
+                                    : 0,
+                            },
+                        });
+                    }
+                }
+            }
+            // ── End session budget check ──
+            // ── Tool authorization check (deny-by-default, after budget gate) ──
+            {
+                const reqTools = Array.isArray(requestBody?.['tools'])
+                    ? requestBody['tools'].map(t => t?.name ?? '').filter(Boolean)
+                    : [];
+                if (reqTools.length > 0) {
+                    const tr = (0, tool_router_js_1.getToolRouter)();
+                    const toolCtx = (0, tool_router_js_1.extractToolContext)(req.headers, nativeSessionId, reqTools, tr);
+                    const authResult = tr.checkTools(toolCtx);
+                    if (authResult.denied.length > 0) {
+                        for (const toolName of authResult.denied) {
+                            tr.recordDenied(nativeSessionId, toolName, 'not_in_active_pack');
+                        }
+                        // Emit tool.denied trace event
+                        const tw = trace_writer_js_1.TraceWriter.getInstance();
+                        if (tw.isEnabled() && recordTelemetry) {
+                            for (const toolName of authResult.denied) {
+                                void tw.write(nativeSessionId, nativeTraceId, {
+                                    eventType: 'tool.denied',
+                                    payload: { toolName },
+                                });
+                            }
+                        }
+                        // If ALL requested tools are denied, block the request
+                        if (authResult.allowed.length === 0) {
+                            res.writeHead(403, {
+                                'Content-Type': 'application/json',
+                                'X-Relay-Tools-Denied': authResult.deniedHeader,
+                            });
+                            res.end(JSON.stringify({
+                                error: 'tool_not_authorized',
+                                denied: authResult.denied,
+                                message: 'All requested tools are denied by the active tool pack policy.',
+                            }));
+                            return;
+                        }
+                    }
+                    // Strip denied tools from the forwarded request body so the model
+                    // cannot call them even when only a partial set of tools was denied.
+                    if (Array.isArray(requestBody['tools'])) {
+                        const allowedSet = new Set(authResult.allowed);
+                        requestBody['tools'] = requestBody['tools'].filter(t => allowedSet.has(t?.name ?? ''));
+                    }
+                    // Set response header so callers know which tools were denied
+                    if (authResult.deniedHeader) {
+                        // Stash for later use when writing response headers
+                        budgetExtraHeaders['X-Relay-Tools-Denied'] = authResult.deniedHeader;
+                    }
+                }
+            }
+            // ── End tool authorization check ──
             // ── Rate limit check ──
             const workspaceId = 'local'; // Local proxy uses single workspace
             try {
@@ -4117,7 +4741,7 @@ async function startProxy(config = {}) {
                         // ── End cross-provider cascade ──
                         const durationMs = Date.now() - startTime;
                         const errMsg = extractProviderErrorMessage(errorPayload, providerResponse.status);
-                        logRequest(originalModel ?? 'unknown', targetModel || requestedModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, errMsg, providerResponse.status);
+                        logRequest(originalModel ?? 'unknown', targetModel || requestedModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, nativeAgentFingerprint, nativeExplicitAgentId, errMsg, providerResponse.status);
                         res.writeHead(providerResponse.status, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify(errorPayload));
                         return;
@@ -4132,6 +4756,8 @@ async function startProxy(config = {}) {
                             'Cache-Control': 'no-cache',
                             'Connection': 'keep-alive',
                             'X-RelayPlane-Cache': cacheBypass ? 'BYPASS' : 'MISS',
+                            'X-Relay-Trace-Id': nativeTraceId,
+                            'X-Relay-Memory-Hits': String((0, osmosis_store_js_1.countAtomsForSession)(nativeSessionId)),
                             ...nativeStreamRpHeaders,
                         });
                         const reader = providerResponse.body?.getReader();
@@ -4226,7 +4852,7 @@ async function startProxy(config = {}) {
                             });
                             log(`Cache STORE for ${targetModel || requestedModel} (hash: ${cacheHash.slice(0, 8)})`);
                         }
-                        res.writeHead(providerResponse.status, { 'Content-Type': 'application/json', 'X-RelayPlane-Cache': nativeCacheHeader, ...nativeRpHeaders });
+                        res.writeHead(providerResponse.status, { 'Content-Type': 'application/json', 'X-RelayPlane-Cache': nativeCacheHeader, 'X-Relay-Trace-Id': nativeTraceId, 'X-Relay-Memory-Hits': String((0, osmosis_store_js_1.countAtomsForSession)(nativeSessionId)), ...nativeRpHeaders });
                         res.end(JSON.stringify(nativeResponseData));
                     }
                 }
@@ -4260,6 +4886,50 @@ async function startProxy(config = {}) {
                 if (nativeAgentFingerprint && nativeAgentFingerprint !== 'unknown') {
                     (0, agent_tracker_js_1.updateAgentCost)(nativeAgentFingerprint, nativeCostUsd);
                 }
+                // ── Session Intelligence: upsert session record ──
+                (0, session_tracker_js_1.upsertSession)(nativeSessionId, nativeSessionSource, nativeCostUsd, nativeTokIn, nativeTokOut);
+                // ── Session 4: Episodic memory write (fire-and-forget) ──
+                try {
+                    (0, episode_writer_js_1.writeEpisode)(nativeSessionId, {
+                        eventType: 'model-response',
+                        modelUsed: targetModel || requestedModel,
+                        tokensIn: nativeTokIn,
+                        tokensOut: nativeTokOut,
+                        costUsd: nativeCostUsd,
+                        outcome: 'success',
+                        traceId: nativeTraceId,
+                        durationMs,
+                    });
+                }
+                catch { /* never block hot path */ }
+                // ── CAP 3: Deterministic Traces — emit request.end + finalize ──
+                {
+                    const tw = trace_writer_js_1.TraceWriter.getInstance();
+                    if (tw.isEnabled() && recordTelemetry) {
+                        const finishReason = nativeResponseData?.['stop_reason']
+                            ?? (nativeResponseData?.['choices']?.[0]?.['finish_reason']);
+                        void tw.write(nativeSessionId, nativeTraceId, {
+                            eventType: 'request.end',
+                            durationMs,
+                            payload: {
+                                modelUsed: targetModel || requestedModel,
+                                tokensIn: nativeTokIn,
+                                tokensOut: nativeTokOut,
+                                costUsd: nativeCostUsd,
+                                finishReason,
+                            },
+                        });
+                        void tw.finalizeTrace(nativeTraceId, nativeSessionId, {
+                            costUsd: nativeCostUsd,
+                            modelUsed: targetModel || requestedModel,
+                            durationMs,
+                        });
+                    }
+                }
+                // ── Session budget: record spend (fire-and-forget, only for claude-code sessions) ──
+                if (nativeSessionSource === 'claude-code') {
+                    budgetManager.updateSessionBudget(nativeSessionId, nativeCostUsd, targetModel || requestedModel);
+                }
                 // ── Post-request: budget spend + anomaly detection ──
                 postRequestRecord(targetModel || requestedModel, nativeTokIn, nativeTokOut, nativeCostUsd);
                 if (recordTelemetry) {
@@ -4290,7 +4960,20 @@ async function startProxy(config = {}) {
                     catchErrMsg = err instanceof Error ? err.message : String(err);
                     catchErrStatus = 500;
                 }
-                logRequest(originalModel ?? 'unknown', targetModel || requestedModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, catchErrMsg, catchErrStatus);
+                logRequest(originalModel ?? 'unknown', targetModel || requestedModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, nativeAgentFingerprint, nativeExplicitAgentId, catchErrMsg, catchErrStatus);
+                // ── CAP 3: Deterministic Traces — emit request.end (error) + finalize ──
+                {
+                    const tw = trace_writer_js_1.TraceWriter.getInstance();
+                    if (tw.isEnabled() && recordTelemetry) {
+                        void tw.write(nativeSessionId, nativeTraceId, {
+                            eventType: 'request.end',
+                            durationMs,
+                            error: { code: String(catchErrStatus), message: catchErrMsg, retryable: catchErrStatus >= 500 },
+                            payload: { modelUsed: targetModel || requestedModel },
+                        });
+                        void tw.finalizeTrace(nativeTraceId, nativeSessionId, { durationMs, modelUsed: targetModel || requestedModel });
+                    }
+                }
                 if (recordTelemetry) {
                     sendCloudTelemetry(taskType, targetModel || requestedModel, 0, 0, durationMs, false, 0, originalModel ?? undefined);
                     meshCapture(targetModel || requestedModel, targetProvider, taskType, 0, 0, 0, durationMs, false, catchErrMsg);
@@ -4404,6 +5087,8 @@ async function startProxy(config = {}) {
             return;
         }
         const isStreaming = request.stream === true;
+        // Extract session ID for chat/completions
+        const { sessionId: chatSessionId, sessionSource: chatSessionSource } = (0, session_tracker_js_1.getSessionId)(req, request.model);
         // Extract agent fingerprint for chat/completions
         const chatSystemPrompt = (0, agent_tracker_js_1.extractSystemPromptFromBody)(request);
         const chatExplicitAgentId = getHeaderValue(req, 'x-relayplane-agent') || undefined;
@@ -4412,6 +5097,24 @@ async function startProxy(config = {}) {
             const agentResult = (0, agent_tracker_js_1.trackAgent)(chatSystemPrompt, 0, chatExplicitAgentId);
             chatAgentFingerprint = agentResult.fingerprint;
         }
+        // ── CAP 3: Deterministic Traces — allocate chatTraceId + emit request.start ──
+        const chatTraceId = (0, node_crypto_1.randomUUID)();
+        {
+            const tw = trace_writer_js_1.TraceWriter.getInstance();
+            if (tw.isEnabled() && recordTelemetry) {
+                const chatSysHash = chatSystemPrompt ? (0, trace_writer_js_1.sha256Hex)(chatSystemPrompt) : undefined;
+                void tw.write(chatSessionId, chatTraceId, {
+                    eventType: 'request.start',
+                    parentTraceId: getHeaderValue(req, 'x-parent-trace-id') || undefined,
+                    agentId: getHeaderValue(req, 'x-agent-id') || chatExplicitAgentId || undefined,
+                    payload: {
+                        model: request.model,
+                        messageCount: request.messages?.length,
+                        systemPromptHash: chatSysHash,
+                    },
+                });
+            }
+        }
         // ── Response Cache: check for cached response (chat/completions) ──
         const chatCacheBypass = responseCache.shouldBypass(request);
         let chatCacheHash;
@@ -4758,7 +5461,7 @@ async function startProxy(config = {}) {
         const startTime = Date.now();
         // Handle streaming vs non-streaming
         if (isStreaming) {
-            await handleStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, useCascade ? 'cascade' : routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity, chatCacheHash, chatCacheBypass, chatAgentFingerprint, chatExplicitAgentId);
+            await handleStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, useCascade ? 'cascade' : routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity, chatCacheHash, chatCacheBypass, chatAgentFingerprint, chatExplicitAgentId, chatSessionId, chatSessionSource);
         }
         else {
             if (useCascade && cascadeConfig) {
@@ -4801,6 +5504,43 @@ async function startProxy(config = {}) {
                     updateLastHistoryEntry(cascadeTokensIn, cascadeTokensOut, cascadeCost, chatCascadeRespModel, cascadeCacheCreation, cascadeCacheRead, chatAgentFingerprint, chatExplicitAgentId);
                     if (chatAgentFingerprint && chatAgentFingerprint !== 'unknown')
                         (0, agent_tracker_js_1.updateAgentCost)(chatAgentFingerprint, cascadeCost);
+                    (0, session_tracker_js_1.upsertSession)(chatSessionId, chatSessionSource, cascadeCost, cascadeTokensIn, cascadeTokensOut);
+                    // ── Session 4: Episodic memory write (fire-and-forget) ──
+                    try {
+                        (0, episode_writer_js_1.writeEpisode)(chatSessionId, {
+                            eventType: 'routing-decision',
+                            modelUsed: cascadeResult.model,
+                            tokensIn: cascadeTokensIn,
+                            tokensOut: cascadeTokensOut,
+                            costUsd: cascadeCost,
+                            outcome: 'success',
+                            outcomeDetail: 'cascade',
+                            traceId: chatTraceId,
+                            durationMs,
+                        });
+                    }
+                    catch { /* never block hot path */ }
+                    // ── CAP 3: Deterministic Traces — emit request.end + finalize (chat cascade) ──
+                    {
+                        const tw = trace_writer_js_1.TraceWriter.getInstance();
+                        if (tw.isEnabled() && recordTelemetry) {
+                            void tw.write(chatSessionId, chatTraceId, {
+                                eventType: 'request.end',
+                                durationMs,
+                                payload: {
+                                    modelUsed: cascadeResult.model,
+                                    tokensIn: cascadeTokensIn,
+                                    tokensOut: cascadeTokensOut,
+                                    costUsd: cascadeCost,
+                                },
+                            });
+                            void tw.finalizeTrace(chatTraceId, chatSessionId, {
+                                costUsd: cascadeCost,
+                                modelUsed: cascadeResult.model,
+                                durationMs,
+                            });
+                        }
+                    }
                     if (recordTelemetry) {
                         try {
                             const runResult = await relay.run({
@@ -4828,7 +5568,7 @@ async function startProxy(config = {}) {
                         meshCapture(cascadeResult.model, cascadeResult.provider, taskType, cascadeTokensIn, cascadeTokensOut, cascadeCost, durationMs, true);
                     }
                     const chatCascadeRpHeaders = buildRelayPlaneResponseHeaders(cascadeResult.model, originalRequestedModel ?? 'unknown', complexity, cascadeResult.provider, 'cascade');
-                    res.writeHead(200, { 'Content-Type': 'application/json', ...chatCascadeRpHeaders });
+                    res.writeHead(200, { 'Content-Type': 'application/json', 'X-Relay-Trace-Id': chatTraceId, 'X-Relay-Memory-Hits': String((0, osmosis_store_js_1.countAtomsForSession)(chatSessionId)), ...chatCascadeRpHeaders });
                     res.end(JSON.stringify(responseData));
                 }
                 catch (err) {
@@ -4843,7 +5583,7 @@ async function startProxy(config = {}) {
                         cascadeErrMsg = err instanceof Error ? err.message : String(err);
                         cascadeErrStatus = 500;
                     }
-                    logRequest(originalRequestedModel ?? 'unknown', targetModel || 'unknown', targetProvider, durationMs, false, 'cascade', undefined, taskType, complexity, undefined, undefined, cascadeErrMsg, cascadeErrStatus);
+                    logRequest(originalRequestedModel ?? 'unknown', targetModel || 'unknown', targetProvider, durationMs, false, 'cascade', undefined, taskType, complexity, chatAgentFingerprint, chatExplicitAgentId, cascadeErrMsg, cascadeErrStatus);
                     if (recordTelemetry) {
                         sendCloudTelemetry(taskType, targetModel || 'unknown', 0, 0, durationMs, false, 0, originalRequestedModel ?? undefined);
                         meshCapture(targetModel || 'unknown', targetProvider, taskType, 0, 0, 0, durationMs, false, cascadeErrMsg);
@@ -4859,7 +5599,10 @@ async function startProxy(config = {}) {
                 }
             }
             else {
-                await handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity, chatAgentFingerprint, chatExplicitAgentId, useAnthropicEnvKey);
+                res.setHeader('X-Relay-Trace-Id', chatTraceId);
+                res.setHeader('X-Relay-Memory-Hits', String((0, osmosis_store_js_1.countAtomsForSession)(chatSessionId)));
+                await handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity, chatAgentFingerprint, chatExplicitAgentId, useAnthropicEnvKey, // pass for cross-provider cascade API key resolution (GH #38)
+                chatSessionId, chatSessionSource, chatTraceId);
             }
         }
     });
@@ -5024,7 +5767,7 @@ async function executeNonStreamingProviderRequest(request, targetProvider, targe
     }
     return { responseData, ok: true, status: 200 };
 }
-async function handleStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity = 'simple', cacheHash, cacheBypass, agentFingerprint, agentId) {
+async function handleStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity = 'simple', cacheHash, cacheBypass, agentFingerprint, agentId, sessionId, sessionSource) {
     let providerResponse;
     try {
         switch (targetProvider) {
@@ -5055,7 +5798,7 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
                 if (!ollamaStream.success || !ollamaStream.stream) {
                     const durationMs = Date.now() - startTime;
                     const errMsg = ollamaStream.error?.message ?? 'Ollama stream failed';
-                    logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, errMsg, ollamaStream.error?.status);
+                    logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, agentFingerprint, agentId, errMsg, ollamaStream.error?.status);
                     res.writeHead(ollamaStream.error?.status ?? 502, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: ollamaStream.error }));
                     return;
@@ -5091,7 +5834,7 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
             }
             const durationMs = Date.now() - startTime;
             const streamErrMsg = extractProviderErrorMessage(errorData, providerResponse.status);
-            logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, streamErrMsg, providerResponse.status);
+            logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, agentFingerprint, agentId, streamErrMsg, providerResponse.status);
             if (recordTelemetry) {
                 sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
                 meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, streamErrMsg);
@@ -5107,7 +5850,7 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
             cooldownManager.recordFailure(targetProvider, errorMsg);
         }
         const durationMs = Date.now() - startTime;
-        logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, errorMsg, 500);
+        logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, agentFingerprint, agentId, errorMsg, 500);
         if (recordTelemetry) {
             sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
             meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, errorMsg);
@@ -5233,6 +5976,23 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
     updateLastHistoryEntry(streamTokensIn, streamTokensOut, streamCost, undefined, streamCacheCreation || undefined, streamCacheRead || undefined, agentFingerprint, agentId);
     if (agentFingerprint && agentFingerprint !== 'unknown')
         (0, agent_tracker_js_1.updateAgentCost)(agentFingerprint, streamCost);
+    if (sessionId && sessionSource)
+        (0, session_tracker_js_1.upsertSession)(sessionId, sessionSource, streamCost, streamTokensIn, streamTokensOut);
+    // ── Session 4: Episodic memory write (fire-and-forget) ──
+    if (sessionId) {
+        try {
+            (0, episode_writer_js_1.writeEpisode)(sessionId, {
+                eventType: 'model-response',
+                modelUsed: targetModel,
+                tokensIn: streamTokensIn,
+                tokensOut: streamTokensOut,
+                costUsd: streamCost,
+                outcome: 'success',
+                durationMs,
+            });
+        }
+        catch { /* never block hot path */ }
+    }
     // ── Post-request: budget spend + anomaly detection ──
     try {
         (0, budget_js_1.getBudgetManager)().recordSpend(streamCost, targetModel);
@@ -5270,7 +6030,9 @@ async function handleStreamingRequest(res, request, targetProvider, targetModel,
  */
 async function handleNonStreamingRequest(res, request, targetProvider, targetModel, apiKey, ctx, relay, promptText, taskType, confidence, routingMode, recordTelemetry, startTime, log, cooldownManager, cooldownsEnabled, complexity = 'simple', agentFingerprint, agentId, 
 /** Anthropic env API key — required for cross-provider cascade API key resolution (GH #38) */
-anthropicEnvKeyForCascade) {
+anthropicEnvKeyForCascade, sessionId, sessionSource, 
+/** CAP 3: trace ID for deterministic trace write */
+traceId) {
     let responseData;
     try {
         const result = await executeNonStreamingProviderRequest(request, targetProvider, targetModel, apiKey, ctx);
@@ -5308,7 +6070,7 @@ anthropicEnvKeyForCascade) {
                     // All fallbacks exhausted — return the primary error
                     const durationMs = Date.now() - startTime;
                     const nsErrMsg = extractProviderErrorMessage(responseData, result.status);
-                    logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, `${routingMode}+cascade`, undefined, taskType, complexity, undefined, undefined, nsErrMsg, result.status);
+                    logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, `${routingMode}+cascade`, undefined, taskType, complexity, agentFingerprint, agentId, nsErrMsg, result.status);
                     if (recordTelemetry) {
                         sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
                         meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, nsErrMsg);
@@ -5322,7 +6084,7 @@ anthropicEnvKeyForCascade) {
                 // No cascade — return error as-is
                 const durationMs = Date.now() - startTime;
                 const nsErrMsg = extractProviderErrorMessage(responseData, result.status);
-                logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, nsErrMsg, result.status);
+                logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, agentFingerprint, agentId, nsErrMsg, result.status);
                 if (recordTelemetry) {
                     sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
                     meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, nsErrMsg);
@@ -5340,7 +6102,7 @@ anthropicEnvKeyForCascade) {
             cooldownManager.recordFailure(targetProvider, errorMsg);
         }
         const durationMs = Date.now() - startTime;
-        logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, undefined, undefined, errorMsg, 500);
+        logRequest(request.model ?? 'unknown', targetModel, targetProvider, durationMs, false, routingMode, undefined, taskType, complexity, agentFingerprint, agentId, errorMsg, 500);
         if (recordTelemetry) {
             sendCloudTelemetry(taskType, targetModel, 0, 0, durationMs, false, 0, request.model ?? undefined);
             meshCapture(targetModel, targetProvider, taskType, 0, 0, 0, durationMs, false, errorMsg);
@@ -5367,6 +6129,39 @@ anthropicEnvKeyForCascade) {
     updateLastHistoryEntry(tokensIn, tokensOut, cost, nonStreamRespModel, cacheCreationTokens || undefined, cacheReadTokens || undefined, agentFingerprint, agentId);
     if (agentFingerprint && agentFingerprint !== 'unknown')
         (0, agent_tracker_js_1.updateAgentCost)(agentFingerprint, cost);
+    if (sessionId && sessionSource)
+        (0, session_tracker_js_1.upsertSession)(sessionId, sessionSource, cost, tokensIn, tokensOut);
+    // ── Session 4: Episodic memory write (fire-and-forget) ──
+    if (sessionId) {
+        try {
+            (0, episode_writer_js_1.writeEpisode)(sessionId, {
+                eventType: 'model-response',
+                modelUsed: targetModel,
+                tokensIn,
+                tokensOut,
+                costUsd: cost,
+                outcome: 'success',
+                traceId: traceId ?? undefined,
+                durationMs,
+            });
+        }
+        catch { /* never block hot path */ }
+    }
+    // ── CAP 3: Deterministic Traces — emit request.end + finalize (chat non-streaming) ──
+    if (traceId && sessionId && recordTelemetry) {
+        const tw = trace_writer_js_1.TraceWriter.getInstance();
+        if (tw.isEnabled()) {
+            const finishReason = responseData?.['choices']
+                ? responseData['choices'][0]?.['finish_reason']
+                : undefined;
+            void tw.write(sessionId, traceId, {
+                eventType: 'request.end',
+                durationMs,
+                payload: { modelUsed: targetModel, tokensIn, tokensOut, costUsd: cost, finishReason },
+            });
+            void tw.finalizeTrace(traceId, sessionId, { costUsd: cost, modelUsed: targetModel, durationMs });
+        }
+    }
     // ── Post-request: budget spend + anomaly detection ──
     try {
         (0, budget_js_1.getBudgetManager)().recordSpend(cost, targetModel);