@vibecodetown/mcp-server 1.3.1 → 1.5.0

package/build/hub/dashboard_routes.js

@@ -0,0 +1,307 @@
+/**
+ * Dashboard Routes — Fastify plugin porting Dashboard's native HTTP routes.
+ *
+ * Migrated from dashboard/server.ts (native http.createServer)
+ * to Fastify plugin for Hub unification.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as crypto from 'node:crypto';
+import { createLivenessHandler, createReadinessHandler, serverRunningChecker, } from '../health/index.js';
+import { SyncPacketBuilder, } from '../sync-packet-builder.js';
+import { createSignalStreamHandler } from '../dashboard/signal_stream.js';
+// ============================================================================
+// Helpers (from dashboard/server.ts)
+// ============================================================================
+const DEFAULT_STORAGE_DIR = path.join(os.homedir(), '.vibe', 'dashboard');
+function ensureDir(dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+function parseBearerToken(raw) {
+    const m = String(raw ?? '').match(/^Bearer\s+(.+)$/i);
+    return m?.[1]?.trim() || null;
+}
+function verifySignatureIfConfigured(packet) {
+    const publicKeyPem = (process.env.VIBE_CLOUD_SYNC_SIGNING_PUBLIC_KEY_PEM || '').trim();
+    if (!publicKeyPem)
+        return { ok: true };
+    if (!packet.signature)
+        return { ok: false, message: 'missing_signature' };
+    try {
+        const payload = Buffer.from(`${packet.run_id}.${packet.iv}.${packet.tag}.${packet.content}.${packet.version}`, 'utf-8');
+        const sig = Buffer.from(packet.signature, 'base64url');
+        const ok = crypto.verify(null, payload, crypto.createPublicKey(publicKeyPem), sig);
+        if (!ok)
+            return { ok: false, message: 'invalid_signature' };
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, message: err instanceof Error ? err.message : String(err) };
+    }
+}
+function listRunFiles(storageDir) {
+    const dir = path.join(storageDir, 'runs');
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+}
+function loadRunPacket(storageDir, runId) {
+    const file = path.join(storageDir, 'runs', `${runId}.json`);
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function saveRunPacket(storageDir, packet) {
+    ensureDir(path.join(storageDir, 'runs'));
+    const file = path.join(storageDir, 'runs', `${packet.metadata.run_id}.json`);
+    fs.writeFileSync(file, JSON.stringify(packet, null, 2), 'utf-8');
+}
+// ============================================================================
+// Fastify Plugin
+// ============================================================================
+export async function registerDashboardRoutes(app, opts = {}) {
+    const storageDir = opts.storageDir ?? process.env.VIBE_DASHBOARD_DIR ?? DEFAULT_STORAGE_DIR;
+    const authToken = opts.authToken ?? (process.env.VIBE_CLOUD_SYNC_TOKEN || null);
+    const secretKey = opts.secretKey ?? authToken;
+    const maxBodyBytes = opts.maxBodyBytes ?? 1_000_000;
+    const workspaceRoot = opts.workspaceRoot ?? process.env.VIBE_WORKSPACE_ROOT ?? process.cwd();
+    ensureDir(storageDir);
+    ensureDir(path.join(storageDir, 'runs'));
+    const builder = new SyncPacketBuilder();
+    const signalsDir = path.join(workspaceRoot, '.vibe', 'signals');
+    const observerSignalsPath = path.join(workspaceRoot, '.vibe', 'observer', 'signals.v1.jsonl');
+    const signalStream = createSignalStreamHandler(signalsDir, observerSignalsPath);
+    // K8s probes
+    const handleLiveness = createLivenessHandler({
+        version: process.env.npm_package_version,
+        component: 'hub',
+    });
+    const handleReadiness = createReadinessHandler([serverRunningChecker()]);
+    // --- Health probes ---
+    app.get('/healthz', (_req, reply) => {
+        handleLiveness(reply.request.raw, reply.raw);
+        reply.hijack();
+    });
+    app.get('/readyz', async (_req, reply) => {
+        await handleReadiness(reply.request.raw, reply.raw);
+        reply.hijack();
+    });
+    app.get('/api/v1/health', async () => ({ ok: true }));
+    // --- Sync ---
+    app.post('/api/v1/sync', async (req, reply) => {
+        try {
+            const bearer = parseBearerToken(req.headers.authorization);
+            if (authToken && bearer !== authToken) {
+                return reply.status(401).send({ ok: false, error: 'unauthorized' });
+            }
+            const raw = req.body;
+            const encrypted = raw;
+            if (!encrypted || typeof encrypted !== 'object') {
+                return reply.status(400).send({ ok: false, error: 'invalid_json' });
+            }
+            if (!encrypted.run_id || !encrypted.iv || !encrypted.tag || !encrypted.content || !encrypted.version) {
+                return reply.status(400).send({ ok: false, error: 'invalid_encrypted_packet' });
+            }
+            const bodyStr = JSON.stringify(raw);
+            if (bodyStr.length > maxBodyBytes) {
+                return reply.status(413).send({ ok: false, error: 'body_too_large' });
+            }
+            const sigCheck = verifySignatureIfConfigured(encrypted);
+            if (!sigCheck.ok) {
+                return reply.status(400).send({ ok: false, error: 'signature_invalid', message: sigCheck.message });
+            }
+            const key = (secretKey || bearer || '').trim();
+            if (!key) {
+                return reply.status(400).send({ ok: false, error: 'missing_secret_key' });
+            }
+            const packet = builder.decrypt(encrypted, key);
+            saveRunPacket(storageDir, packet);
+            return { ok: true, run_id: packet.metadata.run_id, received_at: new Date().toISOString() };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return reply.status(500).send({ ok: false, error: 'sync_failed', message: msg });
+        }
+    });
+    // --- Runs ---
+    app.get('/api/v1/runs', async () => {
+        const runs = listRunFiles(storageDir).map(f => f.replace(/\.json$/, '')).sort();
+        return { runs };
+    });
+    app.get('/api/v1/runs/:id', async (req, reply) => {
+        const runId = req.params.id;
+        const pkt = loadRunPacket(storageDir, runId);
+        if (!pkt)
+            return reply.status(404).send({ ok: false, error: 'not_found' });
+        return pkt;
+    });
+    // --- Stats ---
+    app.get('/api/v1/stats/roi', async () => {
+        const files = listRunFiles(storageDir);
+        let tokensSaved = 0, inputTokens = 0, outputTokens = 0;
+        for (const f of files) {
+            const pkt = loadRunPacket(storageDir, f.replace(/\.json$/, ''));
+            if (!pkt)
+                continue;
+            tokensSaved += pkt.metrics?.token_usage?.saved_by_skeleton ?? 0;
+            inputTokens += pkt.metrics?.token_usage?.input ?? 0;
+            outputTokens += pkt.metrics?.token_usage?.output ?? 0;
+        }
+        const dollarSaved = (tokensSaved / 1000) * 0.015;
+        return {
+            period: 'all',
+            total_runs: files.length,
+            metrics: {
+                tokens_saved: tokensSaved,
+                dollar_saved: Number(dollarSaved.toFixed(2)),
+                hours_saved: 0, auto_fixes: 0, auto_fix_success_rate: 0,
+                token_usage: { input: inputTokens, output: outputTokens },
+            },
+            comparison: { vs_last_month: 'n/a', vs_last_quarter: 'n/a' },
+        };
+    });
+    app.get('/api/v1/stats/safety', async () => {
+        const files = listRunFiles(storageDir);
+        const counts = { GO: 0, FIX: 0, BLOCK: 0 };
+        for (const f of files) {
+            const pkt = loadRunPacket(storageDir, f.replace(/\.json$/, ''));
+            const v = pkt?.verdict_summary?.final_verdict;
+            if (v === 'GO' || v === 'FIX' || v === 'BLOCK')
+                counts[v]++;
+        }
+        const total = files.length || 0;
+        const passRate = total > 0 ? counts.GO / total : 0;
+        return {
+            period: 'all', total_runs: total,
+            verdicts: counts,
+            pass_rate: Number((passRate * 100).toFixed(2)),
+            trend: 'unknown',
+        };
+    });
+    app.get('/api/v1/stats/violations', async () => {
+        const files = listRunFiles(storageDir);
+        const counts = {};
+        for (const f of files) {
+            const pkt = loadRunPacket(storageDir, f.replace(/\.json$/, ''));
+            if (!pkt)
+                continue;
+            for (const v of pkt.violation_details ?? []) {
+                const key = String(v.type || 'UNKNOWN');
+                counts[key] = (counts[key] ?? 0) + 1;
+            }
+        }
+        const totalViolations = Object.values(counts).reduce((a, b) => a + b, 0);
+        const byType = Object.entries(counts)
+            .sort((a, b) => b[1] - a[1])
+            .map(([type, count]) => ({
+            type, count,
+            percentage: totalViolations > 0 ? Math.round((count / totalViolations) * 100) : 0,
+        }));
+        return { period: 'all', total_violations: totalViolations, by_type: byType, trend: 'unknown' };
+    });
+    // --- License ---
+    app.get('/api/v1/license', async (req) => {
+        const bearer = parseBearerToken(req.headers.authorization);
+        const ok = authToken ? bearer === authToken : true;
+        return { ok, auth_required: Boolean(authToken), plan: authToken ? 'PRO' : 'ALL' };
+    });
+    // --- SSE Signal Stream ---
+    app.get('/api/v1/signals/stream', (_req, reply) => {
+        signalStream.handler(reply.request.raw, reply.raw);
+        reply.hijack();
+    });
+    // --- Monitor HTML ---
+    app.get('/monitor', async (_req, reply) => {
+        return reply.type('text/html').send(MONITOR_HTML);
+    });
+    return { signalCleanup: () => signalStream.cleanup() };
+}
+// ============================================================================
+// Monitor HTML (minimal inline page)
+// ============================================================================
+const MONITOR_HTML = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="UTF-8"><title>Musu Monitor</title>
+<style>body{font-family:system-ui;background:#0f1117;color:#e1e4e8;padding:24px;margin:0}
+#status{width:10px;height:10px;border-radius:50%;background:#f85149;display:inline-block}
+#status.connected{background:#3fb950}
+.row{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:16px}
+.sc{background:#161b22;border:1px solid #30363d;border-radius:8px;padding:16px 20px;min-width:100px}
+.sc .l{font-size:12px;color:#8b949e;margin-bottom:4px}.sc .v{font-size:28px;font-weight:700}
+.section{margin-bottom:20px}
+.section h2{font-size:14px;color:#8b949e;margin:0 0 8px 0;text-transform:uppercase;letter-spacing:1px}
+#updated{font-size:11px;color:#484f58;margin-top:8px}
+</style></head><body>
+<header style="display:flex;align-items:center;gap:12px;margin-bottom:24px">
+<div id="status"></div><h1 style="margin:0">Musu Monitor</h1>
+<span id="conn" style="font-size:12px;color:#484f58">Connecting...</span>
+</header>
+<div class="section"><h2>Signals (Live)</h2>
+<div class="row">
+<div class="sc"><div class="l">Events</div><div class="v" id="c-total">0</div></div>
+<div class="sc"><div class="l">High</div><div class="v" style="color:#f85149" id="c-high">0</div></div>
+<div class="sc"><div class="l">Medium</div><div class="v" style="color:#d29922" id="c-med">0</div></div>
+<div class="sc"><div class="l">Low</div><div class="v" style="color:#3fb950" id="c-low">0</div></div>
+</div></div>
+<div class="section"><h2>Observer (Live)</h2>
+<div class="row">
+<div class="sc"><div class="l">Observer</div><div class="v" id="c-obs">0</div></div>
+<div class="sc"><div class="l">Scout ✓</div><div class="v" style="color:#3fb950" id="c-scout-t">0</div></div>
+<div class="sc"><div class="l">Scout ✗</div><div class="v" style="color:#8b949e" id="c-scout-u">0</div></div>
+</div></div>
+<div class="section"><h2>Stats (Auto-refresh 30s)</h2>
+<div class="row">
+<div class="sc"><div class="l">Runs</div><div class="v" id="s-runs">-</div></div>
+<div class="sc"><div class="l">Pass Rate</div><div class="v" style="color:#3fb950" id="s-pass">-</div></div>
+<div class="sc"><div class="l">GO</div><div class="v" style="color:#3fb950" id="s-go">-</div></div>
+<div class="sc"><div class="l">FIX</div><div class="v" style="color:#d29922" id="s-fix">-</div></div>
+<div class="sc"><div class="l">BLOCK</div><div class="v" style="color:#f85149" id="s-block">-</div></div>
+</div>
+<div class="row">
+<div class="sc"><div class="l">Tokens Saved</div><div class="v" id="s-tokens">-</div></div>
+<div class="sc"><div class="l">$ Saved</div><div class="v" style="color:#3fb950" id="s-dollar">-</div></div>
+</div></div>
+<div id="updated"></div>
+<script>
+(function(){var ct=document.getElementById('c-total'),ch=document.getElementById('c-high'),
+cm=document.getElementById('c-med'),cl=document.getElementById('c-low'),
+co=document.getElementById('c-obs'),cst=document.getElementById('c-scout-t'),csu=document.getElementById('c-scout-u'),
+st=document.getElementById('status'),cn=document.getElementById('conn'),
+up=document.getElementById('updated');
+var c={t:0,h:0,m:0,l:0,obs:0,st:0,su:0},retries=0,maxRetry=6;
+function connect(){var es=new EventSource('/api/v1/signals/stream');
+es.onopen=function(){st.className='connected';cn.textContent='Connected';retries=0;};
+es.onmessage=function(e){try{var s=JSON.parse(e.data);
+c.t++;var r=(s.metadata||{}).risk_level||(s.data||{}).risk_level||'low';
+if(r==='high')c.h++;else if(r==='medium')c.m++;else c.l++;
+if(s._source==='observer'){c.obs++;co.textContent=c.obs;
+if(s.type==='SCOUT_TRIGGERED'){c.st++;cst.textContent=c.st;}
+if(s.type==='SCOUT_UNTRIGGERED'){c.su++;csu.textContent=c.su;}}
+ct.textContent=c.t;ch.textContent=c.h;cm.textContent=c.m;cl.textContent=c.l;
+}catch(x){}};
+es.onerror=function(){st.className='';es.close();retries=Math.min(retries+1,maxRetry);
+var delay=Math.min(1000*Math.pow(2,retries),60000);
+cn.textContent='Reconnecting in '+Math.round(delay/1000)+'s...';setTimeout(connect,delay);};
+}connect();
+function refreshStats(){
+fetch('/api/v1/stats/safety').then(function(r){return r.json();}).then(function(d){
+document.getElementById('s-runs').textContent=d.total_runs||0;
+document.getElementById('s-pass').textContent=(d.pass_rate||0)+'%';
+document.getElementById('s-go').textContent=(d.verdicts||{}).GO||0;
+document.getElementById('s-fix').textContent=(d.verdicts||{}).FIX||0;
+document.getElementById('s-block').textContent=(d.verdicts||{}).BLOCK||0;
+}).catch(function(){});
+fetch('/api/v1/stats/roi').then(function(r){return r.json();}).then(function(d){
+var m=d.metrics||{};
+document.getElementById('s-tokens').textContent=m.tokens_saved||0;
+document.getElementById('s-dollar').textContent='$'+(m.dollar_saved||0);
+}).catch(function(){});
+up.textContent='Last updated: '+new Date().toLocaleTimeString();
+}
+refreshStats();setInterval(refreshStats,30000);
+})();
+</script></body></html>`;

package/build/hub/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hub Module — Unified Dashboard + Companion server.
+ * @module hub
+ */
+export { createHubServer } from './server.js';
+export type { HubConfig, HubHandle } from './types.js';
+export { HUB_DEFAULTS } from './types.js';
+export { startHubIfEnabled, shutdownHub, isHubEnabled, isHubRunning, getHubHandle, getHubUrl, } from './autostart.js';
+export { registerDashboardRoutes } from './dashboard_routes.js';
+export type { DashboardRoutesOptions } from './dashboard_routes.js';

