dsh-cherry-bridge 0.1.9 → 0.1.10

package/src/connection.ts

@@ -11,6 +11,7 @@ import {
   DEFAULT_CONTENT_READ_BUDGET_PER_SECOND,
   DEFAULT_RATE_BUDGET_PER_SECOND,
   DEFAULT_TRANSPORT_RETRY_WAIT_MS,
+  RATE_LIMIT_MAX_WAIT_MS,
 } from './defaults.js'
 import { urlHost } from './urlHost.js'
 import type { DeviceRecord } from './deviceStore.js'
@@ -51,9 +52,14 @@ export interface DeviceConnectionOptions {
    * budget satisfies it with no cross-device scheduling.
    *
    * The content tier DERIVES from this value at the production ratio
-   * (DEFAULT_CONTENT_READ_BUDGET_PER_SECOND / DEFAULT_RATE_BUDGET_PER_SECOND),
-   * so one injected budget scales both tiers and the two stay in the same
-   * proportion the peer's allowances have.
+   * (DEFAULT_CONTENT_READ_BUDGET_PER_SECOND / DEFAULT_RATE_BUDGET_PER_SECOND,
+   * i.e. 8 : 1), so LOWERING this lowers both tiers. That ratio matches the
+   * <=2.1.6 allowances (512:64) and is where the 2.1.7 story used to be
+   * conservative — but only the shared line moved (256 in 2.1.7), so the derived
+   * tier is CLAMPED at the peer's 512/s content allowance
+   * (`contentBudgetFor`, issue #111): above a shared budget of 64 the knob stops
+   * scaling it instead of deriving 2,048/s from 2.1.7's shared figure and
+   * spending the tier being refused.
    */
   rateBudgetPerSecond?: number
   /** First reconnect backoff (default 1s); doubles per attempt. */
@@ -228,6 +234,31 @@ const RATE_WINDOW_MS = 1_000
 const RATE_WINDOW_MARGIN_MS = 150
 /** The deliberate local-shutdown face of a disposed client (see the replay path). */
 const DISPOSED_RE = /^JSON-RPC client disposed$/
+
+/**
+ * The peer's structured over-budget refusal (desktop >= 2.1.7), or undefined.
+ *
+ * 2.1.7 answers an over-budget request with ONE `RATE_LIMITED` failure carrying
+ * `retryAfterMs` and keeps the session; <=2.1.6 instead closed the whole socket
+ * with 1011, which is the transport-loss path and never reaches this check.
+ */
+function rateLimitRefusal(error: unknown): JsonRpcRequestError | undefined {
+  if (!(error instanceof JsonRpcRequestError)) return undefined
+  const data = error.data
+  if (typeof data !== 'object' || data === null) return undefined
+  return (data as Record<string, unknown>)['reason'] === 'RATE_LIMITED' ? error : undefined
+}
+
+/**
+ * How long a refusal asks the caller to wait, bounded by
+ * {@link RATE_LIMIT_MAX_WAIT_MS}. An absent or unusable value is 0: retry at
+ * the next pacing slot rather than invent a delay the peer never asked for.
+ */
+function rateLimitWaitMs(refusal: JsonRpcRequestError): number {
+  const raw = (refusal.data as Record<string, unknown>)['retryAfterMs']
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) return 0
+  return Math.min(raw, RATE_LIMIT_MAX_WAIT_MS)
+}
 /**
  * The read methods whose transport loss may be replayed automatically.
  *
@@ -338,8 +369,9 @@ class SecondWindowRateLimiter {
  *    ({@link DEFAULT_CONTENT_READ_BUDGET_PER_SECOND}).
  *
  * WHY TWO TIERS: the desktop paces the two against different allowances (512/s
- * for content reads, 64/s for everything else) and the official client follows
- * suit (480/s and 40/s). Sharing one 32/s tier spent content-read throughput on
+ * for content reads; 64/s for everything else through 2.1.6 and 256/s from
+ * 2.1.7) and the official client follows suit (480/s and 40/s). Sharing one
+ * 32/s tier spent content-read throughput on
  * unrelated RPCs and vice versa: a multi-slice walk of an externalized part —
  * every part over 4,096 characters on Cherry >= 2.1.6 — queued behind list
  * calls at ~36ms per slice.
@@ -350,9 +382,9 @@ type RateTier = 'shared' | 'content'
  * Which tier paces `method`. The rule is EXACT-MATCH: `agent.content.read` is
  * the only method on the content tier, and every other method — a command, a
  * list read, a different `agent.*.read` — keeps the shared tier. A prefix or
- * suffix match would silently widen the 256/s tier to methods whose peer-side
- * allowance is the 64/s one, which is a session-killing mistake (close 1011),
- * so a new content-plane method must be named here deliberately.
+ * suffix match would silently widen the content tier to methods whose peer-side
+ * allowance is the shared one — 64/s through 2.1.6, where exceeding it closes
+ * the SESSION (1011) — so a new content-plane method must be named deliberately.
  */
 function classifyRateTier(method: string): RateTier {
   return method === 'agent.content.read' ? 'content' : 'shared'
@@ -558,6 +590,28 @@ function businessWindowFor(reportedInFlightRequests: number): number {
   return Math.max(1, Math.min(BUSINESS_MAX_IN_FLIGHT, Math.floor(reportedInFlightRequests / 2)))
 }
 
+/**
+ * The desktop's content-read allowance: 512/s, and the SAME in both generations
+ * (`RemoteAccessService.ts` counts `agent.content.read` on its own counter,
+ * 512 in v2.1.6 and v2.1.7 alike; only the shared line moved, 64 ⇒ 256).
+ *
+ * A CEILING on the derived tier, not a third knob. The 8 : 1 ratio exists so an
+ * operator who LOWERS the shared budget lowers both tiers; upward, the ratio
+ * would spend headroom the peer does not have — `rateBudgetPerSecond: 256`
+ * (2.1.7's SHARED figure, an easy number to copy) derives 2,048/s, which the
+ * limiter's 1 ms gap compresses to ~1,000/s against this allowance, so roughly
+ * every other content read is refused. On >=2.1.7 each refusal costs up to a
+ * second plus one replay and a second refusal fails the whole read; on <=2.1.6
+ * an overrun closes the SESSION (1011). Because this line is
+ * generation-INDEPENDENT, bounding it needs no generation detection — the one
+ * bound in this file that does not.
+ *
+ * 512 is the ceiling and 333/s is what the limiter then ACHIEVES from it
+ * (`(1,000 + 150) / 512` ceils to a 3 ms gap), so the saturated tier still
+ * keeps a 1.5x margin on arrival times.
+ */
+const CONTENT_BUDGET_CEILING_PER_SECOND = 512
+
 /**
  * The content-read tier's budget for a given SHARED budget.
  *
@@ -566,10 +620,20 @@ function businessWindowFor(reportedInFlightRequests: number): number {
  * them rather than staying pinned at 256 while the shared tier shrinks. An
  * absent injection is the production default (which yields exactly
  * `DEFAULT_CONTENT_READ_BUDGET_PER_SECOND`).
+ *
+ * Upward the ratio stops at {@link CONTENT_BUDGET_CEILING_PER_SECOND}: past a
+ * shared budget of 64 the derived value would exceed an allowance that never
+ * changed, so it is clamped instead of trying to pace past it.
+ *
+ * Exported for `tests/unit/contentBudgetCeiling.test.ts`, the same reason
+ * `reconnectWait` is: the ceiling is a property of this mapping, and asserting
+ * it through the limiter's timing would be a slower, flakier version of the
+ * same claim.
  */
-function contentBudgetFor(sharedBudgetPerSecond: number | undefined): number {
+export function contentBudgetFor(sharedBudgetPerSecond: number | undefined): number {
   const ratio = DEFAULT_CONTENT_READ_BUDGET_PER_SECOND / DEFAULT_RATE_BUDGET_PER_SECOND
-  return Math.ceil((sharedBudgetPerSecond ?? DEFAULT_RATE_BUDGET_PER_SECOND) * ratio)
+  const derived = Math.ceil((sharedBudgetPerSecond ?? DEFAULT_RATE_BUDGET_PER_SECOND) * ratio)
+  return Math.min(CONTENT_BUDGET_CEILING_PER_SECOND, derived)
 }
 
 function defer<T>(): { promise: Promise<T>; resolve: (value: T) => void; reject: (error: Error) => void } {
@@ -1080,17 +1144,18 @@ export class DeviceConnection {
     // cannot tear down a newer link.
     //
     // ADJUDICATED WEAKENING: the close CODE is deliberately ignored here.
-    // 1011 (server error / rate termination) and 1013 (try again later, e.g.
-    // connection-count over limit) are the peer's AUTHORITATIVE session-level
-    // faces — it ends the whole session, never a single request — so every code
-    // takes the same offline → backoff → reconnect path. Differentiating them
-    // (e.g. a longer, Retry-After-aware backoff for 1013) is deliberately
-    // DEFERRED: it would need a per-code policy the protocol does not yet
-    // guarantee, and a uniform honest retry is strictly safer than guessing a
-    // longer one. The rate limiter still bounds the retry storm in the
-    // meantime, and the contract suite's `rate-limit-terminates-session` item
-    // proves the uniform transition shape: the 1011 close routes through
-    // offline → reconnect rather than surfacing a per-request refusal.
+    // 1011 (server error; rate termination through 2.1.6) and 1013 (try again
+    // later, e.g. connection-count over limit) are session-level faces — the
+    // peer ends the whole session, never a single request — so every code takes
+    // the same offline → backoff → reconnect path. Differentiating them (e.g. a
+    // longer, Retry-After-aware backoff for 1013) is deliberately DEFERRED: it
+    // would need a per-code policy the protocol does not yet guarantee, and a
+    // uniform honest retry is strictly safer than guessing a longer one. The
+    // rate limiter still bounds the retry storm in the meantime, and the
+    // contract suite's `rate-limit-terminates-session` item proves the uniform
+    // transition shape: the 1011 close routes through offline → reconnect.
+    // Since 2.1.7 an over-budget request is refused per request instead (a
+    // structured `RATE_LIMITED`, not a close), so it never reaches this path.
     ws.on('close', () => this.#onLinkLost(epoch, 'socket closed'))
     ws.on('error', () => this.#onLinkLost(epoch, 'socket error'))
 
@@ -1472,6 +1537,8 @@ export class DeviceConnection {
     try {
       return await link.client.request<T>(method, params, opts)
     } catch (error) {
+      const refusal = rateLimitRefusal(error)
+      if (refusal !== undefined) return await this.#replayAfterRateLimit(refusal, method, params, opts)
       if (!this.#isTransportLoss(error)) throw error
       // Reported with the state the request DIED in ('connected'): the
       // supervisor has not necessarily observed the loss yet, and naming the
@@ -1561,6 +1628,70 @@ export class DeviceConnection {
     }
   }
 
+  /**
+   * ONE bounded replay for a READ the peer refused because the socket is over
+   * its rate window.
+   *
+   * 2.1.7 answers that request with a structured `RATE_LIMITED` failure and a
+   * `retryAfterMs` instead of closing the session (see `rateLimitRefusal`), so
+   * the caller no longer learns it was throttled by losing its connection:
+   * without this, a transient refusal became a failed tool call whose part text
+   * the projection would even degrade.
+   *
+   * The shape mirrors the transport-loss replay, for the same reasons:
+   *
+   *  - only a READ is replayed (a command's refusal is a verdict on that
+   *    arrival, and commands are never replayed — receipts recover them);
+   *  - the wait is charged to the caller's deadline and never extends it, so a
+   *    wait answer's budget turns a refusal near its bound into a `'deadline'`
+   *    stop instead of an overrun;
+   *  - the replay takes a FRESH pacing admission: it is a new arrival at the
+   *    peer, and skipping the admission would replay into the same full window.
+   *
+   * A SECOND refusal is a real failure and propagates as itself (the fresh
+   * `retryAfterMs` is the more useful one); a link lost under the replay is
+   * reported as the classified `TransportLostError`, never as bare text.
+   */
+  async #replayAfterRateLimit<T>(
+    refusal: JsonRpcRequestError,
+    method: string,
+    params: unknown,
+    opts: JsonRpcRequestOptions | undefined,
+  ): Promise<T> {
+    if (!RETRYABLE_READ_METHODS.has(method) || !this.#running) throw refusal
+    const remaining = this.#remainingMs(opts)
+    if (remaining !== undefined && remaining <= 0) throw new RpcDeadlineExceededError(this.record.deviceId, method)
+    const requested = rateLimitWaitMs(refusal)
+    const waitMs = Math.min(requested, remaining ?? Number.POSITIVE_INFINITY)
+    // WHICH BOUND WAS SPENT is captured BEFORE the timer, never re-derived from
+    // a clock read after it: a timer may fire a millisecond EARLY (the same race
+    // `reconnectWait`/`deadlineCapped` exists to avoid, and the reason
+    // `RequestTimeoutError.clampedByDeadline` is a flag). When the requested
+    // wait consumed the caller's whole budget, the outcome is the CALLER's
+    // deadline — throwing it here also keeps the one replay from being sent
+    // into a budget that was already spent.
+    const deadlineSpent = remaining !== undefined && requested >= remaining
+    if (waitMs > 0) await new Promise<void>((resolve) => setTimeout(resolve, waitMs))
+    // The wait is not cancellable by `close()`; the state is re-judged instead,
+    // the same way every other parked wait in this class is.
+    if (!this.#running || this.#state !== 'connected') throw refusal
+    if (deadlineSpent || this.#deadlinePassed(opts)) {
+      throw new RpcDeadlineExceededError(this.record.deviceId, method)
+    }
+    await this.#limiter.acquire(method)
+    const link = this.#link
+    if (!this.#running || this.#state !== 'connected' || link === undefined) throw refusal
+    if (this.#deadlinePassed(opts)) throw new RpcDeadlineExceededError(this.record.deviceId, method)
+    try {
+      return await link.client.request<T>(method, params, opts)
+    } catch (error) {
+      if (this.#isTransportLoss(error)) {
+        throw new TransportLostError(this.record.deviceId, 'connected', method, { cause: error })
+      }
+      throw error
+    }
+  }
+
   /** Whether a rejection is the dead channel, as opposed to a peer's own answer. */
   #isTransportLoss(error: unknown): boolean {
     // A peer refusal is a verdict (JsonRpcRequestError) and a deliberate local

package/src/defaults.ts

@@ -21,18 +21,21 @@
  * This is the SHARED tier: it covers every business RPC EXCEPT the content-read
  * tier below (see {@link DEFAULT_CONTENT_READ_BUDGET_PER_SECOND}).
  *
- * WHY 32: the desktop's own allowance for "other" RPCs is 64/s
- * (`RemoteAccessService.ts:223-225`; the official client paces them at 40/s,
- * `DesktopSession.ts:242-244`), and exceeding the allowance is not a refusal
- * but a whole-session close (1011). Half the peer's line leaves room for the
- * housekeeping traffic that shares the socket (hello/authenticate/ping/refresh
- * bypass pacing by design) and for arrival compression between our admission
- * times and the peer's arrival times.
+ * WHY 32: the desktop's allowance for "other" RPCs is 64/s through 2.1.6 and
+ * 256/s from 2.1.7 (`RemoteAccessService.ts`; the official client paces them at
+ * 40/s, `DesktopSession.ts:36-37`). What an over-budget request does also
+ * changed: through 2.1.6 it closes the WHOLE session (1011), while 2.1.7 (PR
+ * #21687) refuses that one request (`RATE_LIMITED` + `retryAfterMs`) and keeps
+ * the session. The generations cannot be told apart before one answers, so the
+ * default is sized for the older, harsher peer: 32 is half of 64 and an eighth
+ * of 256, leaving room for the housekeeping traffic that shares the socket
+ * (hello/authenticate/ping/refresh bypass pacing by design) and for arrival
+ * compression between our admission times and the peer's arrival times.
  *
  * SOURCES (neither is in this repository): the desktop lines are
- * `_research/cherry-studio` @ v2.1.6 (90b234e); the official-client lines are
- * CherryHQ/cherry-studio-app @ main 18329fe (app 0.3.0), read on 2026-10-18 —
- * recorded in `.superpowers/review-v013-r1/context.md`.
+ * `_research/cherry-studio` @ v2.1.6 (90b234e) and CherryHQ/cherry-studio @
+ * v2.1.7; the official-client lines are CherryHQ/cherry-studio-app @ v0.4.0,
+ * both read on 2026-10-22 (issue #102).
  */
 export const DEFAULT_RATE_BUDGET_PER_SECOND = 32
 
@@ -49,9 +52,10 @@ export const DEFAULT_RATE_BUDGET_PER_SECOND = 32
  * (`RemoteAccessService.ts:223-225`) and the official client issues them at
  * 480/s (`DesktopSession.ts:33-37`). Pacing them with the 32/s shared tier
  * bound a multi-slice walk to ~670 KiB/s and queued it behind unrelated RPCs;
- * 256 is half the peer's own kill line — the same 2× margin the shared tier
- * keeps on 64/s — and lifts the bound to the multi-MiB/s range of the official
- * client while leaving the desktop a session-sized headroom.
+ * 256 is half the 512/s content allowance in BOTH desktop generations (the
+ * shared-tier allowance changed in 2.1.7; this one did not) and lifts the bound
+ * to the multi-MiB/s range of the official client while leaving the desktop a
+ * session-sized headroom.
  *
  * NOT a plugin-config key: the two tiers derive from ONE injected shared budget
  * at the ratio below, so an operator who lowers `rateBudgetPerSecond` lowers
@@ -60,12 +64,18 @@ export const DEFAULT_RATE_BUDGET_PER_SECOND = 32
  *
  * THE MARGINS ARE A DEFAULT-INJECTION CLAIM: the 2× headroom above holds at
  * the default injection (32/s), where this tier is exactly 256/s. An injected
- * budget consumes BOTH tiers' headroom in proportion — at 64/s the shared tier
- * is at the peer's 64/s line and this tier derives to 512/s, i.e. nominal
- * saturation of both allowances. The limiter's integer gap means the ACHIEVED
- * rate stays below the nominal one in that case (≤ 334/s on this tier, 55.6/s
- * on the shared one; see `SecondWindowRateLimiter` in `connection.ts`), which
- * is margin by accident rather than by design.
+ * budget consumes BOTH tiers' headroom up to the point where this tier reaches
+ * the PEER'S CEILING — at 64/s the shared tier sits on the ≤2.1.6 line (the
+ * harsher generation, where overrun still closes the session) and this tier
+ * derives to exactly 512/s, the content allowance BOTH generations share. Above
+ * 64/s the clamp holds it at 512/s: `contentBudgetFor` (issue #111) still
+ * derives the ratio, then bounds it — because a knob copied from 2.1.7's shared
+ * figure (256)
+ * would otherwise derive 2,048/s and spend the tier being refused. The
+ * limiter's integer gap means the ACHIEVED rate stays below the nominal one in
+ * that case (≤ 334/s on this tier, 55.6/s on the shared one; see
+ * `SecondWindowRateLimiter` in `connection.ts`), which is margin by accident
+ * rather than by design.
  */
 export const DEFAULT_CONTENT_READ_BUDGET_PER_SECOND = 256
 
@@ -81,6 +91,20 @@ export const DEFAULT_CONTENT_READ_BUDGET_PER_SECOND = 256
  */
 export const DEFAULT_TRANSPORT_RETRY_WAIT_MS = 5_000
 
+/**
+ * The longest a READ may wait for the peer's rate window to clear before its
+ * ONE bounded replay (`RATE_LIMITED` + `retryAfterMs`, desktop >= 2.1.7).
+ *
+ * Why the peer's own window and not a separate budget: the desktop derives
+ * `retryAfterMs` from its 1 s accounting window, so a larger value cannot come
+ * from the peer, and waiting longer would hold a tool call for no reason. The
+ * caller's own deadline (`JsonRpcRequestOptions.deadline`) still clamps it, and
+ * a wait answer's `AssemblyDeadline` is what makes a refusal near the budget a
+ * `'deadline'` stop rather than an overrun. A COMMAND never takes this wait: its
+ * refusal is a verdict on that arrival, and commands are never replayed.
+ */
+export const RATE_LIMIT_MAX_WAIT_MS = 1_000
+
 /**
  * How long a DEVICE TOOL waits for an establishment attempt that is already in
  * flight (`state === 'connecting'`) before judging the device.

package/src/diagnostics.ts

@@ -97,19 +97,26 @@ export const CONTRACT_DIFFERENCES: readonly ContractDifference[] = [
   },
   {
     id: 'rate-limit-terminates-session',
-    title: 'Over-limit rate limiting terminates the whole session (close 1011)',
+    title: 'Over-limit rate limiting is generation-dependent: a whole-session 1011 close (≤2.1.6) or a per-request refusal (≥2.1.7)',
     realPeer:
-      'Exceeding the desktop\'s per-socket budget (64 req/s in the current implementation, a server ' +
-      'value with no negotiation channel) terminates the ENTIRE session with close code 1011 — it is ' +
-      'not a per-request `RATE_LIMITED` rejection the caller can retry in place.',
+      'Through 2.1.6, exceeding the desktop\'s per-socket budget (64 req/s shared, 512 req/s content; ' +
+      'implementation values with no negotiation channel) terminated the ENTIRE session with close ' +
+      'code 1011. From 2.1.7 (PR #21687) the shared allowance is 256 req/s and an over-budget request ' +
+      'is answered with ONE structured `RATE_LIMITED` failure carrying `retryAfterMs`, while the ' +
+      'session survives.',
     fakePeer:
-      'The fake closes the session with 1011 once `rateLimitPerSecond` is exceeded, so the client\'s ' +
-      'offline→backoff→reconnect path is exercised rather than a request-level refusal.',
-    schemaAnchor: 'remoteLimits + peer close code 1011 (implementation value, not a protocol promise)',
+      'The fake models BOTH generations: `rateLimitMode` `close` (the ≤2.1.6 default) closes the ' +
+      'session with 1011 once `rateLimitPerSecond` is exceeded, exercising the ' +
+      'offline→backoff→reconnect path; `refuse` answers one structured `RATE_LIMITED` failure with ' +
+      '`retryAfterMs` and keeps the session, exercising the bounded replay.',
+    schemaAnchor:
+      'remoteLimits + peer close code 1011 (≤2.1.6) / failure data reason RATE_LIMITED + retryAfterMs (≥2.1.7); implementation values, not protocol promises',
     checklistStep:
-      'rate-limit-terminates-session: against a real desktop, drive a burst well above the smooth ' +
-      'budget and confirm the socket is closed with 1011 (session gone, state offline, backoff ' +
-      'restart) rather than a single structured per-request rejection.',
+      'rate-limit-terminates-session: on a ≥2.1.7 desktop, raise `rateBudgetPerSecond` (or use an ' +
+      'unpaced probe) and drive a burst above the allowance; confirm each over-budget request is ' +
+      'refused with `RATE_LIMITED` + `retryAfterMs` while the session stays live, a refused READ ' +
+      'succeeds after ONE replay, and a refused COMMAND surfaces as a verdict and is not replayed. ' +
+      'On ≤2.1.6, the same burst closes the socket with 1011 (state offline, backoff restart).',
   },
   {
     id: 'execution-terminal-no-interrupted',

package/src/index.ts

@@ -83,9 +83,13 @@ export interface CherryBridgeConfig {
    * The CONTENT tier is not configurable on its own: it DERIVES from this value
    * at the 8 : 1 production ratio (`DEFAULT_CONTENT_READ_BUDGET_PER_SECOND` /
    * `DEFAULT_RATE_BUDGET_PER_SECOND`), so the default 32 yields the 256/s
-   * content tier and any other value scales both tiers together. Raising this
-   * toward the peer's own lines therefore spends BOTH tiers' safety margin —
-   * see `DEFAULT_CONTENT_READ_BUDGET_PER_SECOND` for the numbers.
+   * content tier and lowering this lowers both. UPWARD the derivation stops at
+   * the peer's 512/s content allowance (issue #111): a value above 64 no longer
+   * scales that tier, it only spends the shared tier's margin. Raising this
+   * toward the peer's own lines spends margin: on a <=2.1.6 desktop that is
+   * BOTH tiers (64 shared / 512 content), while on 2.1.7 only the shared line
+   * moves (256 there). See `DEFAULT_CONTENT_READ_BUDGET_PER_SECOND` for the
+   * numbers.
    */
   rateBudgetPerSecond?: number
   /**