wizard-server.js

/**
 * wizard-server.js - Clean, focused server for The Wizard
 * 
 * This replaces the 5000+ line the legacy bridge daemon with a minimal
 * server that only handles wizard functionality.
 * 
 * Run with: node wizard-server.js
 * Or via npm: npm run wizard
 */

import express from 'express';
import cors from 'cors';
import net from 'net';
import { parseArgs } from 'node:util';
import { runAgent } from './src/wizard/AgentLoop.js';
import { buildLlmConfig } from './src/wizard/buildLlmConfig.js';
import { getToolDefinitions, executeTool } from './src/wizard/tools/index.js';
import { callLLM } from './src/wizard/LLMClient.js';
import { debugLogSync } from './src/utils/debugLogger.js';
import { enrichBatch, enrichSingle } from './src/wizard/services/wikipediaEnrichment.js';
import SchedulerModule from './src/services/orchestrator/Scheduler.js';
import { initRuntime, resolveWorkspace } from './src/headless/runtime.js';
import { GitHubUniverseSync, parseRepoSpec } from './src/headless/githubSync.js';
import { resolveGithubToken } from './src/headless/config.js';

const app = express();

// ─────────────────────────────────────────────────────────────
// Headless runtime (optional). When a universe file is configured
// (--universe / REDSTRING_UNIVERSE / ~/.redstring/config.json), the server owns
// a live store and executes mutations in-process — no browser required. When
// absent, the server behaves exactly as before (browser-relay mode).
// ─────────────────────────────────────────────────────────────
let runtime = null;
const isHeadless = () => !!runtime;

// Flush + release the lock on shutdown so the .redstring file is never left
// stale and another runtime can take over cleanly.
let shutdownInstalled = false;
function installShutdownHandlers() {
  if (shutdownInstalled) return;
  shutdownInstalled = true;
  let shuttingDown = false;
  const shutdown = async (signal) => {
    if (shuttingDown) return;
    shuttingDown = true;
    console.error(`[Wizard] ${signal} — flushing universe and releasing lock`);
    try { if (runtime) await runtime.shutdown(); } catch (err) { console.error('[Wizard] Shutdown flush failed:', err.message); }
    process.exit(0);
  };
  process.on('SIGINT', () => shutdown('SIGINT'));
  process.on('SIGTERM', () => shutdown('SIGTERM'));
}

// Check if a port is available
function isPortAvailable(port) {
  return new Promise((resolve) => {
    const server = net.createServer();
    server.once('error', () => resolve(false));
    server.once('listening', () => {
      server.close();
      resolve(true);
    });
    server.listen(port);
  });
}

// Find the port to use
async function getPort() {
  // Wizard uses 3001 by default (same as legacy bridge for compatibility)
  const preferred = parseInt(process.env.WIZARD_PORT || process.env.BRIDGE_PORT || '3001', 10);
  if (await isPortAvailable(preferred)) {
    return preferred;
  }

  // If 3001 is in use (e.g., by Electron's embedded bridge), that's fine
  // The UI will connect to whatever is on 3001
  console.log(`[Wizard] Port ${preferred} already in use.`);
  console.log(`[Wizard] If running alongside Electron, stop the Electron app first`);
  console.log(`[Wizard] or set WIZARD_PORT=3002 to run on a different port.`);

  throw new Error(`Port ${preferred} in use. Set WIZARD_PORT env var to use a different port.`);
}

// Middleware
// CORS: this bridge binds to 127.0.0.1, so it should only be driven by the
// local app (Vite dev proxy / Electron renderer / CLI), never by an arbitrary
// website the user happens to have open. Allow requests with no Origin
// (same-origin, proxied, curl, Electron) and localhost origins on any port;
// extend via CORS_ORIGINS (comma-separated) if a specific web origin is needed.
const wizardAllowedOrigins = new Set(
  (process.env.CORS_ORIGINS || '')
    .split(',')
    .map((s) => s.trim())
    .filter(Boolean)
);
// Capacitor/iOS app bundle origins (custom scheme, not a third-party site).
wizardAllowedOrigins.add('capacitor://localhost');
wizardAllowedOrigins.add('ionic://localhost');
app.use(cors({
  origin: (origin, callback) => {
    if (!origin) return callback(null, true);
    if (wizardAllowedOrigins.has(origin)) return callback(null, true);
    try {
      const host = new URL(origin).hostname;
      if (host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || host === '::1') {
        return callback(null, true);
      }
    } catch { /* invalid Origin header */ }
    // Omit CORS headers (don't 500) so same-origin loads still work while
    // cross-origin requests are blocked by the missing allow-origin header.
    return callback(null, false);
  },
  credentials: false,
}));
app.use(express.json({ limit: '20mb' }));