package/build/hub/index.js

@@ -0,0 +1,8 @@
+/**
+ * Hub Module — Unified Dashboard + Companion server.
+ * @module hub
+ */
+export { createHubServer } from './server.js';
+export { HUB_DEFAULTS } from './types.js';
+export { startHubIfEnabled, shutdownHub, isHubEnabled, isHubRunning, getHubHandle, getHubUrl, } from './autostart.js';
+export { registerDashboardRoutes } from './dashboard_routes.js';

package/build/hub/server.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hub Server — Unified Fastify server merging Dashboard + Companion.
+ *
+ * Single port (default 3100) serves:
+ *   - Dashboard API routes (/healthz, /readyz, /api/v1/*, /monitor)
+ *   - Companion chat (/chat SSE, /health)
+ *   - Static files (React SPA)
+ */
+import type { HubConfig, HubHandle } from './types.js';
+export declare function createHubServer(config?: HubConfig): Promise<HubHandle>;

package/build/hub/server.js

@@ -0,0 +1,207 @@
+/**
+ * Hub Server — Unified Fastify server merging Dashboard + Companion.
+ *
+ * Single port (default 3100) serves:
+ *   - Dashboard API routes (/healthz, /readyz, /api/v1/*, /monitor)
+ *   - Companion chat (/chat SSE, /health)
+ *   - Static files (React SPA)
+ */
+import Fastify from 'fastify';
+import * as path from 'node:path';
+import { HUB_DEFAULTS } from './types.js';
+import { registerDashboardRoutes } from './dashboard_routes.js';
+import { handleChat } from '../companion/runtime.js';
+import { encodeSSE } from '../protocol/minp.js';
+import { SignalBridge } from '../kernel/blocks/signal_bridge.js';
+import { getMusuBaseUrl } from '../kernel/musu_endpoint.js';
+import { isGatewayEnabled, getGatewayConfig } from '../gateway/config.js';
+import { registerDispatchRoute } from '../gateway/dispatch_handler.js';
+import { dispatchViaPrime, pollJobResult } from '../gateway/prime_dispatch.js';
+import { startGatewayHeartbeat } from '../gateway/heartbeat.js';
+export async function createHubServer(config = {}) {
+    const host = config.host ?? HUB_DEFAULTS.host;
+    const port = config.port ?? HUB_DEFAULTS.port;
+    const staticDir = config.staticDir ?? path.resolve(new URL('.', import.meta.url).pathname, '../../build/companion-ui');
+    const app = Fastify({ logger: false });
+    // CORS
+    await app.register(import('@fastify/cors'), { origin: '*' });
+    // Dashboard routes (plugin)
+    const { signalCleanup } = await registerDashboardRoutes(app, {
+        storageDir: config.storageDir,
+        workspaceRoot: config.workspaceRoot,
+        authToken: config.authToken,
+        secretKey: config.secretKey,
+        maxBodyBytes: config.maxBodyBytes,
+    });
+    // Signal bridge for companion tool signals
+    const workspaceRoot = config.workspaceRoot ?? process.cwd();
+    const signalBridge = new SignalBridge({ workspaceRoot });
+    const mcpBaseUrl = (config.mcpUrl ?? "http://127.0.0.1:3000").replace(/\/$/, "");
+    // Scout dispatch proxy — routes through Prime if gateway enabled, else direct Worker
+    app.post('/api/v1/scout/dispatch', async (req, reply) => {
+        // Try Prime gateway first
+        if (isGatewayEnabled()) {
+            try {
+                const gwConfig = getGatewayConfig('', 0);
+                const { jobId } = await dispatchViaPrime(gwConfig, 'scout', req.body);
+                const result = await pollJobResult(gwConfig, jobId, 30_000);
+                return reply.status(200).send(result);
+            }
+            catch {
+                // Fall through to direct Worker
+            }
+        }
+        // Direct-to-Worker fallback
+        const workerUrl = config.workerUrl ?? getMusuBaseUrl();
+        const authToken = config.authToken ?? '';
+        try {
+            const res = await fetch(`${workerUrl}/v1/scout/dispatch`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+                },
+                body: JSON.stringify(req.body),
+            });
+            const body = await res.json();
+            return reply.status(res.status).send(body);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return reply.status(502).send({ error: `Worker unavailable: ${msg}` });
+        }
+    });
+    // Root redirect: / → /monitor (if no static SPA index.html served)
+    app.get('/', async (_req, reply) => {
+        return reply.redirect('/monitor');
+    });
+    // Companion: health
+    app.get('/health', async () => ({
+        status: 'ok',
+        service: 'musu-hub',
+        port,
+        timestamp: new Date().toISOString(),
+    }));
+    // Companion: chat SSE
+    app.post('/chat', async (req, reply) => {
+        const { messages } = req.body;
+        if (!messages || !Array.isArray(messages) || messages.length === 0) {
+            return reply.status(400).send({ error: 'messages array is required and must not be empty' });
+        }
+        reply.raw.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+            'Access-Control-Allow-Origin': '*',
+            'X-Accel-Buffering': 'no',
+        });
+        const emit = (packet) => {
+            reply.raw.write(encodeSSE(packet));
+        };
+        const companionConfig = {
+            host, port,
+            bitnetUrl: config.bitnetUrl,
+            bitnetModel: config.bitnetModel,
+            maxSteps: config.maxSteps,
+            adapter: config.adapter,
+            signalBridge,
+        };
+        try {
+            await handleChat(messages, companionConfig, emit);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            reply.raw.write(encodeSSE({ type: 'SYS_EVENT', head: 'ERROR', body: { error: msg } }));
+        }
+        finally {
+            reply.raw.end();
+        }
+    });
+    // MCP proxy routes for catalog/tool UI pages
+    app.get('/mcp/tools', async (_req, reply) => {
+        try {
+            const response = await fetch(`${mcpBaseUrl}/mcp/tools`, { method: 'GET' });
+            const text = await response.text();
+            let payload = { success: false, error: 'Invalid MCP response' };
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = { success: false, error: 'Invalid JSON from MCP server' };
+            }
+            return reply.status(response.status).send(payload);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return reply.status(502).send({
+                success: false,
+                error: `MCP server unreachable: ${msg}`,
+            });
+        }
+    });
+    app.post('/mcp/call', async (req, reply) => {
+        try {
+            const response = await fetch(`${mcpBaseUrl}/mcp/call`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(req.body ?? {}),
+            });
+            const text = await response.text();
+            let payload = { success: false, error: 'Invalid MCP response' };
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                payload = { success: false, error: 'Invalid JSON from MCP server' };
+            }
+            return reply.status(response.status).send(payload);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return reply.status(502).send({
+                success: false,
+                error: `MCP server unreachable: ${msg}`,
+            });
+        }
+    });
+    // Gateway dispatch callback route (Prime pushes jobs here)
+    if (isGatewayEnabled()) {
+        registerDispatchRoute(app);
+    }
+    // Static files (React SPA) — last so routes take precedence
+    try {
+        await app.register(import('@fastify/static'), {
+            root: staticDir,
+            prefix: '/',
+            decorateReply: false,
+        });
+    }
+    catch {
+        // Static dir may not exist yet (before UI build)
+    }
+    await app.listen({ host, port });
+    const addresses = app.addresses();
+    const addr = addresses[0];
+    const actualPort = addr ? addr.port : port;
+    const hubUrl = `http://${host}:${actualPort}`;
+    // Gateway registration + heartbeat (after listen so callback route is ready)
+    let gatewayHandle = null;
+    if (isGatewayEnabled()) {
+        const gwConfig = getGatewayConfig(hubUrl, actualPort);
+        // Fire-and-forget: don't block server startup
+        startGatewayHeartbeat(gwConfig).then(handle => {
+            gatewayHandle = handle;
+        }).catch(() => {
+            // Never fail the server
+        });
+    }
+    return {
+        url: hubUrl,
+        close: async () => {
+            if (gatewayHandle)
+                await gatewayHandle.stop();
+            signalCleanup();
+            await app.close();
+        },
+    };
+}

