@beeos-ai/bma-dsh-adapter 0.3.0 → 0.3.1

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/README.md CHANGED
@@ -11,7 +11,7 @@ BMA 的共享 DSH 适配层(Apache-2.0)。把 [DSH](https://www.npmjs.com/or
11
11
  | `recovery.ts` + `adapter.ts` | JSONL resume(无日志 → `SessionNotFoundError`)、按 input id 幂等(已记录的输入只发续跑提示) | 一致性套件 resume |
12
12
  | `stop.ts` + `spi.ts` | 停止原因映射:`output_limit_reached` / `context_too_large` / `model_stream_idle`(`TurnStopError`,消息以 `<code>: ` 开头),其余通用失败;`AGENT_ERROR_CODES` / `agentErrorCode` 对应执行端契约码表(`contracts/bma/schemas/agent.json` `AgentErrorCode`) | 一致性套件 stop reasons、`stop-contract.test.ts`、`model-limits.test.ts` |
13
13
  | `system-prompt.ts` | `BASE_SYSTEM_PROMPT` + `composeSystemPrompt(agentSystem?)`:所有外壳在这里拼系统提示,不自己写死 | 一致性套件 system prompt、`system-prompt.test.ts` |
14
- | `model.ts`、`model-catalog.ts` | OpenAI Chat 适配器:按模型取 max_tokens / 窗口(声明 > 目录文件 > 保守默认,记录)、图片 `image_url`、流空闲守卫(首个内容增量前空闲:退避 1–2 s 自动重试 1 次,已有内容后不重试) | `model-limits.test.ts` |
14
+ | `model.ts`、`model-catalog.ts` | OpenAI Chat 适配器:按模型取 max_tokens / 窗口(声明 > 目录文件 > 保守默认,记录)、图片 `image_url`、流空闲守卫(首个内容增量前空闲:退避 1–2 s 自动重试 1 次,已有内容后不重试)、暂时性失败重试(首个内容增量前遇到 HTTP 502/503/504、错误体 `retryable: true` 或响应前连接失败:最多重试 2 次,退避从 0.5 s 翻倍、上限 8 s、减最多 25% 抖动,同官方 OpenAI / Anthropic SDK;服务端给了 `retry-after-ms` / `Retry-After` 且比退避长时按它等,超过 8 s 则不等、直接失败;已有内容后不重试;宿主经 `ModelPort.transientRetry` 计数记日志,原因只含状态码和错误码,不含响应体和令牌) | `model-limits.test.ts` |
15
15
  | `spi.ts` | `HarnessAdapter` / `ModelPort` / `PlatformTool` 契约(harness 无关) | — |
16
16
 
17
17
  审批的等待逻辑(interaction.request/response、停机时保持打开)属于宿主的通道,留在宿主里。
package/lib/adapter.d.ts CHANGED
@@ -9,6 +9,8 @@ export interface DshAdapterOptions {
9
9
  streamIdleMs?: number;
10
10
  /** Pause range (ms) before the one retry of a stream that idled before any content; default 1000..2000. */
11
11
  idleRetryBackoffMs?: readonly [number, number];
12
+ /** [first, cap] (ms) of the backoff before a transient retry (502/503/504, retryable, connection); default 500..8000. */
13
+ transientRetryBackoffMs?: readonly [number, number];
12
14
  }
13
15
  export declare class DshAdapter implements HarnessAdapter {
14
16
  readonly id = "dsh";
@@ -18,6 +20,7 @@ export declare class DshAdapter implements HarnessAdapter {
18
20
  private tools;
19
21
  private readonly streamIdleMs;
20
22
  private readonly idleRetryBackoffMs;
23
+ private readonly transientRetryBackoffMs;
21
24
  private port;
22
25
  private readonly toolImages;
23
26
  private constructor();
package/lib/adapter.js CHANGED
@@ -26,16 +26,18 @@ export class DshAdapter {
26
26
  tools = [];
27
27
  streamIdleMs;
28
28
  idleRetryBackoffMs;
29
+ transientRetryBackoffMs;
29
30
  port;
30
31
  toolImages = new RecentToolImages();
31
- constructor(ctx, streamIdleMs, idleRetryBackoffMs) {
32
+ constructor(ctx, streamIdleMs, idleRetryBackoffMs, transientRetryBackoffMs) {
32
33
  this.ctx = ctx;
33
34
  this.streamIdleMs = streamIdleMs;
34
35
  this.idleRetryBackoffMs = idleRetryBackoffMs;
36
+ this.transientRetryBackoffMs = transientRetryBackoffMs;
35
37
  }
36
38
  static async mount(options) {
37
39
  const ctx = await mountKernel({ home: options.home, ...(options.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: options.maxParallelToolCalls } : {}) });
38
- return new DshAdapter(ctx, options.streamIdleMs ?? DEFAULT_STREAM_IDLE_MS, options.idleRetryBackoffMs);
40
+ return new DshAdapter(ctx, options.streamIdleMs ?? DEFAULT_STREAM_IDLE_MS, options.idleRetryBackoffMs, options.transientRetryBackoffMs);
39
41
  }
40
42
  capabilities() {
41
43
  return { resume: true, deltas: true, midTurnInput: true, imageInput: true };
@@ -46,6 +48,7 @@ export class DshAdapter {
46
48
  this.ctx.llm.registerAdapter([PROVIDER], new ChatCompletionsAdapter(port, {
47
49
  streamIdleMs: this.streamIdleMs,
48
50
  ...(this.idleRetryBackoffMs ? { idleRetryBackoffMs: this.idleRetryBackoffMs } : {}),
51
+ ...(this.transientRetryBackoffMs ? { transientRetryBackoffMs: this.transientRetryBackoffMs } : {}),
49
52
  toolImages: (sessionId, callId) => this.toolImages.get(sessionId, callId),
50
53
  readImage: async (block, signal) => {
51
54
  const image = await attachments.readImageRequest(block.attachment, REQUEST_IMAGE_TARGET, signal);
@@ -125,7 +125,7 @@ export function registerConformance(name, factory, options = {}) {
125
125
  await run(adapter, "sesn_can", "in_1", "x", ctl.signal);
126
126
  assert.ok(Date.now() - started < 5_000);
127
127
  });
128
- test(`[conformance:${name}] stop reasons: output limit, context overflow and stream idle are typed; a model failure is generic`, async (t) => {
128
+ test(`[conformance:${name}] stop reasons: output limit, context overflow, stream idle and a refused model request are typed`, async (t) => {
129
129
  const typed = (code) => (err) => err instanceof TurnStopError && err.code === code && err.message.startsWith(`${code}: `);
130
130
  const cut = await mount(t, { script: () => ({ text: "cut off", finishReason: "length" }) });
131
131
  await cut.adapter.createSession(init("sesn_s1"));
@@ -150,6 +150,6 @@ export function registerConformance(name, factory, options = {}) {
150
150
  assert.equal(idle.model.requests.length, 1, "content had arrived: not retried");
151
151
  const failed = await mount(t, { script: () => ({ status: 401 }) });
152
152
  await failed.adapter.createSession(init("sesn_s4"));
153
- await assert.rejects(run(failed.adapter, "sesn_s4", "in_1", "x"), (err) => !(err instanceof TurnStopError));
153
+ await assert.rejects(run(failed.adapter, "sesn_s4", "in_1", "x"), typed("model_request_failed_error"));
154
154
  });
155
155
  }
package/lib/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export * from "./spi.ts";
2
2
  export { DshAdapter, type DshAdapterOptions } from "./adapter.ts";
3
3
  export { mountKernel, COMPACTION_HEADROOM_TOKENS, COMPACTION_SUMMARY_MAX_TOKENS, type KernelOptions } from "./kernel.ts";
4
- export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, MODEL_STREAM_IDLE, PROVIDER, RecentToolImages, TOOL_IMAGE_CALLS, type ModelAdapterOptions, type RequestImage } from "./model.ts";
4
+ export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, DEFAULT_TRANSIENT_RETRY_BACKOFF_MS, MODEL_CONNECTION, MODEL_STREAM_IDLE, TRANSIENT_RETRIES, transientBackoffMs, retryAfterMs, PROVIDER, RecentToolImages, TOOL_IMAGE_INTERVAL, TOOL_IMAGE_KEEP, type ModelAdapterOptions, type RequestImage } from "./model.ts";
5
5
  export { ModelCatalog, DEFAULT_LIMITS, DEFAULT_REQUEST_MAX_TOKENS, requestMaxTokens, loadCatalogFile, parseLimits, type CatalogDefaults, type LimitsInput } from "./model-catalog.ts";
6
6
  export { restrictToPlatformTools, catalogViolation } from "./catalog-gate.ts";
7
7
  export { harnessEventsFromSessionEvent, harnessEventFromStreamFrame, cmaMessageEvent, cmaEventType, type CmaMessageEventType } from "./events.ts";
package/lib/index.js CHANGED
@@ -2,7 +2,7 @@
2
2
  export * from "./spi.js";
3
3
  export { DshAdapter } from "./adapter.js";
4
4
  export { mountKernel, COMPACTION_HEADROOM_TOKENS, COMPACTION_SUMMARY_MAX_TOKENS } from "./kernel.js";
5
- export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, MODEL_STREAM_IDLE, PROVIDER, RecentToolImages, TOOL_IMAGE_CALLS } from "./model.js";
5
+ export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, DEFAULT_TRANSIENT_RETRY_BACKOFF_MS, MODEL_CONNECTION, MODEL_STREAM_IDLE, TRANSIENT_RETRIES, transientBackoffMs, retryAfterMs, PROVIDER, RecentToolImages, TOOL_IMAGE_INTERVAL, TOOL_IMAGE_KEEP } from "./model.js";
6
6
  export { ModelCatalog, DEFAULT_LIMITS, DEFAULT_REQUEST_MAX_TOKENS, requestMaxTokens, loadCatalogFile, parseLimits } from "./model-catalog.js";
7
7
  export { restrictToPlatformTools, catalogViolation } from "./catalog-gate.js";
8
8
  export { harnessEventsFromSessionEvent, harnessEventFromStreamFrame, cmaMessageEvent, cmaEventType } from "./events.js";
package/lib/model.d.ts CHANGED
@@ -3,6 +3,8 @@ import type { ModelPort } from "./spi.ts";
3
3
  export declare const PROVIDER = "bma";
4
4
  /** Error code of a model stream that sent no data for the idle limit (typed stop model_stream_idle). */
5
5
  export declare const MODEL_STREAM_IDLE = "MODEL_STREAM_IDLE";
6
+ /** Error code of a model request whose connection failed before any response (refused, reset, DNS). */
7
+ export declare const MODEL_CONNECTION = "MODEL_CONNECTION";
6
8
  /** One image as the request carries it. */
7
9
  export interface RequestImage {
8
10
  mediaType: string;
@@ -16,18 +18,26 @@ export interface ModelAdapterOptions {
16
18
  readImage: (block: ImageBlock, signal?: AbortSignal) => Promise<RequestImage>;
17
19
  /** Pause before the one idle retry, uniform in [min, max] ms; default DEFAULT_IDLE_RETRY_BACKOFF_MS. */
18
20
  idleRetryBackoffMs?: readonly [number, number];
21
+ /** [first, cap] of the transient retry backoff in ms; default DEFAULT_TRANSIENT_RETRY_BACKOFF_MS. */
22
+ transientRetryBackoffMs?: readonly [number, number];
19
23
  /** The images of a tool result the model still sees (RecentToolImages), by session and call. */
20
24
  toolImages?: (sessionId: string, callId: string) => readonly RequestImage[] | undefined;
21
25
  }
22
26
  /**
23
- * Tool result images (computer_observe screenshots) are kept in memory for the
24
- * most recent TOOL_IMAGE_CALLS calls of a session and sent with those results
25
- * only; older ones, and all of them after a restart, are left out (the result
26
- * text stays). Basis: Anthropic's computer-use reference loop keeps only the N
27
- * most recent screenshots in the request (only_n_most_recent_images, default
28
- * 3) — screenshots are large and only the latest describe the screen.
27
+ * Tool result images (computer_observe screenshots) are kept in memory per
28
+ * session and sent with their results; pruned ones, and all of them after a
29
+ * restart, are left out (the result text stays). Pruning is in batches: once
30
+ * more than TOOL_IMAGE_KEEP + TOOL_IMAGE_INTERVAL calls have images, the oldest
31
+ * TOOL_IMAGE_INTERVAL drop out together, so the request prefix stays
32
+ * byte-identical between two such steps and the provider's prompt cache keeps
33
+ * hitting (a sliding window changes the prefix on every request). Same rule as
34
+ * the Go brain (server/gobrain/application/toolimages.go), shared vectors
35
+ * test/brain-conformance/tool-image-pruning.vectors.json. Basis: Anthropic,
36
+ * "Best practices for computer and browser use with Claude" (rolling buffer,
37
+ * cache-aware: keep_n = 3, interval = 25).
29
38
  */
30
- export declare const TOOL_IMAGE_CALLS = 3;
39
+ export declare const TOOL_IMAGE_KEEP = 3;
40
+ export declare const TOOL_IMAGE_INTERVAL = 25;
31
41
  export declare class RecentToolImages {
32
42
  private readonly bySession;
33
43
  remember(sessionId: string, callId: string, images: readonly {
@@ -45,6 +55,26 @@ export declare class RecentToolImages {
45
55
  * we use 1 retry and 1-2s (Lead ruling). Once any content arrived nothing is retried.
46
56
  */
47
57
  export declare const DEFAULT_IDLE_RETRY_BACKOFF_MS: readonly [number, number];
58
+ /**
59
+ * A transient failure before any content is retried up to TRANSIENT_RETRIES times on a
60
+ * fresh request: HTTP 502/503/504, an error body with `retryable: true`, or a connection
61
+ * that failed before any response. The pause doubles from the first value up to the cap,
62
+ * less up to 25% jitter. Basis: the official OpenAI and Anthropic SDKs (max_retries=2,
63
+ * 0.5s doubling to 8s, jitter). Example: a rolling release of the model gateway refuses
64
+ * connections for a moment (BeeWork tsk_4ec607d9, 2026-11-14: one 503 ended the turn).
65
+ * A failure after content arrived is never retried.
66
+ *
67
+ * A `retry-after-ms` or `Retry-After` header (seconds or an HTTP date) on such a failure
68
+ * lengthens the pause when it is longer than the backoff (same rule as the Go brain,
69
+ * server/gobrain/domain/retry.go). One longer than the backoff cap is not waited for: the
70
+ * failure ends the turn as before, so a pause never exceeds the cap.
71
+ */
72
+ export declare const TRANSIENT_RETRIES = 2;
73
+ export declare const DEFAULT_TRANSIENT_RETRY_BACKOFF_MS: readonly [number, number];
74
+ /** retry-after-ms, then Retry-After as seconds or an HTTP date; undefined when absent, malformed or not in the future. */
75
+ export declare function retryAfterMs(headers: Headers, now?: number): number | undefined;
76
+ /** The pause before transient retry `n` (0-based): first * 2^n up to cap, less up to 25% jitter. */
77
+ export declare function transientBackoffMs(n: number, [first, cap]: readonly [number, number]): number;
48
78
  /**
49
79
  * Default stream idle limit. Same value as the Beework Desktop brain's model
50
80
  * stream guard (behaviour description only); no industry basis. Any received
package/lib/model.js CHANGED
@@ -3,26 +3,36 @@
3
3
  // ModelPort: each session carries its own platform-issued token, so the
4
4
  // platform attributes each request to exactly one session. A request without
5
5
  // a session is never sent (fail closed). No provider key lives in the brain.
6
- import { LlmAdapter, LlmError, CONTEXT_WINDOW_EXCEEDED_CODE, attributionHeaders, isContextWindowExceededError, offloadedImageText, projectOffloadedImages, } from "@deepseek-ai/dsh-llm";
6
+ import { LlmAdapter, LlmError, CONTEXT_WINDOW_EXCEEDED_CODE, QUOTA_EXCEEDED_CODE, attributionHeaders, isContextWindowExceededError, offloadedImageText, projectOffloadedImages, } from "@deepseek-ai/dsh-llm";
7
7
  import { requestMaxTokens } from "./model-catalog.js";
8
8
  export const PROVIDER = "bma";
9
9
  /** Error code of a model stream that sent no data for the idle limit (typed stop model_stream_idle). */
10
10
  export const MODEL_STREAM_IDLE = "MODEL_STREAM_IDLE";
11
+ /** Error code of a model request whose connection failed before any response (refused, reset, DNS). */
12
+ export const MODEL_CONNECTION = "MODEL_CONNECTION";
11
13
  /**
12
- * Tool result images (computer_observe screenshots) are kept in memory for the
13
- * most recent TOOL_IMAGE_CALLS calls of a session and sent with those results
14
- * only; older ones, and all of them after a restart, are left out (the result
15
- * text stays). Basis: Anthropic's computer-use reference loop keeps only the N
16
- * most recent screenshots in the request (only_n_most_recent_images, default
17
- * 3) — screenshots are large and only the latest describe the screen.
14
+ * Tool result images (computer_observe screenshots) are kept in memory per
15
+ * session and sent with their results; pruned ones, and all of them after a
16
+ * restart, are left out (the result text stays). Pruning is in batches: once
17
+ * more than TOOL_IMAGE_KEEP + TOOL_IMAGE_INTERVAL calls have images, the oldest
18
+ * TOOL_IMAGE_INTERVAL drop out together, so the request prefix stays
19
+ * byte-identical between two such steps and the provider's prompt cache keeps
20
+ * hitting (a sliding window changes the prefix on every request). Same rule as
21
+ * the Go brain (server/gobrain/application/toolimages.go), shared vectors
22
+ * test/brain-conformance/tool-image-pruning.vectors.json. Basis: Anthropic,
23
+ * "Best practices for computer and browser use with Claude" (rolling buffer,
24
+ * cache-aware: keep_n = 3, interval = 25).
18
25
  */
19
- export const TOOL_IMAGE_CALLS = 3;
26
+ export const TOOL_IMAGE_KEEP = 3;
27
+ export const TOOL_IMAGE_INTERVAL = 25;
20
28
  export class RecentToolImages {
21
29
  bySession = new Map();
22
30
  remember(sessionId, callId, images) {
31
+ if (!images.length)
32
+ return;
23
33
  const list = this.bySession.get(sessionId) ?? [];
24
34
  list.push({ callId, images: images.map((i) => ({ mediaType: i.mediaType, data: i.data })) });
25
- this.bySession.set(sessionId, list.slice(-TOOL_IMAGE_CALLS));
35
+ this.bySession.set(sessionId, list.length > TOOL_IMAGE_KEEP + TOOL_IMAGE_INTERVAL ? list.slice(TOOL_IMAGE_INTERVAL) : list);
26
36
  }
27
37
  get(sessionId, callId) {
28
38
  return this.bySession.get(sessionId)?.find((e) => e.callId === callId)?.images;
@@ -39,6 +49,63 @@ export class RecentToolImages {
39
49
  * we use 1 retry and 1-2s (Lead ruling). Once any content arrived nothing is retried.
40
50
  */
41
51
  export const DEFAULT_IDLE_RETRY_BACKOFF_MS = [1_000, 2_000];
52
+ /**
53
+ * A transient failure before any content is retried up to TRANSIENT_RETRIES times on a
54
+ * fresh request: HTTP 502/503/504, an error body with `retryable: true`, or a connection
55
+ * that failed before any response. The pause doubles from the first value up to the cap,
56
+ * less up to 25% jitter. Basis: the official OpenAI and Anthropic SDKs (max_retries=2,
57
+ * 0.5s doubling to 8s, jitter). Example: a rolling release of the model gateway refuses
58
+ * connections for a moment (BeeWork tsk_4ec607d9, 2026-11-14: one 503 ended the turn).
59
+ * A failure after content arrived is never retried.
60
+ *
61
+ * A `retry-after-ms` or `Retry-After` header (seconds or an HTTP date) on such a failure
62
+ * lengthens the pause when it is longer than the backoff (same rule as the Go brain,
63
+ * server/gobrain/domain/retry.go). One longer than the backoff cap is not waited for: the
64
+ * failure ends the turn as before, so a pause never exceeds the cap.
65
+ */
66
+ export const TRANSIENT_RETRIES = 2;
67
+ export const DEFAULT_TRANSIENT_RETRY_BACKOFF_MS = [500, 8_000];
68
+ const transientErrors = new WeakMap();
69
+ function transient(err, info) {
70
+ transientErrors.set(err, info);
71
+ return err;
72
+ }
73
+ function transientInfo(err) {
74
+ return err instanceof LlmError ? transientErrors.get(err) : undefined;
75
+ }
76
+ function parseBody(body) {
77
+ try {
78
+ const json = JSON.parse(body);
79
+ return json && typeof json === "object" ? json : undefined;
80
+ }
81
+ catch {
82
+ return undefined;
83
+ }
84
+ }
85
+ /** An error code from the body, only when it looks like an identifier (it goes to logs). */
86
+ function errorCode(json) {
87
+ const code = json?.error?.code ?? json?.error?.type;
88
+ return typeof code === "string" && /^[\w.-]{1,64}$/.test(code) ? code : undefined;
89
+ }
90
+ /** retry-after-ms, then Retry-After as seconds or an HTTP date; undefined when absent, malformed or not in the future. */
91
+ export function retryAfterMs(headers, now = Date.now()) {
92
+ const ms = Number(headers.get("retry-after-ms") ?? NaN);
93
+ if (Number.isFinite(ms) && ms > 0)
94
+ return ms;
95
+ const value = headers.get("retry-after")?.trim();
96
+ if (!value)
97
+ return undefined;
98
+ if (/^\d+(\.\d+)?$/.test(value)) {
99
+ const seconds = Number(value);
100
+ return seconds > 0 ? seconds * 1_000 : undefined;
101
+ }
102
+ const at = Date.parse(value);
103
+ return Number.isFinite(at) && at > now ? at - now : undefined;
104
+ }
105
+ /** The pause before transient retry `n` (0-based): first * 2^n up to cap, less up to 25% jitter. */
106
+ export function transientBackoffMs(n, [first, cap]) {
107
+ return Math.min(first * 2 ** n, cap) * (1 - Math.random() * 0.25);
108
+ }
42
109
  /**
43
110
  * Default stream idle limit. Same value as the Beework Desktop brain's model
44
111
  * stream guard (behaviour description only); no industry basis. Any received
@@ -115,11 +182,18 @@ async function toOpenAi(input, options, sessionId, system, signal) {
115
182
  flushToolImages();
116
183
  return out;
117
184
  }
118
- function failure(status, body) {
185
+ function failure(status, body, headers) {
119
186
  // The canonical overflow code lets dsh compact and retry (compaction-basic reacts to it).
187
+ // The others name the failure class, which stop.ts reports as the contract's model failure stop code.
120
188
  const code = isContextWindowExceededError(body) ? CONTEXT_WINDOW_EXCEEDED_CODE
121
- : status === 401 || status === 403 ? "AUTH" : status === 429 ? "RATE_LIMIT" : "PROVIDER_HTTP";
122
- return new LlmError(`model endpoint HTTP ${status}: ${body.slice(0, 300)}`, code, { status });
189
+ : status === 401 || status === 403 ? "AUTH" : status === 402 ? QUOTA_EXCEEDED_CODE : status === 429 ? "RATE_LIMIT"
190
+ : status >= 500 ? "SERVER" : "PROVIDER_HTTP";
191
+ const err = new LlmError(`model endpoint HTTP ${status}: ${body.slice(0, 300)}`, code, { status });
192
+ const json = parseBody(body);
193
+ if (status !== 502 && status !== 503 && status !== 504 && json?.error?.retryable !== true && json?.retryable !== true)
194
+ return err;
195
+ const after = headers ? retryAfterMs(headers) : undefined;
196
+ return transient(err, { reason: `HTTP ${status}${errorCode(json) ? ` ${errorCode(json)}` : ""}`, ...(after !== undefined ? { retryAfterMs: after } : {}) });
123
197
  }
124
198
  export class ChatCompletionsAdapter extends LlmAdapter {
125
199
  port;
@@ -151,7 +225,10 @@ export class ChatCompletionsAdapter extends LlmAdapter {
151
225
  // caller (loop or compaction) asked for is never above the ceiling, the model's real output limit.
152
226
  const maxTokens = Math.min(request.maxTokens ?? requestMaxTokens(limits), limits.maxOutputTokens);
153
227
  const [minPause, maxPause] = this.options.idleRetryBackoffMs ?? DEFAULT_IDLE_RETRY_BACKOFF_MS;
154
- for (let attempt = 0;; attempt++) {
228
+ const transientBackoff = this.options.transientRetryBackoffMs ?? DEFAULT_TRANSIENT_RETRY_BACKOFF_MS;
229
+ let idleRetried = false;
230
+ let transientRetries = 0;
231
+ for (;;) {
155
232
  const idle = new IdleGuard(this.options.streamIdleMs, request.signal);
156
233
  let content = false;
157
234
  try {
@@ -159,24 +236,41 @@ export class ChatCompletionsAdapter extends LlmAdapter {
159
236
  content = true; // the first chunk is a block-start, only ever produced by a content delta
160
237
  yield chunk;
161
238
  }
162
- if (attempt > 0)
239
+ if (idleRetried)
163
240
  this.port.idleRetry?.(sessionId, "recovered");
241
+ if (transientRetries > 0)
242
+ this.port.transientRetry?.(sessionId, "recovered");
164
243
  return;
165
244
  }
166
245
  catch (err) {
167
- if (!idle.fired)
246
+ if (idle.fired) {
247
+ const stop = new LlmError(`model stream idle: no data for ${this.options.streamIdleMs} ms`, MODEL_STREAM_IDLE, { cause: err });
248
+ if (content || request.signal?.aborted)
249
+ throw stop;
250
+ if (idleRetried) {
251
+ this.port.idleRetry?.(sessionId, "exhausted");
252
+ throw stop;
253
+ }
254
+ idleRetried = true;
255
+ this.port.idleRetry?.(sessionId, "retry");
256
+ await pause(minPause + Math.random() * (maxPause - minPause), request.signal);
257
+ if (request.signal?.aborted)
258
+ throw stop; // cancelled while waiting: give up, no new request
259
+ continue;
260
+ }
261
+ const info = transientInfo(err);
262
+ if (content || request.signal?.aborted || !info)
263
+ throw err;
264
+ const wait = Math.max(transientBackoffMs(transientRetries, transientBackoff), info.retryAfterMs ?? 0);
265
+ if (transientRetries >= TRANSIENT_RETRIES || wait > transientBackoff[1]) {
266
+ this.port.transientRetry?.(sessionId, "exhausted", info.reason);
168
267
  throw err;
169
- const stop = new LlmError(`model stream idle: no data for ${this.options.streamIdleMs} ms`, MODEL_STREAM_IDLE, { cause: err });
170
- if (content || request.signal?.aborted)
171
- throw stop;
172
- if (attempt > 0) {
173
- this.port.idleRetry?.(sessionId, "exhausted");
174
- throw stop;
175
268
  }
176
- this.port.idleRetry?.(sessionId, "retry");
177
- await pause(minPause + Math.random() * (maxPause - minPause), request.signal);
269
+ transientRetries++;
270
+ this.port.transientRetry?.(sessionId, "retry", info.reason);
271
+ await pause(wait, request.signal);
178
272
  if (request.signal?.aborted)
179
- throw stop; // cancelled while waiting: give up, no new request
273
+ throw err; // cancelled while waiting: give up, no new request
180
274
  }
181
275
  finally {
182
276
  idle.stop();
@@ -185,7 +279,7 @@ export class ChatCompletionsAdapter extends LlmAdapter {
185
279
  }
186
280
  async *run(request, sessionId, route, maxTokens, idle, started) {
187
281
  const messages = await toOpenAi(request.messages, this.options, sessionId, request.system, idle.signal);
188
- const response = await fetch(`${route.baseUrl.replace(/\/$/, "")}/chat/completions`, {
282
+ const response = await connect(`${route.baseUrl.replace(/\/$/, "")}/chat/completions`, {
189
283
  method: "POST",
190
284
  signal: idle.signal,
191
285
  headers: { ...attributionHeaders(), "content-type": "application/json", authorization: `Bearer ${route.token}` },
@@ -202,7 +296,7 @@ export class ChatCompletionsAdapter extends LlmAdapter {
202
296
  }),
203
297
  });
204
298
  if (!response.ok || !response.body)
205
- throw failure(response.status, await response.text().catch(() => ""));
299
+ throw failure(response.status, await response.text().catch(() => ""), response.headers);
206
300
  let next = 0;
207
301
  let textIdx;
208
302
  let reasoningIdx;
@@ -321,6 +415,23 @@ export class ChatCompletionsAdapter extends LlmAdapter {
321
415
  yield { type: "finish", reason };
322
416
  }
323
417
  }
418
+ /**
419
+ * fetch, with a connection that failed before any response (refused, reset, DNS, TLS) as a
420
+ * transient MODEL_CONNECTION error. An abort (cancel or idle guard) stays as it is.
421
+ */
422
+ async function connect(url, init) {
423
+ try {
424
+ return await fetch(url, init);
425
+ }
426
+ catch (err) {
427
+ if (init.signal?.aborted)
428
+ throw err;
429
+ const cause = err.cause;
430
+ const detail = cause?.code ?? cause?.message ?? err.message;
431
+ const code = typeof cause?.code === "string" && /^[\w.-]{1,64}$/.test(cause.code) ? cause.code : "failed";
432
+ throw transient(new LlmError(`model endpoint unreachable: ${detail}`, MODEL_CONNECTION, { cause: err }), { reason: `connection ${code}` });
433
+ }
434
+ }
324
435
  /** Resolves after ms, or at once when the signal aborts. */
325
436
  function pause(ms, signal) {
326
437
  return new Promise((resolve) => {
package/lib/spi.d.ts CHANGED
@@ -82,6 +82,17 @@ export interface ModelPort {
82
82
  * Hosts count it as model_stream_idle_retry_total{result} and log it.
83
83
  */
84
84
  idleRetry?(sessionId: string, result: "retry" | "recovered" | "exhausted"): void;
85
+ /**
86
+ * A transient failure before any content (HTTP 502/503/504, `retryable: true`, a
87
+ * connection that failed before any response) and the adapter's reaction: "retry"
88
+ * (a fresh request follows after the backoff), "recovered" (a retry delivered
89
+ * content), "exhausted" (TRANSIENT_RETRIES used up, or the server's Retry-After is
90
+ * longer than the backoff cap; the error ends the turn as before). `reason` is short
91
+ * and safe to log: "HTTP 503 llm_gateway_unavailable" or "connection ECONNREFUSED",
92
+ * never the response body or a token. Hosts count it as
93
+ * model_transient_retry_total{result} and log it, like idleRetry.
94
+ */
95
+ transientRetry?(sessionId: string, result: "retry" | "recovered" | "exhausted", reason?: string): void;
85
96
  }
86
97
  export interface HarnessCapabilities {
87
98
  /** Continues a session from the harness's own durable state in a fresh process. */
@@ -133,7 +144,15 @@ export type StopCode =
133
144
  /** The conversation no longer fits the context window after compaction. */
134
145
  | "context_too_large"
135
146
  /** The model stream sent no data for the idle limit. */
136
- | "model_stream_idle";
147
+ | "model_stream_idle"
148
+ /** The model endpoint answered 5xx or 529. */
149
+ | "model_overloaded_error"
150
+ /** The model endpoint answered 429. */
151
+ | "model_rate_limited_error"
152
+ /** The model endpoint answered 402: the account has no credit. */
153
+ | "billing_error"
154
+ /** The model endpoint refused the request otherwise (any other 4xx, including a rejected credential). */
155
+ | "model_request_failed_error";
137
156
  export declare class TurnStopError extends Error {
138
157
  readonly name = "TurnStopError";
139
158
  readonly code: StopCode;
@@ -175,9 +194,9 @@ export interface HarnessAdapter {
175
194
  /** Loads a session this or an earlier process created (capabilities().resume). */
176
195
  resumeSession(init: SessionInit): Promise<void>;
177
196
  /**
178
- * Replaces the session's host tools (AgentTurnConfig.host_tools of the next
179
- * turn; empty: none) next to the registered tools. Only an adapter that
180
- * offers it takes a turn with host tools.
197
+ * Replaces the session's turn tools (AgentTurnConfig.host_tools and mcp_tools
198
+ * of the next turn; empty: none) next to the registered tools. Only an adapter
199
+ * that offers it takes a turn with host or MCP tools.
181
200
  */
182
201
  setHostTools?(sessionId: string, tools: readonly PlatformTool[]): void;
183
202
  /** The tool names the model will see in this session. */
package/lib/stop.d.ts CHANGED
@@ -10,7 +10,7 @@ export declare function stopForTurnEnd(reason: DshTurnEndReason, context?: {
10
10
  streamIdleMs?: number;
11
11
  }): Error | undefined;
12
12
  /** The contract's stop code table (AgentErrorCode), in contract order. */
13
- export declare const AGENT_ERROR_CODES: readonly ["output_limit_reached", "context_too_large", "model_stream_idle", "agent_error", "agent_unavailable", "agent_auth_required", "agent_protocol_error"];
13
+ export declare const AGENT_ERROR_CODES: readonly ["output_limit_reached", "context_too_large", "model_stream_idle", "agent_error", "agent_unavailable", "agent_auth_required", "agent_protocol_error", "model_overloaded_error", "model_rate_limited_error", "model_request_failed_error", "billing_error"];
14
14
  export type AgentErrorCode = (typeof AGENT_ERROR_CODES)[number];
15
15
  /**
16
16
  * The contract code a failed turn reports: a typed stop is its own code, any
package/lib/stop.js CHANGED
@@ -7,13 +7,25 @@
7
7
  // max-tokens output_limit_reached
8
8
  // error, code CONTEXT_WINDOW_EXCEEDED context_too_large (compaction could not make it fit)
9
9
  // error, code MODEL_STREAM_IDLE model_stream_idle
10
+ // error, code SERVER (5xx, 529) model_overloaded_error (model.ts names the class
11
+ // error, code RATE_LIMIT (429) model_rate_limited_error of a failed model request;
12
+ // error, code QUOTA (402) billing_error the detail is its message)
13
+ // error, code AUTH / PROVIDER_HTTP model_request_failed_error
10
14
  // anything else not completed agent_error: "dsh turn ended: <kind>[: <message>]"
11
15
  //
12
16
  // The codes are the executor contract's stop code table (contracts/bma/schemas/agent.json,
13
17
  // $defs.AgentErrorCode); stop-contract.test.ts fails when the two drift.
14
- import { CONTEXT_WINDOW_EXCEEDED_CODE } from "@deepseek-ai/dsh-llm";
18
+ import { CONTEXT_WINDOW_EXCEEDED_CODE, QUOTA_EXCEEDED_CODE } from "@deepseek-ai/dsh-llm";
15
19
  import { TurnStopError } from "./spi.js";
16
20
  import { MODEL_STREAM_IDLE } from "./model.js";
21
+ /** The stop code of a failed model request, by the class model.ts gave it. */
22
+ const MODEL_FAILURE_STOPS = {
23
+ SERVER: "model_overloaded_error",
24
+ RATE_LIMIT: "model_rate_limited_error",
25
+ [QUOTA_EXCEEDED_CODE]: "billing_error",
26
+ AUTH: "model_request_failed_error",
27
+ PROVIDER_HTTP: "model_request_failed_error",
28
+ };
17
29
  export function stopForTurnEnd(reason, context = {}) {
18
30
  switch (reason.kind) {
19
31
  case "completed":
@@ -26,6 +38,9 @@ export function stopForTurnEnd(reason, context = {}) {
26
38
  return new TurnStopError("context_too_large", "the conversation no longer fits the model context window even after compaction");
27
39
  if (code === MODEL_STREAM_IDLE)
28
40
  return new TurnStopError("model_stream_idle", `the model stream sent no data${context.streamIdleMs ? ` for ${context.streamIdleMs / 1000}s` : ""}`);
41
+ const modelStop = code !== undefined && Object.hasOwn(MODEL_FAILURE_STOPS, code) ? MODEL_FAILURE_STOPS[code] : undefined;
42
+ if (modelStop)
43
+ return new TurnStopError(modelStop, reason.error.message);
29
44
  return new Error(`dsh turn ended: error${reason.error ? `: ${reason.error.message}` : ""}`);
30
45
  }
31
46
  default:
@@ -41,6 +56,10 @@ export const AGENT_ERROR_CODES = [
41
56
  "agent_unavailable",
42
57
  "agent_auth_required",
43
58
  "agent_protocol_error",
59
+ "model_overloaded_error",
60
+ "model_rate_limited_error",
61
+ "model_request_failed_error",
62
+ "billing_error",
44
63
  ];
45
64
  /**
46
65
  * The contract code a failed turn reports: a typed stop is its own code, any
@@ -43,6 +43,12 @@ export interface Reply {
43
43
  status?: number;
44
44
  /** HTTP status plus this error text (default "scripted failure"). */
45
45
  errorText?: string;
46
+ /** With status: send this body as is instead of {error: {message}} (for example a retryable envelope). */
47
+ errorBody?: string;
48
+ /** With status: extra response headers (for example Retry-After). */
49
+ headers?: Record<string, string>;
50
+ /** Close the connection without any response (a stopping backend: the client sees a connection error). */
51
+ drop?: boolean;
46
52
  /** finish_reason of a non-tool reply (default "stop"); "length" simulates a max_tokens cut. */
47
53
  finishReason?: string;
48
54
  /** Usage of the reply (default 11 prompt / 7 completion, no cache); cachedTokens is prompt_tokens_details.cached_tokens, part of promptTokens. */
@@ -29,8 +29,12 @@ export async function startScriptedModel(script, listen = "127.0.0.1") {
29
29
  const request = { token: (req.headers.authorization ?? "").replace(/^Bearer /, ""), body: JSON.parse(Buffer.concat(chunks).toString("utf8")) };
30
30
  requests.push(request);
31
31
  const reply = model.script(request, requests.length - 1);
32
+ if (reply.drop) {
33
+ req.socket.destroy();
34
+ return;
35
+ }
32
36
  if (reply.status) {
33
- res.writeHead(reply.status).end(JSON.stringify({ error: { message: reply.errorText ?? "scripted failure" } }));
37
+ res.writeHead(reply.status, reply.headers).end(reply.errorBody ?? JSON.stringify({ error: { message: reply.errorText ?? "scripted failure" } }));
34
38
  return;
35
39
  }
36
40
  res.writeHead(200, { "content-type": "text/event-stream" });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@beeos-ai/bma-dsh-adapter",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "BMA's shared DSH adapter: kernel assembly, platform-tools-only catalog gate, event translation, approval ids, JSONL resume, typed stop reasons, plus a conformance suite for hosts.",
5
5
  "keywords": [
6
6
  "dsh",