@aiworker/web 1.22.2 → 1.23.1

package/server/lib/quota/providers/openrouter.js

@@ -5,12 +5,30 @@ import {
   buildResult,
   toUsageWindow,
   toNumber,
+  asObject,
   formatMoney
 } from '../utils/index.js';
 
 export const providerId = 'openrouter';
 export const providerName = 'OpenRouter';
-const aliases = ['openrouter'];
+export const aliases = ['openrouter'];
+const OPENROUTER_QUOTA_URL = 'https://openrouter.ai/api/v1/key';
+const PERIOD_SECONDS = { daily: 86400, weekly: 604800, monthly: 30 * 86400 };
+
+export const resolveResetAt = (limitReset, nowMs) => {
+  const now = new Date(nowMs);
+  const y = now.getUTCFullYear();
+  const m = now.getUTCMonth();
+  const d = now.getUTCDate();
+
+  if (limitReset === 'daily') return Date.UTC(y, m, d + 1);
+  if (limitReset === 'weekly') {
+    const dow = now.getUTCDay();
+    return Date.UTC(y, m, d + ((8 - dow) % 7 || 7));
+  }
+  if (limitReset === 'monthly') return Date.UTC(y, m + 1, 1);
+  return null;
+};
 
 export const isConfigured = () => {
   const auth = readAuthFile();
@@ -33,13 +51,16 @@ export const fetchQuota = async () => {
     });
   }
 
+  const timeoutSignal = AbortSignal.timeout(15_000);
+
   try {
-    const response = await fetch('https://openrouter.ai/api/v1/credits', {
+    const response = await fetch(OPENROUTER_QUOTA_URL, {
       method: 'GET',
       headers: {
         Authorization: `Bearer ${apiKey}`,
-        'Content-Type': 'application/json'
-      }
+        'Accept-Encoding': 'identity'
+      },
+      signal: timeoutSignal
     });
 
     if (!response.ok) {
@@ -48,45 +69,119 @@ export const fetchQuota = async () => {
         providerName,
         ok: false,
         configured: true,
-        error: `API error: ${response.status}`
+        error: response.status === 401 || response.status === 403
+          ? 'Session expired — please re-authenticate with OpenRouter'
+          : `API error: ${response.status}`
       });
     }
 
     const payload = await response.json();
-    const credits = payload?.data ?? {};
-    const totalCredits = toNumber(credits.total_credits);
-    const totalUsage = toNumber(credits.total_usage);
-    const remaining = totalCredits !== null && totalUsage !== null
-      ? Math.max(0, totalCredits - totalUsage)
-      : null;
-    let valueLabel = null;
-    if (remaining !== null && totalUsage !== null) {
-      valueLabel = `$${formatMoney(remaining)} left · $${formatMoney(totalUsage)} spent`;
+    const data = asObject(payload?.data);
+
+    if (data === null) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'No quota data in response'
+      });
+    }
+
+    if (data.is_management_key === true) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'Management key configured — quota needs an inference API key'
+      });
     }
 