package/build/hub/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Hub Types — unified config combining Dashboard + Companion.
+ */
+import type { MusuAdapter } from '../kernel/musu_adapter.js';
+export interface HubConfig {
+    host?: string;
+    port?: number;
+    /** Dashboard storage directory (default: ~/.vibe/dashboard) */
+    storageDir?: string;
+    /** Workspace root for signal stream (default: cwd) */
+    workspaceRoot?: string;
+    /** Bearer auth token for sync endpoint */
+    authToken?: string | null;
+    /** Decryption secret (default: authToken) */
+    secretKey?: string | null;
+    /** Max body size in bytes (default: 1MB) */
+    maxBodyBytes?: number;
+    /** Companion: BitNet worker URL */
+    bitnetUrl?: string;
+    /** Companion: model ID */
+    bitnetModel?: string;
+    /** Companion: agent loop max steps */
+    maxSteps?: number;
+    /** Companion: static files directory */
+    staticDir?: string;
+    /** Musu Worker URL for scout proxy (default: MUSU_* resolver, usually http://127.0.0.1:8080) */
+    workerUrl?: string;
+    /** MCP HTTP server base URL for catalog/tool proxy routes (default: http://127.0.0.1:3000) */
+    mcpUrl?: string;
+    /** Injected adapter for real Worker delegation. undefined = stub mode. */
+    adapter?: MusuAdapter;
+    /** Port for auto-spawned Musu Worker (default: 8080) */
+    musuWorkerPort?: number;
+}
+export interface HubHandle {
+    url: string;
+    close: () => Promise<void>;
+}
+export declare const HUB_DEFAULTS: {
+    readonly host: "127.0.0.1";
+    readonly port: 3100;
+    readonly maxBodyBytes: 1000000;
+};

