dsh-cherry-bridge 0.1.9 → 0.1.10

package/src/tools.ts

@@ -12,6 +12,7 @@ import {
 } from './defaults.js'
 import { JsonRpcRequestError, RequestTimeoutError } from './rpc/jsonRpcClient.js'
 import { ContentReadGate } from './contentGate.js'
+import { truncateErrorMessage } from './diagnostics.js'
 import type { ReadResult, SessionSubscriptions } from './subscriptions.js'
 import { PairingError } from './pairing.js'
 import type { PairingErrorKind } from './pairing.js'
@@ -299,12 +300,81 @@ export interface CherryReadPart {
   byteLength?: string
 }
 
+/**
+ * The peer's verdict on a FAILED message, narrowed to what a caller can act on.
+ *
+ * The wire carries more (`failure.failure.source`, `context.responseBody`, the
+ * provider's status code); none of it is projected. `cherry_read` is a text
+ * channel for the conversation, and the provider's raw error body is neither
+ * conversation nor the caller's business — the peer already classified the
+ * cause into `reasonCode`, which is the actionable half.
+ */
+export interface CherryReadFailure {
+  /**
+   * The peer's classification (`provider_unavailable`, `rate_limit`,
+   * `context_length`, … — the protocol's versioned vocabulary).
+   *
+   * Relayed as a SHAPE-checked string rather than matched against a closed
+   * enum: the vocabulary belongs to the peer and grows with it, and relabelling
+   * a new code `'unknown'` would hide a real cause behind a value that means
+   * "the peer could not classify". Absent or unusable values become
+   * `'unknown'`, which is exactly what the contract uses for that case.
+   */
+  reasonCode: string
+  /** Whether the peer judged a retry of the same work worthwhile. */
+  retryable: boolean
+  /**
+   * The peer's one-line explanation, bounded by the diagnostics error cap
+   * (200 characters) with a `…[truncated]` marker when it was cut.
+   */
+  message: string
+}
+
+/** `provider_unavailable`-shaped: lowercase words separated by underscores. */
+const REASON_CODE_SHAPE = /^[a-z][a-z0-9_]{1,63}$/
+
+/**
+ * Projects the wire's `failure` object (present on `status: 'error'` messages)
+ * into {@link CherryReadFailure}, or `undefined` when there is none.
+ *
+ * Deliberately tolerant of a malformed payload: a peer that sends
+ * `failure: { retryable: false }` with no nested record still yields a usable
+ * verdict (`reasonCode: 'unknown'`, empty message) instead of failing the whole
+ * read — the message's TEXT is already in hand, and losing it over a metadata
+ * field would trade the content for the annotation. A degenerate object
+ * (`{}`, `[]`) projects the same way: the peer DID attach a verdict, just an
+ * empty one, and saying so is more honest than reporting "no verdict". Only an
+ * ABSENT or non-object `failure` yields `undefined`.
+ */
+export function projectMessageFailure(raw: Record<string, unknown>): CherryReadFailure | undefined {
+  const failure = raw['failure']
+  if (typeof failure !== 'object' || failure === null) return undefined
+  const record = failure as Record<string, unknown>
+  const nested = record['failure']
+  const detail = typeof nested === 'object' && nested !== null ? (nested as Record<string, unknown>) : {}
+  const rawReason = detail['reasonCode']
+  const reasonCode =
+    typeof rawReason === 'string' && REASON_CODE_SHAPE.test(rawReason) ? rawReason : 'unknown'
+  const rawMessage = record['message']
+  return {
+    reasonCode,
+    retryable: record['retryable'] === true,
+    message: truncateErrorMessage(typeof rawMessage === 'string' ? rawMessage : ''),
+  }
+}
+
 /** One message in a `cherry_read` snapshot. */
 export interface CherryReadMessage {
   messageId: string
   revision: string
   role: string
   status: string
+  /**
+   * Present exactly when the peer sent a `failure` for this message (in
+   * practice: `status: 'error'`). A successful message never carries it, so a
+   * caller can test for the key rather than compare `status` strings.
+   */
+  failure?: CherryReadFailure
   parts: CherryReadPart[]
   /**
    * Present only when this message's parts could NOT all be read: the safety
@@ -1215,6 +1285,87 @@ function withIdempotencyHint(error: unknown): unknown {
   return error
 }
 
+/**
+ * The phrase this hint leaves behind, so applying it twice reads once. A phrase
+ * from the ADVICE rather than the advice itself, because the wait clause varies
+ * with the peer's `retryAfterMs`; matching the peer's own text would match every
+ * rate-limit refusal, hinted or not.
+ */
+const RATE_LIMIT_HINT_MARK = 'refuses BEFORE dispatch'
+
+/**
+ * How long a refused COMMAND was asked to wait, or undefined when the peer sent
+ * nothing a caller can act on.
+ *
+ * `<= 0` counts as absent rather than "retry immediately": a zero delay is
+ * noise in an error message, and the desktop clamps its own value to `>= 1`
+ * (`RemoteAccessService.ts`). CEILED so a fractional remainder is never
+ * reported as a delay shorter than the one the peer asked for.
+ */
+function rateLimitedWaitMs(error: Error): number | undefined {
+  if (!(error instanceof JsonRpcRequestError)) return undefined
+  const data = error.data
+  if (!isRecord(data)) return undefined
+  const raw = data['retryAfterMs']
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw <= 0) return undefined
+  return Math.ceil(raw)
+}
+
+/**
+ * The recovery advice appended to a command's `RATE_LIMITED` refusal (desktop
+ * >= 2.1.7; see the transport-loss section of `connection.ts`), issue #109.
+ *
+ * Two facts decide the retry and NEITHER survives the tool boundary on its own:
+ *
+ *  - **THIS attempt was not applied.** The desktop refuses BEFORE dispatch — its
+ *    gateway calls `remote.rpc.refuse(input, …)` INSTEAD of `receive(input)` —
+ *    so, unlike a reply lost on a dead link, this is a certain non-outcome.
+ *    That is what makes a retry safe, and it is why the SAME `commandId` may be
+ *    reused: nothing reached the peer's command ledger, so no
+ *    `IDEMPOTENCY_CONFLICT` is waiting for the retry. The sentence says THIS
+ *    attempt, not "the command", because an earlier attempt under the same
+ *    `commandId` may itself have lost its reply after dispatch: the retry advice
+ *    is right in that sequence too (the ledger replays the original receipt),
+ *    but "never landed" would be a claim about a run this error knows nothing
+ *    of.
+ *  - **How long the peer asked us to wait** — `retryAfterMs`, derived from its
+ *    own 1 s window and already on the error we are holding. The wait clause
+ *    comes BEFORE the retry blessing, so a skimming reader cannot take "safe to
+ *    retry" and act on it without waiting.
+ *
+ * The cause is named because at the DEFAULT pacing this refusal is unreachable:
+ * the desktop's counter is per SOCKET (locals inside its `run()` loop, one per
+ * accepted connection) and we pace 32/s shared / 256/s content against its
+ * 64-or-256/s shared and 512/s content lines. Seeing one at all therefore
+ * normally means the configured budget is above the peer's allowance — the knob
+ * to look at, not a transient blip — and a caller told to "retry later" without
+ * that pointer would keep retrying into the same wall. Only the 256/s figure is
+ * quoted: this refusal exists only from 2.1.7, so the older 64/s line cannot be
+ * the one an operator has to compare against.
+ *
+ * Like {@link withIdempotencyHint} this only ever EXTENDS `message`: the reason,
+ * the `data` and the `JsonRpcRequestError` identity are the peer's, and one
+ * command is still never replayed (the advice is for the CALLER's retry).
+ */
+export function withRateLimitHint(error: unknown): unknown {
+  if (!(error instanceof Error)) return error
+  if (failureReason(error) !== 'RATE_LIMITED') return error
+  if (error.message.includes(RATE_LIMIT_HINT_MARK)) return error
+  const waitMs = rateLimitedWaitMs(error)
+  const advice = [
+    'this attempt was not applied: the desktop refuses BEFORE dispatch, so nothing reached its ' +
+      'command ledger',
+    waitMs === undefined
+      ? 'A retry is safe, and it may reuse the SAME commandId'
+      : `Wait about ${waitMs} ms first (the peer's retryAfterMs); a retry is then safe, and it may ` +
+        'reuse the SAME commandId',
+    'The default budget (32/s) does not come close to the desktop\'s allowance, so a refusal ' +
+      'normally means `rateBudgetPerSecond` was raised too far (2.1.7+ allows 256/s shared)',
+  ]
+  error.message = `${error.message} — ${advice.join('. ')}.`
+  return error
+}
+
 function optionalString(value: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined
 }
