pi-freeflow 1.38.3 → 1.38.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.38.5
+
+### Patch Changes
+
+- Salvage relay rate-limit responses when direct fallback encounters network-level or abusive-IP 403 errors, preventing transient rate limits from locking up upstream models. Add the `/freeflow sticky` command to pin requests to one healthy relay until a rate limit or edge error occurs, preserving fresh pool relays. Recognize network-restricted and abusive-traffic 403 variants as free-tier gates so fresh sessions automatically fail over to healthy fallback models without interruption.
+
+## 1.38.4
+
+### Patch Changes
+
+- A relay that the upstream free-tier gate rejects can no longer wedge the pool: when a relay forwards back a 403 the relay itself is marked failed and the request rolls to the next candidate (or the direct route), instead of that 403 being recorded as a healthy verdict and pinning the relay as the pool's primary. The machine-wide upstream gate now only trips when the direct route is refused too, so one incompatible relay cannot fail everyone over.
+
+  Deploying a relay now proves inference through it, not just that its models list answers: the completion message verifies a real free-tier request and, when that fails, says so plainly — including the known Deno Deploy case (its platform rewrites the outbound User-Agent, so OpenCode Zen rejects traffic from it while Kilo still works). Deno Deploy deployments also resolve their public URL from the current API response again, so the deploy flow ends with a usable relay address instead of a "could not determine the public URL" error.
+
 ## 1.38.3
 
 ### Patch Changes

package/README.md

@@ -17,7 +17,7 @@ Thin by design: a model list, a relay proxy, and a log. The host (`pi-ai`) handl
 | Feature | What it does | Cost |
 | :--- | :--- | :--- |
 | **36 free models** | 13 from OpenCode Zen, 13 from KiloCode Gateway, 2 from Cline, 8 from OVHcloud AI Endpoints, context windows up to 1M. Full list below. | **$0** |
-| **Relay pool** | Route requests through your own Cloudflare Workers, Deno Deploy, and Vercel Edge relays. Traffic spreads across the pool, or stays on one sticky relay. A relay that rate-limits, times out, or drops the connection cools down while healthy ones take its traffic. | **$0** beyond your platforms' free tiers |
+| **Relay pool** | Route requests through your own relays: a self-hosted egress pool (many egress IPs on one small host) or Cloudflare Workers / Deno Deploy / Vercel Edge workers. Traffic spreads across the pool, or stays on one sticky relay. A relay that rate-limits, times out, or drops the connection cools down while healthy ones take its traffic. | **$0** beyond your host or platforms' free tiers |
 | **Automatic fallback** | When every relay is cooling down, requests go direct to upstream instead of failing. | **$0** |
 | **Short model names** | Most models have a slash-free, colon-free alias, plus an optional `:effort` suffix for thinking depth. You type `freeflow/<name>`; the two Cline models have no alias and must be typed in full. | **$0** |
 | **Shared local proxy** | One daemon on `127.0.0.1:28180` serves every session on the machine, so parallel subagents reuse it instead of opening their own connections. | **$0** |
@@ -75,27 +75,50 @@ supported). The host resolves the rest.
 ### Add relays
 
 The default setup talks to upstream directly. Add relays when shared IPs start
-hitting rate limits. The fastest path is guided deploy: run
-`/freeflow deploy cloudflare` (or `deno`, `vercel`), paste your platform token
-once when asked, and the relay is created and added to your pool. The token
-stays in memory and is never written to disk.
+hitting rate limits — the OpenCode Zen free tier counts them per egress IP, so
+how many dedicated egress addresses you control decides how much you can run at
+once.
 