-    const windows = {
-      credits: toUsageWindow({
-        usedPercent: null,
-        windowSeconds: null,
-        resetAt: null,
-        valueLabel
-      })
-    };
+    const limit = toNumber(data.limit);
+    const limitRemaining = toNumber(data.limit_remaining);
+    if (limit !== null && limitRemaining === null) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'No quota data in response'
+      });
+    }
+
+    const usageMonthly = toNumber(data.usage_monthly);
+    if (limit === null && usageMonthly === null) {
+      return buildResult({
+        providerId,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'No quota data in response'
+      });
+    }
+
+    const nowMs = Date.now();
+    let windowKey;
+    let windowSeconds;
+    let resetAt;
+    let usedPercent;
+    let valueLabel;
+
+    if (limit === null) {
+      windowKey = 'monthly';
+      windowSeconds = PERIOD_SECONDS.monthly;
+      resetAt = resolveResetAt('monthly', nowMs);
+      usedPercent = null;
+      valueLabel = `$${formatMoney(usageMonthly)} spent`;
+    } else {
+      const used = Math.max(0, limit - limitRemaining);
+      const percent = limit > 0 ? (used / limit) * 100 : null;
+      usedPercent = percent === null ? null : Math.min(100, percent);
+      valueLabel = `$${formatMoney(used)} / $${formatMoney(limit)}`;
+
+      if (Object.hasOwn(PERIOD_SECONDS, data.limit_reset)) {
+        windowKey = data.limit_reset;
+        windowSeconds = PERIOD_SECONDS[data.limit_reset];
+        resetAt = resolveResetAt(data.limit_reset, nowMs);
+      } else {
+        windowKey = 'credits';
+        windowSeconds = null;
+        resetAt = null;
+      }
+    }
 
     return buildResult({
       providerId,
       providerName,
       ok: true,
       configured: true,
-      usage: { windows }
+      usage: {
+        windows: {
+          [windowKey]: toUsageWindow({
+            usedPercent,
+            windowSeconds,
+            resetAt,
+            valueLabel
+          })
+        }
+      }
     });
   } catch (error) {
+    const isTimeout = error instanceof DOMException && (
+      error.name === 'TimeoutError' || (error.name === 'AbortError' && timeoutSignal.aborted)
+    );
+    const isParseError = error instanceof SyntaxError;
     return buildResult({
       providerId,
       providerName,
       ok: false,
       configured: true,
-      error: error instanceof Error ? error.message : 'Request failed'
+      error: isTimeout
+        ? 'Request timed out'
+        : isParseError
+          ? 'Invalid response from provider'
+          : (error instanceof Error ? error.message : 'Request failed')
     });
   }
 };

package/server/lib/quota/providers/openrouter.test.js

