twinclaw 1.0.0

package/dist/api/handlers/persona-state.js

@@ -0,0 +1,59 @@
+import { PersonaConflictError, PersonaValidationError, } from '../../types/persona-state.js';
+import { sendError, sendOk } from '../shared.js';
+function sendPersonaDiagnosticError(res, status, message, diagnostics) {
+    const correlationId = res.locals.correlationId;
+    const body = {
+        ok: false,
+        error: message,
+        data: diagnostics,
+        correlationId,
+        timestamp: new Date().toISOString(),
+    };
+    res.status(status).json(body);
+}
+export function handlePersonaStateGet(deps) {
+    return async (_req, res) => {
+        try {
+            const state = await deps.personaStateService.getState();
+            sendOk(res, state);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, `Failed to load persona state: ${message}`, 500);
+        }
+    };
+}
+export function handlePersonaStateUpdate(deps) {
+    return async (req, res) => {
+        const body = (req.body ?? {});
+        const input = {
+            expectedRevision: body.expectedRevision,
+            soul: body.soul,
+            identity: body.identity,
+            user: body.user,
+        };
+        try {
+            const result = await deps.personaStateService.updateState(input);
+            sendOk(res, result);
+        }
+        catch (error) {
+            if (error instanceof PersonaValidationError) {
+                sendPersonaDiagnosticError(res, 400, error.message, {
+                    hints: error.hints,
+                });
+                return;
+            }
+            if (error instanceof PersonaConflictError) {
+                sendPersonaDiagnosticError(res, 409, error.message, {
+                    hints: error.hints,
+                    latestRevision: error.latestRevision,
+                });
+                return;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            sendPersonaDiagnosticError(res, 500, `Failed to update persona state: ${message}`, {
+                hints: ['Retry the operation. If it persists, inspect local filesystem permissions.'],
+            });
+        }
+    };
+}

package/dist/api/handlers/skill-packages.js

@@ -0,0 +1,94 @@
+import { sendError, sendOk } from '../shared.js';
+function readPackageName(body) {
+    if (!body || typeof body !== 'object' || !('name' in body)) {
+        throw new Error("Request body must include 'name'.");
+    }
+    const candidate = body.name;
+    if (typeof candidate !== 'string' || candidate.trim().length === 0) {
+        throw new Error("Field 'name' must be a non-empty string.");
+    }
+    return candidate.trim();
+}
+function readVersionRange(body) {
+    if (!body || typeof body !== 'object' || !('versionRange' in body)) {
+        return undefined;
+    }
+    const candidate = body.versionRange;
+    if (candidate === undefined || candidate === null) {
+        return undefined;
+    }
+    if (typeof candidate !== 'string') {
+        throw new Error("Field 'versionRange' must be a string when provided.");
+    }
+    const trimmed = candidate.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function mapPackageErrorStatus(message) {
+    if (message.includes('must be') ||
+        message.includes('required') ||
+        message.includes('Invalid')) {
+        return 400;
+    }
+    if (message.includes('No compatible version') ||
+        message.includes('Compatibility gate blocked') ||
+        message.includes('Cannot uninstall')) {
+        return 409;
+    }
+    if (message.includes('not installed')) {
+        return 404;
+    }
+    return 500;
+}
+export function handleSkillPackageDiagnostics(deps) {
+    return async (_req, res) => {
+        try {
+            const diagnostics = await deps.mcpManager.getSkillPackageDiagnostics();
+            sendOk(res, diagnostics);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, message, mapPackageErrorStatus(message));
+        }
+    };
+}
+export function handleSkillPackageInstall(deps) {
+    return async (req, res) => {
+        try {
+            const packageName = readPackageName(req.body);
+            const versionRange = readVersionRange(req.body);
+            const result = await deps.mcpManager.installSkillPackage(packageName, versionRange);
+            sendOk(res, result, result.changed ? 201 : 200);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, message, mapPackageErrorStatus(message));
+        }
+    };
+}
+export function handleSkillPackageUpgrade(deps) {
+    return async (req, res) => {
+        try {
+            const packageName = readPackageName(req.body);
+            const versionRange = readVersionRange(req.body);
+            const result = await deps.mcpManager.upgradeSkillPackage(packageName, versionRange);
+            sendOk(res, result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, message, mapPackageErrorStatus(message));
+        }
+    };
+}
+export function handleSkillPackageUninstall(deps) {
+    return async (req, res) => {
+        try {
+            const packageName = readPackageName(req.body);
+            const result = await deps.mcpManager.uninstallSkillPackage(packageName);
+            sendOk(res, result);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            sendError(res, message, mapPackageErrorStatus(message));
+        }
+    };
+}

