tina4-nodejs 3.12.10 → 3.13.0

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.12.10)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.0)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.12.10 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.0 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -548,7 +548,7 @@ r.group("/api/v1", (g) => {
 
 ## Module: Database (`packages/orm/src/database.ts`)
 
-Full Database API. The same instance covers all five drivers (sqlite, postgres, mysql, mssql, firebird) — pick the driver via `DATABASE_URL` or pass a `DatabaseConfig` to `initDatabase()`.
+Full Database API. The same instance covers all five drivers (sqlite, postgres, mysql, mssql, firebird) — pick the driver via `TINA4_DATABASE_URL` or pass a `DatabaseConfig` to `initDatabase()`.
 
 ```typescript
 import { initDatabase, Database, DatabaseResult } from "@tina4/orm";
@@ -956,26 +956,26 @@ import { Router } from "./router.js";  // .js even though the file is .ts
 ## Database Configuration
 
 ### Connection string format
-Set `DATABASE_URL` in your `.env` file using `driver://host:port/database` format:
+Set `TINA4_DATABASE_URL` in your `.env` file using `driver://host:port/database` format:
 
 ```bash
 # SQLite (default if nothing configured)
-DATABASE_URL=sqlite:///path/to/db.sqlite
-DATABASE_URL=sqlite://./data/tina4.db
+TINA4_DATABASE_URL=sqlite:///path/to/db.sqlite
+TINA4_DATABASE_URL=sqlite://./data/tina4.db
 
 # PostgreSQL
-DATABASE_URL=postgres://localhost:5432/mydb
-DATABASE_URL=postgresql://localhost:5432/mydb
+TINA4_DATABASE_URL=postgres://localhost:5432/mydb
+TINA4_DATABASE_URL=postgresql://localhost:5432/mydb
 
 # MySQL
-DATABASE_URL=mysql://localhost:3306/mydb
+TINA4_DATABASE_URL=mysql://localhost:3306/mydb
 
 # MSSQL / SQL Server (both schemes work)
-DATABASE_URL=mssql://localhost:1433/mydb
-DATABASE_URL=sqlserver://localhost:1433/mydb
+TINA4_DATABASE_URL=mssql://localhost:1433/mydb
+TINA4_DATABASE_URL=sqlserver://localhost:1433/mydb
 
 # Firebird
-DATABASE_URL=firebird://localhost:3050/mydb
+TINA4_DATABASE_URL=firebird://localhost:3050/mydb
 ```
 
 ### Credentials
@@ -983,15 +983,15 @@ Credentials can be embedded in the URL or provided separately:
 
 ```bash
 # In the URL
-DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+TINA4_DATABASE_URL=postgres://user:pass@localhost:5432/mydb
 
 # Or as separate env vars (merged when URL has no credentials)
-DATABASE_URL=postgres://localhost:5432/mydb
-DATABASE_USERNAME=myuser
-DATABASE_PASSWORD=mypass
+TINA4_DATABASE_URL=postgres://localhost:5432/mydb
+TINA4_DATABASE_USERNAME=myuser
+TINA4_DATABASE_PASSWORD=mypass
 ```
 
-Credential priority: `config.user` > `config.username` > `DATABASE_USERNAME` env var.
+Credential priority: `config.user` > `config.username` > `TINA4_DATABASE_USERNAME` env var.
 
 ### Programmatic configuration
 ```typescript

package/package.json

@@ -3,11 +3,20 @@
 
 
 
-  "version": "3.12.10",
+  "version": "3.13.0",
 
   "type": "module",
-  "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",
-  "keywords": ["tina4", "framework", "web", "api", "orm", "graphql", "websocket", "typescript"],
+  "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",
+  "keywords": [
+    "tina4",
+    "framework",
+    "web",
+    "api",
+    "orm",
+    "graphql",
+    "websocket",
+    "typescript"
+  ],
   "homepage": "https://tina4.com/nodejs",
   "repository": {
     "type": "git",
@@ -59,4 +68,4 @@
     "tsx": "^4.19.0",
     "esbuild": "^0.24.0"
   }
-}
+}

package/packages/cli/src/commands/migrate.ts

@@ -10,8 +10,14 @@
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { loadEnv } from "../../../core/src/dotenv.js";
 
 export async function runMigrations(migrationDir?: string): Promise<void> {
+  // Load .env before initialising the DB so DATABASE_URL/TINA4_DATABASE_URL
+  // from the project's .env is visible. Without this the migrate command
+  // falls back to ./data/tina4.db regardless of what the project configured.
+  loadEnv();
+
   const dir = resolve(migrationDir ?? "migrations");
 
   if (!existsSync(dir)) {
@@ -40,11 +46,15 @@ export async function runMigrations(migrationDir?: string): Promise<void> {
     process.exit(1);
   }
 
-  // Ensure database is initialised (uses DATABASE_URL or defaults to sqlite)
+  // Ensure database is initialised (uses TINA4_DATABASE_URL/DATABASE_URL or
+  // defaults to sqlite). initDatabase() is async — MUST be awaited, otherwise
+  // setAdapter() has not run by the time ensureMigrationTable() asks for the
+  // adapter and the whole CLI crashes with "No database adapter configured."
   try {
-    initDatabase();
-  } catch {
-    // Adapter may already be set — ignore
+    await initDatabase();
+  } catch (err) {
+    console.error(`  Error initialising database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
   ensureMigrationTable();

package/packages/cli/src/commands/migrateRollback.ts

@@ -9,8 +9,13 @@
  *   tina4 migrate:rollback ./path/to/migrations
  */
 import { resolve } from "node:path";
+import { loadEnv } from "../../../core/src/dotenv.js";
 
 export async function migrateRollback(migrationDir?: string): Promise<void> {
+  // .env must load before initDatabase() — otherwise DATABASE_URL from the
+  // project's .env is invisible and we silently fall back to ./data/tina4.db.
+  loadEnv();
+
   const dir = resolve(migrationDir ?? "migrations");
 
   let initDatabase: typeof import("../../../orm/src/index.js").initDatabase;
@@ -29,11 +34,14 @@ export async function migrateRollback(migrationDir?: string): Promise<void> {
     process.exit(1);
   }
 
-  // Ensure database is initialised
+  // Ensure database is initialised — MUST await; initDatabase() is async
+  // and calls setAdapter() inside the promise. Without await, the next call
+  // to getAdapter() throws "No database adapter configured."
   try {
-    initDatabase();
-  } catch {
-    // Adapter may already be set — ignore
+    await initDatabase();
+  } catch (err) {
+    console.error(`  Error initialising database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
   ensureMigrationTable();

package/packages/cli/src/commands/migrateStatus.ts

@@ -6,8 +6,12 @@
  *   tina4 migrate:status ./path/to/migrations
  */
 import { resolve } from "node:path";
+import { loadEnv } from "../../../core/src/dotenv.js";
 
 export async function migrateStatus(migrationDir?: string): Promise<void> {
+  // .env must load before initDatabase() so the project's DATABASE_URL is seen.
+  loadEnv();
+
   const dir = resolve(migrationDir ?? "migrations");
 
   let initDatabase: typeof import("../../../orm/src/index.js").initDatabase;
@@ -24,11 +28,13 @@ export async function migrateStatus(migrationDir?: string): Promise<void> {
     process.exit(1);
   }
 
-  // Ensure database is initialised
+  // Ensure database is initialised — MUST await; initDatabase() is async
+  // and calls setAdapter() inside. Without await, getAdapter() throws.
   try {
-    initDatabase();
-  } catch {
-    // Adapter may already be set — ignore
+    await initDatabase();
+  } catch (err) {
+    console.error(`  Error initialising database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
   }
 
   ensureMigrationTable();

package/packages/core/src/__feedback/widget.js

@@ -0,0 +1,96 @@
+(function(){"use strict";(()=>{try{const t=window.location.pathname||"";return t.startsWith("/__dev")||t.startsWith("/__feedback")}catch{return!1}})()?console.info("tina4-feedback-widget: skipping on developer path"):window.__tina4FeedbackLoaded?console.warn("tina4-feedback-widget already loaded; skipping"):(window.__tina4FeedbackLoaded=!0,b());function b(){const c=(getComputedStyle(document.documentElement).getPropertyValue("--primary")||"").trim()||"#3b82f6";h(c);const l=m();document.body.appendChild(l);let e=null,u;const r=[];l.addEventListener("click",()=>{if(e){e.remove(),e=null,l.style.display="";return}e=g(),document.body.appendChild(e),l.style.display="none",setTimeout(()=>e?.querySelector("textarea")?.focus(),0)});function g(){const o=document.createElement("div");o.className="tina4-fb-modal",o.innerHTML=`
+      <div class="tina4-fb-head">
+        <span class="tina4-fb-title">Tell us what's not working</span>
+        <button type="button" class="tina4-fb-close" aria-label="Close">×</button>
+      </div>
+      <div class="tina4-fb-context">
+        <span>📍 ${p(location.pathname+location.search)}</span>
+        <span>📐 ${window.innerWidth}×${window.innerHeight}</span>
+      </div>
+      <div class="tina4-fb-chat" role="log"></div>
+      <form class="tina4-fb-form">
+        <textarea
+          rows="3"
+          placeholder="What's hard to use here? Be specific — which field, which button, what you expected."
+          aria-label="Feedback message"
+        ></textarea>
+        <button type="submit" class="tina4-fb-send">Send</button>
+      </form>
+    `,o.querySelector(".tina4-fb-close")?.addEventListener("click",()=>{o.remove(),e=null,l.style.display=""});const a=o.querySelector("form");return a.addEventListener("submit",n=>{n.preventDefault();const i=a.querySelector("textarea"),f=i.value.trim();f&&(i.value="",x(f))}),s(o),o}function s(o){const a=o.querySelector(".tina4-fb-chat");if(a){if(!r.length){a.innerHTML=`<div class="tina4-fb-hint">Your feedback lands directly with the team — no email loop. We'll ask a quick follow-up if we need to.</div>`;return}a.innerHTML=r.map(n=>`<div class="tina4-fb-msg ${n.role==="user"?"tina4-fb-user":"tina4-fb-ai"}">${p(n.text)}</div>`).join(""),a.scrollTop=a.scrollHeight}}async function x(o){if(!e)return;r.push({role:"user",text:o}),s(e),d(e,!0);const a={message:o,context:{url:location.pathname+location.search,viewport:`${window.innerWidth}x${window.innerHeight}`,ua:navigator.userAgent},conversation_id:u};let n;try{const i=await fetch("/__feedback/api/turn",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(a)});if(n=await i.json(),!i.ok){const f=n?.error||`HTTP ${i.status}`;r.push({role:"ai",text:`Couldn't send: ${f}`}),s(e),d(e,!1);return}}catch(i){r.push({role:"ai",text:`Network issue: ${i?.message||i}`}),s(e),d(e,!1);return}if("ask"in n)u=n.conversation_id,r.push({role:"ai",text:n.ask}),s(e),d(e,!1),e?.querySelector("textarea")?.focus();else if("final"in n)r.push({role:"ai",text:`Thanks — filed as: "${n.final.title}". The team will take it from here.`}),s(e),d(e,!1),u=void 0,r.length=0,setTimeout(()=>{e?.remove(),e=null,l.style.display=""},4500);else{const i=n?.error||"unexpected response";r.push({role:"ai",text:`Issue: ${i}`}),s(e),d(e,!1)}}function d(o,a){const n=o.querySelector(".tina4-fb-send"),i=o.querySelector("textarea");n&&(n.disabled=a,n.textContent=a?"Sending…":"Send"),i&&(i.disabled=a)}}function m(){const t=document.createElement("button");return t.type="button",t.className="tina4-fb-btn",t.setAttribute("aria-label","Send feedback"),t.innerHTML="💬",t.title="Tell us what's not working",t}function h(t){const c=document.createElement("style");c.id="tina4-fb-styles",c.textContent=`
+    .tina4-fb-btn {
+      position: fixed; bottom: 1.25rem; right: 1.25rem;
+      width: 48px; height: 48px; border-radius: 50%; border: none;
+      background: ${t}; color: white; font-size: 1.4rem;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.18); cursor: pointer;
+      z-index: 2147483646; transition: transform 0.15s, box-shadow 0.15s;
+      display: flex; align-items: center; justify-content: center;
+      line-height: 1; padding: 0;
+    }
+    .tina4-fb-btn:hover { transform: scale(1.06); box-shadow: 0 6px 16px rgba(0,0,0,0.22); }
+    .tina4-fb-btn:active { transform: scale(0.96); }
+    .tina4-fb-modal {
+      position: fixed; bottom: 5rem; right: 1.25rem;
+      width: 340px; max-height: 480px; display: flex; flex-direction: column;
+      background: #1e1e2e; color: #cdd6f4;
+      border: 1px solid #313244; border-radius: 8px;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.35);
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+      font-size: 0.85rem; z-index: 2147483647;
+      animation: tina4-fb-in 0.18s ease-out;
+    }
+    @keyframes tina4-fb-in {
+      from { opacity: 0; transform: translateY(8px); }
+      to   { opacity: 1; transform: translateY(0); }
+    }
+    .tina4-fb-head {
+      display: flex; align-items: center; justify-content: space-between;
+      padding: 0.6rem 0.8rem; border-bottom: 1px solid #313244;
+    }
+    .tina4-fb-title { font-weight: 600; font-size: 0.9rem; }
+    .tina4-fb-close {
+      background: transparent; border: none; color: #9399b2;
+      font-size: 1.4rem; line-height: 1; cursor: pointer; padding: 0 0.2rem;
+    }
+    .tina4-fb-close:hover { color: #cdd6f4; }
+    .tina4-fb-context {
+      display: flex; gap: 0.6rem; padding: 0.4rem 0.8rem;
+      font-size: 0.7rem; color: #9399b2;
+      border-bottom: 1px solid #313244;
+      font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    }
+    .tina4-fb-chat {
+      flex: 1; overflow-y: auto; padding: 0.5rem 0.8rem;
+      display: flex; flex-direction: column; gap: 0.4rem;
+      min-height: 80px; max-height: 280px;
+    }
+    .tina4-fb-hint {
+      font-size: 0.75rem; color: #9399b2; line-height: 1.4; padding: 0.3rem 0;
+    }
+    .tina4-fb-msg {
+      padding: 0.4rem 0.6rem; border-radius: 6px;
+      max-width: 85%; word-wrap: break-word; line-height: 1.35;
+    }
+    .tina4-fb-user { align-self: flex-end; background: ${t}; color: white; }
+    .tina4-fb-ai   { align-self: flex-start; background: #313244; }
+    .tina4-fb-form {
+      display: flex; flex-direction: column; gap: 0.4rem;
+      padding: 0.5rem 0.8rem 0.8rem; border-top: 1px solid #313244;
+    }
+    .tina4-fb-form textarea {
+      width: 100%; box-sizing: border-box; resize: vertical;
+      min-height: 60px; font-family: inherit; font-size: 0.82rem;
+      padding: 0.4rem 0.5rem; border: 1px solid #313244;
+      background: #11111b; color: #cdd6f4; border-radius: 4px;
+      line-height: 1.3;
+    }
+    .tina4-fb-form textarea:focus {
+      outline: none; border-color: ${t};
+    }
+    .tina4-fb-send {
+      align-self: flex-end; padding: 0.35rem 0.9rem;
+      background: ${t}; color: white; border: none; border-radius: 4px;
+      font-size: 0.8rem; font-weight: 500; cursor: pointer;
+    }
+    .tina4-fb-send:disabled { opacity: 0.55; cursor: wait; }
+    .tina4-fb-send:hover:not(:disabled) { filter: brightness(1.1); }
+  `,document.head.appendChild(c)}function p(t){return t.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;")}})();

package/packages/core/src/auth.ts

@@ -79,12 +79,19 @@ export function getToken(
 }
 
 /**
- * Validate a JWT token and return the decoded payload, or false if invalid/expired.
+ * Validate a JWT token. Returns the decoded payload on success, `null` if
+ * invalid/expired/malformed.
  *
- * Secret is always read from `process.env.TINA4_SECRET`.
+ * 3.13.0 — return type changed from `boolean` to `Record<string, unknown> | null`.
+ * Matches the convention used by `jsonwebtoken` and the Python / PHP / Ruby
+ * Auth.validToken signatures shipped at the same time. Legacy
+ * `if (validToken(t))` patterns keep working because a non-null object is
+ * truthy and null is falsy.
+ *
+ * Secret is read from `process.env.TINA4_SECRET` when not passed explicitly.
  * Algorithm is read from `process.env.TINA4_JWT_ALGORITHM` (default "HS256").
  */
-export function validToken(token: string, secret?: string, algorithm?: string): boolean {
+export function validToken(token: string, secret?: string, algorithm?: string): Record<string, unknown> | null {
   const resolvedSecret = secret ?? process.env.TINA4_SECRET ?? "";
   if (!resolvedSecret) {
     console.warn("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)");
@@ -92,24 +99,24 @@ export function validToken(token: string, secret?: string, algorithm?: string):
   const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
   try {
     const parts = token.split(".");
-    if (parts.length !== 3) return false;
+    if (parts.length !== 3) return null;
 
     const [h, p, sig] = parts;
     const signingInput = `${h}.${p}`;
 
     if (!verifySignature(signingInput, sig, resolvedSecret, resolvedAlgorithm)) {
-      return false;
+      return null;
     }
 
     const payload = JSON.parse(base64urlDecode(p).toString()) as Record<string, unknown>;
 
     if (typeof payload.exp === "number" && Date.now() / 1000 > payload.exp) {
-      return false;
+      return null;
     }
 
-    return true;
+    return payload;
   } catch {
-    return false;
+    return null;
   }
 }
 

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);
 };
 
 // ---------------------------------------------------------------------------