@@ -0,0 +1,330 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../../opencode/auth.js', () => ({
+  readAuthFile: () => ({ openrouter: { key: 'test-token' } }),
+}));
+
+import { fetchQuota, resolveResetAt } from './openrouter.js';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+const mockResponse = (body, init = {}) => ({
+  ok: true,
+  status: 200,
+  json: async () => body,
+  ...init,
+});
+
+// Documented payload shape from https://openrouter.ai/docs/api_reference/limits
+const DOCUMENTED_PAYLOAD = {
+  data: {
+    label: 'Default',
+    limit: 30,
+    limit_remaining: 25,
+    limit_reset: 'monthly',
+    include_byok_in_limit: false,
+    usage: 5,
+    usage_daily: 1,
+    usage_weekly: 3,
+    usage_monthly: 5,
+    byok_usage: 0,
+    byok_usage_daily: 0,
+    byok_usage_weekly: 0,
+    byok_usage_monthly: 0,
+    is_free_tier: false,
+    is_management_key: false,
+    is_provisioning_key: false,
+    creator_user_id: 'user-fixture',
+    expires_at: null,
+    rate_limit: null
+  }
+};
+
+const expectMonthlyReset = (resetAt) => {
+  expect(resetAt).toEqual(expect.any(Number));
+  const resetDate = new Date(resetAt);
+  expect(resetDate.getUTCDate()).toBe(1);
+  expect(resetDate.getUTCHours()).toBe(0);
+  expect(resetAt - Date.now()).toBeGreaterThan(0);
+  expect(resetAt - Date.now()).toBeLessThanOrEqual(31 * 86400 * 1000);
+};
+
+describe('OpenRouter quota provider', () => {
+  it('builds a monthly window from the documented payload', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse(DOCUMENTED_PAYLOAD)));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.monthly;
+
+    expect(result.ok).toBe(true);
+    expect(result.providerId).toBe('openrouter');
+    expect(window.usedPercent).toBeCloseTo(16.6667, 3);
+    expect(window.valueLabel).toBe('$5.00 / $30.00');
+    expect(window.windowSeconds).toBe(30 * 86400);
+    expectMonthlyReset(window.resetAt);
+  });
+
+  it('uses the daily window and preserves the observed funded-key values', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: {
+        usage: 3.17561396,
+        usage_daily: 0.0000018,
+        usage_weekly: 0.0000018,
+        usage_monthly: 3.17561396,
+        limit: 30,
+        limit_remaining: 29.9999982,
+        limit_reset: 'daily',
+        is_free_tier: true,
+        is_management_key: false,
+        include_byok_in_limit: false,
+        byok_usage: 0
+      }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.daily;
+
+    expect(window).toBeDefined();
+    expect(window.windowSeconds).toBe(86400);
+    expect(window.valueLabel).toBe('$0.00 / $30.00');
+    expect(window.usedPercent).toBeLessThan(0.001);
+    expect(window.resetAt % 86400000).toBe(0);
+    expect(window.resetAt - Date.now()).toBeGreaterThan(0);
+    expect(window.resetAt - Date.now()).toBeLessThanOrEqual(86400000);
+  });
+
+  it('builds a monthly unlimited window from null limit fields', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: {
+        limit: null,
+        limit_remaining: null,
+        limit_reset: null,
+        usage_monthly: 3.17561396,
+        is_management_key: false
+      }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.monthly;
+
+    expect(window.usedPercent).toBeNull();
+    expect(window.valueLabel).toBe('$3.18 spent');
+    expect(window.windowSeconds).toBe(30 * 86400);
+    expectMonthlyReset(window.resetAt);
+  });
+
+  it('uses a credits window for a lifetime cap', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { limit: 30, limit_remaining: 25, limit_reset: null, usage_monthly: 5 }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.credits;
+
+    expect(window).toBeDefined();
+    expect(window.resetAt).toBeNull();
+    expect(window.windowSeconds).toBeNull();
+  });
+
+  it('uses a credits window for an unrecognized reset period', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { limit: 30, limit_remaining: 25, limit_reset: 'yearly', usage_monthly: 5 }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.credits;
+
+    expect(window).toBeDefined();
+    expect(window.resetAt).toBeNull();
+    expect(window.windowSeconds).toBeNull();
+  });
+
+  it('builds a weekly window from a weekly limit', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { limit: 30, limit_remaining: 25, limit_reset: 'weekly', usage_monthly: 5 }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.weekly;
+
+    expect(window).toBeDefined();
+    expect(window.windowSeconds).toBe(604800);
+    expect(new Date(window.resetAt).getUTCDay()).toBe(1);
+    expect(window.resetAt - Date.now()).toBeGreaterThan(0);
+    expect(window.resetAt - Date.now()).toBeLessThanOrEqual(7 * 86400 * 1000);
+  });
+
+  it('ignores BYOK usage when calculating the quota label and percent', async () => {
+    const withByokPayload = {
+      ...DOCUMENTED_PAYLOAD,
+      data: {
+        ...DOCUMENTED_PAYLOAD.data,
+        include_byok_in_limit: true,
+        byok_usage_monthly: 100,
+        byok_usage: 100
+      }
+    };
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce(mockResponse(DOCUMENTED_PAYLOAD))
+      .mockResolvedValueOnce(mockResponse(withByokPayload));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const withoutByok = await fetchQuota();
+    const withByok = await fetchQuota();
+
+    expect(withByok.usage.windows.monthly.valueLabel)
+      .toBe(withoutByok.usage.windows.monthly.valueLabel);
+    expect(withByok.usage.windows.monthly.usedPercent)
+      .toBe(withoutByok.usage.windows.monthly.usedPercent);
+  });
+
+  it('rejects management keys with a specific error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { is_management_key: true }
+    })));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe('Management key configured — quota needs an inference API key');
+  });
+
+  it.each([401, 403])('maps %s to a session-expired error', async (status) => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ ok: false, status }));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('Session expired — please re-authenticate with OpenRouter');
+  });
+
+  it('reports invalid-response on JSON parse failure', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => { throw new SyntaxError('Unexpected token'); },
+    }));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('Invalid response from provider');
+  });
+
+  it('reports a normalized timeout error', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new DOMException('The operation timed out.', 'TimeoutError')));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('Request timed out');
+  });
+
+  it('returns no-quota-data when data is missing', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({})));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.error).toBe('No quota data in response');
+    expect(result.usage).toBeNull();
+  });
+
+  it('returns no-quota-data when data is empty', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({ data: {} })));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.error).toBe('No quota data in response');
+    expect(result.usage).toBeNull();
+  });
+
+  it.each([null, []])('returns no-quota-data when data is %s', async (data) => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({ data })));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe('No quota data in response');
+  });
+
+  it('returns no-quota-data when a limit has no remaining value', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { limit: 30, limit_remaining: null, usage_monthly: 5 }
+    })));
+
+    const result = await fetchQuota();
+
+    expect(result.ok).toBe(false);
+    expect(result.error).toBe('No quota data in response');
+  });
+
+  it('keeps a zero limit valid with a null percent', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { limit: 0, limit_remaining: 0, limit_reset: 'monthly', usage_monthly: 0 }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.monthly;
+
+    expect(result.ok).toBe(true);
+    expect(window.usedPercent).toBeNull();
+    expect(window.valueLabel).toBe('$0.00 / $0.00');
+  });
+
+  it('requests the key endpoint and never the credits endpoint', async () => {
+    const fetchMock = vi.fn().mockResolvedValue(mockResponse(DOCUMENTED_PAYLOAD));
+    vi.stubGlobal('fetch', fetchMock);
+
+    await fetchQuota();
+
+    const requestedUrl = fetchMock.mock.calls[0][0];
+    expect(requestedUrl).toBe('https://openrouter.ai/api/v1/key');
+    expect(requestedUrl).not.toContain('/api/v1/credits');
+  });
+
+  it('resolves daily reset at the next UTC day across year boundaries', () => {
+    expect(resolveResetAt('daily', Date.UTC(2024, 11, 31, 23, 59))).toBe(Date.UTC(2025, 0, 1));
+  });
+
+  it('resolves weekly reset from Sunday to the next Monday', () => {
+    expect(resolveResetAt('weekly', Date.UTC(2024, 0, 7, 12))).toBe(Date.UTC(2024, 0, 8));
+  });
+
+  it('resolves weekly reset from Monday to the following Monday', () => {
+    expect(resolveResetAt('weekly', Date.UTC(2024, 0, 8, 12))).toBe(Date.UTC(2024, 0, 15));
+  });
+
+  it('resolves weekly reset from Wednesday to the next Monday', () => {
+    expect(resolveResetAt('weekly', Date.UTC(2024, 0, 10, 12))).toBe(Date.UTC(2024, 0, 15));
+  });
+
+  it('resolves monthly reset from January 31 to February 1', () => {
+    expect(resolveResetAt('monthly', Date.UTC(2024, 0, 31, 12))).toBe(Date.UTC(2024, 1, 1));
+  });
+
+  it('resolves monthly reset across December to January', () => {
+    expect(resolveResetAt('monthly', Date.UTC(2024, 11, 31, 23, 59))).toBe(Date.UTC(2025, 0, 1));
+  });
+
+  it('clamps percent at 100 while leaving the money label unclamped', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue(mockResponse({
+      data: { limit: 30, limit_remaining: -1, limit_reset: 'monthly', usage_monthly: 31 }
+    })));
+
+    const result = await fetchQuota();
+    const window = result.usage.windows.monthly;
+
+    expect(window.usedPercent).toBe(100);
+    expect(window.valueLabel).toBe('$31.00 / $30.00');
+  });
+});