-Manual fallback per platform:
+**Option A: Self-hosted WARP relay pool (recommended for OpenCode Zen)**
+
+One Linux VPS runs a pool of isolated Cloudflare WARP egress addresses with
+automatic rotation of rate-limited IPs — [trefeon/warp-relay-pool](https://github.com/trefeon/warp-relay-pool):
 
-**Option A: Cloudflare Workers, auto deploy (recommended)**
+```bash
+git clone https://github.com/trefeon/warp-relay-pool.git
+cd warp-relay-pool && ./setup.sh
+```
+
+- **Many egress IPs, tiny footprint**: each relay node is ~1.8 MiB of RAM; the
+  default five-relay pool fits a 512 MB VPS (~50 MB of stack over a private
+  mesh-VPN URL, ~160 MB with public tunnel URLs).
+- **Auto-rotation**: a background service probes each egress for HTTP 429 and
+  rotates only the throttled node — the rest of the pool keeps serving and your
+  client URLs stay put.
+- **No platform quotas, no request rewriting**: your host's bandwidth, and
+  requests arrive upstream with the client's own fingerprint.
+- **Same contract as edge relays**: implements `x-relay-target`, so it can sit
+  in a pool alongside worker deployments.
+- The setup wizard prints ready-to-paste `/freeflow add <url> <label>` commands;
+  pair the pool with `/freeflow spread` so parallel sessions and subagents land
+  on different egress IPs.
+
+**Option B: Cloudflare Workers, auto deploy (zero-infra)**
 ```bash
 /freeflow deploy cloudflare  # prompts token in-memory, auto-adds to pool
 # or /freeflow deploy with no argument to pick the platform interactively
 ```
 Manual fallback: `dash.cloudflare.com` → Workers → Create → Deploy → Edit code → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your.workers.dev cf-worker-1`
 
-**Option B: Deno Deploy, auto deploy**
+**Option C: Deno Deploy, auto deploy (Kilo models only)**
 ```bash
 /freeflow deploy deno  # prompts token in-memory, auto-adds to pool
 ```
 Manual fallback: `dash.deno.com` → New Project → Playground → paste the canonical worker source (see below) → Deploy → `/freeflow add https://your-project.deno.dev deno-relay-1`
 
-**Option C: Vercel Edge Relay (last resort, paid plan only)**
+Deno Deploy rewrites the outbound `User-Agent` at the platform layer, so OpenCode Zen free-tier traffic through a Deno relay is refused with `403 FreeTierError`; Kilo models still work. The deploy flow warns up front and its post-deploy inference probe reports what the relay can actually serve.
+
+**Option D: Vercel Edge Relay (last resort, paid plan only)**
 ```bash
 /freeflow deploy vercel  # prompts token in-memory, auto-adds to pool
 ```
@@ -108,18 +131,6 @@ For `api/relay.js`, use the canonical worker source (see below); `vercel.json` s
 { "rewrites": [{ "source": "/(.*)", "destination": "/api/relay" }] }
 ```
 
-**Option D: Self-Hosted WARP Relay on VPS (1GB VPS friendly)**
-
-If you have a Linux VPS (even a low-spec 1GB RAM instance), you can self-host a dedicated egress relay pool using [trefeon/warp-relay-pool](https://github.com/trefeon/warp-relay-pool):
-- **1GB VPS friendly**: Lightweight footprint designed to run comfortably on low-resource VPS nodes.
-- **Rotating Cloudflare WARP egress**: Automatically rotates outbound IPs so upstream rate limits don't block your sessions.
-- **Full protocol compatibility**: Implements the `x-relay-target` contract used by pi-freeflow.
-
-Once deployed on your VPS, register it in your relay pool:
-```bash
-/freeflow add https://your-vps:port vps-warp-relay
-```
-
 **Canonical worker source (all platforms)**
 
 The relay worker template is generated per deployment by `/freeflow deploy`, with one shared core adapted for Vercel, Cloudflare, and Deno. Every deploy embeds a random 32-byte secret, and the generated worker answers `401` to any request without a matching `x-relay-auth` header; the client sends that secret to each relay in the pool. Only a hand-pasted legacy worker built without a secret is open to anyone. Either way, a relay forwards only to an allowlist (`https://opencode.ai`, `https://api.kilo.ai`) with private-host and path checks.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-freeflow",
   "type": "module",
-  "version": "1.38.3",
+  "version": "1.38.5",
   "description": "Thin provider for OMP/Pi — model list + dumb relay proxy + log; host pi-ai owns thinking/normalization",
   "main": "extensions/index.ts",
   "types": "src/index.ts",

package/src/commands.ts

@@ -540,10 +540,11 @@ export function createCommandSpec(
 ): Omit<RegisteredCommand, "name"> {
  return {
   description:
-   "Relay egress: auto | spread | on | off | hide | show | widget hide/show | status | kill|stop|shutdown | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | url [value] | test [target|opencode] [--chat] | export [path] [--include-secrets] | import <path> [--merge|--replace] [--dry-run] | logs [level] [n] | trace [reqId] | debug on|off|level <level> | refresh | models|reload | update [auto on|off] | autoupdate [on|off] | deploy cloudflare | deploy deno | deploy vercel | install-startup | uninstall-startup | cline login [--key] [slot] | cline accounts | cline logout [slot] | cline signout|switch",
+   "Relay egress: auto | sticky | spread | on | off | hide | show | widget hide/show | status | kill|stop|shutdown | add <URL> [name] | list | use <URL|name|index> [name] | label <target> <name> | remove <target> | url [value] | test [target|opencode] [--chat] | export [path] [--include-secrets] | import <path> [--merge|--replace] [--dry-run] | logs [level] [n] | trace [reqId] | debug on|off|level <level> | refresh | models|reload | update [auto on|off] | autoupdate [on|off] | deploy cloudflare | deploy deno | deploy vercel | install-startup | uninstall-startup | cline login [--key] [slot] | cline accounts | cline logout [slot] | cline signout|switch",
   getArgumentCompletions: (prefix: string) =>
    [
     "auto",
+    "sticky",
     "spread",
     "on",
     "off",
@@ -728,6 +729,15 @@ export function createCommandSpec(
        ? "Deno Deploy relay — token: dash.deno.com → Access Tokens"
        : "Vercel relay — token: vercel.com/account/tokens";
     ctx.ui.notify(tokenHint, "info");
+    if (platform === "deno") {
+     // Verified 2026-10-17: Deno Deploy rewrites the outbound User-Agent at the
+     // platform layer, so OpenCode Zen's free tier rejects every request that
+     // rides this relay. Warn before spending a token on a Zen-only deployment.
+     ctx.ui.notify(
+      "⚠ Deno Deploy rewrites outbound User-Agent: OpenCode Zen free-tier requests through this relay are rejected (403 FreeTierError). It can still serve Kilo models — prefer Cloudflare for Zen.",
+      "warning",
+     );
+    }
     const token = (
      await ctx.ui.input(`${label} API token:`, "")
     )?.trim();
@@ -812,9 +822,31 @@ export function createCommandSpec(
         );
        },
       });
-      probeNote = probe.ok
-       ? ` ✓ reachable (HTTP ${probe.status}, ${probe.latencyMs}ms)`
-       : ` ⚠ deployed but unreachable (${probe.error || `HTTP ${probe.status}`}) — run /freeflow test ${finalUrl} to retry, or /freeflow remove ${finalUrl} to drop it`;
+      if (!probe.ok) {
+       probeNote = ` ⚠ deployed but unreachable (${probe.error || `HTTP ${probe.status}`}) — run /freeflow test ${finalUrl} to retry, or /freeflow remove ${finalUrl} to drop it`;
+      } else {
+       // Reachability is not enough: a relay can answer /v1/models while its
+       // egress is transformed in flight (Deno Deploy rewrites the outbound
+       // User-Agent), and OpenCode Zen then rejects the real traffic. The chat
+       // probe carries the full free-tier fingerprint + tools + stream, so it
+       // fails exactly when Zen inference through this relay would.
+       const chat = await probeRelay(finalUrl, auth, {
+        endpoint: "chat",
+        retries: 1,
+        retryDelayMs: retryDelay,
+       });
+       if (chat.ok) {
+        probeNote = ` ✓ reachable + free-tier inference verified (HTTP ${chat.status}, ${chat.latencyMs}ms)`;
+       } else {
+        // The Deno User-Agent rewrite only explains the free-tier gate; a
+        // timeout or a 5xx must report what was actually observed instead.
+        const denoGate = platform === "deno" && chat.status === 403;
+        const reason = denoGate
+         ? "— Deno Deploy rewrites the outbound User-Agent, which OpenCode Zen rejects; Kilo models still work through this relay"
+         : `(${chat.error || `HTTP ${chat.status}`}) — this relay cannot serve OpenCode Zen traffic (its egress is transformed in flight)`;
+        probeNote = ` ⚠ reachable, but the free-tier inference probe failed ${reason}. Run /freeflow test ${finalUrl} --chat to re-check, or /freeflow remove ${finalUrl} to drop it`;
+       }
+      }
      } catch {
       // probeRelay never throws, but keep the notify safe regardless
      }
@@ -1103,7 +1135,7 @@ export function createCommandSpec(
     }
    };
 