package/dist/api/router.js

@@ -0,0 +1,278 @@
+import { createServer } from 'node:http';
+import express from 'express';
+import { handleHealth, handleLiveness, handleReadiness } from './handlers/health.js';
+import { handleBrowserSnapshot, handleBrowserClick } from './handlers/browser.js';
+import { handleWebhookCallback } from './handlers/callback.js';
+import { handleSkillPackageDiagnostics, handleSkillPackageInstall, handleSkillPackageUpgrade, handleSkillPackageUninstall, } from './handlers/skill-packages.js';
+import { handleLocalStateBackupDiagnostics, handleLocalStateCreateSnapshot, handleLocalStateRestoreSnapshot, } from './handlers/local-state-backup.js';
+import { handlePersonaStateGet, handlePersonaStateUpdate, } from './handlers/persona-state.js';
+import { handleConfigValidate } from './handlers/config-validate.js';
+import { requestLogger, requireSignature, sendError } from './shared.js';
+import { BrowserService } from '../services/browser-service.js';
+import { getPersonaStateService } from '../services/persona-state.js';
+import { logThought } from '../utils/logger.js';
+import { getCallbackOutcomeCounts } from '../services/db.js';
+import { sendOk } from './shared.js';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getConfigValue } from '../config/config-loader.js';
+const DEFAULT_PORT = 18789;
+/**
+ * Create and start the Control Plane HTTP API server.
+ *
+ * Endpoints:
+ *   GET  /health              — System health snapshot
+ *   GET  /config/validate     — Runtime config and env-key validation report
+ *   GET  /backup/diagnostics  — Local backup + restore diagnostics
+ *   POST /backup/snapshot     — Trigger manual local-state snapshot
+ *   POST /backup/restore      — Restore local-state snapshot (dry-run supported)
+ *   GET  /skills/packages     — Skill package diagnostics and compatibility state
+ *   POST /skills/packages/*   — Install/upgrade/uninstall skill packages
+ *   GET  /reliability          — Delivery reliability metrics
+ *   GET  /budget/state         — Runtime budget state snapshot
+ *   GET  /budget/events        — Recent budget policy events
+ *   POST /budget/profile       — Manual profile override (signed)
+ *   POST /budget/reset         — Reset budget policy state (signed)
+ *   GET  /routing/telemetry    — Model routing telemetry snapshot
+ *   POST /routing/mode         — Update model routing fallback mode (signed)
+ *   GET  /incidents/current    — Active incident + safe-mode snapshot
+ *   GET  /incidents/history    — Historical incidents and timeline events
+ *   POST /incidents/evaluate   — Force immediate incident detection cycle
+ *   GET  /persona/state        — Read persona source-of-truth state
+ *   PUT  /persona/state        — Safely update persona source-of-truth state
+ *   POST /browser/snapshot     — Take a browser screenshot + accessibility tree
+ *   POST /browser/click        — Click an element by selector or coordinates
+ *   POST /callback/webhook     — Ingest external task completion events (authenticated)
+ */
+export function startApiServer(deps) {
+    const app = express();
+    const port = Number(getConfigValue('API_PORT')) || DEFAULT_PORT;
+    const server = createServer(app);
+    // Attach WebSocket hub if provided
+    if (deps.wsHub) {
+        deps.wsHub.attach(server);
+    }
+    // ── Global Middleware ───────────────────────────────────────────────────────
+    app.use(express.json());
+    app.use(requestLogger);
+    // ── Shared Services ─────────────────────────────────────────────────────────
+    const browserService = new BrowserService();
+    const healthDeps = {
+        heartbeat: deps.heartbeat,
+        skillRegistry: deps.skillRegistry,
+        mcpManager: deps.mcpManager,
+        budgetGovernor: deps.budgetGovernor,
+        localStateBackup: deps.localStateBackup,
+        modelRouter: deps.modelRouter,
+    };
+    const browserDeps = { browserService };
+    const callbackDeps = { gateway: deps.gateway };
+    const skillPackageDeps = { mcpManager: deps.mcpManager };
+    const localStateBackupDeps = { backupService: deps.localStateBackup };
+    const personaStateDeps = {
+        personaStateService: getPersonaStateService(),
+    };
+    // ── Routes ──────────────────────────────────────────────────────────────────
+    app.get('/health', handleHealth(healthDeps));
+    app.get('/health/live', handleLiveness());
+    app.get('/health/ready', handleReadiness(healthDeps));
+    app.get('/config/validate', handleConfigValidate());
+    app.get('/backup/diagnostics', handleLocalStateBackupDiagnostics(localStateBackupDeps));
+    app.post('/backup/snapshot', handleLocalStateCreateSnapshot(localStateBackupDeps));
+    app.post('/backup/restore', handleLocalStateRestoreSnapshot(localStateBackupDeps));
+    app.get('/skills/packages', handleSkillPackageDiagnostics(skillPackageDeps));
+    app.post('/skills/packages/install', handleSkillPackageInstall(skillPackageDeps));
+    app.post('/skills/packages/upgrade', handleSkillPackageUpgrade(skillPackageDeps));
+    app.post('/skills/packages/uninstall', handleSkillPackageUninstall(skillPackageDeps));
+    app.get('/reliability', (_req, res) => {
+        const queueMetrics = deps.dispatcher?.queue.getStats() ?? null;
+        const callbackCounts = getCallbackOutcomeCounts();
+        const callbackMetrics = {
+            totalAccepted: callbackCounts.accepted,
+            totalDuplicate: callbackCounts.duplicate,
+            totalRejected: callbackCounts.rejected,
+        };
+        sendOk(res, {
+            queue: queueMetrics,
+            callbacks: callbackMetrics
+        });
+    });
+    app.get('/budget/state', (req, res) => {
+        if (!deps.budgetGovernor) {
+            sendError(res, 'Runtime budget governor not initialized.', 503);
+            return;
+        }
+        const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId : undefined;
+        sendOk(res, deps.budgetGovernor.getSnapshot(sessionId));
+    });
+    app.get('/budget/events', (req, res) => {
+        if (!deps.budgetGovernor) {
+            sendError(res, 'Runtime budget governor not initialized.', 503);
+            return;
+        }
+        const requestedLimit = Number(req.query.limit ?? 100);
+        const limit = Number.isFinite(requestedLimit) && requestedLimit > 0
+            ? Math.min(500, Math.floor(requestedLimit))
+            : 100;
+        sendOk(res, { events: deps.budgetGovernor.getRecentEvents(limit) });
+    });
+    app.post('/budget/profile', requireSignature, (req, res) => {
+        if (!deps.budgetGovernor) {
+            sendError(res, 'Runtime budget governor not initialized.', 503);
+            return;
+        }
+        const rawProfile = req.body?.profile;
+        if (rawProfile !== null && rawProfile !== undefined && typeof rawProfile !== 'string') {
+            sendError(res, 'Invalid profile. Expected one of: economy, balanced, performance, null.', 400);
+            return;
+        }
+        if (typeof rawProfile === 'string' && !['economy', 'balanced', 'performance'].includes(rawProfile)) {
+            sendError(res, 'Invalid profile. Expected one of: economy, balanced, performance, null.', 400);
+            return;
+        }
+        const profile = typeof rawProfile === 'string'
+            ? rawProfile
+            : null;
+        deps.budgetGovernor.setManualProfile(profile, typeof req.body?.sessionId === 'string' ? req.body.sessionId : undefined);
+        sendOk(res, {
+            message: profile
+                ? `Manual budget profile set to '${profile}'.`
+                : 'Manual budget profile override cleared.',
+            snapshot: deps.budgetGovernor.getSnapshot(typeof req.body?.sessionId === 'string' ? req.body.sessionId : undefined),
+        });
+    });
+    app.post('/budget/reset', requireSignature, (req, res) => {
+        if (!deps.budgetGovernor) {
+            sendError(res, 'Runtime budget governor not initialized.', 503);
+            return;
+        }
+        const sessionId = typeof req.body?.sessionId === 'string' ? req.body.sessionId : undefined;
+        deps.budgetGovernor.resetPolicyState(sessionId);
+        sendOk(res, {
+            message: 'Runtime budget policy state reset.',
+            snapshot: deps.budgetGovernor.getSnapshot(sessionId),
+        });
+    });
+    app.get('/routing/telemetry', (_req, res) => {
+        if (!deps.modelRouter) {
+            sendError(res, 'Model router not initialized.', 503);
+            return;
+        }
+        sendOk(res, deps.modelRouter.getHealthSnapshot());
+    });
+    app.post('/routing/mode', requireSignature, (req, res) => {
+        if (!deps.modelRouter) {
+            sendError(res, 'Model router not initialized.', 503);
+            return;
+        }
+        const mode = req.body?.mode;
+        if (typeof mode !== 'string' || !['intelligent_pacing', 'aggressive_fallback'].includes(mode)) {
+            sendError(res, 'Invalid mode. Expected one of: intelligent_pacing, aggressive_fallback.', 400);
+            return;
+        }
+        const snapshot = deps.modelRouter.setFallbackMode(mode);
+        sendOk(res, {
+            message: `Routing fallback mode set to '${mode}'.`,
+            snapshot,
+        });
+    });
+    app.get('/logs', async (_req, res) => {
+        try {
+            const dateIso = new Date().toISOString().slice(0, 10);
+            const logPath = path.resolve('memory', `${dateIso}.md`);
+            const content = await readFile(logPath, 'utf8').catch(() => 'No logs found for today.');
+            // Simple parsing to turn markdown into a list of "entries"
+            // Entries are separated by ## title @ timestamp
+            const sections = content.split(/\n## /).filter(Boolean);
+            const entries = sections.map(s => {
+                const [header, ...bodyLines] = s.split('\n');
+                const [type, timestamp] = header.split(' @ ');
+                return {
+                    timestamp: timestamp || new Date().toISOString(),
+                    level: type.toUpperCase(),
+                    message: bodyLines.join('\n').trim()
+                };
+            }).reverse().slice(0, 100); // Return last 100 entries
+            sendOk(res, entries);
+        }
+        catch (err) {
+            sendError(res, 'Failed to read logs.', 500);
+        }
+    });
+    app.post('/reliability/replay/:id', (_req, res) => {
+        const id = _req.params.id;
+        if (!deps.dispatcher) {
+            sendError(res, 'Dispatcher not active.', 500);
+            return;
+        }
+        try {
+            deps.dispatcher.queue.requeueDeadLetter(id);
+            sendOk(res, { message: `Queued replay for message ${id}` });
+        }
+        catch (err) {
+            sendError(res, `Failed to requeue: ${err instanceof Error ? err.message : String(err)}`, 500);
+        }
+    });
+    app.get('/incidents/current', (_req, res) => {
+        if (!deps.incidentManager) {
+            sendError(res, 'Incident manager not initialized.', 503);
+            return;
+        }
+        sendOk(res, {
+            safeMode: deps.incidentManager.isSafeModeEnabled(),
+            incidents: deps.incidentManager.getCurrentIncidents(),
+        });
+    });
+    app.get('/incidents/history', (req, res) => {
+        if (!deps.incidentManager) {
+            sendError(res, 'Incident manager not initialized.', 503);
+            return;
+        }
+        const requestedLimit = Number(req.query.limit ?? 200);
+        const limit = Number.isFinite(requestedLimit) && requestedLimit > 0
+            ? Math.min(500, Math.floor(requestedLimit))
+            : 200;
+        sendOk(res, {
+            incidents: deps.incidentManager.getIncidentHistory(limit),
+            timeline: deps.incidentManager.getIncidentTimeline(limit),
+        });
+    });
+    app.post('/incidents/evaluate', (_req, res) => {
+        if (!deps.incidentManager) {
+            sendError(res, 'Incident manager not initialized.', 503);
+            return;
+        }
+        const incidents = deps.incidentManager.evaluateNow();
+        sendOk(res, {
+            safeMode: deps.incidentManager.isSafeModeEnabled(),
+            incidents,
+        });
+    });
+    app.get('/persona/state', handlePersonaStateGet(personaStateDeps));
+    app.put('/persona/state', handlePersonaStateUpdate(personaStateDeps));
+    app.post('/browser/snapshot', handleBrowserSnapshot(browserDeps));
+    app.post('/browser/click', handleBrowserClick(browserDeps));
+    app.post('/callback/webhook', requireSignature, handleWebhookCallback(callbackDeps));
+    app.post('/system/halt', requireSignature, (_req, res) => {
+        void logThought('[API] Received /system/halt request from Control Plane GUI. Halting node process.');
+        sendOk(res, { message: 'Agent halting...' });
+        // Give the response a moment to flush before killing process
+        setTimeout(() => process.exit(0), 500);
+    });
+    app.get('/ws/metrics', (_req, res) => {
+        if (!deps.wsHub) {
+            sendError(res, 'WebSocket hub not initialized.', 503);
+            return;
+        }
+        sendOk(res, deps.wsHub.getMetrics());
+    });
+    // ── Catch-all 404 ──────────────────────────────────────────────────────────
+    app.use((_req, res) => {
+        sendError(res, 'Not found.', 404);
+    });
+    // ── Start ──────────────────────────────────────────────────────────────────
+    server.listen(port, () => {
+        console.log(`[TwinBot API] Control plane listening on http://localhost:${port}`);
+        void logThought(`[API] HTTP server started on port ${port}.`);
+    });
+}

package/dist/api/runtime-event-producer.js

@@ -0,0 +1,99 @@
+import { logThought } from '../utils/logger.js';
+import { getCallbackOutcomeCounts } from '../services/db.js';
+const DEFAULT_PUBLISH_INTERVAL_MS = 5_000;
+/**
+ * Collects state from existing runtime services on a fixed interval and
+ * publishes typed event envelopes through the WebSocket hub.
+ *
+ * Also responds to new-subscription callbacks from the hub by dispatching an
+ * immediate full-state snapshot so newly connected clients receive current
+ * state without waiting for the next polling cycle.
+ */
+export class RuntimeEventProducer {
+    #hub;
+    #deps;
+    #intervalMs;
+    #timer = null;
+    constructor(deps, config = {}) {
+        const { hub, ...rest } = deps;
+        this.#hub = hub;
+        this.#deps = rest;
+        this.#intervalMs = config.publishIntervalMs ?? DEFAULT_PUBLISH_INTERVAL_MS;
+        // When a client subscribes, immediately send a full snapshot
+        this.#hub.onSubscribe = (clientId, topics) => {
+            this.#dispatchSnapshotTo(clientId, topics);
+        };
+    }
+    start() {
+        if (this.#timer)
+            return;
+        this.#timer = setInterval(() => {
+            this.#publishAll();
+        }, this.#intervalMs);
+        void logThought('[RuntimeEventProducer] Started periodic event publishing.');
+    }
+    stop() {
+        if (this.#timer) {
+            clearInterval(this.#timer);
+            this.#timer = null;
+        }
+        void logThought('[RuntimeEventProducer] Stopped.');
+    }
+    // ── Snapshot ───────────────────────────────────────────────────────────────
+    /**
+     * Build a full-state snapshot keyed by topic for the given set of topics.
+     * Used for initial snapshot on subscription and for testing.
+     */
+    collectSnapshot(topics) {
+        const all = !topics || topics.length === 0;
+        const include = (t) => all || topics.includes(t);
+        const snapshot = {};
+        if (include('incidents') && this.#deps.incidentManager) {
+            snapshot.incidents = {
+                safeMode: this.#deps.incidentManager.isSafeModeEnabled(),
+                current: this.#deps.incidentManager.getCurrentIncidents(),
+            };
+        }
+        if (include('routing') && this.#deps.modelRouter) {
+            snapshot.routing = this.#deps.modelRouter.getHealthSnapshot();
+        }
+        if (include('reliability') && this.#deps.dispatcher) {
+            snapshot.reliability = this.#buildReliabilityPayload();
+        }
+        return snapshot;
+    }
+    // ── Private Helpers ────────────────────────────────────────────────────────
+    #publishAll() {
+        if (this.#deps.incidentManager) {
+            this.#hub.publish('incidents', {
+                safeMode: this.#deps.incidentManager.isSafeModeEnabled(),
+                current: this.#deps.incidentManager.getCurrentIncidents(),
+            });
+        }
+        if (this.#deps.modelRouter) {
+            this.#hub.publish('routing', this.#deps.modelRouter.getHealthSnapshot());
+        }
+        if (this.#deps.dispatcher) {
+            this.#hub.publish('reliability', this.#buildReliabilityPayload());
+        }
+    }
+    #buildReliabilityPayload() {
+        const queueMetrics = this.#deps.dispatcher.queue.getStats() ?? null;
+        const callbackCounts = getCallbackOutcomeCounts();
+        return {
+            queue: queueMetrics,
+            callbacks: {
+                totalAccepted: callbackCounts.accepted,
+                totalDuplicate: callbackCounts.duplicate,
+                totalRejected: callbackCounts.rejected,
+            },
+        };
+    }
+    #dispatchSnapshotTo(clientId, subscribedTopics) {
+        const snapshot = this.collectSnapshot(subscribedTopics);
+        if (Object.keys(snapshot).length === 0)
+            return;
+        this.#hub.sendSnapshotTo(clientId, snapshot);
+        void logThought(`[RuntimeEventProducer] Dispatched initial snapshot to client ${clientId}.`);
+    }
+}

