@aiworker/web 1.22.0 → 1.23.0

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/quota/providers/xai.js

@@ -323,7 +323,7 @@ const fetchUsage = async (accessToken) => {
       'Content-Type': 'application/grpc-web+proto',
       'x-grpc-web': '1',
       'x-user-agent': 'connect-es/2.1.1',
-      'User-Agent': 'OpenChamber'
+      'User-Agent': 'AiWorker'
     },
     body: EMPTY_GRPC_WEB_BODY,
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)

package/server/lib/quota/routes.js

@@ -2,8 +2,10 @@ import express from 'express';
 import { deleteManagedCredential, getManagedCredentialStatus, normalizers, readManagedCredential, writeManagedCredential } from './credentials/providers.js';
 import { fetchOllamaCloudUsage } from './providers/ollama-cloud.js';
 import { importCursorCredential, validateCursorCredential } from './providers/cursor.js';
+import { fetchExeDevUsage } from './providers/exe-dev.js';
 
 const validators = {
+  'exe-dev': fetchExeDevUsage,
   'ollama-cloud': fetchOllamaCloudUsage,
   cursor: validateCursorCredential,
 };

package/server/lib/quota/utils/auth.js

@@ -1,8 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { OPENCODE_CONFIG_DIR } from '../../opencode/shared.js';
 
