tina4-nodejs 3.12.10 → 3.13.1

package/packages/core/src/devAdmin.ts

@@ -18,6 +18,7 @@ import type { RouteHandler } from "./types.js";
 import { DevMailbox } from "./devMailbox.js";
 import { isTruthy } from "./dotenv.js";
 import { quickMetrics, fullAnalysis, fileDetail } from "./metrics.js";
+import { registerFeedbackRoutes } from "./feedback.js";
 
 const cpuCount = osCpus().length;
 
@@ -433,6 +434,12 @@ export class DevAdmin {
     // Register error handlers to feed the ErrorTracker
     ErrorTracker.register();
 
+    // Customer feedback widget routes — gated at request time by
+    // TINA4_ENABLE_FEEDBACK + TINA4_FEEDBACK_WHITELIST. The handlers
+    // themselves are always registered (so toggling env vars doesn't
+    // require a server restart) but each request re-checks the gate.
+    registerFeedbackRoutes(router);
+
     const routes: Array<{ method: string; pattern: string; handler: RouteHandler }> = [
       // Dashboard
       { method: "GET", pattern: "/__dev", handler: handleDashboard },
@@ -478,8 +485,18 @@ export class DevAdmin {
       { method: "POST", pattern: "/__dev/api/websockets/disconnect", handler: handleWebsocketsDisconnect },
       // Tools
       { method: "POST", pattern: "/__dev/api/tool", handler: handleTool },
-      // Chat
+      // Chat — proxies to Rust agent /chat (SSE passthrough). Forwards
+      // active_file and any other body keys verbatim. See proxyToSupervisor.
       { method: "POST", pattern: "/__dev/api/chat", handler: handleChat },
+      // Threads — proxies to Rust agent /threads. Mirrors Python's
+      // _api_threads + _api_threads_sub.
+      { method: "GET",  pattern: "/__dev/api/threads", handler: handleThreads },
+      { method: "POST", pattern: "/__dev/api/threads", handler: handleThreads },
+      { method: "GET",    pattern: "/__dev/api/threads/{id}", handler: handleThreadsSub },
+      { method: "PATCH",  pattern: "/__dev/api/threads/{id}", handler: handleThreadsSub },
+      { method: "DELETE", pattern: "/__dev/api/threads/{id}", handler: handleThreadsSub },
+      { method: "GET",    pattern: "/__dev/api/threads/{id}/messages", handler: handleThreadsSub },
+      { method: "POST",   pattern: "/__dev/api/threads/{id}/messages", handler: handleThreadsSub },
       // Connections
       { method: "GET", pattern: "/__dev/api/connections", handler: handleConnections },
       { method: "POST", pattern: "/__dev/api/connections/test", handler: handleConnectionsTest },
@@ -623,6 +640,22 @@ const handleReload: RouteHandler = async (req, res) => {
   _reloadFile = (body?.file as string) || "";
   const reloadType = (body?.type as string) || "reload";
   console.log(`  External reload trigger: ${reloadType}${_reloadFile ? ` (${_reloadFile})` : ""}`);
+
+  // Re-discover so new files in src/routes/ register without a server restart.
+  // rediscoverRoutes() is idempotent — already-loaded files are skipped, only
+  // the new ones run. Add the freshly-discovered routes to the default router.
+  try {
+    const { rediscoverRoutes } = await import("./routeDiscovery.js");
+    const newRoutes = await rediscoverRoutes();
+    if (newRoutes.length > 0) {
+      const { defaultRouter } = await import("./router.js");
+      for (const route of newRoutes) defaultRouter.addRoute(route);
+      console.log(`  Re-discovered ${newRoutes.length} new route(s) on reload`);
+    }
+  } catch (err) {
+    console.error(`  Re-discover on reload failed:`, err);
+  }
+
   res.json({ ok: true, type: reloadType });
 };
 
@@ -1155,19 +1188,204 @@ const handleTool: RouteHandler = (req, res) => {
   res.json({ tool, status: "executed", message: `Tool '${tool}' executed (stub)`, timestamp: new Date().toISOString() });
 };
 
+// -- Supervisor proxy helpers --
+
+/**
+ * Return the base URL for the co-located Rust agent server.
+ *
+ * Mirrors Python's `_supervisor_base_url()` in
+ * `tina4_python/dev_admin/__init__.py`. Resolution order:
+ *   1. `TINA4_SUPERVISOR_URL` — explicit full URL.
+ *   2. `TINA4_AGENT_PORT` — explicit port on 127.0.0.1.
+ *   3. `PORT` + 2000 — auto-derived (matches `tina4 serve` agent port).
+ *   4. Fallback `http://127.0.0.1:9145` — matches standalone `tina4 agent`.
+ */
+export function supervisorBaseUrl(): string {
+  const explicit = (process.env.TINA4_SUPERVISOR_URL ?? "").replace(/\/+$/, "");
+  if (explicit) return explicit;
+  const agentPort = (process.env.TINA4_AGENT_PORT ?? "").trim();
+  if (/^\d+$/.test(agentPort)) return `http://127.0.0.1:${parseInt(agentPort, 10)}`;
+  const fwPort = (process.env.PORT ?? "").trim();
+  if (/^\d+$/.test(fwPort)) return `http://127.0.0.1:${parseInt(fwPort, 10) + 2000}`;
+  return "http://127.0.0.1:9145";
+}
+
+/**
+ * Forward a dev-admin request to the Rust agent server.
+ *
+ * Mirrors Python's `_proxy_to_supervisor()`. Strips the `/__dev/api` prefix,
+ * forwards method/body/query verbatim to `<base>{downstreamPath}`, and pipes
+ * the response back. SSE (`text/event-stream`) is streamed chunk-by-chunk so
+ * progress events reach the SPA live instead of after the full multi-agent
+ * run completes. When the agent is unreachable we respond with 503 and a
+ * hint so the SPA can show a useful error.
+ */
+async function proxyToSupervisor(
+  req: any,
+  res: any,
+  downstreamPath: string,
+): Promise<void> {
+  const base = supervisorBaseUrl();
+
+  // Forward query string verbatim
+  let qs = "";
+  try {
+    const reqUrl = new URL(req.url ?? "/", "http://localhost");
+    if (reqUrl.search) qs = reqUrl.search;
+  } catch { /* ignore */ }
+  const target = `${base}${downstreamPath}${qs}`;
+
+  const method = (req.method ?? "GET").toUpperCase();
+
+  // Build the body for methods that carry one
+  let bodyText: string | undefined;
+  if (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE") {
+    const body = (req as any).body;
+    if (body !== undefined && body !== null) {
+      if (typeof body === "string") {
+        bodyText = body;
+      } else if (typeof body === "object") {
+        // SPA→agent convention fixup (matches Python): `/execute` sends
+        // plan_file as a bare filename but the rust agent expects a
+        // project-relative path. Prepend `plan/` when no slash is present.
+        let outBody: any = body;
+        if (!Array.isArray(body)) {
+          const pf = (body as any).plan_file;
+          if (typeof pf === "string" && pf && !pf.includes("/")) {
+            outBody = { ...body, plan_file: `plan/${pf}` };
+          }
+        }
+        bodyText = JSON.stringify(outBody);
+      }
+    }
+  }
+
+  // Heavy multi-agent endpoints get a generous timeout; metadata-only
+  // /supervise/* and /threads/* calls return fast.
+  const timeoutMs = downstreamPath === "/execute" || downstreamPath === "/chat" ? 600_000 : 30_000;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(target, {
+      method,
+      headers: { "Content-Type": "application/json" },
+      body: bodyText,
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    res.json(
+      {
+        error: "supervisor unavailable",
+        detail: (e as Error).message,
+        hint: "Run `tina4 serve` (starts the agent server) or set TINA4_SUPERVISOR_URL",
+      },
+      503,
+    );
+    return;
+  }
+
+  const ct = (upstream.headers.get("content-type") ?? "").toLowerCase();
+
+  // SSE / event-stream — stream chunks through as they arrive.
+  if (ct.includes("text/event-stream")) {
+    res.raw.writeHead(upstream.status || 200, {
+      "Content-Type": upstream.headers.get("content-type") ?? "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive",
+    });
+    if (typeof (res.raw as any).flushHeaders === "function") {
+      (res.raw as any).flushHeaders();
+    }
+    if (!upstream.body) {
+      res.raw.end();
+      clearTimeout(timer);
+      return;
+    }
+    const reader = upstream.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) res.raw.write(Buffer.from(value));
+      }
+    } finally {
+      clearTimeout(timer);
+      res.raw.end();
+    }
+    return;
+  }
+
+  clearTimeout(timer);
+
+  // JSON / other — drain the body and return as before.
+  const raw = await upstream.text();
+  const status = upstream.status || 200;
+  try {
+    res.json(JSON.parse(raw), status);
+  } catch {
+    // Non-JSON upstream — pass through as text with the same status.
+    res.raw.writeHead(status, {
+      "Content-Type": upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
+    });
+    res.raw.end(raw);
+  }
+}
+
 // -- Chat handler --
+//
+// Proxies POST /__dev/api/chat → Rust agent `POST /chat`. The SPA's Chat
+// view POSTs `{message, settings?, thread_id?, active_file?, files?}` and
+// expects an SSE stream of `event: status / message / done` chunks.
+// active_file (and any other body keys) are forwarded verbatim.
+const handleChat: RouteHandler = async (req, res) => {
+  await proxyToSupervisor(req, res, "/chat");
+};
+
+// -- Threads handlers --
 
-const handleChat: RouteHandler = (req, res) => {
-  const message = (req as any).body?.message ?? "";
-  if (!message) {
-    res.json({ error: "Missing message parameter" });
+/**
+ * Proxy /__dev/api/threads → Rust agent /threads.
+ *   GET  → list threads
+ *   POST → create thread
+ * Method-multiplexed — anything else gets a 405.
+ */
+const handleThreads: RouteHandler = async (req, res) => {
+  const method = (req.method ?? "GET").toUpperCase();
+  if (method !== "GET" && method !== "POST") {
+    res.json({ error: "method not allowed" }, 405);
     return;
   }
-  // Placeholder AI chat response
-  res.json({
-    reply: `AI chat is not yet configured. You said: "${message}"`,
-    timestamp: new Date().toISOString(),
-  });
+  await proxyToSupervisor(req, res, "/threads");
+};
+
+/**
+ * Proxy /__dev/api/threads/{id}[/messages] → Rust agent.
+ *
+ * Strips the dev-admin prefix and forwards the remaining path verbatim so
+ * /__dev/api/threads/abc/messages becomes /threads/abc/messages on the
+ * agent side. Mirrors Python's `_api_threads_sub`.
+ */
+const handleThreadsSub: RouteHandler = async (req, res) => {
+  let pathname = "";
+  try {
+    pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+  } catch {
+    pathname = req.url ?? "";
+  }
+  const prefix = "/__dev/api";
+  if (!pathname.startsWith(prefix)) {
+    res.json({ error: "not found" }, 404);
+    return;
+  }
+  const suffix = pathname.slice(prefix.length); // "/threads/abc[/messages]"
+  if (!suffix.startsWith("/threads/")) {
+    res.json({ error: "not found" }, 404);
+    return;
+  }
+  await proxyToSupervisor(req, res, suffix);
 };
 
 // ---------------------------------------------------------------------------

package/packages/core/src/errorOverlay.ts

@@ -19,7 +19,7 @@
  * In production, call renderProductionError() instead.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { isTruthy } from "./dotenv.js";
 
@@ -111,8 +111,38 @@ function formatSourceBlock(filename: string, lineno: number): string {
     + rows + `</div>`;
 }
 
-function formatFrame(frame: StackFrame): string {
+/**
+ * Render one stack frame.
+ *
+ * When the file was modified AFTER `capturedAt`, append a peach
+ * "FILE MODIFIED" badge so a stale browser-cached overlay can't lie
+ * about what the source looks like now. The AI coder often rewrites
+ * files in place between page loads, leaving the overlay's source
+ * view showing different code than what raised the error.
+ *
+ * `capturedAt` is in seconds (Date.now() / 1000) for parity with
+ * Python's time.time().
+ */
+function formatFrame(frame: StackFrame, capturedAt = 0): string {
   const source = frame.file && frame.line > 0 ? formatSourceBlock(frame.file, frame.line) : "";
+  let staleBadge = "";
+  if (capturedAt && frame.file) {
+    try {
+      const absPath = resolve(frame.file);
+      const mtime = statSync(absPath).mtimeMs / 1000;
+      if (mtime > capturedAt + 0.5) {  // 0.5s margin for fs noise
+        const d = new Date(mtime * 1000);
+        const mtimeIso = `${String(d.getUTCHours()).padStart(2, "0")}:`
+          + `${String(d.getUTCMinutes()).padStart(2, "0")}:`
+          + `${String(d.getUTCSeconds()).padStart(2, "0")}`;
+        staleBadge = ` <span style="background:${PEACH};color:${BG};padding:1px 8px;`
+          + `border-radius:3px;font-size:11px;font-weight:700;margin-left:6px;">`
+          + `FILE MODIFIED @ ${mtimeIso} UTC &mdash; source may not match what failed</span>`;
+      }
+    } catch {
+      // best-effort — ignore missing files / permission errors
+    }
+  }
   return `<div style="margin-bottom:16px;">`
     + `<div style="margin-bottom:4px;">`
     + `<span style="color:${BLUE};">${esc(frame.file)}</span>`
@@ -120,6 +150,7 @@ function formatFrame(frame: StackFrame): string {
     + `<span style="color:${YELLOW};">${frame.line}</span>`
     + `<span style="color:${SUBTEXT};"> in </span>`
     + `<span style="color:${GREEN};">${esc(frame.func)}</span>`
+    + staleBadge
     + `</div>`
     + source
     + `</div>`;
@@ -153,14 +184,21 @@ function table(pairs: Array<[string, string]>): string {
  * @returns Complete HTML page string.
  */
 export function renderErrorOverlay(error: Error, request?: any): string {
+  // Stamp ONCE per render — every frame compares against this. Seconds-since-epoch
+  // matches Python's time.time() so frames stale by < 0.5s of fs noise don't trip.
+  const capturedAt = Date.now() / 1000;
   const excType = error.constructor?.name ?? "Error";
   const excMsg = error.message ?? String(error);
   const frames = error.stack ? parseStack(error.stack) : [];
 
   // ── Stack trace ──
+  // Each frame compares its source file's mtime to capturedAt and flags itself
+  // if the file has been modified since — protects against the "browser cached
+  // an old overlay, then the AI rewrote the file" confusion where displayed
+  // source no longer matches what actually raised the error.
   let framesHtml = "";
   for (const frame of frames) {
-    framesHtml += formatFrame(frame);
+    framesHtml += formatFrame(frame, capturedAt);
   }
 
   // ── Request info ──

package/packages/core/src/feedback.ts

@@ -0,0 +1,277 @@
+/**
+ * Customer feedback widget — Tier 4 port from tina4-python.
+ *
+ * End-users of a shipped Tina4 app give UX feedback via a floating bubble
+ * widget. Widget visibility + API are gated by TWO env flags:
+ *
+ *   - TINA4_ENABLE_FEEDBACK   master switch (explicit opt-in)
+ *   - TINA4_FEEDBACK_WHITELIST comma-separated emails / user IDs
+ *
+ * Architecture (mirrors Python `tina4_python/dev_admin/__init__.py`
+ * lines 1440-1645):
+ *
+ *   1. Framework middleware injects <script src="/__feedback/widget.js">
+ *      into HTML responses for whitelisted users only.
+ *   2. Widget POSTs to /__feedback/api/turn for each conversational turn.
+ *   3. That handler verifies whitelist + rate-limit, stamps the user
+ *      identity server-side (client cannot fake `sender`), then forwards
+ *      to the Rust agent's /feedback/intake.
+ *
+ * The widget is for END USERS of a shipped app — the /__dev paths get
+ * skipped so the dev admin's own chat bubble doesn't sit on top of the
+ * customer feedback bubble.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { authenticateRequest } from "./auth.js";
+import { supervisorBaseUrl } from "./devAdmin.js";
+import type { RouteHandler, Tina4Request } from "./types.js";
+import type { Router } from "./router.js";
+
+// ── Module-level rate-limit state ──────────────────────────────
+// 5 turns/hour per identified user. Stored in-memory only; this is
+// per-process — for multi-instance deployments a shared backend would
+// be needed, but the python reference is the same shape.
+const RATE_LIMIT_WINDOW_SEC = 3600;
+const RATE_LIMIT_MAX = 5;
+const _rateLimitHits = new Map<string, number[]>();
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+/**
+ * Master switch — both this AND a non-empty whitelist must be set for
+ * the widget to render or the API to accept submissions. Mirrors
+ * Python's `_feedback_enabled()`.
+ */
+export function feedbackEnabled(): boolean {
+  const raw = (process.env.TINA4_ENABLE_FEEDBACK ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+
+/**
+ * Comma-separated emails / user IDs in env, lowercased + trimmed.
+ * Returns [] when the master switch is off so callers can short-circuit
+ * with a single check. Mirrors Python's `_feedback_whitelist()`.
+ */
+export function feedbackWhitelist(): string[] {
+  if (!feedbackEnabled()) return [];
+  const raw = (process.env.TINA4_FEEDBACK_WHITELIST ?? "").trim();
+  if (!raw) return [];
+  return raw
+    .split(",")
+    .map((e) => e.trim().toLowerCase())
+    .filter((e) => e.length > 0);
+}
+
+/**
+ * Best-effort user identity from JWT/Bearer auth. Falls back to
+ * TINA4_FEEDBACK_DEV_USER (local dev convenience — lets the framework
+ * owner test the widget without a full auth setup). Mirrors Python's
+ * `_feedback_identify_user()`.
+ */
+export function feedbackIdentifyUser(request: Tina4Request): string | null {
+  try {
+    const payload = authenticateRequest(
+      (request.headers ?? {}) as Record<string, string | string[] | undefined>,
+    );
+    if (payload && typeof payload === "object") {
+      for (const key of ["email", "sub", "user_id"]) {
+        const v = (payload as Record<string, unknown>)[key];
+        if (v) return String(v).trim().toLowerCase();
+      }
+    }
+  } catch {
+    /* ignore — fall through to dev override */
+  }
+  const dev = (process.env.TINA4_FEEDBACK_DEV_USER ?? "").trim();
+  if (dev) return dev.toLowerCase();
+  return null;
+}
+
+/**
+ * Returns [allowed, userId]. Both halves are required — feature off when
+ * either is falsy. Mirrors Python's `_feedback_is_whitelisted()`.
+ */
+export function feedbackIsWhitelisted(
+  request: Tina4Request,
+): [boolean, string | null] {
+  const wl = feedbackWhitelist();
+  if (wl.length === 0) return [false, null];
+  const user = feedbackIdentifyUser(request);
+  if (!user) return [false, null];
+  return [wl.includes(user), user];
+}
+
+/**
+ * 5 turns/hour per user, sliding window. Prunes old timestamps lazily on
+ * every call (no background task needed). Mirrors Python's
+ * `_feedback_rate_limit_ok()`.
+ */
+export function feedbackRateLimitOk(user: string): boolean {
+  const now = Date.now() / 1000;
+  const prior = _rateLimitHits.get(user) ?? [];
+  const fresh = prior.filter((t) => now - t < RATE_LIMIT_WINDOW_SEC);
+  if (fresh.length >= RATE_LIMIT_MAX) {
+    _rateLimitHits.set(user, fresh);
+    return false;
+  }
+  fresh.push(now);
+  _rateLimitHits.set(user, fresh);
+  return true;
+}
+
+/** Test-only: clear rate-limit state between cases. Not part of public API. */
+export function _resetFeedbackRateLimit(): void {
+  _rateLimitHits.clear();
+}
+
+/**
+ * Insert the widget <script> into HTML for whitelisted users. Called
+ * from the response pipeline right before the body is flushed. No-op if:
+ *   - request path starts with /__dev or /__feedback (developer
+ *     pages have their own chat trigger)
+ *   - master switch / whitelist not set
+ *   - user not in whitelist
+ *   - html lacks </body>
+ * Idempotent — looks for the `data-tina4-feedback` marker and bails.
+ * Mirrors Python's `inject_feedback_widget()`.
+ */
+export function injectFeedbackWidget(
+  request: Tina4Request,
+  html: string,
+): string {
+  if (!html) return html;
+  const path = (request.path ?? "") || "";
+  if (path.startsWith("/__dev") || path.startsWith("/__feedback")) return html;
+  if (html.includes("data-tina4-feedback")) return html;
+  const [allowed] = feedbackIsWhitelisted(request);
+  if (!allowed) return html;
+  const lastBody = html.lastIndexOf("</body>");
+  if (lastBody < 0) return html;
+  const snippet =
+    '<script src="/__feedback/widget.js" data-tina4-feedback></script>';
+  return html.slice(0, lastBody) + snippet + html.slice(lastBody);
+}
+
+// ── Route handlers ──────────────────────────────────────────────
+
+/**
+ * POST /__feedback/api/turn — proxy one conversational turn to the Rust
+ * agent's `/feedback/intake`. Server stamps `sender` from the verified
+ * identity so the client cannot inject who they are. Mirrors Python's
+ * `_api_feedback_turn()`.
+ */
+export const handleFeedbackTurn: RouteHandler = async (req, res) => {
+  const [allowed, user] = feedbackIsWhitelisted(req);
+  if (!allowed || !user) {
+    res.json({ error: "not authorised for feedback" }, 403);
+    return;
+  }
+  if (!feedbackRateLimitOk(user)) {
+    res.json(
+      {
+        error: "rate limit exceeded",
+        hint: `max ${RATE_LIMIT_MAX} turns per hour`,
+      },
+      429,
+    );
+    return;
+  }
+
+  const body = (req as Tina4Request).body;
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    res.json({ error: "expected JSON body" }, 400);
+    return;
+  }
+
+  // Stamp sender server-side — client cannot override identity.
+  const forwardBody = { ...(body as Record<string, unknown>), sender: user };
+  const base = supervisorBaseUrl();
+  const target = `${base}/feedback/intake`;
+
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), 60_000);
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(target, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(forwardBody),
+      signal: ctrl.signal,
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    res.json(
+      { error: "agent unreachable", detail: (e as Error).message },
+      502,
+    );
+    return;
+  }
+  clearTimeout(timer);
+
+  const raw = await upstream.text();
+  const status = upstream.status || 200;
+  try {
+    res.json(JSON.parse(raw), status);
+  } catch {
+    res.raw.writeHead(status, {
+      "Content-Type":
+        upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
+    });
+    res.raw.end(raw);
+  }
+};
+
+// Widget bundle lives at packages/core/src/__feedback/widget.js so that
+// it isn't auto-served by the static-file handler (which would skip the
+// no-cache headers below).
+const __feedbackDirname = dirname(fileURLToPath(import.meta.url));
+const WIDGET_BUNDLE_PATH = resolve(__feedbackDirname, "__feedback", "widget.js");
+
+/**
+ * GET /__feedback/widget.js — serve the widget bundle with no-cache
+ * headers so a broken bundle doesn't get stuck in browser caches.
+ * Mirrors Python's `_api_feedback_widget_js()`.
+ */
+export const handleFeedbackWidgetJs: RouteHandler = (_req, res) => {
+  let body: Buffer | string;
+  if (existsSync(WIDGET_BUNDLE_PATH)) {
+    body = readFileSync(WIDGET_BUNDLE_PATH);
+  } else {
+    body = "console.warn('tina4-feedback-widget bundle not built yet');";
+  }
+  res.raw.writeHead(200, {
+    "Content-Type": "application/javascript; charset=utf-8",
+    "Cache-Control": "no-cache, must-revalidate",
+    Pragma: "no-cache",
+  });
+  res.raw.end(body);
+};
+
+/**
+ * Register the two feedback routes on a Router. Called from the dev
+ * admin setup so the routes only exist when the dev surface is
+ * enabled — production deployments without TINA4_DEBUG also skip them.
+ */
+export function registerFeedbackRoutes(router: Router): void {
+  router.addRoute({
+    method: "POST",
+    pattern: "/__feedback/api/turn",
+    handler: handleFeedbackTurn,
+  });
+  router.addRoute({
+    method: "GET",
+    pattern: "/__feedback/widget.js",
+    handler: handleFeedbackWidgetJs,
+  });
+}
+
+// Re-export the bundle path so other tools (e.g. CLI builds) can find it.
+export { WIDGET_BUNDLE_PATH };
+// Silence unused-import lint where the helpers are imported but `join` isn't
+// used in this file's current code path. (Kept available for future tweaks.)
+void join;