@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 +1 -1
- package/lib/adapter.d.ts +3 -0
- package/lib/adapter.js +5 -2
- package/lib/conformance/index.js +2 -2
- package/lib/index.d.ts +1 -1
- package/lib/index.js +1 -1
- package/lib/model.d.ts +37 -7
- package/lib/model.js +137 -26
- package/lib/spi.d.ts +23 -4
- package/lib/stop.d.ts +1 -1
- package/lib/stop.js +20 -1
- package/lib/testing/scripted-model.d.ts +6 -0
- package/lib/testing/scripted-model.js +5 -1
- package/package.json +1 -1
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
|
|
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);
|
package/lib/conformance/index.js
CHANGED
|
@@ -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
|
|
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"), (
|
|
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,
|
|
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,
|
|
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
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
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
|
|
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
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
*
|
|
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
|
|
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(
|
|
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 ===
|
|
122
|
-
|
|
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
|
-
|
|
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 (
|
|
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 (
|
|
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
|
-
|
|
177
|
-
|
|
269
|
+
transientRetries++;
|
|
270
|
+
this.port.transientRetry?.(sessionId, "retry", info.reason);
|
|
271
|
+
await pause(wait, request.signal);
|
|
178
272
|
if (request.signal?.aborted)
|
|
179
|
-
throw
|
|
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
|
|
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
|
|
179
|
-
* turn; empty: none) next to the registered tools. Only an adapter
|
|
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.
|
|
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",
|