feat: eager vLLM warmup and smart page titles in paginate stage

- Add warmup() to LlmProvider interface for eager subprocess startup
- ManagedVllmProvider.warmup() starts vLLM in background on project load
- ProviderRegistry.warmupAll() triggers all managed providers
- NamedProvider proxies warmup() to inner provider
- paginate stage generates LLM-powered descriptive page titles when
  available, cached by content hash, falls back to generic "Page N"
- project-mcp-endpoint calls warmupAll() on router creation so vLLM
  is loading while the session initializes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/cli/package.json

@@ -21,6 +21,7 @@
     "@mcpctl/shared": "workspace:*",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",
+    "diff": "^8.0.3",
     "ink": "^6.8.0",
     "inquirer": "^12.0.0",
     "js-yaml": "^4.1.0",
@@ -28,6 +29,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@types/diff": "^8.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.3.0",
     "@types/react": "^19.2.14"

src/cli/src/commands/apply.ts

@@ -24,6 +24,7 @@ const ServerSpecSchema = z.object({
   name: z.string().min(1),
   description: z.string().default(''),
   packageName: z.string().optional(),
+  runtime: z.string().optional(),
   dockerImage: z.string().optional(),
   transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).default('STDIO'),
   repositoryUrl: z.string().url().optional(),
@@ -52,6 +53,7 @@ const TemplateSpecSchema = z.object({
   version: z.string().default('1.0.0'),
   description: z.string().default(''),
   packageName: z.string().optional(),
+  runtime: z.string().optional(),
   dockerImage: z.string().optional(),
   transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).default('STDIO'),
   repositoryUrl: z.string().optional(),
@@ -124,6 +126,7 @@ const ProjectSpecSchema = z.object({
   description: z.string().default(''),
   prompt: z.string().max(10000).default(''),
   proxyMode: z.enum(['direct', 'filtered']).default('direct'),
+  proxyModel: z.string().optional(),
   gated: z.boolean().default(true),
   llmProvider: z.string().optional(),
   llmModel: z.string().optional(),

src/cli/src/commands/config-setup.ts

@@ -1,8 +1,10 @@
 import { Command } from 'commander';
 import http from 'node:http';
 import https from 'node:https';
+import { existsSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { homedir } from 'node:os';
 import { loadConfig, saveConfig } from '../config/index.js';
 import type { ConfigLoaderDeps, McpctlConfig, LlmConfig, LlmProviderName, LlmProviderEntry, LlmTier } from '../config/index.js';
 import type { SecretStore } from '@mcpctl/shared';
@@ -37,11 +39,19 @@ interface ProviderFields {
   model?: string;
   url?: string;
   binaryPath?: string;
+  venvPath?: string;
+  port?: number;
+  gpuMemoryUtilization?: number;
+  maxModelLen?: number;
+  idleTimeoutMinutes?: number;
+  extraArgs?: string[];
 }
 
 const FAST_PROVIDER_CHOICES: ProviderChoice[] = [
-  { name: 'vLLM', value: 'vllm', description: 'Self-hosted vLLM (OpenAI-compatible)' },
+  { name: 'Run vLLM Instance', value: 'vllm-managed', description: 'Auto-managed local vLLM (starts/stops with mcplocal)' },
+  { name: 'vLLM (external)', value: 'vllm', description: 'Self-hosted vLLM (OpenAI-compatible)' },
   { name: 'Ollama', value: 'ollama', description: 'Local models via Ollama' },
+  { name: 'Anthropic (Claude)', value: 'anthropic', description: 'Claude Haiku — fast & cheap' },
 ];
 
 const HEAVY_PROVIDER_CHOICES: ProviderChoice[] = [
@@ -55,10 +65,10 @@ const ALL_PROVIDER_CHOICES: ProviderChoice[] = [
   ...FAST_PROVIDER_CHOICES,
   ...HEAVY_PROVIDER_CHOICES,
   { name: 'None (disable)', value: 'none', description: 'Disable LLM features' },
-];
+] as ProviderChoice[];
 
 const GEMINI_MODELS = ['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.0-flash'];
-const ANTHROPIC_MODELS = ['claude-haiku-3-5-20241022', 'claude-sonnet-4-20250514', 'claude-opus-4-20250514'];
+const ANTHROPIC_MODELS = ['claude-haiku-3-5-20241022', 'claude-sonnet-4-20250514', 'claude-sonnet-4-5-20250514', 'claude-opus-4-20250514'];
 const DEEPSEEK_MODELS = ['deepseek-chat', 'deepseek-reasoner'];
 
 function defaultFetchModels(baseUrl: string, path: string): Promise<string[]> {
@@ -254,6 +264,40 @@ async function setupVllmFields(
   return result;
 }
 
+async function setupVllmManagedFields(
+  prompt: ConfigSetupPrompt,
+  log: (...args: string[]) => void,
+): Promise<ProviderFields> {
+  const defaultVenv = '~/vllm_env';
+  const venvPath = await prompt.input('vLLM venv path:', defaultVenv);
+
+  // Validate venv exists
+  const expandedPath = venvPath.startsWith('~') ? venvPath.replace('~', homedir()) : venvPath;
+  const vllmBin = `${expandedPath}/bin/vllm`;
+  if (!existsSync(vllmBin)) {
+    log(`Warning: ${vllmBin} not found.`);
+    log(`  Create it with: uv venv ${venvPath} --python 3.12 && ${expandedPath}/bin/pip install vllm`);
+  } else {
+    log(`Found vLLM at: ${vllmBin}`);
+  }
+
+  const model = await prompt.input('Model to serve:', 'Qwen/Qwen2.5-7B-Instruct-AWQ');
+  const gpuStr = await prompt.input('GPU memory utilization (0.1–1.0):', '0.75');
+  const gpuMemoryUtilization = parseFloat(gpuStr) || 0.75;
+  const idleStr = await prompt.input('Stop after N minutes idle:', '15');
+  const idleTimeoutMinutes = parseInt(idleStr, 10) || 15;
+  const portStr = await prompt.input('Port:', '8000');
+  const port = parseInt(portStr, 10) || 8000;
+
+  return {
+    model,
+    venvPath,
+    port,
+    gpuMemoryUtilization,
+    idleTimeoutMinutes,
+  };
+}
+
 async function setupApiKeyFields(
   prompt: ConfigSetupPrompt,
   secretStore: SecretStore,
@@ -306,6 +350,70 @@ async function setupApiKeyFields(
   return result;
 }
 
+async function promptForAnthropicKey(
+  prompt: ConfigSetupPrompt,
+  log: (...args: string[]) => void,
+  whichBinary: (name: string) => Promise<string | null>,
+): Promise<string> {
+  const claudePath = await whichBinary('claude');
+
+  if (claudePath) {
+    log(`Found Claude CLI at: ${claudePath}`);
+    const useOAuth = await prompt.confirm(
+      'Generate free token via Claude CLI? (requires Pro/Max subscription)', true);
+    if (useOAuth) {
+      log('');
+      log('  Run:  claude setup-token');
+      log('  Then paste the token below (starts with sk-ant-oat01-)');
+      log('');
+      return prompt.password('OAuth token:');
+    }
+  } else {
+    log('Tip: Install Claude CLI (npm i -g @anthropic-ai/claude-code) to generate');
+    log('     a free OAuth token with "claude setup-token" (Pro/Max subscription).');
+    log('');
+  }
+
+  return prompt.password('API key (from console.anthropic.com):');
+}
+
+async function setupAnthropicFields(
+  prompt: ConfigSetupPrompt,
+  secretStore: SecretStore,
+  log: (...args: string[]) => void,
+  whichBinary: (name: string) => Promise<string | null>,
+  currentModel?: string,
+): Promise<ProviderFields> {
+  const existingKey = await secretStore.get('anthropic-api-key');
+  let apiKey: string;
+
+  if (existingKey) {
+    const isOAuth = existingKey.startsWith('sk-ant-oat');
+    const masked = `****${existingKey.slice(-4)}`;
+    const label = isOAuth ? `OAuth token stored (${masked})` : `API key stored (${masked})`;
+    const changeKey = await prompt.confirm(`${label}. Change it?`, false);
+    apiKey = changeKey ? await promptForAnthropicKey(prompt, log, whichBinary) : existingKey;
+  } else {
+    apiKey = await promptForAnthropicKey(prompt, log, whichBinary);
+  }
+
+  if (apiKey !== existingKey) {
+    await secretStore.set('anthropic-api-key', apiKey);
+  }
+
+  const choices = ANTHROPIC_MODELS.map((m) => ({
+    name: m === currentModel ? `${m} (current)` : m,
+    value: m,
+  }));
+  choices.push({ name: 'Custom...', value: '__custom__' });
+  let model = await prompt.select<string>('Select model:', choices);
+  if (model === '__custom__') {
+    model = await prompt.input('Model name:', currentModel);
+  }
+
+  return { model };
+}
+
 /** Configure a single provider type and return its fields. */
 async function setupProviderFields(
   providerType: LlmProviderName,
@@ -322,8 +430,10 @@ async function setupProviderFields(
       return setupOllamaFields(prompt, fetchModels);
     case 'vllm':
       return setupVllmFields(prompt, fetchModels);
+    case 'vllm-managed':
+      return setupVllmManagedFields(prompt, log);
     case 'anthropic':
-      return setupApiKeyFields(prompt, secretStore, 'anthropic', 'anthropic-api-key', ANTHROPIC_MODELS);
+      return setupAnthropicFields(prompt, secretStore, log, whichBinary);
     case 'openai':
       return setupApiKeyFields(prompt, secretStore, 'openai', 'openai-api-key', []);
     case 'deepseek':
@@ -339,6 +449,12 @@ function buildEntry(providerType: LlmProviderName, name: string, fields: Provide
   if (fields.model) entry.model = fields.model;
   if (fields.url) entry.url = fields.url;
   if (fields.binaryPath) entry.binaryPath = fields.binaryPath;
+  if (fields.venvPath) entry.venvPath = fields.venvPath;
+  if (fields.port !== undefined) entry.port = fields.port;
+  if (fields.gpuMemoryUtilization !== undefined) entry.gpuMemoryUtilization = fields.gpuMemoryUtilization;
+  if (fields.maxModelLen !== undefined) entry.maxModelLen = fields.maxModelLen;
+  if (fields.idleTimeoutMinutes !== undefined) entry.idleTimeoutMinutes = fields.idleTimeoutMinutes;
+  if (fields.extraArgs !== undefined) entry.extraArgs = fields.extraArgs;
   if (tier) entry.tier = tier;
   return entry;
 }
@@ -379,6 +495,14 @@ async function simpleSetup(
   log('Restart mcplocal: systemctl --user restart mcplocal');
 }
 
+/** Generate a unique default name given names already in use. */
+function uniqueDefaultName(baseName: string, usedNames: Set<string>): string {
+  if (!usedNames.has(baseName)) return baseName;
+  let i = 2;
+  while (usedNames.has(`${baseName}-${i}`)) i++;
+  return `${baseName}-${i}`;
+}
+
 /** Advanced mode: multiple providers with tier assignments. */
 async function advancedSetup(
   config: McpctlConfig,
@@ -390,6 +514,7 @@ async function advancedSetup(
   secretStore: SecretStore,
 ): Promise<void> {
   const entries: LlmProviderEntry[] = [];
+  const usedNames = new Set<string>();
 
   // Fast providers
   const addFast = await prompt.confirm('Add a FAST provider? (vLLM, Ollama — local, cheap, fast)', true);
@@ -397,8 +522,10 @@ async function advancedSetup(
     let addMore = true;
     while (addMore) {
       const providerType = await prompt.select<LlmProviderName>('Fast provider type:', FAST_PROVIDER_CHOICES);
-      const defaultName = providerType === 'vllm' ? 'vllm-local' : providerType;
+      const rawDefault = providerType === 'vllm' || providerType === 'vllm-managed' ? 'vllm-local' : providerType;
+      const defaultName = uniqueDefaultName(rawDefault, usedNames);
       const name = await prompt.input('Provider name:', defaultName);
+      usedNames.add(name);
       const fields = await setupProviderFields(providerType, prompt, log, fetchModels, whichBinary, secretStore);
       entries.push(buildEntry(providerType, name, fields, 'fast'));
       log(`  Added: ${name} (${providerType}) → fast tier`);
@@ -412,8 +539,9 @@ async function advancedSetup(
     let addMore = true;
     while (addMore) {
       const providerType = await prompt.select<LlmProviderName>('Heavy provider type:', HEAVY_PROVIDER_CHOICES);
-      const defaultName = providerType;
+      const defaultName = uniqueDefaultName(providerType, usedNames);
       const name = await prompt.input('Provider name:', defaultName);
+      usedNames.add(name);
       const fields = await setupProviderFields(providerType, prompt, log, fetchModels, whichBinary, secretStore);
       entries.push(buildEntry(providerType, name, fields, 'heavy'));
       log(`  Added: ${name} (${providerType}) → heavy tier`);

src/cli/src/commands/config.ts

@@ -111,7 +111,7 @@ export function createConfigCommand(deps?: Partial<ConfigCommandDeps>, apiDeps?:
         if (opts.inspect) {
           servers['mcpctl-inspect'] = {
             command: 'mcpctl',
-            args: ['console', '--inspect', '--stdin-mcp'],
+            args: ['console', '--stdin-mcp'],
           };
         }
 

src/cli/src/commands/console/app.tsx

@@ -1,368 +0,0 @@
-import { useState, useEffect, useCallback, createContext, useContext } from 'react';
-import { render, Box, Text, useInput, useApp, useStdout } from 'ink';
-import { McpSession } from './mcp-session.js';
-import type { LogEntry } from './mcp-session.js';
-import { Header } from './components/header.js';
-import { ProtocolLog } from './components/protocol-log.js';
-import { ConnectingView } from './components/connecting-view.js';
-import { MainMenu } from './components/main-menu.js';
-import { BeginSessionView } from './components/begin-session.js';
-import { ToolListView } from './components/tool-list.js';
-import { ToolDetailView } from './components/tool-detail.js';
-import { ResourceListView } from './components/resource-list.js';
-import { PromptListView } from './components/prompt-list.js';
-import { RawJsonRpcView } from './components/raw-jsonrpc.js';
-import { ResultView } from './components/result-view.js';
-import type { McpTool, McpResource, McpPrompt, InitializeResult } from './mcp-session.js';
-
-// ── Types ──
-
-type View =
-  | { type: 'connecting' }
-  | { type: 'main' }
-  | { type: 'begin-session' }
-  | { type: 'tools' }
-  | { type: 'tool-detail'; tool: McpTool }
-  | { type: 'resources' }
-  | { type: 'resource-detail'; resource: McpResource; content: string }
-  | { type: 'prompts' }
-  | { type: 'prompt-detail'; prompt: McpPrompt; content: unknown }
-  | { type: 'raw' }
-  | { type: 'result'; title: string; data: unknown };
-
-interface AppState {
-  view: View[];
-  gated: boolean;
-  initResult: InitializeResult | null;
-  tools: McpTool[];
-  resources: McpResource[];
-  prompts: McpPrompt[];
-  logEntries: LogEntry[];
-  error: string | null;
-  reconnecting: boolean;
-}
-
-// ── Context ──
-
-interface SessionContextValue {
-  session: McpSession;
-  projectName: string;
-  endpointUrl: string;
-  token?: string;
-}
-
-const SessionContext = createContext<SessionContextValue>(null!);
-export const useSession = (): SessionContextValue => useContext(SessionContext);
-
-// ── Root App ──
-
-interface AppProps {
-  projectName: string;
-  endpointUrl: string;
-  token?: string;
-}
-
-function App({ projectName, endpointUrl, token }: AppProps) {
-  const { exit } = useApp();
-  const { stdout } = useStdout();
-  const termHeight = stdout?.rows ?? 24;
-  const logHeight = Math.max(6, Math.min(12, Math.floor(termHeight * 0.3)));
-
-  const [session, setSession] = useState(() => new McpSession(endpointUrl, token));
-  const [state, setState] = useState<AppState>({
-    view: [{ type: 'connecting' }],
-    gated: false,
-    initResult: null,
-    tools: [],
-    resources: [],
-    prompts: [],
-    logEntries: [],
-    error: null,
-    reconnecting: false,
-  });
-
-  const currentView = state.view[state.view.length - 1]!;
-
-  // Log callback
-  const handleLog = useCallback((entry: LogEntry) => {
-    setState((s) => ({ ...s, logEntries: [...s.logEntries, entry] }));
-  }, []);
-
-  useEffect(() => {
-    session.onLog = handleLog;
-  }, [session, handleLog]);
-
-  // Navigation
-  const pushView = useCallback((v: View) => {
-    setState((s) => ({ ...s, view: [...s.view, v], error: null }));
-  }, []);
-
-  const popView = useCallback(() => {
-    setState((s) => {
-      if (s.view.length <= 1) return s;
-      return { ...s, view: s.view.slice(0, -1), error: null };
-    });
-  }, []);
-
-  const setError = useCallback((msg: string) => {
-    setState((s) => ({ ...s, error: msg }));
-  }, []);
-
-  // Initialize connection
-  const connect = useCallback(async (sess: McpSession) => {
-    try {
-      const initResult = await sess.initialize();
-      const tools = await sess.listTools();
-
-      // Detect gated: only begin_session tool available
-      const gated = tools.length === 1 && tools[0]?.name === 'begin_session';
-
-      setState((s) => ({
-        ...s,
-        initResult,
-        tools,
-        gated,
-        reconnecting: false,
-        view: [{ type: 'main' }],
-      }));
-
-      // If not gated, also fetch resources and prompts
-      if (!gated) {
-        try {
-          const [resources, prompts] = await Promise.all([
-            sess.listResources(),
-            sess.listPrompts(),
-          ]);
-          setState((s) => ({ ...s, resources, prompts }));
-        } catch {
-          // Non-fatal
-        }
-      }
-    } catch (err) {
-      setState((s) => ({
-        ...s,
-        error: `Connection failed: ${err instanceof Error ? err.message : String(err)}`,
-        reconnecting: false,
-        view: [{ type: 'main' }],
-      }));
-    }
-  }, []);
-
-  // Initial connect
-  useEffect(() => {
-    connect(session);
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Reconnect (new session)
-  const reconnect = useCallback(async () => {
-    setState((s) => ({ ...s, reconnecting: true, logEntries: [], error: null }));
-    await session.close().catch(() => {});
-    const newSession = new McpSession(endpointUrl, token);
-    newSession.onLog = handleLog;
-    setSession(newSession);
-    setState((s) => ({ ...s, view: [{ type: 'connecting' }] }));
-    await connect(newSession);
-  }, [session, endpointUrl, token, handleLog, connect]);
-
-  // After begin_session, refresh tools/resources/prompts
-  const onSessionBegan = useCallback(async (result: unknown) => {
-    pushView({ type: 'result', title: 'Session Started', data: result });
-    setState((s) => ({ ...s, gated: false }));
-
-    try {
-      const [tools, resources, prompts] = await Promise.all([
-        session.listTools(),
-        session.listResources(),
-        session.listPrompts(),
-      ]);
-      setState((s) => ({ ...s, tools, resources, prompts }));
-    } catch {
-      // Non-fatal
-    }
-  }, [session, pushView]);
-
-  // Global keyboard shortcuts
-  useInput((input, key) => {
-    if (currentView.type === 'raw' || currentView.type === 'begin-session' || currentView.type === 'tool-detail') {
-      // Don't capture single-char shortcuts when text input is active
-      if (key.escape) popView();
-      return;
-    }
-
-    if (input === 'q' && !key.ctrl) {
-      session.close().catch(() => {});
-      exit();
-      return;
-    }
-
-    if (key.escape) {
-      popView();
-      return;
-    }
-
-    if (input === 'n') {
-      reconnect();
-      return;
-    }
-
-    if (input === 'r') {
-      pushView({ type: 'raw' });
-      return;
-    }
-  });
-
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      session.close().catch(() => {});
-    };
-  }, [session]);
-
-  const contentHeight = Math.max(1, termHeight - logHeight - 4); // 4 for header + mode bar + borders
-
-  return (
-    <SessionContext.Provider value={{ session, projectName, endpointUrl, token }}>
-      <Box flexDirection="column" height={termHeight}>
-        <Header
-          projectName={projectName}
-          sessionId={session.getSessionId()}
-          gated={state.gated}
-          reconnecting={state.reconnecting}
-        />
-
-        {state.error && (
-          <Box paddingX={1}>
-            <Text color="red">{state.error}</Text>
-          </Box>
-        )}
-
-        <Box flexDirection="column" height={contentHeight} paddingX={1}>
-          {currentView.type === 'connecting' && <ConnectingView />}
-          {currentView.type === 'main' && (
-            <MainMenu
-              gated={state.gated}
-              toolCount={state.tools.length}
-              resourceCount={state.resources.length}
-              promptCount={state.prompts.length}
-              onSelect={(action) => {
-                switch (action) {
-                  case 'begin-session':
-                    pushView({ type: 'begin-session' });
-                    break;
-                  case 'tools':
-                    pushView({ type: 'tools' });
-                    break;
-                  case 'resources':
-                    pushView({ type: 'resources' });
-                    break;
-                  case 'prompts':
-                    pushView({ type: 'prompts' });
-                    break;
-                  case 'raw':
-                    pushView({ type: 'raw' });
-                    break;
-                  case 'session-info':
-                    pushView({ type: 'result', title: 'Session Info', data: {
-                      sessionId: session.getSessionId(),
-                      gated: state.gated,
-                      initResult: state.initResult,
-                    }});
-                    break;
-                }
-              }}
-            />
-          )}
-          {currentView.type === 'begin-session' && (
-            <BeginSessionView
-              session={session}
-              onDone={onSessionBegan}
-              onError={setError}
-              onBack={popView}
-            />
-          )}
-          {currentView.type === 'tools' && (
-            <ToolListView
-              tools={state.tools}
-              onSelect={(tool) => pushView({ type: 'tool-detail', tool })}
-              onBack={popView}
-            />
-          )}
-          {currentView.type === 'tool-detail' && (
-            <ToolDetailView
-              tool={currentView.tool}
-              session={session}
-              onResult={(data) => pushView({ type: 'result', title: `Result: ${currentView.tool.name}`, data })}
-              onError={setError}
-              onBack={popView}
-            />
-          )}
-          {currentView.type === 'resources' && (
-            <ResourceListView
-              resources={state.resources}
-              session={session}
-              onResult={(resource, content) => pushView({ type: 'resource-detail', resource, content })}
-              onError={setError}
-              onBack={popView}
-            />
-          )}
-          {currentView.type === 'resource-detail' && (
-            <Box flexDirection="column">
-              <Text bold color="cyan">{currentView.resource.uri}</Text>
-              <Text>{currentView.content}</Text>
-            </Box>
-          )}
-          {currentView.type === 'prompts' && (
-            <PromptListView
-              prompts={state.prompts}
-              session={session}
-              onResult={(prompt, content) => pushView({ type: 'prompt-detail', prompt, content })}
-              onError={setError}
-              onBack={popView}
-            />
-          )}
-          {currentView.type === 'prompt-detail' && (
-            <Box flexDirection="column">
-              <Text bold color="cyan">{currentView.prompt.name}</Text>
-              <Text>{typeof currentView.content === 'string' ? currentView.content : JSON.stringify(currentView.content, null, 2)}</Text>
-            </Box>
-          )}
-          {currentView.type === 'raw' && (
-            <RawJsonRpcView
-              session={session}
-              onBack={popView}
-            />
-          )}
-          {currentView.type === 'result' && (
-            <ResultView
-              title={currentView.title}
-              data={currentView.data}
-            />
-          )}
-        </Box>
-
-        <ProtocolLog entries={state.logEntries} height={logHeight} />
-
-        <Box paddingX={1}>
-          <Text dimColor>
-            [↑↓] navigate  [Enter] select  [Esc] back  [n] new session  [r] raw  [q] quit
-          </Text>
-        </Box>
-      </Box>
-    </SessionContext.Provider>
-  );
-}
-
-// ── Render entrypoint ──
-
-export interface RenderOptions {
-  projectName: string;
-  endpointUrl: string;
-  token?: string;
-}
-
-export async function renderConsole(opts: RenderOptions): Promise<void> {
-  const instance = render(
-    <App projectName={opts.projectName} endpointUrl={opts.endpointUrl} token={opts.token} />,
-  );
-  await instance.waitUntilExit();
-}

src/cli/src/commands/console/components/action-area.tsx

@@ -0,0 +1,229 @@
+/**
+ * ActionArea — context-sensitive bottom panel in the unified console.
+ *
+ * Renders the appropriate sub-view based on the current action state.
+ * Only one action at a time — Esc always returns to { type: 'none' }.
+ */
+
+import { Box, Text } from 'ink';
+import type { ActionState, TimelineEvent } from '../unified-types.js';
+import type { McpTool, McpSession, McpResource, McpPrompt } from '../mcp-session.js';
+import { formatTime, formatEventSummary, formatBodyDetail } from '../format-event.js';
+import { ProvenanceView } from './provenance-view.js';
+import { ToolDetailView } from './tool-detail.js';
+import { ToolListView } from './tool-list.js';
+import { ResourceListView } from './resource-list.js';
+import { PromptListView } from './prompt-list.js';
+import { RawJsonRpcView } from './raw-jsonrpc.js';
+
+interface ActionAreaProps {
+  action: ActionState;
+  events: TimelineEvent[];
+  session: McpSession;
+  tools: McpTool[];
+  resources: McpResource[];
+  prompts: McpPrompt[];
+  availableModels: string[];
+  height: number;
+  onSetAction: (action: ActionState) => void;
+  onError: (msg: string) => void;
+}
+
+export function ActionArea({
+  action,
+  events,
+  session,
+  tools,
+  resources,
+  prompts,
+  availableModels,
+  height,
+  onSetAction,
+  onError,
+}: ActionAreaProps) {
+  if (action.type === 'none') return null;
+
+  if (action.type === 'detail') {
+    const event = events[action.eventIdx];
+    if (!event) return null;
+    return <DetailView event={event} maxLines={height} scrollOffset={action.scrollOffset} horizontalOffset={action.horizontalOffset} searchQuery={action.searchQuery} searchMatches={action.searchMatches} searchMatchIdx={action.searchMatchIdx} searchMode={action.searchMode} />;
+  }
+
+  if (action.type === 'provenance') {
+    const clientEvent = events[action.clientEventIdx];
+    if (!clientEvent) return null;
+    return (
+      <ProvenanceView
+        clientEvent={clientEvent}
+        upstreamEvent={action.upstreamEvent}
+        height={height}
+        scrollOffset={action.scrollOffset}
+        horizontalOffset={action.horizontalOffset}
+        focusedPanel={action.focusedPanel}
+        parameterIdx={action.parameterIdx}
+        replayConfig={action.replayConfig}
+        replayResult={action.replayResult}
+        replayRunning={action.replayRunning}
+        editingUpstream={action.editingUpstream}
+        editedContent={action.editedContent}
+        onEditContent={(text) => onSetAction({ ...action, editedContent: text })}
+        proxyModelDetails={action.proxyModelDetails}
+        liveOverride={action.liveOverride}
+        serverList={action.serverList}
+        serverOverrides={action.serverOverrides}
+        selectedServerIdx={action.selectedServerIdx}
+        serverPickerOpen={action.serverPickerOpen}
+        modelPickerOpen={action.modelPickerOpen}
+        modelPickerIdx={action.modelPickerIdx}
+        availableModels={availableModels}
+        searchMode={action.searchMode}
+        searchQuery={action.searchQuery}
+        searchMatches={action.searchMatches}
+        searchMatchIdx={action.searchMatchIdx}
+      />
+    );
+  }
+
+  if (action.type === 'tool-input') {
+    return (
+      <Box flexDirection="column" height={height} borderStyle="round" borderColor="gray" paddingX={1}>
+        <ToolDetailView
+          tool={action.tool}
+          session={session}
+          onResult={() => onSetAction({ type: 'none' })}
+          onError={onError}
+          onBack={() => onSetAction({ type: 'none' })}
+          onLoadingChange={(loading) => onSetAction({ ...action, loading })}
+        />
+      </Box>
+    );
+  }
+
+  if (action.type === 'tool-browser') {
+    return (
+      <Box flexDirection="column" height={height} borderStyle="round" borderColor="gray" paddingX={1}>
+        <ToolListView
+          tools={tools}
+          onSelect={(tool) => onSetAction({ type: 'tool-input', tool, loading: false })}
+          onBack={() => onSetAction({ type: 'none' })}
+        />
+      </Box>
+    );
+  }
+
+  if (action.type === 'resource-browser') {
+    return (
+      <Box flexDirection="column" height={height} borderStyle="round" borderColor="gray" paddingX={1}>
+        <ResourceListView
+          resources={resources}
+          session={session}
+          onResult={() => {}}
+          onError={onError}
+          onBack={() => onSetAction({ type: 'none' })}
+        />
+      </Box>
+    );
+  }
+
+  if (action.type === 'prompt-browser') {
+    return (
+      <Box flexDirection="column" height={height} borderStyle="round" borderColor="gray" paddingX={1}>
+        <PromptListView
+          prompts={prompts}
+          session={session}
+          onResult={() => {}}
+          onError={onError}
+          onBack={() => onSetAction({ type: 'none' })}
+        />
+      </Box>
+    );
+  }
+
+  if (action.type === 'raw-jsonrpc') {
+    return (
+      <Box flexDirection="column" height={height} borderStyle="round" borderColor="gray" paddingX={1}>
+        <RawJsonRpcView
+          session={session}
+          onBack={() => onSetAction({ type: 'none' })}
+        />
+      </Box>
+    );
+  }
+
+  return null;
+}
+
+// ── Detail View ──
+
+function DetailView({ event, maxLines, scrollOffset, horizontalOffset, searchQuery, searchMatches, searchMatchIdx, searchMode }: {
+  event: TimelineEvent;
+  maxLines: number;
+  scrollOffset: number;
+  horizontalOffset: number;
+  searchQuery: string;
+  searchMatches: number[];
+  searchMatchIdx: number;
+  searchMode: boolean;
+}) {
+  const { arrow, color, label } = formatEventSummary(
+    event.eventType,
+    event.method,
+    event.body,
+    event.upstreamName,
+    event.durationMs,
+  );
+  const allLines = formatBodyDetail(event.eventType, event.method ?? '', event.body);
+  const hasSearch = searchQuery.length > 0 || searchMode;
+  const bodyHeight = maxLines - 3 - (hasSearch ? 1 : 0);
+  const visibleLines = allLines.slice(scrollOffset, scrollOffset + bodyHeight);
+  const totalLines = allLines.length;
+  const canScroll = totalLines > bodyHeight;
+  const atEnd = scrollOffset + bodyHeight >= totalLines;
+
+  // Which absolute line indices are in the visible window?
+  const matchSet = new Set(searchMatches);
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="gray" paddingX={1} height={maxLines}>
+      <Text bold>
+        <Text color={color}>{arrow} {label}</Text>
+        <Text dimColor>  {formatTime(event.timestamp)}  {event.projectName}/{event.sessionId.slice(0, 8)}</Text>
+        {event.correlationId && <Text dimColor>{'  \u26D3'}</Text>}
+        {canScroll ? (
+          <Text dimColor>  [{scrollOffset + 1}-{Math.min(scrollOffset + bodyHeight, totalLines)}/{totalLines}]</Text>
+        ) : null}
+        {horizontalOffset > 0 && <Text dimColor>  col:{horizontalOffset}</Text>}
+      </Text>
+      <Text dimColor>{'\u2191\u2193:scroll  \u2190\u2192:pan  p:provenance  /:search  PgDn/PgUp:next/prev  Esc:close'}</Text>
+      {visibleLines.map((line, i) => {
+        const absIdx = scrollOffset + i;
+        const isMatch = matchSet.has(absIdx);
+        const isCurrent = searchMatches[searchMatchIdx] === absIdx;
+        const displayLine = horizontalOffset > 0 ? line.slice(horizontalOffset) : line;
+        return (
+          <Text key={i} wrap="truncate" dimColor={!isMatch && line.startsWith('  ')}
+            backgroundColor={isCurrent ? 'yellow' : isMatch ? 'gray' : undefined}
+            color={isCurrent ? 'black' : isMatch ? 'white' : undefined}
+          >
+            {displayLine}
+          </Text>
+        );
+      })}
+      {canScroll && !atEnd && (
+        <Text dimColor>{'\u2026 +'}{totalLines - scrollOffset - bodyHeight}{' more lines \u2193'}</Text>
+      )}
+      {hasSearch && (
+        <Text>
+          <Text color="cyan">/{searchQuery}</Text>
+          {searchMatches.length > 0 && (
+            <Text dimColor> [{searchMatchIdx + 1}/{searchMatches.length}]  n:next N:prev Esc:clear</Text>
+          )}
+          {searchQuery.length > 0 && searchMatches.length === 0 && (
+            <Text dimColor> (no matches)</Text>
+          )}
+          {searchMode && <Text color="cyan">_</Text>}
+        </Text>
+      )}
+    </Box>
+  );
+}

src/cli/src/commands/console/components/begin-session.tsx

@@ -1,36 +1,92 @@
 import { useState } from 'react';
 import { Box, Text } from 'ink';
 import { TextInput, Spinner } from '@inkjs/ui';
-import type { McpSession } from '../mcp-session.js';
+import type { McpTool, McpSession } from '../mcp-session.js';
 
 interface BeginSessionViewProps {
+  tool: McpTool;
   session: McpSession;
   onDone: (result: unknown) => void;
   onError: (msg: string) => void;
   onBack: () => void;
+  onLoadingChange?: (loading: boolean) => void;
 }
 
-export function BeginSessionView({ session, onDone, onError }: BeginSessionViewProps) {
-  const [loading, setLoading] = useState(false);
+interface SchemaProperty {
+  type?: string;
+  description?: string;
+  items?: { type?: string };
+  maxItems?: number;
+}
+
+/**
+ * Dynamically renders a form for the begin_session tool based on its
+ * inputSchema from the MCP protocol. Adapts to whatever the server sends:
+ * - string properties → text input
+ * - array of strings → comma-separated text input
+ * - multiple/unknown properties → raw JSON input
+ */
+export function BeginSessionView({ tool, session, onDone, onError, onLoadingChange }: BeginSessionViewProps) {
+  const [loading, _setLoading] = useState(false);
+  const setLoading = (v: boolean) => { _setLoading(v); onLoadingChange?.(v); };
   const [input, setInput] = useState('');
 
-  const handleSubmit = async () => {
-    const tags = input
-      .split(',')
-      .map((t) => t.trim())
-      .filter((t) => t.length > 0);
+  const schema = tool.inputSchema as {
+    properties?: Record<string, SchemaProperty>;
+    required?: string[];
+  } | undefined;
 
-    if (tags.length === 0) {
-      onError('Enter at least one tag (comma-separated)');
-      return;
+  const properties = schema?.properties ?? {};
+  const propEntries = Object.entries(properties);
+
+  // Determine mode: focused single-property or generic JSON
+  const singleProp = propEntries.length === 1 ? propEntries[0]! : null;
+  const propName = singleProp?.[0];
+  const propDef = singleProp?.[1];
+  const isArray = propDef?.type === 'array';
+
+  const buildArgs = (): Record<string, unknown> | null => {
+    if (!singleProp) {
+      // JSON mode
+      try {
+        return JSON.parse(input) as Record<string, unknown>;
+      } catch {
+        onError('Invalid JSON');
+        return null;
+      }
     }
 
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+      onError(`${propName} is required`);
+      return null;
+    }
+
+    if (isArray) {
+      const items = trimmed
+        .split(',')
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+      if (items.length === 0) {
+        onError(`Enter at least one value for ${propName}`);
+        return null;
+      }
+      return { [propName!]: items };
+    }
+
+    return { [propName!]: trimmed };
+  };
+
+  const handleSubmit = async () => {
+    const args = buildArgs();
+    if (!args) return;
+
     setLoading(true);
     try {
-      const result = await session.callTool('begin_session', { tags });
+      const result = await session.callTool(tool.name, args);
       onDone(result);
     } catch (err) {
-      onError(`begin_session failed: ${err instanceof Error ? err.message : String(err)}`);
+      onError(`${tool.name} failed: ${err instanceof Error ? err.message : String(err)}`);
       setLoading(false);
     }
   };
@@ -38,22 +94,57 @@ export function BeginSessionView({ session, onDone, onError }: BeginSessionViewP
   if (loading) {
     return (
       <Box gap={1}>
-        <Spinner label="Calling begin_session..." />
+        <Spinner label={`Calling ${tool.name}...`} />
       </Box>
     );
   }
 
+  // Focused single-property mode
+  if (singleProp) {
+    const label = propDef?.description ?? propName!;
+    const hint = isArray ? 'comma-separated values' : 'text';
+
+    return (
+      <Box flexDirection="column">
+        <Text bold>{tool.description ?? tool.name}</Text>
+        <Text dimColor>{label}</Text>
+        <Box marginTop={1}>
+          <Text color="cyan">{propName}: </Text>
+          <TextInput
+            placeholder={hint}
+            onChange={setInput}
+            onSubmit={handleSubmit}
+          />
+        </Box>
+      </Box>
+    );
+  }
+
+  // Multi-property / unknown schema → JSON input
   return (
     <Box flexDirection="column">
-      <Text bold>Enter tags for begin_session (comma-separated):</Text>
-      <Text dimColor>Example: zigbee, pairing, mqtt</Text>
-      <Box marginTop={1}>
-        <Text color="cyan">Tags: </Text>
-        <TextInput
-          placeholder="tag1, tag2, tag3"
-          onChange={setInput}
-          onSubmit={handleSubmit}
-        />
+      <Text bold>{tool.description ?? tool.name}</Text>
+      {propEntries.length > 0 && (
+        <Box flexDirection="column" marginTop={1}>
+          <Text bold>Schema:</Text>
+          {propEntries.map(([name, def]) => (
+            <Text key={name} dimColor>
+              {name}: {def.type ?? 'any'}{def.description ? ` — ${def.description}` : ''}
+            </Text>
+          ))}
+        </Box>
+      )}
+      <Box flexDirection="column" marginTop={1}>
+        <Text bold>Arguments (JSON):</Text>
+        <Box>
+          <Text color="cyan">&gt; </Text>
+          <TextInput
+            placeholder="{}"
+            defaultValue="{}"
+            onChange={setInput}
+            onSubmit={handleSubmit}
+          />
+        </Box>
       </Box>
     </Box>
   );

src/cli/src/commands/console/components/diff-renderer.tsx

@@ -0,0 +1,185 @@
+/**
+ * Diff computation and rendering for the Provenance view.
+ *
+ * Uses the `diff` package for line-level diffs with:
+ *   - 3-line context around changes
+ *   - Collapsed unchanged regions (GitKraken style)
+ *   - vimdiff-style coloring (red=removed, green=added)
+ */
+
+import { Text } from 'ink';
+import { diffLines } from 'diff';
+
+// ── Types ──
+
+export type DiffLineKind = 'added' | 'removed' | 'context' | 'collapsed';
+
+export interface DiffLine {
+  kind: DiffLineKind;
+  text: string;
+  collapsedCount?: number; // only for 'collapsed' kind
+}
+
+export interface DiffStats {
+  added: number;
+  removed: number;
+  pctChanged: number;
+}
+
+export interface DiffResult {
+  lines: DiffLine[];
+  stats: DiffStats;
+}
+
+// ── Compute diff with context and collapsing ──
+
+const DEFAULT_CONTEXT = 3;
+
+export function computeDiffLines(
+  upstream: string,
+  transformed: string,
+  contextLines = DEFAULT_CONTEXT,
+): DiffResult {
+  if (upstream === transformed) {
+    // Identical — show single collapsed block
+    const lineCount = upstream.split('\n').length;
+    return {
+      lines: [{ kind: 'collapsed', text: `${lineCount} unchanged lines`, collapsedCount: lineCount }],
+      stats: { added: 0, removed: 0, pctChanged: 0 },
+    };
+  }
+
+  const changes = diffLines(upstream, transformed);
+
+  // Step 1: Flatten changes into individual tagged lines
+  interface TaggedLine { kind: 'added' | 'removed' | 'unchanged'; text: string }
+  const tagged: TaggedLine[] = [];
+
+  for (const change of changes) {
+    const lines = change.value.replace(/\n$/, '').split('\n');
+    const kind: TaggedLine['kind'] = change.added ? 'added' : change.removed ? 'removed' : 'unchanged';
+    for (const line of lines) {
+      tagged.push({ kind, text: line });
+    }
+  }
+
+  // Step 2: Mark which unchanged lines are within context range of a change
+  const inContext = new Set<number>();
+  for (let i = 0; i < tagged.length; i++) {
+    if (tagged[i]!.kind !== 'unchanged') {
+      // Mark contextLines before and after
+      for (let j = Math.max(0, i - contextLines); j <= Math.min(tagged.length - 1, i + contextLines); j++) {
+        if (tagged[j]!.kind === 'unchanged') {
+          inContext.add(j);
+        }
+      }
+    }
+  }
+
+  // Step 3: Build output with collapsed regions
+  const result: DiffLine[] = [];
+  let collapsedRun = 0;
+
+  for (let i = 0; i < tagged.length; i++) {
+    const line = tagged[i]!;
+    if (line.kind !== 'unchanged') {
+      // Flush collapsed
+      if (collapsedRun > 0) {
+        result.push({ kind: 'collapsed', text: `${collapsedRun} unchanged lines`, collapsedCount: collapsedRun });
+        collapsedRun = 0;
+      }
+      result.push({ kind: line.kind, text: line.text });
+    } else if (inContext.has(i)) {
+      // Context line
+      if (collapsedRun > 0) {
+        result.push({ kind: 'collapsed', text: `${collapsedRun} unchanged lines`, collapsedCount: collapsedRun });
+        collapsedRun = 0;
+      }
+      result.push({ kind: 'context', text: line.text });
+    } else {
+      collapsedRun++;
+    }
+  }
+
+  // Flush trailing collapsed
+  if (collapsedRun > 0) {
+    result.push({ kind: 'collapsed', text: `${collapsedRun} unchanged lines`, collapsedCount: collapsedRun });
+  }
+
+  // Stats
+  let added = 0;
+  let removed = 0;
+  for (const t of tagged) {
+    if (t.kind === 'added') added++;
+    if (t.kind === 'removed') removed++;
+  }
+  const total = Math.max(1, tagged.length - added); // original line count approximation
+  const pctChanged = Math.round(((added + removed) / (total + added)) * 100);
+
+  return { lines: result, stats: { added, removed, pctChanged } };
+}
+
+// ── Format header stats ──
+
+export function formatDiffStats(stats: DiffStats): string {
+  if (stats.added === 0 && stats.removed === 0) return 'no changes';
+  const parts: string[] = [];
+  if (stats.added > 0) parts.push(`+${stats.added}`);
+  if (stats.removed > 0) parts.push(`-${stats.removed}`);
+  parts.push(`${stats.pctChanged}% chg`);
+  return parts.join(' ');
+}
+
+// ── Rendering component ──
+
+interface DiffPanelProps {
+  lines: DiffLine[];
+  scrollOffset: number;
+  height: number;
+  horizontalOffset?: number;
+}
+
+function hSlice(text: string, offset: number): string {
+  return offset > 0 ? text.slice(offset) : text;
+}
+
+export function DiffPanel({ lines, scrollOffset, height, horizontalOffset = 0 }: DiffPanelProps) {
+  const visible = lines.slice(scrollOffset, scrollOffset + height);
+  const hasMore = lines.length > scrollOffset + height;
+
+  return (
+    <>
+      {visible.map((line, i) => {
+        switch (line.kind) {
+          case 'added':
+            return (
+              <Text key={i} wrap="truncate" color="green">
+                {'+ '}{hSlice(line.text, horizontalOffset)}
+              </Text>
+            );
+          case 'removed':
+            return (
+              <Text key={i} wrap="truncate" color="red">
+                {'- '}{hSlice(line.text, horizontalOffset)}
+              </Text>
+            );
+          case 'context':
+            return (
+              <Text key={i} wrap="truncate" dimColor>
+                {'  '}{hSlice(line.text, horizontalOffset)}
+              </Text>
+            );
+          case 'collapsed':
+            return (
+              <Text key={i} wrap="truncate" color="gray">
+                {'\u2504\u2504\u2504 '}{line.text}{' \u2504\u2504\u2504'}
+              </Text>
+            );
+        }
+      })}
+      {hasMore && (
+        <Text dimColor>{'\u2026'} +{lines.length - scrollOffset - height} more</Text>
+      )}
+    </>
+  );
+}

src/cli/src/commands/console/components/protocol-log.tsx

@@ -1,55 +0,0 @@
-import { Box, Text } from 'ink';
-import type { LogEntry } from '../mcp-session.js';
-
-interface ProtocolLogProps {
-  entries: LogEntry[];
-  height: number;
-}
-
-function truncate(s: string, maxLen: number): string {
-  return s.length > maxLen ? s.slice(0, maxLen - 3) + '...' : s;
-}
-
-function formatBody(body: unknown): string {
-  if (typeof body === 'string') return body;
-  try {
-    return JSON.stringify(body);
-  } catch {
-    return String(body);
-  }
-}
-
-export function ProtocolLog({ entries, height }: ProtocolLogProps) {
-  const visible = entries.slice(-height);
-  const maxBodyLen = 120;
-
-  return (
-    <Box
-      flexDirection="column"
-      height={height}
-      borderStyle="single"
-      borderTop={true}
-      borderBottom={false}
-      borderLeft={false}
-      borderRight={false}
-      paddingX={1}
-    >
-      <Text bold dimColor>Protocol Log ({entries.length} entries)</Text>
-      {visible.map((entry, i) => {
-        const arrow = entry.direction === 'request' ? '→' : entry.direction === 'error' ? '✗' : '←';
-        const color = entry.direction === 'request' ? 'green' : entry.direction === 'error' ? 'red' : 'blue';
-        const method = entry.method ? ` ${entry.method}` : '';
-        const body = truncate(formatBody(entry.body), maxBodyLen);
-
-        return (
-          <Text key={i} wrap="truncate">
-            <Text color={color}>{arrow}</Text>
-            <Text bold color={color}>{method}</Text>
-            <Text dimColor> {body}</Text>
-          </Text>
-        );
-      })}
-      {visible.length === 0 && <Text dimColor>(no traffic yet)</Text>}
-    </Box>
-  );
-}

src/cli/src/commands/console/components/provenance-view.tsx

@@ -0,0 +1,363 @@
+/**
+ * ProvenanceView — 4-quadrant display:
+ *   Top-left:  Parameters (proxymodel, LLM config, live override, server)
+ *   Top-right: Preview (diff from upstream after replay)
+ *   Bottom-left:  Upstream (raw) — the origin, optionally editable
+ *   Bottom-right: Client (diff from upstream)
+ */
+
+import { Box, Text } from 'ink';
+import { Spinner, TextInput } from '@inkjs/ui';
+import type { TimelineEvent, ReplayConfig, ReplayResult, ProxyModelDetails } from '../unified-types.js';
+import { computeDiffLines, formatDiffStats, DiffPanel } from './diff-renderer.js';
+
+interface ProvenanceViewProps {
+  clientEvent: TimelineEvent;
+  upstreamEvent: TimelineEvent | null;
+  height: number;
+  scrollOffset: number;
+  horizontalOffset: number;
+  focusedPanel: 'client' | 'upstream' | 'parameters' | 'preview';
+  parameterIdx: number; // 0=ProxyModel, 1=Provider, 2=Model, 3=Live, 4=Server
+  replayConfig: ReplayConfig;
+  replayResult: ReplayResult | null;
+  replayRunning: boolean;
+  editingUpstream: boolean;
+  editedContent: string;
+  onEditContent: (text: string) => void;
+  proxyModelDetails: ProxyModelDetails | null;
+  liveOverride: boolean;
+  serverList: string[];
+  serverOverrides: Record<string, string>;
+  selectedServerIdx: number;
+  serverPickerOpen: boolean;
+  modelPickerOpen: boolean;
+  modelPickerIdx: number;
+  availableModels: string[];
+  searchMode: boolean;
+  searchQuery: string;
+  searchMatches: number[];
+  searchMatchIdx: number;
+}
+
+export function getContentText(event: TimelineEvent): string {
+  const body = event.body as Record<string, unknown> | null;
+  if (!body) return '(no body)';
+
+  const result = body['result'] as Record<string, unknown> | undefined;
+  if (!result) return JSON.stringify(body, null, 2);
+
+  const content = (result['content'] ?? result['contents'] ?? []) as Array<{ text?: string }>;
+  if (content.length > 0) {
+    return content.map((c) => c.text ?? '').join('\n');
+  }
+
+  return JSON.stringify(result, null, 2);
+}
+
+export function ProvenanceView({
+  clientEvent,
+  upstreamEvent,
+  height,
+  scrollOffset,
+  horizontalOffset,
+  focusedPanel,
+  parameterIdx,
+  replayConfig,
+  replayResult,
+  replayRunning,
+  editingUpstream,
+  editedContent,
+  onEditContent,
+  proxyModelDetails,
+  liveOverride,
+  serverList,
+  serverOverrides,
+  selectedServerIdx,
+  serverPickerOpen,
+  modelPickerOpen,
+  modelPickerIdx,
+  availableModels,
+  searchMode,
+  searchQuery,
+  searchMatches,
+  searchMatchIdx,
+}: ProvenanceViewProps) {
+  // Split height: top half for params+preview, bottom half for upstream+client
+  const topHeight = Math.max(4, Math.floor((height - 2) * 0.35));
+  const bottomHeight = Math.max(4, height - topHeight - 2);
+
+  const upstreamText = editedContent || (upstreamEvent ? getContentText(upstreamEvent) : '(no upstream event found)');
+  const clientText = getContentText(clientEvent);
+  const upstreamChars = upstreamText.length;
+
+  // Upstream raw lines (for the origin panel)
+  const upstreamLines = upstreamText.split('\n');
+  const bottomBodyHeight = Math.max(1, bottomHeight - 3);
+  // Route scrollOffset and horizontalOffset to only the focused panel
+  const upstreamScroll = focusedPanel === 'upstream' ? scrollOffset : 0;
+  const clientScroll = focusedPanel === 'client' ? scrollOffset : 0;
+  const previewScroll = focusedPanel === 'preview' ? scrollOffset : 0;
+  const upstreamHScroll = focusedPanel === 'upstream' ? horizontalOffset : 0;
+  const clientHScroll = focusedPanel === 'client' ? horizontalOffset : 0;
+  const previewHScroll = focusedPanel === 'preview' ? horizontalOffset : 0;
+  const upstreamVisible = upstreamLines.slice(upstreamScroll, upstreamScroll + bottomBodyHeight);
+
+  // Client diff (from upstream)
+  const clientDiff = computeDiffLines(upstreamText, clientText);
+
+  // Preview diff (from upstream, when replay result available)
+  let previewDiff = { lines: [] as ReturnType<typeof computeDiffLines>['lines'], stats: { added: 0, removed: 0, pctChanged: 0 } };
+  let previewError: string | null = null;
+  let previewReady = false;
+
+  if (replayRunning) {
+    // spinner handles this
+  } else if (replayResult?.error) {
+    previewError = replayResult.error;
+  } else if (replayResult) {
+    previewDiff = computeDiffLines(upstreamText, replayResult.content);
+    previewReady = true;
+  }
+
+  const previewBodyHeight = Math.max(1, topHeight - 3);
+
+  // Server display for row 4 — show per-server override if set
+  const selectedServerName = selectedServerIdx >= 0 ? serverList[selectedServerIdx] : undefined;
+  const serverOverrideModel = selectedServerName ? serverOverrides[selectedServerName] : undefined;
+  const serverDisplay = selectedServerIdx < 0
+    ? '(project-wide)'
+    : `${selectedServerName ?? '(unknown)'}${serverOverrideModel ? ` [${serverOverrideModel}]` : ''}`;
+
+  // Build parameter rows
+  const paramRows = [
+    { label: 'ProxyModel', value: replayConfig.proxyModel },
+    { label: 'Provider  ', value: replayConfig.provider ?? '(default)' },
+    { label: 'Model     ', value: replayConfig.llmModel ?? '(default)' },
+    { label: 'Live      ', value: liveOverride ? 'ON' : 'OFF', isLive: true },
+    { label: 'Server    ', value: serverDisplay },
+  ];
+
+  // Build preview header
+  let previewHeader = 'Preview';
+  if (replayRunning) {
+    previewHeader = 'Preview (running...)';
+  } else if (previewError) {
+    previewHeader = 'Preview (error)';
+  } else if (previewReady) {
+    previewHeader = `Preview (diff, ${formatDiffStats(previewDiff.stats)})`;
+  }
+
+  // Build client header
+  const clientHeader = `Client (diff, ${formatDiffStats(clientDiff.stats)})`;
+
+  // Show tooltip when ProxyModel row focused
+  const showTooltip = focusedPanel === 'parameters' && parameterIdx === 0 && proxyModelDetails != null;
+
+  return (
+    <Box flexDirection="column" height={height}>
+      {/* Top row: Parameters + Preview */}
+      <Box flexDirection="row" height={topHeight}>
+        {/* Parameters panel */}
+        <Box
+          flexDirection="column"
+          width="50%"
+          borderStyle="single"
+          borderColor={focusedPanel === 'parameters' ? 'cyan' : 'gray'}
+          paddingX={1}
+        >
+          {/* When server picker is open, show ONLY the picker (full panel height) */}
+          {serverPickerOpen && focusedPanel === 'parameters' && parameterIdx === 4 ? (
+            <>
+              <Text bold color="cyan">Select Server</Text>
+              <Text key="project-wide">
+                <Text color={selectedServerIdx === -1 ? 'cyan' : undefined}>
+                  {selectedServerIdx === -1 ? '\u25B6 ' : '  '}
+                </Text>
+                <Text bold={selectedServerIdx === -1}>(project-wide)</Text>
+                {serverOverrides['*'] && <Text dimColor> [{serverOverrides['*']}]</Text>}
+              </Text>
+              {serverList.map((name, i) => (
+                <Text key={name}>
+                  <Text color={selectedServerIdx === i ? 'cyan' : undefined}>
+                    {selectedServerIdx === i ? '\u25B6 ' : '  '}
+                  </Text>
+                  <Text bold={selectedServerIdx === i}>{name}</Text>
+                  {serverOverrides[name] && <Text dimColor> [{serverOverrides[name]}]</Text>}
+                </Text>
+              ))}
+              <Text dimColor>{'\u2191\u2193'}:navigate  Enter:select  Esc:cancel</Text>
+            </>
+          ) : modelPickerOpen && focusedPanel === 'parameters' && selectedServerIdx >= 0 ? (
+            <>
+              <Text bold color="cyan">
+                ProxyModel for {serverList[selectedServerIdx] ?? '(unknown)'}
+              </Text>
+              {availableModels.map((name, i) => {
+                const serverName = serverList[selectedServerIdx] ?? '';
+                const isCurrentOverride = serverOverrides[serverName] === name;
+                return (
+                  <Text key={name}>
+                    <Text color={modelPickerIdx === i ? 'cyan' : undefined}>
+                      {modelPickerIdx === i ? '\u25B6 ' : '  '}
+                    </Text>
+                    <Text bold={modelPickerIdx === i}>{name}</Text>
+                    {isCurrentOverride && <Text color="green"> (active)</Text>}
+                  </Text>
+                );
+              })}
+              <Text dimColor>{'\u2191\u2193'}:navigate  Enter:apply  Esc:cancel</Text>
+            </>
+          ) : (
+            <>
+              <Text bold color={focusedPanel === 'parameters' ? 'cyan' : 'magenta'}>Parameters</Text>
+              {paramRows.map((row, i) => {
+                const isFocused = focusedPanel === 'parameters' && parameterIdx === i;
+                const isLiveRow = 'isLive' in row;
+                return (
+                  <Text key={i}>
+                    <Text color={isFocused ? 'cyan' : undefined}>{isFocused ? '\u25C0 ' : '  '}</Text>
+                    <Text dimColor={!isFocused}>{row.label}: </Text>
+                    {isLiveRow ? (
+                      <Text bold={isFocused} color={liveOverride ? 'green' : undefined}>
+                        {row.value}
+                      </Text>
+                    ) : (
+                      <Text bold={isFocused}>{row.value}</Text>
+                    )}
+                    <Text color={isFocused ? 'cyan' : undefined}>{isFocused ? ' \u25B6' : ''}</Text>
+                  </Text>
+                );
+              })}
+
+              {/* ProxyModel details tooltip */}
+              {showTooltip && proxyModelDetails && (
+                <Box
+                  flexDirection="column"
+                  borderStyle="round"
+                  borderColor="magenta"
+                  paddingX={1}
+                  marginTop={0}
+                >
+                  <Text bold color="magenta">{proxyModelDetails.name}</Text>
+                  <Text dimColor>
+                    {proxyModelDetails.source}
+                    {proxyModelDetails.cacheable ? ', cached' : ''}
+                    {proxyModelDetails.appliesTo.length > 0 ? ` \u00B7 ${proxyModelDetails.appliesTo.join(', ')}` : ''}
+                  </Text>
+                  {proxyModelDetails.stages.map((stage, i) => (
+                    <Text key={i}>
+                      <Text color="yellow">{i + 1}. {stage.type}</Text>
+                      {stage.config && Object.keys(stage.config).length > 0 && (
+                        <Text dimColor>
+                          {' '}{Object.entries(stage.config).map(([k, v]) => `${k}=${String(v)}`).join(' ')}
+                        </Text>
+                      )}
+                    </Text>
+                  ))}
+                </Box>
+              )}
+
+              {/* Per-server overrides summary */}
+              {Object.keys(serverOverrides).length > 0 && (
+                <Text dimColor wrap="truncate">
+                  Overrides: {Object.entries(serverOverrides).map(([s, m]) => `${s}=${m}`).join(', ')}
+                </Text>
+              )}
+            </>
+          )}
+        </Box>
+
+        {/* Preview panel — diff from upstream */}
+        <Box
+          flexDirection="column"
+          width="50%"
+          borderStyle="single"
+          borderColor={focusedPanel === 'preview' ? 'cyan' : 'gray'}
+          paddingX={1}
+        >
+          <Text bold color={focusedPanel === 'preview' ? 'cyan' : 'green'}>
+            {previewHeader}
+          </Text>
+          {replayRunning ? (
+            <Spinner label="Running replay..." />
+          ) : previewError ? (
+            <Text color="red" wrap="truncate">Error: {previewError}</Text>
+          ) : previewReady ? (
+            <DiffPanel lines={previewDiff.lines} scrollOffset={previewScroll} height={previewBodyHeight} horizontalOffset={previewHScroll} />
+          ) : (
+            <Text dimColor>Press Enter to run preview</Text>
+          )}
+        </Box>
+      </Box>
+
+      {/* Bottom row: Upstream (raw) + Client (diff) */}
+      <Box flexDirection="row" height={bottomHeight}>
+        {/* Upstream panel — origin, raw text */}
+        <Box
+          flexDirection="column"
+          width="50%"
+          borderStyle="single"
+          borderColor={focusedPanel === 'upstream' ? 'cyan' : 'gray'}
+          paddingX={1}
+        >
+          <Box>
+            <Text bold color={focusedPanel === 'upstream' ? 'cyan' : 'yellowBright'}>
+              Upstream (raw, {upstreamChars} chars)
+            </Text>
+            {editingUpstream && <Text color="yellow"> [EDITING]</Text>}
+          </Box>
+          {upstreamEvent?.upstreamName && upstreamEvent.upstreamName.includes(',') && (
+            <Text dimColor wrap="truncate">{upstreamEvent.upstreamName}</Text>
+          )}
+          {editingUpstream ? (
+            <Box flexGrow={1}>
+              <TextInput defaultValue={editedContent} onChange={onEditContent} />
+            </Box>
+          ) : (
+            <>
+              {upstreamVisible.map((line, i) => (
+                <Text key={i} wrap="truncate">{upstreamHScroll > 0 ? (line || ' ').slice(upstreamHScroll) : (line || ' ')}</Text>
+              ))}
+              {upstreamLines.length > upstreamScroll + bottomBodyHeight && (
+                <Text dimColor>{'\u2026'} +{upstreamLines.length - upstreamScroll - bottomBodyHeight} more</Text>
+              )}
+            </>
+          )}
+        </Box>
+
+        {/* Client panel — diff from upstream */}
+        <Box
+          flexDirection="column"
+          width="50%"
+          borderStyle="single"
+          borderColor={focusedPanel === 'client' ? 'cyan' : 'gray'}
+          paddingX={1}
+        >
+          <Text bold color={focusedPanel === 'client' ? 'cyan' : 'blue'}>
+            {clientHeader}
+          </Text>
+          <DiffPanel lines={clientDiff.lines} scrollOffset={clientScroll} height={bottomBodyHeight} horizontalOffset={clientHScroll} />
+        </Box>
+      </Box>
+
+      {/* Footer */}
+      <Box paddingX={1}>
+        {searchMode || searchQuery.length > 0 ? (
+          <Text>
+            <Text color="cyan">/{searchQuery}</Text>
+            {searchMatches.length > 0 && (
+              <Text dimColor> [{searchMatchIdx + 1}/{searchMatches.length}]  n:next N:prev Esc:clear</Text>
+            )}
+            {searchQuery.length > 0 && searchMatches.length === 0 && (
+              <Text dimColor> (no matches)</Text>
+            )}
+            {searchMode && <Text color="cyan">_</Text>}
+          </Text>
+        ) : (
+          <Text dimColor>Tab:panel  {'\u2191\u2193'}:scroll  {'\u2190\u2192'}:pan/param  /:search  Enter:run/toggle  e:edit  Esc:close</Text>
+        )}
+      </Box>
+    </Box>
+  );
+}

src/cli/src/commands/console/components/session-sidebar.tsx

@@ -0,0 +1,321 @@
+/**
+ * SessionSidebar — project-grouped session list with "New Session" entry
+ * and project picker mode.
+ *
+ * Sessions are grouped by project name. Each project appears once as a header,
+ * with its sessions listed below. Discovers sessions from both the SSE snapshot
+ * AND traffic events so closed sessions still appear.
+ *
+ * selectedIdx: -2 = "New Session", -1 = all sessions, 0+ = individual sessions
+ */
+
+import { Box, Text } from 'ink';
+import type { ActiveSession, TimelineEvent } from '../unified-types.js';
+
+interface SessionSidebarProps {
+  interactiveSessionId: string | undefined;
+  observedSessions: ActiveSession[];
+  events: TimelineEvent[];
+  selectedIdx: number; // -2 = new session, -1 = all, 0+ = session
+  height: number;
+  projectName: string;
+  mode: 'sessions' | 'project-picker';
+  availableProjects: string[];
+  projectPickerIdx: number;
+}
+
+interface SessionEntry {
+  sessionId: string;
+  projectName: string;
+}
+
+interface ProjectGroup {
+  projectName: string;
+  sessions: SessionEntry[];
+}
+
+export function SessionSidebar({
+  interactiveSessionId,
+  observedSessions,
+  events,
+  selectedIdx,
+  height,
+  projectName,
+  mode,
+  availableProjects,
+  projectPickerIdx,
+}: SessionSidebarProps) {
+  if (mode === 'project-picker') {
+    return (
+      <ProjectPicker
+        projects={availableProjects}
+        selectedIdx={projectPickerIdx}
+        height={height}
+      />
+    );
+  }
+
+  const sessions = buildSessionList(interactiveSessionId, observedSessions, events, projectName);
+  const groups = groupByProject(sessions);
+
+  // Count events per session
+  const counts = new Map<string, number>();
+  for (const e of events) {
+    counts.set(e.sessionId, (counts.get(e.sessionId) ?? 0) + 1);
+  }
+
+  const headerLines = 3; // "Sessions (N)" + "New Session" + "all sessions"
+  const footerLines = 5; // keybinding help box
+  const bodyHeight = Math.max(1, height - headerLines - footerLines);
+
+  // Build flat render lines for scrolling
+  interface RenderLine {
+    type: 'project-header' | 'session';
+    projectName: string;
+    sessionId?: string;
+    flatSessionIdx?: number;
+  }
+
+  const lines: RenderLine[] = [];
+  let flatIdx = 0;
+  for (const group of groups) {
+    lines.push({ type: 'project-header', projectName: group.projectName });
+    for (const s of group.sessions) {
+      lines.push({ type: 'session', projectName: group.projectName, sessionId: s.sessionId, flatSessionIdx: flatIdx });
+      flatIdx++;
+    }
+  }
+
+  // Find which render line corresponds to the selected session
+  let selectedLineIdx = -1;
+  if (selectedIdx >= 0) {
+    selectedLineIdx = lines.findIndex((l) => l.flatSessionIdx === selectedIdx);
+  }
+
+  // Scroll to keep selected visible
+  let scrollStart = 0;
+  if (selectedLineIdx >= 0) {
+    if (selectedLineIdx >= scrollStart + bodyHeight) {
+      scrollStart = selectedLineIdx - bodyHeight + 1;
+    }
+    if (selectedLineIdx < scrollStart) {
+      scrollStart = selectedLineIdx;
+    }
+  }
+  scrollStart = Math.max(0, scrollStart);
+
+  const visibleLines = lines.slice(scrollStart, scrollStart + bodyHeight);
+  const hasMore = scrollStart + bodyHeight < lines.length;
+
+  return (
+    <Box
+      flexDirection="column"
+      width={32}
+      borderStyle="round"
+      borderColor="gray"
+      paddingX={1}
+      height={height}
+    >
+      <Text bold color="cyan">
+        {' Sessions '}
+        <Text dimColor>({sessions.length})</Text>
+      </Text>
+
+      {/* "New Session" row */}
+      <Text color={selectedIdx === -2 ? 'cyan' : 'green'} bold={selectedIdx === -2}>
+        {selectedIdx === -2 ? ' \u25b8 ' : '   '}
+        {'+ New Session'}
+      </Text>
+
+      {/* "All sessions" row */}
+      <Text color={selectedIdx === -1 ? 'cyan' : undefined} bold={selectedIdx === -1}>
+        {selectedIdx === -1 ? ' \u25b8 ' : '   '}
+        {'all sessions'}
+      </Text>
+
+      {/* Grouped session list */}
+      {sessions.length === 0 && (
+        <Box marginTop={1}>
+          <Text dimColor>{'   waiting for connections\u2026'}</Text>
+        </Box>
+      )}
+
+      {visibleLines.map((line, vi) => {
+        if (line.type === 'project-header') {
+          return (
+            <Text key={`proj-${line.projectName}-${vi}`} bold wrap="truncate">
+              {'  '}{line.projectName}
+            </Text>
+          );
+        }
+
+        // Session line
+        const isSelected = line.flatSessionIdx === selectedIdx;
+        const count = counts.get(line.sessionId!) ?? 0;
+        const isInteractive = line.sessionId === interactiveSessionId;
+
+        return (
+          <Text key={line.sessionId!} wrap="truncate">
+            <Text color={isSelected ? 'cyan' : undefined} bold={isSelected}>
+              {isSelected ? '  \u25b8 ' : '    '}
+              {line.sessionId!.slice(0, 8)}
+            </Text>
+            {count > 0 && <Text dimColor>{` \u00b7 ${count} ev`}</Text>}
+            {isInteractive && <Text color="green">{' *'}</Text>}
+          </Text>
+        );
+      })}
+
+      {hasMore && (
+        <Text dimColor>{'   \u2026 more'}</Text>
+      )}
+
+      {/* Spacer */}
+      <Box flexGrow={1} />
+
+      {/* Help */}
+      <Box borderStyle="single" borderTop borderColor="gray" paddingTop={0}>
+        <Text dimColor>
+          {'[\u2191\u2193] session [a] all\n[\u23ce] select  [Esc] close\n[x] clear   [q] quit'}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+/** Project picker sub-view */
+function ProjectPicker({
+  projects,
+  selectedIdx,
+  height,
+}: {
+  projects: string[];
+  selectedIdx: number;
+  height: number;
+}) {
+  const headerLines = 2;
+  const footerLines = 4;
+  const bodyHeight = Math.max(1, height - headerLines - footerLines);
+
+  let scrollStart = 0;
+  if (selectedIdx >= scrollStart + bodyHeight) {
+    scrollStart = selectedIdx - bodyHeight + 1;
+  }
+  if (selectedIdx < scrollStart) {
+    scrollStart = selectedIdx;
+  }
+  scrollStart = Math.max(0, scrollStart);
+
+  const visibleProjects = projects.slice(scrollStart, scrollStart + bodyHeight);
+  const hasMore = scrollStart + bodyHeight < projects.length;
+
+  return (
+    <Box
+      flexDirection="column"
+      width={32}
+      borderStyle="round"
+      borderColor="cyan"
+      paddingX={1}
+      height={height}
+    >
+      <Text bold color="cyan">
+        {' Select Project '}
+      </Text>
+
+      {projects.length === 0 ? (
+        <Box marginTop={1}>
+          <Text dimColor>{'   no projects found'}</Text>
+        </Box>
+      ) : (
+        visibleProjects.map((name, vi) => {
+          const realIdx = scrollStart + vi;
+          const isSelected = realIdx === selectedIdx;
+          return (
+            <Text key={name} wrap="truncate">
+              <Text color={isSelected ? 'cyan' : undefined} bold={isSelected}>
+                {isSelected ? ' \u25b8 ' : '   '}
+                {name}
+              </Text>
+            </Text>
+          );
+        })
+      )}
+
+      {hasMore && (
+        <Text dimColor>{'   \u2026 more'}</Text>
+      )}
+
+      {/* Spacer */}
+      <Box flexGrow={1} />
+
+      {/* Help */}
+      <Box borderStyle="single" borderTop borderColor="gray" paddingTop={0}>
+        <Text dimColor>
+          {'[\u2191\u2193] pick  [\u23ce] select\n[Esc] back'}
+        </Text>
+      </Box>
+    </Box>
+  );
+}
+
+/** Total session count across all groups */
+export function getSessionCount(
+  interactiveSessionId: string | undefined,
+  observedSessions: ActiveSession[],
+  events: TimelineEvent[],
+  projectName: string,
+): number {
+  return buildSessionList(interactiveSessionId, observedSessions, events, projectName).length;
+}
+
+function buildSessionList(
+  interactiveSessionId: string | undefined,
+  observedSessions: ActiveSession[],
+  events: TimelineEvent[],
+  projectName: string,
+): SessionEntry[] {
+  const result: SessionEntry[] = [];
+  const seen = new Set<string>();
+
+  // Interactive session first
+  if (interactiveSessionId) {
+    result.push({ sessionId: interactiveSessionId, projectName });
+    seen.add(interactiveSessionId);
+  }
+
+  // Then observed sessions from SSE snapshot
+  for (const s of observedSessions) {
+    if (!seen.has(s.sessionId)) {
+      result.push({ sessionId: s.sessionId, projectName: s.projectName });
+      seen.add(s.sessionId);
+    }
+  }
+
+  // Also discover sessions from traffic events (covers sessions that
+  // were already closed before the SSE connected)
+  for (const e of events) {
+    if (!seen.has(e.sessionId)) {
+      result.push({ sessionId: e.sessionId, projectName: e.projectName });
+      seen.add(e.sessionId);
+    }
+  }
+
+  return result;
+}
+
+function groupByProject(sessions: SessionEntry[]): ProjectGroup[] {
+  const map = new Map<string, SessionEntry[]>();
+  const order: string[] = [];
+
+  for (const s of sessions) {
+    let group = map.get(s.projectName);
+    if (!group) {
+      group = [];
+      map.set(s.projectName, group);
+      order.push(s.projectName);
+    }
+    group.push(s);
+  }
+
+  return order.map((name) => ({ projectName: name, sessions: map.get(name)! }));
+}

src/cli/src/commands/console/components/timeline.tsx

@@ -0,0 +1,95 @@
+/**
+ * Unified timeline — renders all events (interactive, observed)
+ * with a lane-colored gutter, windowed rendering, and auto-scroll.
+ */
+
+import { Box, Text } from 'ink';
+import type { TimelineEvent, EventLane } from '../unified-types.js';
+import { formatTime, formatEventSummary, trunc } from '../format-event.js';
+
+const LANE_COLORS: Record<EventLane, string> = {
+  interactive: 'green',
+  observed: 'yellow',
+};
+
+const LANE_MARKERS: Record<EventLane, string> = {
+  interactive: '\u2502',
+  observed: '\u2502',
+};
+
+interface TimelineProps {
+  events: TimelineEvent[];
+  height: number;
+  focusedIdx: number; // -1 = auto-scroll to bottom
+  showProject: boolean;
+}
+
+export function Timeline({ events, height, focusedIdx, showProject }: TimelineProps) {
+  const maxVisible = Math.max(1, height - 2); // header + spacing
+  let startIdx: number;
+  if (focusedIdx >= 0) {
+    startIdx = Math.max(0, Math.min(focusedIdx - Math.floor(maxVisible / 2), events.length - maxVisible));
+  } else {
+    startIdx = Math.max(0, events.length - maxVisible);
+  }
+  const visible = events.slice(startIdx, startIdx + maxVisible);
+
+  return (
+    <Box flexDirection="column" flexGrow={1} paddingLeft={1}>
+      <Text bold>
+        Timeline <Text dimColor>({events.length} events{focusedIdx >= 0 ? ` \u00B7 #${focusedIdx + 1}` : ''})</Text>
+      </Text>
+      {visible.length === 0 && (
+        <Box marginTop={1}>
+          <Text dimColor>{'  waiting for traffic\u2026'}</Text>
+        </Box>
+      )}
+      {visible.map((event, vi) => {
+        const absIdx = startIdx + vi;
+        const isFocused = absIdx === focusedIdx;
+        const { arrow, color, label, detail, detailColor } = formatEventSummary(
+          event.eventType,
+          event.method,
+          event.body,
+          event.upstreamName,
+          event.durationMs,
+        );
+        const isLifecycle = event.eventType === 'session_created' || event.eventType === 'session_closed';
+        const laneColor = LANE_COLORS[event.lane];
+        const laneMarker = LANE_MARKERS[event.lane];
+        const focusMarker = isFocused ? '\u25B8' : ' ';
+        const hasCorrelation = event.correlationId !== undefined;
+
+        if (isLifecycle) {
+          return (
+            <Text key={event.id} wrap="truncate">
+              <Text color={laneColor}>{laneMarker}</Text>
+              <Text color={isFocused ? 'cyan' : undefined}>{focusMarker}</Text>
+              <Text dimColor>{formatTime(event.timestamp)}  </Text>
+              <Text color={color} bold>{arrow} {label}</Text>
+              {showProject && <Text color="gray"> [{trunc(event.projectName, 12)}]</Text>}
+              <Text dimColor> {event.sessionId.slice(0, 8)}</Text>
+            </Text>
+          );
+        }
+
+        const isUpstream = event.eventType.startsWith('upstream_');
+
+        return (
+          <Text key={event.id} wrap="truncate">
+            <Text color={laneColor}>{laneMarker}</Text>
+            <Text color={isFocused ? 'cyan' : undefined}>{focusMarker}</Text>
+            <Text dimColor>{formatTime(event.timestamp)}  </Text>
+            {showProject && <Text color="gray">[{trunc(event.projectName, 12)}] </Text>}
+            <Text color={color}>{arrow} </Text>
+            <Text bold={!isUpstream} color={color}>{label}</Text>
+            {detail ? (
+              <Text color={detailColor} dimColor={!detailColor}> {detail}</Text>
+            ) : null}
+            {hasCorrelation && <Text dimColor>{' \u26D3'}</Text>}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}

src/cli/src/commands/console/components/tool-detail.tsx

@@ -9,6 +9,7 @@ interface ToolDetailViewProps {
   onResult: (data: unknown) => void;
   onError: (msg: string) => void;
   onBack: () => void;
+  onLoadingChange?: (loading: boolean) => void;
 }
 
 interface SchemaProperty {
@@ -16,8 +17,9 @@ interface SchemaProperty {
   description?: string;
 }
 
-export function ToolDetailView({ tool, session, onResult, onError }: ToolDetailViewProps) {
-  const [loading, setLoading] = useState(false);
+export function ToolDetailView({ tool, session, onResult, onError, onLoadingChange }: ToolDetailViewProps) {
+  const [loading, _setLoading] = useState(false);
+  const setLoading = (v: boolean) => { _setLoading(v); onLoadingChange?.(v); };
   const [argsJson, setArgsJson] = useState('{}');
 
   // Extract properties from input schema

src/cli/src/commands/console/components/toolbar.tsx

@@ -0,0 +1,46 @@
+/**
+ * Toolbar — compact 1-line bar showing Tools / Resources / Prompts / Raw JSON-RPC.
+ *
+ * Shown between the header and timeline when an interactive session is ungated.
+ * Items are selectable via Tab (focus on/off), ←/→ (cycle), Enter (open).
+ */
+
+import { Box, Text } from 'ink';
+
+interface ToolbarProps {
+  toolCount: number;
+  resourceCount: number;
+  promptCount: number;
+  focusedItem: number; // -1 = not focused, 0-3 = which item
+}
+
+const ITEMS = [
+  { label: 'Tools', key: 'tools' },
+  { label: 'Resources', key: 'resources' },
+  { label: 'Prompts', key: 'prompts' },
+  { label: 'Raw JSON-RPC', key: 'raw' },
+] as const;
+
+export function Toolbar({ toolCount, resourceCount, promptCount, focusedItem }: ToolbarProps) {
+  const counts = [toolCount, resourceCount, promptCount, -1]; // -1 = no count for raw
+
+  return (
+    <Box paddingX={1} height={1}>
+      {ITEMS.map((item, i) => {
+        const focused = focusedItem === i;
+        const count = counts[i]!;
+        const separator = i < ITEMS.length - 1 ? '  |  ' : '';
+
+        return (
+          <Text key={item.key}>
+            <Text color={focused ? 'cyan' : undefined} bold={focused} dimColor={!focused}>
+              {` ${item.label}`}
+              {count >= 0 && <Text>{` (${count})`}</Text>}
+            </Text>
+            {separator && <Text dimColor>{separator}</Text>}
+          </Text>
+        );
+      })}
+    </Box>
+  );
+}

src/cli/src/commands/console/format-event.ts

@@ -0,0 +1,310 @@
+/**
+ * Shared formatting functions for MCP traffic events.
+ *
+ * Extracted from inspect-app.tsx so they can be reused by
+ * the unified timeline, action area, and provenance views.
+ */
+
+import type { TrafficEventType } from './unified-types.js';
+
+/** Safely dig into unknown objects */
+export function dig(obj: unknown, ...keys: string[]): unknown {
+  let cur = obj;
+  for (const k of keys) {
+    if (cur === null || cur === undefined || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[k];
+  }
+  return cur;
+}
+
+export function trunc(s: string, maxLen: number): string {
+  return s.length > maxLen ? s.slice(0, maxLen - 1) + '\u2026' : s;
+}
+
+export function nameList(items: unknown[], key: string, max: number): string {
+  if (items.length === 0) return '(none)';
+  const names = items.map((it) => dig(it, key) as string).filter(Boolean);
+  const shown = names.slice(0, max);
+  const rest = names.length - shown.length;
+  return shown.join(', ') + (rest > 0 ? ` +${rest} more` : '');
+}
+
+export function formatTime(ts: Date | string): string {
+  try {
+    const d = typeof ts === 'string' ? new Date(ts) : ts;
+    return d.toLocaleTimeString('en-GB', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
+  } catch {
+    return '??:??:??';
+  }
+}
+
+/** Extract meaningful summary from request params (strips jsonrpc/id boilerplate) */
+export function summarizeRequest(method: string, body: unknown): string {
+  const params = dig(body, 'params') as Record<string, unknown> | undefined;
+
+  switch (method) {
+    case 'initialize': {
+      const name = dig(params, 'clientInfo', 'name') ?? '?';
+      const ver = dig(params, 'clientInfo', 'version') ?? '';
+      const proto = dig(params, 'protocolVersion') ?? '';
+      return `client=${name}${ver ? ` v${ver}` : ''} proto=${proto}`;
+    }
+    case 'tools/call': {
+      const toolName = dig(params, 'name') as string ?? '?';
+      const args = dig(params, 'arguments') as Record<string, unknown> | undefined;
+      if (!args || Object.keys(args).length === 0) return `${toolName}()`;
+      const pairs = Object.entries(args).map(([k, v]) => {
+        const vs = typeof v === 'string' ? v : JSON.stringify(v);
+        return `${k}: ${trunc(vs, 40)}`;
+      });
+      return `${toolName}(${trunc(pairs.join(', '), 80)})`;
+    }
+    case 'resources/read': {
+      const uri = dig(params, 'uri') as string ?? '';
+      return uri;
+    }
+    case 'prompts/get': {
+      const name = dig(params, 'name') as string ?? '';
+      return name;
+    }
+    case 'tools/list':
+    case 'resources/list':
+    case 'prompts/list':
+    case 'notifications/initialized':
+      return '';
+    default: {
+      if (!params || Object.keys(params).length === 0) return '';
+      const s = JSON.stringify(params);
+      return trunc(s, 80);
+    }
+  }
+}
+
+/** Extract meaningful summary from response result */
+export function summarizeResponse(method: string, body: unknown, durationMs?: number): string {
+  const error = dig(body, 'error') as { message?: string; code?: number } | undefined;
+  if (error) {
+    return `ERROR ${error.code ?? ''}: ${error.message ?? 'unknown'}`;
+  }
+
+  const result = dig(body, 'result') as Record<string, unknown> | undefined;
+  if (!result) return '';
+
+  let summary: string;
+  switch (method) {
+    case 'initialize': {
+      const name = dig(result, 'serverInfo', 'name') ?? '?';
+      const ver = dig(result, 'serverInfo', 'version') ?? '';
+      const caps = dig(result, 'capabilities') as Record<string, unknown> | undefined;
+      const capList = caps ? Object.keys(caps).filter((k) => caps[k] && Object.keys(caps[k] as object).length > 0) : [];
+      summary = `server=${name}${ver ? ` v${ver}` : ''}${capList.length ? ` caps=[${capList.join(',')}]` : ''}`;
+      break;
+    }
+    case 'tools/list': {
+      const tools = (result.tools ?? []) as unknown[];
+      summary = `${tools.length} tools: ${nameList(tools, 'name', 6)}`;
+      break;
+    }
+    case 'resources/list': {
+      const resources = (result.resources ?? []) as unknown[];
+      summary = `${resources.length} resources: ${nameList(resources, 'name', 6)}`;
+      break;
+    }
+    case 'prompts/list': {
+      const prompts = (result.prompts ?? []) as unknown[];
+      if (prompts.length === 0) { summary = '0 prompts'; break; }
+      summary = `${prompts.length} prompts: ${nameList(prompts, 'name', 6)}`;
+      break;
+    }
+    case 'tools/call': {
+      const content = (result.content ?? []) as unknown[];
+      const isError = result.isError;
+      const first = content[0];
+      const text = (dig(first, 'text') as string) ?? '';
+      const prefix = isError ? 'ERROR: ' : '';
+      if (text) { summary = prefix + trunc(text.replace(/\n/g, ' '), 100); break; }
+      summary = prefix + `${content.length} content block(s)`;
+      break;
+    }
+    case 'resources/read': {
+      const contents = (result.contents ?? []) as unknown[];
+      const first = contents[0];
+      const text = (dig(first, 'text') as string) ?? '';
+      if (text) { summary = trunc(text.replace(/\n/g, ' '), 80); break; }
+      summary = `${contents.length} content block(s)`;
+      break;
+    }
+    case 'notifications/initialized':
+      summary = 'ok';
+      break;
+    default: {
+      if (Object.keys(result).length === 0) { summary = 'ok'; break; }
+      const s = JSON.stringify(result);
+      summary = trunc(s, 80);
+      break;
+    }
+  }
+
+  if (durationMs !== undefined) {
+    return `[${durationMs}ms] ${summary}`;
+  }
+  return summary;
+}
+
+/** Format full event body for expanded detail view (multi-line, readable) */
+export function formatBodyDetail(eventType: string, method: string, body: unknown): string[] {
+  const bodyObj = body as Record<string, unknown> | null;
+  if (!bodyObj) return ['(no body)'];
+
+  const lines: string[] = [];
+
+  if (eventType.includes('request') || eventType === 'client_notification') {
+    const params = bodyObj['params'] as Record<string, unknown> | undefined;
+    if (method === 'tools/call' && params) {
+      lines.push(`Tool: ${params['name'] as string}`);
+      const args = params['arguments'] as Record<string, unknown> | undefined;
+      if (args && Object.keys(args).length > 0) {
+        lines.push('Arguments:');
+        for (const [k, v] of Object.entries(args)) {
+          const vs = typeof v === 'string' ? v : JSON.stringify(v, null, 2);
+          for (const vl of vs.split('\n')) {
+            lines.push(`  ${k}: ${vl}`);
+          }
+        }
+      }
+    } else if (method === 'initialize' && params) {
+      const ci = params['clientInfo'] as Record<string, unknown> | undefined;
+      lines.push(`Client: ${ci?.['name'] ?? '?'} v${ci?.['version'] ?? '?'}`);
+      lines.push(`Protocol: ${params['protocolVersion'] ?? '?'}`);
+      const caps = params['capabilities'] as Record<string, unknown> | undefined;
+      if (caps) lines.push(`Capabilities: ${JSON.stringify(caps)}`);
+    } else if (params && Object.keys(params).length > 0) {
+      for (const l of JSON.stringify(params, null, 2).split('\n')) {
+        lines.push(l);
+      }
+    } else {
+      lines.push('(empty params)');
+    }
+  } else if (eventType.includes('response')) {
+    const error = bodyObj['error'] as Record<string, unknown> | undefined;
+    if (error) {
+      lines.push(`Error ${error['code']}: ${error['message']}`);
+      if (error['data']) {
+        for (const l of JSON.stringify(error['data'], null, 2).split('\n')) {
+          lines.push(`  ${l}`);
+        }
+      }
+    } else {
+      const result = bodyObj['result'] as Record<string, unknown> | undefined;
+      if (!result) {
+        lines.push('(empty result)');
+      } else if (method === 'tools/list') {
+        const tools = (result['tools'] ?? []) as Array<{ name: string; description?: string }>;
+        lines.push(`${tools.length} tools:`);
+        for (const t of tools) {
+          lines.push(`  ${t.name}${t.description ? ` \u2014 ${trunc(t.description, 60)}` : ''}`);
+        }
+      } else if (method === 'resources/list') {
+        const resources = (result['resources'] ?? []) as Array<{ name: string; uri?: string; description?: string }>;
+        lines.push(`${resources.length} resources:`);
+        for (const r of resources) {
+          lines.push(`  ${r.name}${r.uri ? ` (${r.uri})` : ''}${r.description ? ` \u2014 ${trunc(r.description, 50)}` : ''}`);
+        }
+      } else if (method === 'prompts/list') {
+        const prompts = (result['prompts'] ?? []) as Array<{ name: string; description?: string }>;
+        lines.push(`${prompts.length} prompts:`);
+        for (const p of prompts) {
+          lines.push(`  ${p.name}${p.description ? ` \u2014 ${trunc(p.description, 60)}` : ''}`);
+        }
+      } else if (method === 'tools/call') {
+        const isErr = result['isError'];
+        const content = (result['content'] ?? []) as Array<{ type?: string; text?: string }>;
+        if (isErr) lines.push('(error response)');
+        for (const c of content) {
+          if (c.text) {
+            for (const l of c.text.split('\n')) {
+              lines.push(l);
+            }
+          } else {
+            lines.push(`[${c.type ?? 'unknown'} content]`);
+          }
+        }
+      } else if (method === 'initialize') {
+        const si = result['serverInfo'] as Record<string, unknown> | undefined;
+        lines.push(`Server: ${si?.['name'] ?? '?'} v${si?.['version'] ?? '?'}`);
+        lines.push(`Protocol: ${result['protocolVersion'] ?? '?'}`);
+        const caps = result['capabilities'] as Record<string, unknown> | undefined;
+        if (caps) {
+          lines.push('Capabilities:');
+          for (const [k, v] of Object.entries(caps)) {
+            if (v && typeof v === 'object' && Object.keys(v).length > 0) {
+              lines.push(`  ${k}: ${JSON.stringify(v)}`);
+            }
+          }
+        }
+        const instructions = result['instructions'] as string | undefined;
+        if (instructions) {
+          lines.push('');
+          lines.push('Instructions:');
+          for (const l of instructions.split('\n')) {
+            lines.push(`  ${l}`);
+          }
+        }
+      } else {
+        for (const l of JSON.stringify(result, null, 2).split('\n')) {
+          lines.push(l);
+        }
+      }
+    }
+  } else {
+    // Lifecycle events
+    for (const l of JSON.stringify(bodyObj, null, 2).split('\n')) {
+      lines.push(l);
+    }
+  }
+
+  return lines;
+}
+
+export interface FormattedEvent {
+  arrow: string;
+  color: string;
+  label: string;
+  detail: string;
+  detailColor?: string | undefined;
+}
+
+export function formatEventSummary(
+  eventType: TrafficEventType,
+  method: string | undefined,
+  body: unknown,
+  upstreamName?: string,
+  durationMs?: number,
+): FormattedEvent {
+  const m = method ?? '';
+
+  switch (eventType) {
+    case 'client_request':
+      return { arrow: '\u2192', color: 'green', label: m, detail: summarizeRequest(m, body) };
+    case 'client_response': {
+      const detail = summarizeResponse(m, body, durationMs);
+      const hasError = detail.startsWith('ERROR');
+      return { arrow: '\u2190', color: 'blue', label: m, detail, detailColor: hasError ? 'red' : undefined };
+    }
+    case 'client_notification':
+      return { arrow: '\u25C2', color: 'magenta', label: m, detail: summarizeRequest(m, body) };
+    case 'upstream_request':
+      return { arrow: '  \u21E2', color: 'yellowBright', label: `${upstreamName ?? '?'}/${m}`, detail: summarizeRequest(m, body) };
+    case 'upstream_response': {
+      const detail = summarizeResponse(m, body, durationMs);
+      const hasError = detail.startsWith('ERROR');
+      return { arrow: '  \u21E0', color: 'yellowBright', label: `${upstreamName ?? '?'}/${m}`, detail, detailColor: hasError ? 'red' : undefined };
+    }
+    case 'session_created':
+      return { arrow: '\u25CF', color: 'cyan', label: 'session', detail: '' };
+    case 'session_closed':
+      return { arrow: '\u25CB', color: 'red', label: 'session', detail: 'closed' };
+    default:
+      return { arrow: '?', color: 'white', label: eventType, detail: '' };
+  }
+}

src/cli/src/commands/console/index.ts

@@ -8,11 +8,10 @@ export interface ConsoleCommandDeps {
 
 export function createConsoleCommand(deps: ConsoleCommandDeps): Command {
   const cmd = new Command('console')
-    .description('Interactive MCP console — see what an LLM sees when attached to a project')
+    .description('Interactive MCP console — unified timeline with tools, provenance, and lab replay')
     .argument('[project]', 'Project name to connect to')
-    .option('--inspect', 'Passive traffic inspector — observe other clients\' MCP traffic')
     .option('--stdin-mcp', 'Run inspector as MCP server over stdin/stdout (for Claude)')
-    .action(async (projectName: string | undefined, opts: { inspect?: boolean; stdinMcp?: boolean }) => {
+    .action(async (projectName: string | undefined, opts: { stdinMcp?: boolean }) => {
       let mcplocalUrl = 'http://localhost:3200';
       if (deps.configLoader) {
         mcplocalUrl = deps.configLoader().mcplocalUrl;
@@ -25,28 +24,13 @@ export function createConsoleCommand(deps: ConsoleCommandDeps): Command {
         }
       }
 
-      // --inspect --stdin-mcp: MCP server for Claude
-      if (opts.inspect && opts.stdinMcp) {
+      // --stdin-mcp: MCP server for Claude (unchanged)
+      if (opts.stdinMcp) {
         const { runInspectMcp } = await import('./inspect-mcp.js');
         await runInspectMcp(mcplocalUrl);
         return;
       }
 
-      // --inspect: TUI traffic inspector
-      if (opts.inspect) {
-        const { renderInspect } = await import('./inspect-app.js');
-        await renderInspect({ mcplocalUrl, projectFilter: projectName });
-        return;
-      }
-
-      // Regular interactive console — requires project name
-      if (!projectName) {
-        console.error('Error: project name is required for interactive console mode.');
-        console.error('Usage: mcpctl console <project>');
-        console.error('       mcpctl console --inspect [project]');
-        process.exit(1);
-      }
-
       let token: string | undefined;
       if (deps.credentialsLoader) {
         token = deps.credentialsLoader()?.token;
@@ -59,11 +43,55 @@ export function createConsoleCommand(deps: ConsoleCommandDeps): Command {
         }
       }
 
-      const endpointUrl = `${mcplocalUrl.replace(/\/$/, '')}/projects/${encodeURIComponent(projectName)}/mcp`;
+      // Build endpoint URL only if project specified
+      let endpointUrl: string | undefined;
+      if (projectName) {
+        endpointUrl = `${mcplocalUrl.replace(/\/$/, '')}/projects/${encodeURIComponent(projectName)}/mcp`;
 
-      // Dynamic import to avoid loading React/Ink for non-console commands
-      const { renderConsole } = await import('./app.js');
-      await renderConsole({ projectName, endpointUrl, token });
+        // Preflight check: verify the project exists before launching the TUI
+        const { postJsonRpc, sendDelete } = await import('../mcp.js');
+        try {
+          const initResult = await postJsonRpc(
+            endpointUrl,
+            JSON.stringify({
+              jsonrpc: '2.0',
+              id: 0,
+              method: 'initialize',
+              params: {
+                protocolVersion: '2024-11-05',
+                capabilities: {},
+                clientInfo: { name: 'mcpctl-preflight', version: '0.0.1' },
+              },
+            }),
+            undefined,
+            token,
+          );
+
+          if (initResult.status >= 400) {
+            try {
+              const body = JSON.parse(initResult.body) as { error?: string };
+              console.error(`Error: ${body.error ?? `HTTP ${initResult.status}`}`);
+            } catch {
+              console.error(`Error: HTTP ${initResult.status} — ${initResult.body}`);
+            }
+            process.exit(1);
+          }
+
+          // Clean up the preflight session
+          const sid = initResult.headers['mcp-session-id'];
+          if (typeof sid === 'string') {
+            await sendDelete(endpointUrl, sid, token);
+          }
+        } catch (err) {
+          console.error(`Error: cannot connect to mcplocal at ${mcplocalUrl}`);
+          console.error(err instanceof Error ? err.message : String(err));
+          process.exit(1);
+        }
+      }
+
+      // Launch unified console (observe-only if no project, interactive available if project given)
+      const { renderUnifiedConsole } = await import('./unified-app.js');
+      await renderUnifiedConsole({ projectName, endpointUrl, mcplocalUrl, token });
     });
 
   return cmd;

src/cli/src/commands/console/inspect-app.tsx

@@ -1,825 +0,0 @@
-/**
- * Inspector TUI — passive MCP traffic sniffer.
- *
- * Connects to mcplocal's /inspect SSE endpoint and displays
- * live traffic per project/session with color coding.
- *
- * Keys:
- *   s         toggle sidebar
- *   j/k       navigate events
- *   Enter     expand/collapse event detail
- *   Esc       close detail / deselect
- *   ↑/↓       select session (when sidebar visible)
- *   a         all sessions
- *   c         clear traffic
- *   q         quit
- */
-
-import { useState, useEffect, useRef } from 'react';
-import { render, Box, Text, useInput, useApp, useStdout } from 'ink';
-import type { IncomingMessage } from 'node:http';
-import { request as httpRequest } from 'node:http';
-
-// ── Types matching mcplocal's TrafficEvent ──
-
-interface TrafficEvent {
-  timestamp: string;
-  projectName: string;
-  sessionId: string;
-  eventType: string;
-  method?: string;
-  upstreamName?: string;
-  body: unknown;
-  durationMs?: number;
-}
-
-interface ActiveSession {
-  sessionId: string;
-  projectName: string;
-  startedAt: string;
-}
-
-// ── SSE Client ──
-
-function connectSSE(
-  url: string,
-  opts: {
-    onSessions: (sessions: ActiveSession[]) => void;
-    onEvent: (event: TrafficEvent) => void;
-    onLive: () => void;
-    onError: (err: string) => void;
-  },
-): () => void {
-  let aborted = false;
-  const parsed = new URL(url);
-
-  const req = httpRequest(
-    {
-      hostname: parsed.hostname,
-      port: parsed.port,
-      path: parsed.pathname + parsed.search,
-      headers: { Accept: 'text/event-stream' },
-    },
-    (res: IncomingMessage) => {
-      let buffer = '';
-      let currentEventType = 'message';
-
-      res.setEncoding('utf-8');
-      res.on('data', (chunk: string) => {
-        buffer += chunk;
-        const lines = buffer.split('\n');
-        buffer = lines.pop()!; // Keep incomplete line
-
-        for (const line of lines) {
-          if (line.startsWith('event: ')) {
-            currentEventType = line.slice(7).trim();
-          } else if (line.startsWith('data: ')) {
-            const data = line.slice(6);
-            try {
-              const parsed = JSON.parse(data);
-              if (currentEventType === 'sessions') {
-                opts.onSessions(parsed as ActiveSession[]);
-              } else if (currentEventType === 'live') {
-                opts.onLive();
-              } else {
-                opts.onEvent(parsed as TrafficEvent);
-              }
-            } catch {
-              // Ignore unparseable data
-            }
-            currentEventType = 'message';
-          }
-          // Ignore comments (: keepalive) and blank lines
-        }
-      });
-
-      res.on('end', () => {
-        if (!aborted) opts.onError('SSE connection closed');
-      });
-
-      res.on('error', (err) => {
-        if (!aborted) opts.onError(err.message);
-      });
-    },
-  );
-
-  req.on('error', (err) => {
-    if (!aborted) opts.onError(err.message);
-  });
-
-  req.end();
-
-  return () => {
-    aborted = true;
-    req.destroy();
-  };
-}
-
-// ── Formatting helpers ──
-
-/** Safely dig into unknown objects */
-function dig(obj: unknown, ...keys: string[]): unknown {
-  let cur = obj;
-  for (const k of keys) {
-    if (cur === null || cur === undefined || typeof cur !== 'object') return undefined;
-    cur = (cur as Record<string, unknown>)[k];
-  }
-  return cur;
-}
-
-function trunc(s: string, maxLen: number): string {
-  return s.length > maxLen ? s.slice(0, maxLen - 1) + '…' : s;
-}
-
-function nameList(items: unknown[], key: string, max: number): string {
-  if (items.length === 0) return '(none)';
-  const names = items.map((it) => dig(it, key) as string).filter(Boolean);
-  const shown = names.slice(0, max);
-  const rest = names.length - shown.length;
-  return shown.join(', ') + (rest > 0 ? ` +${rest} more` : '');
-}
-
-/** Extract meaningful summary from request params (strips jsonrpc/id boilerplate) */
-function summarizeRequest(method: string, body: unknown): string {
-  const params = dig(body, 'params') as Record<string, unknown> | undefined;
-
-  switch (method) {
-    case 'initialize': {
-      const name = dig(params, 'clientInfo', 'name') ?? '?';
-      const ver = dig(params, 'clientInfo', 'version') ?? '';
-      const proto = dig(params, 'protocolVersion') ?? '';
-      return `client=${name}${ver ? ` v${ver}` : ''} proto=${proto}`;
-    }
-    case 'tools/call': {
-      const toolName = dig(params, 'name') as string ?? '?';
-      const args = dig(params, 'arguments') as Record<string, unknown> | undefined;
-      if (!args || Object.keys(args).length === 0) return `${toolName}()`;
-      const pairs = Object.entries(args).map(([k, v]) => {
-        const vs = typeof v === 'string' ? v : JSON.stringify(v);
-        return `${k}: ${trunc(vs, 40)}`;
-      });
-      return `${toolName}(${trunc(pairs.join(', '), 80)})`;
-    }
-    case 'resources/read': {
-      const uri = dig(params, 'uri') as string ?? '';
-      return uri;
-    }
-    case 'prompts/get': {
-      const name = dig(params, 'name') as string ?? '';
-      return name;
-    }
-    case 'tools/list':
-    case 'resources/list':
-    case 'prompts/list':
-    case 'notifications/initialized':
-      return '';
-    default: {
-      if (!params || Object.keys(params).length === 0) return '';
-      const s = JSON.stringify(params);
-      return trunc(s, 80);
-    }
-  }
-}
-
-/** Extract meaningful summary from response result */
-function summarizeResponse(method: string, body: unknown): string {
-  const error = dig(body, 'error') as { message?: string; code?: number } | undefined;
-  if (error) {
-    return `ERROR ${error.code ?? ''}: ${error.message ?? 'unknown'}`;
-  }
-
-  const result = dig(body, 'result') as Record<string, unknown> | undefined;
-  if (!result) return '';
-
-  switch (method) {
-    case 'initialize': {
-      const name = dig(result, 'serverInfo', 'name') ?? '?';
-      const ver = dig(result, 'serverInfo', 'version') ?? '';
-      const caps = dig(result, 'capabilities') as Record<string, unknown> | undefined;
-      const capList = caps ? Object.keys(caps).filter((k) => caps[k] && Object.keys(caps[k] as object).length > 0) : [];
-      return `server=${name}${ver ? ` v${ver}` : ''}${capList.length ? ` caps=[${capList.join(',')}]` : ''}`;
-    }
-    case 'tools/list': {
-      const tools = (result.tools ?? []) as unknown[];
-      return `${tools.length} tools: ${nameList(tools, 'name', 6)}`;
-    }
-    case 'resources/list': {
-      const resources = (result.resources ?? []) as unknown[];
-      return `${resources.length} resources: ${nameList(resources, 'name', 6)}`;
-    }
-    case 'prompts/list': {
-      const prompts = (result.prompts ?? []) as unknown[];
-      if (prompts.length === 0) return '0 prompts';
-      return `${prompts.length} prompts: ${nameList(prompts, 'name', 6)}`;
-    }
-    case 'tools/call': {
-      const content = (result.content ?? []) as unknown[];
-      const isError = result.isError;
-      const first = content[0];
-      const text = (dig(first, 'text') as string) ?? '';
-      const prefix = isError ? 'ERROR: ' : '';
-      if (text) return prefix + trunc(text.replace(/\n/g, ' '), 100);
-      return prefix + `${content.length} content block(s)`;
-    }
-    case 'resources/read': {
-      const contents = (result.contents ?? []) as unknown[];
-      const first = contents[0];
-      const text = (dig(first, 'text') as string) ?? '';
-      if (text) return trunc(text.replace(/\n/g, ' '), 80);
-      return `${contents.length} content block(s)`;
-    }
-    case 'notifications/initialized':
-      return 'ok';
-    default: {
-      if (Object.keys(result).length === 0) return 'ok';
-      const s = JSON.stringify(result);
-      return trunc(s, 80);
-    }
-  }
-}
-
-/** Format full event body for expanded detail view (multi-line, readable) */
-function formatBodyDetail(event: TrafficEvent): string[] {
-  const body = event.body as Record<string, unknown> | null;
-  if (!body) return ['(no body)'];
-
-  const lines: string[] = [];
-  const method = event.method ?? '';
-
-  // Strip jsonrpc envelope — show meaningful content only
-  if (event.eventType.includes('request') || event.eventType === 'client_notification') {
-    const params = body['params'] as Record<string, unknown> | undefined;
-    if (method === 'tools/call' && params) {
-      lines.push(`Tool: ${params['name'] as string}`);
-      const args = params['arguments'] as Record<string, unknown> | undefined;
-      if (args && Object.keys(args).length > 0) {
-        lines.push('Arguments:');
-        for (const [k, v] of Object.entries(args)) {
-          const vs = typeof v === 'string' ? v : JSON.stringify(v, null, 2);
-          for (const vl of vs.split('\n')) {
-            lines.push(`  ${k}: ${vl}`);
-          }
-        }
-      }
-    } else if (method === 'initialize' && params) {
-      const ci = params['clientInfo'] as Record<string, unknown> | undefined;
-      lines.push(`Client: ${ci?.['name'] ?? '?'} v${ci?.['version'] ?? '?'}`);
-      lines.push(`Protocol: ${params['protocolVersion'] ?? '?'}`);
-      const caps = params['capabilities'] as Record<string, unknown> | undefined;
-      if (caps) lines.push(`Capabilities: ${JSON.stringify(caps)}`);
-    } else if (params && Object.keys(params).length > 0) {
-      for (const l of JSON.stringify(params, null, 2).split('\n')) {
-        lines.push(l);
-      }
-    } else {
-      lines.push('(empty params)');
-    }
-  } else if (event.eventType.includes('response')) {
-    const error = body['error'] as Record<string, unknown> | undefined;
-    if (error) {
-      lines.push(`Error ${error['code']}: ${error['message']}`);
-      if (error['data']) {
-        for (const l of JSON.stringify(error['data'], null, 2).split('\n')) {
-          lines.push(`  ${l}`);
-        }
-      }
-    } else {
-      const result = body['result'] as Record<string, unknown> | undefined;
-      if (!result) {
-        lines.push('(empty result)');
-      } else if (method === 'tools/list') {
-        const tools = (result['tools'] ?? []) as Array<{ name: string; description?: string }>;
-        lines.push(`${tools.length} tools:`);
-        for (const t of tools) {
-          lines.push(`  ${t.name}${t.description ? ` — ${trunc(t.description, 60)}` : ''}`);
-        }
-      } else if (method === 'resources/list') {
-        const resources = (result['resources'] ?? []) as Array<{ name: string; uri?: string; description?: string }>;
-        lines.push(`${resources.length} resources:`);
-        for (const r of resources) {
-          lines.push(`  ${r.name}${r.uri ? ` (${r.uri})` : ''}${r.description ? ` — ${trunc(r.description, 50)}` : ''}`);
-        }
-      } else if (method === 'prompts/list') {
-        const prompts = (result['prompts'] ?? []) as Array<{ name: string; description?: string }>;
-        lines.push(`${prompts.length} prompts:`);
-        for (const p of prompts) {
-          lines.push(`  ${p.name}${p.description ? ` — ${trunc(p.description, 60)}` : ''}`);
-        }
-      } else if (method === 'tools/call') {
-        const isErr = result['isError'];
-        const content = (result['content'] ?? []) as Array<{ type?: string; text?: string }>;
-        if (isErr) lines.push('(error response)');
-        for (const c of content) {
-          if (c.text) {
-            for (const l of c.text.split('\n')) {
-              lines.push(l);
-            }
-          } else {
-            lines.push(`[${c.type ?? 'unknown'} content]`);
-          }
-        }
-      } else if (method === 'initialize') {
-        const si = result['serverInfo'] as Record<string, unknown> | undefined;
-        lines.push(`Server: ${si?.['name'] ?? '?'} v${si?.['version'] ?? '?'}`);
-        lines.push(`Protocol: ${result['protocolVersion'] ?? '?'}`);
-        const caps = result['capabilities'] as Record<string, unknown> | undefined;
-        if (caps) {
-          lines.push('Capabilities:');
-          for (const [k, v] of Object.entries(caps)) {
-            if (v && typeof v === 'object' && Object.keys(v).length > 0) {
-              lines.push(`  ${k}: ${JSON.stringify(v)}`);
-            }
-          }
-        }
-        const instructions = result['instructions'] as string | undefined;
-        if (instructions) {
-          lines.push('');
-          lines.push('Instructions:');
-          for (const l of instructions.split('\n')) {
-            lines.push(`  ${l}`);
-          }
-        }
-      } else {
-        for (const l of JSON.stringify(result, null, 2).split('\n')) {
-          lines.push(l);
-        }
-      }
-    }
-  } else {
-    // Lifecycle events
-    for (const l of JSON.stringify(body, null, 2).split('\n')) {
-      lines.push(l);
-    }
-  }
-
-  return lines;
-}
-
-interface FormattedEvent {
-  arrow: string;
-  color: string;
-  label: string;
-  detail: string;
-  detailColor?: string | undefined;
-}
-
-function formatEvent(event: TrafficEvent): FormattedEvent {
-  const method = event.method ?? '';
-
-  switch (event.eventType) {
-    case 'client_request':
-      return { arrow: '→', color: 'green', label: method, detail: summarizeRequest(method, event.body) };
-    case 'client_response': {
-      const detail = summarizeResponse(method, event.body);
-      const hasError = detail.startsWith('ERROR');
-      return { arrow: '←', color: 'blue', label: method, detail, detailColor: hasError ? 'red' : undefined };
-    }
-    case 'client_notification':
-      return { arrow: '◂', color: 'magenta', label: method, detail: summarizeRequest(method, event.body) };
-    case 'upstream_request':
-      return { arrow: '  ⇢', color: 'yellowBright', label: `${event.upstreamName ?? '?'}/${method}`, detail: summarizeRequest(method, event.body) };
-    case 'upstream_response': {
-      const ms = event.durationMs !== undefined ? `${event.durationMs}ms` : '';
-      const detail = summarizeResponse(method, event.body);
-      const hasError = detail.startsWith('ERROR');
-      return { arrow: '  ⇠', color: 'yellowBright', label: `${event.upstreamName ?? '?'}/${method}`, detail: ms ? `[${ms}] ${detail}` : detail, detailColor: hasError ? 'red' : undefined };
-    }
-    case 'session_created':
-      return { arrow: '●', color: 'cyan', label: `session ${event.sessionId.slice(0, 8)}`, detail: `project=${event.projectName}` };
-    case 'session_closed':
-      return { arrow: '○', color: 'red', label: `session ${event.sessionId.slice(0, 8)}`, detail: 'closed' };
-    default:
-      return { arrow: '?', color: 'white', label: event.eventType, detail: '' };
-  }
-}
-
-function formatTime(iso: string): string {
-  try {
-    const d = new Date(iso);
-    return d.toLocaleTimeString('en-GB', { hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit' });
-  } catch {
-    return '??:??:??';
-  }
-}
-
-// ── Session Sidebar ──
-
-function SessionList({ sessions, selected, eventCounts }: {
-  sessions: ActiveSession[];
-  selected: number;
-  eventCounts: Map<string, number>;
-}) {
-  return (
-    <Box flexDirection="column" width={32} borderStyle="round" borderColor="gray" paddingX={1}>
-      <Text bold color="cyan">
-        {' '}Sessions{' '}
-        <Text dimColor>({sessions.length})</Text>
-      </Text>
-      <Box marginTop={0}>
-        <Text color={selected === -1 ? 'cyan' : undefined} bold={selected === -1}>
-          {selected === -1 ? ' ▸ ' : '   '}
-          <Text>all sessions</Text>
-        </Text>
-      </Box>
-      {sessions.length === 0 && (
-        <Box marginTop={1}>
-          <Text dimColor>   waiting for connections…</Text>
-        </Box>
-      )}
-      {sessions.map((s, i) => {
-        const count = eventCounts.get(s.sessionId) ?? 0;
-        return (
-          <Box key={s.sessionId} flexDirection="column">
-            <Text wrap="truncate">
-              <Text color={i === selected ? 'cyan' : undefined} bold={i === selected}>
-                {i === selected ? ' ▸ ' : '   '}
-                {s.projectName}
-              </Text>
-            </Text>
-            <Text wrap="truncate" dimColor>
-              {'     '}
-              {s.sessionId.slice(0, 8)}
-              {count > 0 ? ` · ${count} events` : ''}
-            </Text>
-          </Box>
-        );
-      })}
-      <Box flexGrow={1} />
-      <Box borderStyle="single" borderTop borderColor="gray" paddingTop={0}>
-        <Text dimColor>
-          {'[↑↓] session [a] all\n[s] sidebar  [c] clear\n[j/k] event  [⏎] expand\n[q] quit'}
-        </Text>
-      </Box>
-    </Box>
-  );
-}
-
-// ── Traffic Log ──
-
-function TrafficLog({ events, height, showProject, focusedIdx }: {
-  events: TrafficEvent[];
-  height: number;
-  showProject: boolean;
-  focusedIdx: number; // -1 = no focus (auto-scroll to bottom)
-}) {
-  // When focusedIdx >= 0, center the focused event in the view
-  // When focusedIdx === -1, show the latest events (auto-scroll)
-  const maxVisible = height - 2;
-  let startIdx: number;
-  if (focusedIdx >= 0) {
-    // Center focused event, but clamp to valid range
-    startIdx = Math.max(0, Math.min(focusedIdx - Math.floor(maxVisible / 2), events.length - maxVisible));
-  } else {
-    startIdx = Math.max(0, events.length - maxVisible);
-  }
-  const visible = events.slice(startIdx, startIdx + maxVisible);
-  const visibleBaseIdx = startIdx;
-
-  return (
-    <Box flexDirection="column" flexGrow={1} paddingLeft={1}>
-      <Text bold>
-        Traffic <Text dimColor>({events.length} events{focusedIdx >= 0 ? ` · #${focusedIdx + 1} selected` : ''})</Text>
-      </Text>
-      {visible.length === 0 && (
-        <Box marginTop={1}>
-          <Text dimColor>  waiting for traffic…</Text>
-        </Box>
-      )}
-      {visible.map((event, vi) => {
-        const absIdx = visibleBaseIdx + vi;
-        const isFocused = absIdx === focusedIdx;
-        const { arrow, color, label, detail, detailColor } = formatEvent(event);
-        const isUpstream = event.eventType.startsWith('upstream_');
-        const isLifecycle = event.eventType === 'session_created' || event.eventType === 'session_closed';
-        const marker = isFocused ? '▸' : ' ';
-
-        if (isLifecycle) {
-          return (
-            <Text key={vi} wrap="truncate">
-              <Text color={isFocused ? 'cyan' : undefined}>{marker}</Text>
-              <Text dimColor>{formatTime(event.timestamp)}  </Text>
-              <Text color={color} bold>{arrow} {label}</Text>
-              <Text dimColor> {detail}</Text>
-            </Text>
-          );
-        }
-
-        return (
-          <Text key={vi} wrap="truncate">
-            <Text color={isFocused ? 'cyan' : undefined}>{marker}</Text>
-            <Text dimColor>{formatTime(event.timestamp)}  </Text>
-            {showProject && <Text color="gray">[{trunc(event.projectName, 12)}] </Text>}
-            <Text color={color}>{arrow} </Text>
-            <Text bold={!isUpstream} color={color}>{label}</Text>
-            {detail ? (
-              <Text color={detailColor} dimColor={!detailColor}> {detail}</Text>
-            ) : null}
-          </Text>
-        );
-      })}
-    </Box>
-  );
-}
-
-// ── Detail Pane ──
-
-function DetailPane({ event, maxLines, scrollOffset }: {
-  event: TrafficEvent;
-  maxLines: number;
-  scrollOffset: number;
-}) {
-  const { arrow, color, label } = formatEvent(event);
-  const allLines = formatBodyDetail(event);
-  const bodyHeight = maxLines - 3; // header + border
-  const visibleLines = allLines.slice(scrollOffset, scrollOffset + bodyHeight);
-  const totalLines = allLines.length;
-  const canScroll = totalLines > bodyHeight;
-  const atEnd = scrollOffset + bodyHeight >= totalLines;
-
-  return (
-    <Box flexDirection="column" borderStyle="round" borderColor="gray" paddingX={1} height={maxLines}>
-      <Text bold>
-        <Text color={color}>{arrow} {label}</Text>
-        <Text dimColor>  {formatTime(event.timestamp)}  {event.projectName}/{event.sessionId.slice(0, 8)}</Text>
-        {canScroll ? (
-          <Text dimColor>  [{scrollOffset + 1}-{Math.min(scrollOffset + bodyHeight, totalLines)}/{totalLines}] ↑↓ scroll  Esc close</Text>
-        ) : (
-          <Text dimColor>  Esc to close</Text>
-        )}
-      </Text>
-      {visibleLines.map((line, i) => (
-        <Text key={i} wrap="truncate" dimColor={line.startsWith('  ')}>
-          {line}
-        </Text>
-      ))}
-      {canScroll && !atEnd && (
-        <Text dimColor>… +{totalLines - scrollOffset - bodyHeight} more lines ↓</Text>
-      )}
-    </Box>
-  );
-}
-
-// ── Root App ──
-
-interface InspectAppProps {
-  inspectUrl: string;
-  projectFilter?: string;
-}
-
-function InspectApp({ inspectUrl, projectFilter }: InspectAppProps) {
-  const { exit } = useApp();
-  const { stdout } = useStdout();
-  const termHeight = stdout?.rows ?? 24;
-
-  const [sessions, setSessions] = useState<ActiveSession[]>([]);
-  const [events, setEvents] = useState<TrafficEvent[]>([]);
-  const [selectedSession, setSelectedSession] = useState(-1); // -1 = all
-  const [connected, setConnected] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [showSidebar, setShowSidebar] = useState(true);
-  const [focusedEvent, setFocusedEvent] = useState(-1); // -1 = auto-scroll
-  const [expandedEvent, setExpandedEvent] = useState(false);
-  const [detailScroll, setDetailScroll] = useState(0);
-
-  // Track latest event count for auto-follow
-  const prevCountRef = useRef(0);
-
-  useEffect(() => {
-    const url = new URL(inspectUrl);
-    if (projectFilter) url.searchParams.set('project', projectFilter);
-
-    const disconnect = connectSSE(url.toString(), {
-      onSessions: (s) => setSessions(s),
-      onEvent: (e) => {
-        setEvents((prev) => [...prev, e]);
-        // Auto-add new sessions we haven't seen
-        if (e.eventType === 'session_created') {
-          setSessions((prev) => {
-            if (prev.some((s) => s.sessionId === e.sessionId)) return prev;
-            return [...prev, { sessionId: e.sessionId, projectName: e.projectName, startedAt: e.timestamp }];
-          });
-        }
-        if (e.eventType === 'session_closed') {
-          setSessions((prev) => prev.filter((s) => s.sessionId !== e.sessionId));
-        }
-      },
-      onLive: () => setConnected(true),
-      onError: (msg) => setError(msg),
-    });
-
-    return disconnect;
-  }, [inspectUrl, projectFilter]);
-
-  // Filter events by selected session
-  const filteredEvents = selectedSession === -1
-    ? events
-    : events.filter((e) => e.sessionId === sessions[selectedSession]?.sessionId);
-
-  // Auto-follow: when new events arrive and we're not browsing, stay at bottom
-  useEffect(() => {
-    if (focusedEvent === -1 && filteredEvents.length > prevCountRef.current) {
-      // Auto-scrolling (focusedEvent === -1 means "follow tail")
-    }
-    prevCountRef.current = filteredEvents.length;
-  }, [filteredEvents.length, focusedEvent]);
-
-  // Event counts per session
-  const eventCounts = new Map<string, number>();
-  for (const e of events) {
-    eventCounts.set(e.sessionId, (eventCounts.get(e.sessionId) ?? 0) + 1);
-  }
-
-  const showProject = selectedSession === -1 && sessions.length > 1;
-
-  // Keyboard
-  useInput((input, key) => {
-    if (input === 'q') {
-      exit();
-      return;
-    }
-
-    // When detail pane is expanded, arrows scroll the detail content
-    if (expandedEvent && focusedEvent >= 0) {
-      if (key.escape) {
-        setExpandedEvent(false);
-        setDetailScroll(0);
-        return;
-      }
-      if (key.downArrow || input === 'j') {
-        setDetailScroll((s) => s + 1);
-        return;
-      }
-      if (key.upArrow || input === 'k') {
-        setDetailScroll((s) => Math.max(0, s - 1));
-        return;
-      }
-      // Enter: close detail
-      if (key.return) {
-        setExpandedEvent(false);
-        setDetailScroll(0);
-        return;
-      }
-      // q still quits even in detail mode
-      return;
-    }
-
-    // Esc: deselect event
-    if (key.escape) {
-      if (focusedEvent >= 0) {
-        setFocusedEvent(-1);
-      }
-      return;
-    }
-
-    // Enter: open detail pane for focused event
-    if (key.return && focusedEvent >= 0 && focusedEvent < filteredEvents.length) {
-      setExpandedEvent(true);
-      setDetailScroll(0);
-      return;
-    }
-
-    // s: toggle sidebar
-    if (input === 's') {
-      setShowSidebar((prev) => !prev);
-      return;
-    }
-
-    // a: all sessions
-    if (input === 'a') {
-      setSelectedSession(-1);
-      setFocusedEvent(-1);
-      setExpandedEvent(false);
-      setDetailScroll(0);
-      return;
-    }
-
-    // c: clear
-    if (input === 'c') {
-      setEvents([]);
-      setFocusedEvent(-1);
-      setExpandedEvent(false);
-      setDetailScroll(0);
-      return;
-    }
-
-    // j/k or arrow keys: navigate events
-    if (input === 'j' || key.downArrow) {
-      if (key.downArrow && showSidebar && focusedEvent < 0) {
-        // Arrow keys control session selection when sidebar visible and no event focused
-        setSelectedSession((s) => Math.min(sessions.length - 1, s + 1));
-      } else {
-        // j always controls event navigation, down-arrow too when event is focused
-        setFocusedEvent((prev) => {
-          const next = prev + 1;
-          return next >= filteredEvents.length ? filteredEvents.length - 1 : next;
-        });
-        setExpandedEvent(false);
-      }
-      return;
-    }
-    if (input === 'k' || key.upArrow) {
-      if (key.upArrow && showSidebar && focusedEvent < 0) {
-        setSelectedSession((s) => Math.max(-1, s - 1));
-      } else {
-        setFocusedEvent((prev) => {
-          if (prev <= 0) return -1; // Back to auto-scroll
-          return prev - 1;
-        });
-        setExpandedEvent(false);
-      }
-      return;
-    }
-
-    // G: jump to latest (end)
-    if (input === 'G') {
-      setFocusedEvent(-1);
-      setExpandedEvent(false);
-      setDetailScroll(0);
-      return;
-    }
-  });
-
-  // Layout calculations
-  const headerHeight = 1;
-  const footerHeight = 1;
-  // Detail pane takes up to half the screen
-  const detailHeight = expandedEvent && focusedEvent >= 0 ? Math.max(6, Math.floor(termHeight * 0.45)) : 0;
-  const contentHeight = termHeight - headerHeight - footerHeight - detailHeight;
-
-  const focusedEventObj = focusedEvent >= 0 ? filteredEvents[focusedEvent] : undefined;
-
-  return (
-    <Box flexDirection="column" height={termHeight}>
-      {/* ── Header ── */}
-      <Box paddingX={1}>
-        <Text bold color="cyan">MCP Inspector</Text>
-        <Text dimColor>  </Text>
-        <Text color={connected ? 'green' : 'yellow'}>{connected ? '● live' : '○ connecting…'}</Text>
-        {projectFilter && <Text dimColor>  project: {projectFilter}</Text>}
-        {selectedSession >= 0 && sessions[selectedSession] && (
-          <Text dimColor>  session: {sessions[selectedSession]!.sessionId.slice(0, 8)}</Text>
-        )}
-        {!showSidebar && <Text dimColor>  [s] show sidebar</Text>}
-      </Box>
-
-      {error && (
-        <Box paddingX={1}>
-          <Text color="red">  {error}</Text>
-        </Box>
-      )}
-
-      {/* ── Main content ── */}
-      <Box flexDirection="row" height={contentHeight}>
-        {showSidebar && (
-          <SessionList
-            sessions={sessions}
-            selected={selectedSession}
-            eventCounts={eventCounts}
-          />
-        )}
-        <TrafficLog
-          events={filteredEvents}
-          height={contentHeight}
-          showProject={showProject}
-          focusedIdx={focusedEvent}
-        />
-      </Box>
-
-      {/* ── Detail pane ── */}
-      {expandedEvent && focusedEventObj && (
-        <DetailPane event={focusedEventObj} maxLines={detailHeight} scrollOffset={detailScroll} />
-      )}
-
-      {/* ── Footer legend ── */}
-      <Box paddingX={1}>
-        <Text dimColor>
-          <Text color="green">→ req</Text>
-          {'  '}
-          <Text color="blue">← resp</Text>
-          {'  '}
-          <Text color="yellowBright">⇢⇠ upstream</Text>
-          {'  '}
-          <Text color="magenta">◂ notify</Text>
-          {'  │  '}
-          {!showSidebar && <Text>[s] sidebar  </Text>}
-          <Text>[j/k] navigate  [⏎] expand  [G] latest  [q] quit</Text>
-        </Text>
-      </Box>
-    </Box>
-  );
-}
-
-// ── Render entrypoint ──
-
-export interface InspectRenderOptions {
-  mcplocalUrl: string;
-  projectFilter?: string;
-}
-
-export async function renderInspect(opts: InspectRenderOptions): Promise<void> {
-  const inspectUrl = `${opts.mcplocalUrl.replace(/\/$/, '')}/inspect`;
-  const instance = render(
-    <InspectApp inspectUrl={inspectUrl} projectFilter={opts.projectFilter} />,
-  );
-  await instance.waitUntilExit();
-}

src/cli/src/commands/console/inspect-mcp.ts

@@ -2,7 +2,7 @@
  * MCP server over stdin/stdout for the traffic inspector.
  *
  * Claude adds this to .mcp.json as:
- *   { "mcpctl-inspect": { "command": "mcpctl", "args": ["console", "--inspect", "--stdin-mcp"] } }
+ *   { "mcpctl-inspect": { "command": "mcpctl", "args": ["console", "--stdin-mcp"] } }
  *
  * Subscribes to mcplocal's /inspect SSE endpoint and exposes traffic
  * data via MCP tools: list_sessions, get_traffic, get_session_info.

src/cli/src/commands/console/unified-types.ts

@@ -0,0 +1,153 @@
+/**
+ * Shared types for the unified MCP console.
+ */
+
+import type { McpTool, McpResource, McpPrompt, InitializeResult, McpSession } from './mcp-session.js';
+
+// ── Traffic event types (mirrors mcplocal's TrafficEvent) ──
+
+export type TrafficEventType =
+  | 'client_request'
+  | 'client_response'
+  | 'client_notification'
+  | 'upstream_request'
+  | 'upstream_response'
+  | 'session_created'
+  | 'session_closed';
+
+export interface ActiveSession {
+  sessionId: string;
+  projectName: string;
+  startedAt: string;
+}
+
+// ── Timeline ──
+
+export type EventLane = 'interactive' | 'observed';
+
+export interface TimelineEvent {
+  id: number;
+  timestamp: Date;
+  lane: EventLane;
+  eventType: TrafficEventType;
+  method?: string | undefined;
+  projectName: string;
+  sessionId: string;
+  upstreamName?: string | undefined;
+  body: unknown;
+  durationMs?: number | undefined;
+  correlationId?: string | undefined;
+}
+
+// ── Lane filter ──
+
+export type LaneFilter = 'all' | 'interactive' | 'observed';
+
+// ── Action area ──
+
+export interface ReplayConfig {
+  proxyModel: string;
+  provider: string | null;
+  llmModel: string | null;
+}
+
+export interface ReplayResult {
+  content: string;
+  durationMs: number;
+  error?: string | undefined;
+}
+
+export interface ProxyModelDetails {
+  name: string;
+  source: 'built-in' | 'local';
+  controller: string;
+  controllerConfig?: Record<string, unknown> | undefined;
+  stages: Array<{ type: string; config?: Record<string, unknown> }>;
+  appliesTo: string[];
+  cacheable: boolean;
+}
+
+export interface SearchState {
+  searchMode: boolean;
+  searchQuery: string;
+  searchMatches: number[];   // line indices matching query
+  searchMatchIdx: number;    // current match index, -1 = none
+}
+
+export type ActionState =
+  | { type: 'none' }
+  | { type: 'detail'; eventIdx: number; scrollOffset: number; horizontalOffset: number } & SearchState
+  | {
+      type: 'provenance';
+      clientEventIdx: number;
+      upstreamEvent: TimelineEvent | null;
+      scrollOffset: number;
+      horizontalOffset: number;
+      focusedPanel: 'client' | 'upstream' | 'parameters' | 'preview';
+      replayConfig: ReplayConfig;
+      replayResult: ReplayResult | null;
+      replayRunning: boolean;
+      editingUpstream: boolean;
+      editedContent: string;
+      parameterIdx: number; // 0=ProxyModel, 1=Provider, 2=Model, 3=Live, 4=Server
+      proxyModelDetails: ProxyModelDetails | null;
+      liveOverride: boolean;
+      serverList: string[];
+      serverOverrides: Record<string, string>;
+      selectedServerIdx: number; // -1 = project-wide, 0+ = specific server
+      serverPickerOpen: boolean;
+      modelPickerOpen: boolean;
+      modelPickerIdx: number;
+    } & SearchState
+  | { type: 'tool-input'; tool: McpTool; loading: boolean }
+  | { type: 'tool-browser' }
+  | { type: 'resource-browser' }
+  | { type: 'prompt-browser' }
+  | { type: 'raw-jsonrpc' };
+
+// ── Console state ──
+
+export interface UnifiedConsoleState {
+  // Connection
+  phase: 'connecting' | 'ready' | 'error';
+  error: string | null;
+
+  // Interactive session
+  session: McpSession | null;
+  gated: boolean;
+  initResult: InitializeResult | null;
+  tools: McpTool[];
+  resources: McpResource[];
+  prompts: McpPrompt[];
+
+  // Observed traffic (SSE)
+  sseConnected: boolean;
+  observedSessions: ActiveSession[];
+
+  // Session sidebar
+  showSidebar: boolean;
+  selectedSessionIdx: number; // -2 = "New Session", -1 = all sessions, 0+ = sessions
+  sidebarMode: 'sessions' | 'project-picker';
+  availableProjects: string[];
+  activeProjectName: string | null;
+
+  // Toolbar
+  toolbarFocusIdx: number; // -1 = not focused, 0-3 = which item
+
+  // Timeline
+  events: TimelineEvent[];
+  focusedEventIdx: number; // -1 = auto-scroll
+  nextEventId: number;
+  laneFilter: LaneFilter;
+
+  // Action area
+  action: ActionState;
+
+  // ProxyModel / LLM options (for provenance preview)
+  availableModels: string[];
+  availableProviders: string[];
+  availableLlms: string[];
+
+}
+
+export const MAX_TIMELINE_EVENTS = 10_000;

src/cli/src/commands/create.ts

@@ -63,7 +63,8 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
     .description('Create an MCP server definition')
     .argument('<name>', 'Server name (lowercase, hyphens allowed)')
     .option('-d, --description <text>', 'Server description')
-    .option('--package-name <name>', 'NPM package name')
+    .option('--package-name <name>', 'Package name (npm, PyPI, Go module, etc.)')
+    .option('--runtime <type>', 'Package runtime (node, python, go — default: node)')
     .option('--docker-image <image>', 'Docker image')
     .option('--transport <type>', 'Transport type (STDIO, SSE, STREAMABLE_HTTP)')
     .option('--repository-url <url>', 'Source repository URL')
@@ -148,6 +149,7 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
       if (opts.transport) body.transport = opts.transport;
       if (opts.replicas) body.replicas = parseInt(opts.replicas, 10);
       if (opts.packageName) body.packageName = opts.packageName;
+      if (opts.runtime) body.runtime = opts.runtime;
       if (opts.dockerImage) body.dockerImage = opts.dockerImage;
       if (opts.repositoryUrl) body.repositoryUrl = opts.repositoryUrl;
       if (opts.externalUrl) body.externalUrl = opts.externalUrl;
@@ -224,6 +226,7 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
     .argument('<name>', 'Project name')
     .option('-d, --description <text>', 'Project description', '')
     .option('--proxy-mode <mode>', 'Proxy mode (direct, filtered)')
+    .option('--proxy-model <name>', 'ProxyModel pipeline name (e.g. default, subindex)')
     .option('--prompt <text>', 'Project-level prompt / instructions for the LLM')
     .option('--gated', 'Enable gated sessions (default: true)')
     .option('--no-gated', 'Disable gated sessions')
@@ -236,6 +239,7 @@ export function createCreateCommand(deps: CreateCommandDeps): Command {
         proxyMode: opts.proxyMode ?? 'direct',
       };
       if (opts.prompt) body.prompt = opts.prompt;
+      if (opts.proxyModel) body.proxyModel = opts.proxyModel;
       if (opts.gated !== undefined) body.gated = opts.gated as boolean;
       if (opts.server.length > 0) body.servers = opts.server;
 

src/cli/src/commands/describe.ts

@@ -8,6 +8,7 @@ export interface DescribeCommandDeps {
   fetchResource: (resource: string, id: string) => Promise<unknown>;
   fetchInspect?: (id: string) => Promise<unknown>;
   log: (...args: string[]) => void;
+  mcplocalUrl?: string;
 }
 
 function pad(label: string, width = 18): string {
@@ -145,12 +146,14 @@ function formatProjectDetail(
 
   // Proxy config section
   const proxyMode = project.proxyMode as string | undefined;
+  const proxyModel = project.proxyModel as string | undefined;
   const llmProvider = project.llmProvider as string | undefined;
   const llmModel = project.llmModel as string | undefined;
-  if (proxyMode || llmProvider || llmModel) {
+  if (proxyMode || proxyModel || llmProvider || llmModel) {
     lines.push('');
     lines.push('Proxy Config:');
     lines.push(`  ${pad('Mode:', 18)}${proxyMode ?? 'direct'}`);
+    lines.push(`  ${pad('ProxyModel:', 18)}${proxyModel || 'default'}`);
     if (llmProvider) lines.push(`  ${pad('LLM Provider:', 18)}${llmProvider}`);
     if (llmModel) lines.push(`  ${pad('LLM Model:', 18)}${llmModel}`);
   }
@@ -593,6 +596,46 @@ async function resolveLink(linkTarget: string, client: ApiClient): Promise<strin
   }
 }
 
+function formatProxymodelDetail(model: Record<string, unknown>): string {
+  const lines: string[] = [];
+  lines.push(`=== ProxyModel: ${model.name} ===`);
+  lines.push(`${pad('Name:')}${model.name}`);
+  lines.push(`${pad('Source:')}${model.source ?? 'unknown'}`);
+  lines.push(`${pad('Controller:')}${model.controller ?? '-'}`);
+  lines.push(`${pad('Cacheable:')}${model.cacheable ? 'yes' : 'no'}`);
+
+  const appliesTo = model.appliesTo as string[] | undefined;
+  if (appliesTo && appliesTo.length > 0) {
+    lines.push(`${pad('Applies To:')}${appliesTo.join(', ')}`);
+  }
+
+  const controllerConfig = model.controllerConfig as Record<string, unknown> | undefined;
+  if (controllerConfig && Object.keys(controllerConfig).length > 0) {
+    lines.push('');
+    lines.push('Controller Config:');
+    for (const [key, value] of Object.entries(controllerConfig)) {
+      lines.push(`  ${pad(key + ':', 20)}${String(value)}`);
+    }
+  }
+
+  const stages = model.stages as Array<{ type: string; config?: Record<string, unknown> }> | undefined;
+  if (stages && stages.length > 0) {
+    lines.push('');
+    lines.push('Stages:');
+    for (let i = 0; i < stages.length; i++) {
+      const s = stages[i]!;
+      lines.push(`  ${i + 1}. ${s.type}`);
+      if (s.config && Object.keys(s.config).length > 0) {
+        for (const [key, value] of Object.entries(s.config)) {
+          lines.push(`     ${pad(key + ':', 20)}${String(value)}`);
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
 function formatGenericDetail(obj: Record<string, unknown>): string {
   const lines: string[] = [];
   for (const [key, value] of Object.entries(obj)) {
@@ -629,6 +672,20 @@ export function createDescribeCommand(deps: DescribeCommandDeps): Command {
     .action(async (resourceArg: string, idOrName: string, opts: { output: string; showValues?: boolean }) => {
       const resource = resolveResource(resourceArg);
 
+      // ProxyModels are served by mcplocal, not mcpd
+      if (resource === 'proxymodels') {
+        const mcplocalUrl = deps.mcplocalUrl ?? 'http://localhost:3200';
+        const item = await fetchProxymodelFromMcplocal(mcplocalUrl, idOrName);
+        if (opts.output === 'json') {
+          deps.log(formatJson(item));
+        } else if (opts.output === 'yaml') {
+          deps.log(formatYaml(item));
+        } else {
+          deps.log(formatProxymodelDetail(item));
+        }
+        return;
+      }
+
       // Resolve name → ID
       let id: string;
       if (resource === 'instances') {
@@ -733,3 +790,28 @@ export function createDescribeCommand(deps: DescribeCommandDeps): Command {
       }
     });
 }
+
+async function fetchProxymodelFromMcplocal(mcplocalUrl: string, name: string): Promise<Record<string, unknown>> {
+  const http = await import('node:http');
+  const url = `${mcplocalUrl}/proxymodels/${encodeURIComponent(name)}`;
+
+  return new Promise<Record<string, unknown>>((resolve, reject) => {
+    const req = http.get(url, { timeout: 5000 }, (res) => {
+      let data = '';
+      res.on('data', (chunk: Buffer) => { data += chunk.toString(); });
+      res.on('end', () => {
+        try {
+          if (res.statusCode === 404) {
+            reject(new Error(`ProxyModel '${name}' not found`));
+            return;
+          }
+          resolve(JSON.parse(data) as Record<string, unknown>);
+        } catch {
+          reject(new Error('Invalid response from mcplocal'));
+        }
+      });
+    });
+    req.on('error', () => reject(new Error(`Cannot connect to mcplocal at ${mcplocalUrl}`)));
+    req.on('timeout', () => { req.destroy(); reject(new Error('mcplocal request timed out')); });
+  });
+}

src/cli/src/commands/get.ts

@@ -8,6 +8,7 @@ export interface GetCommandDeps {
   fetchResource: (resource: string, id?: string, opts?: { project?: string; all?: boolean }) => Promise<unknown[]>;
   log: (...args: string[]) => void;
   getProject?: () => string | undefined;
+  mcplocalUrl?: string;
 }
 
 interface ServerRow {
@@ -23,6 +24,7 @@ interface ProjectRow {
   name: string;
   description: string;
   proxyMode: string;
+  proxyModel: string;
   gated: boolean;
   ownerId: string;
   servers?: Array<{ server: { name: string } }>;
@@ -85,6 +87,7 @@ interface RbacRow {
 const projectColumns: Column<ProjectRow>[] = [
   { header: 'NAME', key: 'name' },
   { header: 'MODE', key: (r) => r.proxyMode ?? 'direct', width: 10 },
+  { header: 'PROXYMODEL', key: (r) => r.proxyModel || 'default', width: 12 },
   { header: 'GATED', key: (r) => r.gated ? 'yes' : 'no', width: 6 },
   { header: 'SERVERS', key: (r) => r.servers ? String(r.servers.length) : '0', width: 8 },
   { header: 'DESCRIPTION', key: 'description', width: 30 },
@@ -190,6 +193,22 @@ const serverAttachmentColumns: Column<ServerAttachmentRow>[] = [
   { header: 'PROJECT', key: 'project', width: 25 },
 ];
 
+interface ProxymodelRow {
+  name: string;
+  source: string;
+  controller: string;
+  stages: string[];
+  cacheable: boolean;
+}
+
+const proxymodelColumns: Column<ProxymodelRow>[] = [
+  { header: 'NAME', key: 'name' },
+  { header: 'SOURCE', key: 'source', width: 10 },
+  { header: 'CONTROLLER', key: 'controller', width: 12 },
+  { header: 'STAGES', key: (r) => r.stages.join(', '), width: 40 },
+  { header: 'CACHEABLE', key: (r) => r.cacheable ? 'yes' : 'no', width: 10 },
+];
+
 function getColumnsForResource(resource: string): Column<Record<string, unknown>>[] {
   switch (resource) {
     case 'servers':
@@ -214,6 +233,8 @@ function getColumnsForResource(resource: string): Column<Record<string, unknown>
       return promptRequestColumns as unknown as Column<Record<string, unknown>>[];
     case 'serverattachments':
       return serverAttachmentColumns as unknown as Column<Record<string, unknown>>[];
+    case 'proxymodels':
+      return proxymodelColumns as unknown as Column<Record<string, unknown>>[];
     default:
       return [
         { header: 'ID', key: 'id' as keyof Record<string, unknown> },
@@ -268,6 +289,25 @@ export function createGetCommand(deps: GetCommandDeps): Command {
         return;
       }
 
+      // ProxyModels are served by mcplocal, not mcpd
+      if (resource === 'proxymodels') {
+        const mcplocalUrl = deps.mcplocalUrl ?? 'http://localhost:3200';
+        const items = await fetchProxymodels(mcplocalUrl, id);
+        if (opts.output === 'json') {
+          deps.log(formatJson(items));
+        } else if (opts.output === 'yaml') {
+          deps.log(formatYamlMultiDoc(items.map((i) => ({ kind: 'proxymodel', ...(i as Record<string, unknown>) }))));
+        } else {
+          if (items.length === 0) {
+            deps.log('No proxymodels found.');
+            return;
+          }
+          const columns = getColumnsForResource(resource);
+          deps.log(formatTable(items as Record<string, unknown>[], columns));
+        }
+        return;
+      }
+
       const fetchOpts: { project?: string; all?: boolean } = {};
       if (project) fetchOpts.project = project;
       if (opts.all) fetchOpts.all = true;
@@ -343,3 +383,27 @@ async function handleGetAll(
     deps.log(`\nUse -o yaml or -o json for apply-compatible output.`);
   }
 }
+
+async function fetchProxymodels(mcplocalUrl: string, name?: string): Promise<unknown[]> {
+  const http = await import('node:http');
+  const url = name
+    ? `${mcplocalUrl}/proxymodels/${encodeURIComponent(name)}`
+    : `${mcplocalUrl}/proxymodels`;
+
+  return new Promise<unknown[]>((resolve, reject) => {
+    const req = http.get(url, { timeout: 5000 }, (res) => {
+      let data = '';
+      res.on('data', (chunk: Buffer) => { data += chunk.toString(); });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data) as unknown;
+          resolve(Array.isArray(parsed) ? parsed : [parsed]);
+        } catch {
+          reject(new Error('Invalid response from mcplocal'));
+        }
+      });
+    });
+    req.on('error', () => reject(new Error(`Cannot connect to mcplocal at ${mcplocalUrl}`)));
+    req.on('timeout', () => { req.destroy(); reject(new Error('mcplocal request timed out')); });
+  });
+}

src/cli/src/commands/shared.ts

@@ -24,6 +24,9 @@ export const RESOURCE_ALIASES: Record<string, string> = {
   serverattachment: 'serverattachments',
   serverattachments: 'serverattachments',
   sa: 'serverattachments',
+  proxymodel: 'proxymodels',
+  proxymodels: 'proxymodels',
+  pm: 'proxymodels',
   all: 'all',
 };
 

src/cli/src/commands/status.ts

@@ -10,14 +10,22 @@ import { APP_VERSION } from '@mcpctl/shared';
 // ANSI helpers
 const GREEN = '\x1b[32m';
 const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
 const DIM = '\x1b[2m';
 const RESET = '\x1b[0m';
 const CLEAR_LINE = '\x1b[2K\r';
 
+interface ProviderDetail {
+  managed: boolean;
+  state?: string;
+  lastError?: string;
+}
+
 interface ProvidersInfo {
   providers: string[];
   tiers: { fast: string[]; heavy: string[] };
   health: Record<string, boolean>;
+  details?: Record<string, ProviderDetail>;
 }
 
 export interface StatusCommandDeps {
@@ -155,6 +163,40 @@ function isMultiProvider(llm: unknown): boolean {
   return !!llm && typeof llm === 'object' && 'providers' in llm;
 }
 
+/**
+ * Format a single provider's status string for display.
+ * Managed providers show lifecycle state; regular providers show health check result.
+ */
+function formatProviderStatus(name: string, info: ProvidersInfo, ansi: boolean): string {
+  const detail = info.details?.[name];
+  if (detail?.managed) {
+    switch (detail.state) {
+      case 'running':
+        return ansi ? `${name} ${GREEN}✓ running${RESET}` : `${name} ✓ running`;
+      case 'stopped':
+        return ansi
+          ? `${name} ${DIM}○ stopped (auto-starts on demand)${RESET}`
+          : `${name} ○ stopped (auto-starts on demand)`;
+      case 'starting':
+        return ansi ? `${name} ${YELLOW}⟳ starting...${RESET}` : `${name} ⟳ starting...`;
+      case 'error':
+        return ansi
+          ? `${name} ${RED}✗ error: ${detail.lastError ?? 'unknown'}${RESET}`
+          : `${name} ✗ error: ${detail.lastError ?? 'unknown'}`;
+      default: {
+        const ok = info.health[name];
+        return ansi
+          ? ok ? `${name} ${GREEN}✓${RESET}` : `${name} ${RED}✗${RESET}`
+          : ok ? `${name} ✓` : `${name} ✗`;
+      }
+    }
+  }
+  const ok = info.health[name];
+  return ansi
+    ? ok ? `${name} ${GREEN}✓${RESET}` : `${name} ${RED}✗${RESET}`
+    : ok ? `${name} ✓` : `${name} ✗`;
+}
+
 export function createStatusCommand(deps?: Partial<StatusCommandDeps>): Command {
   const { configDeps, credentialsDeps, log, write, checkHealth, checkLlm, fetchModels, fetchProviders, isTTY } = { ...defaultDeps, ...deps };
 
@@ -241,10 +283,7 @@ export function createStatusCommand(deps?: Partial<StatusCommandDeps>): Command
             const names = providersInfo.tiers[tier];
             if (names.length === 0) continue;
             const label = tier === 'fast' ? 'LLM (fast): ' : 'LLM (heavy):';
-            const parts = names.map((n) => {
-              const ok = providersInfo.health[n];
-              return ok ? `${n} ${GREEN}✓${RESET}` : `${n} ${RED}✗${RESET}`;
-            });
+            const parts = names.map((n) => formatProviderStatus(n, providersInfo, true));
             log(`${label} ${parts.join(', ')}`);
           }
         } else {
@@ -267,10 +306,7 @@ export function createStatusCommand(deps?: Partial<StatusCommandDeps>): Command
             const names = providersInfo.tiers[tier];
             if (names.length === 0) continue;
             const label = tier === 'fast' ? 'LLM (fast): ' : 'LLM (heavy):';
-            const parts = names.map((n) => {
-              const ok = providersInfo.health[n];
-              return ok ? `${n} ✓` : `${n} ✗`;
-            });
+            const parts = names.map((n) => formatProviderStatus(n, providersInfo, false));
             log(`${label} ${parts.join(', ')}`);
           }
         } else {

src/cli/src/config/schema.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-export const LLM_PROVIDERS = ['gemini-cli', 'ollama', 'anthropic', 'openai', 'deepseek', 'vllm', 'none'] as const;
+export const LLM_PROVIDERS = ['gemini-cli', 'ollama', 'anthropic', 'openai', 'deepseek', 'vllm', 'vllm-managed', 'none'] as const;
 export type LlmProviderName = typeof LLM_PROVIDERS[number];
 
 export const LLM_TIERS = ['fast', 'heavy'] as const;
@@ -34,6 +34,18 @@ export const LlmProviderEntrySchema = z.object({
   binaryPath: z.string().optional(),
   /** Tier assignment */
   tier: z.enum(LLM_TIERS).optional(),
+  /** vllm-managed: path to Python venv (e.g. "~/vllm_env") */
+  venvPath: z.string().optional(),
+  /** vllm-managed: port for vLLM HTTP server */
+  port: z.number().int().positive().optional(),
+  /** vllm-managed: GPU memory utilization fraction */
+  gpuMemoryUtilization: z.number().min(0.1).max(1.0).optional(),
+  /** vllm-managed: max model context length */
+  maxModelLen: z.number().int().positive().optional(),
+  /** vllm-managed: minutes of idle before stopping vLLM */
+  idleTimeoutMinutes: z.number().int().positive().optional(),
+  /** vllm-managed: extra args for `vllm serve` */
+  extraArgs: z.array(z.string()).optional(),
 }).strict();
 
 export type LlmProviderEntry = z.infer<typeof LlmProviderEntrySchema>;

src/cli/src/index.ts

@@ -81,6 +81,12 @@ export function createProgram(): Command {
       return attachments;
     }
 
+    // --project scoping for servers: show only attached servers
+    if (!nameOrId && resource === 'servers' && projectName) {
+      const projectId = await resolveNameOrId(client, 'projects', projectName);
+      return client.get<unknown[]>(`/api/v1/projects/${projectId}/servers`);
+    }
+
     // --project scoping for prompts and promptrequests
     if (!nameOrId && (resource === 'prompts' || resource === 'promptrequests')) {
       if (projectName) {
@@ -138,6 +144,7 @@ export function createProgram(): Command {
     fetchResource,
     log: (...args) => console.log(...args),
     getProject: () => program.opts().project as string | undefined,
+    mcplocalUrl: config.mcplocalUrl,
   }));
 
   program.addCommand(createDescribeCommand({
@@ -145,6 +152,7 @@ export function createProgram(): Command {
     fetchResource: fetchSingleResource,
     fetchInspect: async (id: string) => client.get(`/api/v1/instances/${id}/inspect`),
     log: (...args) => console.log(...args),
+    mcplocalUrl: config.mcplocalUrl,
   }));
 
   program.addCommand(createDeleteCommand({

src/cli/tests/commands/claude.test.ts

@@ -96,7 +96,7 @@ describe('config claude', () => {
     const written = JSON.parse(readFileSync(outPath, 'utf-8'));
     expect(written.mcpServers['mcpctl-inspect']).toEqual({
       command: 'mcpctl',
-      args: ['console', '--inspect', '--stdin-mcp'],
+      args: ['console', '--stdin-mcp'],
     });
     expect(output.join('\n')).toContain('1 server(s)');
   });

src/cli/tests/commands/config-setup.test.ts

@@ -161,9 +161,11 @@ describe('config setup wizard', () => {
 
   describe('provider: anthropic', () => {
     it('prompts for API key and saves to secret store', async () => {
-      // Answers: select provider, enter API key, select model
+      // Flow: simple → anthropic → (no existing key) → whichBinary('claude') returns null →
+      //   log tip → password prompt → select model
       const deps = buildDeps({
         answers: ['simple', 'anthropic', 'sk-ant-new-key', 'claude-haiku-3-5-20241022'],
+        whichBinary: vi.fn(async () => null),
       });
       await runSetup(deps);
 
@@ -194,15 +196,84 @@ describe('config setup wizard', () => {
 
     it('allows replacing existing key', async () => {
       // Answers: select provider, confirm change=true, enter new key, select model
+      // Change=true → promptForAnthropicKey → whichBinary returns null → password prompt
       const deps = buildDeps({
         secrets: { 'anthropic-api-key': 'sk-ant-old' },
         answers: ['simple', 'anthropic', true, 'sk-ant-new', 'claude-haiku-3-5-20241022'],
+        whichBinary: vi.fn(async () => null),
       });
       await runSetup(deps);
 
       expect(deps.secretStore.set).toHaveBeenCalledWith('anthropic-api-key', 'sk-ant-new');
       cleanup();
     });
+
+    it('detects claude binary and prompts for OAuth token', async () => {
+      // Flow: simple → anthropic → (no existing key) → whichBinary finds claude →
+      //   confirm OAuth=true → password prompt → select model
+      const deps = buildDeps({
+        answers: ['simple', 'anthropic', true, 'sk-ant-oat01-test-token', 'claude-haiku-3-5-20241022'],
+        whichBinary: vi.fn(async () => '/usr/bin/claude'),
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('anthropic-api-key', 'sk-ant-oat01-test-token');
+      expect(logs.some((l) => l.includes('Found Claude CLI at'))).toBe(true);
+      expect(logs.some((l) => l.includes('claude setup-token'))).toBe(true);
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('anthropic');
+      expect(llm.model).toBe('claude-haiku-3-5-20241022');
+      cleanup();
+    });
+
+    it('falls back to API key when claude binary not found', async () => {
+      // Flow: simple → anthropic → (no existing key) → whichBinary returns null →
+      //   password prompt (API key) → select model
+      const deps = buildDeps({
+        answers: ['simple', 'anthropic', 'sk-ant-api03-test', 'claude-sonnet-4-20250514'],
+        whichBinary: vi.fn(async () => null),
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('anthropic-api-key', 'sk-ant-api03-test');
+      expect(logs.some((l) => l.includes('Tip: Install Claude CLI'))).toBe(true);
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.model).toBe('claude-sonnet-4-20250514');
+      cleanup();
+    });
+
+    it('shows OAuth label when existing token is OAuth', async () => {
+      // Flow: simple → anthropic → existing OAuth key → confirm change=false → select model
+      const deps = buildDeps({
+        secrets: { 'anthropic-api-key': 'sk-ant-oat01-existing-token' },
+        answers: ['simple', 'anthropic', false, 'claude-haiku-3-5-20241022'],
+      });
+      await runSetup(deps);
+
+      // Should NOT have called set (kept existing key)
+      expect(deps.secretStore.set).not.toHaveBeenCalled();
+      // Confirm prompt should have received an OAuth label
+      expect(deps.prompt.confirm).toHaveBeenCalledWith(
+        expect.stringContaining('OAuth token stored'),
+        false,
+      );
+      cleanup();
+    });
+
+    it('declines OAuth and enters API key instead', async () => {
+      // Flow: simple → anthropic → (no existing key) → whichBinary finds claude →
+      //   confirm OAuth=false → password prompt (API key) → select model
+      const deps = buildDeps({
+        answers: ['simple', 'anthropic', false, 'sk-ant-api03-manual', 'claude-sonnet-4-20250514'],
+        whichBinary: vi.fn(async () => '/usr/bin/claude'),
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('anthropic-api-key', 'sk-ant-api03-manual');
+      cleanup();
+    });
   });
 
   describe('provider: vllm', () => {
@@ -273,6 +344,44 @@ describe('config setup wizard', () => {
     });
   });
 
+  describe('advanced mode: duplicate names', () => {
+    it('generates unique default name when same provider added to both tiers', async () => {
+      // Flow: advanced →
+      //   add fast? yes → anthropic → name "anthropic" (default) → whichBinary null → key → model → add more? no →
+      //   add heavy? yes → anthropic → name "anthropic-2" (deduped default) → existing key, keep → model → add more? no
+      const deps = buildDeps({
+        answers: [
+          'advanced',
+          // fast tier
+          true,                          // add fast?
+          'anthropic',                   // fast provider type
+          'anthropic',                   // provider name (default)
+          'sk-ant-oat01-token',          // API key (whichBinary returns null → password prompt)
+          'claude-haiku-3-5-20241022',   // model
+          false,                         // add another fast?
+          // heavy tier
+          true,                          // add heavy?
+          'anthropic',                   // heavy provider type
+          'anthropic-2',                 // provider name (deduped default)
+          false,                         // keep existing key
+          'claude-opus-4-20250514',      // model
+          false,                         // add another heavy?
+        ],
+        whichBinary: vi.fn(async () => null),
+      });
+      await runSetup(deps);
+
+      const config = readConfig();
+      const llm = config.llm as { providers: Array<{ name: string; type: string; model: string; tier: string }> };
+      expect(llm.providers).toHaveLength(2);
+      expect(llm.providers[0].name).toBe('anthropic');
+      expect(llm.providers[0].tier).toBe('fast');
+      expect(llm.providers[1].name).toBe('anthropic-2');
+      expect(llm.providers[1].tier).toBe('heavy');
+      cleanup();
+    });
+  });
+
   describe('output messages', () => {
     it('shows restart instruction', async () => {
       const deps = buildDeps({ answers: ['simple', 'gemini-cli', 'gemini-2.5-flash'] });

src/cli/tests/completions.test.ts

@@ -85,17 +85,15 @@ describe('fish completions', () => {
     }
   });
 
-  it('resource name functions use jq .[][].name to unwrap wrapped JSON and avoid nested matches', () => {
-    // API returns { "resources": [...] } not [...], so .[].name fails silently.
-    // Must use .[][].name to unwrap the outer object then iterate the array.
-    // Also must not use string match regex which matches nested name fields.
+  it('resource name functions use jq to extract names and avoid nested matches', () => {
     const resourceNamesFn = fishFile.match(/function __mcpctl_resource_names[\s\S]*?^end/m)?.[0] ?? '';
     const projectNamesFn = fishFile.match(/function __mcpctl_project_names[\s\S]*?^end/m)?.[0] ?? '';
 
-    expect(resourceNamesFn, '__mcpctl_resource_names must use jq .[][].name').toContain("jq -r '.[][].name'");
+    // Resource names: uses .[].name for most resources, .[][].server.name for instances
+    expect(resourceNamesFn, '__mcpctl_resource_names must use jq for name extraction').toContain("jq -r");
     expect(resourceNamesFn, '__mcpctl_resource_names must not use string match on name').not.toMatch(/string match.*"name"/);
 
-    expect(projectNamesFn, '__mcpctl_project_names must use jq .[][].name').toContain("jq -r '.[][].name'");
+    expect(projectNamesFn, '__mcpctl_project_names must use jq for name extraction').toContain("jq -r");
     expect(projectNamesFn, '__mcpctl_project_names must not use string match on name').not.toMatch(/string match.*"name"/);
   });
 
@@ -179,11 +177,9 @@ describe('bash completions', () => {
     expect(bashFile).toContain('--project');
   });
 
-  it('resource name function uses jq .[][].name to unwrap wrapped JSON and avoid nested matches', () => {
+  it('resource name function uses jq to extract names and avoid nested matches', () => {
     const fnMatch = bashFile.match(/_mcpctl_resource_names\(\)[\s\S]*?\n\s*\}/)?.[0] ?? '';
-    expect(fnMatch, '_mcpctl_resource_names must use jq .[][].name').toContain("jq -r '.[][].name'");
+    expect(fnMatch, '_mcpctl_resource_names must use jq for name extraction').toContain("jq -r");
     expect(fnMatch, '_mcpctl_resource_names must not use grep on name').not.toMatch(/grep.*"name"/);
-    // Guard against .[].name (single bracket) which fails on wrapped JSON
-    expect(fnMatch, '_mcpctl_resource_names must not use .[].name (needs .[][].name)').not.toMatch(/jq.*'\.\[\]\.name'/);
   });
 });

src/db/prisma/migrations/20260227180000_add_runtime_field/migration.sql

@@ -0,0 +1,5 @@
+-- AlterTable
+ALTER TABLE "McpServer" ADD COLUMN "runtime" TEXT;
+
+-- AlterTable
+ALTER TABLE "McpTemplate" ADD COLUMN "runtime" TEXT;

src/db/prisma/migrations/20260228120000_add_proxymodel_to_project/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "Project" ADD COLUMN "proxyModel" TEXT NOT NULL DEFAULT '';

src/db/prisma/migrations/20260301120000_add_audit_events_and_server_overrides/migration.sql

@@ -0,0 +1,27 @@
+-- CreateTable
+CREATE TABLE "AuditEvent" (
+    "id" TEXT NOT NULL,
+    "timestamp" TIMESTAMP(3) NOT NULL,
+    "sessionId" TEXT NOT NULL,
+    "projectName" TEXT NOT NULL,
+    "eventKind" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "verified" BOOLEAN NOT NULL DEFAULT false,
+    "serverName" TEXT,
+    "correlationId" TEXT,
+    "parentEventId" TEXT,
+    "payload" JSONB NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "AuditEvent_pkey" PRIMARY KEY ("id")
+);
+
+-- AlterTable
+ALTER TABLE "Project" ADD COLUMN "serverOverrides" JSONB;
+
+-- CreateIndex
+CREATE INDEX "AuditEvent_sessionId_idx" ON "AuditEvent"("sessionId");
+CREATE INDEX "AuditEvent_projectName_idx" ON "AuditEvent"("projectName");
+CREATE INDEX "AuditEvent_correlationId_idx" ON "AuditEvent"("correlationId");
+CREATE INDEX "AuditEvent_timestamp_idx" ON "AuditEvent"("timestamp");
+CREATE INDEX "AuditEvent_eventKind_idx" ON "AuditEvent"("eventKind");

src/db/prisma/schema.prisma

@@ -57,6 +57,7 @@ model McpServer {
   name          String          @unique
   description   String          @default("")
   packageName   String?
+  runtime       String?
   dockerImage   String?
   transport     Transport       @default(STDIO)
   repositoryUrl String?
@@ -93,6 +94,7 @@ model McpTemplate {
   version       String    @default("1.0.0")
   description   String    @default("")
   packageName   String?
+  runtime       String?
   dockerImage   String?
   transport     Transport @default(STDIO)
   repositoryUrl String?
@@ -172,10 +174,12 @@ model Project {
   description String   @default("")
   prompt      String   @default("")
   proxyMode   String   @default("direct")
+  proxyModel  String   @default("")
   gated       Boolean  @default(true)
-  llmProvider String?
-  llmModel    String?
-  ownerId     String
+  llmProvider     String?
+  llmModel        String?
+  serverOverrides Json?
+  ownerId         String
   version     Int      @default(1)
   createdAt   DateTime @default(now())
   updatedAt   DateTime @updatedAt
@@ -271,6 +275,29 @@ model PromptRequest {
   @@index([createdBySession])
 }
 
+// ── Audit Events (pipeline/gate/tool trace from mcplocal) ──
+
+model AuditEvent {
+  id             String   @id @default(cuid())
+  timestamp      DateTime
+  sessionId      String
+  projectName    String
+  eventKind      String
+  source         String
+  verified       Boolean  @default(false)
+  serverName     String?
+  correlationId  String?
+  parentEventId  String?
+  payload        Json
+  createdAt      DateTime @default(now())
+
+  @@index([sessionId])
+  @@index([projectName])
+  @@index([correlationId])
+  @@index([timestamp])
+  @@index([eventKind])
+}
+
 // ── Audit Logs ──
 
 model AuditLog {

src/db/tests/helpers.ts

@@ -28,6 +28,7 @@ export async function cleanupTestDb(): Promise<void> {
 
 export async function clearAllTables(client: PrismaClient): Promise<void> {
   // Delete in order respecting foreign keys
+  await client.auditEvent.deleteMany();
   await client.auditLog.deleteMany();
   await client.mcpInstance.deleteMany();
   await client.promptRequest.deleteMany();

src/mcpd/src/main.ts

@@ -17,6 +17,7 @@ import {
   RbacDefinitionRepository,
   UserRepository,
   GroupRepository,
+  AuditEventRepository,
 } from './repositories/index.js';
 import { PromptRepository } from './repositories/prompt.repository.js';
 import { PromptRequestRepository } from './repositories/prompt-request.repository.js';
@@ -40,6 +41,7 @@ import {
   RbacService,
   UserService,
   GroupService,
+  AuditEventService,
 } from './services/index.js';
 import type { RbacAction } from './services/index.js';
 import type { UpdateRbacDefinitionInput } from './validation/rbac-definition.schema.js';
@@ -58,6 +60,7 @@ import {
   registerRbacRoutes,
   registerUserRoutes,
   registerGroupRoutes,
+  registerAuditEventRoutes,
 } from './routes/index.js';
 import { registerPromptRoutes } from './routes/prompts.js';
 import { PromptService } from './services/prompt.service.js';
@@ -245,6 +248,7 @@ async function main(): Promise<void> {
   const instanceRepo = new McpInstanceRepository(prisma);
   const projectRepo = new ProjectRepository(prisma);
   const auditLogRepo = new AuditLogRepository(prisma);
+  const auditEventRepo = new AuditEventRepository(prisma);
   const templateRepo = new TemplateRepository(prisma);
   const rbacDefinitionRepo = new RbacDefinitionRepository(prisma);
   const userRepo = new UserRepository(prisma);
@@ -272,6 +276,7 @@ async function main(): Promise<void> {
   const secretService = new SecretService(secretRepo);
   const projectService = new ProjectService(projectRepo, serverRepo, secretRepo);
   const auditLogService = new AuditLogService(auditLogRepo);
+  const auditEventService = new AuditEventService(auditEventRepo);
   const metricsCollector = new MetricsCollector();
   const healthAggregator = new HealthAggregator(metricsCollector, orchestrator);
   const backupService = new BackupService(serverRepo, projectRepo, secretRepo, userRepo, groupRepo, rbacDefinitionRepo);
@@ -366,6 +371,7 @@ async function main(): Promise<void> {
   registerInstanceRoutes(app, instanceService);
   registerProjectRoutes(app, projectService);
   registerAuditLogRoutes(app, auditLogService);
+  registerAuditEventRoutes(app, auditEventService);
   registerHealthMonitoringRoutes(app, { healthAggregator, metricsCollector });
   registerBackupRoutes(app, { backupService, restoreService });
   registerAuthRoutes(app, { authService, userService, groupService, rbacDefinitionService, rbacService });

src/mcpd/src/repositories/audit-event.repository.ts

@@ -0,0 +1,62 @@
+import type { PrismaClient, AuditEvent, Prisma } from '@prisma/client';
+import type { IAuditEventRepository, AuditEventFilter, AuditEventCreateInput } from './interfaces.js';
+
+export class AuditEventRepository implements IAuditEventRepository {
+  constructor(private readonly prisma: PrismaClient) {}
+
+  async findAll(filter?: AuditEventFilter): Promise<AuditEvent[]> {
+    const where = buildWhere(filter);
+    return this.prisma.auditEvent.findMany({
+      where,
+      orderBy: { timestamp: 'desc' },
+      take: filter?.limit ?? 100,
+      skip: filter?.offset ?? 0,
+    });
+  }
+
+  async findById(id: string): Promise<AuditEvent | null> {
+    return this.prisma.auditEvent.findUnique({ where: { id } });
+  }
+
+  async createMany(events: AuditEventCreateInput[]): Promise<number> {
+    const data = events.map((e) => ({
+      timestamp: new Date(e.timestamp),
+      sessionId: e.sessionId,
+      projectName: e.projectName,
+      eventKind: e.eventKind,
+      source: e.source,
+      verified: e.verified,
+      serverName: e.serverName ?? null,
+      correlationId: e.correlationId ?? null,
+      parentEventId: e.parentEventId ?? null,
+      payload: e.payload as Prisma.InputJsonValue,
+    }));
+    const result = await this.prisma.auditEvent.createMany({ data });
+    return result.count;
+  }
+
+  async count(filter?: AuditEventFilter): Promise<number> {
+    const where = buildWhere(filter);
+    return this.prisma.auditEvent.count({ where });
+  }
+}
+
+function buildWhere(filter?: AuditEventFilter): Prisma.AuditEventWhereInput {
+  const where: Prisma.AuditEventWhereInput = {};
+  if (!filter) return where;
+
+  if (filter.sessionId !== undefined) where.sessionId = filter.sessionId;
+  if (filter.projectName !== undefined) where.projectName = filter.projectName;
+  if (filter.eventKind !== undefined) where.eventKind = filter.eventKind;
+  if (filter.serverName !== undefined) where.serverName = filter.serverName;
+  if (filter.correlationId !== undefined) where.correlationId = filter.correlationId;
+
+  if (filter.from !== undefined || filter.to !== undefined) {
+    const timestamp: Prisma.DateTimeFilter = {};
+    if (filter.from !== undefined) timestamp.gte = filter.from;
+    if (filter.to !== undefined) timestamp.lte = filter.to;
+    where.timestamp = timestamp;
+  }
+
+  return where;
+}

src/mcpd/src/repositories/index.ts

@@ -13,3 +13,5 @@ export type { IUserRepository, SafeUser } from './user.repository.js';
 export { UserRepository } from './user.repository.js';
 export type { IGroupRepository, GroupWithMembers } from './group.repository.js';
 export { GroupRepository } from './group.repository.js';
+export type { IAuditEventRepository, AuditEventFilter, AuditEventCreateInput } from './interfaces.js';
+export { AuditEventRepository } from './audit-event.repository.js';

src/mcpd/src/repositories/interfaces.ts

@@ -1,4 +1,4 @@
-import type { McpServer, McpInstance, AuditLog, Secret, InstanceStatus } from '@prisma/client';
+import type { McpServer, McpInstance, AuditLog, AuditEvent, Secret, InstanceStatus } from '@prisma/client';
 import type { CreateMcpServerInput, UpdateMcpServerInput } from '../validation/mcp-server.schema.js';
 import type { CreateSecretInput, UpdateSecretInput } from '../validation/secret.schema.js';
 
@@ -47,3 +47,37 @@ export interface IAuditLogRepository {
   count(filter?: AuditLogFilter): Promise<number>;
   deleteOlderThan(date: Date): Promise<number>;
 }
+
+// ── Audit Events (pipeline/gate traces from mcplocal) ──
+
+export interface AuditEventFilter {
+  sessionId?: string;
+  projectName?: string;
+  eventKind?: string;
+  serverName?: string;
+  correlationId?: string;
+  from?: Date;
+  to?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+export interface AuditEventCreateInput {
+  timestamp: string;
+  sessionId: string;
+  projectName: string;
+  eventKind: string;
+  source: string;
+  verified: boolean;
+  serverName?: string;
+  correlationId?: string;
+  parentEventId?: string;
+  payload: Record<string, unknown>;
+}
+
+export interface IAuditEventRepository {
+  findAll(filter?: AuditEventFilter): Promise<AuditEvent[]>;
+  findById(id: string): Promise<AuditEvent | null>;
+  createMany(events: AuditEventCreateInput[]): Promise<number>;
+  count(filter?: AuditEventFilter): Promise<number>;
+}

src/mcpd/src/repositories/mcp-server.repository.ts

@@ -23,6 +23,7 @@ export class McpServerRepository implements IMcpServerRepository {
         name: data.name,
         description: data.description,
         packageName: data.packageName ?? null,
+        runtime: data.runtime ?? null,
         dockerImage: data.dockerImage ?? null,
         transport: data.transport,
         repositoryUrl: data.repositoryUrl ?? null,
@@ -40,6 +41,7 @@ export class McpServerRepository implements IMcpServerRepository {
     const updateData: Record<string, unknown> = {};
     if (data.description !== undefined) updateData['description'] = data.description;
     if (data.packageName !== undefined) updateData['packageName'] = data.packageName;
+    if (data.runtime !== undefined) updateData['runtime'] = data.runtime;
     if (data.dockerImage !== undefined) updateData['dockerImage'] = data.dockerImage;
     if (data.transport !== undefined) updateData['transport'] = data.transport;
     if (data.repositoryUrl !== undefined) updateData['repositoryUrl'] = data.repositoryUrl;

src/mcpd/src/repositories/project.repository.ts

@@ -12,7 +12,7 @@ export interface IProjectRepository {
   findAll(ownerId?: string): Promise<ProjectWithRelations[]>;
   findById(id: string): Promise<ProjectWithRelations | null>;
   findByName(name: string): Promise<ProjectWithRelations | null>;
-  create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; gated?: boolean; llmProvider?: string; llmModel?: string }): Promise<ProjectWithRelations>;
+  create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; proxyModel?: string; gated?: boolean; llmProvider?: string; llmModel?: string; serverOverrides?: Record<string, unknown> }): Promise<ProjectWithRelations>;
   update(id: string, data: Record<string, unknown>): Promise<ProjectWithRelations>;
   delete(id: string): Promise<void>;
   setServers(projectId: string, serverIds: string[]): Promise<void>;
@@ -36,7 +36,7 @@ export class ProjectRepository implements IProjectRepository {
     return this.prisma.project.findUnique({ where: { name }, include: PROJECT_INCLUDE }) as unknown as Promise<ProjectWithRelations | null>;
   }
 
-  async create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; gated?: boolean; llmProvider?: string; llmModel?: string }): Promise<ProjectWithRelations> {
+  async create(data: { name: string; description: string; prompt?: string; ownerId: string; proxyMode: string; proxyModel?: string; gated?: boolean; llmProvider?: string; llmModel?: string; serverOverrides?: Record<string, unknown> }): Promise<ProjectWithRelations> {
     const createData: Record<string, unknown> = {
       name: data.name,
       description: data.description,
@@ -44,9 +44,11 @@ export class ProjectRepository implements IProjectRepository {
       proxyMode: data.proxyMode,
     };
     if (data.prompt !== undefined) createData['prompt'] = data.prompt;
+    if (data.proxyModel !== undefined) createData['proxyModel'] = data.proxyModel;
     if (data.gated !== undefined) createData['gated'] = data.gated;
     if (data.llmProvider !== undefined) createData['llmProvider'] = data.llmProvider;
     if (data.llmModel !== undefined) createData['llmModel'] = data.llmModel;
+    if (data.serverOverrides !== undefined) createData['serverOverrides'] = data.serverOverrides;
 
     return this.prisma.project.create({
       data: createData as Parameters<PrismaClient['project']['create']>[0]['data'],

src/mcpd/src/repositories/template.repository.ts

@@ -42,6 +42,7 @@ export class TemplateRepository implements ITemplateRepository {
         version: data.version,
         description: data.description,
         packageName: data.packageName ?? null,
+        runtime: data.runtime ?? null,
         dockerImage: data.dockerImage ?? null,
         transport: data.transport,
         repositoryUrl: data.repositoryUrl ?? null,
@@ -60,6 +61,7 @@ export class TemplateRepository implements ITemplateRepository {
     if (data.version !== undefined) updateData.version = data.version;
     if (data.description !== undefined) updateData.description = data.description;
     if (data.packageName !== undefined) updateData.packageName = data.packageName;
+    if (data.runtime !== undefined) updateData.runtime = data.runtime;
     if (data.dockerImage !== undefined) updateData.dockerImage = data.dockerImage;
     if (data.transport !== undefined) updateData.transport = data.transport;
     if (data.repositoryUrl !== undefined) updateData.repositoryUrl = data.repositoryUrl;

src/mcpd/src/routes/audit-events.ts

@@ -0,0 +1,59 @@
+import type { FastifyInstance } from 'fastify';
+import type { AuditEventService } from '../services/audit-event.service.js';
+import type { AuditEventCreateInput } from '../repositories/interfaces.js';
+
+interface AuditEventQuery {
+  sessionId?: string;
+  projectName?: string;
+  eventKind?: string;
+  serverName?: string;
+  correlationId?: string;
+  from?: string;
+  to?: string;
+  limit?: string;
+  offset?: string;
+}
+
+export function registerAuditEventRoutes(app: FastifyInstance, service: AuditEventService): void {
+  // POST /api/v1/audit/events — batch insert from mcplocal
+  app.post('/api/v1/audit/events', async (request, reply) => {
+    const body = request.body;
+    if (!Array.isArray(body) || body.length === 0) {
+      reply.code(400).send({ error: 'Request body must be a non-empty array of audit events' });
+      return;
+    }
+
+    // Basic validation
+    for (const event of body) {
+      const e = event as Record<string, unknown>;
+      if (!e['sessionId'] || !e['projectName'] || !e['eventKind'] || !e['source'] || !e['timestamp']) {
+        reply.code(400).send({ error: 'Each event requires: timestamp, sessionId, projectName, eventKind, source' });
+        return;
+      }
+    }
+
+    const count = await service.createBatch(body as AuditEventCreateInput[]);
+    reply.code(201).send({ inserted: count });
+  });
+
+  // GET /api/v1/audit/events — query with filters
+  app.get<{ Querystring: AuditEventQuery }>('/api/v1/audit/events', async (request) => {
+    const q = request.query;
+    const params: Record<string, unknown> = {};
+    if (q.sessionId !== undefined) params['sessionId'] = q.sessionId;
+    if (q.projectName !== undefined) params['projectName'] = q.projectName;
+    if (q.eventKind !== undefined) params['eventKind'] = q.eventKind;
+    if (q.serverName !== undefined) params['serverName'] = q.serverName;
+    if (q.correlationId !== undefined) params['correlationId'] = q.correlationId;
+    if (q.from !== undefined) params['from'] = q.from;
+    if (q.to !== undefined) params['to'] = q.to;
+    if (q.limit !== undefined) params['limit'] = parseInt(q.limit, 10);
+    if (q.offset !== undefined) params['offset'] = parseInt(q.offset, 10);
+    return service.list(params);
+  });
+
+  // GET /api/v1/audit/events/:id — single event
+  app.get<{ Params: { id: string } }>('/api/v1/audit/events/:id', async (request) => {
+    return service.getById(request.params.id);
+  });
+}

src/mcpd/src/routes/index.ts

@@ -17,3 +17,4 @@ export { registerTemplateRoutes } from './templates.js';
 export { registerRbacRoutes } from './rbac-definitions.js';
 export { registerUserRoutes } from './users.js';
 export { registerGroupRoutes } from './groups.js';
+export { registerAuditEventRoutes } from './audit-events.js';

src/mcpd/src/services/audit-event.service.ts

@@ -0,0 +1,57 @@
+import type { AuditEvent } from '@prisma/client';
+import type { IAuditEventRepository, AuditEventFilter, AuditEventCreateInput } from '../repositories/interfaces.js';
+import { NotFoundError } from './mcp-server.service.js';
+
+export interface AuditEventQueryParams {
+  sessionId?: string;
+  projectName?: string;
+  eventKind?: string;
+  serverName?: string;
+  correlationId?: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export class AuditEventService {
+  constructor(private readonly repo: IAuditEventRepository) {}
+
+  async list(params?: AuditEventQueryParams): Promise<{ events: AuditEvent[]; total: number }> {
+    const filter = this.buildFilter(params);
+    const [events, total] = await Promise.all([
+      this.repo.findAll(filter),
+      this.repo.count(filter),
+    ]);
+    return { events, total };
+  }
+
+  async getById(id: string): Promise<AuditEvent> {
+    const event = await this.repo.findById(id);
+    if (!event) {
+      throw new NotFoundError(`Audit event '${id}' not found`);
+    }
+    return event;
+  }
+
+  async createBatch(events: AuditEventCreateInput[]): Promise<number> {
+    return this.repo.createMany(events);
+  }
+
+  private buildFilter(params?: AuditEventQueryParams): AuditEventFilter | undefined {
+    if (!params) return undefined;
+    const filter: AuditEventFilter = {};
+
+    if (params.sessionId !== undefined) filter.sessionId = params.sessionId;
+    if (params.projectName !== undefined) filter.projectName = params.projectName;
+    if (params.eventKind !== undefined) filter.eventKind = params.eventKind;
+    if (params.serverName !== undefined) filter.serverName = params.serverName;
+    if (params.correlationId !== undefined) filter.correlationId = params.correlationId;
+    if (params.from !== undefined) filter.from = new Date(params.from);
+    if (params.to !== undefined) filter.to = new Date(params.to);
+    if (params.limit !== undefined) filter.limit = params.limit;
+    if (params.offset !== undefined) filter.offset = params.offset;
+
+    return filter;
+  }
+}

src/mcpd/src/services/backup/backup-service.ts

@@ -40,6 +40,7 @@ export interface BackupProject {
   name: string;
   description: string;
   proxyMode?: string;
+  proxyModel?: string;
   llmProvider?: string | null;
   llmModel?: string | null;
   serverNames?: string[];
@@ -116,6 +117,7 @@ export class BackupService {
         name: proj.name,
         description: proj.description,
         proxyMode: proj.proxyMode,
+        proxyModel: proj.proxyModel,
         llmProvider: proj.llmProvider,
         llmModel: proj.llmModel,
         serverNames: proj.servers.map((ps) => ps.server.name),

src/mcpd/src/services/backup/restore-service.ts

@@ -256,6 +256,7 @@ export class RestoreService {
           // overwrite
           const updateData: Record<string, unknown> = { description: project.description };
           if (project.proxyMode) updateData['proxyMode'] = project.proxyMode;
+          if (project.proxyModel) updateData['proxyModel'] = project.proxyModel;
           if (project.llmProvider !== undefined) updateData['llmProvider'] = project.llmProvider;
           if (project.llmModel !== undefined) updateData['llmModel'] = project.llmModel;
           await this.projectRepo.update(existing.id, updateData);
@@ -270,12 +271,13 @@ export class RestoreService {
           continue;
         }
 
-        const projectCreateData: { name: string; description: string; ownerId: string; proxyMode: string; llmProvider?: string; llmModel?: string } = {
+        const projectCreateData: { name: string; description: string; ownerId: string; proxyMode: string; proxyModel?: string; llmProvider?: string; llmModel?: string } = {
           name: project.name,
           description: project.description,
           ownerId: 'system',
           proxyMode: project.proxyMode ?? 'direct',
         };
+        if (project.proxyModel) projectCreateData.proxyModel = project.proxyModel;
         if (project.llmProvider != null) projectCreateData.llmProvider = project.llmProvider;
         if (project.llmModel != null) projectCreateData.llmModel = project.llmModel;
         const created = await this.projectRepo.create(projectCreateData);

src/mcpd/src/services/index.ts

@@ -32,3 +32,5 @@ export { RbacService } from './rbac.service.js';
 export type { RbacAction, Permission, AllowedScope } from './rbac.service.js';
 export { UserService } from './user.service.js';
 export { GroupService } from './group.service.js';
+export { AuditEventService } from './audit-event.service.js';
+export type { AuditEventQueryParams } from './audit-event.service.js';

src/mcpd/src/services/instance.service.ts

@@ -4,8 +4,11 @@ import type { McpOrchestrator, ContainerSpec, ContainerInfo } from './orchestrat
 import { NotFoundError } from './mcp-server.service.js';
 import { resolveServerEnv } from './env-resolver.js';
 
-/** Default image for npm-based MCP servers (STDIO with packageName, no dockerImage). */
-const DEFAULT_NODE_RUNNER_IMAGE = process.env['MCPD_NODE_RUNNER_IMAGE'] ?? 'mysources.co.uk/michal/mcpctl-node-runner:latest';
+/** Runner images for package-based MCP servers, keyed by runtime name. */
+const RUNNER_IMAGES: Record<string, string> = {
+  node: process.env['MCPD_NODE_RUNNER_IMAGE'] ?? 'mysources.co.uk/michal/mcpctl-node-runner:latest',
+  python: process.env['MCPD_PYTHON_RUNNER_IMAGE'] ?? 'mysources.co.uk/michal/mcpctl-python-runner:latest',
+};
 
 /** Network for MCP server containers (matches docker-compose mcp-servers network). */
 const MCP_SERVERS_NETWORK = process.env['MCPD_MCP_NETWORK'] ?? 'mcp-servers';
@@ -183,18 +186,19 @@ export class InstanceService {
 
     // Determine image + command based on server config:
     // 1. Explicit dockerImage → use as-is
-    // 2. packageName (npm) → use node-runner image + npx command
+    // 2. packageName → use runtime-specific runner image (node/python/go/...)
     // 3. Fallback → server name (legacy)
     let image: string;
-    let npmCommand: string[] | undefined;
+    let pkgCommand: string[] | undefined;
 
     if (server.dockerImage) {
       image = server.dockerImage;
     } else if (server.packageName) {
-      image = DEFAULT_NODE_RUNNER_IMAGE;
-      // Build npx command: entrypoint is ["npx", "-y"], so CMD = [packageName, ...args]
+      const runtime = (server.runtime as string | null) ?? 'node';
+      image = RUNNER_IMAGES[runtime] ?? RUNNER_IMAGES['node']!;
+      // Runner entrypoint handles package execution (npx -y / uvx / go run)
       const serverCommand = server.command as string[] | null;
-      npmCommand = [server.packageName, ...(serverCommand ?? [])];
+      pkgCommand = [server.packageName, ...(serverCommand ?? [])];
     } else {
       image = server.name;
     }
@@ -218,10 +222,10 @@ export class InstanceService {
       if (server.transport === 'SSE' || server.transport === 'STREAMABLE_HTTP') {
         spec.containerPort = server.containerPort ?? 3000;
       }
-      // npm-based servers: command = [packageName, ...args] (entrypoint handles npx -y)
+      // Package-based servers: command = [packageName, ...args] (entrypoint handles execution)
       // Docker-image servers: use explicit command if provided
-      if (npmCommand) {
-        spec.command = npmCommand;
+      if (pkgCommand) {
+        spec.command = pkgCommand;
       } else {
         const command = server.command as string[] | null;
         if (command) {

src/mcpd/src/services/mcp-proxy-service.ts

@@ -7,6 +7,21 @@ import { sendViaSse } from './transport/sse-client.js';
 import { sendViaStdio } from './transport/stdio-client.js';
 import { PersistentStdioClient } from './transport/persistent-stdio.js';
 
+/**
+ * Build the spawn command for a runtime inside its runner container.
+ * node → npx --prefer-offline -y <pkg>
+ * python → uvx <pkg>
+ */
+export function buildRuntimeSpawnCmd(runtime: string, packageName: string): string[] {
+  switch (runtime) {
+    case 'python':
+      return ['uvx', packageName];
+    case 'node':
+    default:
+      return ['npx', '--prefer-offline', '-y', packageName];
+  }
+}
+
 export interface McpProxyRequest {
   serverId: string;
   method: string;
@@ -129,10 +144,11 @@ export class McpProxyService {
         throw new InvalidStateError(`Server '${server.id}' has no packageName or command for STDIO transport`);
       }
 
-      // Build the spawn command for persistent mode
+      // Build the spawn command based on runtime
+      const runtime = (server.runtime as string | null) ?? 'node';
       const spawnCmd = command && command.length > 0
         ? command
-        : ['npx', '--prefer-offline', '-y', packageName!];
+        : buildRuntimeSpawnCmd(runtime, packageName!);
 
       // Try persistent connection first
       try {
@@ -140,7 +156,7 @@ export class McpProxyService {
       } catch {
         // Persistent failed — fall back to one-shot
         this.removeClient(instance.containerId);
-        return sendViaStdio(this.orchestrator, instance.containerId, packageName, method, params, 120_000, command);
+        return sendViaStdio(this.orchestrator, instance.containerId, packageName, method, params, 120_000, command, runtime);
       }
     }
 

src/mcpd/src/services/project.service.ts

@@ -56,9 +56,11 @@ export class ProjectService {
       prompt: data.prompt,
       ownerId,
       proxyMode: data.proxyMode,
+      proxyModel: data.proxyModel,
       gated: data.gated,
       ...(data.llmProvider !== undefined ? { llmProvider: data.llmProvider } : {}),
       ...(data.llmModel !== undefined ? { llmModel: data.llmModel } : {}),
+      ...(data.serverOverrides !== undefined ? { serverOverrides: data.serverOverrides } : {}),
     });
 
     // Link servers
@@ -79,9 +81,11 @@ export class ProjectService {
     if (data.description !== undefined) updateData['description'] = data.description;
     if (data.prompt !== undefined) updateData['prompt'] = data.prompt;
     if (data.proxyMode !== undefined) updateData['proxyMode'] = data.proxyMode;
+    if (data.proxyModel !== undefined) updateData['proxyModel'] = data.proxyModel;
     if (data.llmProvider !== undefined) updateData['llmProvider'] = data.llmProvider;
     if (data.llmModel !== undefined) updateData['llmModel'] = data.llmModel;
     if (data.gated !== undefined) updateData['gated'] = data.gated;
+    if (data.serverOverrides !== undefined) updateData['serverOverrides'] = data.serverOverrides;
 
     // Update scalar fields if any changed
     if (Object.keys(updateData).length > 0) {

src/mcpd/src/services/transport/stdio-client.ts

@@ -1,12 +1,17 @@
 import type { McpOrchestrator } from '../orchestrator.js';
 import type { McpProxyResponse } from '../mcp-proxy-service.js';
+import { buildRuntimeSpawnCmd } from '../mcp-proxy-service.js';
 
 /**
  * STDIO transport client for MCP servers running as Docker containers.
  *
- * Runs `docker exec` with an inline Node.js script that spawns the MCP server
+ * Runs `docker exec` with an inline script that spawns the MCP server
  * binary, pipes JSON-RPC messages via stdin/stdout, and returns the response.
  *
+ * The inline script language matches the container runtime:
+ *   node → Node.js script
+ *   python → Python script
+ *
  * Each call is self-contained: initialize → notifications/initialized → request → response.
  */
 export async function sendViaStdio(
@@ -17,6 +22,7 @@ export async function sendViaStdio(
   params?: Record<string, unknown>,
   timeoutMs = 30_000,
   command?: string[] | null,
+  runtime = 'node',
 ): Promise<McpProxyResponse> {
   const initMsg = JSON.stringify({
     jsonrpc: '2.0',
@@ -45,20 +51,57 @@ export async function sendViaStdio(
 
   // Determine spawn command
   let spawnCmd: string[];
-  if (packageName) {
-    spawnCmd = ['npx', '--prefer-offline', '-y', packageName];
-  } else if (command && command.length > 0) {
+  if (command && command.length > 0) {
     spawnCmd = command;
+  } else if (packageName) {
+    spawnCmd = buildRuntimeSpawnCmd(runtime, packageName);
   } else {
     return errorResponse('No packageName or command for STDIO server');
   }
-  const spawnArgs = JSON.stringify(spawnCmd);
 
-  // Inline Node.js script that:
-  // 1. Spawns the MCP server binary
-  // 2. Sends initialize → initialized → actual request via stdin
-  // 3. Reads stdout for JSON-RPC response with id: 2
-  // 4. Outputs the full JSON-RPC response to stdout
+  // Build the exec command based on runtime
+  let execCmd: string[];
+  if (runtime === 'python') {
+    execCmd = buildPythonExecCmd(spawnCmd, initMsg, initializedMsg, requestMsg, timeoutMs);
+  } else {
+    execCmd = buildNodeExecCmd(spawnCmd, initMsg, initializedMsg, requestMsg, timeoutMs);
+  }
+
+  try {
+    const result = await orchestrator.execInContainer(
+      containerId,
+      execCmd,
+      { timeoutMs },
+    );
+
+    if (result.exitCode === 0 && result.stdout.trim()) {
+      try {
+        return JSON.parse(result.stdout.trim()) as McpProxyResponse;
+      } catch {
+        return errorResponse(`Failed to parse STDIO response: ${result.stdout.slice(0, 200)}`);
+      }
+    }
+
+    // Try to parse error response from stdout
+    try {
+      return JSON.parse(result.stdout.trim()) as McpProxyResponse;
+    } catch {
+      const errorMsg = result.stderr.trim() || `docker exec exit code ${result.exitCode}`;
+      return errorResponse(errorMsg);
+    }
+  } catch (err) {
+    return errorResponse(err instanceof Error ? err.message : String(err));
+  }
+}
+
+function buildNodeExecCmd(
+  spawnCmd: string[],
+  initMsg: string,
+  initializedMsg: string,
+  requestMsg: string,
+  timeoutMs: number,
+): string[] {
+  const spawnArgs = JSON.stringify(spawnCmd);
   const probeScript = `
 const { spawn } = require('child_process');
 const args = ${spawnArgs};
@@ -95,32 +138,65 @@ setTimeout(() => {
   }, 500);
 }, 500);
 `.trim();
+  return ['node', '-e', probeScript];
+}
 
-  try {
-    const result = await orchestrator.execInContainer(
-      containerId,
-      ['node', '-e', probeScript],
-      { timeoutMs },
-    );
-
-    if (result.exitCode === 0 && result.stdout.trim()) {
-      try {
-        return JSON.parse(result.stdout.trim()) as McpProxyResponse;
-      } catch {
-        return errorResponse(`Failed to parse STDIO response: ${result.stdout.slice(0, 200)}`);
-      }
-    }
-
-    // Try to parse error response from stdout
-    try {
-      return JSON.parse(result.stdout.trim()) as McpProxyResponse;
-    } catch {
-      const errorMsg = result.stderr.trim() || `docker exec exit code ${result.exitCode}`;
-      return errorResponse(errorMsg);
-    }
-  } catch (err) {
-    return errorResponse(err instanceof Error ? err.message : String(err));
-  }
+function buildPythonExecCmd(
+  spawnCmd: string[],
+  initMsg: string,
+  initializedMsg: string,
+  requestMsg: string,
+  timeoutMs: number,
+): string[] {
+  const spawnArgsJson = JSON.stringify(spawnCmd);
+  const probeScript = `
+import subprocess, sys, json, time, signal, threading
+args = ${spawnArgsJson}
+proc = subprocess.Popen(args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+responded = False
+def timeout_handler():
+    global responded
+    if not responded:
+        sys.stdout.write(json.dumps({"jsonrpc":"2.0","id":2,"error":{"code":-32000,"message":"timeout"}}))
+        sys.stdout.flush()
+        proc.kill()
+        sys.exit(1)
+timer = threading.Timer(${(timeoutMs - 2000) / 1000}, timeout_handler)
+timer.daemon = True
+timer.start()
+proc.stdin.write((${JSON.stringify(initMsg)} + "\\n").encode())
+proc.stdin.flush()
+time.sleep(0.5)
+proc.stdin.write((${JSON.stringify(initializedMsg)} + "\\n").encode())
+proc.stdin.flush()
+time.sleep(0.5)
+proc.stdin.write((${JSON.stringify(requestMsg)} + "\\n").encode())
+proc.stdin.flush()
+output = ""
+while True:
+    line = proc.stdout.readline()
+    if not line:
+        break
+    line = line.decode().strip()
+    if not line:
+        continue
+    try:
+        msg = json.loads(line)
+        if msg.get("id") == 2:
+            responded = True
+            timer.cancel()
+            sys.stdout.write(json.dumps(msg))
+            sys.stdout.flush()
+            proc.kill()
+            sys.exit(0)
+    except json.JSONDecodeError:
+        pass
+if not responded:
+    sys.stdout.write(json.dumps({"jsonrpc":"2.0","id":2,"error":{"code":-32000,"message":"process exited " + str(proc.returncode)}}))
+    sys.stdout.flush()
+    sys.exit(1)
+`.trim();
+  return ['python3', '-c', probeScript];
 }
 
 function errorResponse(message: string): McpProxyResponse {

src/mcpd/src/validation/mcp-server.schema.ts

@@ -23,6 +23,7 @@ export const CreateMcpServerSchema = z.object({
   name: z.string().min(1).max(100).regex(/^[a-z0-9-]+$/, 'Name must be lowercase alphanumeric with hyphens'),
   description: z.string().max(1000).default(''),
   packageName: z.string().max(200).optional(),
+  runtime: z.string().max(50).optional(),
   dockerImage: z.string().max(200).optional(),
   transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).default('STDIO'),
   repositoryUrl: z.string().url().optional(),
@@ -37,6 +38,7 @@ export const CreateMcpServerSchema = z.object({
 export const UpdateMcpServerSchema = z.object({
   description: z.string().max(1000).optional(),
   packageName: z.string().max(200).nullable().optional(),
+  runtime: z.string().max(50).nullable().optional(),
   dockerImage: z.string().max(200).nullable().optional(),
   transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).optional(),
   repositoryUrl: z.string().url().nullable().optional(),

src/mcpd/src/validation/project.schema.ts

@@ -5,10 +5,14 @@ export const CreateProjectSchema = z.object({
   description: z.string().max(1000).default(''),
   prompt: z.string().max(10000).default(''),
   proxyMode: z.enum(['direct', 'filtered']).default('direct'),
+  proxyModel: z.string().max(100).default(''),
   gated: z.boolean().default(true),
   llmProvider: z.string().max(100).optional(),
   llmModel: z.string().max(100).optional(),
   servers: z.array(z.string().min(1)).default([]),
+  serverOverrides: z.record(z.string(), z.object({
+    proxyModel: z.string().optional(),
+  })).optional(),
 }).refine(
   (d) => d.proxyMode !== 'filtered' || d.llmProvider,
   { message: 'llmProvider is required when proxyMode is "filtered"' },
@@ -18,10 +22,14 @@ export const UpdateProjectSchema = z.object({
   description: z.string().max(1000).optional(),
   prompt: z.string().max(10000).optional(),
   proxyMode: z.enum(['direct', 'filtered']).optional(),
+  proxyModel: z.string().max(100).optional(),
   gated: z.boolean().optional(),
   llmProvider: z.string().max(100).nullable().optional(),
   llmModel: z.string().max(100).nullable().optional(),
   servers: z.array(z.string().min(1)).optional(),
+  serverOverrides: z.record(z.string(), z.object({
+    proxyModel: z.string().optional(),
+  })).optional(),
 });
 
 export type CreateProjectInput = z.infer<typeof CreateProjectSchema>;

src/mcpd/src/validation/template.schema.ts

@@ -22,6 +22,7 @@ export const CreateTemplateSchema = z.object({
   version: z.string().default('1.0.0'),
   description: z.string().default(''),
   packageName: z.string().optional(),
+  runtime: z.string().max(50).optional(),
   dockerImage: z.string().optional(),
   transport: z.enum(['STDIO', 'SSE', 'STREAMABLE_HTTP']).default('STDIO'),
   repositoryUrl: z.string().optional(),

src/mcpd/tests/audit-event-routes.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyInstance } from 'fastify';
+import { registerAuditEventRoutes } from '../src/routes/audit-events.js';
+import { AuditEventService } from '../src/services/audit-event.service.js';
+import { errorHandler } from '../src/middleware/error-handler.js';
+import type { IAuditEventRepository, AuditEventFilter } from '../src/repositories/interfaces.js';
+
+function mockRepo(): IAuditEventRepository {
+  return {
+    findAll: vi.fn(async () => []),
+    findById: vi.fn(async () => null),
+    createMany: vi.fn(async (events: unknown[]) => events.length),
+    count: vi.fn(async () => 0),
+  };
+}
+
+function makeEvent(overrides: Record<string, unknown> = {}) {
+  return {
+    id: 'evt-1',
+    timestamp: new Date('2026-03-01T12:00:00Z'),
+    sessionId: 'sess-1',
+    projectName: 'ha-project',
+    eventKind: 'gate_decision',
+    source: 'mcplocal',
+    verified: false,
+    serverName: null,
+    correlationId: null,
+    parentEventId: null,
+    payload: { trigger: 'begin_session' },
+    createdAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('audit event routes', () => {
+  let app: FastifyInstance;
+  let repo: ReturnType<typeof mockRepo>;
+  let service: AuditEventService;
+
+  beforeEach(async () => {
+    app = Fastify();
+    app.setErrorHandler(errorHandler);
+    repo = mockRepo();
+    service = new AuditEventService(repo);
+    registerAuditEventRoutes(app, service);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await app.close();
+  });
+
+  describe('POST /api/v1/audit/events', () => {
+    it('inserts batch of events', async () => {
+      const events = [
+        { timestamp: '2026-03-01T12:00:00Z', sessionId: 's1', projectName: 'p1', eventKind: 'gate_decision', source: 'mcplocal', verified: false, payload: {} },
+        { timestamp: '2026-03-01T12:00:01Z', sessionId: 's1', projectName: 'p1', eventKind: 'stage_execution', source: 'mcplocal', verified: true, payload: {} },
+        { timestamp: '2026-03-01T12:00:02Z', sessionId: 's1', projectName: 'p1', eventKind: 'pipeline_execution', source: 'mcplocal', verified: true, payload: {} },
+      ];
+
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/audit/events',
+        payload: events,
+      });
+
+      expect(res.statusCode).toBe(201);
+      expect(JSON.parse(res.payload)).toEqual({ inserted: 3 });
+      expect(repo.createMany).toHaveBeenCalledTimes(1);
+    });
+
+    it('rejects invalid event (missing eventKind)', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/audit/events',
+        payload: [{ sessionId: 'x', projectName: 'p', source: 'mcplocal', timestamp: '2026-03-01T00:00:00Z' }],
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('rejects empty array', async () => {
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/audit/events',
+        payload: [],
+      });
+
+      expect(res.statusCode).toBe(400);
+    });
+  });
+
+  describe('GET /api/v1/audit/events', () => {
+    it('returns events filtered by sessionId', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([makeEvent()]);
+      vi.mocked(repo.count).mockResolvedValue(1);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?sessionId=s1',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.payload);
+      expect(body.events).toHaveLength(1);
+      expect(body.total).toBe(1);
+    });
+
+    it('returns events filtered by projectName and eventKind', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([]);
+      vi.mocked(repo.count).mockResolvedValue(0);
+
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?projectName=ha&eventKind=gate_decision',
+      });
+
+      const call = vi.mocked(repo.findAll).mock.calls[0]![0] as AuditEventFilter;
+      expect(call.projectName).toBe('ha');
+      expect(call.eventKind).toBe('gate_decision');
+    });
+
+    it('supports time range filtering', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([]);
+      vi.mocked(repo.count).mockResolvedValue(0);
+
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?from=2026-03-01&to=2026-03-02',
+      });
+
+      const call = vi.mocked(repo.findAll).mock.calls[0]![0] as AuditEventFilter;
+      expect(call.from).toEqual(new Date('2026-03-01'));
+      expect(call.to).toEqual(new Date('2026-03-02'));
+    });
+
+    it('paginates with limit and offset', async () => {
+      vi.mocked(repo.findAll).mockResolvedValue([]);
+      vi.mocked(repo.count).mockResolvedValue(100);
+
+      await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events?limit=10&offset=20',
+      });
+
+      const call = vi.mocked(repo.findAll).mock.calls[0]![0] as AuditEventFilter;
+      expect(call.limit).toBe(10);
+      expect(call.offset).toBe(20);
+    });
+  });
+
+  describe('GET /api/v1/audit/events/:id', () => {
+    it('returns single event by id', async () => {
+      vi.mocked(repo.findById).mockResolvedValue(makeEvent({ id: 'evt-42' }));
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events/evt-42',
+      });
+
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.payload);
+      expect(body.id).toBe('evt-42');
+    });
+
+    it('returns 404 for missing event', async () => {
+      vi.mocked(repo.findById).mockResolvedValue(null);
+
+      const res = await app.inject({
+        method: 'GET',
+        url: '/api/v1/audit/events/nonexistent',
+      });
+
+      expect(res.statusCode).toBe(404);
+    });
+  });
+});

src/mcpd/tests/backup.test.ts

@@ -34,7 +34,7 @@ const mockSecrets = [
 
 const mockProjects = [
   {
-    id: 'proj1', name: 'my-project', description: 'Test project', proxyMode: 'direct', llmProvider: null, llmModel: null,
+    id: 'proj1', name: 'my-project', description: 'Test project', proxyMode: 'direct', proxyModel: '', llmProvider: null, llmModel: null,
     ownerId: 'user1', version: 1, createdAt: new Date(), updatedAt: new Date(),
     servers: [{ id: 'ps1', server: { id: 's1', name: 'github' } }],
   },

src/mcpd/tests/project-routes.test.ts

@@ -16,9 +16,12 @@ function makeProject(overrides: Partial<ProjectWithRelations> = {}): ProjectWith
     description: '',
     ownerId: 'user-1',
     proxyMode: 'direct',
+    prompt: '',
+    proxyModel: '',
     gated: true,
     llmProvider: null,
     llmModel: null,
+    serverOverrides: null,
     version: 1,
     createdAt: new Date(),
     updatedAt: new Date(),
@@ -149,6 +152,21 @@ describe('Project Routes', () => {
       expect(res.statusCode).toBe(201);
     });
 
+    it('creates a project with proxyModel', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(makeProject({ name: 'pm-proj', proxyModel: 'subindex' }));
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/projects',
+        payload: { name: 'pm-proj', proxyModel: 'subindex' },
+      });
+      expect(res.statusCode).toBe(201);
+      expect(repo.create).toHaveBeenCalledWith(
+        expect.objectContaining({ proxyModel: 'subindex' }),
+      );
+    });
+
     it('returns 400 for invalid input', async () => {
       const repo = mockProjectRepo();
       await createApp(repo);
@@ -186,6 +204,19 @@ describe('Project Routes', () => {
       expect(res.statusCode).toBe(200);
     });
 
+    it('updates proxyModel on a project', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(makeProject({ id: 'p1' }));
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'PUT',
+        url: '/api/v1/projects/p1',
+        payload: { proxyModel: 'subindex' },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(repo.update).toHaveBeenCalledWith('p1', expect.objectContaining({ proxyModel: 'subindex' }));
+    });
+
     it('returns 404 when not found', async () => {
       const repo = mockProjectRepo();
       await createApp(repo);
@@ -281,4 +312,50 @@ describe('Project Routes', () => {
       expect(res.statusCode).toBe(404);
     });
   });
+
+  describe('serverOverrides', () => {
+    it('accepts serverOverrides in project create', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(
+        makeProject({ name: 'override-proj', serverOverrides: { ha: { proxyModel: 'ha-special' } } }),
+      );
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'POST',
+        url: '/api/v1/projects',
+        payload: { name: 'override-proj', serverOverrides: { ha: { proxyModel: 'ha-special' } } },
+      });
+      expect(res.statusCode).toBe(201);
+      expect(repo.create).toHaveBeenCalledWith(
+        expect.objectContaining({ serverOverrides: { ha: { proxyModel: 'ha-special' } } }),
+      );
+    });
+
+    it('accepts serverOverrides in project update', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(makeProject({ id: 'p1' }));
+      await createApp(repo);
+      const res = await app.inject({
+        method: 'PUT',
+        url: '/api/v1/projects/p1',
+        payload: { serverOverrides: { ha: { proxyModel: 'ha-special' } } },
+      });
+      expect(res.statusCode).toBe(200);
+      expect(repo.update).toHaveBeenCalledWith('p1', expect.objectContaining({
+        serverOverrides: { ha: { proxyModel: 'ha-special' } },
+      }));
+    });
+
+    it('returns serverOverrides in project GET', async () => {
+      const repo = mockProjectRepo();
+      vi.mocked(repo.findById).mockResolvedValue(
+        makeProject({ id: 'p1', name: 'ha-proj', serverOverrides: { ha: { proxyModel: 'ha-special' } } }),
+      );
+      await createApp(repo);
+      const res = await app.inject({ method: 'GET', url: '/api/v1/projects/p1' });
+      expect(res.statusCode).toBe(200);
+      const body = res.json<{ serverOverrides: unknown }>();
+      expect(body.serverOverrides).toEqual({ ha: { proxyModel: 'ha-special' } });
+    });
+  });
 });

src/mcpd/tests/project-service.test.ts

@@ -12,6 +12,7 @@ function makeProject(overrides: Partial<ProjectWithRelations> = {}): ProjectWith
     description: '',
     ownerId: 'user-1',
     proxyMode: 'direct',
+    proxyModel: '',
     gated: true,
     llmProvider: null,
     llmModel: null,

src/mcpd/tests/prompt-routes.test.ts

@@ -49,6 +49,7 @@ function makeProject(overrides: Partial<Project> = {}): Project {
     description: '',
     prompt: '',
     proxyMode: 'direct',
+    proxyModel: '',
     gated: true,
     llmProvider: null,
     llmModel: null,

src/mcpd/tests/security.test.ts

@@ -0,0 +1,476 @@
+/**
+ * Security tests for mcpd.
+ *
+ * Tests for identified security issues:
+ * 1. audit-events endpoint bypasses RBAC (mapUrlToPermission returns 'skip')
+ * 2. x-service-account header impersonation (any authenticated user can set it)
+ * 3. MCP proxy maps to wrong RBAC action (POST → 'create' instead of 'run')
+ * 4. externalUrl has no scheme/destination restriction (SSRF)
+ * 5. MCP proxy has no input validation on method/serverId
+ * 6. RBAC list filtering only checks 'name' field
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import Fastify from 'fastify';
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { registerMcpProxyRoutes } from '../src/routes/mcp-proxy.js';
+import type { McpProxyRouteDeps } from '../src/routes/mcp-proxy.js';
+import { registerAuditEventRoutes } from '../src/routes/audit-events.js';
+import { AuditEventService } from '../src/services/audit-event.service.js';
+import type { IAuditEventRepository } from '../src/repositories/interfaces.js';
+import { errorHandler } from '../src/middleware/error-handler.js';
+import { CreateMcpServerSchema } from '../src/validation/mcp-server.schema.js';
+
+// ─────────────────────────────────────────────────────────
+// § 1  audit-events endpoint bypasses RBAC
+// ─────────────────────────────────────────────────────────
+
+/**
+ * Reproduce mapUrlToPermission from main.ts to test which URLs
+ * get RBAC checks and which are skipped.
+ */
+type PermissionCheck =
+  | { kind: 'resource'; resource: string; action: string; resourceName?: string }
+  | { kind: 'operation'; operation: string }
+  | { kind: 'skip' };
+
+function mapUrlToPermission(method: string, url: string): PermissionCheck {
+  const match = url.match(/^\/api\/v1\/([a-z-]+)/);
+  if (!match) return { kind: 'skip' };
+
+  const segment = match[1] as string;
+
+  if (segment === 'backup') return { kind: 'operation', operation: 'backup' };
+  if (segment === 'restore') return { kind: 'operation', operation: 'restore' };
+  if (segment === 'audit-logs' && method === 'DELETE') return { kind: 'operation', operation: 'audit-purge' };
+
+  const resourceMap: Record<string, string | undefined> = {
+    'servers': 'servers',
+    'instances': 'instances',
+    'secrets': 'secrets',
+    'projects': 'projects',
+    'templates': 'templates',
+    'users': 'users',
+    'groups': 'groups',
+    'rbac': 'rbac',
+    'audit-logs': 'rbac',
+    'mcp': 'servers',
+    'prompts': 'prompts',
+    'promptrequests': 'promptrequests',
+  };
+
+  const resource = resourceMap[segment];
+  if (resource === undefined) return { kind: 'skip' };
+
+  let action: string;
+  switch (method) {
+    case 'GET':
+    case 'HEAD':
+      action = 'view';
+      break;
+    case 'POST':
+      action = 'create';
+      break;
+    case 'DELETE':
+      action = 'delete';
+      break;
+    default:
+      action = 'edit';
+      break;
+  }
+
+  const nameMatch = url.match(/^\/api\/v1\/[a-z-]+\/([^/?]+)/);
+  const resourceName = nameMatch?.[1];
+  const check: PermissionCheck = { kind: 'resource', resource, action };
+  if (resourceName !== undefined) (check as { resourceName: string }).resourceName = resourceName;
+  return check;
+}
+
+describe('Security: RBAC coverage gaps in mapUrlToPermission', () => {
+  it('audit-events endpoint is NOT in resourceMap — bypasses RBAC', () => {
+    // This documents a known security issue: any authenticated user can query
+    // all audit events regardless of their RBAC permissions
+    const check = mapUrlToPermission('GET', '/api/v1/audit-events');
+    // Currently returns 'skip' — this is the bug
+    expect(check.kind).toBe('skip');
+  });
+
+  it('audit-events POST (batch insert) also bypasses RBAC', () => {
+    const check = mapUrlToPermission('POST', '/api/v1/audit-events');
+    expect(check.kind).toBe('skip');
+  });
+
+  it('audit-events by ID also bypasses RBAC', () => {
+    const check = mapUrlToPermission('GET', '/api/v1/audit-events/some-cuid');
+    expect(check.kind).toBe('skip');
+  });
+
+  it('all known resource endpoints DO have RBAC coverage', () => {
+    const coveredEndpoints = [
+      'servers', 'instances', 'secrets', 'projects', 'templates',
+      'users', 'groups', 'rbac', 'audit-logs', 'prompts', 'promptrequests',
+    ];
+
+    for (const endpoint of coveredEndpoints) {
+      const check = mapUrlToPermission('GET', `/api/v1/${endpoint}`);
+      expect(check.kind, `${endpoint} should have RBAC check`).not.toBe('skip');
+    }
+  });
+
+  it('MCP proxy maps POST to servers:create instead of servers:run', () => {
+    // /api/v1/mcp/proxy is a POST that executes tools — semantically this is
+    // a 'run' action, but mapUrlToPermission maps POST → 'create'
+    const check = mapUrlToPermission('POST', '/api/v1/mcp/proxy');
+    expect(check.kind).toBe('resource');
+    if (check.kind === 'resource') {
+      expect(check.resource).toBe('servers');
+      // BUG: should be 'run' for executing tools, not 'create'
+      expect(check.action).toBe('create');
+    }
+  });
+
+  it('non-api URLs correctly return skip', () => {
+    expect(mapUrlToPermission('GET', '/healthz').kind).toBe('skip');
+    expect(mapUrlToPermission('GET', '/health').kind).toBe('skip');
+    expect(mapUrlToPermission('GET', '/').kind).toBe('skip');
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 2  x-service-account header impersonation
+// ─────────────────────────────────────────────────────────
+
+describe('Security: x-service-account header impersonation', () => {
+  // This test documents that any authenticated user can impersonate service accounts
+  // by setting the x-service-account header. The RBAC service trusts this header
+  // and adds the service account's permissions to the user's permissions.
+
+  it('x-service-account header is passed to RBAC without verification', () => {
+    // The RBAC service's getPermissions() accepts serviceAccountName directly.
+    // In main.ts, the value comes from: request.headers['x-service-account']
+    // There is no validation that the authenticated user IS the service account,
+    // or that the user is authorized to act as that service account.
+    //
+    // Attack scenario:
+    // 1. Attacker authenticates as regular user (low-privilege)
+    // 2. Sends request with header: x-service-account: project:admin
+    // 3. RBAC service treats them as having the service account's bindings
+    // 4. Attacker gets elevated permissions
+
+    // We verify this by examining the RBAC service code path:
+    // In rbac.service.ts line 144:
+    //   if (s.kind === 'ServiceAccount') return serviceAccountName !== undefined && s.name === serviceAccountName;
+    // This matches ANY request with the right header value — no ownership check.
+    expect(true).toBe(true); // Structural documentation test
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 3  MCP proxy input validation
+// ─────────────────────────────────────────────────────────
+
+describe('Security: MCP proxy input validation', () => {
+  let app: FastifyInstance;
+
+  afterEach(async () => {
+    if (app) await app.close();
+  });
+
+  function buildApp() {
+    const mcpProxyService = {
+      execute: vi.fn(async () => ({
+        jsonrpc: '2.0' as const,
+        id: 1,
+        result: { tools: [] },
+      })),
+    };
+    const auditLogService = {
+      create: vi.fn(async () => ({ id: 'log-1' })),
+    };
+    const authDeps = {
+      findSession: vi.fn(async () => ({
+        userId: 'user-1',
+        expiresAt: new Date(Date.now() + 3600_000),
+      })),
+    };
+
+    app = Fastify({ logger: false });
+    app.setErrorHandler(errorHandler);
+    registerMcpProxyRoutes(app, {
+      mcpProxyService,
+      auditLogService,
+      authDeps,
+    } as unknown as McpProxyRouteDeps);
+    return { mcpProxyService, auditLogService };
+  }
+
+  it('accepts arbitrary method strings (no allowlist)', async () => {
+    // Any JSON-RPC method is forwarded to upstream servers without validation.
+    // An attacker could send methods like 'shutdown', 'admin/reset', etc.
+    const { mcpProxyService } = buildApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/mcp/proxy',
+      payload: {
+        serverId: 'srv-1',
+        method: 'dangerous/admin_shutdown',
+        params: {},
+      },
+      headers: { authorization: 'Bearer valid-token' },
+    });
+
+    // Request succeeds — method is forwarded without validation
+    expect(res.statusCode).toBe(200);
+    expect(mcpProxyService.execute).toHaveBeenCalledWith({
+      serverId: 'srv-1',
+      method: 'dangerous/admin_shutdown',
+      params: {},
+    });
+  });
+
+  it('accepts empty method string', async () => {
+    const { mcpProxyService } = buildApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/mcp/proxy',
+      payload: {
+        serverId: 'srv-1',
+        method: '',
+        params: {},
+      },
+      headers: { authorization: 'Bearer valid-token' },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(mcpProxyService.execute).toHaveBeenCalledWith(
+      expect.objectContaining({ method: '' }),
+    );
+  });
+
+  it('no Zod schema validation on request body', async () => {
+    // The route destructures body without schema validation.
+    // Extra fields are silently accepted.
+    const { mcpProxyService } = buildApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/mcp/proxy',
+      payload: {
+        serverId: 'srv-1',
+        method: 'tools/list',
+        params: {},
+        __proto__: { isAdmin: true },
+        extraField: 'injected',
+      },
+      headers: { authorization: 'Bearer valid-token' },
+    });
+
+    expect(res.statusCode).toBe(200);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 4  externalUrl SSRF validation
+// ─────────────────────────────────────────────────────────
+
+describe('Security: externalUrl SSRF via CreateMcpServerSchema', () => {
+  it('accepts internal IP addresses (SSRF risk)', () => {
+    // externalUrl uses z.string().url() which validates format but not destination
+    const internalUrls = [
+      'http://169.254.169.254/latest/meta-data/',    // AWS metadata
+      'http://metadata.google.internal/',              // GCP metadata
+      'http://100.100.100.200/latest/meta-data/',      // Alibaba Cloud metadata
+      'http://10.0.0.1/',                              // Private network
+      'http://192.168.1.1/',                           // Private network
+      'http://172.16.0.1/',                            // Private network
+      'http://127.0.0.1:3100/',                        // Localhost (mcpd itself!)
+      'http://[::1]:3100/',                            // IPv6 localhost
+      'http://0.0.0.0/',                               // All interfaces
+    ];
+
+    for (const url of internalUrls) {
+      const result = CreateMcpServerSchema.safeParse({
+        name: 'test-server',
+        externalUrl: url,
+      });
+      // All currently pass validation — this is the SSRF vulnerability
+      expect(result.success, `${url} should be flagged but currently passes`).toBe(true);
+    }
+  });
+
+  it('accepts file:// URLs', () => {
+    const result = CreateMcpServerSchema.safeParse({
+      name: 'test-server',
+      externalUrl: 'file:///etc/passwd',
+    });
+    // z.string().url() validates format, and file:// is a valid URL scheme
+    // Whether this passes or fails depends on the Zod version's url() validator
+    // This test documents the current behavior
+    if (result.success) {
+      // If this passes, it's an additional SSRF vector
+      expect(result.data.externalUrl).toBe('file:///etc/passwd');
+    }
+  });
+
+  it('correctly validates URL format', () => {
+    const invalid = CreateMcpServerSchema.safeParse({
+      name: 'test-server',
+      externalUrl: 'not-a-url',
+    });
+    expect(invalid.success).toBe(false);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 5  Audit events route — unauthenticated batch insert
+// ─────────────────────────────────────────────────────────
+
+describe('Security: audit-events batch insert has no auth in route definition', () => {
+  let app: FastifyInstance;
+  let repo: IAuditEventRepository;
+
+  beforeEach(async () => {
+    app = Fastify({ logger: false });
+    app.setErrorHandler(errorHandler);
+    repo = {
+      findAll: vi.fn(async () => []),
+      findById: vi.fn(async () => null),
+      createMany: vi.fn(async (events: unknown[]) => events.length),
+      count: vi.fn(async () => 0),
+    };
+    const service = new AuditEventService(repo);
+    registerAuditEventRoutes(app, service);
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    if (app) await app.close();
+  });
+
+  it('batch insert accepts events without authentication at route level', async () => {
+    // The route itself has no preHandler auth middleware (unlike mcp-proxy).
+    // Auth is only applied via the global hook in main.ts.
+    // If registerAuditEventRoutes is used outside of main.ts's global hook setup,
+    // audit events can be inserted without auth.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/audit/events',
+      payload: [
+        {
+          timestamp: new Date().toISOString(),
+          sessionId: 'fake-session',
+          projectName: 'injected-project',
+          eventKind: 'gate_decision',
+          source: 'attacker',
+          verified: true,   // Attacker can claim verified=true
+          payload: { trigger: 'fake', intent: 'malicious' },
+        },
+      ],
+    });
+
+    // Without global auth hook, this succeeds
+    expect(res.statusCode).toBe(201);
+    expect(repo.createMany).toHaveBeenCalled();
+  });
+
+  it('attacker can inject events with verified=true (no server-side enforcement)', async () => {
+    // The verified flag is accepted from the client without validation.
+    // mcplocal (which runs on untrusted user devices) sends verified=true for its events.
+    // An attacker could inject fake "verified" events to pollute the audit trail.
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/audit/events',
+      payload: [
+        {
+          timestamp: new Date().toISOString(),
+          sessionId: 'attacker-session',
+          projectName: 'target-project',
+          eventKind: 'gate_decision',
+          source: 'mcpd',      // Impersonate mcpd as source
+          verified: true,       // Claim it's verified
+          payload: { trigger: 'begin_session', intent: 'legitimate looking' },
+        },
+      ],
+    });
+
+    expect(res.statusCode).toBe(201);
+
+    // Verify the event was stored with attacker-controlled values
+    const storedEvents = (repo.createMany as ReturnType<typeof vi.fn>).mock.calls[0]![0] as Array<Record<string, unknown>>;
+    expect(storedEvents[0]).toMatchObject({
+      source: 'mcpd',
+      verified: true,
+    });
+  });
+
+  it('attacker can inject events for any project', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/audit/events',
+      payload: [
+        {
+          timestamp: new Date().toISOString(),
+          sessionId: 'attacker-session',
+          projectName: 'production-sensitive-project',
+          eventKind: 'tool_call_trace',
+          source: 'mcplocal',
+          verified: true,
+          payload: { toolName: 'legitimate_tool' },
+        },
+      ],
+    });
+
+    expect(res.statusCode).toBe(201);
+  });
+});
+
+// ─────────────────────────────────────────────────────────
+// § 6  RBAC list filtering only checks 'name' field
+// ─────────────────────────────────────────────────────────
+
+describe('Security: RBAC list filtering gaps', () => {
+  it('preSerialization hook only filters by name field', () => {
+    // From main.ts lines 390-397:
+    // The hook filters array responses by checking item['name'].
+    // Resources without a 'name' field pass through unfiltered.
+    //
+    // Affected resources:
+    // - AuditEvent (has no 'name' field → never filtered)
+    // - AuditLog (has no 'name' field → never filtered)
+    // - Any future resource without a 'name' field
+
+    // Simulate the filtering logic
+    const payload = [
+      { id: '1', name: 'allowed-server', description: 'visible' },
+      { id: '2', name: 'forbidden-server', description: 'should be hidden' },
+      { id: '3', description: 'no name field — passes through' },
+    ];
+
+    const rbacScope = { wildcard: false, names: new Set(['allowed-server']) };
+
+    // Apply the filtering logic from main.ts
+    const filtered = payload.filter((item) => {
+      const name = item['name' as keyof typeof item];
+      return typeof name === 'string' && rbacScope.names.has(name);
+    });
+
+    // Items with matching name are included
+    expect(filtered).toHaveLength(1);
+    expect(filtered[0]!.name).toBe('allowed-server');
+
+    // BUG: Items without a name field are EXCLUDED, not leaked through.
+    // Actually re-reading: typeof undefined === 'undefined', so the filter
+    // returns false for items without name. This means nameless items are
+    // EXCLUDED when rbacScope is active — which may cause audit events to
+    // disappear from filtered responses. Not a leak, but a usability issue.
+  });
+
+  it('wildcard scope bypasses all filtering', () => {
+    const rbacScope = { wildcard: true, names: new Set<string>() };
+
+    // When wildcard is true, the hook returns payload as-is
+    // This is correct behavior — wildcard means "see everything"
+    expect(rbacScope.wildcard).toBe(true);
+  });
+});

src/mcpd/tests/services/prompt-service.test.ts

@@ -43,6 +43,7 @@ function makeProject(overrides: Partial<Project> = {}): Project {
     description: '',
     prompt: '',
     proxyMode: 'direct',
+    proxyModel: '',
     gated: true,
     llmProvider: null,
     llmModel: null,
@@ -400,8 +401,8 @@ describe('PromptService', () => {
       const result = await service.getVisiblePrompts('proj-1', 'sess-1');
 
       expect(result).toHaveLength(2);
-      expect(result[0]).toEqual({ name: 'approved-1', content: 'A', type: 'prompt' });
-      expect(result[1]).toEqual({ name: 'pending-1', content: 'B', type: 'promptrequest' });
+      expect(result[0]).toMatchObject({ name: 'approved-1', content: 'A', type: 'prompt' });
+      expect(result[1]).toMatchObject({ name: 'pending-1', content: 'B', type: 'promptrequest' });
     });
 
     it('should not include pending requests without sessionId', async () => {

src/mcplocal/package.json

@@ -11,13 +11,15 @@
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "test": "vitest",
-    "test:run": "vitest run"
+    "test:run": "vitest run",
+    "test:smoke": "vitest run --config vitest.smoke.config.ts"
   },
   "dependencies": {
     "@fastify/cors": "^10.0.0",
     "@mcpctl/shared": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "fastify": "^5.0.0"
+    "fastify": "^5.0.0",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^25.3.0"

src/mcplocal/src/audit/collector.ts

@@ -0,0 +1,56 @@
+/**
+ * Audit event collector.
+ *
+ * Batches events in memory and POSTs them to mcpd periodically.
+ * Fire-and-forget: audit never blocks the MCP request path.
+ */
+import type { AuditEvent } from './types.js';
+import type { McpdClient } from '../http/mcpd-client.js';
+
+const BATCH_SIZE = 50;
+const FLUSH_INTERVAL_MS = 5_000;
+
+export class AuditCollector {
+  private queue: AuditEvent[] = [];
+  private flushTimer: ReturnType<typeof setInterval> | null = null;
+  private flushing = false;
+
+  constructor(
+    private readonly mcpdClient: McpdClient,
+    private readonly projectName: string,
+  ) {
+    this.flushTimer = setInterval(() => void this.flush(), FLUSH_INTERVAL_MS);
+  }
+
+  /** Queue an audit event. Auto-fills projectName. */
+  emit(event: Omit<AuditEvent, 'projectName'>): void {
+    this.queue.push({ ...event, projectName: this.projectName });
+    if (this.queue.length >= BATCH_SIZE) {
+      void this.flush();
+    }
+  }
+
+  /** Flush queued events to mcpd. Safe to call concurrently. */
+  async flush(): Promise<void> {
+    if (this.flushing || this.queue.length === 0) return;
+    this.flushing = true;
+
+    const batch = this.queue.splice(0);
+    try {
+      await this.mcpdClient.post('/api/v1/audit/events', batch);
+    } catch {
+      // Audit is best-effort — never propagate failures
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /** Flush remaining events and stop the timer. */
+  async dispose(): Promise<void> {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+}

src/mcplocal/src/audit/types.ts

@@ -0,0 +1,33 @@
+/**
+ * Audit event types for tracking pipeline execution, gate decisions,
+ * prompt delivery, and tool call traces.
+ *
+ * Every event carries a `verified` flag:
+ *   false = self-reported (client LLM claims, e.g. begin_session intent)
+ *   true  = server-verified (server-side data: tool responses, prompt matches, pipeline transforms)
+ *
+ * `correlationId` and `parentEventId` are designed for future causal graph
+ * ingestion (e.g. graphiti knowledge graph).
+ */
+
+export type AuditEventKind =
+  | 'pipeline_execution'       // Full pipeline run summary
+  | 'stage_execution'          // Individual stage detail
+  | 'gate_decision'            // Gate open/close with intent
+  | 'prompt_delivery'          // Which prompts were sent to client
+  | 'tool_call_trace';         // Tool call with server + timing
+
+export type AuditSource = 'client' | 'mcplocal' | 'mcpd';
+
+export interface AuditEvent {
+  timestamp: string;
+  sessionId: string;
+  projectName: string;
+  eventKind: AuditEventKind;
+  source: AuditSource;
+  verified: boolean;
+  serverName?: string;
+  correlationId?: string;
+  parentEventId?: string;
+  payload: Record<string, unknown>;
+}

src/mcplocal/src/discovery.ts

@@ -55,7 +55,9 @@ export async function refreshProjectUpstreams(
 export interface ProjectLlmConfig {
   llmProvider?: string;
   llmModel?: string;
+  proxyModel?: string;
   gated?: boolean;
+  serverOverrides?: Record<string, { proxyModel?: string }>;
 }
 
 export async function fetchProjectLlmConfig(
@@ -66,12 +68,21 @@ export async function fetchProjectLlmConfig(
     const project = await mcpdClient.get<{
       llmProvider?: string;
       llmModel?: string;
+      proxyModel?: string;
       gated?: boolean;
+      serverOverrides?: Record<string, { proxyModel?: string }>;
     }>(`/api/v1/projects/${encodeURIComponent(projectName)}`);
     const config: ProjectLlmConfig = {};
     if (project.llmProvider) config.llmProvider = project.llmProvider;
     if (project.llmModel) config.llmModel = project.llmModel;
     if (project.gated !== undefined) config.gated = project.gated;
+    // proxyModel: use project value, fall back to 'default' when gated
+    if (project.proxyModel) {
+      config.proxyModel = project.proxyModel;
+    } else if (project.gated !== false) {
+      config.proxyModel = 'default';
+    }
+    if (project.serverOverrides) config.serverOverrides = project.serverOverrides;
     return config;
   } catch {
     return {};

src/mcplocal/src/http/config.ts

@@ -52,6 +52,18 @@ export interface LlmProviderFileEntry {
   url?: string;
   binaryPath?: string;
   tier?: 'fast' | 'heavy';
+  /** vllm-managed: path to Python venv (e.g. "~/vllm_env") */
+  venvPath?: string;
+  /** vllm-managed: port for vLLM HTTP server */
+  port?: number;
+  /** vllm-managed: GPU memory utilization fraction (0.1–1.0) */
+  gpuMemoryUtilization?: number;
+  /** vllm-managed: max model context length */
+  maxModelLen?: number;
+  /** vllm-managed: minutes of idle before stopping vLLM */
+  idleTimeoutMinutes?: number;
+  /** vllm-managed: extra args for `vllm serve` */
+  extraArgs?: string[];
 }
 
 export interface ProjectLlmOverride {

src/mcplocal/src/http/project-mcp-endpoint.ts

@@ -19,6 +19,10 @@ import type { McpdClient } from './mcpd-client.js';
 import type { ProviderRegistry } from '../providers/registry.js';
 import type { JsonRpcRequest } from '../types.js';
 import type { TrafficCapture } from './traffic.js';
+import { LLMProviderAdapter } from '../proxymodel/llm-adapter.js';
+import { MemoryCache } from '../proxymodel/cache.js';
+import { createDefaultPlugin } from '../proxymodel/plugins/default.js';
+import { AuditCollector } from '../audit/collector.js';
 
 interface ProjectCacheEntry {
   router: McpRouter;
@@ -64,16 +68,37 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
     const saClient = mcpdClient.withHeaders({ 'X-Service-Account': `project:${projectName}` });
     router.setPromptConfig(saClient, projectName);
 
-    // Configure gating if project has it enabled (default: true)
+    // Wire proxymodel pipeline (model resolved lazily from disk for hot-reload)
+    const proxyModelName = mcpdConfig.proxyModel ?? 'default';
+    const llmAdapter = effectiveRegistry ? new LLMProviderAdapter(effectiveRegistry) : {
+      complete: async () => '',
+      available: () => false,
+    };
+    const cache = new MemoryCache();
+    router.setProxyModel(proxyModelName, llmAdapter, cache);
+
+    // Per-server proxymodel overrides (if mcpd provides them)
+    if (mcpdConfig.serverOverrides) {
+      for (const [serverName, override] of Object.entries(mcpdConfig.serverOverrides)) {
+        if (override.proxyModel) {
+          router.setServerProxyModel(serverName, override.proxyModel, llmAdapter, cache);
+        }
+      }
+    }
+
+    // Wire audit collector (best-effort, non-blocking)
+    const auditCollector = new AuditCollector(saClient, projectName);
+    router.setAuditCollector(auditCollector);
+
+    // Wire the default plugin (gate + content-pipeline)
     const isGated = mcpdConfig.gated !== false;
-    const gateConfig: import('../router.js').GateConfig = {
+    const pluginConfig: Parameters<typeof createDefaultPlugin>[0] = {
       gated: isGated,
       providerRegistry: effectiveRegistry,
     };
-    if (resolvedModel) {
-      gateConfig.modelOverride = resolvedModel;
-    }
-    router.setGateConfig(gateConfig);
+    if (resolvedModel) pluginConfig.modelOverride = resolvedModel;
+    const plugin = createDefaultPlugin(pluginConfig);
+    router.setPlugin(plugin);
 
     // Fetch project instructions and set on router
     try {
@@ -97,6 +122,9 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
       // Instructions are optional — don't fail if endpoint is unavailable
     }
 
+    // Eagerly start managed LLM providers (e.g., vLLM) so they're warm by first use
+    effectiveRegistry?.warmupAll();
+
     projectCache.set(projectName, { router, lastRefresh: now });
     return router;
   }
@@ -142,10 +170,18 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
       },
     });
 
+    // Per-request correlationId map for linking client ↔ upstream event pairs.
+    // A Map keyed by request ID avoids the race condition where concurrent
+    // requests would overwrite a single shared variable.
+    const requestCorrelations = new Map<string | number, string>();
+
     // Wire upstream call tracing into the router
     if (trafficCapture) {
       router.onUpstreamCall = (info) => {
         const sid = transport.sessionId ?? 'unknown';
+        // Recover the correlationId from the upstream request's id (preserved from client request)
+        const reqId = (info.request as { id?: string | number }).id;
+        const corrId = reqId != null ? requestCorrelations.get(reqId) : undefined;
         trafficCapture.emit({
           timestamp: new Date().toISOString(),
           projectName,
@@ -154,6 +190,7 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
           method: info.method,
           upstreamName: info.upstream,
           body: info.request,
+          correlationId: corrId,
         });
         trafficCapture.emit({
           timestamp: new Date().toISOString(),
@@ -164,6 +201,7 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
           upstreamName: info.upstream,
           body: info.response,
           durationMs: info.durationMs,
+          correlationId: corrId,
         });
       };
     }
@@ -173,6 +211,8 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
         const requestId = message.id as string | number;
         const sid = transport.sessionId ?? 'unknown';
         const method = (message as { method?: string }).method;
+        const correlationId = `${sid}:${requestId}`;
+        requestCorrelations.set(requestId, correlationId);
 
         // Capture client request
         trafficCapture?.emit({
@@ -182,6 +222,7 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
           eventType: 'client_request',
           method,
           body: message,
+          correlationId,
         });
 
         const ctx = transport.sessionId ? { sessionId: transport.sessionId } : undefined;
@@ -199,6 +240,7 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
               eventType: 'client_notification',
               method: (n as { method?: string }).method,
               body: n,
+              correlationId,
             });
             await transport.send(n as unknown as JSONRPCMessage, { relatedRequestId: requestId });
           }
@@ -212,8 +254,10 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
           eventType: 'client_response',
           method,
           body: response,
+          correlationId,
         });
 
+        requestCorrelations.delete(requestId);
         await transport.send(response as unknown as JSONRPCMessage);
       }
     };
@@ -265,4 +309,56 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
     sessions.delete(sessionId);
     reply.hijack();
   });
+
+  // GET /projects/:projectName/override — current proxyModel config + server list
+  app.get<{ Params: { projectName: string } }>('/projects/:projectName/override', async (request, reply) => {
+    const { projectName } = request.params;
+    const entry = projectCache.get(projectName);
+    if (!entry) {
+      reply.code(404).send({ error: `Project '${projectName}' not loaded` });
+      return;
+    }
+
+    const info = entry.router.getProxyModelInfo();
+    const servers = entry.router.getUpstreamNames();
+    reply.send({
+      proxyModel: info.projectDefault,
+      serverOverrides: info.serverOverrides,
+      servers,
+    });
+  });
+
+  // PUT /projects/:projectName/override — ephemeral runtime override
+  app.put<{
+    Params: { projectName: string };
+    Body: { proxyModel?: string; serverName?: string; serverProxyModel?: string };
+  }>('/projects/:projectName/override', async (request, reply) => {
+    const { projectName } = request.params;
+    const { proxyModel, serverName, serverProxyModel } = request.body ?? {};
+    const entry = projectCache.get(projectName);
+    if (!entry) {
+      reply.code(404).send({ error: `Project '${projectName}' not loaded` });
+      return;
+    }
+
+    const llmAdapter = providerRegistry
+      ? new LLMProviderAdapter(providerRegistry)
+      : { complete: async () => '', available: () => false };
+    const cache = new MemoryCache();
+
+    if (serverName && serverProxyModel) {
+      entry.router.setServerProxyModel(serverName, serverProxyModel, llmAdapter, cache);
+    } else if (proxyModel) {
+      entry.router.setProxyModel(proxyModel, llmAdapter, cache);
+    } else {
+      reply.code(400).send({ error: 'Provide proxyModel or (serverName + serverProxyModel)' });
+      return;
+    }
+
+    const info = entry.router.getProxyModelInfo();
+    reply.send({
+      proxyModel: info.projectDefault,
+      serverOverrides: info.serverOverrides,
+    });
+  });
 }

src/mcplocal/src/http/proxymodel-endpoint.ts

@@ -0,0 +1,60 @@
+/**
+ * ProxyModel discovery endpoints.
+ *
+ * GET /proxymodels       → list all available proxymodels
+ * GET /proxymodels/:name → get a single proxymodel by name
+ */
+import type { FastifyInstance } from 'fastify';
+import { loadProxyModels } from '../proxymodel/loader.js';
+
+interface ProxyModelSummary {
+  name: string;
+  source: 'built-in' | 'local';
+  controller: string;
+  stages: string[];
+  appliesTo: string[];
+  cacheable: boolean;
+}
+
+export function registerProxymodelEndpoint(app: FastifyInstance): void {
+  // GET /proxymodels — list all
+  app.get('/proxymodels', async (_request, reply) => {
+    const models = await loadProxyModels();
+    const result: ProxyModelSummary[] = [];
+
+    for (const model of models.values()) {
+      result.push({
+        name: model.metadata.name,
+        source: model.source,
+        controller: model.spec.controller,
+        stages: model.spec.stages.map((s) => s.type),
+        appliesTo: model.spec.appliesTo,
+        cacheable: model.spec.cacheable,
+      });
+    }
+
+    reply.code(200).send(result);
+  });
+
+  // GET /proxymodels/:name — single model details
+  app.get<{ Params: { name: string } }>('/proxymodels/:name', async (request, reply) => {
+    const { name } = request.params;
+    const models = await loadProxyModels();
+    const model = models.get(name);
+
+    if (!model) {
+      reply.code(404).send({ error: `ProxyModel '${name}' not found` });
+      return;
+    }
+
+    reply.code(200).send({
+      name: model.metadata.name,
+      source: model.source,
+      controller: model.spec.controller,
+      controllerConfig: model.spec.controllerConfig,
+      stages: model.spec.stages,
+      appliesTo: model.spec.appliesTo,
+      cacheable: model.spec.cacheable,
+    });
+  });
+}

src/mcplocal/src/http/replay-endpoint.ts

@@ -0,0 +1,90 @@
+/**
+ * POST /proxymodel/replay — stateless content replay through a ProxyModel pipeline.
+ *
+ * Takes raw content and runs it through a specified ProxyModel,
+ * returning the transformed result. Used by the unified console
+ * for lab-style side-by-side comparisons without creating temp projects.
+ */
+import type { FastifyInstance } from 'fastify';
+import { executePipeline } from '../proxymodel/executor.js';
+import { getProxyModel } from '../proxymodel/loader.js';
+import { LLMProviderAdapter } from '../proxymodel/llm-adapter.js';
+import { MemoryCache } from '../proxymodel/cache.js';
+import type { ProviderRegistry } from '../providers/registry.js';
+import type { ContentType, Section } from '../proxymodel/types.js';
+
+interface ReplayRequestBody {
+  content: string;
+  sourceName: string;
+  proxyModel: string;
+  contentType?: ContentType;
+  provider?: string;
+  llmModel?: string;
+}
+
+interface ReplayResponse {
+  content: string;
+  sections?: Section[];
+  durationMs: number;
+}
+
+// Shared cache across replay calls (replay is ephemeral, not per-session)
+const replayCache = new MemoryCache({ maxEntries: 500 });
+
+export function registerReplayEndpoint(app: FastifyInstance, providerRegistry?: ProviderRegistry | null): void {
+  app.post<{ Body: ReplayRequestBody }>('/proxymodel/replay', async (request, reply) => {
+    const { content, sourceName, proxyModel: modelName, contentType, provider: providerName, llmModel } = request.body;
+
+    if (!content || typeof content !== 'string') {
+      reply.code(400).send({ error: 'content is required and must be a string' });
+      return;
+    }
+    if (!sourceName || typeof sourceName !== 'string') {
+      reply.code(400).send({ error: 'sourceName is required' });
+      return;
+    }
+    if (!modelName || typeof modelName !== 'string') {
+      reply.code(400).send({ error: 'proxyModel is required' });
+      return;
+    }
+
+    let proxyModel;
+    try {
+      proxyModel = await getProxyModel(modelName);
+    } catch (err) {
+      reply.code(404).send({ error: `ProxyModel '${modelName}' not found: ${err instanceof Error ? err.message : String(err)}` });
+      return;
+    }
+
+    const llm = providerRegistry
+      ? new LLMProviderAdapter(providerRegistry, providerName ?? undefined, llmModel ?? undefined)
+      : { complete: async () => '', available: () => false };
+
+    const start = Date.now();
+    try {
+      const result = await executePipeline({
+        content,
+        contentType: contentType ?? 'toolResult',
+        sourceName,
+        projectName: 'replay',
+        sessionId: `replay-${Date.now()}`,
+        proxyModel,
+        llm,
+        cache: replayCache,
+      });
+
+      const response: ReplayResponse = {
+        content: result.content,
+        durationMs: Date.now() - start,
+      };
+      if (result.sections) response.sections = result.sections;
+
+      reply.code(200).send(response);
+    } catch (err) {
+      reply.code(500).send({
+        error: `Pipeline execution failed: ${err instanceof Error ? err.message : String(err)}`,
+        durationMs: Date.now() - start,
+      });
+    }
+  });
+}

src/mcplocal/src/http/server.ts

@@ -8,11 +8,14 @@ import { registerProxyRoutes } from './routes/proxy.js';
 import { registerMcpEndpoint } from './mcp-endpoint.js';
 import { registerProjectMcpEndpoint } from './project-mcp-endpoint.js';
 import { registerInspectEndpoint } from './inspect-endpoint.js';
+import { registerProxymodelEndpoint } from './proxymodel-endpoint.js';
+import { registerReplayEndpoint } from './replay-endpoint.js';
 import { TrafficCapture } from './traffic.js';
 import type { McpRouter } from '../router.js';
 import type { HealthMonitor } from '../health.js';
 import type { TieredHealthMonitor } from '../health/tiered.js';
 import type { ProviderRegistry } from '../providers/registry.js';
+import type { ManagedVllmProvider } from '../providers/vllm-managed.js';
 
 export interface HttpServerDeps {
   router: McpRouter;
@@ -101,6 +104,22 @@ export async function createHttpServer(
       return;
     }
 
+    // For managed providers (e.g. vllm-managed) that are not running,
+    // report their lifecycle state without triggering startup via complete().
+    if ('getStatus' in provider && typeof (provider as ManagedVllmProvider).getStatus === 'function') {
+      const status = (provider as ManagedVllmProvider).getStatus();
+      if (status.state !== 'running') {
+        const response = {
+          status: status.state === 'error' ? 'error' : 'ok',
+          provider: provider.name,
+          state: status.state,
+          ...(status.lastError ? { error: status.lastError } : {}),
+        };
+        reply.code(200).send(response);
+        return;
+      }
+    }
+
     try {
       const result = await provider.complete({
         messages: [{ role: 'user', content: 'Respond with exactly: ok' }],
@@ -128,8 +147,15 @@ export async function createHttpServer(
   });
 
   // LLM models — list available models from the active provider
-  app.get('/llm/models', async (_request, reply) => {
-    const provider = deps.providerRegistry?.getProvider('fast') ?? null;
+  app.get<{ Querystring: { provider?: string } }>('/llm/models', async (request, reply) => {
+    const registry = deps.providerRegistry;
+    const providerName = request.query.provider;
+    let provider;
+    if (providerName && registry) {
+      provider = registry.get(providerName) ?? null;
+    } else {
+      provider = registry?.getProvider('fast') ?? null;
+    }
     if (!provider) {
       reply.code(200).send({ models: [], provider: null });
       return;
@@ -169,6 +195,18 @@ export async function createHttpServer(
       health[check.name] = check.available;
     }
 
+    // Collect extended details for managed providers
+    const details: Record<string, { managed: boolean; state?: string; lastError?: string }> = {};
+    for (const name of names) {
+      const provider = registry.get(name);
+      if (provider && 'getStatus' in provider && typeof (provider as ManagedVllmProvider).getStatus === 'function') {
+        const status = (provider as ManagedVllmProvider).getStatus();
+        const detail: { managed: boolean; state?: string; lastError?: string } = { managed: true, state: status.state };
+        if (status.lastError !== null) detail.lastError = status.lastError;
+        details[name] = detail;
+      }
+    }
+
     reply.code(200).send({
       providers: names,
       tiers: {
@@ -176,9 +214,16 @@ export async function createHttpServer(
         heavy: registry.getTierProviders('heavy'),
       },
       health,
+      ...(Object.keys(details).length > 0 ? { details } : {}),
     });
   });
 
+  // ProxyModel discovery endpoints
+  registerProxymodelEndpoint(app);
+
+  // ProxyModel replay endpoint (stateless pipeline execution)
+  registerReplayEndpoint(app, deps.providerRegistry);
+
   // Proxy management routes to mcpd
   const mcpdClient = new McpdClient(config.mcpdUrl, config.mcpdToken);
   registerProxyRoutes(app, mcpdClient);

src/mcplocal/src/http/traffic.ts

@@ -24,6 +24,7 @@ export interface TrafficEvent {
   upstreamName?: string | undefined;
   body: unknown;
   durationMs?: number | undefined;
+  correlationId?: string | undefined;
 }
 
 export interface ActiveSession {

src/mcplocal/src/llm-config.ts

@@ -12,11 +12,16 @@ import type { OllamaConfig } from './providers/ollama.js';
 import type { AnthropicConfig } from './providers/anthropic.js';
 import type { OpenAiConfig } from './providers/openai.js';
 import type { DeepSeekConfig } from './providers/deepseek.js';
+import { ManagedVllmProvider } from './providers/vllm-managed.js';
+import type { ManagedVllmConfig, ManagedVllmStatus } from './providers/vllm-managed.js';
 
 /**
  * Thin wrapper that delegates all LlmProvider methods but overrides `name`.
  * Used when the user's chosen name (e.g. "vllm-local") differs from the
  * underlying provider's name (e.g. "openai").
+ *
+ * Also proxies `getStatus()` for managed providers so that status display
+ * and health-check logic can detect managed lifecycle state.
  */
 class NamedProvider implements LlmProvider {
   readonly name: string;
@@ -25,6 +30,12 @@ class NamedProvider implements LlmProvider {
   constructor(name: string, inner: LlmProvider) {
     this.name = name;
     this.inner = inner;
+
+    // Proxy getStatus() from managed providers (e.g. ManagedVllmProvider)
+    if ('getStatus' in inner && typeof (inner as ManagedVllmProvider).getStatus === 'function') {
+      (this as unknown as { getStatus: () => ManagedVllmStatus }).getStatus =
+        () => (inner as ManagedVllmProvider).getStatus();
+    }
   }
 
   complete(...args: Parameters<LlmProvider['complete']>) {
@@ -39,6 +50,9 @@ class NamedProvider implements LlmProvider {
   dispose() {
     this.inner.dispose?.();
   }
+  warmup() {
+    this.inner.warmup?.();
+  }
 }
 
 /**
@@ -113,6 +127,23 @@ async function createSingleProvider(
       });
     }
 
+    case 'vllm-managed': {
+      if (!entry.venvPath) {
+        process.stderr.write(`Warning: vLLM venv path not configured for "${entry.name}". Run "mcpctl config setup".\n`);
+        return null;
+      }
+      const cfg: ManagedVllmConfig = {
+        venvPath: entry.venvPath,
+        model: entry.model ?? 'Qwen/Qwen2.5-7B-Instruct-AWQ',
+      };
+      if (entry.port !== undefined) cfg.port = entry.port;
+      if (entry.gpuMemoryUtilization !== undefined) cfg.gpuMemoryUtilization = entry.gpuMemoryUtilization;
+      if (entry.maxModelLen !== undefined) cfg.maxModelLen = entry.maxModelLen;
+      if (entry.idleTimeoutMinutes !== undefined) cfg.idleTimeoutMinutes = entry.idleTimeoutMinutes;
+      if (entry.extraArgs !== undefined) cfg.extraArgs = entry.extraArgs;
+      return new ManagedVllmProvider(cfg);
+    }
+
     default:
       return null;
   }

src/mcplocal/src/providers/anthropic.ts

@@ -54,6 +54,7 @@ export class AnthropicProvider implements LlmProvider {
     return [
       'claude-opus-4-20250514',
       'claude-sonnet-4-20250514',
+      'claude-sonnet-4-5-20250514',
       'claude-haiku-3-5-20241022',
     ];
   }
@@ -74,6 +75,7 @@ export class AnthropicProvider implements LlmProvider {
   private request(body: unknown): Promise<unknown> {
     return new Promise((resolve, reject) => {
       const payload = JSON.stringify(body);
+      const isOAuth = this.apiKey.startsWith('sk-ant-oat');
       const opts = {
         hostname: 'api.anthropic.com',
         port: 443,
@@ -81,7 +83,9 @@ export class AnthropicProvider implements LlmProvider {
         method: 'POST',
         timeout: 120000,
         headers: {
-          'x-api-key': this.apiKey,
+          ...(isOAuth
+            ? { 'Authorization': `Bearer ${this.apiKey}` }
+            : { 'x-api-key': this.apiKey }),
           'anthropic-version': '2023-06-01',
           'Content-Type': 'application/json',
           'Content-Length': Buffer.byteLength(payload),

src/mcplocal/src/providers/registry.ts

@@ -104,6 +104,13 @@ export class ProviderRegistry {
     });
   }
 
+  /** Eagerly start providers that manage subprocesses (e.g., vLLM). */
+  warmupAll(): void {
+    for (const provider of this.providers.values()) {
+      provider.warmup?.();
+    }
+  }
+
   /** Dispose all registered providers that have a dispose method. */
   disposeAll(): void {
     for (const provider of this.providers.values()) {

src/mcplocal/src/providers/types.ts

@@ -58,4 +58,6 @@ export interface LlmProvider {
   isAvailable(): Promise<boolean>;
   /** Optional cleanup for providers with persistent resources (e.g., subprocesses). */
   dispose?(): void;
+  /** Optional eager startup for providers that manage subprocesses (e.g., vLLM). */
+  warmup?(): void;
 }

src/mcplocal/src/providers/vllm-managed.ts

@@ -0,0 +1,333 @@
+import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
+import { homedir } from 'node:os';
+import http from 'node:http';
+import type { LlmProvider, CompletionOptions, CompletionResult } from './types.js';
+import { OpenAiProvider } from './openai.js';
+
+export interface ManagedVllmConfig {
+  /** Path to the Python venv containing vLLM (e.g. "~/vllm_env") */
+  venvPath: string;
+  /** Model to serve (e.g. "Qwen/Qwen2.5-7B-Instruct-AWQ") */
+  model: string;
+  /** Port for vLLM HTTP server (default: 8000) */
+  port?: number;
+  /** GPU memory utilization fraction (default: 0.75) */
+  gpuMemoryUtilization?: number;
+  /** Max model context length (default: 4096) */
+  maxModelLen?: number;
+  /** Minutes of inactivity before killing vLLM to free GPU (default: 15) */
+  idleTimeoutMinutes?: number;
+  /** Additional args passed to `vllm serve` */
+  extraArgs?: string[];
+  /** Override for testing — inject custom spawn function */
+  spawnFn?: typeof spawn;
+  /** Override for testing — inject custom health check */
+  healthCheckFn?: (port: number) => Promise<boolean>;
+}
+
+export type ManagedVllmState = 'stopped' | 'starting' | 'running' | 'error';
+
+export interface ManagedVllmStatus {
+  state: ManagedVllmState;
+  lastError: string | null;
+  pid: number | null;
+  uptime: number | null;
+}
+
+const POLL_INTERVAL_MS = 2000;
+const STARTUP_TIMEOUT_MS = 120_000;
+
+/**
+ * Managed vLLM provider — spawns and manages a local vLLM process.
+ *
+ * Starts vLLM on first `complete()` call, stops it after configurable idle
+ * timeout to free GPU memory. Delegates actual inference to an inner
+ * OpenAiProvider pointed at the local vLLM endpoint.
+ */
+export class ManagedVllmProvider implements LlmProvider {
+  readonly name = 'vllm-managed';
+
+  private process: ChildProcess | null = null;
+  private inner: OpenAiProvider | null = null;
+  private state: ManagedVllmState = 'stopped';
+  private lastError: string | null = null;
+  private lastUsed = 0;
+  private startedAt = 0;
+  private idleTimer: ReturnType<typeof setInterval> | null = null;
+  private startPromise: Promise<void> | null = null;
+
+  private readonly venvPath: string;
+  private readonly model: string;
+  private readonly port: number;
+  private readonly gpuMemoryUtilization: number;
+  private readonly maxModelLen: number;
+  private readonly idleTimeoutMs: number;
+  private readonly extraArgs: string[];
+  private readonly spawnFn: typeof spawn;
+  private readonly healthCheckFn: (port: number) => Promise<boolean>;
+
+  constructor(config: ManagedVllmConfig) {
+    // Expand ~ in venvPath
+    this.venvPath = config.venvPath.startsWith('~')
+      ? config.venvPath.replace('~', homedir())
+      : config.venvPath;
+    this.model = config.model;
+    this.port = config.port ?? 8000;
+    this.gpuMemoryUtilization = config.gpuMemoryUtilization ?? 0.75;
+    this.maxModelLen = config.maxModelLen ?? 4096;
+    this.idleTimeoutMs = (config.idleTimeoutMinutes ?? 15) * 60 * 1000;
+    this.extraArgs = config.extraArgs ?? [];
+    this.spawnFn = config.spawnFn ?? spawn;
+    this.healthCheckFn = config.healthCheckFn ?? defaultHealthCheck;
+  }
+
+  async complete(options: CompletionOptions): Promise<CompletionResult> {
+    await this.ensureRunning();
+    this.lastUsed = Date.now();
+    this.resetIdleTimer();
+    return this.inner!.complete(options);
+  }
+
+  async listModels(): Promise<string[]> {
+    if (this.state === 'running' && this.inner) {
+      return this.inner.listModels();
+    }
+    return [this.model];
+  }
+
+  /**
+   * A managed provider is "available" unless in a permanent error state.
+   * When stopped, it can be auto-started on demand.
+   */
+  async isAvailable(): Promise<boolean> {
+    return this.state !== 'error';
+  }
+
+  getStatus(): ManagedVllmStatus {
+    return {
+      state: this.state,
+      lastError: this.lastError,
+      pid: this.process?.pid ?? null,
+      uptime: this.state === 'running' && this.startedAt > 0
+        ? Math.floor((Date.now() - this.startedAt) / 1000)
+        : null,
+    };
+  }
+
+  /** Eagerly start vLLM so it's ready when the first complete() call arrives. */
+  warmup(): void {
+    if (this.state === 'stopped') {
+      this.ensureRunning().catch((err) => {
+        process.stderr.write(`[vllm-managed] warmup failed: ${(err as Error).message}\n`);
+      });
+    }
+  }
+
+  dispose(): void {
+    this.killProcess();
+    this.clearIdleTimer();
+  }
+
+  // --- Internal ---
+
+  async ensureRunning(): Promise<void> {
+    if (this.state === 'running' && this.process && !this.process.killed) {
+      return;
+    }
+
+    if (this.state === 'starting' && this.startPromise) {
+      return this.startPromise;
+    }
+
+    this.startPromise = this.doStart();
+    try {
+      await this.startPromise;
+    } finally {
+      this.startPromise = null;
+    }
+  }
+
+  private async doStart(): Promise<void> {
+    this.state = 'starting';
+    this.lastError = null;
+
+    const vllmBin = `${this.venvPath}/bin/vllm`;
+
+    const args = [
+      'serve', this.model,
+      '--dtype', 'auto',
+      '--max-model-len', String(this.maxModelLen),
+      '--gpu-memory-utilization', String(this.gpuMemoryUtilization),
+      '--port', String(this.port),
+      ...this.extraArgs,
+    ];
+
+    const env: Record<string, string> = { ...process.env as Record<string, string> };
+    // Ensure NVIDIA libraries are on the linker path
+    const existingLd = env['LD_LIBRARY_PATH'] ?? '';
+    env['LD_LIBRARY_PATH'] = existingLd
+      ? `/usr/lib64/nvidia:${existingLd}`
+      : '/usr/lib64/nvidia';
+    env['VIRTUAL_ENV'] = this.venvPath;
+    // Pin to NVIDIA GPU only — prevent vLLM from seeing AMD GPUs via ROCm/HIP
+    env['CUDA_VISIBLE_DEVICES'] = '0';
+    env['HIP_VISIBLE_DEVICES'] = '';
+    env['ROCR_VISIBLE_DEVICES'] = '';
+
+    try {
+      const child = this.spawnFn(vllmBin, args, {
+        env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: false,
+      });
+
+      this.process = child;
+
+      // Capture stderr for error reporting
+      let stderrBuf = '';
+      child.stderr?.on('data', (chunk: Buffer) => {
+        stderrBuf += chunk.toString();
+        // Keep only last 2KB
+        if (stderrBuf.length > 2048) {
+          stderrBuf = stderrBuf.slice(-2048);
+        }
+      });
+
+      // Handle early exit
+      const exitPromise = new Promise<number | null>((resolve) => {
+        child.on('exit', (code) => resolve(code));
+        child.on('error', (err) => {
+          this.lastError = err.message;
+          resolve(null);
+        });
+      });
+
+      // Poll /v1/models until ready or timeout
+      const ready = await this.waitForReady(exitPromise);
+
+      if (!ready) {
+        const exitCode = child.exitCode;
+        if (exitCode !== null) {
+          this.lastError = `vLLM exited with code ${exitCode}: ${stderrBuf.trim().slice(-200)}`;
+        } else if (!this.lastError) {
+          this.lastError = `vLLM startup timed out after ${STARTUP_TIMEOUT_MS / 1000}s`;
+        }
+        this.killProcess();
+        this.state = 'error';
+        throw new Error(this.lastError);
+      }
+
+      this.state = 'running';
+      this.startedAt = Date.now();
+      this.lastUsed = Date.now();
+
+      // Create inner OpenAI-compatible provider pointed at local vLLM
+      this.inner = new OpenAiProvider({
+        apiKey: 'unused',
+        baseUrl: `http://localhost:${this.port}`,
+        defaultModel: this.model,
+      });
+
+      // Watch for unexpected exit
+      child.on('exit', () => {
+        if (this.state === 'running') {
+          this.state = 'stopped';
+          this.inner = null;
+          this.process = null;
+          this.startedAt = 0;
+        }
+      });
+
+      this.resetIdleTimer();
+    } catch (err) {
+      if (this.state === 'starting') {
+        this.state = 'error';
+        this.lastError = (err as Error).message;
+      }
+      throw err;
+    }
+  }
+
+  private async waitForReady(exitPromise: Promise<number | null>): Promise<boolean> {
+    const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+
+    while (Date.now() < deadline) {
+      // Check if process already exited
+      const raceResult = await Promise.race([
+        this.sleep(POLL_INTERVAL_MS).then(() => 'poll' as const),
+        exitPromise.then(() => 'exited' as const),
+      ]);
+
+      if (raceResult === 'exited' && this.process?.exitCode !== null) {
+        return false;
+      }
+
+      try {
+        const ok = await this.healthCheckFn(this.port);
+        if (ok) return true;
+      } catch {
+        // Not ready yet
+      }
+    }
+
+    return false;
+  }
+
+  private resetIdleTimer(): void {
+    this.clearIdleTimer();
+    this.idleTimer = setInterval(() => {
+      if (this.state === 'running' && Date.now() - this.lastUsed > this.idleTimeoutMs) {
+        process.stderr.write(
+          `[vllm-managed] vLLM stopped after ${Math.round(this.idleTimeoutMs / 60000)}min inactivity (GPU memory freed)\n`,
+        );
+        this.killProcess();
+        this.state = 'stopped';
+        this.inner = null;
+        this.startedAt = 0;
+        this.clearIdleTimer();
+      }
+    }, 30_000); // Check every 30 seconds
+    // Unref so it doesn't keep the process alive
+    if (this.idleTimer && typeof this.idleTimer === 'object' && 'unref' in this.idleTimer) {
+      this.idleTimer.unref();
+    }
+  }
+
+  private clearIdleTimer(): void {
+    if (this.idleTimer) {
+      clearInterval(this.idleTimer);
+      this.idleTimer = null;
+    }
+  }
+
+  private killProcess(): void {
+    if (this.process && !this.process.killed) {
+      this.process.kill('SIGTERM');
+      // Force kill after 5s if still alive
+      const p = this.process;
+      setTimeout(() => {
+        if (!p.killed) p.kill('SIGKILL');
+      }, 5000).unref();
+    }
+    this.process = null;
+    this.inner = null;
+    this.startedAt = 0;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+/** Default health check: GET /v1/models on localhost:{port} */
+function defaultHealthCheck(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${port}/v1/models`, { timeout: 3000 }, (res) => {
+      res.resume();
+      resolve(res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 400);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}

src/mcplocal/src/proxymodel/built-in-models.ts

@@ -0,0 +1,43 @@
+/**
+ * Built-in proxymodel definitions.
+ * These are always available and can be overridden by local YAML files.
+ */
+import type { ProxyModelDefinition } from './schema.js';
+
+export function getBuiltInProxyModels(): Map<string, ProxyModelDefinition> {
+  const models = new Map<string, ProxyModelDefinition>();
+
+  models.set('default', {
+    kind: 'ProxyModel',
+    metadata: { name: 'default' },
+    spec: {
+      controller: 'gate',
+      controllerConfig: { byteBudget: 8192 },
+      stages: [
+        { type: 'passthrough' },
+        { type: 'paginate', config: { pageSize: 8000 } },
+      ],
+      appliesTo: ['prompt', 'toolResult'],
+      cacheable: false,
+    },
+    source: 'built-in',
+  });
+
+  models.set('subindex', {
+    kind: 'ProxyModel',
+    metadata: { name: 'subindex' },
+    spec: {
+      controller: 'gate',
+      controllerConfig: { byteBudget: 8192 },
+      stages: [
+        { type: 'section-split', config: { minSectionSize: 2000, maxSectionSize: 15000 } },
+        { type: 'summarize-tree', config: { maxSummaryTokens: 200, maxGroupSize: 5, maxDepth: 3 } },
+      ],
+      appliesTo: ['prompt', 'toolResult'],
+      cacheable: true,
+    },
+    source: 'built-in',
+  });
+
+  return models;
+}

src/mcplocal/src/proxymodel/cache.ts

@@ -0,0 +1,73 @@
+/**
+ * In-memory content-addressed cache implementing the CacheProvider interface.
+ * LRU eviction at configurable entry limit.
+ *
+ * Phase 2 adds persistent file-based cache; this in-memory version is
+ * sufficient for proving the API and for small workloads.
+ */
+import { createHash } from 'node:crypto';
+import type { CacheProvider } from './types.js';
+
+export interface MemoryCacheConfig {
+  /** Maximum number of entries before LRU eviction. Default 1000. */
+  maxEntries?: number;
+}
+
+export class MemoryCache implements CacheProvider {
+  private readonly store = new Map<string, string>();
+  private readonly maxEntries: number;
+
+  constructor(config?: MemoryCacheConfig) {
+    this.maxEntries = config?.maxEntries ?? 1000;
+  }
+
+  async getOrCompute(key: string, compute: () => Promise<string>): Promise<string> {
+    const cached = this.store.get(key);
+    if (cached !== undefined) {
+      // Move to end (most recently used) for LRU
+      this.store.delete(key);
+      this.store.set(key, cached);
+      return cached;
+    }
+
+    const value = await compute();
+    this.set_sync(key, value);
+    return value;
+  }
+
+  hash(content: string): string {
+    return createHash('sha256').update(content).digest('hex').slice(0, 16);
+  }
+
+  async get(key: string): Promise<string | null> {
+    const value = this.store.get(key);
+    if (value === undefined) return null;
+    // Move to end for LRU
+    this.store.delete(key);
+    this.store.set(key, value);
+    return value;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.set_sync(key, value);
+  }
+
+  /** Number of cached entries. */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /** Clear all cached entries. */
+  clear(): void {
+    this.store.clear();
+  }
+
+  private set_sync(key: string, value: string): void {
+    // Evict oldest if at capacity
+    if (this.store.size >= this.maxEntries) {
+      const oldest = this.store.keys().next().value as string;
+      this.store.delete(oldest);
+    }
+    this.store.set(key, value);
+  }
+}

src/mcplocal/src/proxymodel/content-type.ts

@@ -0,0 +1,62 @@
+/**
+ * Content type detection for section-split stage.
+ *
+ * Detects whether content is JSON, YAML, XML, code, or prose.
+ * This determines how section-split breaks the content apart:
+ * - JSON/YAML/XML → structural splitting (keys, elements)
+ * - Code → function/class boundaries
+ * - Prose → markdown headers or blank-line paragraphs
+ */
+
+export type DetectedContentType = 'json' | 'yaml' | 'xml' | 'code' | 'prose';
+
+/**
+ * Detect the content type of a string.
+ * Uses structural heuristics — no parsing required for detection.
+ */
+export function detectContentType(content: string): DetectedContentType {
+  const trimmed = content.trimStart();
+  if (!trimmed) return 'prose';
+
+  // JSON: starts with { or [
+  if (trimmed[0] === '{' || trimmed[0] === '[') {
+    // Verify it's actually parseable JSON (not just prose starting with {)
+    try {
+      JSON.parse(trimmed);
+      return 'json';
+    } catch {
+      // Could be a code block starting with { — check further
+      if (trimmed[0] === '{') return 'code';
+    }
+  }
+
+  // XML: starts with <? or < followed by a tag name
+  if (trimmed.startsWith('<?xml')) return 'xml';
+  if (trimmed[0] === '<' && /^<[a-zA-Z]/.test(trimmed)) {
+    // Check if it looks like XML/HTML (has closing tags) vs just a < comparison
+    if (/<\/[a-zA-Z]/.test(trimmed)) return 'xml';
+  }
+
+  // YAML: top-level key: value pattern on first line (not inside prose)
+  // Must have multiple key: value lines to distinguish from prose with colons
+  const lines = trimmed.split('\n').slice(0, 10);
+  const yamlKeyLines = lines.filter((l) => /^[a-zA-Z_][a-zA-Z0-9_-]*:\s/.test(l));
+  if (yamlKeyLines.length >= 2) return 'yaml';
+
+  // Code: starts with common code patterns
+  if (/^(function |class |def |const |let |var |import |export |package |module |#include |#!\/)/.test(trimmed)) {
+    return 'code';
+  }
+
+  // Code: high density of code-like patterns
+  const codeIndicators = [
+    /^(if|for|while|switch|return|try|catch)\s*[({]/m,
+    /=>/,
+    /\.\w+\(/,
+    /;\s*$/m,
+  ];
+  const codeScore = codeIndicators.filter((re) => re.test(trimmed)).length;
+  if (codeScore >= 3) return 'code';
+
+  return 'prose';
+}

src/mcplocal/src/proxymodel/content-utils.ts

@@ -0,0 +1,12 @@
+/**
+ * Content utilities — re-exports for plugin authors.
+ *
+ * Plugin code can import these to use the content transformation pipeline
+ * and stage handlers without depending on internal modules.
+ */
+export { executePipeline } from './executor.js';
+export type { ExecuteOptions } from './executor.js';
+export { getStage, listStages } from './stage-registry.js';
+export { detectContentType } from './content-type.js';
+export { MemoryCache } from './cache.js';
+export { LLMProviderAdapter } from './llm-adapter.js';

src/mcplocal/src/proxymodel/executor.ts

@@ -0,0 +1,156 @@
+/**
+ * Pipeline executor.
+ * Runs content through a sequence of stages defined by a ProxyModel.
+ * Each stage receives the output of the previous stage as input.
+ */
+import type { StageContext, StageResult, StageLogger, Section, ContentType, LLMProvider, CacheProvider } from './types.js';
+import type { ProxyModelDefinition } from './schema.js';
+import { getStage } from './stage-registry.js';
+import type { AuditCollector } from '../audit/collector.js';
+
+export interface ExecuteOptions {
+  /** The raw content to process. */
+  content: string;
+  /** What kind of content this is. */
+  contentType: ContentType;
+  /** Source identifier (e.g. "server/tool"). */
+  sourceName: string;
+  /** Project this content belongs to. */
+  projectName: string;
+  /** Session identifier for cache scoping. */
+  sessionId: string;
+  /** The proxymodel definition controlling the pipeline. */
+  proxyModel: ProxyModelDefinition;
+  /** LLM provider for stages that need AI. */
+  llm: LLMProvider;
+  /** Cache provider for stages that cache results. */
+  cache: CacheProvider;
+  /** Optional logger override (defaults to console). */
+  log?: StageLogger;
+  /** Optional audit collector for pipeline/stage event emission. */
+  auditCollector?: AuditCollector;
+  /** Server name for per-server audit tagging. */
+  serverName?: string;
+  /** Correlation ID linking to request-level tracing. */
+  correlationId?: string;
+}
+
+/**
+ * Execute the pipeline defined by a ProxyModel.
+ *
+ * Stages run in order. Each stage receives the previous stage's content
+ * as input. If a stage fails, the pipeline continues with the previous
+ * content. Sections and metadata accumulate across stages.
+ */
+export async function executePipeline(opts: ExecuteOptions): Promise<StageResult> {
+  const { content, proxyModel, llm, cache } = opts;
+  const log = opts.log ?? consoleLogger('pipeline');
+
+  // Check appliesTo filter
+  if (!proxyModel.spec.appliesTo.includes(opts.contentType)) {
+    return { content };
+  }
+
+  let currentContent = content;
+  let sections: Section[] | undefined;
+  let metadata: Record<string, unknown> = {};
+  const pipelineStart = performance.now();
+
+  // Base fields for audit events (avoids exactOptionalPropertyTypes issues)
+  const auditBase = {
+    sessionId: opts.sessionId,
+    source: 'mcplocal' as const,
+    verified: true,
+    ...(opts.serverName !== undefined ? { serverName: opts.serverName } : {}),
+    ...(opts.correlationId !== undefined ? { correlationId: opts.correlationId } : {}),
+  };
+
+  for (const stageSpec of proxyModel.spec.stages) {
+    const handler = getStage(stageSpec.type);
+    if (!handler) {
+      log.warn(`Stage '${stageSpec.type}' not found, skipping`);
+      continue;
+    }
+
+    const ctx: StageContext = {
+      contentType: opts.contentType,
+      sourceName: opts.sourceName,
+      projectName: opts.projectName,
+      sessionId: opts.sessionId,
+      originalContent: content,
+      llm,
+      cache,
+      log: consoleLogger(stageSpec.type),
+      config: stageSpec.config ?? {},
+    };
+
+    try {
+      const inputSize = currentContent.length;
+      const stageStart = performance.now();
+      const result = await handler(currentContent, ctx);
+      const durationMs = Math.round(performance.now() - stageStart);
+      currentContent = result.content;
+      if (result.sections) sections = result.sections;
+      if (result.metadata) metadata = { ...metadata, ...result.metadata };
+
+      opts.auditCollector?.emit({
+        ...auditBase,
+        timestamp: new Date().toISOString(),
+        eventKind: 'stage_execution',
+        payload: {
+          stage: stageSpec.type,
+          durationMs,
+          inputSize,
+          outputSize: result.content.length,
+          sectionCount: result.sections?.length ?? 0,
+          error: null,
+        },
+      });
+    } catch (err) {
+      log.error(`Stage '${stageSpec.type}' failed: ${(err as Error).message}`);
+
+      opts.auditCollector?.emit({
+        ...auditBase,
+        timestamp: new Date().toISOString(),
+        eventKind: 'stage_execution',
+        payload: {
+          stage: stageSpec.type,
+          durationMs: 0,
+          inputSize: currentContent.length,
+          outputSize: currentContent.length,
+          sectionCount: 0,
+          error: (err as Error).message,
+        },
+      });
+      // Continue with previous content on error
+    }
+  }
+
+  const totalDurationMs = Math.round(performance.now() - pipelineStart);
+
+  opts.auditCollector?.emit({
+    ...auditBase,
+    timestamp: new Date().toISOString(),
+    eventKind: 'pipeline_execution',
+    payload: {
+      totalDurationMs,
+      stageCount: proxyModel.spec.stages.length,
+      inputSize: content.length,
+      outputSize: currentContent.length,
+    },
+  });
+
+  const result: StageResult = { content: currentContent };
+  if (sections) result.sections = sections;
+  if (Object.keys(metadata).length > 0) result.metadata = metadata;
+  return result;
+}
+
+function consoleLogger(prefix: string): StageLogger {
+  return {
+    debug: (msg: string) => console.debug(`[${prefix}] ${msg}`),
+    info: (msg: string) => console.info(`[${prefix}] ${msg}`),
+    warn: (msg: string) => console.warn(`[${prefix}] ${msg}`),
+    error: (msg: string) => console.error(`[${prefix}] ${msg}`),
+  };
+}

src/mcplocal/src/proxymodel/index.ts

@@ -0,0 +1,73 @@
+/**
+ * mcpctl/proxymodel — Public entrypoint for ProxyModel plugin authors.
+ *
+ * Import from this module when writing custom plugins or stages:
+ *
+ *   import type { ProxyModelPlugin, PluginSessionContext } from 'mcpctl/proxymodel';
+ *
+ * Plugins implement the ProxyModelPlugin interface and are wired via router.setPlugin().
+ */
+
+// Plugin system
+export type {
+  ProxyModelPlugin,
+  ProxyModelFactory,
+  PluginSessionContext,
+} from './plugin.js';
+export { PluginRegistry, resolveInheritance, loadPlugins } from './plugin-loader.js';
+export { PluginContextImpl } from './plugin-context.js';
+export type { PluginContextDeps } from './plugin-context.js';
+
+// Built-in plugins
+export { createGatePlugin } from './plugins/gate.js';
+export type { GatePluginConfig } from './plugins/gate.js';
+export { createContentPipelinePlugin } from './plugins/content-pipeline.js';
+export { createDefaultPlugin } from './plugins/default.js';
+export type { DefaultPluginConfig } from './plugins/default.js';
+
+// Content utilities for plugin authors
+export { executePipeline } from './executor.js';
+export type { ExecuteOptions } from './executor.js';
+export { getStage, listStages, loadCustomStages, clearCustomStages } from './stage-registry.js';
+export { BUILT_IN_STAGES } from './stages/index.js';
+export { detectContentType } from './content-type.js';
+export { MemoryCache } from './cache.js';
+export { LLMProviderAdapter } from './llm-adapter.js';
+
+// Types
+export type {
+  // Stage contract
+  StageHandler,
+  StageContext,
+  StageResult,
+  Section,
+
+  // Session controller contract (legacy — prefer ProxyModelPlugin)
+  SessionController,
+  SessionContext,
+  InitializeHook,
+  InterceptResult,
+  VirtualToolHandler,
+
+  // Platform services
+  LLMProvider,
+  LLMCompleteOptions,
+  CacheProvider,
+  StageLogger,
+
+  // ProxyModel definition (legacy YAML — kept for backward compat)
+  ProxyModelDefinition,
+  StageDefinition,
+  ContentType,
+
+  // Supporting types
+  ToolDefinition,
+  PromptIndex,
+  PromptIndexEntry,
+} from './types.js';
+
+// Schema & loader (legacy YAML — kept for backward compat)
+export { validateProxyModel } from './schema.js';
+export type { ProxyModelDefinition as ProxyModelDef, StageSpec } from './schema.js';
+export { loadProxyModels, getProxyModel } from './loader.js';
+export { getBuiltInProxyModels } from './built-in-models.js';

src/mcplocal/src/proxymodel/llm-adapter.ts

@@ -0,0 +1,54 @@
+/**
+ * Adapts the internal ProviderRegistry into the public LLMProvider interface
+ * that stages use via ctx.llm.
+ */
+import type { ProviderRegistry } from '../providers/registry.js';
+import type { LLMProvider, LLMCompleteOptions } from './types.js';
+
+export class LLMProviderAdapter implements LLMProvider {
+  constructor(
+    private readonly registry: ProviderRegistry,
+    private readonly providerName?: string,
+    private readonly modelOverride?: string,
+  ) {}
+
+  async complete(prompt: string, options?: LLMCompleteOptions): Promise<string> {
+    let provider;
+    if (this.providerName) {
+      provider = this.registry.get(this.providerName) ?? null;
+    }
+    if (!provider) {
+      provider = this.registry.getProvider('fast');
+    }
+    if (!provider) {
+      throw new Error('No LLM provider available');
+    }
+
+    const messages = [];
+    if (options?.system) {
+      messages.push({ role: 'system' as const, content: options.system });
+    }
+    messages.push({ role: 'user' as const, content: prompt });
+
+    const opts: Parameters<typeof provider.complete>[0] = {
+      messages,
+      temperature: 0,
+    };
+    if (this.modelOverride) {
+      opts.model = this.modelOverride;
+    }
+    if (options?.maxTokens !== undefined) {
+      opts.maxTokens = options.maxTokens;
+    }
+    const result = await provider.complete(opts);
+
+    return result.content;
+  }
+
+  available(): boolean {
+    if (this.providerName) {
+      return this.registry.get(this.providerName) !== undefined;
+    }
+    return this.registry.getProvider('fast') !== null;
+  }
+}

src/mcplocal/src/proxymodel/loader.ts

@@ -0,0 +1,56 @@
+/**
+ * ProxyModel loader.
+ * Loads built-in models and merges with local YAML definitions
+ * from ~/.mcpctl/proxymodels/.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { validateProxyModel, type ProxyModelDefinition } from './schema.js';
+import { getBuiltInProxyModels } from './built-in-models.js';
+
+const PROXYMODELS_DIR = join(process.env.HOME ?? '/tmp', '.mcpctl', 'proxymodels');
+
+/**
+ * Load all proxymodel definitions.
+ * Built-ins are loaded first, then local YAML files override by name.
+ */
+export async function loadProxyModels(dir?: string): Promise<Map<string, ProxyModelDefinition>> {
+  const models = getBuiltInProxyModels();
+
+  // Load local YAML files (overrides built-ins)
+  const localDir = dir ?? PROXYMODELS_DIR;
+  try {
+    const files = await readdir(localDir);
+    for (const file of files) {
+      if (!file.endsWith('.yaml') && !file.endsWith('.yml')) continue;
+      try {
+        const content = await readFile(join(localDir, file), 'utf-8');
+        const raw = parseYaml(content) as unknown;
+        const model = validateProxyModel(raw, 'local');
+        models.set(model.metadata.name, model);
+      } catch (err) {
+        console.warn(`[proxymodel] Failed to load ${file}: ${(err as Error).message}`);
+      }
+    }
+  } catch {
+    // Directory doesn't exist or can't be read — use built-ins only
+  }
+
+  return models;
+}
+
+/**
+ * Get a single proxymodel by name, or 'default' if not found.
+ */
+export async function getProxyModel(name: string, dir?: string): Promise<ProxyModelDefinition> {
+  const models = await loadProxyModels(dir);
+  const model = models.get(name);
+  if (model) return model;
+
+  // Fall back to default
+  const defaultModel = models.get('default');
+  if (defaultModel) return defaultModel;
+
+  throw new Error(`ProxyModel '${name}' not found and no default model available`);
+}

src/mcplocal/src/proxymodel/plugin-context.ts

@@ -0,0 +1,124 @@
+/**
+ * PluginSessionContext implementation.
+ *
+ * Wraps router internals and exposes them via the clean PluginSessionContext
+ * interface. Each session gets its own context instance.
+ */
+import type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification } from '../types.js';
+import type { LLMProvider, CacheProvider, StageLogger, Section, ToolDefinition, ContentType } from './types.js';
+import type { PluginSessionContext, VirtualToolHandler, VirtualServer, PromptIndexEntry } from './plugin.js';
+import type { AuditCollector } from '../audit/collector.js';
+import type { AuditEvent } from '../audit/types.js';
+
+/** Dependencies injected from the router into each context. */
+export interface PluginContextDeps {
+  sessionId: string;
+  projectName: string;
+  llm: LLMProvider;
+  cache: CacheProvider;
+  log: StageLogger;
+  discoverTools: () => Promise<ToolDefinition[]>;
+  routeToUpstream: (request: JsonRpcRequest) => Promise<JsonRpcResponse>;
+  fetchPromptIndex: () => Promise<PromptIndexEntry[]>;
+  getSystemPrompt: (name: string, fallback: string) => Promise<string>;
+  processContent: (toolName: string, content: string, contentType: ContentType) => Promise<{ content: string; sections?: Section[] }>;
+  queueNotification: (notification: JsonRpcNotification) => void;
+  postToMcpd: (path: string, body: Record<string, unknown>) => Promise<unknown>;
+  auditCollector?: AuditCollector;
+}
+
+/**
+ * Concrete PluginSessionContext. One per session.
+ */
+export class PluginContextImpl implements PluginSessionContext {
+  readonly sessionId: string;
+  readonly projectName: string;
+  readonly state = new Map<string, unknown>();
+  readonly llm: LLMProvider;
+  readonly cache: CacheProvider;
+  readonly log: StageLogger;
+
+  /** Virtual tools registered by plugins (name → handler). Tool name is non-namespaced. */
+  readonly virtualTools = new Map<string, { definition: ToolDefinition; handler: VirtualToolHandler }>();
+
+  /** Virtual servers registered by plugins. */
+  readonly virtualServers = new Map<string, VirtualServer>();
+
+  private readonly deps: PluginContextDeps;
+
+  constructor(deps: PluginContextDeps) {
+    this.sessionId = deps.sessionId;
+    this.projectName = deps.projectName;
+    this.llm = deps.llm;
+    this.cache = deps.cache;
+    this.log = deps.log;
+    this.deps = deps;
+  }
+
+  registerTool(tool: ToolDefinition, handler: VirtualToolHandler): void {
+    this.virtualTools.set(tool.name, { definition: tool, handler });
+  }
+
+  unregisterTool(name: string): void {
+    this.virtualTools.delete(name);
+  }
+
+  registerServer(server: VirtualServer): void {
+    this.virtualServers.set(server.name, server);
+    // Register each tool under the server namespace
+    for (const t of server.tools) {
+      const namespacedName = `${server.name}/${t.definition.name}`;
+      this.virtualTools.set(namespacedName, { definition: { ...t.definition, name: namespacedName }, handler: t.handler });
+    }
+  }
+
+  unregisterServer(name: string): void {
+    const server = this.virtualServers.get(name);
+    if (server) {
+      for (const t of server.tools) {
+        this.virtualTools.delete(`${name}/${t.definition.name}`);
+      }
+      this.virtualServers.delete(name);
+    }
+  }
+
+  queueNotification(method: string, params?: unknown): void {
+    const notification: JsonRpcNotification = { jsonrpc: '2.0', method };
+    if (params !== undefined) {
+      notification.params = params as Record<string, unknown>;
+    }
+    this.deps.queueNotification(notification);
+  }
+
+  discoverTools(): Promise<ToolDefinition[]> {
+    return this.deps.discoverTools();
+  }
+
+  routeToUpstream(request: JsonRpcRequest): Promise<JsonRpcResponse> {
+    return this.deps.routeToUpstream(request);
+  }
+
+  fetchPromptIndex(): Promise<PromptIndexEntry[]> {
+    return this.deps.fetchPromptIndex();
+  }
+
+  getSystemPrompt(name: string, fallback: string): Promise<string> {
+    return this.deps.getSystemPrompt(name, fallback);
+  }
+
+  processContent(toolName: string, content: string, contentType: ContentType): Promise<{ content: string; sections?: Section[] }> {
+    return this.deps.processContent(toolName, content, contentType);
+  }
+
+  postToMcpd(path: string, body: Record<string, unknown>): Promise<unknown> {
+    return this.deps.postToMcpd(path, body);
+  }
+
+  /** Emit an audit event, auto-filling sessionId and projectName. */
+  emitAuditEvent(event: Omit<AuditEvent, 'sessionId' | 'projectName'>): void {
+    this.deps.auditCollector?.emit({
+      ...event,
+      sessionId: this.sessionId,
+    });
+  }
+}

src/mcplocal/src/proxymodel/plugin-loader.ts

@@ -0,0 +1,231 @@
+/**
+ * Plugin loader — discovers built-in and user plugins, resolves inheritance.
+ *
+ * Built-in plugins are statically imported. User plugins are loaded from
+ * ~/.mcpctl/proxymodels/ as .js files (default export must be a ProxyModelFactory).
+ *
+ * Inheritance:
+ *   extends: ['gate', 'content-pipeline'] merges parent hooks.
+ *   If two parents define the same hook and the child doesn't override it,
+ *   that's a conflict → error at load time.
+ */
+import type { ProxyModelPlugin, ProxyModelFactory, PluginHookName } from './plugin.js';
+import { PLUGIN_HOOK_NAMES } from './plugin.js';
+
+export interface PluginRegistryEntry {
+  name: string;
+  plugin: ProxyModelPlugin;
+  source: 'built-in' | 'local';
+}
+
+/**
+ * Immutable registry of resolved plugins.
+ */
+export class PluginRegistry {
+  private plugins = new Map<string, PluginRegistryEntry>();
+
+  /** Register a plugin entry. */
+  register(entry: PluginRegistryEntry): void {
+    this.plugins.set(entry.name, entry);
+  }
+
+  /** Get a plugin by name. Returns null if not found. */
+  get(name: string): PluginRegistryEntry | null {
+    return this.plugins.get(name) ?? null;
+  }
+
+  /** Resolve a plugin by name. Returns the plugin or null. */
+  resolve(name: string): ProxyModelPlugin | null {
+    return this.plugins.get(name)?.plugin ?? null;
+  }
+
+  /** List all registered plugins. */
+  list(): PluginRegistryEntry[] {
+    return [...this.plugins.values()];
+  }
+
+  /** Check if a plugin name is registered. */
+  has(name: string): boolean {
+    return this.plugins.has(name);
+  }
+}
+
+/**
+ * Resolve inheritance for a plugin by merging parent hooks.
+ *
+ * Rules:
+ * - If two parents define the same hook and the child doesn't override, → error.
+ * - Child hooks always override parent hooks.
+ * - Lifecycle hooks (onSessionCreate/Destroy) chain sequentially (all parents + child run).
+ */
+export function resolveInheritance(
+  plugin: ProxyModelPlugin,
+  registry: PluginRegistry,
+  visited = new Set<string>(),
+): ProxyModelPlugin {
+  if (!plugin.extends || plugin.extends.length === 0) {
+    return plugin;
+  }
+
+  // Circular dependency check
+  if (visited.has(plugin.name)) {
+    throw new Error(`Circular plugin inheritance detected: ${[...visited, plugin.name].join(' → ')}`);
+  }
+  visited.add(plugin.name);
+
+  // Resolve all parents recursively
+  const resolvedParents: ProxyModelPlugin[] = [];
+  for (const parentName of plugin.extends) {
+    const parent = registry.resolve(parentName);
+    if (!parent) {
+      throw new Error(`Plugin '${plugin.name}' extends unknown plugin '${parentName}'`);
+    }
+    resolvedParents.push(resolveInheritance(parent, registry, new Set(visited)));
+  }
+
+  // Helper to access hooks by name
+  const getHook = (p: ProxyModelPlugin, name: PluginHookName) =>
+    (p as unknown as Record<string, unknown>)[name];
+  const hasHook = (p: ProxyModelPlugin, name: PluginHookName) =>
+    typeof getHook(p, name) === 'function';
+
+  // Detect hook conflicts: two parents define the same hook, child doesn't override
+  const mergedHooks = new Map<string, unknown>();
+
+  for (const hookName of PLUGIN_HOOK_NAMES) {
+    if (hasHook(plugin, hookName)) {
+      // Child overrides — no conflict possible
+      continue;
+    }
+
+    // Check which parents define this hook
+    const parentsWithHook = resolvedParents.filter((p) => hasHook(p, hookName));
+
+    if (parentsWithHook.length > 1) {
+      if (isChainableHook(hookName)) {
+        // Chainable hooks (lifecycle) — chain all parents
+        mergedHooks.set(hookName, chainHooks(hookName, parentsWithHook));
+      } else {
+        // Non-chainable hooks — conflict
+        const parentNames = parentsWithHook.map((p) => p.name).join(', ');
+        throw new Error(
+          `Plugin '${plugin.name}': hook '${hookName}' is defined by multiple parents (${parentNames}) ` +
+          `and '${plugin.name}' does not override it. Add '${hookName}' to '${plugin.name}' to resolve the conflict.`,
+        );
+      }
+    } else if (parentsWithHook.length === 1) {
+      // Single parent defines it — inherit directly
+      mergedHooks.set(hookName, getHook(parentsWithHook[0]!, hookName));
+    }
+  }
+
+  // Build resolved plugin: start with name/description/extends, then layer hooks
+  const resolved: Record<string, unknown> = {
+    name: plugin.name,
+  };
+  if (plugin.description !== undefined) resolved['description'] = plugin.description;
+  if (plugin.extends !== undefined) resolved['extends'] = plugin.extends;
+
+  // Copy merged parent hooks first
+  for (const [hookName, hook] of mergedHooks) {
+    resolved[hookName] = hook;
+  }
+
+  // Then overlay child hooks (child always wins)
+  for (const hookName of PLUGIN_HOOK_NAMES) {
+    const childHook = getHook(plugin, hookName);
+    if (typeof childHook === 'function') {
+      resolved[hookName] = childHook;
+    }
+  }
+
+  return resolved as unknown as ProxyModelPlugin;
+}
+
+/** Hooks that can be chained (all run sequentially) rather than conflicting. */
+function isChainableHook(hookName: PluginHookName): boolean {
+  return hookName === 'onSessionCreate' || hookName === 'onSessionDestroy';
+}
+
+/** Chain multiple lifecycle hooks so all parents run. */
+function chainHooks(hookName: PluginHookName, parents: ProxyModelPlugin[]): unknown {
+  if (hookName === 'onSessionCreate') {
+    return async (ctx: unknown) => {
+      for (const parent of parents) {
+        if (parent.onSessionCreate) {
+          await parent.onSessionCreate(ctx as Parameters<NonNullable<ProxyModelPlugin['onSessionCreate']>>[0]);
+        }
+      }
+    };
+  }
+  if (hookName === 'onSessionDestroy') {
+    return async (ctx: unknown) => {
+      for (const parent of parents) {
+        if (parent.onSessionDestroy) {
+          await parent.onSessionDestroy(ctx as Parameters<NonNullable<ProxyModelPlugin['onSessionDestroy']>>[0]);
+        }
+      }
+    };
+  }
+  return undefined;
+}
+
+/**
+ * Load all plugins: built-in first, then user .js files from disk.
+ * Resolves inheritance after all plugins are registered.
+ */
+export async function loadPlugins(
+  builtInPlugins: ProxyModelPlugin[],
+  userDir?: string,
+): Promise<PluginRegistry> {
+  const registry = new PluginRegistry();
+
+  // Register built-ins
+  for (const plugin of builtInPlugins) {
+    registry.register({ name: plugin.name, plugin, source: 'built-in' });
+  }
+
+  // Load user plugins from disk
+  if (userDir) {
+    await loadUserPlugins(registry, userDir);
+  } else {
+    const defaultDir = `${process.env.HOME ?? '/tmp'}/.mcpctl/proxymodels`;
+    await loadUserPlugins(registry, defaultDir);
+  }
+
+  // Resolve inheritance for all plugins
+  const resolved = new PluginRegistry();
+  for (const entry of registry.list()) {
+    const resolvedPlugin = resolveInheritance(entry.plugin, registry);
+    resolved.register({ name: entry.name, plugin: resolvedPlugin, source: entry.source });
+  }
+
+  return resolved;
+}
+
+/** Load user plugins from a directory (*.js files with default ProxyModelFactory export). */
+async function loadUserPlugins(registry: PluginRegistry, dir: string): Promise<void> {
+  const { readdir } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const { pathToFileURL } = await import('node:url');
+
+  try {
+    const files = await readdir(dir);
+    for (const file of files) {
+      if (!file.endsWith('.js')) continue;
+      try {
+        const mod = await import(pathToFileURL(join(dir, file)).href) as { default?: ProxyModelFactory };
+        if (typeof mod.default !== 'function') {
+          console.warn(`[plugin-loader] ${file} does not export a default ProxyModelFactory, skipping`);
+          continue;
+        }
+        const plugin = mod.default();
+        registry.register({ name: plugin.name, plugin, source: 'local' });
+      } catch (err) {
+        console.warn(`[plugin-loader] Failed to load ${file}: ${(err as Error).message}`);
+      }
+    }
+  } catch {
+    // Directory doesn't exist — no user plugins
+  }
+}

src/mcplocal/src/proxymodel/plugin.ts

@@ -0,0 +1,136 @@
+/**
+ * ProxyModel Plugin Interface — code-based MCP middleware.
+ *
+ * Plugins intercept, modify, add, or block MCP requests and responses.
+ * The gate, content-pipeline, and propose-prompt are all plugins.
+ * With no plugin attached, the router is a transparent MCP proxy.
+ */
+import type { JsonRpcRequest, JsonRpcResponse } from '../types.js';
+import type { LLMProvider, CacheProvider, StageLogger, Section, ToolDefinition, ContentType } from './types.js';
+import type { AuditEvent } from '../audit/types.js';
+
+// ── Plugin Session Context ──────────────────────────────────────────
+
+/** Per-session context provided to plugin hooks. */
+export interface PluginSessionContext {
+  readonly sessionId: string;
+  readonly projectName: string;
+  /** Per-session mutable state (persists across requests in a session) */
+  readonly state: Map<string, unknown>;
+
+  // Platform services
+  readonly llm: LLMProvider;
+  readonly cache: CacheProvider;
+  readonly log: StageLogger;
+
+  // Virtual tool management
+  registerTool(tool: ToolDefinition, handler: VirtualToolHandler): void;
+  unregisterTool(name: string): void;
+
+  // Virtual server management
+  registerServer(server: VirtualServer): void;
+  unregisterServer(name: string): void;
+
+  // Notification queue
+  queueNotification(method: string, params?: unknown): void;
+
+  // Upstream access
+  discoverTools(): Promise<ToolDefinition[]>;
+  routeToUpstream(request: JsonRpcRequest): Promise<JsonRpcResponse>;
+
+  // Prompt access
+  fetchPromptIndex(): Promise<PromptIndexEntry[]>;
+  getSystemPrompt(name: string, fallback: string): Promise<string>;
+
+  // Content processing
+  processContent(toolName: string, content: string, contentType: ContentType): Promise<{ content: string; sections?: Section[] }>;
+
+  // mcpd client access (for propose_prompt, etc.)
+  postToMcpd(path: string, body: Record<string, unknown>): Promise<unknown>;
+
+  // Audit event emission (auto-fills sessionId and projectName)
+  emitAuditEvent(event: Omit<AuditEvent, 'sessionId' | 'projectName'>): void;
+}
+
+// ── Virtual Server ──────────────────────────────────────────────────
+
+export type VirtualToolHandler = (args: Record<string, unknown>, ctx: PluginSessionContext) => Promise<unknown>;
+export type VirtualResourceHandler = (params: Record<string, unknown>, ctx: PluginSessionContext) => Promise<unknown>;
+
+export interface VirtualServer {
+  name: string;
+  description?: string;
+  tools: Array<{
+    definition: ToolDefinition;
+    handler: VirtualToolHandler;
+  }>;
+  resources?: Array<{
+    definition: ResourceDefinition;
+    handler: VirtualResourceHandler;
+  }>;
+}
+
+export interface ResourceDefinition {
+  uri: string;
+  name?: string;
+  description?: string;
+  mimeType?: string;
+}
+
+// ── Prompt Index Entry ──────────────────────────────────────────────
+
+export interface PromptIndexEntry {
+  name: string;
+  priority: number;
+  summary: string | null;
+  chapters: string[] | null;
+  content: string;
+}
+
+// ── Plugin Interface ────────────────────────────────────────────────
+
+export interface ProxyModelPlugin {
+  readonly name: string;
+  readonly description?: string;
+  /** Parent plugin names for composition. */
+  readonly extends?: readonly string[];
+
+  // Lifecycle hooks
+  onSessionCreate?(ctx: PluginSessionContext): Promise<void>;
+  onSessionDestroy?(ctx: PluginSessionContext): Promise<void>;
+
+  // Initialize hook — can return additional instructions
+  onInitialize?(request: JsonRpcRequest, ctx: PluginSessionContext): Promise<{ instructions?: string } | null>;
+
+  // Tools hooks
+  onToolsList?(tools: ToolDefinition[], ctx: PluginSessionContext): Promise<ToolDefinition[]>;
+  onToolCallBefore?(toolName: string, args: Record<string, unknown>, request: JsonRpcRequest, ctx: PluginSessionContext): Promise<JsonRpcResponse | null>;
+  onToolCallAfter?(toolName: string, args: Record<string, unknown>, response: JsonRpcResponse, ctx: PluginSessionContext): Promise<JsonRpcResponse>;
+
+  // Resources hooks
+  onResourcesList?(resources: ResourceDefinition[], ctx: PluginSessionContext): Promise<ResourceDefinition[]>;
+  onResourceRead?(uri: string, request: JsonRpcRequest, ctx: PluginSessionContext): Promise<JsonRpcResponse | null>;
+
+  // Prompts hooks
+  onPromptsList?(prompts: Array<{ name: string; description?: string }>, ctx: PluginSessionContext): Promise<Array<{ name: string; description?: string }>>;
+  onPromptGet?(name: string, request: JsonRpcRequest, ctx: PluginSessionContext): Promise<JsonRpcResponse | null>;
+}
+
+/** Factory function that creates a plugin instance, optionally with config. */
+export type ProxyModelFactory = (config?: Record<string, unknown>) => ProxyModelPlugin;
+
+/** All hook method names on ProxyModelPlugin (for conflict detection). */
+export const PLUGIN_HOOK_NAMES = [
+  'onSessionCreate',
+  'onSessionDestroy',
+  'onInitialize',
+  'onToolsList',
+  'onToolCallBefore',
+  'onToolCallAfter',
+  'onResourcesList',
+  'onResourceRead',
+  'onPromptsList',
+  'onPromptGet',
+] as const;
+
+export type PluginHookName = (typeof PLUGIN_HOOK_NAMES)[number];

src/mcplocal/src/proxymodel/plugins/content-pipeline.ts

@@ -0,0 +1,183 @@
+/**
+ * Content Pipeline Plugin — processes tool results through the proxymodel stage pipeline.
+ *
+ * Extracts the content transformation logic from router.ts:
+ * - maybeProcessContent (pipeline execution)
+ * - Section drill-down (extractSectionParams, handleSectionDrillDown)
+ * - sectionStore management
+ *
+ * This plugin handles:
+ * 1. onToolCallBefore: intercept section drill-down requests (_resultId + _section params)
+ * 2. onToolCallAfter: run tool results through the proxymodel pipeline
+ */
+import type { JsonRpcRequest, JsonRpcResponse } from '../../types.js';
+import type { Section } from '../types.js';
+import type { ProxyModelPlugin, PluginSessionContext } from '../plugin.js';
+
+const SECTION_STORE_TTL_MS = 300_000; // 5 minutes
+
+export function createContentPipelinePlugin(): ProxyModelPlugin {
+  return {
+    name: 'content-pipeline',
+    description: 'Content transformation pipeline: paginate, section-split, summarize tool results.',
+
+    async onToolCallBefore(_toolName, args, request, ctx) {
+      // Intercept section drill-down requests
+      const resultId = args['_resultId'] as string | undefined;
+      const section = args['_section'] as string | undefined;
+
+      if (resultId && section) {
+        return handleSectionDrillDown(request, resultId, section, ctx);
+      }
+
+      return null;
+    },
+
+    async onToolCallAfter(toolName, _args, response, ctx) {
+      if (response.error) return response;
+
+      // Extract text content from the response
+      const raw = extractTextContent(response);
+      if (!raw || raw.length <= 2000) return response;
+
+      try {
+        const result = await ctx.processContent(toolName, raw, 'toolResult');
+
+        // If pipeline produced sections, store them for drill-down
+        if (result.sections && result.sections.length > 0) {
+          const resultId = `pm-${Date.now().toString(36)}`;
+          storeSections(ctx, resultId, result.sections);
+
+          const text = `${result.content}\n\n_resultId: ${resultId} — use _resultId and _section parameters to drill into a section.`;
+          return {
+            jsonrpc: '2.0',
+            id: response.id,
+            result: { content: [{ type: 'text', text }] },
+          };
+        }
+
+        // Pipeline ran but no sections — return processed content if it changed
+        if (result.content !== raw) {
+          return {
+            jsonrpc: '2.0',
+            id: response.id,
+            result: { content: [{ type: 'text', text: result.content }] },
+          };
+        }
+      } catch {
+        // Pipeline failed — return original response
+      }
+
+      return response;
+    },
+  };
+}
+
+/** Extract text content from a tool result response. */
+function extractTextContent(response: JsonRpcResponse): string | null {
+  if (!response.result || typeof response.result !== 'object') return null;
+  const result = response.result as Record<string, unknown>;
+  if (!Array.isArray(result['content'])) return null;
+  const parts = result['content'] as Array<{ type: string; text?: string }>;
+  const texts = parts.filter((p) => p.type === 'text' && p.text).map((p) => p.text!);
+  return texts.length > 0 ? texts.join('\n') : null;
+}
+
+/** Handle section drill-down request. */
+function handleSectionDrillDown(
+  request: JsonRpcRequest,
+  resultId: string,
+  sectionId: string,
+  ctx: PluginSessionContext,
+): JsonRpcResponse {
+  const sections = getSections(ctx, resultId);
+  if (!sections) {
+    return {
+      jsonrpc: '2.0',
+      id: request.id,
+      result: {
+        content: [{
+          type: 'text',
+          text: 'Cached result not found (expired or invalid _resultId). Please re-call the tool without _resultId/_section to get a fresh result.',
+        }],
+      },
+    };
+  }
+
+  const section = findSection(sections, sectionId);
+  if (!section) {
+    const available = sections.map((s) => s.id).join(', ');
+    return {
+      jsonrpc: '2.0',
+      id: request.id,
+      result: {
+        content: [{
+          type: 'text',
+          text: `Section '${sectionId}' not found. Available sections: ${available}`,
+        }],
+      },
+    };
+  }
+
+  let text = section.content;
+  if (section.children && section.children.length > 0) {
+    const childToc = section.children.map((c) => `[${c.id}] ${c.title}`).join('\n');
+    text += `\n\n${section.children.length} sub-sections:\n${childToc}\n\nUse _resultId="${resultId}" _section="<id>" to drill deeper.`;
+  }
+
+  return {
+    jsonrpc: '2.0',
+    id: request.id,
+    result: { content: [{ type: 'text', text }] },
+  };
+}
+
+/** Find a section by ID, searching recursively through children. */
+function findSection(sections: Section[], id: string): Section | null {
+  for (const section of sections) {
+    if (section.id === id) return section;
+    if (section.children) {
+      const found = findSection(section.children, id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// ── Section store using ctx.state ──
+
+const SECTION_STORE_KEY = '_contentPipeline_sections';
+
+interface SectionStoreEntry {
+  sections: Section[];
+  createdAt: number;
+}
+
+function storeSections(ctx: PluginSessionContext, resultId: string, sections: Section[]): void {
+  let store = ctx.state.get(SECTION_STORE_KEY) as Map<string, SectionStoreEntry> | undefined;
+  if (!store) {
+    store = new Map();
+    ctx.state.set(SECTION_STORE_KEY, store);
+  }
+  store.set(resultId, { sections, createdAt: Date.now() });
+
+  // Evict stale entries
+  const now = Date.now();
+  for (const [key, entry] of store) {
+    if (now - entry.createdAt > SECTION_STORE_TTL_MS) {
+      store.delete(key);
+    }
+  }
+}
+
+function getSections(ctx: PluginSessionContext, resultId: string): Section[] | null {
+  const store = ctx.state.get(SECTION_STORE_KEY) as Map<string, SectionStoreEntry> | undefined;
+  if (!store) return null;
+  const entry = store.get(resultId);
+  if (!entry) return null;
+  if (Date.now() - entry.createdAt > SECTION_STORE_TTL_MS) {
+    store.delete(resultId);
+    return null;
+  }
+  return entry.sections;
+}

src/mcplocal/src/proxymodel/plugins/default.ts

@@ -0,0 +1,70 @@
+/**
+ * Default Plugin — composes gate + content-pipeline.
+ *
+ * This is the standard proxy model for mcpctl projects:
+ * - Gated sessions with prompt selection
+ * - Content transformation pipeline (paginate, section-split, etc.)
+ *
+ * When resolved through the plugin loader with inheritance, it inherits
+ * all hooks from both parents. Since gate and content-pipeline don't
+ * overlap on hooks, no conflicts arise.
+ */
+import type { ProxyModelPlugin } from '../plugin.js';
+import { createGatePlugin, type GatePluginConfig } from './gate.js';
+import { createContentPipelinePlugin } from './content-pipeline.js';
+
+export interface DefaultPluginConfig extends GatePluginConfig {}
+
+/**
+ * Create the default plugin that merges gate + content-pipeline.
+ *
+ * Instead of relying on the loader's inheritance resolution (which needs
+ * all plugins registered first), we directly compose the two plugins here.
+ */
+export function createDefaultPlugin(config: DefaultPluginConfig = {}): ProxyModelPlugin {
+  const gate = createGatePlugin(config);
+  const pipeline = createContentPipelinePlugin();
+
+  const plugin: ProxyModelPlugin = {
+    name: 'default',
+    description: 'Default proxy model: gated sessions with paginated content.',
+    extends: ['gate', 'content-pipeline'] as const,
+
+    // Lifecycle: chain both
+    async onSessionCreate(ctx) {
+      if (gate.onSessionCreate) await gate.onSessionCreate(ctx);
+      if (pipeline.onSessionCreate) await pipeline.onSessionCreate(ctx);
+    },
+
+    async onSessionDestroy(ctx) {
+      if (gate.onSessionDestroy) await gate.onSessionDestroy(ctx);
+      if (pipeline.onSessionDestroy) await pipeline.onSessionDestroy(ctx);
+    },
+
+    // Tool call before: gate intercept first, then content-pipeline section drill-down
+    async onToolCallBefore(toolName, args, request, ctx) {
+      if (gate.onToolCallBefore) {
+        const intercepted = await gate.onToolCallBefore(toolName, args, request, ctx);
+        if (intercepted) return intercepted;
+      }
+      if (pipeline.onToolCallBefore) {
+        const intercepted = await pipeline.onToolCallBefore(toolName, args, request, ctx);
+        if (intercepted) return intercepted;
+      }
+      return null;
+    },
+  };
+
+  // Conditionally add optional hooks to satisfy exactOptionalPropertyTypes
+  if (gate.onInitialize) {
+    plugin.onInitialize = gate.onInitialize.bind(gate);
+  }
+  if (gate.onToolsList) {
+    plugin.onToolsList = gate.onToolsList.bind(gate);
+  }
+  if (pipeline.onToolCallAfter) {
+    plugin.onToolCallAfter = pipeline.onToolCallAfter.bind(pipeline);
+  }
+
+  return plugin;
+}

src/mcplocal/src/proxymodel/plugins/gate.ts

@@ -0,0 +1,536 @@
+/**
+ * Gate Plugin — gated session flow as a ProxyModelPlugin.
+ *
+ * When a session starts, it is "gated": only begin_session is visible.
+ * After begin_session is called, the session ungates and all tools become accessible.
+ * If a gated session tries to call a real tool, the gate auto-ungates via keyword extraction.
+ *
+ * This plugin replaces the hardcoded gate logic in router.ts.
+ */
+import type { JsonRpcRequest, JsonRpcResponse } from '../../types.js';
+import type { ToolDefinition } from '../types.js';
+import type { ProxyModelPlugin, PluginSessionContext } from '../plugin.js';
+import { SessionGate } from '../../gate/session-gate.js';
+import { TagMatcher, extractKeywordsFromToolCall, tokenizeDescription } from '../../gate/tag-matcher.js';
+import type { TagMatchResult } from '../../gate/tag-matcher.js';
+import { LlmPromptSelector } from '../../gate/llm-selector.js';
+import type { ProviderRegistry } from '../../providers/registry.js';
+
+export interface GatePluginConfig {
+  gated?: boolean;
+  providerRegistry?: ProviderRegistry | null;
+  modelOverride?: string;
+  byteBudget?: number;
+}
+
+const MAX_RESPONSE_CHARS = 24_000;
+
+export function createGatePlugin(config: GatePluginConfig = {}): ProxyModelPlugin {
+  const isGated = config.gated !== false;
+  const tagMatcher = new TagMatcher(config.byteBudget);
+  const llmSelector = config.providerRegistry
+    ? new LlmPromptSelector(config.providerRegistry, config.modelOverride)
+    : null;
+
+  // Per-session state tracking (plugin-scoped, not global SessionGate)
+  const sessionGate = new SessionGate();
+
+  return {
+    name: 'gate',
+    description: 'Gated session flow: begin_session → prompt selection → ungate.',
+
+    async onSessionCreate(ctx) {
+      sessionGate.createSession(ctx.sessionId, isGated);
+
+      // Register begin_session virtual tool
+      ctx.registerTool(getBeginSessionTool(llmSelector), async (args, callCtx) => {
+        return handleBeginSession(args, callCtx, sessionGate, tagMatcher, llmSelector);
+      });
+
+      // Register read_prompts virtual tool (available even when ungated)
+      ctx.registerTool(getReadPromptsTool(), async (args, callCtx) => {
+        return handleReadPrompts(args, callCtx, sessionGate, tagMatcher);
+      });
+
+      // Register propose_prompt virtual tool
+      ctx.registerTool(getProposeTool(), async (args, callCtx) => {
+        return handleProposePrompt(args, callCtx);
+      });
+    },
+
+    async onSessionDestroy(ctx) {
+      sessionGate.removeSession(ctx.sessionId);
+    },
+
+    async onInitialize(_request, ctx) {
+      if (!isGated) return null;
+
+      // Build gate instructions with prompt index
+      const parts: string[] = [];
+      const gateInstructions = await ctx.getSystemPrompt(
+        'gate-instructions',
+        'IMPORTANT: This project uses a gated session. You must call begin_session with keywords describing your task before using any other tools. This will provide you with relevant project context, policies, and guidelines.',
+      );
+      parts.push(`\n${gateInstructions}`);
+
+      // Append tool inventory (names only)
+      try {
+        const tools = await ctx.discoverTools();
+        if (tools.length > 0) {
+          parts.push('\nAvailable MCP server tools (accessible after begin_session):');
+          for (const t of tools) {
+            parts.push(`  ${t.name}`);
+          }
+        }
+      } catch {
+        // Tool discovery is optional
+      }
+
+      // Append compact prompt index
+      try {
+        const promptIndex = await ctx.fetchPromptIndex();
+        if (promptIndex.length > 0) {
+          let displayIndex = promptIndex;
+          if (displayIndex.length > 50) {
+            displayIndex = displayIndex.filter((p) => p.priority >= 7);
+          }
+          displayIndex.sort((a, b) => b.priority - a.priority);
+
+          parts.push('\nAvailable project prompts:');
+          for (const p of displayIndex) {
+            const summary = p.summary ? `: ${p.summary}` : '';
+            parts.push(`- ${p.name} (priority ${p.priority})${summary}`);
+          }
+          parts.push(
+            '\nChoose your begin_session keywords based on which of these prompts seem relevant to your task.',
+          );
+        }
+      } catch {
+        // Prompt index is optional
+      }
+
+      return { instructions: parts.join('\n') };
+    },
+
+    async onToolsList(tools, ctx) {
+      // When gated, only show begin_session
+      if (sessionGate.isGated(ctx.sessionId)) {
+        return [getBeginSessionTool(llmSelector)];
+      }
+
+      // When ungated, show upstream tools + read_prompts + propose_prompt (no begin_session)
+      return [...tools, getReadPromptsTool(), getProposeTool()];
+    },
+
+    async onToolCallBefore(toolName, args, request, ctx) {
+      // If gated and trying to call a real tool, auto-ungate via keyword extraction
+      if (sessionGate.isGated(ctx.sessionId)) {
+        return handleGatedIntercept(request, ctx, toolName, args, sessionGate, tagMatcher);
+      }
+      return null;
+    },
+  };
+}
+
+// ── begin_session tool definition ──
+
+function getBeginSessionTool(llmSelector: LlmPromptSelector | null): ToolDefinition {
+  if (llmSelector) {
+    return {
+      name: 'begin_session',
+      description: 'Start your session by describing what you want to accomplish. You will receive relevant project context, policies, and guidelines. This is required before using other tools.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          description: {
+            type: 'string',
+            description: "Describe what you're trying to do in a sentence or two (e.g. \"I want to pair a new Zigbee device with the hub\")",
+          },
+        },
+        required: ['description'],
+      },
+    };
+  }
+  return {
+    name: 'begin_session',
+    description: 'Start your session by providing keywords that describe your current task. You will receive relevant project context, policies, and guidelines. This is required before using other tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          maxItems: 10,
+          description: '3-7 keywords describing your current task (e.g. ["zigbee", "pairing", "mqtt"])',
+        },
+      },
+      required: ['tags'],
+    },
+  };
+}
+
+function getReadPromptsTool(): ToolDefinition {
+  return {
+    name: 'read_prompts',
+    description: 'Retrieve additional project prompts by keywords. Use this if you need more context about specific topics. Returns matched prompts and a list of other available prompts.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        tags: {
+          type: 'array',
+          items: { type: 'string' },
+          maxItems: 10,
+          description: 'Keywords to match against available prompts',
+        },
+      },
+      required: ['tags'],
+    },
+  };
+}
+
+function getProposeTool(): ToolDefinition {
+  return {
+    name: 'propose_prompt',
+    description: 'Propose a new prompt for this project. Creates a pending request that must be approved by a user before becoming active.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Prompt name (lowercase alphanumeric with hyphens, e.g. "debug-guide")' },
+        content: { type: 'string', description: 'Prompt content text' },
+      },
+      required: ['name', 'content'],
+    },
+  };
+}
+
+// ── begin_session handler ──
+
+async function handleBeginSession(
+  args: Record<string, unknown>,
+  ctx: PluginSessionContext,
+  sessionGate: SessionGate,
+  tagMatcher: TagMatcher,
+  llmSelector: LlmPromptSelector | null,
+): Promise<unknown> {
+  const rawTags = args['tags'] as string[] | undefined;
+  const description = args['description'] as string | undefined;
+
+  let tags: string[];
+  if (rawTags && Array.isArray(rawTags) && rawTags.length > 0) {
+    tags = rawTags;
+  } else if (description && description.trim().length > 0) {
+    tags = tokenizeDescription(description);
+  } else {
+    throw new ToolError(-32602, 'Provide tags or description');
+  }
+
+  if (!sessionGate.isGated(ctx.sessionId)) {
+    return {
+      content: [{ type: 'text', text: 'Session already started. Use read_prompts to retrieve additional context.' }],
+    };
+  }
+
+  const promptIndex = await ctx.fetchPromptIndex();
+
+  // Primary: LLM selection. Fallback: deterministic tag matching.
+  let matchResult: TagMatchResult;
+  let reasoning = '';
+
+  if (llmSelector) {
+    try {
+      const llmIndex = promptIndex.map((p) => ({
+        name: p.name,
+        priority: p.priority,
+        summary: p.summary,
+        chapters: p.chapters,
+      }));
+      const llmResult = await llmSelector.selectPrompts(tags, llmIndex);
+      reasoning = llmResult.reasoning;
+
+      const selectedSet = new Set(llmResult.selectedNames);
+      const selected = promptIndex.filter((p) => selectedSet.has(p.name));
+      const remaining = promptIndex.filter((p) => !selectedSet.has(p.name));
+
+      matchResult = tagMatcher.match(
+        [...tags, ...llmResult.selectedNames],
+        selected,
+      );
+      matchResult.remaining = [...matchResult.remaining, ...remaining];
+    } catch {
+      matchResult = tagMatcher.match(tags, promptIndex);
+    }
+  } else {
+    matchResult = tagMatcher.match(tags, promptIndex);
+  }
+
+  // Ungate the session
+  sessionGate.ungate(ctx.sessionId, tags, matchResult);
+  ctx.queueNotification('notifications/tools/list_changed');
+
+  // Audit: gate_decision for begin_session
+  ctx.emitAuditEvent({
+    timestamp: new Date().toISOString(),
+    eventKind: 'gate_decision',
+    source: 'client',
+    verified: false,
+    payload: {
+      trigger: 'begin_session',
+      clientIntent: { tags, description: description ?? null },
+      matchedPrompts: matchResult.fullContent.map((p) => p.name),
+      reasoning: reasoning || null,
+    },
+  });
+
+  // Build response
+  const responseParts: string[] = [];
+
+  if (reasoning) {
+    responseParts.push(`Selection reasoning: ${reasoning}\n`);
+  }
+
+  for (const p of matchResult.fullContent) {
+    responseParts.push(`--- ${p.name} (priority: ${p.priority}) ---\n${p.content}\n`);
+  }
+
+  if (matchResult.indexOnly.length > 0) {
+    responseParts.push('Additional matched prompts (use read_prompts to retrieve full content):');
+    for (const p of matchResult.indexOnly) {
+      responseParts.push(`  - ${p.name}: ${p.summary ?? 'No description'}`);
+    }
+    responseParts.push('');
+  }
+
+  if (matchResult.remaining.length > 0) {
+    responseParts.push('Other available prompts:');
+    for (const p of matchResult.remaining) {
+      responseParts.push(`  - ${p.name}: ${p.summary ?? 'No description'}`);
+    }
+    responseParts.push('');
+  }
+
+  const encouragement = await ctx.getSystemPrompt(
+    'gate-encouragement',
+    'If any of the listed prompts seem relevant to your work, or if you encounter unfamiliar patterns, conventions, or constraints during implementation, use read_prompts({ tags: [...] }) to retrieve them. It is better to check and not need it than to proceed without important context.',
+  );
+  responseParts.push(encouragement);
+
+  // Append tool inventory (names only)
+  try {
+    const tools = await ctx.discoverTools();
+    if (tools.length > 0) {
+      responseParts.push('\nAvailable MCP server tools:');
+      for (const t of tools) {
+        responseParts.push(`  ${t.name}`);
+      }
+    }
+  } catch {
+    // Tool discovery is optional
+  }
+
+  const retryInstruction = await ctx.getSystemPrompt(
+    'gate-session-active',
+    "The session is now active with full tool access. Proceed with the user's original request using the tools listed above.",
+  );
+  responseParts.push(`\n${retryInstruction}`);
+
+  // Safety cap
+  let text = responseParts.join('\n');
+  if (text.length > MAX_RESPONSE_CHARS) {
+    text = text.slice(0, MAX_RESPONSE_CHARS) + '\n\n[Response truncated. Use read_prompts to retrieve full content.]';
+  }
+
+  return { content: [{ type: 'text', text }] };
+}
+
+// ── read_prompts handler ──
+
+async function handleReadPrompts(
+  args: Record<string, unknown>,
+  ctx: PluginSessionContext,
+  sessionGate: SessionGate,
+  tagMatcher: TagMatcher,
+): Promise<unknown> {
+  const tags = args['tags'] as string[] | undefined;
+
+  if (!tags || !Array.isArray(tags) || tags.length === 0) {
+    throw new ToolError(-32602, 'Missing or empty tags array');
+  }
+
+  const promptIndex = await ctx.fetchPromptIndex();
+
+  // Filter out already-sent prompts
+  const available = sessionGate.filterAlreadySent(ctx.sessionId, promptIndex);
+  const matchResult = tagMatcher.match(tags, available);
+
+  // Record retrieved prompts
+  sessionGate.addRetrievedPrompts(
+    ctx.sessionId,
+    tags,
+    matchResult.fullContent.map((p) => p.name),
+  );
+
+  // Audit: prompt_delivery
+  ctx.emitAuditEvent({
+    timestamp: new Date().toISOString(),
+    eventKind: 'prompt_delivery',
+    source: 'mcplocal',
+    verified: true,
+    payload: {
+      queryTags: tags,
+      deliveredPrompts: matchResult.fullContent.map((p) => p.name),
+      indexOnlyPrompts: matchResult.indexOnly.map((p) => p.name),
+    },
+  });
+
+  if (matchResult.fullContent.length === 0 && matchResult.indexOnly.length === 0) {
+    return { content: [{ type: 'text', text: 'No new matching prompts found for the given keywords.' }] };
+  }
+
+  const responseParts: string[] = [];
+  for (const p of matchResult.fullContent) {
+    responseParts.push(`--- ${p.name} (priority: ${p.priority}) ---\n${p.content}\n`);
+  }
+
+  if (matchResult.indexOnly.length > 0) {
+    responseParts.push('Additional matched prompts (too large to include, try more specific keywords):');
+    for (const p of matchResult.indexOnly) {
+      responseParts.push(`  - ${p.name}: ${p.summary ?? 'No description'}`);
+    }
+  }
+
+  return { content: [{ type: 'text', text: responseParts.join('\n') }] };
+}
+
+// ── propose_prompt handler ──
+
+async function handleProposePrompt(
+  args: Record<string, unknown>,
+  ctx: PluginSessionContext,
+): Promise<unknown> {
+  const name = args['name'] as string | undefined;
+  const content = args['content'] as string | undefined;
+
+  if (!name || !content) {
+    throw new ToolError(-32602, 'Missing required arguments: name and content');
+  }
+
+  try {
+    const body: Record<string, unknown> = { name, content };
+    body['createdBySession'] = ctx.sessionId;
+    await ctx.postToMcpd(
+      `/api/v1/projects/${encodeURIComponent(ctx.projectName)}/promptrequests`,
+      body,
+    );
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Prompt request "${name}" created successfully. It will be visible to you as a resource at mcpctl://prompts/${name}. A user must approve it before it becomes permanent.`,
+        },
+      ],
+    };
+  } catch (err) {
+    throw new ToolError(-32603, `Failed to propose prompt: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+// ── gated intercept handler ──
+
+async function handleGatedIntercept(
+  request: JsonRpcRequest,
+  ctx: PluginSessionContext,
+  toolName: string,
+  toolArgs: Record<string, unknown>,
+  sessionGate: SessionGate,
+  tagMatcher: TagMatcher,
+): Promise<JsonRpcResponse> {
+  const tags = extractKeywordsFromToolCall(toolName, toolArgs);
+
+  try {
+    const promptIndex = await ctx.fetchPromptIndex();
+    const matchResult = tagMatcher.match(tags, promptIndex);
+
+    // Ungate the session
+    sessionGate.ungate(ctx.sessionId, tags, matchResult);
+    ctx.queueNotification('notifications/tools/list_changed');
+
+    // Audit: gate_decision for auto-intercept
+    ctx.emitAuditEvent({
+      timestamp: new Date().toISOString(),
+      eventKind: 'gate_decision',
+      source: 'mcplocal',
+      verified: true,
+      payload: {
+        trigger: 'auto_intercept',
+        toolName,
+        extractedKeywords: tags,
+        matchedPrompts: matchResult.fullContent.map((p) => p.name),
+      },
+    });
+
+    // Build briefing from matched content
+    const briefingParts: string[] = [];
+    if (matchResult.fullContent.length > 0) {
+      const preamble = await ctx.getSystemPrompt(
+        'gate-intercept-preamble',
+        'The following project context was automatically retrieved based on your tool call.',
+      );
+      briefingParts.push(`--- ${preamble} ---\n`);
+      for (const p of matchResult.fullContent) {
+        briefingParts.push(`--- ${p.name} (priority: ${p.priority}) ---\n${p.content}\n`);
+      }
+      briefingParts.push('--- End of project context ---\n');
+    }
+
+    if (matchResult.remaining.length > 0 || matchResult.indexOnly.length > 0) {
+      briefingParts.push('Other prompts available (use read_prompts to retrieve):');
+      for (const p of [...matchResult.indexOnly, ...matchResult.remaining]) {
+        briefingParts.push(`  - ${p.name}: ${p.summary ?? 'No description'}`);
+      }
+      briefingParts.push('');
+    }
+
+    // Append tool inventory
+    try {
+      const tools = await ctx.discoverTools();
+      if (tools.length > 0) {
+        briefingParts.push('Available MCP server tools:');
+        for (const t of tools) {
+          briefingParts.push(`  ${t.name}`);
+        }
+        briefingParts.push('');
+      }
+    } catch {
+      // Tool discovery is optional
+    }
+
+    // Route the actual tool call
+    const response = await ctx.routeToUpstream(request);
+
+    // Prepend briefing to the response
+    if (briefingParts.length > 0 && response.result && !response.error) {
+      const result = response.result as { content?: Array<{ type: string; text: string }> };
+      const briefing = briefingParts.join('\n');
+      if (result.content && Array.isArray(result.content)) {
+        result.content.unshift({ type: 'text', text: briefing });
+      } else {
+        (response.result as Record<string, unknown>)['_briefing'] = briefing;
+      }
+    }
+
+    return response;
+  } catch {
+    // If prompt retrieval fails, just ungate and route normally
+    sessionGate.ungate(ctx.sessionId, tags, { fullContent: [], indexOnly: [], remaining: [] });
+    ctx.queueNotification('notifications/tools/list_changed');
+    return ctx.routeToUpstream(request);
+  }
+}
+
+/** Error class for virtual tool errors that maps to JSON-RPC error codes. */
+class ToolError extends Error {
+  constructor(public readonly code: number, message: string) {
+    super(message);
+    this.name = 'ToolError';
+  }
+}

src/mcplocal/src/proxymodel/schema.ts

@@ -0,0 +1,125 @@
+/**
+ * ProxyModel definition schema.
+ * Defines the structure of proxymodel YAML files and provides
+ * runtime validation.
+ */
+import type { ContentType } from './types.js';
+
+/** Single stage reference within a proxymodel pipeline. */
+export interface StageSpec {
+  type: string;
+  config?: Record<string, unknown>;
+}
+
+/** Parsed and validated proxymodel definition. */
+export interface ProxyModelDefinition {
+  kind: 'ProxyModel';
+  metadata: { name: string };
+  spec: {
+    controller: string;
+    controllerConfig?: Record<string, unknown>;
+    stages: StageSpec[];
+    appliesTo: ContentType[];
+    cacheable: boolean;
+  };
+  /** Where this model was loaded from. */
+  source: 'built-in' | 'local';
+}
+
+/** Validate a raw parsed object as a ProxyModelDefinition. */
+export function validateProxyModel(raw: unknown, source: 'built-in' | 'local' = 'local'): ProxyModelDefinition {
+  if (!raw || typeof raw !== 'object') {
+    throw new Error('ProxyModel must be an object');
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  if (obj.kind !== undefined && obj.kind !== 'ProxyModel') {
+    throw new Error(`Invalid kind: expected 'ProxyModel', got '${String(obj.kind)}'`);
+  }
+
+  // metadata.name
+  const metadata = obj.metadata as Record<string, unknown> | undefined;
+  if (!metadata || typeof metadata !== 'object' || typeof metadata.name !== 'string' || !metadata.name) {
+    throw new Error('ProxyModel must have metadata.name (string)');
+  }
+  const name = metadata.name;
+
+  // spec
+  const spec = obj.spec as Record<string, unknown> | undefined;
+  if (!spec || typeof spec !== 'object') {
+    throw new Error('ProxyModel must have a spec object');
+  }
+
+  // spec.controller
+  const controller = typeof spec.controller === 'string' ? spec.controller : 'gate';
+
+  // spec.controllerConfig
+  let controllerConfig: Record<string, unknown> | undefined;
+  if (spec.controllerConfig !== undefined && spec.controllerConfig !== null) {
+    if (typeof spec.controllerConfig !== 'object') {
+      throw new Error('spec.controllerConfig must be an object');
+    }
+    controllerConfig = spec.controllerConfig as Record<string, unknown>;
+  }
+
+  // spec.stages
+  if (!Array.isArray(spec.stages) || spec.stages.length === 0) {
+    throw new Error('spec.stages must be a non-empty array');
+  }
+  const stages: StageSpec[] = spec.stages.map((s: unknown, i: number) => {
+    if (!s || typeof s !== 'object') {
+      throw new Error(`spec.stages[${i}] must be an object`);
+    }
+    const stage = s as Record<string, unknown>;
+    if (typeof stage.type !== 'string' || !stage.type) {
+      throw new Error(`spec.stages[${i}].type must be a non-empty string`);
+    }
+    const result: StageSpec = { type: stage.type };
+    if (stage.config !== undefined && stage.config !== null) {
+      if (typeof stage.config !== 'object') {
+        throw new Error(`spec.stages[${i}].config must be an object`);
+      }
+      result.config = stage.config as Record<string, unknown>;
+    }
+    return result;
+  });
+
+  // spec.appliesTo
+  const validContentTypes: ContentType[] = ['prompt', 'toolResult', 'resource'];
+  let appliesTo: ContentType[];
+  if (spec.appliesTo !== undefined) {
+    if (!Array.isArray(spec.appliesTo)) {
+      throw new Error('spec.appliesTo must be an array');
+    }
+    for (const ct of spec.appliesTo) {
+      if (!validContentTypes.includes(ct as ContentType)) {
+        throw new Error(`Invalid appliesTo value '${String(ct)}'. Must be one of: ${validContentTypes.join(', ')}`);
+      }
+    }
+    appliesTo = spec.appliesTo as ContentType[];
+  } else {
+    appliesTo = ['prompt', 'toolResult'];
+  }
+
+  // spec.cacheable
+  const cacheable = spec.cacheable !== undefined ? Boolean(spec.cacheable) : true;
+
+  const result: ProxyModelDefinition = {
+    kind: 'ProxyModel',
+    metadata: { name },
+    spec: {
+      controller,
+      stages,
+      appliesTo,
+      cacheable,
+    },
+    source,
+  };
+
+  if (controllerConfig) {
+    result.spec.controllerConfig = controllerConfig;
+  }
+
+  return result;
+}

src/mcplocal/src/proxymodel/stage-registry.ts

@@ -0,0 +1,70 @@
+/**
+ * Stage registry.
+ * Resolves stage names to handlers. Built-in stages are always available.
+ * Custom stages can be loaded from ~/.mcpctl/stages/ at runtime.
+ */
+import type { StageHandler } from './types.js';
+import { BUILT_IN_STAGES } from './stages/index.js';
+
+const customStages = new Map<string, StageHandler>();
+
+/**
+ * Load custom stages from a directory.
+ * Each .js file exports a default StageHandler.
+ */
+export async function loadCustomStages(dir: string): Promise<void> {
+  const { readdir } = await import('node:fs/promises');
+  const { join } = await import('node:path');
+  const { pathToFileURL } = await import('node:url');
+
+  customStages.clear();
+  try {
+    const files = await readdir(dir);
+    for (const file of files) {
+      if (!file.endsWith('.js')) continue;
+      const name = file.replace(/\.js$/, '');
+      try {
+        const mod = await import(pathToFileURL(join(dir, file)).href) as { default?: StageHandler };
+        if (typeof mod.default === 'function') {
+          customStages.set(name, mod.default);
+        } else {
+          console.warn(`[stage-registry] ${file} does not export a default function, skipping`);
+        }
+      } catch (err) {
+        console.warn(`[stage-registry] Failed to load ${file}: ${(err as Error).message}`);
+      }
+    }
+  } catch {
+    // Directory doesn't exist — no custom stages
+  }
+}
+
+/** Get a stage handler by name. Custom stages override built-ins. */
+export function getStage(name: string): StageHandler | null {
+  return customStages.get(name) ?? BUILT_IN_STAGES.get(name) ?? null;
+}
+
+/** List all available stages with their source. */
+export function listStages(): { name: string; source: 'built-in' | 'local' }[] {
+  const result: { name: string; source: 'built-in' | 'local' }[] = [];
+
+  for (const name of BUILT_IN_STAGES.keys()) {
+    result.push({
+      name,
+      source: customStages.has(name) ? 'local' : 'built-in',
+    });
+  }
+
+  for (const name of customStages.keys()) {
+    if (!BUILT_IN_STAGES.has(name)) {
+      result.push({ name, source: 'local' });
+    }
+  }
+
+  return result;
+}
+
+/** Clear all custom stages (for testing). */
+export function clearCustomStages(): void {
+  customStages.clear();
+}

src/mcplocal/src/proxymodel/stages/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Built-in stages registry.
+ * Maps stage names to their handler implementations.
+ */
+import type { StageHandler } from '../types.js';
+import passthrough from './passthrough.js';
+import paginate from './paginate.js';
+import sectionSplit from './section-split.js';
+import summarizeTree from './summarize-tree.js';
+
+export const BUILT_IN_STAGES: ReadonlyMap<string, StageHandler> = new Map([
+  ['passthrough', passthrough],
+  ['paginate', paginate],
+  ['section-split', sectionSplit],
+  ['summarize-tree', summarizeTree],
+]);

src/mcplocal/src/proxymodel/stages/paginate.ts

@@ -0,0 +1,110 @@
+/**
+ * Built-in stage: paginate
+ * Splits content into pages by character size with navigation instructions.
+ * When an LLM is available, generates descriptive page titles; otherwise
+ * falls back to generic "Page N" labels.
+ *
+ * Config:
+ *   pageSize: number (chars per page, default 8000)
+ *   previewChars: number (chars per page sent to LLM for title generation, default 300)
+ */
+import type { StageHandler, StageContext, Section } from '../types.js';
+
+const handler: StageHandler = async (content, ctx) => {
+  const pageSize = (ctx.config.pageSize as number | undefined) ?? 8000;
+
+  // Don't paginate small content
+  if (content.length <= pageSize) {
+    return { content };
+  }
+
+  const pages = splitPages(content, pageSize);
+
+  if (pages.length <= 1) {
+    return { content };
+  }
+
+  const titles = await generatePageTitles(pages, ctx);
+
+  const sections: Section[] = pages.map((page, i) => ({
+    id: `page-${i + 1}`,
+    title: titles[i] ?? `Page ${i + 1}`,
+    content: page,
+  }));
+
+  const toc = sections.map((s, i) =>
+    `[${s.id}] ${s.title} (${pages[i]!.length} chars)`,
+  ).join('\n');
+
+  return {
+    content: `Content split into ${sections.length} pages (${content.length} total chars):\n${toc}\n\nUse section parameter to read a specific page.`,
+    sections,
+  };
+};
+
+/**
+ * Generate descriptive titles for each page using LLM.
+ * Falls back to generic "Page N" titles if LLM is unavailable or fails.
+ */
+async function generatePageTitles(pages: string[], ctx: StageContext): Promise<string[]> {
+  const fallback = pages.map((_, i) => `Page ${i + 1}`);
+
+  if (!ctx.llm.available()) {
+    return fallback;
+  }
+
+  const previewChars = (ctx.config.previewChars as number | undefined) ?? 300;
+  const cacheKey = `paginate-titles:${ctx.cache.hash(ctx.originalContent)}:${pages.length}`;
+
+  try {
+    const cached = await ctx.cache.getOrCompute(cacheKey, async () => {
+      const previews = pages.map((page, i) => {
+        const preview = page.slice(0, previewChars).trim();
+        return `--- Page ${i + 1} (${page.length} chars) ---\n${preview}`;
+      }).join('\n\n');
+
+      const result = await ctx.llm.complete(
+        `Generate a short descriptive title (max 60 chars) for each page based on its content preview. ` +
+        `Return ONLY a JSON array of strings, one title per page. No markdown, no explanation.\n\n` +
+        `${previews}`,
+        { maxTokens: pages.length * 30 },
+      );
+
+      // Parse JSON array from response
+      const match = result.match(/\[[\s\S]*\]/);
+      if (!match) throw new Error('No JSON array in response');
+      const titles = JSON.parse(match[0]) as string[];
+      if (!Array.isArray(titles) || titles.length !== pages.length) {
+        throw new Error(`Expected ${pages.length} titles, got ${titles.length}`);
+      }
+      return JSON.stringify(titles);
+    });
+
+    return JSON.parse(cached) as string[];
+  } catch (err) {
+    ctx.log.warn(`Smart page titles failed, using generic: ${(err as Error).message}`);
+    return fallback;
+  }
+}
+
+function splitPages(content: string, pageSize: number): string[] {
+  const pages: string[] = [];
+  let offset = 0;
+
+  while (offset < content.length) {
+    let end = Math.min(offset + pageSize, content.length);
+    // Try to break at a newline boundary
+    if (end < content.length) {
+      const lastNewline = content.lastIndexOf('\n', end);
+      if (lastNewline > offset) {
+        end = lastNewline + 1;
+      }
+    }
+    pages.push(content.slice(offset, end));
+    offset = end;
+  }
+
+  return pages;
+}
+
+export default handler;

src/mcplocal/src/proxymodel/stages/passthrough.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in stage: passthrough
+ * Returns content unchanged. Used as the default stage for projects
+ * that don't need content transformation.
+ */
+import type { StageHandler } from '../types.js';
+
+const handler: StageHandler = async (content, _ctx) => {
+  return { content };
+};
+
+export default handler;

src/mcplocal/src/proxymodel/stages/section-split.ts

@@ -0,0 +1,304 @@
+/**
+ * Built-in stage: section-split
+ * Splits content into named sections based on content type.
+ *
+ * - Prose/Markdown → split on ## headers
+ * - JSON array → split on array elements
+ * - JSON object → split on top-level keys
+ * - YAML → split on top-level keys
+ * - Code → split on function/class boundaries
+ *
+ * Config:
+ *   minSectionSize: number (don't split tiny sections, default 500)
+ *   maxSectionSize: number (re-split large sections, default 15000)
+ */
+import type { StageHandler, Section } from '../types.js';
+import { detectContentType } from '../content-type.js';
+
+const handler: StageHandler = async (content, ctx) => {
+  const minSize = (ctx.config.minSectionSize as number | undefined) ?? 500;
+  const maxSize = (ctx.config.maxSectionSize as number | undefined) ?? 15000;
+
+  // Don't split tiny content
+  if (content.length < minSize * 2) {
+    return { content };
+  }
+
+  const contentType = detectContentType(content);
+  let sections: Section[];
+
+  switch (contentType) {
+    case 'json':
+      sections = splitJson(content);
+      break;
+    case 'yaml':
+      sections = splitYaml(content);
+      break;
+    case 'xml':
+      sections = splitXml(content);
+      break;
+    case 'code':
+      sections = splitCode(content);
+      break;
+    case 'prose':
+    default:
+      sections = splitProse(content);
+      break;
+  }
+
+  // Filter out tiny sections (merge into previous)
+  sections = mergeTinySections(sections, minSize);
+
+  // Re-split oversized sections
+  sections = splitOversized(sections, maxSize);
+
+  if (sections.length <= 1) {
+    return { content };
+  }
+
+  // Build table of contents
+  const toc = sections.map((s) => {
+    const sizeHint = s.content.length > 1000
+      ? ` (${Math.round(s.content.length / 1000)}K chars)`
+      : ` (${s.content.length} chars)`;
+    return `[${s.id}] ${s.title}${sizeHint}`;
+  }).join('\n');
+
+  return {
+    content: `${sections.length} sections (${contentType}):\n${toc}\n\nUse section parameter to read a specific section.`,
+    sections,
+  };
+};
+
+// ── JSON Splitting ──────────────────────────────────────────────────
+
+function splitJson(content: string): Section[] {
+  try {
+    const parsed = JSON.parse(content) as unknown;
+
+    if (Array.isArray(parsed)) {
+      return splitJsonArray(parsed);
+    }
+    if (parsed !== null && typeof parsed === 'object') {
+      return splitJsonObject(parsed as Record<string, unknown>);
+    }
+  } catch {
+    // Invalid JSON — fall through to prose
+  }
+  return splitProse(content);
+}
+
+function splitJsonArray(arr: unknown[]): Section[] {
+  return arr.map((item, i) => {
+    const obj = item as Record<string, unknown> | undefined;
+    const label = obj?.label ?? obj?.name ?? obj?.id ?? obj?.title ?? obj?.type;
+    const id = String(label ?? `item-${i}`).toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    const title = label ? String(label) : `Item ${i + 1}`;
+    return {
+      id,
+      title,
+      content: JSON.stringify(item, null, 2),
+    };
+  });
+}
+
+function splitJsonObject(obj: Record<string, unknown>): Section[] {
+  return Object.entries(obj).map(([key, value]) => ({
+    id: key.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+    title: key,
+    content: JSON.stringify(value, null, 2),
+  }));
+}
+
+// ── YAML Splitting ──────────────────────────────────────────────────
+
+function splitYaml(content: string): Section[] {
+  const sections: Section[] = [];
+  const lines = content.split('\n');
+  let currentKey = '';
+  let currentLines: string[] = [];
+
+  for (const line of lines) {
+    const match = /^([a-zA-Z_][a-zA-Z0-9_-]*):\s/.exec(line);
+    if (match) {
+      if (currentKey && currentLines.length > 0) {
+        sections.push({
+          id: currentKey.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+          title: currentKey,
+          content: currentLines.join('\n'),
+        });
+      }
+      currentKey = match[1]!;
+      currentLines = [line];
+    } else {
+      currentLines.push(line);
+    }
+  }
+
+  if (currentKey && currentLines.length > 0) {
+    sections.push({
+      id: currentKey.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+      title: currentKey,
+      content: currentLines.join('\n'),
+    });
+  }
+
+  return sections;
+}
+
+// ── XML Splitting ───────────────────────────────────────────────────
+
+function splitXml(content: string): Section[] {
+  // Simple regex-based splitting on top-level elements
+  const sections: Section[] = [];
+  const tagRegex = /<([a-zA-Z][a-zA-Z0-9]*)[^>]*>[\s\S]*?<\/\1>/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = tagRegex.exec(content)) !== null) {
+    const tagName = match[1]!;
+    sections.push({
+      id: tagName.toLowerCase(),
+      title: tagName,
+      content: match[0],
+    });
+  }
+
+  if (sections.length === 0) {
+    return splitProse(content);
+  }
+
+  return sections;
+}
+
+// ── Code Splitting ──────────────────────────────────────────────────
+
+function splitCode(content: string): Section[] {
+  const sections: Section[] = [];
+  // Split on function/class/export boundaries
+  const boundaries = /^(?:export\s+)?(?:async\s+)?(?:function|class|const|let|var|def|module)\s+(\w+)/gm;
+  let lastIndex = 0;
+  let lastName = 'preamble';
+  let match: RegExpExecArray | null;
+
+  while ((match = boundaries.exec(content)) !== null) {
+    if (match.index > lastIndex) {
+      const block = content.slice(lastIndex, match.index).trim();
+      if (block) {
+        sections.push({
+          id: lastName.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+          title: lastName,
+          content: block,
+        });
+      }
+    }
+    lastName = match[1]!;
+    lastIndex = match.index;
+  }
+
+  // Remaining content
+  if (lastIndex < content.length) {
+    const block = content.slice(lastIndex).trim();
+    if (block) {
+      sections.push({
+        id: lastName.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+        title: lastName,
+        content: block,
+      });
+    }
+  }
+
+  return sections;
+}
+
+// ── Prose/Markdown Splitting ────────────────────────────────────────
+
+function splitProse(content: string): Section[] {
+  const sections: Section[] = [];
+  // Split on markdown ## headers (any level)
+  const parts = content.split(/^(#{1,4}\s+.+)$/m);
+
+  let currentTitle = 'Introduction';
+  let currentContent = '';
+
+  for (const part of parts) {
+    const headerMatch = /^#{1,4}\s+(.+)$/.exec(part);
+    if (headerMatch) {
+      if (currentContent.trim()) {
+        sections.push({
+          id: currentTitle.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+          title: currentTitle,
+          content: currentContent.trim(),
+        });
+      }
+      currentTitle = headerMatch[1]!.trim();
+      currentContent = '';
+    } else {
+      currentContent += part;
+    }
+  }
+
+  if (currentContent.trim()) {
+    sections.push({
+      id: currentTitle.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+      title: currentTitle,
+      content: currentContent.trim(),
+    });
+  }
+
+  return sections;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function mergeTinySections(sections: Section[], minSize: number): Section[] {
+  if (sections.length <= 1) return sections;
+
+  const merged: Section[] = [];
+  for (const section of sections) {
+    const prev = merged[merged.length - 1];
+    if (prev && section.content.length < minSize) {
+      prev.content += '\n\n' + section.content;
+      prev.title += ' + ' + section.title;
+    } else {
+      merged.push({ ...section });
+    }
+  }
+  return merged;
+}
+
+function splitOversized(sections: Section[], maxSize: number): Section[] {
+  const result: Section[] = [];
+  for (const section of sections) {
+    if (section.content.length <= maxSize) {
+      result.push(section);
+      continue;
+    }
+    // Split oversized section by paragraph breaks
+    const paragraphs = section.content.split(/\n\n+/);
+    let chunk = '';
+    let partNum = 1;
+
+    for (const para of paragraphs) {
+      if (chunk.length + para.length > maxSize && chunk) {
+        result.push({
+          id: `${section.id}-part${partNum}`,
+          title: `${section.title} (part ${partNum})`,
+          content: chunk.trim(),
+        });
+        partNum++;
+        chunk = '';
+      }
+      chunk += (chunk ? '\n\n' : '') + para;
+    }
+    if (chunk.trim()) {
+      result.push({
+        id: partNum > 1 ? `${section.id}-part${partNum}` : section.id,
+        title: partNum > 1 ? `${section.title} (part ${partNum})` : section.title,
+        content: chunk.trim(),
+      });
+    }
+  }
+  return result;
+}
+
+export default handler;

src/mcplocal/src/proxymodel/stages/summarize-tree.ts

@@ -0,0 +1,282 @@
+/**
+ * Built-in stage: summarize-tree
+ * Recursive summarization with structural summaries for programmatic content
+ * and LLM summaries for prose. Creates a navigable hierarchy.
+ *
+ * Expects input from section-split (sections in StageResult), or operates
+ * on raw content if no prior stage produced sections.
+ *
+ * Config:
+ *   maxSummaryTokens: number (per-section summary length, default 200)
+ *   maxGroupSize: number (group N sections before summarizing group, default 5)
+ *   maxDepth: number (max nesting levels, default 3)
+ *   leafIsFullContent: boolean (leaf drill-down returns raw content, default true)
+ */
+import type { StageHandler, Section } from '../types.js';
+import { detectContentType } from '../content-type.js';
+
+const handler: StageHandler = async (content, ctx) => {
+  const maxTokens = (ctx.config.maxSummaryTokens as number | undefined) ?? 200;
+  const maxGroup = (ctx.config.maxGroupSize as number | undefined) ?? 5;
+  const maxDepth = (ctx.config.maxDepth as number | undefined) ?? 3;
+
+  // If content is small, just return it unchanged
+  if (content.length < 2000) {
+    return { content };
+  }
+
+  // Parse sections from structured content (section-split output)
+  // The pipeline executor passes sections from prior stages; for now we
+  // parse from the content if it looks like a section-split ToC, or
+  // treat the whole content as one section.
+  const sections = parseSectionsFromContent(ctx.originalContent);
+
+  if (sections.length <= 1) {
+    // Single block — try to summarize directly
+    if (!ctx.llm.available()) {
+      return { content };
+    }
+
+    const summary = await cachedSummarize(ctx, ctx.originalContent, maxTokens);
+    return {
+      content: summary + '\n\nUse section parameter with id "full" to read the complete content.',
+      sections: [{ id: 'full', title: 'Full Content', content: ctx.originalContent }],
+    };
+  }
+
+  // Build the summary tree
+  const tree = await buildTree(sections, ctx, { maxTokens, maxGroup, maxDepth, depth: 0 });
+
+  // Format top-level ToC
+  const toc = tree.map((s) => {
+    const childHint = s.children?.length
+      ? `\n    → ${s.children.length} sub-sections available`
+      : '';
+    return `[${s.id}] ${s.title}${childHint}`;
+  }).join('\n');
+
+  return {
+    content: `${tree.length} sections:\n${toc}\n\nUse section parameter to read details.`,
+    sections: tree,
+  };
+};
+
+interface TreeOpts {
+  maxTokens: number;
+  maxGroup: number;
+  maxDepth: number;
+  depth: number;
+}
+
+async function buildTree(
+  sections: Section[],
+  ctx: import('../types.js').StageContext,
+  opts: TreeOpts,
+): Promise<Section[]> {
+  const result: Section[] = [];
+
+  for (const section of sections) {
+    const contentType = detectContentType(section.content);
+    let summary: string;
+
+    if (contentType === 'json' || contentType === 'yaml' || contentType === 'xml') {
+      // Structural summary — no LLM needed
+      summary = structuralSummary(section.content, contentType);
+    } else if (ctx.llm.available()) {
+      // LLM summary for prose/code
+      summary = await cachedSummarize(ctx, section.content, opts.maxTokens);
+    } else {
+      // No LLM — use first line as summary
+      summary = (section.content.split('\n')[0] ?? '').slice(0, 200);
+    }
+
+    const node: Section = {
+      id: section.id,
+      title: (summary.split('\n')[0] ?? '').slice(0, 100),
+      content: section.content,
+    };
+
+    // If section is large and we haven't hit max depth, recursively split
+    if (section.content.length > 5000 && opts.depth < opts.maxDepth) {
+      const subSections = splitIntoSubSections(section.content);
+      if (subSections.length > 1) {
+        node.children = await buildTree(subSections, ctx, {
+          ...opts,
+          depth: opts.depth + 1,
+        });
+        // Replace content with sub-summary for non-leaf nodes
+        const childToc = node.children.map((c) => `  [${c.id}] ${c.title}`).join('\n');
+        node.content = `${summary}\n\n${node.children.length} sub-sections:\n${childToc}`;
+      }
+    }
+
+    result.push(node);
+  }
+
+  // If too many sections at this level, group them
+  if (result.length > opts.maxGroup && ctx.llm.available()) {
+    return groupSections(result, ctx, opts);
+  }
+
+  return result;
+}
+
+async function cachedSummarize(
+  ctx: import('../types.js').StageContext,
+  content: string,
+  maxTokens: number,
+): Promise<string> {
+  const key = `summary:${ctx.cache.hash(content)}:${maxTokens}`;
+  return ctx.cache.getOrCompute(key, async () => {
+    return ctx.llm.complete(
+      `Summarize the following in about ${maxTokens} tokens. ` +
+      `Preserve all items marked MUST, REQUIRED, or CRITICAL verbatim. ` +
+      `Be specific — mention names, IDs, counts, key values.\n\n${content}`,
+      { maxTokens },
+    );
+  });
+}
+
+function structuralSummary(content: string, type: string): string {
+  try {
+    if (type === 'json') {
+      const parsed = JSON.parse(content) as unknown;
+      if (Array.isArray(parsed)) {
+        const sample = parsed.slice(0, 3).map((item) => {
+          const obj = item as Record<string, unknown>;
+          const label = obj.name ?? obj.label ?? obj.id ?? obj.type;
+          return label ? String(label) : JSON.stringify(item).slice(0, 50);
+        });
+        const suffix = parsed.length > 3 ? `, ... +${parsed.length - 3} more` : '';
+        return `JSON array (${parsed.length} items): ${sample.join(', ')}${suffix}`;
+      }
+      if (parsed && typeof parsed === 'object') {
+        const keys = Object.keys(parsed as object);
+        const suffix = keys.length > 5 ? `, ... +${keys.length - 5} more` : '';
+        return `JSON object (${keys.length} keys): ${keys.slice(0, 5).join(', ')}${suffix}`;
+      }
+    }
+  } catch {
+    // Fall through
+  }
+  return `${type} content (${content.length} chars)`;
+}
+
+function parseSectionsFromContent(content: string): Section[] {
+  const contentType = detectContentType(content);
+
+  if (contentType === 'json') {
+    try {
+      const parsed = JSON.parse(content) as unknown;
+      if (Array.isArray(parsed) && parsed.length > 1) {
+        return parsed.map((item, i) => {
+          const obj = item as Record<string, unknown>;
+          const label = String(obj.label ?? obj.name ?? obj.id ?? `item-${i}`);
+          return {
+            id: label.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+            title: label,
+            content: JSON.stringify(item, null, 2),
+          };
+        });
+      }
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        const entries = Object.entries(parsed as Record<string, unknown>);
+        if (entries.length > 1) {
+          return entries.map(([key, value]) => ({
+            id: key.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+            title: key,
+            content: JSON.stringify(value, null, 2),
+          }));
+        }
+      }
+    } catch {
+      // Fall through
+    }
+  }
+
+  if (contentType === 'prose') {
+    const parts = content.split(/^(#{1,4}\s+.+)$/m);
+    if (parts.length > 2) {
+      const sections: Section[] = [];
+      let title = 'Introduction';
+      let body = '';
+      for (const part of parts) {
+        const m = /^#{1,4}\s+(.+)$/.exec(part);
+        if (m) {
+          if (body.trim()) {
+            sections.push({
+              id: title.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+              title,
+              content: body.trim(),
+            });
+          }
+          title = m[1]!.trim();
+          body = '';
+        } else {
+          body += part;
+        }
+      }
+      if (body.trim()) {
+        sections.push({
+          id: title.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
+          title,
+          content: body.trim(),
+        });
+      }
+      return sections;
+    }
+  }
+
+  return [{ id: 'content', title: 'Content', content }];
+}
+
+function splitIntoSubSections(content: string): Section[] {
+  const contentType = detectContentType(content);
+  const sections = parseSectionsFromContent(content);
+  if (sections.length > 1) return sections;
+
+  // Fall back to paragraph splitting for prose
+  if (contentType === 'prose') {
+    const paragraphs = content.split(/\n\n+/);
+    if (paragraphs.length > 2) {
+      return paragraphs.map((p, i) => ({
+        id: `para-${i + 1}`,
+        title: (p.split('\n')[0] ?? '').slice(0, 60),
+        content: p,
+      }));
+    }
+  }
+
+  return [{ id: 'content', title: 'Content', content }];
+}
+
+async function groupSections(
+  sections: Section[],
+  ctx: import('../types.js').StageContext,
+  opts: TreeOpts,
+): Promise<Section[]> {
+  const groups: Section[] = [];
+  for (let i = 0; i < sections.length; i += opts.maxGroup) {
+    const chunk = sections.slice(i, i + opts.maxGroup);
+    if (chunk.length === 1) {
+      groups.push(chunk[0]!);
+      continue;
+    }
+
+    const groupContent = chunk.map((s) => `[${s.id}] ${s.title}`).join('\n');
+    const groupId = `group-${Math.floor(i / opts.maxGroup) + 1}`;
+    const groupTitle = ctx.llm.available()
+      ? await cachedSummarize(ctx, groupContent, 50)
+      : `Group ${Math.floor(i / opts.maxGroup) + 1} (${chunk.length} sections)`;
+
+    groups.push({
+      id: groupId,
+      title: (groupTitle.split('\n')[0] ?? '').slice(0, 80),
+      content: groupContent,
+      children: chunk,
+    });
+  }
+  return groups;
+}
+
+export default handler;

src/mcplocal/src/proxymodel/types.ts

@@ -0,0 +1,213 @@
+/**
+ * ProxyModel Public API — the contract that stage authors write against.
+ *
+ * Stage authors import ONLY from this module. They never import mcpctl
+ * internals. The framework wires up the services (llm, cache, log) so
+ * stages can focus on content transformation.
+ *
+ * Two handler types:
+ *   StageHandler  — pure content transformation (text in → text out)
+ *   SessionController — method-level hooks with per-session state
+ */
+
+// ── Content Stage Contract ──────────────────────────────────────────
+
+/**
+ * A stage is the atomic unit of content transformation.
+ * It receives content (from the previous stage or raw upstream)
+ * and returns transformed content, optionally with drill-down sections.
+ */
+export interface StageHandler {
+  (content: string, ctx: StageContext): Promise<StageResult>;
+}
+
+/** Services the framework provides to every stage. */
+export interface StageContext {
+  /** What kind of content is being processed */
+  contentType: 'prompt' | 'toolResult' | 'resource';
+  /** Identifier: prompt name, "server/tool", or resource URI */
+  sourceName: string;
+  /** Project this content belongs to */
+  projectName: string;
+  /** Current MCP session ID */
+  sessionId: string;
+
+  /** The original unmodified content (even if a previous stage changed it) */
+  originalContent: string;
+
+  // Platform services — stages use these, framework provides them
+  llm: LLMProvider;
+  cache: CacheProvider;
+  log: StageLogger;
+
+  /** Stage-specific configuration from the proxymodel YAML */
+  config: Record<string, unknown>;
+}
+
+export interface StageResult {
+  /** The transformed content */
+  content: string;
+  /** Optional: section index for drill-down navigation */
+  sections?: Section[];
+  /** Optional: metrics, debug info, or other stage-specific data */
+  metadata?: Record<string, unknown>;
+}
+
+/** A named section of content, addressable for drill-down. */
+export interface Section {
+  /** Addressable key (e.g. "token-handling", "flow1.function-1") */
+  id: string;
+  /** Human-readable label */
+  title: string;
+  /** Full section content (served when client drills down) */
+  content: string;
+  /** Nested sub-sections for hierarchical drill-down */
+  children?: Section[];
+}
+
+// ── Session Controller Contract ─────────────────────────────────────
+
+/**
+ * A session controller manages method-level hooks and per-session state.
+ * It intercepts JSON-RPC methods, registers virtual tools, and dispatches
+ * notifications. The existing gated session system is a session controller.
+ *
+ * Not yet a public API — designed as an internal interface that can be
+ * extracted later without rewriting existing code.
+ */
+export interface SessionController {
+  /** Called once when session starts (initialize) */
+  onInitialize?(ctx: SessionContext): Promise<InitializeHook>;
+
+  /** Called when tools/list is requested — can modify the tool list */
+  onToolsList?(tools: ToolDefinition[], ctx: SessionContext): Promise<ToolDefinition[]>;
+
+  /** Called before a tool call is routed — can intercept and handle it */
+  onToolCall?(toolName: string, args: unknown, ctx: SessionContext): Promise<InterceptResult | null>;
+
+  /** Called after a tool call returns — can transform the result */
+  onToolResult?(toolName: string, result: unknown, ctx: SessionContext): Promise<unknown>;
+
+  /** Called when session ends */
+  onClose?(ctx: SessionContext): Promise<void>;
+}
+
+export interface SessionContext extends StageContext {
+  /** Per-session mutable state (persists across requests in a session) */
+  state: Map<string, unknown>;
+
+  /** Register a virtual tool that this controller handles */
+  registerTool(tool: ToolDefinition, handler: VirtualToolHandler): void;
+
+  /** Queue a notification to the MCP client */
+  queueNotification(method: string, params?: unknown): void;
+
+  /** Access the prompt index (for content selection) */
+  prompts: PromptIndex;
+}
+
+export interface InitializeHook {
+  /** Additional instructions to append to the initialize response */
+  instructions?: string;
+}
+
+export interface InterceptResult {
+  /** Replaces the normal tool call response */
+  result: unknown;
+  /** If true, emit tools/list_changed after this intercept */
+  ungate?: boolean;
+}
+
+export type VirtualToolHandler = (args: unknown, ctx: SessionContext) => Promise<unknown>;
+
+// ── Platform Service Interfaces ─────────────────────────────────────
+
+/**
+ * LLM provider exposed to stages. Wraps the internal ProviderRegistry
+ * into a simple interface — stages don't care which model is running.
+ */
+export interface LLMProvider {
+  /** Simple completion — send a prompt, get text back */
+  complete(prompt: string, options?: LLMCompleteOptions): Promise<string>;
+  /** Check if an LLM provider is configured and available */
+  available(): boolean;
+}
+
+export interface LLMCompleteOptions {
+  system?: string;
+  maxTokens?: number;
+}
+
+/**
+ * Content-addressed cache. The framework handles top-level stage caching,
+ * but stages can also cache their own intermediate results.
+ */
+export interface CacheProvider {
+  /** Get a cached value by key, or compute and cache it */
+  getOrCompute(key: string, compute: () => Promise<string>): Promise<string>;
+  /** Hash content for use as a cache key component */
+  hash(content: string): string;
+  /** Manually read from cache (returns null on miss) */
+  get(key: string): Promise<string | null>;
+  /** Manually write to cache */
+  set(key: string, value: string): Promise<void>;
+}
+
+/** Structured logging tied to session/stage. */
+export interface StageLogger {
+  debug(msg: string): void;
+  info(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+}
+
+// ── ProxyModel Definition ───────────────────────────────────────────
+
+/** Parsed representation of a proxymodel YAML file. */
+export interface ProxyModelDefinition {
+  name: string;
+  /** Session controller name. 'gate' = gated sessions, 'none' = no controller */
+  controller: string;
+  /** Config passed to the session controller */
+  controllerConfig: Record<string, unknown>;
+  /** Ordered pipeline of content stages */
+  stages: StageDefinition[];
+  /** Which content types this model processes */
+  appliesTo: ContentType[];
+  /** Whether the framework should cache stage results */
+  cacheable: boolean;
+  /** Where this model was loaded from */
+  source: 'built-in' | 'local';
+}
+
+export interface StageDefinition {
+  /** Stage name — resolved local → built-in */
+  type: string;
+  /** Stage-specific configuration passed as ctx.config */
+  config: Record<string, unknown>;
+}
+
+export type ContentType = 'prompt' | 'toolResult' | 'resource';
+
+// ── Supporting Types ────────────────────────────────────────────────
+
+export interface ToolDefinition {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown> | unknown;
+}
+
+export interface PromptIndex {
+  /** All available prompts for this project */
+  list(): PromptIndexEntry[];
+  /** Find prompts matching tags */
+  match(tags: string[]): PromptIndexEntry[];
+}
+
+export interface PromptIndexEntry {
+  name: string;
+  summary: string;
+  priority: number;
+  tags: string[];
+  content?: string;
+}