@@ -2450,7 +2601,11 @@ class CherryToolEngine {
         'are deliberately not fetched into a text channel. Messages come NEWEST-first, so the ' +
         'first entry is the latest and `limit` drops the OLDEST messages — truncation never cuts ' +
         'inside a retained message\'s parts; a message whose own parts could not be fully read ' +
-        'carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. The ' +
+        'carries `incomplete`, and may carry `unavailableParts` when parts were unreadable. A ' +
+        'failed message (`status: "error"`) may carry `failure: {reasonCode, retryable, ' +
+        'message}` when the peer sent one — its classification, whether it judged a retry ' +
+        'worthwhile, and a bounded summary; the peer\'s `source` and `context.responseBody` ' +
+        'are never projected. The ' +
         'answer is ALSO bounded by an output budget: `truncated` with `truncationReason: ' +
         '"aggregate-bytes"` means the walk stopped because the result reached its size limit, ' +
         'not because `limit` was reached — raising `limit` does NOT reach the messages left out ' +
@@ -2779,11 +2934,13 @@ class CherryToolEngine {
     // stays absent rather than claiming a zero.
     const unavailableParts = parts.filter((part) => part.unavailable !== undefined).length
     const incomplete = unavailableParts > 0 || partsTruncated !== undefined
+    const failure = projectMessageFailure(raw)
     return {
       messageId,
       revision,
       role: String(raw['role'] ?? ''),
       status: String(raw['status'] ?? ''),
+      ...(failure === undefined ? {} : { failure }),
       parts,
       // A circuit-broken part list advertises itself: the caller can see that
       // this message is incomplete and that later parts are still unread, so
@@ -2967,13 +3124,23 @@ class CherryToolEngine {
    *    back a snapshot that looks complete while containing content the peer
    *    never certified. That is worse than an error: the caller cannot tell it
    *    apart from a good read. It keeps failing loudly.
+   *  - **NOT degradable — a RATE LIMIT.** A `RATE_LIMITED` refusal is
+   *    SESSION-wide, not part-specific: the peer refused the arrival, it did not
+   *    fail to serve THIS part. Degrading would hand back a "complete" message
+   *    whose text is empty for a reason the caller could act on (wait and ask
+   *    again) — and if one slice is refused the others will be too, so the
+   *    snapshot would be missing precisely what was requested. The connection
+   *    already waited out `retryAfterMs` and replayed the slice ONCE, so a
+   *    second refusal is a real failure and the whole read fails with it.
    *
    * The discriminator is the DIGEST CHECK specifically, which is why
    * {@link CherryToolEngine.#readExternalized} marks it: matching on message
-   * text would break the moment the wording changed.
+   * text would break the moment the wording changed. The rate-limit arm keys on
+   * the peer's REASON, never on wording.
    */
   #degradableReadFailure(error: unknown): boolean {
-    return !(error instanceof ContentIntegrityError)
+    if (error instanceof ContentIntegrityError) return false
+    return failureReason(error) !== 'RATE_LIMITED'
   }
 
   /**
@@ -4330,12 +4497,12 @@ class CherryToolEngine {
    * subscription failures still reject this call: the two surfaces stay
    * distinct all the way to the caller (spec §6).
    *
-   * ONE exception, and it is a HINT rather than a translation: the peer's
+   * TWO exceptions, and both are HINTS rather than translations: the peer's
    * `IDEMPOTENCY_CONFLICT` — the same `commandId` re-used with a DIFFERENT body
-   * — carries the §6 recovery advice on the rethrown error (see
-   * {@link withIdempotencyHint}). The reason, the `data` and the failure
-   * currency are untouched; only the prose a caller reads grows the actionable
-   * half.
+   * — and its `RATE_LIMITED` refusal (desktop >= 2.1.7) each carry their
+   * recovery advice on the rethrown error (see {@link withIdempotencyHint} /
+   * {@link withRateLimitHint}). The reason, the `data` and the failure currency
+   * are untouched; only the prose a caller reads grows the actionable half.
    */
   async #command(
     connection: DeviceConnection,
@@ -4345,7 +4512,7 @@ class CherryToolEngine {
     try {
       return (await connection.rpc.request(method, params)) as Record<string, unknown>
     } catch (error) {
-      throw withIdempotencyHint(error)
+      throw withRateLimitHint(withIdempotencyHint(error))
     }
   }