// Request logging
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.path} ${res.statusCode} ${duration}ms`);
  });
  next();
});

// ─────────────────────────────────────────────────────────────
// Scheduler (processes queued tool actions)
// ─────────────────────────────────────────────────────────────

let scheduler = null;

async function ensureSchedulerStarted() {
  if (!scheduler) {
    try {
      scheduler = SchedulerModule;
    } catch (e) {
      console.warn('[Wizard] Failed to load scheduler:', e.message);
      return;
    }
  }

  if (scheduler && typeof scheduler.start === 'function') {
    const status = scheduler.status();
    if (!status.enabled) {
      scheduler.start({ planner: true, executor: true, auditor: true });
      console.log('[Wizard] Scheduler started');
    }
  }
}

// ─────────────────────────────────────────────────────────────
// Health Check
// ─────────────────────────────────────────────────────────────

app.get('/api/bridge/health', (req, res) => {
  res.json({
    status: 'ok',
    source: 'wizard-server',
    timestamp: new Date().toISOString(),
    scheduler: scheduler?.status() || { enabled: false },
    // Headless runtime status — the browser (BridgeClient) reads `headless` to
    // switch into runtime-authoritative mode (Phase 6).
    headless: isHeadless(),
    storeMode: isHeadless() ? 'runtime' : 'browser',
    workspace: isHeadless() ? runtime.workspaceDir : null,
    universe: isHeadless() ? runtime.universePath : null,
    activeUniverse: isHeadless() ? (runtime.getActiveUniverse()?.slug || null) : null,
    stateVersion: isHeadless() ? runtime.stateVersion : null
  });
});

app.get('/health', (req, res) => {
  res.json({ status: 'ok', source: 'wizard-server' });
});

// ─────────────────────────────────────────────────────────────
// The Wizard Endpoint (SSE streaming)
// ─────────────────────────────────────────────────────────────

app.post('/api/wizard', async (req, res) => {
  try {
    const { message, graphState, conversationHistory, tabularData, config } = req.body || {};

    if (!message) {
      return res.status(400).json({ error: 'Message is required' });
    }

    // Inject tabular data into graphState so tools can access it via graphState._tabularData
    if (tabularData && Array.isArray(tabularData) && tabularData.length > 0) {
      if (graphState) graphState._tabularData = tabularData;
      console.log(`[Wizard] Tabular data attached: ${tabularData.length} file(s), first: ${tabularData[0]?.filename}`);
    }

    const apiKey = req.headers.authorization?.replace(/^Bearer\s+/i, '') || '';
    const apiConfig = config?.apiConfig || {};

    if (!apiKey) {
      return res.status(401).json({ error: 'API key required in Authorization header' });
    }

    // Set up SSE
    res.setHeader('Content-Type', 'text/event-stream');
    res.setHeader('Cache-Control', 'no-cache');
    res.setHeader('Connection', 'keep-alive');
    res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
    res.flushHeaders(); // Send headers immediately so browser knows stream is open

    // Shared with the in-app runner so the two cannot drift on the iteration
    // and token clamps. See src/wizard/buildLlmConfig.js.
    const llmConfig = buildLlmConfig({
      apiKey,
      apiConfig,
      cid: config?.cid,
      systemPrompt: config?.systemPrompt,
      contextItems: req.body.contextItems || [],
      conversationHistory: conversationHistory || []
    });

    const messagePreview = typeof message === 'string'
      ? message.substring(0, 50)
      : `[multimodal: ${message.length} blocks]`;
    console.log('[Wizard] Request:', {
      messagePreview,
      provider: llmConfig.provider,
      model: llmConfig.model,
      historyLength: conversationHistory?.length || 0,
      activeGraph: graphState?.activeGraphId
    });

    const abortController = new AbortController();
    // req.on('aborted') is deprecated in Node 17+ — use res.on('close') instead.
    // Fires when the client disconnects or aborts the fetch; writableEnded guards
    // against triggering on normal completion.
    res.on('close', () => {
      if (!res.writableEnded) {
        console.log('[Wizard] Client disconnected, canceling agent loop');
        abortController.abort();
      }
    });

    let lastUsage = null;
    try {
      for await (const event of runAgent(message, graphState || {}, llmConfig, ensureSchedulerStarted, abortController.signal)) {
        if (event.type === 'usage') lastUsage = event;
        res.write(`data: ${JSON.stringify(event)}\n\n`);
        // Delay now handled in AgentLoop.js to prevent tool execution before browser renders
      }
      // Per-ask token accounting — one line per ask so spend is inspectable in logs.
      if (lastUsage) {
        // charged vs uploaded is the line to read: uploaded counts every input
        // token the model saw, charged applies the cache discount. A large gap
        // means caching is working; charged ≈ uploaded on a long run means it
        // is not, and the ask is paying full price for identical bytes.
        console.log('[Wizard] Token usage:', {
          cid: llmConfig.cid,
          provider: llmConfig.provider,
          model: llmConfig.model,
          iterations: lastUsage.iteration,
          promptTokens: lastUsage.askPromptTokens,
          completionTokens: lastUsage.askCompletionTokens,
          totalTokens: lastUsage.askTotalTokens,
          uploadedTokens: lastUsage.askUploadedTokens,
          chargedTokens: lastUsage.askChargedTokens,
          cacheSavings: lastUsage.askUploadedTokens
            ? `${Math.round((1 - (lastUsage.askChargedTokens / lastUsage.askUploadedTokens)) * 100)}%`
            : 'n/a'
        });
        // The follow-up question to "how much" is always "on what". This is the
        // last iteration's split, which is the worst case — history is at its
        // largest by then, so if anything is crowding out the conversation it
        // shows up here.
        if (lastUsage.costBreakdown) {
          const b = lastUsage.costBreakdown;
          console.log('[Wizard] Final-iteration input split:', {
            tools: b.tools,
            system: b.system,
            graphContext: b.context,
            history: b.history,
            cachedFraction: `${b.cachedFraction}%`,
            reclaimedByDedup: b.reclaimed,
            ...(Object.keys(b.reclaimedByTool || {}).length > 0
              ? { reclaimedByTool: b.reclaimedByTool }
              : {})
          });
        }
      }
      res.write(`data: ${JSON.stringify({ type: 'done' })}\n\n`);
    } catch (error) {
      if (error.name === 'AbortError' || error.message?.includes('aborted')) {
        console.log('[Wizard] Agent loop aborted gracefully on server');
        if (!res.headersSent) {
          res.write(`data: ${JSON.stringify({ type: 'done' })}\n\n`);
        }
      } else {
        console.error('[Wizard] Agent error:', error);
        res.write(`data: ${JSON.stringify({ type: 'error', message: error.message })}\n\n`);
      }
    }

    res.end();
  } catch (error) {
    console.error('[Wizard] Request error:', error);
    if (!res.headersSent) {
      res.status(500).json({ error: error.message });
    } else {
      res.write(`data: ${JSON.stringify({ type: 'error', message: error.message })}\n\n`);
      res.end();
    }
  }
});

// ─────────────────────────────────────────────────────────────
// Simple Chat Endpoint (for Questions and tests)
// ─────────────────────────────────────────────────────────────

app.post('/api/ai/chat', async (req, res) => {
  try {
    const { message, context, systemPrompt, model: reqModel } = req.body || {};
    const apiKey = req.headers.authorization?.replace(/^Bearer\s+/i, '') || '';

    if (!apiKey) {
      return res.status(401).json({ error: 'API key required' });
    }

    const apiConfig = context?.apiConfig || {};

    const config = {
      apiKey,
      provider: apiConfig.provider || 'openrouter',
      endpoint: apiConfig.endpoint,
      model: reqModel || apiConfig.model,
      temperature: 0.7,
      maxTokens: 1024
    };

    const messages = [];
    if (systemPrompt) {
      messages.push({ role: 'system', content: systemPrompt });
    }
    messages.push({ role: 'user', content: message || 'test' });

    const { content } = await callLLM(messages, [], config);
    res.json({ response: content || 'Success' });
  } catch (err) {
    console.error('[Wizard] /api/ai/chat error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// ─────────────────────────────────────────────────────────────
// UI Tool Tester Endpoints
// ─────────────────────────────────────────────────────────────

app.get('/api/wizard/tools', (req, res) => {
  try {
    const tools = getToolDefinitions();
    res.json({ tools });
  } catch (error) {
    console.error('[Wizard] Failed to get tools:', error);
    res.status(500).json({ error: error.message });
  }
});

app.post('/api/wizard/execute-tool', async (req, res) => {
  try {
    const { name, args, graphState, config } = req.body || {};

    if (!name) {
      return res.status(400).json({ error: 'Tool name is required' });
    }

    const cid = config?.cid || `tool-test-${Date.now()}`;
    const apiKey = req.headers.authorization?.replace(/^Bearer\s+/i, '') || '';

    console.log(`[Wizard] Executing tool manually: ${name}`, args);

    // Create a synthesized graphState if not fully valid
    const safeGraphState = graphState || {
      graphs: [],
      nodePrototypes: [],
      edges: [],
      activeGraphId: null
    };

    // Inject the apiKey if it's not present just in case a tool needs it
    if (apiKey && !safeGraphState.apiKey) {
      safeGraphState.apiKey = apiKey;
    }

    await ensureSchedulerStarted();

    const result = await executeTool(name, args || {}, safeGraphState, cid, ensureSchedulerStarted);

    res.json({ success: true, result });
  } catch (error) {
    console.error(`[Wizard] Error executing tool ${req.body?.name}:`, error);
    res.status(500).json({ error: error.message });
  }
});

// ─────────────────────────────────────────────────────────────
// Scheduler Status
// ─────────────────────────────────────────────────────────────

app.get('/api/scheduler/status', (req, res) => {
  res.json(scheduler?.status() || { enabled: false, message: 'Scheduler not initialized' });
});

app.post('/api/scheduler/start', async (req, res) => {
  await ensureSchedulerStarted();
  res.json(scheduler?.status() || { enabled: false });
});

// ─────────────────────────────────────────────────────────────
// UI Compatibility Endpoints (minimal stubs)
// ─────────────────────────────────────────────────────────────

// Store registration - UI calls this on startup
let registeredStore = null;
app.post('/api/bridge/register-store', (req, res) => {
  registeredStore = req.body || {};
  res.json({ ok: true, registered: true });
});

// State endpoint - stores latest state from BridgeClient.jsx for MCP server consumption
let latestBridgeState = null;

let warnedIgnoredStatePost = false;

app.get('/api/bridge/state', (req, res) => {
  // Headless: serve the live store directly (canonical). The MCP server reads
  // the same shape it reads from the browser (buildBridgeState contract).
  if (isHeadless()) {
    return res.json(runtime.buildBridgeStatePayload());
  }
  if (latestBridgeState) {
    res.json(latestBridgeState);
  } else {
    res.json({
      graphs: [],
      pendingActions: [],
      source: 'wizard-server',
      summary: { lastUpdate: Date.now() }
    });
  }
});

app.post('/api/bridge/state', (req, res) => {
  // Headless: the runtime owns the store, so an inbound bridge snapshot is not
  // authoritative — ignore it (log once) rather than clobbering live state.
  if (isHeadless()) {
    if (!warnedIgnoredStatePost) {
      console.log('[Wizard] Headless mode: ignoring POST /api/bridge/state (runtime owns the store)');
      warnedIgnoredStatePost = true;
    }
    return res.json({ ok: true, ignored: true, storeMode: 'runtime' });
  }
  // Store state updates from BridgeClient.jsx so MCP server can read them
  latestBridgeState = req.body || null;
  res.json({ ok: true });
});

// ─────────────────────────────────────────────────────────────
// Store endpoints (headless only) — full lossless universe access for the CLI
// and, later, browser↔runtime sync (Phase 6).
// ─────────────────────────────────────────────────────────────

app.get('/api/store/export', (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless', message: 'No runtime universe loaded' });
  try {
    res.json(runtime.exportRedstring());
  } catch (err) {
    res.status(500).json({ error: String(err?.message || err) });
  }
});

app.get('/api/store/status', (req, res) => {
  if (!isHeadless()) return res.json({ headless: false });
  const state = runtime.getState();
  res.json({
    headless: true,
    universe: runtime.universePath,
    stateVersion: runtime.stateVersion,
    graphs: state.graphs.size,
    prototypes: state.nodePrototypes.size,
    edges: state.edges?.size || 0,
    activeGraphId: state.activeGraphId || null
  });
});

app.post('/api/store/save', async (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    await runtime.flush();
    res.json({ ok: true, stateVersion: runtime.stateVersion, universe: runtime.universePath });
  } catch (err) {
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// Browser → runtime forward-edit (Phase 6 coexistence). Optimistic concurrency:
// the browser sends the stateVersion it last observed; if the runtime has since
// advanced (e.g. an MCP mutation landed), reject with 409 so the browser
// re-hydrates instead of clobbering. Body: { baseVersion?, redstring }.
app.post('/api/store/import', (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  const { baseVersion, redstring } = req.body || {};
  if (typeof baseVersion === 'number' && baseVersion !== runtime.stateVersion) {
    return res.status(409).json({ error: 'version-conflict', stateVersion: runtime.stateVersion });
  }
  if (!redstring || typeof redstring !== 'object') {
    return res.status(400).json({ error: 'missing-redstring' });
  }
  try {
    const ok = runtime.importRedstring(redstring);
    if (!ok) return res.status(400).json({ error: 'import-rejected' });
    res.json({ ok: true, stateVersion: runtime.stateVersion });
  } catch (err) {
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// ─────────────────────────────────────────────────────────────
// Workspace / universe management (headless only). Lets the CLI (HTTP mode)
// and a future GUI drive the same universe lifecycle the direct-library path uses.
// ─────────────────────────────────────────────────────────────

app.get('/api/workspace', (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  res.json({
    workspace: runtime.workspaceDir,
    active: runtime.getActiveUniverse()?.slug || null,
    universes: runtime.listUniverses()
  });
});

app.post('/api/workspace/universes', async (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    const universe = await runtime.createUniverse(req.body?.name || 'Universe');
    res.json({ ok: true, universe, active: runtime.getActiveUniverse()?.slug, stateVersion: runtime.stateVersion });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

app.post('/api/workspace/active', async (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    await runtime.switchUniverse(req.body?.slug);
    res.json({ ok: true, active: runtime.getActiveUniverse()?.slug, stateVersion: runtime.stateVersion });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

app.delete('/api/workspace/universes/:slug', async (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    const result = await runtime.deleteUniverse(req.params.slug, { keepFile: req.query.keepFile === 'true' });
    res.json({ ok: true, ...result });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

app.post('/api/workspace/unlink', (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    runtime.unlinkUniverse(req.body?.slug, req.body?.slot);
    res.json({ ok: true });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

app.post('/api/workspace/link', (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    const { slug, repo, branch = 'main' } = req.body || {};
    if (!slug || !repo) return res.status(400).json({ error: 'slug and repo required' });
    const { user, repo: repoName, path: repoPath } = parseRepoSpec(repo);
    const entry = runtime.setGitLink(
      slug,
      { type: 'github', user, repo: repoName, authMethod: 'token', branch },
      repoPath ? { universeFolder: repoPath.includes('/') ? repoPath.slice(0, repoPath.lastIndexOf('/')) : slug, universeFile: repoPath.split('/').pop() } : {}
    );
    res.json({ ok: true, universe: entry });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

// Build a GitHub sync client from a repo spec + server-resolved BYOK token.
function buildGithubSync(repoSpec, { branch } = {}) {
  const { user, repo, path: repoPath } = parseRepoSpec(repoSpec);
  const token = resolveGithubToken({ env: process.env });
  const sync = new GitHubUniverseSync({ user, repo, token, branch: branch || 'main' });
  return { sync, repoPath };
}

app.post('/api/workspace/pull', async (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    const { repo, name = null, activate = true, branch = null } = req.body || {};
    if (!repo) return res.status(400).json({ error: 'repo required (user/repo[/path])' });
    const { sync, repoPath } = buildGithubSync(repo, { branch });
    const universe = await runtime.pullUniverse(sync, { repoPath, name, activate });
    res.json({ ok: true, universe, active: runtime.getActiveUniverse()?.slug, stateVersion: runtime.stateVersion });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

app.post('/api/workspace/push', async (req, res) => {
  if (!isHeadless()) return res.status(409).json({ error: 'not-headless' });
  try {
    const { slug: slugIn = null, repo = null, message = null, branch = null } = req.body || {};
    const slug = slugIn || runtime.getActiveUniverse()?.slug;
    if (!slug) return res.status(400).json({ error: 'no universe to push' });
    const entry = runtime.listUniverses().find((u) => u.slug === slug);
    if (!entry) return res.status(404).json({ error: `no such universe: ${slug}` });

    // Resolve the repo from the request, else the universe's recorded link.
    let repoSpec = repo;
    let repoPath = null;
    if (!repoSpec && entry.gitRepo?.enabled && entry.gitRepo.linkedRepo) {
      const lr = entry.gitRepo.linkedRepo;
      repoSpec = `${lr.user}/${lr.repo}`;
      repoPath = entry.gitRepo.repoPath || null;
    }
    if (!repoSpec) return res.status(400).json({ error: 'no linked repo — pass repo: "user/repo"' });

    const built = buildGithubSync(repoSpec, { branch: branch || entry.gitRepo?.linkedRepo?.branch });
    const result = await runtime.pushUniverse(built.sync, slug, { message, repoPath: repoPath || built.repoPath });
    res.json({ ok: true, ...result });
  } catch (err) { res.status(400).json({ error: String(err?.message || err) }); }
});

// SSE events stream - UI subscribes to this for real-time updates
const sseClients = new Set();

app.get('/events/stream', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.setHeader('X-Accel-Buffering', 'no');

  // Send initial ping
  res.write(`data: ${JSON.stringify({ type: 'connected', source: 'wizard-server' })}\n\n`);

  sseClients.add(res);

  req.on('close', () => {
    sseClients.delete(res);
  });
});

// Broadcast to all SSE clients (used internally)
function broadcastEvent(event) {
  const data = `data: ${JSON.stringify(event)}\n\n`;
  for (const client of sseClients) {
    try {
      client.write(data);
    } catch (e) {
      sseClients.delete(client);
    }
  }
}

// ─────────────────────────────────────────────────────────────
// Pending Actions State (for UI ↔ Server communication)
// ─────────────────────────────────────────────────────────────

let pendingActions = [];
const inflightActionIds = new Set();
const inflightMeta = new Map(); // id -> { ts, action, params }
const completedActions = new Map(); // id -> { result, completedAt }
/** How long a client may hold a leased action before it is offered to another. */
const INFLIGHT_TTL_MS = 300000; // 5 min, matching completedActions
let telemetry = [];
let chatLog = [];

// Telemetry is append-only from nine call sites and is polled by every connected
// client every 500ms–5s. Left unbounded it made both processes do O(n) work per
// poll — O(n²) over a session — and eventually crashed the client, which spread
// the array into Math.max(). Trim it exactly as chatLog beside it already is.
const TELEMETRY_MAX = 1000;
const TELEMETRY_KEEP = 800;
function pushTelemetry(entry) {
  telemetry.push(entry);
  if (telemetry.length > TELEMETRY_MAX) telemetry = telemetry.slice(-TELEMETRY_KEEP);
}

// Telemetry endpoint
app.get('/api/bridge/telemetry', (req, res) => {
  // Sliced like `chat` beside it: clients only ever read the recent tail.
  res.json({ telemetry: telemetry.slice(-500), chat: chatLog.slice(-200) });
});

// ─────────────────────────────────────────────────────────────
// Pending Actions Endpoints (for Committer and UI)
// ─────────────────────────────────────────────────────────────

// GET pending actions - UI polls this to receive mutations
app.get('/api/bridge/pending-actions', (req, res) => {
  try {
    // Headless: the runtime executes actions in-process, so never hand them to a
    // (coexisting) browser — that would double-apply the same mutation.
    if (isHeadless()) return res.json({ pendingActions: [] });
    // Expire stale leases first. A client that leased an action and then died
    // never reports back, and this filter is what hides the action from every
    // other client — so without a TTL that action is hidden permanently. Same
    // 5 minutes completedActions already uses.
    const leaseCutoff = Date.now() - INFLIGHT_TTL_MS;
    for (const [id, meta] of inflightMeta) {
      if (meta.ts < leaseCutoff) {
        inflightMeta.delete(id);
        inflightActionIds.delete(id);
        console.warn(`[Wizard] Lease on action ${id} (${meta.action}) expired — returning it to the queue.`);
      }
    }

    const available = pendingActions.filter(a => !inflightActionIds.has(a.id));
    available.forEach(a => {
      inflightActionIds.add(a.id);
      inflightMeta.set(a.id, { ts: Date.now(), action: a.action, params: a.params });
      pushTelemetry({ ts: Date.now(), type: 'tool_call', name: a.action, args: a.params, leased: true, id: a.id });
    });
    res.json({ pendingActions: available });
  } catch (err) {
    console.error('[Wizard] Pending actions error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// POST enqueue actions - Committer uses this to push mutations
app.post('/api/bridge/pending-actions/enqueue', (req, res) => {
  try {
    const { actions } = req.body || {};
    if (!Array.isArray(actions) || actions.length === 0) {
      return res.status(400).json({ ok: false, error: 'actions[] required' });
    }
    // Prepend openGraph actions inferred from any applyMutations ops to avoid UI timing races
    const expanded = [];
    for (const a of actions) {
      if (a && a.action === 'applyMutations' && Array.isArray(a.params?.[0])) {
        const ops = a.params[0];
        const graphIds = new Set();
        for (const op of ops) {
          if (op && typeof op.graphId === 'string' && op.graphId) graphIds.add(op.graphId);
        }
        for (const gid of graphIds) expanded.push({ action: 'openGraph', params: [gid] });
      }
      expanded.push(a);
    }
    const id = (suffix) => `pa-${Date.now()}-${Math.random().toString(36).slice(2, 8)}-${suffix}`;
    const generatedIds = [];

    // Headless: execute each action in-process, in dependency order (shared
    // priority()), then mark it completed immediately so the MCP server's
    // action-status poll resolves on the first hit (no browser to lease it).
    if (isHeadless()) {
      // Assign ids synchronously (in execution order) so the response carries
      // them; mark each pending until the async executor completes it.
      const ordered = [...expanded]
        .sort((x, y) => runtime.priority(x) - runtime.priority(y))
        .map((a) => {
          const actionId = id(a.action || 'act');
          generatedIds.push(actionId);
          pendingActions.push({ id: actionId, action: a.action, params: a.params, timestamp: Date.now() });
          return { actionId, action: a.action, params: a.params };
        });

      // Fire-and-forget sequential execution; the MCP client polls action-status.
      (async () => {
        for (const { actionId, action, params } of ordered) {
          pushTelemetry({ ts: Date.now(), type: 'tool_call', name: action, args: params, status: 'running', id: actionId });
          try {
            const result = await runtime.executeAction(action, params);
            completedActions.set(actionId, { result: result ?? { success: true }, completedAt: Date.now() });
            pushTelemetry({ ts: Date.now(), type: 'tool_call', name: action, args: params, status: 'completed', id: actionId });
          } catch (err) {
            completedActions.set(actionId, { result: { success: false, error: String(err?.message || err) }, completedAt: Date.now() });
            pushTelemetry({ ts: Date.now(), type: 'tool_call', name: action, args: params, status: 'error', error: String(err?.message || err), id: actionId });
          } finally {
            pendingActions = pendingActions.filter((p) => p.id !== actionId);
            setTimeout(() => completedActions.delete(actionId), 300000); // 5 min TTL
          }
        }
      })();
      return res.json({ ok: true, enqueued: expanded.length, actionIds: generatedIds, storeMode: 'runtime' });
    }

    for (const a of expanded) {
      const actionId = id(a.action || 'act');
      generatedIds.push(actionId);
      pendingActions.push({ id: actionId, action: a.action, params: a.params, timestamp: Date.now() });
      pushTelemetry({ ts: Date.now(), type: 'tool_call', name: a.action, args: a.params, status: 'queued' });
    }
    res.json({ ok: true, enqueued: actions.length, actionIds: generatedIds });
  } catch (err) {
    console.error('[Wizard] Enqueue error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// POST action completed - UI calls this when an action is done
app.post('/api/bridge/action-completed', (req, res) => {
  try {
    const { actionId, result } = req.body || {};
    if (actionId) {
      pendingActions = pendingActions.filter(a => a.id !== actionId);
      inflightActionIds.delete(actionId);
      const meta = inflightMeta.get(actionId);
      if (meta) {
        pushTelemetry({ ts: Date.now(), type: 'tool_call', name: meta.action, args: meta.params, status: 'completed', id: actionId });
        inflightMeta.delete(actionId);
      }
      // Store completion for MCP server polling
      completedActions.set(actionId, { result, completedAt: Date.now() });
      setTimeout(() => completedActions.delete(actionId), 300000); // 5 min TTL
    }
    res.json({ success: true });
  } catch (err) {
    console.error('[Wizard] Action completed error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// GET action status - MCP server polls this to wait for completion
app.get('/api/bridge/action-status/:actionId', (req, res) => {
  const { actionId } = req.params;
  if (completedActions.has(actionId)) {
    return res.json({ status: 'completed', ...completedActions.get(actionId) });
  }
  if (inflightActionIds.has(actionId)) {
    return res.json({ status: 'running' });
  }
  if (pendingActions.some(a => a.id === actionId)) {
    return res.json({ status: 'pending' });
  }
  res.json({ status: 'unknown' });
});

// POST action feedback - for warnings and errors
app.post('/api/bridge/action-feedback', (req, res) => {
  try {
    const { action, status, error, params } = req.body || {};
    pushTelemetry({ ts: Date.now(), type: 'action_feedback', action, status, error, params });
    console.log(`[Wizard] Action feedback: ${action} - ${status}`);
    res.json({ acknowledged: true });
  } catch (err) {
    console.error('[Wizard] Action feedback error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// POST tool status - track tool execution
app.post('/api/bridge/tool-status', (req, res) => {
  try {
    const { cid, toolCalls } = req.body || {};
    if (!Array.isArray(toolCalls) || toolCalls.length === 0) {
      return res.status(400).json({ error: 'toolCalls array required' });
    }
    for (const tool of toolCalls) {
      pushTelemetry({
        ts: tool.timestamp || Date.now(),
        type: 'tool_call',
        name: tool.name,
        args: tool.args || {},
        status: tool.status || 'completed',
        result: tool.result,
        error: tool.error,
        executionTime: tool.executionTime,
        cid
      });
    }
    res.json({ ok: true, updated: toolCalls.length });
  } catch (err) {
    console.error('[Wizard] Tool status error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// POST chat append - add messages to chat log
app.post('/api/bridge/chat/append', (req, res) => {
  try {
    const { role, text, cid, channel } = req.body || {};
    if (!text) return res.status(400).json({ error: 'text required' });
    const entry = { ts: Date.now(), role: role || 'system', text: String(text), cid, channel: channel || 'agent' };
    chatLog.push(entry);
    if (chatLog.length > 1000) chatLog = chatLog.slice(-800);
    pushTelemetry({ ts: entry.ts, type: 'chat', role: entry.role, text: entry.text, cid, channel });
    res.json({ ok: true });
  } catch (err) {
    console.error('[Wizard] Chat append error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// ─────────────────────────────────────────────────────────────
// Wikipedia Enrichment (server-side — keeps heavy API calls
// out of the Electron renderer process)
// ─────────────────────────────────────────────────────────────

app.post('/api/enrich', async (req, res) => {
  try {
    const { nodeNames, nodeName, minConfidence = 0.40 } = req.body || {};

    if (nodeName) {
      // Single node enrichment
      const result = await enrichSingle(nodeName, { minConfidence });
      return res.json({ ok: true, matches: result ? [result] : [] });
    }

    if (Array.isArray(nodeNames) && nodeNames.length > 0) {
      // Batch enrichment
      const matches = await enrichBatch(nodeNames, { minConfidence });
      return res.json({ ok: true, matches });
    }

    return res.status(400).json({ error: 'nodeNames[] or nodeName required' });
  } catch (err) {
    console.error('[Wizard] Enrich error:', err);
    res.status(500).json({ error: String(err?.message || err) });
  }
});

// ─────────────────────────────────────────────────────────────
// Fallback for unhandled endpoints
// ─────────────────────────────────────────────────────────────

app.all('/api/*', (req, res) => {
  console.log(`[Wizard] Unhandled: ${req.method} ${req.path}`);
  res.status(404).json({
    error: 'Endpoint not available in wizard-server',
    path: req.path,
    available: ['/api/wizard', '/api/bridge/health', '/api/bridge/state', '/api/bridge/pending-actions', '/events/stream']
  });
});

// ─────────────────────────────────────────────────────────────
// Start Server
// ─────────────────────────────────────────────────────────────

// Start server function
export async function startWizardServer() {
  // #region agent log
  debugLogSync('wizard-server.js:startWizardServer:ENTRY', 'startWizardServer called', {}, 'debug-session', 'C');
  // #endregion
  try {
    // Headless mode is OPT-IN via an explicit workspace/universe (flag or env).
    // Bare `npm run wizard` (the Electron embedded bridge) has none, so it stays
    // in browser-relay mode exactly as before — the browser owns its universes.
    let wsFlags = {};
    try {
      ({ values: wsFlags } = parseArgs({
        args: process.argv.slice(2),
        options: { workspace: { type: 'string', short: 'w' }, universe: { type: 'string' } },
        strict: false, allowPositionals: true
      }));
    } catch { /* ignore malformed args */ }
    const explicit = wsFlags.workspace || wsFlags.universe || process.env.REDSTRING_WORKSPACE || process.env.REDSTRING_UNIVERSE;
    if (explicit) {
      try {
        const { dir, activeFileHint } = resolveWorkspace({ flags: wsFlags });
        console.log(`[Wizard] Headless mode: workspace ${dir}`);
        runtime = await initRuntime({ workspaceDir: dir, activeFileHint, log: (...a) => console.error(...a) });
        const active = runtime.getActiveUniverse();
        console.log(`[Wizard] Headless runtime ready — active universe "${active?.name || '?'}" (v${runtime.stateVersion})`);
        installShutdownHandlers();
      } catch (err) {
        console.error(`[Wizard] Failed to start headless runtime: ${err.message}`);
        throw err;
      }
    }

    // #region agent log
    debugLogSync('wizard-server.js:getPort:BEFORE', 'About to call getPort', {}, 'debug-session', 'D');
    // #endregion
    const PORT = await getPort();
    // #region agent log
    debugLogSync('wizard-server.js:getPort:AFTER', 'getPort returned', { port: PORT }, 'debug-session', 'D');
    // #endregion

    return new Promise((resolve, reject) => {
      // Bind to loopback so the wizard server is only reachable from the
      // local machine — it has no auth and exposes graph state + tool
      // execution endpoints that should never be reachable from the LAN.
      const server = app.listen(PORT, '127.0.0.1', () => {
        console.log(`
╔═══════════════════════════════════════════════════════════╗
║                    🧙 THE WIZARD 🧙                        ║
╠═══════════════════════════════════════════════════════════╣
║  Server running on http://localhost:${PORT}                  ║
║                                                           ║
║  Endpoints:                                               ║
║    POST /api/wizard         - Chat with The Wizard        ║
║    GET  /api/bridge/health  - Health check                ║
║    GET  /api/scheduler/status - Queue processor status    ║
╚═══════════════════════════════════════════════════════════╝
`);

        // Start scheduler on boot
        ensureSchedulerStarted().catch(e => {
          console.warn('[Wizard] Failed to start scheduler on boot:', e.message);
        });

        resolve({ server, port: PORT });
      });

      server.on('error', reject);
    });
  } catch (e) {
    console.error('[Wizard] Failed to start:', e.message);
    throw e;
  }
}

// Auto-start when run directly (not imported)
// Check if this is the main module by looking at argv
const isMainModule = process.argv[1]?.endsWith('wizard-server.js');

if (isMainModule) {
  startWizardServer().catch(e => {
    console.error('[Wizard] Startup failed:', e);
    process.exit(1);
  });
}

export default app;