package/dist/api/shared.js

@@ -0,0 +1,82 @@
+import { createHmac, timingSafeEqual, randomUUID } from 'node:crypto';
+import { logThought, scrubSensitiveText } from '../utils/logger.js';
+import { getSecretVaultService } from '../services/secret-vault.js';
+// ── Response Helpers ────────────────────────────────────────────────────────
+/** Send a successful JSON response using the standard envelope. */
+export function sendOk(res, data, status = 200) {
+    const correlationId = res.locals.correlationId;
+    const body = {
+        ok: true,
+        data,
+        correlationId,
+        timestamp: new Date().toISOString(),
+    };
+    res.status(status).json(body);
+}
+/** Send an error JSON response using the standard envelope. */
+export function sendError(res, message, status = 400) {
+    const correlationId = res.locals.correlationId;
+    const redactedMessage = scrubSensitiveText(message);
+    const body = {
+        ok: false,
+        error: redactedMessage,
+        correlationId,
+        timestamp: new Date().toISOString(),
+    };
+    res.status(status).json(body);
+}
+// ── Auth Middleware ──────────────────────────────────────────────────────────
+/**
+ * Validate the `X-Signature` header on incoming webhook callbacks.
+ *
+ * Expected format: `sha256=<hex digest of HMAC-SHA256(body, API_SECRET)>`
+ *
+ * If API_SECRET is not configured, all callback requests are rejected.
+ */
+export function requireSignature(req, res, next) {
+    const apiSecret = getSecretVaultService().readSecret('API_SECRET') ?? '';
+    if (!apiSecret) {
+        void logThought('[API] Webhook rejected — API_SECRET not configured.');
+        sendError(res, 'Webhook endpoint not configured (missing API_SECRET).', 503);
+        return;
+    }
+    const signatureHeader = req.headers['x-signature'];
+    if (typeof signatureHeader !== 'string' || !signatureHeader.startsWith('sha256=')) {
+        void logThought('[API] Webhook rejected — missing or malformed X-Signature header.');
+        sendError(res, 'Missing or malformed X-Signature header.', 401);
+        return;
+    }
+    const providedHex = signatureHeader.slice('sha256='.length);
+    const rawBody = JSON.stringify(req.body);
+    const expectedHex = createHmac('sha256', apiSecret).update(rawBody).digest('hex');
+    const provided = Buffer.from(providedHex, 'hex');
+    const expected = Buffer.from(expectedHex, 'hex');
+    if (provided.length !== expected.length || !timingSafeEqual(provided, expected)) {
+        void logThought('[API] Webhook rejected — signature mismatch.');
+        sendError(res, 'Invalid signature.', 403);
+        return;
+    }
+    next();
+}
+// ── Error Mapping ───────────────────────────────────────────────────────────
+/** Map a caught error to a status code and message. */
+export function mapError(err) {
+    if (err instanceof Error) {
+        if (err.message.includes('not initialized') || err.message.includes('not connected')) {
+            return { status: 503, message: scrubSensitiveText(err.message) };
+        }
+        return { status: 500, message: scrubSensitiveText(err.message) };
+    }
+    return { status: 500, message: scrubSensitiveText(String(err)) };
+}
+// ── Logging Middleware ───────────────────────────────────────────────────────
+/** Log every incoming request and inject a correlation ID. */
+export function requestLogger(req, res, next) {
+    const correlationId = randomUUID();
+    res.locals.correlationId = correlationId;
+    const method = req.method;
+    const path = req.path;
+    console.log(`[API] [${correlationId}] ${method} ${path}`);
+    void logThought(`[API] [${correlationId}] ${method} ${path}`);
+    next();
+}