package/server/lib/relay/DOCUMENTATION.md

@@ -25,6 +25,7 @@ Host side (`packages/web/server/lib/relay/`):
 - `host-client.js` — the long-lived connection manager: one outbound control connection to the relay, a per-client data connection for each connected device, reconnect/backoff, and the E2EE responder handshake per connection.
 - `host-lock.js` — the per-machine host claim. Every local instance sharing the data dir shares the relay identity (same serverId), so concurrent relay hosts evict each other at the relay worker (`4001: Control replaced`) and paired devices land on whichever local process won last. The claim file (`<data-dir>/relay-host.lock`, `{ pid }`) makes this deterministic: `service.js` only starts the host when no LIVE process holds the claim (stale claims from dead pids are ignored), goes to `standby` otherwise, and a 30s watcher both takes over when the claimant dies and stands down when another process claims. A standby watcher waits a 2-minute grace after the claim frees before taking over, so a cleanly restarting host (app update/relaunch) — which reclaims at boot with no wait — always wins the restart window over a bystander instance. Explicit user intent — creating a pairing link or hitting `/relay/enable` — force-claims; the previous holder's watcher sees the takeover and backs off instead of fighting. Instances created with `allowPassiveHost: false` (dev servers via `AIWORKER_RELAY_HOST=off`, the Electron dev shell via `AIWORKER_ELECTRON_DEV`; `AIWORKER_RELAY_HOST=on` overrides) never start the host passively at all — boot, demand reconcile, and watcher takeover leave them in `standby`; only explicit enable/pairing hosts there. The claim is cooperative (the relay worker still enforces the single host slot); it only decides which process keeps retrying.
 - `tunnel-host.js` — the per-connection dispatcher: decrypts tunnel frames and forwards HTTP/SSE/WS to the local server over loopback, then streams responses back. Enforces a path allowlist and never injects credentials.