-   if (sub === "auto") {
+   if (sub === "auto" || sub === "sticky") {
     applyRelayState((s) => {
      s.mode = "auto";
      s.enabled = true;
@@ -1180,10 +1212,10 @@ export function createCommandSpec(
      relayState.mode === "off"
       ? "Mode: off (always direct)"
       : relayState.mode === "on"
-       ? "Mode: on (always relay)"
+       ? "Mode: on (always relay, sticky primary)"
        : relayState.mode === "spread"
         ? "Mode: spread (rotates across healthy relays, auto-rolls on 429/5xx)"
-        : "Mode: auto (enabled on session, auto-rolls on 429/5xx)";
+        : "Mode: auto (sticky primary, auto-rolls on 429/5xx)";
     const poolLine = `${relayState.relays.length} relay(s)${relayState.relays.length > 0
      ? ` | active: ${shortRelayLabel(relayState.url, relayState.relays)}`
      : ""
@@ -1926,8 +1958,8 @@ export function createCommandSpec(
      "Deploy Cloudflare relay…",
      "Deploy Deno relay…",
      "Deploy Vercel relay (last resort)…",
-     "Mode: AUTO (auto-detect on model select)",
-     "Mode: ON (always relay)",
+     "Mode: AUTO (sticky primary, auto-detect on model select)",
+     "Mode: ON (always relay, sticky primary)",
      "Mode: OFF (always direct)",
      "Mode: SPREAD (rotate across healthy relays)",
     ]);
@@ -1955,7 +1987,7 @@ export function createCommandSpec(
      await doDeploy("cloudflare");
     } else if (choice === "Deploy Deno relay…") {
      await doDeploy("deno");
-    } else if (choice === "Mode: AUTO (auto-detect on model select)") {
+    } else if (choice === "Mode: AUTO (sticky primary, auto-detect on model select)") {
      applyRelayState((s) => {
       s.mode = "auto";
       s.enabled = true;
@@ -1967,7 +1999,7 @@ export function createCommandSpec(
      });
      persist();
      flash();
-    } else if (choice === "Mode: ON (always relay)") {
+    } else if (choice === "Mode: ON (always relay, sticky primary)") {
      applyRelayState((s) => {
       s.mode = "on";
       s.enabled = true;

package/src/deploy.ts

@@ -488,18 +488,45 @@ export async function deployCloudflareWorker(
  return { url, auth: relayAuth };
 }
 
+type DenoTimeline = {
+ /** Live v2 shape: display name, e.g. "Production". */
+ name?: string;
+ /** Live v2 shape: routing context ("Production" / "Preview"). */
+ context?: string;
+ /** Live v2 shape: hostnames routed to this timeline. */
+ hostnames?: string[];
+ /** Legacy shape retained for older API responses. */
+ slug?: string;
+ domains?: Array<{ domain?: string }>;
+};
+
 type DenoRevision = {
  status?: string;
  failure_reason?: string | null;
- timelines?: Array<{ slug?: string; domains?: Array<{ domain?: string }> }>;
+ timelines?: DenoTimeline[];
 };
 
+/** The v2 API labels the production timeline via `name`/`context` (legacy: `slug`). */
+function isProductionTimeline(t: DenoTimeline): boolean {
+ return [t.name, t.context, t.slug].some(
+  (v) => typeof v === "string" && v.trim().toLowerCase() === "production",
+ );
+}
+
+/**
+ * Resolve the hostname routed to the production timeline of a revision.
+ * The live v2 API answers `timelines[].hostnames` (e.g. `app-org.deno.net`);
+ * older responses carried `slug` + `domains: [{ domain }]`. Both are read,
+ * preferring whichever timeline is marked production, else the first one.
+ */
 function resolveRoutedDomain(revision: DenoRevision): string | null {
  const timelines = revision.timelines ?? [];
- const production = timelines.find((t) => t.slug === "production") ?? timelines[0];
- const host = (production?.domains ?? [])
-  .map((d) => d.domain ?? "")
-  .find((h) => h.length > 0);
+ const production = timelines.find(isProductionTimeline) ?? timelines[0];
+ if (!production) return null;
+ const host = [
+  ...(production.hostnames ?? []),
+  ...(production.domains ?? []).map((d) => d.domain ?? ""),
+ ].find((h) => typeof h === "string" && h.length > 0);
  return host ?? null;
 }
 

package/src/proxy.ts

@@ -1612,12 +1612,18 @@ export function startProxy(
         ) {
          rememberIssuerRelay(conversationKey, servedIssuer);
         }
-        // Upstream degradation tracking: successes prove Zen reachable,
-        // 403 free-tier gates feed the health state machine (a 403 never
-        // rolls — it is a terminal upstream verdict, not a relay fault).
+        // Upstream degradation tracking: successes prove Zen reachable; a 403
+        // free-tier gate feeds the health state machine only when the DIRECT
+        // path produced it (servedIssuer === null). A relay-served 403 is
+        // relay-shaped — relay.ts rolls it and marks the relay — so a salvaged
+        // relay 403 must never flip the machine-wide gate.
         if (response.ok) {
          recordUpstreamSuccess("zen", { sessionKey, canary: isCanary });
-        } else if (response.status === 403 && (response.headers.get("content-type") ?? "").includes("application/json")) {
+        } else if (
+         servedIssuer === null &&
+         response.status === 403 &&
+         (response.headers.get("content-type") ?? "").includes("application/json")
+        ) {
          try {
           const gateText = await response.clone().text();
           recordUpstreamFailure("zen", 403, gateText);

package/src/relay.ts

@@ -489,25 +489,38 @@ export async function relayFetch(
 				continue;
 			}
 
-			// Relay auth rejection: a deployed worker whose RELAY_AUTH no longer
-			// matches this entry's x-relay-auth answers 401 {"error":"unauthorized"}
-			// before forwarding, so the relay never reached upstream (deploy.ts).
-			// That is a relay-host fault, not an upstream verdict: mark it and roll
-			// like every other relay failure. Left to fall through, the broken relay
-			// reached markRelaySuccess below — recorded healthy/sticky, EWMA reset,
-			// no roll, so it kept serving the pool until something else noticed.
-			// Strictly 401: a 403 free-tier gate stays a terminal upstream verdict
-			// (rolling one buys nothing and burns pool quota), and 404-style client
-			// errors keep their non-penalizing terminal path below.
-			if (res.status === 401) {
-				markRelayFailure(targetUrl, 401, "Relay auth rejected (x-relay-auth mismatch)");
+			// Relay-host rejection: 401 = a deployed worker whose RELAY_AUTH no
+			// longer matches this entry's x-relay-auth answers
+			// 401 {"error":"unauthorized"} before forwarding (deploy.ts). 403 =
+			// the relay's egress transformed the request fingerprint (e.g. a
+			// stripped User-Agent), so the worker's target guard or the upstream
+			// free-tier check rejected it — the relay never produced a genuine
+			// upstream verdict either. Both are relay-host faults: mark and roll
+			// like every other relay failure. Left to fall through, the broken
+			// relay reached markRelaySuccess below — recorded healthy/sticky,
+			// EWMA reset, no roll, so it kept serving the pool until something
+			// else noticed. A 403 is no longer treated as a terminal upstream
+			// verdict: rolls are bounded by pool size, and the gate state machine
+			// only primes on a 403 the direct path produced (proxy.ts). Non-401/403
+			// client errors keep their non-penalizing terminal path below.
+			if (res.status === 401 || res.status === 403) {
+				const authRejected = res.status === 401;
+				markRelayFailure(
+					targetUrl,
+					res.status,
+					authRejected
+						? "Relay auth rejected (x-relay-auth mismatch)"
+						: "Relay returned HTTP 403 (stripped or blocked egress fingerprint)",
+				);
 				lastResponse?.body?.cancel().catch(() => {});
 				lastResponse = res;
 				lastResponseRelay = targetUrl;
 				log(
 					"warn",
-					`relay ${targetUrl} rejected the relay auth in ${elapsed}s — rolling to next relay`,
-					{ upstream: url, status: 401 },
+					authRejected
+						? `relay ${targetUrl} rejected the relay auth in ${elapsed}s — rolling to next relay`
+						: `relay ${targetUrl} returned HTTP 403 (blocked egress fingerprint) in ${elapsed}s — rolling to next relay`,
+					{ upstream: url, status: res.status },
 					rid,
 				);
 				const now = Date.now();
@@ -515,7 +528,12 @@ export async function relayFetch(
 					lastRollNotify = now;
 					const ui = getStatusUi();
 					if (ui?.notify) {
-						ui.notify(`relay ${shortRelayLabel(targetUrl)} rejected the relay auth (HTTP 401) — rolled to next relay`, "warning");
+						ui.notify(
+							authRejected
+								? `relay ${shortRelayLabel(targetUrl)} rejected the relay auth (HTTP 401) — rolled to next relay`
+								: `relay ${shortRelayLabel(targetUrl)} failed (HTTP 403) — rolled to next relay`,
+							"warning",
+						);
 					}
 				}
 				continue;
@@ -603,6 +621,25 @@ export async function relayFetch(
 		directHeaders.set("x-request-id", rid);
 
 		const directRes = await fetch(url, { ...opts, headers: directHeaders } as unknown as RequestInit);
+		if (
+			directRes.status === 403 &&
+			lastResponse &&
+			(lastResponse.status === 429 || lastResponse.status === 502 || lastResponse.status === 503)
+		) {
+			log(
+				"warn",
+				`direct fallback returned HTTP 403 FreeTierError (direct IP untrusted) — salvaging last relay HTTP ${lastResponse.status}`,
+				{
+					upstream: url,
+					directStatus: 403,
+					relayStatus: lastResponse.status,
+				},
+				rid,
+			);
+			directRes.body?.cancel().catch(() => {});
+			affinity.onServed?.(lastResponseRelay);
+			return lastResponse;
+		}
 		// lastResponse holds an unread body that would otherwise leak its socket
 		// until GC; the salvage path below still needs it, so only cancel here.
 		lastResponse?.body?.cancel().catch(() => {});

package/src/upstream-health.ts

@@ -31,10 +31,11 @@ export const FALLBACK_KILO_MODEL = "nvidia/nemotron-3.5-lightning:free";
 
 export type ZenRoute = "passthrough" | "failover" | "canary";
 
-/** Free-tier gate marker: the free tier only works from inside OpenCode. */
+/** Free-tier gate marker: the free tier only works from inside OpenCode or is blocked by network/VPN abuse detection. */
 const GATE_CODE_MARKER = "FreeTierError";
 const GATE_MESSAGE_MARKER = "only be used from within OpenCode";
-
+const GATE_ABUSIVE_MARKER = "abusive traffic";
+const GATE_NETWORK_MARKER = "aren't available from your current network";
 /** User-visible hint attached to fast-failed 403 gate bodies. */
 const FREE_TIER_HINT =
  "OpenCode's free tier is only available inside OpenCode right now, " +
@@ -266,12 +267,14 @@ export function notifyGateTransition(upstream: UpstreamName, gated?: boolean): v
 
 /** True when a status/body pair is the free-tier gate (fresh sessions refused). */
 export function isFreeTierGate(status: number, bodyText: unknown): boolean {
- if (status !== 403 || typeof bodyText !== "string") return false;
- return (
-  bodyText.includes(GATE_CODE_MARKER) && bodyText.includes(GATE_MESSAGE_MARKER)
- );
+	if (status !== 403 || typeof bodyText !== "string") return false;
+	if (!bodyText.includes(GATE_CODE_MARKER)) return false;
+	return (
+		bodyText.includes(GATE_MESSAGE_MARKER) ||
+		bodyText.includes(GATE_ABUSIVE_MARKER) ||
+		bodyText.includes(GATE_NETWORK_MARKER)
+	);
 }
-
 /** Stable conversation key carried by request bodies, if the caller sent one. */
 export function sessionKeyOf(parsedBody: unknown): string | null {
  if (typeof parsedBody !== "object" || parsedBody === null) return null;