@crossworks/voice-client 0.300.46 → 0.300.48

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crossworks/voice-client",
3
- "version": "0.300.46",
3
+ "version": "0.300.48",
4
4
  "description": "Browser-safe surface of the voice/model layer — provider catalogue, model catalogs, audio tags, and the adapter type/metadata contract. Zero deps by design: nothing here may reach the network adapters or node builtins (the jackdaw-repo-split P0 boundary).",
5
5
  "exports": {
6
6
  ".": "./src/index.ts",
@@ -22,7 +22,6 @@ import type {
22
22
  TtsDispatcher,
23
23
  VisionDispatcher,
24
24
  } from './types';
25
- import { withChatRetry } from './retry';
26
25
 
27
26
  const CHAT = new Map<ProviderId, ChatDispatcher>();
28
27
  const TTS = new Map<ProviderId, TtsDispatcher>();
@@ -102,15 +101,14 @@ export function registerChatAdapter(adapter: ChatDispatcher): void {
102
101
  CHAT.set(adapter.providerId, adapter);
103
102
  }
104
103
 
105
- export function getChatAdapter(providerId: string): ChatDispatcher | null {
106
- const adapter = CHAT.get(providerId as ProviderId) ?? null;
107
- if (!adapter) return null;
108
- // OpenRouter's SDK already retries transient errors internally; wrapping it
109
- // would compound attempt counts. The native-fetch adapters (anthropic /
110
- // google / xai / huggingface / deepseek) have no retry of their own, so wrap
111
- // those once here for uniform 429/5xx/network/timeout backoff.
112
- if (adapter.providerId === 'openrouter') return adapter;
113
- return withChatRetry(adapter);
104
+ /**
105
+ * The chat adapter as registered, WITHOUT the retry wrapper. Callers use
106
+ * `getChatAdapter` from @mantle/voice, which wraps the native-fetch adapters
107
+ * in withChatRetry (A10 #10 moved the retry out of this zero-dependency
108
+ * contract package, to sit on @mantle/std's withRetry).
109
+ */
110
+ export function registeredChatAdapter(providerId: string): ChatDispatcher | null {
111
+ return CHAT.get(providerId as ProviderId) ?? null;
114
112
  }
115
113
 
116
114
  export function listChatAdapters(): ChatDispatcher[] {
package/src/index.ts CHANGED
@@ -35,8 +35,8 @@ export * from './catalogs/assemblyai';
35
35
  export * from './catalogs/deepseek';
36
36
  export * from './catalogs/mammouth';
37
37
 
38
- // Pure wiring metadata (no adapter modules pulled — registry.ts only imports
39
- // the retry helper, which is itself dependency-free).
38
+ // Pure wiring metadata (no adapter modules pulled: registry.ts imports types
39
+ // only).
40
40
  export { isProviderWired, wiredCapabilitiesFor, WIRED_PROVIDERS } from './adapters/registry';
41
41
  export type { WiredCapability } from './adapters/registry';
42
42
 
@@ -1,237 +0,0 @@
1
- /**
2
- * Retry/backoff for the chat dispatch path.
3
- *
4
- * The native-fetch chat adapters (anthropic / google / xai / huggingface /
5
- * deepseek) were each a single `fetch` that threw on the first non-OK
6
- * response — so a momentary 429 or 503 on ANY tool-loop iteration aborted the
7
- * whole turn (the responder dropped the inbound message; a multi-iteration
8
- * tool run lost all prior work). Only OpenRouter had resilience, via its SDK's
9
- * built-in retries.
10
- *
11
- * `withChatRetry` wraps a ChatDispatcher so the direct-provider adapters get
12
- * uniform, configurable retry on transient errors (429, 408/409/425, 5xx,
13
- * network blips, and the adapters' own 60s fetch timeout) with exponential
14
- * backoff + jitter, honoring `Retry-After` when the provider sends it. It is
15
- * applied once at the `getChatAdapter` registry boundary, so every chat call
16
- * site (responder, web assistant, extractor, summarizer, reflector,
17
- * heartbeats, invoke_agent) is covered without opting in.
18
- *
19
- * OpenRouter is intentionally NOT wrapped — its SDK already retries, and
20
- * double-wrapping would compound attempt counts. See registry.getChatAdapter.
21
- */
22
- import type { ChatDispatcher, ChatOptions, ChatResult, ChatStreamSink } from './types';
23
-
24
- /** Default attempts AFTER the first try (so 2 ⇒ up to 3 total calls). */
25
- export const DEFAULT_MAX_RETRIES = 2;
26
- const DEFAULT_BASE_DELAY_MS = 500;
27
- const DEFAULT_MAX_DELAY_MS = 8_000;
28
- /** Cap an honored Retry-After so a pathological header can't stall a turn. */
29
- const RETRY_AFTER_CAP_MS = 30_000;
30
-
31
- /** Transient HTTP statuses worth retrying. */
32
- const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
33
-
34
- /**
35
- * Structured error the native-fetch chat adapters throw on a non-OK response.
36
- * Carries the status + parsed Retry-After so the retry wrapper can decide
37
- * cleanly (no message parsing). The `message` is byte-identical to the plain
38
- * `Error` the adapters threw before (`<provider> chat <status>: <body…>`), so
39
- * existing wire-shape tests and log scrapers are unaffected.
40
- */
41
- export class ChatHttpError extends Error {
42
- readonly provider: string;
43
- readonly status: number;
44
- readonly retryAfterMs?: number;
45
- readonly body?: string;
46
- constructor(opts: { provider: string; status: number; body?: string; retryAfterMs?: number }) {
47
- super(`${opts.provider} chat ${opts.status}: ${(opts.body ?? '').slice(0, 400)}`);
48
- this.name = 'ChatHttpError';
49
- this.provider = opts.provider;
50
- this.status = opts.status;
51
- this.retryAfterMs = opts.retryAfterMs;
52
- this.body = opts.body;
53
- }
54
- }
55
-
56
- /**
57
- * Parse a `Retry-After` header (RFC 7231: delta-seconds or HTTP-date) into ms.
58
- * Returns undefined when absent/unparseable.
59
- */
60
- export function parseRetryAfterMs(headers?: Headers | null): number | undefined {
61
- // Defensive `?.get?.` — real `fetch` always gives a Headers, but tests (and
62
- // some mocked transports) hand back a plain object with no headers.
63
- const raw = headers?.get?.('retry-after');
64
- if (!raw) return undefined;
65
- const secs = Number(raw);
66
- if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
67
- const when = Date.parse(raw);
68
- if (Number.isFinite(when)) return Math.max(0, when - Date.now());
69
- return undefined;
70
- }
71
-
72
- /**
73
- * An empty or truncated 2xx body that `JSON.parse` choked on — the signature of
74
- * an upstream timeout / dropped connection that still returned 200 (or a cut-off
75
- * stream). Transient: the same request usually succeeds on retry. (Caught in
76
- * prod: a 16-step assistant turn died here after a 34s upstream stall returned
77
- * an empty body — see openrouter-chat.ts.)
78
- *
79
- * We match only the families that CANNOT arise from a complete payload, because
80
- * a complete-but-invalid body is a genuine bug we must not mask behind retries:
81
- *
82
- * - "Unexpected end of JSON input" — `''`, whitespace, or input ending where
83
- * a value was expected. Always truncation.
84
- * - "Unterminated string in JSON" — a string opened and never closed. Only
85
- * reachable by running out of input.
86
- *
87
- * Deliberately NOT matched: `Expected ',' or '}' after property value…`,
88
- * `Expected ':' after property name…`, `Expected property name or '}'…`. Those
89
- * fire for BOTH a mid-object truncation and a malformed-but-complete body, and
90
- * the message alone cannot tell them apart — only the byte offset versus the
91
- * body length could, which this signature doesn't receive. Retrying a real
92
- * malformed payload would turn one loud bug into three silent ones.
93
- *
94
- * ⚠️ The message strings are V8's, and V8 has changed them before: this used to
95
- * claim it covered truncation generally, which was true on older Node where
96
- * every cut-off body said "Unexpected end of JSON input". Modern V8 emits
97
- * specific messages per failure shape, so that claim had quietly become false
98
- * for most truncations. The tests below parse REAL malformed JSON rather than
99
- * asserting hand-written message strings, so the next V8 wording change fails
100
- * them instead of silently narrowing this again.
101
- */
102
- export function isEmptyJsonBodyError(err: unknown): boolean {
103
- if (!(err instanceof SyntaxError)) return false;
104
- return (
105
- /unexpected end of (json )?input/i.test(err.message) ||
106
- /unterminated string in json/i.test(err.message)
107
- );
108
- }
109
-
110
- /** Decide whether an adapter error is worth retrying, and after how long. */
111
- export function classifyChatError(err: unknown): {
112
- retry: boolean;
113
- retryAfterMs?: number;
114
- } {
115
- if (err instanceof ChatHttpError) {
116
- return { retry: RETRYABLE_STATUS.has(err.status), retryAfterMs: err.retryAfterMs };
117
- }
118
- // Defensive: any error exposing a numeric HTTP status (e.g. an SDK error).
119
- const status = (err as { status?: unknown } | null)?.status;
120
- if (typeof status === 'number') return { retry: RETRYABLE_STATUS.has(status) };
121
- // The adapters' own `AbortSignal.timeout(60_000)` fires a TimeoutError; a
122
- // bare AbortError is USUALLY that timeout too — but since the Stop wiring,
123
- // ChatOptions CAN carry a caller-supplied signal (a user Stop), and
124
- // retrying against an aborted signal just burns backoff sleeps.
125
- // `withChatRetry` short-circuits that case (it can see the signal; this
126
- // classifier only sees the error). What reaches here is transient — retry.
127
- const name = (err as { name?: string } | null)?.name;
128
- if (name === 'TimeoutError' || name === 'AbortError') return { retry: true };
129
- // Raw fetch network failures surface as TypeError ("fetch failed", ECONNRESET,
130
- // DNS, …). The wrapper only guards a network call, so this is a blip — retry.
131
- if (err instanceof TypeError) return { retry: true };
132
- // Empty/truncated JSON body — an upstream stall that returned no parseable
133
- // payload. Transient, and not covered by the status/network checks above.
134
- if (isEmptyJsonBodyError(err)) return { retry: true };
135
- const msg = String((err as { message?: unknown } | null)?.message ?? '');
136
- if (/fetch failed|ECONNRESET|ETIMEDOUT|EAI_AGAIN|socket hang up/i.test(msg)) {
137
- return { retry: true };
138
- }
139
- return { retry: false };
140
- }
141
-
142
- function describeError(err: unknown): string {
143
- if (err instanceof ChatHttpError) return `HTTP ${err.status}`;
144
- if (isEmptyJsonBodyError(err)) return 'empty/truncated response';
145
- const name = (err as { name?: string } | null)?.name;
146
- return name && name !== 'Error' ? name : 'network error';
147
- }
148
-
149
- export interface ChatRetryConfig {
150
- maxRetries?: number;
151
- baseDelayMs?: number;
152
- maxDelayMs?: number;
153
- }
154
-
155
- /** One attempt loop shared by the one-shot and streaming wrappers. `run` is
156
- * called per attempt; `mayRetry` lets the streaming path veto a replay once
157
- * output has already reached the user. */
158
- async function attemptWithRetry<T>(
159
- adapter: ChatDispatcher,
160
- opts: ChatOptions,
161
- config: ChatRetryConfig,
162
- run: () => Promise<T>,
163
- mayRetry: () => boolean,
164
- ): Promise<T> {
165
- const base = config.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
166
- const max = config.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
167
- const maxRetries = opts.maxRetries ?? config.maxRetries ?? DEFAULT_MAX_RETRIES;
168
- let attempt = 0;
169
- for (;;) {
170
- try {
171
- return await run();
172
- } catch (err) {
173
- // A caller-aborted signal (user Stop) is not transient: every retry
174
- // would abort identically after a pointless backoff sleep. Surface it
175
- // immediately — the tool loop / run-turn recognise the stop.
176
- if (opts.signal?.aborted) throw err;
177
- if (!mayRetry()) throw err;
178
- const { retry, retryAfterMs } = classifyChatError(err);
179
- if (!retry || attempt >= maxRetries) throw err;
180
- attempt += 1;
181
- const delay =
182
- retryAfterMs != null
183
- ? Math.min(retryAfterMs, RETRY_AFTER_CAP_MS)
184
- : Math.round(Math.random() * Math.min(max, base * 2 ** (attempt - 1)));
185
- console.warn(
186
- `[chat-retry] ${adapter.adapterName} ${opts.model}: ${describeError(err)} — retry ${attempt}/${maxRetries} in ${delay}ms`,
187
- );
188
- await new Promise((resolve) => setTimeout(resolve, delay));
189
- }
190
- }
191
- }
192
-
193
- /**
194
- * Wrap a ChatDispatcher with retry/backoff on its `chat` AND `chatStream`
195
- * calls. Per-call `opts.maxRetries` overrides the config default; 0 disables.
196
- * All other dispatcher members (providerId, adapterName, discoverModels,
197
- * staticCatalog) are preserved unchanged.
198
- *
199
- * Streaming is retried only while nothing has reached the user yet: a 429, a
200
- * 5xx, a network blip or a connect timeout before the first delta re-sends the
201
- * request exactly like the one-shot path. Once a delta has been emitted the
202
- * error surfaces as-is — replaying would repeat text the client already
203
- * rendered, and the adapters already return the partial on a user Stop.
204
- * (Before 2026-09-02 only `chat` was wrapped; the tool loop prefers
205
- * `chatStream` whenever a turn is live, so live turns had no retry at all.)
206
- */
207
- export function withChatRetry(
208
- adapter: ChatDispatcher,
209
- config: ChatRetryConfig = {},
210
- ): ChatDispatcher {
211
- const chat = (opts: ChatOptions): Promise<ChatResult> =>
212
- attemptWithRetry(
213
- adapter,
214
- opts,
215
- config,
216
- () => adapter.chat(opts),
217
- () => true,
218
- );
219
- const inner = adapter.chatStream?.bind(adapter);
220
- const chatStream = inner
221
- ? (opts: ChatOptions, onDelta: ChatStreamSink): Promise<ChatResult> => {
222
- let emitted = false;
223
- const sink: ChatStreamSink = (delta) => {
224
- emitted = true;
225
- onDelta(delta);
226
- };
227
- return attemptWithRetry(
228
- adapter,
229
- opts,
230
- config,
231
- () => inner(opts, sink),
232
- () => !emitted,
233
- );
234
- }
235
- : undefined;
236
- return { ...adapter, chat, ...(chatStream ? { chatStream } : {}) };
237
- }