@beeos-ai/bma-dsh-adapter 0.2.2 → 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 +17 -0
- package/lib/adapter.js +75 -10
- package/lib/catalog-gate.d.ts +2 -0
- package/lib/catalog-gate.js +20 -17
- package/lib/conformance/index.js +2 -2
- package/lib/index.d.ts +2 -1
- package/lib/index.js +1 -1
- package/lib/input-skills.d.ts +22 -0
- package/lib/input-skills.js +23 -0
- package/lib/model.d.ts +37 -7
- package/lib/model.js +142 -28
- package/lib/spi.d.ts +33 -1
- package/lib/spi.js +0 -9
- package/lib/stop.d.ts +1 -1
- package/lib/stop.js +20 -1
- package/lib/system-prompt.js +5 -1
- package/lib/testing/scripted-model.d.ts +12 -0
- package/lib/testing/scripted-model.js +11 -2
- 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
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Context } from "@deepseek-ai/cordis";
|
|
2
2
|
import { type HarnessAdapter, type HarnessCapabilities, type HarnessEvent, type HarnessInput, type ModelPort, type PlatformTool, type SessionInit } from "./spi.ts";
|
|
3
|
+
import { type InputSkillDocument, type InputSkillReceipt } from "./input-skills.ts";
|
|
3
4
|
export interface DshAdapterOptions {
|
|
4
5
|
home: string;
|
|
5
6
|
/** Concurrent read-only tool calls per step (dsh agent-loop); omitted = dsh's own default. */
|
|
@@ -8,6 +9,8 @@ export interface DshAdapterOptions {
|
|
|
8
9
|
streamIdleMs?: number;
|
|
9
10
|
/** Pause range (ms) before the one retry of a stream that idled before any content; default 1000..2000. */
|
|
10
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];
|
|
11
14
|
}
|
|
12
15
|
export declare class DshAdapter implements HarnessAdapter {
|
|
13
16
|
readonly id = "dsh";
|
|
@@ -17,6 +20,7 @@ export declare class DshAdapter implements HarnessAdapter {
|
|
|
17
20
|
private tools;
|
|
18
21
|
private readonly streamIdleMs;
|
|
19
22
|
private readonly idleRetryBackoffMs;
|
|
23
|
+
private readonly transientRetryBackoffMs;
|
|
20
24
|
private port;
|
|
21
25
|
private readonly toolImages;
|
|
22
26
|
private constructor();
|
|
@@ -28,7 +32,20 @@ export declare class DshAdapter implements HarnessAdapter {
|
|
|
28
32
|
resumeSession(init: SessionInit): Promise<void>;
|
|
29
33
|
private open;
|
|
30
34
|
private get;
|
|
35
|
+
/**
|
|
36
|
+
* The session's host tools from now on (AgentTurnConfig.host_tools of the
|
|
37
|
+
* turn about to run), next to the registered platform tools: the previous
|
|
38
|
+
* set is unregistered first. Not while an input runs.
|
|
39
|
+
*/
|
|
40
|
+
setHostTools(sessionId: string, tools: readonly PlatformTool[]): void;
|
|
31
41
|
toolCatalog(sessionId: string): readonly string[];
|
|
42
|
+
/** Installs exact turn-only context before returning its executor receipt.
|
|
43
|
+
* The host must bind this to the accepted opening input and durable turn config.
|
|
44
|
+
* No public capability is advertised until that contract is wired end to end.
|
|
45
|
+
*/
|
|
46
|
+
prepareInputSkills(sessionId: string, inputId: string, documents: readonly InputSkillDocument[]): InputSkillReceipt;
|
|
47
|
+
/** Cancelled accepted work may never enter submitInput. Release only its idle preparation. */
|
|
48
|
+
clearPreparedInputSkills(sessionId: string, inputId: string): void;
|
|
32
49
|
submitInput(sessionId: string, input: HarnessInput, signal: AbortSignal): AsyncIterable<HarnessEvent>;
|
|
33
50
|
/** Text-only input only: the host queues an input with images as the next turn instead. */
|
|
34
51
|
appendInput(sessionId: string, input: HarnessInput): void;
|
package/lib/adapter.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { MessageId, freezeMessage } from "@deepseek-ai/dsh-llm";
|
|
2
2
|
import { SessionId } from "@deepseek-ai/dsh-session";
|
|
3
3
|
import {} from "./spi.js";
|
|
4
|
+
import { prepareInputSkills } from "./input-skills.js";
|
|
4
5
|
import { AsyncQueue } from "./async-queue.js";
|
|
5
|
-
import { restrictToPlatformTools } from "./catalog-gate.js";
|
|
6
|
+
import { registerPlatformTool, restrictToPlatformTools } from "./catalog-gate.js";
|
|
6
7
|
import { requestMaxTokens } from "./model-catalog.js";
|
|
7
8
|
import { harnessEventFromStreamFrame, harnessEventsFromSessionEvent } from "./events.js";
|
|
8
9
|
import { CONTINUE_NOTE, assertResumable, continuationId, hasRecordedInput } from "./recovery.js";
|
|
@@ -25,16 +26,18 @@ export class DshAdapter {
|
|
|
25
26
|
tools = [];
|
|
26
27
|
streamIdleMs;
|
|
27
28
|
idleRetryBackoffMs;
|
|
29
|
+
transientRetryBackoffMs;
|
|
28
30
|
port;
|
|
29
31
|
toolImages = new RecentToolImages();
|
|
30
|
-
constructor(ctx, streamIdleMs, idleRetryBackoffMs) {
|
|
32
|
+
constructor(ctx, streamIdleMs, idleRetryBackoffMs, transientRetryBackoffMs) {
|
|
31
33
|
this.ctx = ctx;
|
|
32
34
|
this.streamIdleMs = streamIdleMs;
|
|
33
35
|
this.idleRetryBackoffMs = idleRetryBackoffMs;
|
|
36
|
+
this.transientRetryBackoffMs = transientRetryBackoffMs;
|
|
34
37
|
}
|
|
35
38
|
static async mount(options) {
|
|
36
39
|
const ctx = await mountKernel({ home: options.home, ...(options.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: options.maxParallelToolCalls } : {}) });
|
|
37
|
-
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);
|
|
38
41
|
}
|
|
39
42
|
capabilities() {
|
|
40
43
|
return { resume: true, deltas: true, midTurnInput: true, imageInput: true };
|
|
@@ -45,6 +48,7 @@ export class DshAdapter {
|
|
|
45
48
|
this.ctx.llm.registerAdapter([PROVIDER], new ChatCompletionsAdapter(port, {
|
|
46
49
|
streamIdleMs: this.streamIdleMs,
|
|
47
50
|
...(this.idleRetryBackoffMs ? { idleRetryBackoffMs: this.idleRetryBackoffMs } : {}),
|
|
51
|
+
...(this.transientRetryBackoffMs ? { transientRetryBackoffMs: this.transientRetryBackoffMs } : {}),
|
|
48
52
|
toolImages: (sessionId, callId) => this.toolImages.get(sessionId, callId),
|
|
49
53
|
readImage: async (block, signal) => {
|
|
50
54
|
const image = await attachments.readImageRequest(block.attachment, REQUEST_IMAGE_TARGET, signal);
|
|
@@ -66,10 +70,11 @@ export class DshAdapter {
|
|
|
66
70
|
if (this.sessions.has(init.sessionId))
|
|
67
71
|
throw new Error(`session ${init.sessionId} is already open`);
|
|
68
72
|
const sessionId = SessionId(init.sessionId);
|
|
69
|
-
const state = { init };
|
|
73
|
+
const state = { init, hostTools: { tools: [], dispose: [] } };
|
|
70
74
|
const setup = (scope) => {
|
|
71
|
-
scope
|
|
72
|
-
|
|
75
|
+
state.scope = scope;
|
|
76
|
+
scope.systemPrompt.section({ name: "bma", order: 0, complete: true, interpolate: false, text: () => state.init.systemPrompt + (state.inputSkills?.system ?? "") });
|
|
77
|
+
restrictToPlatformTools(scope, init.sessionId, [...this.tools, ...(init.sessionTools ?? [])], (callId, images) => this.toolImages.remember(init.sessionId, callId, images));
|
|
73
78
|
scope.on("session/event", (session, event) => {
|
|
74
79
|
if (session.id === sessionId)
|
|
75
80
|
this.onSessionEvent(state, event);
|
|
@@ -88,26 +93,83 @@ export class DshAdapter {
|
|
|
88
93
|
throw new Error(`session ${sessionId} is not open`);
|
|
89
94
|
return state;
|
|
90
95
|
}
|
|
96
|
+
/**
|
|
97
|
+
* The session's host tools from now on (AgentTurnConfig.host_tools of the
|
|
98
|
+
* turn about to run), next to the registered platform tools: the previous
|
|
99
|
+
* set is unregistered first. Not while an input runs.
|
|
100
|
+
*/
|
|
101
|
+
setHostTools(sessionId, tools) {
|
|
102
|
+
const state = this.get(sessionId);
|
|
103
|
+
if (state.sink)
|
|
104
|
+
throw new Error("cannot change host tools during an active input");
|
|
105
|
+
for (const dispose of state.hostTools.dispose)
|
|
106
|
+
dispose();
|
|
107
|
+
state.hostTools = {
|
|
108
|
+
tools,
|
|
109
|
+
dispose: tools.map((tool) => registerPlatformTool(state.scope, sessionId, tool, (callId, images) => this.toolImages.remember(sessionId, callId, images))),
|
|
110
|
+
};
|
|
111
|
+
}
|
|
91
112
|
toolCatalog(sessionId) {
|
|
92
113
|
return this.ctx.tools.schemas(this.get(sessionId).handle.agent).map((s) => s.name);
|
|
93
114
|
}
|
|
115
|
+
/** Installs exact turn-only context before returning its executor receipt.
|
|
116
|
+
* The host must bind this to the accepted opening input and durable turn config.
|
|
117
|
+
* No public capability is advertised until that contract is wired end to end.
|
|
118
|
+
*/
|
|
119
|
+
prepareInputSkills(sessionId, inputId, documents) {
|
|
120
|
+
const state = this.get(sessionId);
|
|
121
|
+
if (state.sink)
|
|
122
|
+
throw new Error("cannot change selected skills during an active input");
|
|
123
|
+
const candidate = prepareInputSkills(inputId, documents);
|
|
124
|
+
if (state.inputSkills && JSON.stringify(state.inputSkills.receipt) !== JSON.stringify(candidate.receipt)) {
|
|
125
|
+
throw new Error("another input skill context is already installed");
|
|
126
|
+
}
|
|
127
|
+
if (state.inputSkills)
|
|
128
|
+
return state.inputSkills.receipt;
|
|
129
|
+
state.inputSkills = candidate;
|
|
130
|
+
return candidate.receipt;
|
|
131
|
+
}
|
|
132
|
+
/** Cancelled accepted work may never enter submitInput. Release only its idle preparation. */
|
|
133
|
+
clearPreparedInputSkills(sessionId, inputId) {
|
|
134
|
+
const state = this.get(sessionId);
|
|
135
|
+
if (state.sink)
|
|
136
|
+
throw new Error("cannot clear selected skills while input is active");
|
|
137
|
+
if (state.inputSkills?.receipt.input_id === inputId)
|
|
138
|
+
state.inputSkills = undefined;
|
|
139
|
+
}
|
|
94
140
|
async *submitInput(sessionId, input, signal) {
|
|
95
141
|
const state = this.get(sessionId);
|
|
142
|
+
if (state.sink)
|
|
143
|
+
throw new Error("session already has an active input");
|
|
144
|
+
if (state.inputSkills && state.inputSkills.receipt.input_id !== (input.bindingInputId ?? input.id))
|
|
145
|
+
throw new Error("selected skills belong to another input");
|
|
96
146
|
const agent = state.handle.agent;
|
|
97
147
|
const queue = new AsyncQueue();
|
|
98
148
|
state.sink = (e) => queue.push(e);
|
|
99
149
|
const onAbort = () => agent.cancel({ kind: "user" });
|
|
100
150
|
signal.addEventListener("abort", onAbort, { once: true });
|
|
101
151
|
const from = agent.session.snapshotEvents().length;
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
const idle = agent.whenIdle().then(() => queue.end(), (err) => queue.fail(err));
|
|
152
|
+
let idle;
|
|
153
|
+
let settled = false;
|
|
105
154
|
try {
|
|
155
|
+
signal.throwIfAborted();
|
|
156
|
+
const seen = hasRecordedInput(agent.session.snapshotEvents(), input.id);
|
|
157
|
+
const content = seen ? [{ type: "text", text: CONTINUE_NOTE }] : await this.content(input);
|
|
158
|
+
signal.throwIfAborted();
|
|
159
|
+
agent.followup(userMessage(seen ? continuationId(input.id) : input.id, content));
|
|
160
|
+
idle = agent.whenIdle().then(() => { settled = true; queue.end(); }, (err) => { settled = true; queue.fail(err); });
|
|
106
161
|
yield* queue;
|
|
107
162
|
await idle;
|
|
108
163
|
}
|
|
109
164
|
finally {
|
|
165
|
+
// A consumer may stop iterating before the agent is idle. Retain the
|
|
166
|
+
// context and exclusion until cancellation has actually settled.
|
|
167
|
+
if (idle && !settled) {
|
|
168
|
+
agent.cancel({ kind: "user" });
|
|
169
|
+
await idle;
|
|
170
|
+
}
|
|
110
171
|
state.sink = undefined;
|
|
172
|
+
state.inputSkills = undefined;
|
|
111
173
|
signal.removeEventListener("abort", onAbort);
|
|
112
174
|
}
|
|
113
175
|
if (signal.aborted)
|
|
@@ -125,7 +187,10 @@ export class DshAdapter {
|
|
|
125
187
|
appendInput(sessionId, input) {
|
|
126
188
|
if (input.images?.length)
|
|
127
189
|
throw new Error("appendInput does not take images");
|
|
128
|
-
this.get(sessionId)
|
|
190
|
+
const state = this.get(sessionId);
|
|
191
|
+
if (state.inputSkills)
|
|
192
|
+
throw new Error("cannot append another input to a selected-skill turn");
|
|
193
|
+
state.handle.agent.followup(userMessage(input.id, [{ type: "text", text: input.text }]));
|
|
129
194
|
}
|
|
130
195
|
/**
|
|
131
196
|
* Whether this build can take image input: the attachment service decodes
|
package/lib/catalog-gate.d.ts
CHANGED
|
@@ -3,5 +3,7 @@ import type { InputImage, PlatformTool } from "./spi.ts";
|
|
|
3
3
|
/** Receives the images of a tool result (they are not part of the stored result; see model.ts). */
|
|
4
4
|
export type ToolImageSink = (callId: string, images: readonly InputImage[]) => void;
|
|
5
5
|
export declare function restrictToPlatformTools(scope: Context, sessionId: string, tools: readonly PlatformTool[], onImages?: ToolImageSink): void;
|
|
6
|
+
/** Registers one platform tool into the agent scope; returns its disposer. */
|
|
7
|
+
export declare function registerPlatformTool(scope: Context, sessionId: string, tool: PlatformTool, onImages?: ToolImageSink): () => void;
|
|
6
8
|
/** Why a session must be refused, or undefined when the catalog is exactly the expected tools. */
|
|
7
9
|
export declare function catalogViolation(harnessId: string, expected: readonly string[], actual: readonly string[]): string | undefined;
|
package/lib/catalog-gate.js
CHANGED
|
@@ -1,22 +1,25 @@
|
|
|
1
1
|
export function restrictToPlatformTools(scope, sessionId, tools, onImages) {
|
|
2
2
|
scope.tools.restrict({ allow: [] });
|
|
3
|
-
for (const tool of tools)
|
|
4
|
-
scope
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
3
|
+
for (const tool of tools)
|
|
4
|
+
registerPlatformTool(scope, sessionId, tool, onImages);
|
|
5
|
+
}
|
|
6
|
+
/** Registers one platform tool into the agent scope; returns its disposer. */
|
|
7
|
+
export function registerPlatformTool(scope, sessionId, tool, onImages) {
|
|
8
|
+
return scope.tools.register({
|
|
9
|
+
name: tool.name,
|
|
10
|
+
description: tool.description,
|
|
11
|
+
parameters: tool.parameters,
|
|
12
|
+
output: { schema: { type: "string" }, render: (_args, value) => [{ type: "text", text: String(value) }] },
|
|
13
|
+
isConcurrencySafe: () => tool.readOnly,
|
|
14
|
+
execute: async (args, exec) => {
|
|
15
|
+
const result = await tool.invoke({ sessionId, callId: exec.callId, input: (args ?? {}), signal: exec.signal });
|
|
16
|
+
if (result.isError)
|
|
17
|
+
throw new Error(result.text);
|
|
18
|
+
if (result.images?.length)
|
|
19
|
+
onImages?.(exec.callId, result.images);
|
|
20
|
+
return result.text;
|
|
21
|
+
},
|
|
22
|
+
});
|
|
20
23
|
}
|
|
21
24
|
/** Why a session must be refused, or undefined when the catalog is exactly the expected tools. */
|
|
22
25
|
export function catalogViolation(harnessId, expected, actual) {
|
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";
|
|
@@ -10,3 +10,4 @@ export { CONTINUE_NOTE, assertResumable, hasRecordedInput, continuationId } from
|
|
|
10
10
|
export { stopForTurnEnd, agentErrorCode, AGENT_ERROR_CODES, type AgentErrorCode, type DshTurnEndReason } from "./stop.ts";
|
|
11
11
|
export { BASE_SYSTEM_PROMPT, composeSystemPrompt } from "./system-prompt.ts";
|
|
12
12
|
export { DSH_VERSION } from "./version.ts";
|
|
13
|
+
export type { InputSkillDocument, InputSkillReceipt } from "./input-skills.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";
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/** Resolved by the platform under current grant and session-frozen revision checks. */
|
|
2
|
+
export interface InputSkillDocument {
|
|
3
|
+
readonly skill_id: string;
|
|
4
|
+
readonly revision_id: string;
|
|
5
|
+
readonly name: string;
|
|
6
|
+
readonly body: string;
|
|
7
|
+
readonly body_sha256: string;
|
|
8
|
+
}
|
|
9
|
+
export interface InputSkillReceipt {
|
|
10
|
+
readonly input_id: string;
|
|
11
|
+
readonly skills: readonly {
|
|
12
|
+
readonly skill_id: string;
|
|
13
|
+
readonly revision_id: string;
|
|
14
|
+
readonly body_sha256: string;
|
|
15
|
+
}[];
|
|
16
|
+
}
|
|
17
|
+
export interface PreparedInputSkills {
|
|
18
|
+
readonly receipt: InputSkillReceipt;
|
|
19
|
+
readonly system: string;
|
|
20
|
+
}
|
|
21
|
+
/** Verify bytes again at the executor boundary; never acknowledge archive hashes. */
|
|
22
|
+
export declare function prepareInputSkills(inputId: string, documents: readonly InputSkillDocument[]): PreparedInputSkills;
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
/** Verify bytes again at the executor boundary; never acknowledge archive hashes. */
|
|
3
|
+
export function prepareInputSkills(inputId, documents) {
|
|
4
|
+
if (!inputId || documents.length < 1 || documents.length > 10)
|
|
5
|
+
throw new Error('invalid input skill selection');
|
|
6
|
+
const seen = new Set();
|
|
7
|
+
let total = 0;
|
|
8
|
+
const copies = documents.map(doc => {
|
|
9
|
+
if (!doc || !/^skl_[a-zA-Z0-9_-]{1,124}$/.test(doc.skill_id) || !/^skr_[a-zA-Z0-9_-]{1,124}$/.test(doc.revision_id)
|
|
10
|
+
|| seen.has(doc.skill_id) || typeof doc.name !== 'string' || !doc.name.trim() || Buffer.byteLength(doc.name) > 255
|
|
11
|
+
|| typeof doc.body !== 'string' || !doc.body.trim() || Buffer.byteLength(doc.body) > 65_536
|
|
12
|
+
|| createHash('sha256').update(doc.body, 'utf8').digest('hex') !== doc.body_sha256) {
|
|
13
|
+
throw new Error('selected skill bytes do not match the admitted version');
|
|
14
|
+
}
|
|
15
|
+
total += Buffer.byteLength(doc.body);
|
|
16
|
+
if (total > 262_144)
|
|
17
|
+
throw new Error('selected skill context is too large');
|
|
18
|
+
seen.add(doc.skill_id);
|
|
19
|
+
return { skill_id: doc.skill_id, revision_id: doc.revision_id, name: doc.name, body: doc.body, body_sha256: doc.body_sha256 };
|
|
20
|
+
});
|
|
21
|
+
const receipt = Object.freeze({ input_id: inputId, skills: Object.freeze(copies.map(({ skill_id, revision_id, body_sha256 }) => Object.freeze({ skill_id, revision_id, body_sha256 }))) });
|
|
22
|
+
return Object.freeze({ receipt, system: '\n\nSkills explicitly selected for this input only:\n' + JSON.stringify(copies) });
|
|
23
|
+
}
|
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;
|
|
@@ -236,12 +330,15 @@ export class ChatCompletionsAdapter extends LlmAdapter {
|
|
|
236
330
|
throw new LlmError(`model stream error: ${JSON.stringify(json.error).slice(0, 300)}`, "PROVIDER_STREAM");
|
|
237
331
|
if (json.usage) {
|
|
238
332
|
// dsh requires losslessly JSON-serializable chunks: no undefined members.
|
|
333
|
+
// OpenAI prompt_tokens include the cached reads; dsh counts input and cache reads apart
|
|
334
|
+
// (its context pressure is input + cacheRead + cacheWrite), so input is the uncached part.
|
|
239
335
|
const u = json.usage;
|
|
336
|
+
const cached = u.prompt_tokens_details?.cached_tokens;
|
|
240
337
|
usage = {
|
|
241
|
-
inputTokens: u.prompt_tokens ?? 0,
|
|
338
|
+
inputTokens: Math.max(0, (u.prompt_tokens ?? 0) - (cached ?? 0)),
|
|
242
339
|
outputTokens: u.completion_tokens ?? 0,
|
|
243
340
|
...(u.total_tokens !== undefined ? { totalTokens: u.total_tokens } : {}),
|
|
244
|
-
...(
|
|
341
|
+
...(cached !== undefined ? { cacheReadTokens: cached } : {}),
|
|
245
342
|
...(u.completion_tokens_details?.reasoning_tokens !== undefined ? { reasoningTokens: u.completion_tokens_details.reasoning_tokens } : {}),
|
|
246
343
|
};
|
|
247
344
|
}
|
|
@@ -318,6 +415,23 @@ export class ChatCompletionsAdapter extends LlmAdapter {
|
|
|
318
415
|
yield { type: "finish", reason };
|
|
319
416
|
}
|
|
320
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
|
+
}
|
|
321
435
|
/** Resolves after ms, or at once when the signal aborts. */
|
|
322
436
|
function pause(ms, signal) {
|
|
323
437
|
return new Promise((resolve) => {
|
package/lib/spi.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { InputSkillDocument, InputSkillReceipt } from "./input-skills.ts";
|
|
1
2
|
/** The six official agent_toolset tools a server-side brain may call (ADR 0005). */
|
|
2
3
|
export type ToolName = "bash" | "read" | "write" | "edit" | "glob" | "grep";
|
|
3
4
|
/** One model tool call handed to the platform. */
|
|
@@ -81,6 +82,17 @@ export interface ModelPort {
|
|
|
81
82
|
* Hosts count it as model_stream_idle_retry_total{result} and log it.
|
|
82
83
|
*/
|
|
83
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;
|
|
84
96
|
}
|
|
85
97
|
export interface HarnessCapabilities {
|
|
86
98
|
/** Continues a session from the harness's own durable state in a fresh process. */
|
|
@@ -99,6 +111,8 @@ export interface SessionInit {
|
|
|
99
111
|
readonly systemPrompt: string;
|
|
100
112
|
/** Working directory on the session's machine, for the prompt only (tools run on the machine). */
|
|
101
113
|
readonly cwd: string;
|
|
114
|
+
/** Tools of this session only, next to the registered platform tools (the agent's custom tools). */
|
|
115
|
+
readonly sessionTools?: readonly PlatformTool[];
|
|
102
116
|
}
|
|
103
117
|
/** One image of a user input, already fetched by the host. */
|
|
104
118
|
export interface InputImage {
|
|
@@ -111,6 +125,8 @@ export interface HarnessInput {
|
|
|
111
125
|
/** Platform input id, or a host-made id for a recovery note. */
|
|
112
126
|
readonly id: string;
|
|
113
127
|
readonly text: string;
|
|
128
|
+
/** Host recovery can use a new transcript message while retaining its admitted opening-input binding. */
|
|
129
|
+
readonly bindingInputId?: string;
|
|
114
130
|
/** Images the model sees with the text; only when capabilities().imageInput. */
|
|
115
131
|
readonly images?: readonly InputImage[];
|
|
116
132
|
}
|
|
@@ -128,7 +144,15 @@ export type StopCode =
|
|
|
128
144
|
/** The conversation no longer fits the context window after compaction. */
|
|
129
145
|
| "context_too_large"
|
|
130
146
|
/** The model stream sent no data for the idle limit. */
|
|
131
|
-
| "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";
|
|
132
156
|
export declare class TurnStopError extends Error {
|
|
133
157
|
readonly name = "TurnStopError";
|
|
134
158
|
readonly code: StopCode;
|
|
@@ -169,6 +193,12 @@ export interface HarnessAdapter {
|
|
|
169
193
|
createSession(init: SessionInit): Promise<void>;
|
|
170
194
|
/** Loads a session this or an earlier process created (capabilities().resume). */
|
|
171
195
|
resumeSession(init: SessionInit): Promise<void>;
|
|
196
|
+
/**
|
|
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.
|
|
200
|
+
*/
|
|
201
|
+
setHostTools?(sessionId: string, tools: readonly PlatformTool[]): void;
|
|
172
202
|
/** The tool names the model will see in this session. */
|
|
173
203
|
toolCatalog(sessionId: string): readonly string[];
|
|
174
204
|
/**
|
|
@@ -179,6 +209,8 @@ export interface HarnessAdapter {
|
|
|
179
209
|
* input the harness already recorded; the harness then continues that
|
|
180
210
|
* input instead of adding it twice.
|
|
181
211
|
*/
|
|
212
|
+
prepareInputSkills?(sessionId: string, inputId: string, documents: readonly InputSkillDocument[]): InputSkillReceipt;
|
|
213
|
+
clearPreparedInputSkills?(sessionId: string, inputId: string): void;
|
|
182
214
|
submitInput(sessionId: string, input: HarnessInput, signal: AbortSignal): AsyncIterable<HarnessEvent>;
|
|
183
215
|
/** Adds input to the running turn; only when capabilities().midTurnInput. */
|
|
184
216
|
appendInput(sessionId: string, input: HarnessInput): void;
|
package/lib/spi.js
CHANGED
|
@@ -1,12 +1,3 @@
|
|
|
1
|
-
// HarnessAdapter SPI: the only code a new harness (DSH, Claude Agent SDK, ...)
|
|
2
|
-
// has to write. Everything platform-shaped — the executor agent channel,
|
|
3
|
-
// session lifecycle, the six platform tools and their approval/gateway path,
|
|
4
|
-
// per-session model routing, recovery after a host restart, limits, logs and
|
|
5
|
-
// metrics — lives in the host framework (src/host/) and reaches the harness
|
|
6
|
-
// only through these interfaces.
|
|
7
|
-
//
|
|
8
|
-
// Shape follows duyet/oma HarnessInterface/HarnessRuntime/HarnessContext and
|
|
9
|
-
// BMA H0 driver.Harness (ADR 0001/0004).
|
|
10
1
|
/**
|
|
11
2
|
* Reasoning effort levels, the union of OpenAI's `reasoning_effort` (none, minimal, low, medium,
|
|
12
3
|
* high, xhigh, max) and Claude Code's effort levels (low, medium, high, xhigh, max), lowest first.
|
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
|
package/lib/system-prompt.js
CHANGED
|
@@ -4,7 +4,11 @@
|
|
|
4
4
|
// The kernel adds nothing of its own (no harness identity, no runtime context).
|
|
5
5
|
export const BASE_SYSTEM_PROMPT = [
|
|
6
6
|
"You are an agent running on BMA (BeeOS Managed Agents).",
|
|
7
|
-
"Your tools run on the session's machine; use absolute paths.
|
|
7
|
+
"Your tools run on the session's machine; use absolute paths.",
|
|
8
|
+
// Session deliverables (docs/architecture/session-deliverables.md): outputs
|
|
9
|
+
// holds only final files, and a file is delivered when the final reply names it.
|
|
10
|
+
"Keep intermediate files (extracted text, helper scripts, logs, drafts) in your home directory or /tmp, never in the session's outputs directory.",
|
|
11
|
+
"Write to the session's outputs directory (named under Session files) only the final files the user asked for, and name each one by its file name in your final reply: only the files named there are delivered to the user.",
|
|
8
12
|
"Be concise. When a task is done, say what you did.",
|
|
9
13
|
].join("\n");
|
|
10
14
|
/** Base prompt, then the agent's `system` after one blank line; no `system` (or an empty one) is the base prompt alone. */
|
|
@@ -43,8 +43,20 @@ 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;
|
|
54
|
+
/** Usage of the reply (default 11 prompt / 7 completion, no cache); cachedTokens is prompt_tokens_details.cached_tokens, part of promptTokens. */
|
|
55
|
+
usage?: {
|
|
56
|
+
promptTokens: number;
|
|
57
|
+
completionTokens: number;
|
|
58
|
+
cachedTokens?: number;
|
|
59
|
+
};
|
|
48
60
|
}
|
|
49
61
|
export type Script = (req: ModelRequest, index: number) => Reply;
|
|
50
62
|
export interface ScriptedModel {
|
|
@@ -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" });
|
|
@@ -46,7 +50,12 @@ export async function startScriptedModel(script, listen = "127.0.0.1") {
|
|
|
46
50
|
return;
|
|
47
51
|
(reply.toolCalls ?? []).forEach((c, i) => send({ tool_calls: [{ index: i, id: c.id, type: "function", function: { name: c.name, arguments: JSON.stringify(c.args) } }] }));
|
|
48
52
|
send({}, reply.toolCalls?.length && !reply.finishReason ? "tool_calls" : (reply.finishReason ?? "stop"));
|
|
49
|
-
|
|
53
|
+
const u = reply.usage ?? { promptTokens: 11, completionTokens: 7 };
|
|
54
|
+
const usage = {
|
|
55
|
+
prompt_tokens: u.promptTokens, completion_tokens: u.completionTokens, total_tokens: u.promptTokens + u.completionTokens,
|
|
56
|
+
...(u.cachedTokens !== undefined ? { prompt_tokens_details: { cached_tokens: u.cachedTokens } } : {}),
|
|
57
|
+
};
|
|
58
|
+
res.write(`data: ${JSON.stringify({ choices: [], usage })}\n\n`);
|
|
50
59
|
res.end("data: [DONE]\n\n");
|
|
51
60
|
});
|
|
52
61
|
server.on("connection", (s) => { sockets.add(s); s.on("close", () => sockets.delete(s)); });
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@beeos-ai/bma-dsh-adapter",
|
|
3
|
-
"version": "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",
|