package/build/hub/types.js

@@ -0,0 +1,8 @@
+/**
+ * Hub Types — unified config combining Dashboard + Companion.
+ */
+export const HUB_DEFAULTS = {
+    host: '127.0.0.1',
+    port: 3100,
+    maxBodyBytes: 1_000_000,
+};

package/build/index.d.ts

@@ -20,22 +20,22 @@ export declare const EXIT_CODES: {
     readonly BLOCK: 3;
     readonly ERROR: 1;
 };
-export type Verdict = "GO" | "FIX" | "BLOCK";
-export { SkillLoader, createSkillLoader, type Skill, type SkillStep, type Skillpack, type SkillContext, type SkillResult, type StepResult, type ToolRef, type ArtifactRef, type Profile, } from "./skill-loader.js";
-export { EvidenceReportGenerator, generateEvidenceReport, generateEvidenceReportFromRunDir, saveEvidenceReport, saveEvidenceReportFromRunDir, generatePrComment, generatePrCommentFromRunDir, savePrComment, savePrCommentFromRunDir, } from "./evidence-report.js";
-export { ProfileManager, loadProfileFromEnv, filterSkillsByProfile, requireFeature, getAvailableProfiles, PROFILES, MVP_PROFILE, PRO_PROFILE, ALL_PROFILE, type ProfileConfig, type ProfileFeatures, type ProfileLimits, } from "./profile-config.js";
-export { LicenseManager, loadEntitlements, setupEngineEnvironment, getLicenseDir, getLicensePath, type Plan, type LicenseStatus, type DowngradeReason, type Switches, type Limits, type EntitlementsEffective, type EngineEnvConfig, } from "./license-manager.js";
-export { pathViolationMessage, readOnlyViolationMessage, commandSafetyMessage, licenseRestrictionMessage, iterationLimitMessage, scopeDriftMessage, missingWorkOrderMessage, missingDecisionMessage, formatCorrectionForAgent, formatCorrectionForUser, type ViolationType, type CorrectionMessage, } from "./correction-messages.js";
-export { SyncPacketBuilder, buildSyncPacket, encryptSyncPacket, decryptSyncPacket, generateRunId, type SyncMetadata, type VerdictSummary, type TokenUsage, type SyncMetrics, type ViolationSummary, type ViolationDetail, type TimingInfo, type SyncPacket, type EncryptedPacket, type GateResult, type ClinicResult, } from "./sync-packet-builder.js";
-export { BackgroundSyncWorker, flushQueueInBackground, queueAndFlush, getQueueDir, getDlqDir, type SyncWorkerOptions, type SyncResult, } from "./background-sync-worker.js";
-export { OfflineQueue, getDefaultQueueDir, type OfflineQueueOptions, type OfflineQueueStats, type QueueDrainResult, type DrainHandlerResult, type QueuedPacket, } from "./offline-queue.js";
-export { SyncManager, sendEncryptedPacket, type SyncManagerOptions, type QueueRunInput, type SyncManagerResult, } from "./sync-manager.js";
-export { startDashboardServer, type DashboardServerOptions, type DashboardServerHandle, } from "./dashboard/server.js";
-export { ReportGenerator, generatePdfReport, generateHtmlReport, generateMarkdownReport, generateHtmlFromCiSummary, writeHtmlReportFromCiSummary, writeHtmlReportFromCiSummarySafe, type ReportData, type ReportOptions, type CiSummaryV1, type HtmlReportFromSummaryOptions, } from "./report-generator.js";
-export { createVscodeLink, createJetBrainsLink, renderTerminalLink, renderPlainLink, supportsOsc8, renderViolationLinks, buildViolationLinks, createReportLink, renderSummaryWithLink, type ViolationLink, } from "./deep-link.js";
-export type { RiskLevel, SkeletonStatus, FocusModule, FocusFile, SkeletonFocus, SkeletonMapSummary, CiSummarySkeletonData, TokenRoi, SkeletonReadResult, } from "./skeleton-types.js";
-export { VERDICT_TO_SIGNAL, SIGNAL_EMOJI, type ReviewerSignal, type DecisionType, type DecisionLogEntry, type ReviewHistoryEntry, type HotspotFile, type ScopeDriftViolation, type ReviewerUxData, } from "./reviewer-ux-types.js";
-export { readDecisionLog, readRecentDecisions, hasDecisionEvidence, findDecisionLogPath, } from "./decision-log-reader.js";
-export { recordReviewHistory, getHotspotFiles, hasReviewHistory, getHistoryEntryCount, cleanupOldHistory, } from "./review-history.js";
-export type { VibeMode, Theme, SyncOnError, ChromaUnavailablePolicy, PolicyOverrides, PolicyConfig, ChromaConfig, ReportingConfig, SyncConfig, VibeCiConfig, SyncHookContext, } from "./types/vibe-ci-config.js";
-export { loadVibeCiConfig, loadVibeCiConfigSafe, createDefaultConfig, createDefaultPolicy, type ResolvedPolicy, type LoadedConfig, type LoadConfigOptions, } from "./config/load-config.js";
+export type Verdict = 'GO' | 'FIX' | 'BLOCK';
+export { SkillLoader, createSkillLoader, type Skill, type SkillStep, type Skillpack, type SkillContext, type SkillResult, type StepResult, type ToolRef, type ArtifactRef, type Profile, } from './skill-loader.js';
+export { EvidenceReportGenerator, generateEvidenceReport, generateEvidenceReportFromRunDir, saveEvidenceReport, saveEvidenceReportFromRunDir, generatePrComment, generatePrCommentFromRunDir, savePrComment, savePrCommentFromRunDir, } from './evidence-report.js';
+export { ProfileManager, loadProfileFromEnv, filterSkillsByProfile, requireFeature, getAvailableProfiles, PROFILES, MVP_PROFILE, PRO_PROFILE, ALL_PROFILE, type ProfileConfig, type ProfileFeatures, type ProfileLimits, } from './profile-config.js';
+export { LicenseManager, loadEntitlements, setupEngineEnvironment, getLicenseDir, getLicensePath, type Plan, type LicenseStatus, type DowngradeReason, type Switches, type Limits, type EntitlementsEffective, type EngineEnvConfig, } from './license-manager.js';
+export { pathViolationMessage, readOnlyViolationMessage, commandSafetyMessage, licenseRestrictionMessage, iterationLimitMessage, scopeDriftMessage, missingWorkOrderMessage, missingDecisionMessage, formatCorrectionForAgent, formatCorrectionForUser, type ViolationType, type CorrectionMessage, } from './correction-messages.js';
+export { SyncPacketBuilder, buildSyncPacket, encryptSyncPacket, decryptSyncPacket, generateRunId, type SyncMetadata, type VerdictSummary, type TokenUsage, type SyncMetrics, type ViolationSummary, type ViolationDetail, type TimingInfo, type SyncPacket, type EncryptedPacket, type GateResult, type ClinicResult, } from './sync-packet-builder.js';
+export { BackgroundSyncWorker, flushQueueInBackground, queueAndFlush, getQueueDir, getDlqDir, type SyncWorkerOptions, type SyncResult, } from './background-sync-worker.js';
+export { OfflineQueue, getDefaultQueueDir, type OfflineQueueOptions, type OfflineQueueStats, type QueueDrainResult, type DrainHandlerResult, type QueuedPacket, } from './offline-queue.js';
+export { SyncManager, sendEncryptedPacket, type SyncManagerOptions, type QueueRunInput, type SyncManagerResult, } from './sync-manager.js';
+export { startDashboardServer, type DashboardServerOptions, type DashboardServerHandle, } from './dashboard/server.js';
+export { ReportGenerator, generatePdfReport, generateHtmlReport, generateMarkdownReport, generateHtmlFromCiSummary, writeHtmlReportFromCiSummary, writeHtmlReportFromCiSummarySafe, type ReportData, type ReportOptions, type CiSummaryV1, type HtmlReportFromSummaryOptions, } from './report-generator.js';
+export { createVscodeLink, createJetBrainsLink, renderTerminalLink, renderPlainLink, supportsOsc8, renderViolationLinks, buildViolationLinks, createReportLink, renderSummaryWithLink, type ViolationLink, } from './deep-link.js';
+export type { RiskLevel, SkeletonStatus, FocusModule, FocusFile, SkeletonFocus, SkeletonMapSummary, CiSummarySkeletonData, TokenRoi, SkeletonReadResult, } from './skeleton-types.js';
+export { VERDICT_TO_SIGNAL, SIGNAL_EMOJI, type ReviewerSignal, type DecisionType, type DecisionLogEntry, type ReviewHistoryEntry, type HotspotFile, type ScopeDriftViolation, type ReviewerUxData, } from './reviewer-ux-types.js';
+export { readDecisionLog, readRecentDecisions, hasDecisionEvidence, findDecisionLogPath, } from './decision-log-reader.js';
+export { recordReviewHistory, getHotspotFiles, hasReviewHistory, getHistoryEntryCount, cleanupOldHistory, } from './review-history.js';
+export type { VibeMode, Theme, SyncOnError, ChromaUnavailablePolicy, PolicyOverrides, PolicyConfig, ChromaConfig, ReportingConfig, SyncConfig, VibeCiConfig, SyncHookContext, } from './types/vibe-ci-config.js';
+export { loadVibeCiConfig, loadVibeCiConfigSafe, createDefaultConfig, createDefaultPolicy, type ResolvedPolicy, type LoadedConfig, type LoadConfigOptions, } from './config/load-config.js';