mslxdff 0.1.87 → 0.1.89

package/src/routes/chat/gateway.js

@@ -1,26 +1,14 @@
-import { performance } from "node:perf_hooks";
-import { injectReasoningContent, normalizeModel } from "../../reasoning.js";
-import { isAutoModel } from "../../auto.js";
-import { clientIp, json, readBody, parseHops, summarizePrompt, errMsg } from "../helpers.js";
-import { hedgeDelayMs, shouldHedge } from "../hedge.js";
+import { clientIp, json, readBody, parseHops } from "../helpers.js";
 import { runHook } from "../../plugins.js";
-import { parseShareKeysHeader, SHARE_KEYS_HEADER } from "../../providers/share-keys.js";
-import { handleHedge } from "./hedge-handler.js";
-import { handleLocalRelay } from "./local-handler.js";
-import { handlePeerRelay } from "./peer-handler.js";
-import { handleBroadbandRelay } from "./broadband-handler.js";
-import { handleViaRoute } from "./via-route-handler.js";
-import { handleExhaustedLocal, handleExhaustedAll } from "./exhausted-handler.js";
-import { normalizeFullId, getModelAlias } from "../../providers/model-id.js";
+import { createChatPipeline } from "../../chat-pipeline/index.js";
 
 /**
- * ChatGateway 深模块：对外 1 handle，内部 Policy→Selector→Executor 三段编排
- * Policy: 别名/allowlist/header 透传
- * Selector: order 推导 + 并发择优 + 排序
- * Executor: 串行 trial → hedge → local → peer → broadband → exhausted
- * 两 adapter：Provider(upstream.chat) + Clock/Latency(auto) 可注入 fake
+ * ChatGateway 薄适配层：仅负责 HTTP I/O（readBody + request:received hook）→ 委托 ChatPipeline.execute
+ * Policy/Order/AutoRace/hedge/peer/broadband 全部在 chat-pipeline 深模块内。
  */