-const OPENCODE_CONFIG_DIR = path.join(os.homedir(), '.config', 'opencode');
 const OPENCODE_DATA_DIR = path.join(os.homedir(), '.local', 'share', 'opencode');
 
 export const ANTIGRAVITY_ACCOUNTS_PATHS = [

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/`):
@@ -41,12 +42,59 @@ Relay is not a separate link format: it is one transport candidate inside the un
 Everything a client normally sends to the single AiWorker origin:
 - **HTTP** — REST endpoints and proxied OpenCode SDK calls under `/api/*`, plus `/auth/*` and `/health`.
 - **SSE** — long-lived streamed responses (the event stream and notifications). These are just HTTP responses whose body streams; the tunnel needs no special SSE handling.
-- **WebSocket** — the endpoints that use a real socket (the global event stream on platforms that support WS, terminal I/O, dictation).
+- **WebSocket** — the endpoints that use a real socket (the global event stream on platforms that support WS, terminal I/O, dictation, and desktop dev-server previews).
 
 The host dispatcher restricts tunneled traffic to explicit path allowlists (one for HTTP, one for WS).
 
 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
 
 - 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.
@@ -87,6 +135,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);

package/server/lib/relay/downstream-scheduler.js

@@ -0,0 +1,154 @@
+// Downstream credit belongs to the end client, not the relay's TCP connection.
+// Producers await send(), so HTTP readers stop before building a plaintext queue.
+import { decodeTunnelFrame } from './tunnel-codec.js';
+import { MAX_PLAINTEXT_FRAME_BYTES } from './e2ee.js';
+
+export const DOWNSTREAM_CHUNK_BYTES = 8 * 1024;
+const MIN_WINDOW_BYTES = 64 * 1024;
+const MAX_WINDOW_BYTES = 1024 * 1024;
+const MAX_QUEUED_BYTES = 4 * 1024 * 1024;
+const MAX_QUEUED_FRAMES = 4096;
+const MAX_OUTSTANDING_FRAMES = 4096;
+const QUEUE_DELAY_TARGET_MS = 100;
+
+export const createDownstreamScheduler = ({ sendBatch, onError, maxBatchFrames = 32, now = () => performance.now() }) => {
+  const queues = new Map();
+  const outstanding = [];
+  let queuedBytes = 0;
+  let queuedFrames = 0;
+  let sentBytes = 0;
+  let acknowledgedBytes = 0;
+  let windowBytes = MIN_WINDOW_BYTES;
+  let minRtt = Infinity;
+  let adjustmentBoundary = MIN_WINDOW_BYTES;
+  let windowLimited = false;
+  let draining = false;
+  let closed = false;
+  let sending = [];
+
+  const close = () => {
+    closed = true;
+    for (const queue of queues.values()) for (const entry of queue) entry.resolve();
+    for (const entry of sending) entry.resolve();
+    sending = [];
+    queues.clear();
+    outstanding.length = 0;
+    queuedBytes = 0;
+    queuedFrames = 0;
+  };
+
+  const fail = error => {
+    close();
+    onError(error);
+  };
+
+  const drain = async () => {
+    if (draining || closed) return;
+    draining = true;
+    try {
+      while (!closed) {
+        const selected = [];
+        let batchBytes = 1;
+        while (selected.length < maxBatchFrames) {
+          // Stream zero carries only tiny keepalives; it must not wait for credit.
+          const next = queues.has(0) ? [0, queues.get(0)] : queues.entries().next().value;
+          if (!next) break;
+          const [streamId, queue] = next;
+          const entry = queue[0];
+          // Do not skip a larger head indefinitely in favour of smaller frames.
+          if (streamId !== 0 && sentBytes - acknowledgedBytes + entry.frame.length > windowBytes) {
+            windowLimited = true;
+            break;
+          }
+          if (streamId !== 0 && outstanding.length >= MAX_OUTSTANDING_FRAMES) break;
+          if (batchBytes + 4 + entry.frame.length > MAX_PLAINTEXT_FRAME_BYTES) break;
+          queue.shift();
+          queues.delete(streamId);
+          if (queue.length) queues.set(streamId, queue);
+          queuedBytes -= entry.frame.length;
+          queuedFrames -= 1;
+          if (streamId !== 0) {
+            sentBytes += entry.frame.length;
+            outstanding.push({ end: sentBytes, at: now() });
+          }
+          selected.push(entry);
+          batchBytes += 4 + entry.frame.length;
+        }
+        if (!selected.length) break;
+        sending = selected;
+        try {
+          // Selection precedes encryption. Never reorder encrypted IV counters.
+          await sendBatch(selected.map(entry => entry.frame));
+        } finally {
+          for (const entry of selected) entry.resolve();
+          sending = [];
+        }
+      }
+    } catch (error) {
+      fail(error);
+    } finally {
+      draining = false;
+    }
+  };
+
+  return {
+    send(frame) {
+      if (closed) return Promise.resolve();
+      const { streamId } = decodeTunnelFrame(frame);
+      if (queuedBytes + frame.length > MAX_QUEUED_BYTES || queuedFrames >= MAX_QUEUED_FRAMES) {
+        fail(new Error('relay downstream queue limit exceeded'));
+        return Promise.resolve();
+      }
+      return new Promise(resolve => {
+        const queue = queues.get(streamId) ?? [];
+        queue.push({ frame, resolve, streamId });
+        queues.set(streamId, queue);
+        queuedBytes += frame.length;
+        queuedFrames += 1;
+        // Let concurrent streams join this round before selecting the next frame.
+        queueMicrotask(() => { void drain(); });
+      });
+    },
+    acknowledge(bytes) {
+      if (closed) return;
+      if (!Number.isSafeInteger(bytes) || bytes <= acknowledgedBytes || bytes > sentBytes) {
+        throw new Error('invalid relay delivery acknowledgement');
+      }
+      // An ACK may cover several complete frames, never a partial frame.
+      const endIndex = outstanding.findIndex(entry => entry.end === bytes);
+      if (endIndex < 0) throw new Error('relay acknowledgement is not a frame boundary');
+      const rtt = Math.max(1, now() - outstanding[endIndex].at);
+      outstanding.splice(0, endIndex + 1);
+      acknowledgedBytes = bytes;
+      minRtt = Math.min(minRtt, rtt);
+      // Grow on a clear path, reduce when the client's delivery delay grows.
+      // Adjust once per window, not once per frame in a burst of ACKs.
+      if (bytes >= adjustmentBoundary) {
+        if (rtt > minRtt + QUEUE_DELAY_TARGET_MS) {
+          windowBytes = Math.max(MIN_WINDOW_BYTES, Math.floor(windowBytes / 2));
+        } else if (windowLimited) {
+          // Sparse token traffic must not inflate a future bash burst's window.
+          windowBytes = Math.min(MAX_WINDOW_BYTES, windowBytes * 2);
+        }
+        windowLimited = false;
+        adjustmentBoundary = bytes + windowBytes;
+      }
+      void drain();
+    },
+    cancel(streamId) {
+      // Already-selected bytes may still arrive and must still be ACKed, but
+      // cancelled producers need not wait for an in-progress encryption call.
+      for (const entry of sending) if (entry.streamId === streamId) entry.resolve();
+      const queue = queues.get(streamId);
+      if (!queue) return;
+      queues.delete(streamId);
+      for (const entry of queue) {
+        queuedBytes -= entry.frame.length;
+        queuedFrames -= 1;
+        entry.resolve();
+      }
+      void drain();
+    },
+    close,
+  };
+};