+- `downstream-scheduler.js` owns end-client delivery credit and round-robin transmission across response streams. It selects plaintext frames before encryption.
 - `e2ee.js`, `tunnel-codec.js` — host-side (JS) mirrors of the shared crypto and framing (see "Two implementations" below).
 
 Client side (`packages/ui/src/lib/relay/`):
@@ -47,8 +48,75 @@ The host dispatcher restricts tunneled traffic to explicit path allowlists (one
 
 Request bodies crossing the tunnel are buffered on the host and forwarded to loopback only once the client's `StreamEnd` frame arrives (bodies above ~512 KB stream live instead). A body whose frames were lost in transit therefore never reaches the loopback server as an empty/truncated chunked body — the host aborts the stream and the client sees an ambiguous transport failure it can retry, instead of the loopback server's bare `400` ("Failed to send message (400)" from the mobile app).
 
+## Downstream flow control
+
+`hello` and `ready` negotiate `flowControl: true` independently of `batch`.
+When either peer omits the flag, the host keeps the legacy transmission path.
+This capability controls host-to-client traffic only. Uploads retain their
+existing request-body behavior. The Cloudflare broker needs no changes.
+
+The client sends encrypted `DeliveryAck` frames on stream zero. Their payload is
+an eight-byte unsigned big-endian cumulative count of received raw tunnel-frame
+bytes on nonzero streams, including the five-byte frame header. Batch envelopes,
+encryption overhead and stream-zero keepalives are excluded. The count resets
+with each handshake. ACKs cover complete frames and include late frames for
+cancelled streams, since those frames still consumed credit. The host rejects
+duplicate, regressing, partial-frame or beyond-sent acknowledgements.
+
+The client acknowledges after decoding and dispatching transport data, without
+waiting for React rendering. It coalesces acknowledgements by byte count with a
+short timer for the tail. Keepalives and ACK processing never await downstream
+credit, which would deadlock the channel.
+
+The scheduler starts with a small byte window. A backlogged sender can grow its
+window when ACK latency stays near the best observed round trip, and reduces it
+when delivery delay rises. Sparse traffic cannot inflate the window for a later
+bulk burst. The window has a hard upper bound; a sudden bandwidth drop can still
+delay bytes already sent, but cannot create an unlimited network backlog.
+
+HTTP bodies and WS messages are sliced into small frames. The scheduler rotates
+streams, preserves each stream's order, and batches selected frames before the
+serialized encryption step. Producers offer a bounded group of slices and await
+transmission before reading more. The legacy timed batcher remains in use only
+without negotiated flow control.
+
+HTTP/SSE backpressure reaches the loopback response reader. Node's `ws` pauses
+loopback socket reads while output is waiting. Bun's `ws` shim cannot pause, so
+the dispatcher instead enforces a connection-wide pending WS byte/message cap
+and explicitly aborts the offending substream on overflow. It never silently
+discards deltas. WS output messages are serialized through their last fragment,
+and the close frame follows pending output. Cancellation releases queued work;
+channel teardown releases all producers and acknowledgement state.
+
+Regression coverage lives in `downstream-scheduler.test.js`, `flow-control.test.js`
+and `cross-compat.test.js`. The end-to-end fixture uses the real client, host,
+crypto and loopback requests with a byte-paced relay leg. It compares delivery
+ordering, queue growth and a concurrent small response, including both legacy
+fallback directions, unbatched operation, cancellation and fragmented WS output.
+It does not replace a physical iOS/LTE check.
+
 ## Authentication model
 
+### Self-reported app diagnostics
+
+Host-control, host-data and client upgrades include optional `appId`,
+`appVersion` and `platform` query parameters. AiWorker sends `aiworker`,
+the local package version and the local runtime. Client platforms use the
+existing presence values: `desktop` for Electron, `vscode`, `ios`, `android`
+and `web` for browsers, including hosted mobile. Hosts use
+`AIWORKER_RUNTIME`, defaulting to `web`, so SSH hosts report `ssh-remote`.
+These labels describe the connecting process, not its remote target.
+
+These fields are diagnostics only, outside the signed auth payload. Older
+relays ignore them and older apps remain connectable. The hosted relay groups
+missing or invalid fields as `unknown`. Its analytics count host-control and
+client connections separately, including reconnects, and show labels as
+self-reported, never as verified app identity. Host-data sockets are excluded.
+App diagnostics are written on connection, without per-app traffic counters.
+No credentials, device names or application contents are added to diagnostics.
+
+### Access checks
+
 - The tunnel is **transport only**. The AiWorker server still authenticates every tunneled request exactly as it authenticates a direct remote client. The relay path grants reachability, not authorization.
 - Clients carry their normal credential. HTTP and SSE requests authenticate with the client's bearer token (a header). **WebSocket upgrades cannot send headers**, so they authenticate with a short-lived URL-scoped token minted beforehand and passed as a query parameter. This asymmetry is important when adding new WebSocket features (see the skill).
 - The host authenticates itself to the relay with a signed handshake using its long-lived signing key.
@@ -87,6 +155,13 @@ The E2EE and framing logic exists twice: TypeScript in `packages/ui/src/lib/rela
 
 ## Runtime integration (client)
 
+Client keepalive liveness comes from received frames only. Outbound HTTP retries
+cannot suppress a probe of a silent peer. Any valid inbound traffic, including a
+Pong, clears the probe deadline. Terminal relay close codes retain their error
+for the lifetime of that client: subsequent HTTP requests and WS opens fail
+immediately rather than waiting for a reconnect that will never be scheduled.
+Transient failures still use the existing reconnect/backoff path.
+
 Relay mode plugs into the existing client transport layer rather than a parallel path: `runtime-switch` activates the tunnel singleton, `runtime-fetch` routes runtime requests through it, `runtime-url`/`runtime-socket` yield tunnel-backed URLs and sockets, and `runtime-auth` mints the URL-scoped token through the tunnel. Direct-URL connections and the Electron realtime-proxy path are unaffected.
 
 ## Design invariants (do not regress)

package/server/lib/relay/cross-compat.test.js

@@ -12,16 +12,42 @@ import {
   decodeTunnelFrame as jsDecode,
   encodeFrameBatch as jsEncodeBatch,
   encodeTunnelFrame as jsEncode,
+  decodeDeliveryAck,
 } from './tunnel-codec.js';
 import {
   decodeFrameBatch as tsDecodeBatch,
   decodeTunnelFrame as tsDecode,
   encodeFrameBatch as tsEncodeBatch,
   encodeTunnelFrame as tsEncode,
+  encodeDeliveryAck,
 } from '../../../../ui/src/lib/relay/tunnel-codec.ts';
 import { TunnelFrameType as TsFrameType } from '../../../../ui/src/lib/relay/protocol.ts';
 
 describe('relay JS-host <-> TS-client cross compatibility', () => {
+  it('negotiates flow control independently of batching, with legacy fallback on either side', async () => {
+    const keys = await generateEcdhKeyPair();
+    const pub = await exportPublicKeyJwk(keys.publicKey);
+    for (const batch of [false, true]) {
+      for (const clientFlow of [false, true]) {
+        for (const hostFlow of [false, true]) {
+          const client = await createClientHandshake(pub, { batch, flowControl: clientFlow });
+          const host = createHostHandshake(keys.privateKey, { batch, flowControl: hostFlow });
+          const ready = await host.handleText(client.helloText);
+          const established = await client.handleText(ready.replyText);
+          expect(ready.flowControl).toBe(clientFlow && hostFlow);
+          expect(established.flowControl).toBe(clientFlow && hostFlow);
+          expect(established.batch).toBe(batch);
+          expect((await host.handleText(client.helloText)).text).toBe(ready.replyText);
+        }
+      }
+    }
+    expect(JsFrameType).toEqual(TsFrameType);
+    for (const bytes of [0, 8197, 2 ** 32 + 17, Number.MAX_SAFE_INTEGER]) {
+      expect(decodeDeliveryAck(encodeDeliveryAck(bytes))).toBe(bytes);
+    }
+    expect(() => decodeDeliveryAck(new Uint8Array(7))).toThrow();
+    expect(() => decodeDeliveryAck(new Uint8Array(8).fill(255))).toThrow();
+  });
   it('completes a handshake and exchanges frames both ways', async () => {
     const hostKeys = await generateEcdhKeyPair();
     const hostPubJwk = await exportPublicKeyJwk(hostKeys.publicKey);