-export function createChatGateway({ upstream, auto, logs, peers, maxHops, groups, bus, token, plugins }) {
+export function createChatGateway(deps = {}) {
+  const pipeline = createChatPipeline(deps);
+
   async function handle({ req, res }) {
     let body;
     try {
@@ -28,276 +16,25 @@ export function createChatGateway({ upstream, auto, logs, peers, maxHops, groups
     } catch {
       return json(res, 400, { error: "Invalid JSON body" });
     }
-    if (plugins?.length) {
-      const rc = await runHook(plugins, "request:received", { ip: clientIp(req), hops: parseHops(req.headers["x-mslxdff-hops"]), headers: { "content-type": req.headers["content-type"] }, body });
-      for (const e of rc.errors) logs?.appendEvent?.({ ts: Date.now(), type: "plugin-hook-error", hook: "request:received", plugin: e.plugin, error: e.error });
+    if (deps.plugins?.length) {
+      const rc = await runHook(deps.plugins, "request:received", {
+        ip: clientIp(req),
+        hops: parseHops(req.headers["x-mslxdff-hops"]),
+        headers: { "content-type": req.headers["content-type"] },
+        body,
+      });
+      for (const e of rc.errors) deps.logs?.appendEvent?.({ ts: Date.now(), type: "plugin-hook-error", hook: "request:received", plugin: e.plugin, error: e.error });
       const respond = rc.value?.respond;
       if (respond && typeof respond === "object") return json(res, respond.status || 200, respond.body ?? {});
     }
-
-    const startedAt = Date.now();
-    const reqId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
-    const perf0 = performance.now();
-    const stages = [];
-    const mark = (name) => stages.push([name, Math.round(performance.now() - perf0)]);
-
-    // ===== Policy =====
-    const hops = parseHops(req.headers["x-mslxdff-hops"]);
-    const shareKeys = parseShareKeysHeader(req.headers[SHARE_KEYS_HEADER] || "");
-    const workbuddyUid = (req.headers["x-mslxdff-workbuddy-uid"] || req.headers["x-workbuddy-uid"] || "").toString().trim();
-    const lockModel = req.headers["x-mslxdff-model-lock"] || "";
-    const rawModel = body.model || "";
-    let normalizedRequested = normalizeModel(lockModel || rawModel || "");
-    const aliasResolved = getModelAlias(normalizedRequested);
-    if (aliasResolved) { normalizedRequested = aliasResolved; body = { ...body, model: aliasResolved }; }
-    let requested = normalizedRequested;
-    let aliasInfo = null;
-    // opencode 侧 provider.mslxdff 模型会以 mslxdff/<id> 形式到达，剥掉前缀即得真实模型
-    if (requested.startsWith("mslxdff/")) {
-      const rawPart = requested.slice("mslxdff/".length);
-      aliasInfo = `${requested} -> ${rawPart} (mslxdff provider stripped)`;
-      requested = rawPart;
-      // mslxdff/bai-deepseek... 这类 dash 形态二次走 alias 表还原为 bai/...
-      const alias2 = getModelAlias(requested);
-      if (alias2) {
-        aliasInfo = `${rawModel} -> ${alias2} (mslxdff + alias)`;
-        requested = alias2;
-        body = { ...body, model: alias2 };
-      }
-    }
-    // 非 mslxdff 前缀的 dash 形态（如 bai-deepseek）已在首轮 aliasResolved 处理
-    const useAuto = isAutoModel(requested);
-    mark("parsed");
-    if (aliasInfo) { try { res.setHeader("x-mslxdff-alias", aliasInfo); } catch {} }
-
-    // ===== Selector: order 推导 =====
-    let order;
-    if (lockModel) order = [requested];
-    else if (useAuto) order = auto ? await auto.candidates() : [""];
-    else order = auto ? await auto.candidatesFor(requested) : [requested];
-    if (!order.length) order = [""];
-    const canFallback = order.length > 1;
-    const canForwardPeers = Boolean(peers) && hops < maxHops;
-    mark("ordered");
-
-    const logCall = (model, status) => logs?.appendCall({ reqId, model, auto: useAuto, status, durationMs: Date.now() - startedAt, stream: Boolean(body.stream), stages });
-    const logError = (model, status, message) => logs?.appendError({ reqId, model, auto: useAuto, status, message, stages });
-    const evt = (type, data) => {
-      const entry = { ts: Date.now(), reqId, type, ...data, model: data.model ?? requested, auto: useAuto, durationMs: Date.now() - startedAt, stages: [...stages] };
-      if (bus) bus.emit(entry);
-      logs?.appendEvent?.(entry);
-    };
-    const done = (info) => {
-      if (!plugins?.length) return;
-      runHook(plugins, "request:completed", { reqId, requested, useAuto, hops, stream: Boolean(body.stream), durationMs: Date.now() - startedAt, ...info }).catch(() => {});
-    };
-    evt("request", { reqId, hops, ip: clientIp(req), stream: Boolean(body.stream), prompt: summarizePrompt(body), rawModel, requested, lockModel: lockModel || null });
-    if (aliasInfo) evt("alias", { reqId, alias: aliasInfo, rawModel, requested });
-    if (Object.keys(shareKeys).length) evt("share-keys", { reqId, providers: Object.keys(shareKeys) });
-    evt("ordered", { reqId, order, canFallback, canForwardPeers, useAuto, statuses: auto?.statuses?.() ?? null });
-
-    if (plugins?.length && !lockModel) {
-      const sel = await runHook(plugins, "model:select", { reqId, requested, useAuto, order: [...order], hops, stream: Boolean(body.stream) });
-      if (sel.changed && Array.isArray(sel.value) && sel.value.length) {
-        order = sel.value.filter(Boolean);
-        if (!order.length) order = [requested];
-        evt("plugin-hook", { reqId, hook: "model:select", applied: true, order: [...order] });
-      }
-      for (const e of sel.errors) evt("plugin-hook-error", { reqId, hook: "model:select", plugin: e.plugin, error: e.error });
-    }
-
-    const handlerCtx = { reqId, model: null, body, hops, peers, plugins, evt, logError, logCall, logs, workbuddyUid };
-
-    // ===== Selector: 首次 auto 并发择优 =====
-    if (useAuto && order.length > 1 && auto && !lockModel) {
-      const statuses = auto.statuses?.() ?? {};
-      const hasPriorSuccess = Object.values(statuses).some((e) => e && typeof e === "object" && e.status === "normal");
-      const nonCoolingOrder = order.filter((m) => { try { return !auto.isCooling(m); } catch { return true; } });
-      if (!hasPriorSuccess && nonCoolingOrder.length > 1) {
-        const concLimit = (() => {
-          const v = Number(process.env.MSLXDFF_AUTO_CONCURRENT);
-          if (Number.isInteger(v) && v > 0) return Math.min(v, nonCoolingOrder.length);
-          return Math.min(nonCoolingOrder.length, 5);
-        })();
-        let raceModels=nonCoolingOrder.slice(0,concLimit);
-        if(plugins?.length){const k=[];for(const m of raceModels){const b=await runHook(plugins,"model:beforeTry",{reqId,requested,model:m,hops});if(b.value===false||b.value?.skip)continue;k.push(m);}raceModels=k;}
-        if(!raceModels.length){order=order.filter(m=>!new Set(nonCoolingOrder.slice(0,concLimit)).has(m));if(!order.length){await handleExhaustedAll({res,body,lastErr:{model:requested,status:502,message:"all concurrent candidates skipped by plugin"},order:nonCoolingOrder.slice(0,concLimit),requested,handlerCtx:{...handlerCtx,reqId,startedAt},evt,logCall,mark,perf0,stages});return;}}else{evt("auto-concurrent-race",{reqId,models:raceModels,skippedFaulty:order.length-nonCoolingOrder.length,limit:concLimit});const raceStart=performance.now();const attempts=raceModels.map(async m=>{let f={...injectReasoningContent(m,body),model:m};if(plugins?.length){const u=await runHook(plugins,"upstream:request",{reqId,requested,model:m,payload:f,stream:Boolean(body.stream)});if(u.changed&&u.value?.payload) f=u.value.payload;}let r=null;try{const o={};if(Object.keys(shareKeys).length)o.shareKeys=shareKeys;if(workbuddyUid)o.workbuddyUid=workbuddyUid;r=await upstream.chat(f,Object.keys(o).length?o:undefined);}catch(e){if(plugins?.length)runHook(plugins,"upstream:response",{reqId,requested,model:m,status:null,ok:false,error:errMsg(e),timing:e?._t??null}).catch(()=>{});return{model:m,ok:false,error:errMsg(e),status:502,timing:e?._t??null};}if(plugins?.length)runHook(plugins,"upstream:response",{reqId,requested,model:m,status:r instanceof Error?null:r?.status??null,ok:!(r instanceof Error)&&r?r.status<400:false,error:r instanceof Error?errMsg(r):null,timing:r?._t??null}).catch(()=>{});if(r&&r.status>=400){const a=r.status===403&&r.headers?.get?.("x-mslxdff-allowlist")==="1";if(a)return{model:m,ok:false,error:"allowlist",status:403,allowlist:true};return{model:m,ok:false,error:`upstream ${r.status}`,status:r.status,res:r,timing:r._t??null};}if(r instanceof Error)return{model:m,ok:false,error:errMsg(r),status:502};return{model:m,ok:true,res:r,status:r.status,timing:r._t??null};});
-        const results = await Promise.allSettled(attempts);
-        const okList = results.map((r, i) => ({ r, i, model: raceModels[i] }))
-          .filter(({ r }) => r.status === "fulfilled" && r.value?.ok)
-          .map(({ r, i, model }) => ({ model, idx: i, val: r.value, t: r.value.timing?.totalMs ?? r.value.timing?.ms ?? Number.MAX_SAFE_INTEGER }));
-        if (okList.length) {
-          okList.sort((a, b) => a.t - b.t);
-          const best = okList[0];
-          const winModel = best.model;
-          evt("auto-concurrent-win", { reqId, model: winModel, timing: best.val.timing, totalMs: Math.round(performance.now() - raceStart), tried: raceModels.length });
-          for (const { r, i } of results.map((r, i) => ({ r, i }))) {
-            const m = raceModels[i];
-            if (r.status === "fulfilled" && r.value?.ok) {
-              if (m === winModel) {
-                const latencyMs = r.value.timing?.totalMs ?? Math.round(performance.now() - raceStart);
-                await auto.recordOk(m, { latencyMs });
-                try { const { savePreferredModel } = await import("../../state.js"); savePreferredModel(m); evt("auto-concurrent-preferred", { reqId, model: m }); } catch {}
-              }
-            } else if (r.status === "fulfilled" && !r.value?.ok && !r.value?.allowlist) await auto.recordError(m, { status: r.value.status || 502 });
-            else if (r.status === "rejected") await auto.recordError(m, { status: 502 });
-          }
-          handlerCtx.model = winModel;
-          const { handleLocalRelay: _relay } = await import("./local-handler.js");
-          const lr = await _relay({
-            upRes: best.val.res, model: winModel, body, order: raceModels, idx: best.idx,
-            lastErr: null, requested, useAuto, lockModel, auto, handlerCtx, evt, logCall, logError, mark, perf0, stages, startedAt, plugins, res,
-          });
-          if (lr.handled) return;
-          if (!lr.lastErr) return;
-        } else {
-          evt("auto-concurrent-all-fail", { reqId, tried: raceModels.length, totalMs: Math.round(performance.now() - raceStart) });
-          for (const { r, i } of results.map((r, i) => ({ r, i }))) {
-            const m = raceModels[i];
-            if (r.status === "fulfilled" && !r.value?.ok && !r.value?.allowlist) await auto.recordError(m, { status: r.value.status || 502 });
-            else if (r.status === "rejected") await auto.recordError(m, { status: 502 });
-          }
-        }
-        const triedSet = new Set(raceModels);
-        order = order.filter((m) => !triedSet.has(m));
-        if (!order.length) {
-          const failedStatuses = results.map((r) => (r.status === "fulfilled" ? r.value?.status : null)).filter((s) => Number.isInteger(s));
-          const lastStatus = failedStatuses[failedStatuses.length - 1] || failedStatuses[0] || 502;
-          const last = { model: raceModels[0] || requested, status: lastStatus, message: "all concurrent candidates failed" };
-          await handleExhaustedAll({ res, body, lastErr: last, order: raceModels, requested, handlerCtx: { ...handlerCtx, reqId, startedAt }, evt, logCall, mark, perf0, stages });
-          return;
-        }
-        } // close else (raceModels not empty)
-      }
-    }
-
-    // ===== VIA-ROUTE 单路径择路（显式锁模型，不并发） =====
-    let viaRouteLastErr = null;
-    if (!useAuto && requested && requested.includes("/") && canForwardPeers && !lockModel && peers) {
-      try {
-        const vr = await handleViaRoute({
-          model: requested,
-          body,
-          peers,
-          handlerCtx,
-          evt,
-          logCall,
-          logError,
-          mark,
-          perf0,
-          stages,
-          startedAt,
-          plugins,
-          res,
-          requested,
-          useAuto,
-          lockModel,
-          auto,
-        });
-        if (vr.handled) return;
-        if (vr.lastErr) viaRouteLastErr = vr.lastErr;
-      } catch (e) {
-        evt("via-route-exception", { reqId, model: requested, error: errMsg(e) });
-      }
-    }
-
-    // ===== Executor: 串行 trial =====
-    let lastErr = viaRouteLastErr;
-    for (let idx = 0; idx < order.length; idx++) {
-      const model = order[idx];
-      handlerCtx.model = model;
-      evt("model-try", { reqId, model, idx, remaining: order.length - idx });
-      if (plugins?.length) {
-        const bt = await runHook(plugins, "model:beforeTry", { reqId, requested, model, idx, hops });
-        for (const e of bt.errors) evt("plugin-hook-error", { reqId, hook: "model:beforeTry", plugin: e.plugin, error: e.error });
-        if (bt.value === false || bt.value?.skip === true) { evt("plugin-hook", { reqId, hook: "model:beforeTry", applied: true, skipped: model }); continue; }
-      }
-      let upRes = null;
-      let forwarded = { ...injectReasoningContent(model, body), model };
-      if (plugins?.length) {
-        const ur = await runHook(plugins, "upstream:request", { reqId, requested, model, payload: forwarded, stream: Boolean(body.stream) });
-        for (const e of ur.errors) evt("plugin-hook-error", { reqId, hook: "upstream:request", plugin: e.plugin, error: e.error });
-        if (ur.changed && ur.value?.payload && typeof ur.value.payload === "object") { forwarded = ur.value.payload; evt("plugin-hook", { reqId, hook: "upstream:request", applied: true, model, rewrittenModel: forwarded.model ?? null }); }
-      }
-      const tUp = performance.now();
-      evt("upstream-try", { reqId, model, attempt: idx + 1 });
-      try {
-        const chatOpts = {};
-        if (Object.keys(shareKeys).length) chatOpts.shareKeys = shareKeys;
-        if (workbuddyUid) chatOpts.workbuddyUid = workbuddyUid;
-        upRes = await upstream.chat(forwarded, Object.keys(chatOpts).length ? chatOpts : undefined);
-        evt("upstream-done", { reqId, model, ok: !(upRes instanceof Error) && upRes.status < 400, status: upRes instanceof Error ? null : upRes.status, timing: upRes._t ?? null, error: null });
-      } catch (err) {
-        if (auto) await auto.recordError(model, { message: errMsg(err) });
-        lastErr = { model, upstream: null, status: 502, message: errMsg(err) };
-        logError(model, 502, errMsg(err));
-        evt("upstream-error", { reqId, model, status: 502, message: errMsg(err), timing: err._t ?? { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - tUp) } });
-      }
-      if (plugins?.length) {
-        runHook(plugins, "upstream:response", {
-          reqId, requested, model,
-          status: upRes instanceof Error ? null : upRes instanceof Object ? (upRes.status ?? null) : null,
-          ok: !(upRes instanceof Error) && upRes ? upRes.status < 400 : false,
-          error: upRes instanceof Error ? errMsg(upRes) : null,
-          timing: upRes?._t ?? null,
-        }).catch(() => {});
-      }
-      mark(`up-${model}`);
-      if (upRes && upRes.status >= 400) {
-        const isAllowlistBlock = upRes.status === 403 && (upRes.headers?.get?.("x-mslxdff-allowlist") === "1");
-        if (isAllowlistBlock) {
-          let bodyText = null; try { bodyText = await upRes.clone().text(); } catch {}
-          let errBody = { error: `model not allowed for provider` };
-          try { errBody = bodyText ? JSON.parse(bodyText) : errBody; } catch { errBody = { error: bodyText || "model not allowed" }; }
-          if (useAuto) {
-            logError(model, 403, errBody.error || "model not allowed");
-            evt("upstream-error", { reqId, model, status: 403, message: errBody.error, timing: upRes._t ?? null, allowlist: true, skipped: true });
-            lastErr = { model, upstream: upRes, status: 403, message: errBody.error || "model not allowed" };
-            if (canFallback && idx < order.length - 1) { evt("fallback", { reqId, from: model, to: order[idx + 1] ?? null, reason: `allowlist skip ${errBody.error || "blocked"}` }); continue; }
-            return json(res, 403, errBody);
-          }
-          logError(model, 403, errBody.error || "model not allowed");
-          evt("upstream-error", { reqId, model, status: 403, message: errBody.error, timing: upRes._t ?? null, allowlist: true });
-          return json(res, 403, errBody);
-        }
-        if (auto) await auto.recordError(model, { status: upRes.status });
-        lastErr = { model, upstream: upRes, status: upRes.status, message: null };
-        logError(model, upRes.status, `upstream ${upRes.status}`);
-        evt("upstream-error", { reqId, model, status: upRes.status, message: null, timing: upRes._t ?? null });
-        upRes = null;
-      }
-      if (upRes) {
-        const isStream = Boolean(body.stream);
-        const d = hedgeDelayMs();
-        const hasPeers = Boolean(peers) && peers.ordered().length > 0;
-        const doHedge = shouldHedge({ isStream, canForwardPeers, hedgeDelayMs: d, hasPeers }) && upRes.status === 200 && upRes.body;
-        if (doHedge) {
-          const hr = await handleHedge({ upRes, model, body, order, idx, lastErr, requested, useAuto, lockModel, auto, peers, handlerCtx, evt, logCall, logError, mark, perf0, stages, startedAt, plugins, res, hedgeDelayMs: d });
-          if (hr.handled) return;
-          if (hr.lastErr) lastErr = hr.lastErr;
-          if (hr.upRes === null) upRes = null;
-          else if (hr.upRes) upRes = hr.upRes;
-        }
-        if (upRes) {
-          const lr = await handleLocalRelay({ upRes, model, body, order, idx, lastErr, requested, useAuto, lockModel, auto, handlerCtx, evt, logCall, logError, mark, perf0, stages, startedAt, plugins, res });
-          if (lr.handled) return;
-          if (lr.lastErr) { lastErr = lr.lastErr; continue; }
-          return;
-        }
-      }
-      if (canForwardPeers) {
-        const pr = await handlePeerRelay({ model, body, lastErr, requested, useAuto, lockModel, auto, peers, handlerCtx, evt, logCall, mark, perf0, stages, startedAt, plugins, res });
-        if (pr.handled) return;
-      }
-      if (groups) {
-        const br = await handleBroadbandRelay({ model, body, hops, lastErr, requested, useAuto, lockModel, auto, groups, token, bus, logs, handlerCtx, evt, mark, perf0, stages, res, startedAt, plugins });
-        if (br.handled) return;
-      }
-      if (canFallback) { evt("fallback", { reqId, from: model, to: order[idx + 1] ?? null, reason: lastErr?.message || `upstream ${lastErr?.status ?? 502}` }); continue; }
-      await handleExhaustedLocal({ res, body, lastErr, order, handlerCtx: { ...handlerCtx, model, reqId }, evt, logCall, mark, perf0, stages, done, requested, useAuto });
-      return;
+    req.body = body;
+    try {
+      await pipeline.execute({ req, res });
+    } catch (err) {
+      const msg = err?.message || String(err);
+      if (!res.headersSent) return json(res, 502, { error: msg });
+      try { res.end(); } catch {}
     }
-    await handleExhaustedAll({ res, body, lastErr, order, requested, handlerCtx: { ...handlerCtx, reqId, startedAt }, evt, logCall, mark, perf0, stages });
   }
 
   return { handle };
@@ -307,4 +44,4 @@ export function createChatGateway({ upstream, auto, logs, peers, maxHops, groups
 export async function chatHandler(ctx) {
   const gw = createChatGateway(ctx);
   return gw.handle(ctx);
-}
+}

package/src/routes/groups-relay.js

@@ -1,6 +1,6 @@
 import { clientIp, json, readBody, parseHops, errMsg } from "./helpers.js";
 import { DEFAULT_MAX_HOPS } from "../peers.js";
-import { enqueueRelay, dequeueRelayForPoll, resolveRelay } from "./relay-queue.js";
+import { enqueueRelay, dequeueRelayForPoll, resolveRelay, subscribeStream, unsubscribeStream } from "./relay-queue.js";
 
 export async function heartbeatHandler({ req, res, groups, bus, logs }) {
   const auth = /^Bearer (.+)$/.exec(req.headers["authorization"] || "");
@@ -63,6 +63,90 @@ export async function resultHandler({ req, res, groups }) {
   return json(res, 200, { object: "result", ok: true });
 }
 
+function isStreamEnabled() {
+  const v = process.env.MSLXDFF_BROADBAND_STREAM;
+  if (v === "0" || v === "false" || v === "off") return false;
+  return true;
+}
+
+export async function streamHandler({ req, res, groups, bus, logs }) {
+  if (!isStreamEnabled()) return json(res, 404, { error: "broadband stream disabled" });
+  const auth = /^Bearer (.+)$/.exec(req.headers["authorization"] || "");
+  if (!auth) return json(res, 401, { error: "bearer token required" });
+  // support GET query ?name= & ?group=
+  let groupName = null;
+  try {
+    const u = new URL(req.url || "", "http://127.0.0.1");
+    groupName = u.searchParams.get("name") || u.searchParams.get("group");
+  } catch {}
+  if (!groupName) {
+    // also try body for POST-compat (though GET should use query)
+    try {
+      const b = await readBody(req);
+      groupName = b?.name || b?.group;
+    } catch {}
+  }
+  if (!groupName) return json(res, 400, { error: "group name is required" });
+  const hit = groups?.membersForToken(groupName, auth[1]);
+  if (!hit) return json(res, 403, { error: "invalid member token" });
+  const targetUrl = hit.member?.url;
+  if (!targetUrl) return json(res, 400, { error: "member url not found" });
+  const isBb = hit.member?.kind === "broadband" || String(targetUrl).startsWith("relay://");
+  if (!isBb) return json(res, 403, { error: "only broadband members can stream" });
+  // SSE headers
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+  res.setHeader("X-Accel-Buffering", "no");
+  if (typeof res.flushHeaders === "function") res.flushHeaders();
+  // initial frame
+  try { res.write(`:connected ${Date.now()}\n\n`); } catch {}
+  const pingMs = Number(process.env.MSLXDFF_BROADBAND_PING_MS) > 0 ? Number(process.env.MSLXDFF_BROADBAND_PING_MS) : 25_000;
+  subscribeStream({ group: groupName, target: targetUrl, res });
+  const evtOpen = { ts: Date.now(), type: "relay-stream-open", member: targetUrl, group: groupName };
+  try { bus?.emit(evtOpen); } catch {}
+  try { logs?.appendEvent?.(evtOpen); } catch {}
+  // heartbeat touch
+  try {
+    const ip = clientIp(req);
+    const members = groups.list()[groupName]?.members || {};
+    const targetId = Object.keys(members).find((k) => members[k].url === targetUrl) || targetUrl;
+    const m = members[targetId] || hit.member;
+    if (m) {
+      m.publicIp = ip;
+      m.lastSeen = Date.now();
+      try { groups.upsertMember(groupName, { memberName: targetId, url: m.url, token: m.token, kind: "broadband", publicIp: ip, lastSeen: m.lastSeen }); } catch {}
+    }
+  } catch {}
+  const pingTimer = setInterval(() => {
+    try { res.write(`:ping ${Date.now()}\n\n`); } catch {}
+    // keep lastSeen fresh so forward doesn't see stale while stream is alive
+    try {
+      const members = groups.list()[groupName]?.members || {};
+      const targetId = Object.keys(members).find((k) => members[k].url === targetUrl) || targetUrl;
+      const m = members[targetId] || hit.member;
+      if (m) {
+        m.lastSeen = Date.now();
+        try { groups.upsertMember(groupName, { memberName: targetId, url: m.url, token: m.token, kind: "broadband", lastSeen: m.lastSeen }); } catch {}
+      }
+    } catch {}
+    const evt = { ts: Date.now(), type: "relay-stream-ping", member: targetUrl, group: groupName };
+    try { bus?.emit(evt); } catch {}
+  }, pingMs);
+  pingTimer.unref?.();
+  const cleanup = () => {
+    clearInterval(pingTimer);
+    unsubscribeStream({ group: groupName, target: targetUrl, res });
+    const evt = { ts: Date.now(), type: "relay-stream-close", member: targetUrl, group: groupName };
+    try { bus?.emit(evt); } catch {}
+    try { logs?.appendEvent?.(evt); } catch {}
+  };
+  req.on("close", cleanup);
+  req.on("error", cleanup);
+  // keep promise pending until close — do not end res here
+  await new Promise(() => {});
+}
+
 export async function forwardHandler({ req, res, groups, bus, logs }) {
   let body;
   try { body = await readBody(req); } catch { return json(res, 400, { error: "Invalid JSON body" }); }

package/src/routes/index.js

@@ -3,7 +3,7 @@ import { DEFAULT_MAX_HOPS } from "../peers.js";
 import { json, notFound, authorized } from "./helpers.js";
 import { chatHandler } from "./chat.js";
 import { joinHandler, leaveHandler } from "./groups.js";
-import { heartbeatHandler, pollHandler, resultHandler, forwardHandler } from "./groups-relay.js";
+import { heartbeatHandler, pollHandler, resultHandler, forwardHandler, streamHandler } from "./groups-relay.js";
 import { modelsHandler, modelsStatusHandler, providerModelsHandler } from "./models-route.js";
 import { relayHandler } from "./relay.js";
 
@@ -73,6 +73,12 @@ const ROUTES = [
     requiresAuth: false,
     handler: resultHandler,
   },
+  {
+    method: "GET",
+    path: "/v1/groups/relay/stream",
+    requiresAuth: false,
+    handler: streamHandler,
+  },
   {
     method: "POST",
     path: "/v1/groups/relay/forward",

package/src/routes/relay-queue.js

@@ -2,9 +2,62 @@ import { loadGroupsJoined } from "../state.js";
 
 const relayPending = new Map();
 const relayPendingByReqId = new Map();
+const streamSubscribers = new Map(); // key group::target -> Set<res>
+
+function streamKey(group, target) { return `${group}::${target}`; }
+
+export function subscribeStream({ group, target, res }) {
+  const k = streamKey(group, target);
+  const set = streamSubscribers.get(k) || new Set();
+  set.add(res);
+  streamSubscribers.set(k, set);
+}
+
+export function unsubscribeStream({ group, target, res }) {
+  const k = streamKey(group, target);
+  const set = streamSubscribers.get(k);
+  if (!set) return;
+  set.delete(res);
+  if (set.size === 0) streamSubscribers.delete(k);
+}
+
+export function clearStreamSubscribers() { streamSubscribers.clear(); }
+export function getStreamSubscribers() { return streamSubscribers; }
+
+export function pushToStream({ group, target, entry }) {
+  const k = streamKey(group, target);
+  const set = streamSubscribers.get(k);
+  if (!set || set.size === 0) return false;
+  const payload = JSON.stringify({ reqId: entry.reqId, body: entry.body, hops: entry.hops });
+  const frame = `event: relay\ndata: ${payload}\n\n`;
+  let pushed = 0;
+  for (const res of [...set]) {
+    try {
+      res.write(frame);
+      pushed++;
+    } catch {
+      set.delete(res);
+    }
+  }
+  if (set.size === 0) streamSubscribers.delete(k);
+  return pushed > 0;
+}
 
 export function enqueueRelay({ group, target, reqId, body, hops }) {
   const key = `${group}::${target}`;
+  // try stream push first — if any subscriber, push and don't enqueue to poll queue
+  const entryForPush = { reqId, body, hops };
+  if (pushToStream({ group, target, entry: entryForPush })) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        relayPendingByReqId.delete(reqId);
+        reject(new Error("relay timeout"));
+      }, 30_000);
+      timer.unref?.();
+      const entry = { reqId, body, hops, resolve, reject, timer };
+      relayPendingByReqId.set(reqId, entry);
+    });
+  }
   const list = relayPending.get(key) || [];
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {