@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 CHANGED
@@ -11,7 +11,7 @@ BMA 的共享 DSH 适配层(Apache-2.0)。把 [DSH](https://www.npmjs.com/or
11
11
  | `recovery.ts` + `adapter.ts` | JSONL resume(无日志 → `SessionNotFoundError`)、按 input id 幂等(已记录的输入只发续跑提示) | 一致性套件 resume |
12
12
  | `stop.ts` + `spi.ts` | 停止原因映射:`output_limit_reached` / `context_too_large` / `model_stream_idle`(`TurnStopError`,消息以 `<code>: ` 开头),其余通用失败;`AGENT_ERROR_CODES` / `agentErrorCode` 对应执行端契约码表(`contracts/bma/schemas/agent.json` `AgentErrorCode`) | 一致性套件 stop reasons、`stop-contract.test.ts`、`model-limits.test.ts` |
13
13
  | `system-prompt.ts` | `BASE_SYSTEM_PROMPT` + `composeSystemPrompt(agentSystem?)`:所有外壳在这里拼系统提示,不自己写死 | 一致性套件 system prompt、`system-prompt.test.ts` |
14
- | `model.ts`、`model-catalog.ts` | OpenAI Chat 适配器:按模型取 max_tokens / 窗口(声明 > 目录文件 > 保守默认,记录)、图片 `image_url`、流空闲守卫(首个内容增量前空闲:退避 1–2 s 自动重试 1 次,已有内容后不重试) | `model-limits.test.ts` |
14
+ | `model.ts`、`model-catalog.ts` | OpenAI Chat 适配器:按模型取 max_tokens / 窗口(声明 > 目录文件 > 保守默认,记录)、图片 `image_url`、流空闲守卫(首个内容增量前空闲:退避 1–2 s 自动重试 1 次,已有内容后不重试)、暂时性失败重试(首个内容增量前遇到 HTTP 502/503/504、错误体 `retryable: true` 或响应前连接失败:最多重试 2 次,退避从 0.5 s 翻倍、上限 8 s、减最多 25% 抖动,同官方 OpenAI / Anthropic SDK;服务端给了 `retry-after-ms` / `Retry-After` 且比退避长时按它等,超过 8 s 则不等、直接失败;已有内容后不重试;宿主经 `ModelPort.transientRetry` 计数记日志,原因只含状态码和错误码,不含响应体和令牌) | `model-limits.test.ts` |
15
15
  | `spi.ts` | `HarnessAdapter` / `ModelPort` / `PlatformTool` 契约(harness 无关) | — |
16
16
 
17
17
  审批的等待逻辑(interaction.request/response、停机时保持打开)属于宿主的通道,留在宿主里。
package/lib/adapter.d.ts CHANGED
@@ -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.systemPrompt.section({ name: "bma", order: 0, complete: true, interpolate: false, text: () => state.init.systemPrompt });
72
- restrictToPlatformTools(scope, init.sessionId, this.tools, (callId, images) => this.toolImages.remember(init.sessionId, callId, images));
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
- const seen = hasRecordedInput(agent.session.snapshotEvents(), input.id);
103
- agent.followup(seen ? userMessage(continuationId(input.id), [{ type: "text", text: CONTINUE_NOTE }]) : userMessage(input.id, await this.content(input)));
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).handle.agent.followup(userMessage(input.id, [{ type: "text", text: input.text }]));
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
@@ -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;
@@ -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.tools.register({
5
- name: tool.name,
6
- description: tool.description,
7
- parameters: tool.parameters,
8
- output: { schema: { type: "string" }, render: (_args, value) => [{ type: "text", text: String(value) }] },
9
- isConcurrencySafe: () => tool.readOnly,
10
- execute: async (args, exec) => {
11
- const result = await tool.invoke({ sessionId, callId: exec.callId, input: (args ?? {}), signal: exec.signal });
12
- if (result.isError)
13
- throw new Error(result.text);
14
- if (result.images?.length)
15
- onImages?.(exec.callId, result.images);
16
- return result.text;
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) {
@@ -125,7 +125,7 @@ export function registerConformance(name, factory, options = {}) {
125
125
  await run(adapter, "sesn_can", "in_1", "x", ctl.signal);
126
126
  assert.ok(Date.now() - started < 5_000);
127
127
  });
128
- test(`[conformance:${name}] stop reasons: output limit, context overflow and stream idle are typed; a model failure is generic`, async (t) => {
128
+ test(`[conformance:${name}] stop reasons: output limit, context overflow, stream idle and a refused model request are typed`, async (t) => {
129
129
  const typed = (code) => (err) => err instanceof TurnStopError && err.code === code && err.message.startsWith(`${code}: `);
130
130
  const cut = await mount(t, { script: () => ({ text: "cut off", finishReason: "length" }) });
131
131
  await cut.adapter.createSession(init("sesn_s1"));
@@ -150,6 +150,6 @@ export function registerConformance(name, factory, options = {}) {
150
150
  assert.equal(idle.model.requests.length, 1, "content had arrived: not retried");
151
151
  const failed = await mount(t, { script: () => ({ status: 401 }) });
152
152
  await failed.adapter.createSession(init("sesn_s4"));
153
- await assert.rejects(run(failed.adapter, "sesn_s4", "in_1", "x"), (err) => !(err instanceof TurnStopError));
153
+ await assert.rejects(run(failed.adapter, "sesn_s4", "in_1", "x"), typed("model_request_failed_error"));
154
154
  });
155
155
  }
package/lib/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export * from "./spi.ts";
2
2
  export { DshAdapter, type DshAdapterOptions } from "./adapter.ts";
3
3
  export { mountKernel, COMPACTION_HEADROOM_TOKENS, COMPACTION_SUMMARY_MAX_TOKENS, type KernelOptions } from "./kernel.ts";
4
- export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, MODEL_STREAM_IDLE, PROVIDER, RecentToolImages, TOOL_IMAGE_CALLS, type ModelAdapterOptions, type RequestImage } from "./model.ts";
4
+ export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, DEFAULT_TRANSIENT_RETRY_BACKOFF_MS, MODEL_CONNECTION, MODEL_STREAM_IDLE, TRANSIENT_RETRIES, transientBackoffMs, retryAfterMs, PROVIDER, RecentToolImages, TOOL_IMAGE_INTERVAL, TOOL_IMAGE_KEEP, type ModelAdapterOptions, type RequestImage } from "./model.ts";
5
5
  export { ModelCatalog, DEFAULT_LIMITS, DEFAULT_REQUEST_MAX_TOKENS, requestMaxTokens, loadCatalogFile, parseLimits, type CatalogDefaults, type LimitsInput } from "./model-catalog.ts";
6
6
  export { restrictToPlatformTools, catalogViolation } from "./catalog-gate.ts";
7
7
  export { harnessEventsFromSessionEvent, harnessEventFromStreamFrame, cmaMessageEvent, cmaEventType, type CmaMessageEventType } from "./events.ts";
@@ -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, TOOL_IMAGE_CALLS } from "./model.js";
5
+ export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, DEFAULT_TRANSIENT_RETRY_BACKOFF_MS, MODEL_CONNECTION, MODEL_STREAM_IDLE, TRANSIENT_RETRIES, transientBackoffMs, retryAfterMs, PROVIDER, RecentToolImages, TOOL_IMAGE_INTERVAL, TOOL_IMAGE_KEEP } from "./model.js";
6
6
  export { ModelCatalog, DEFAULT_LIMITS, DEFAULT_REQUEST_MAX_TOKENS, requestMaxTokens, loadCatalogFile, parseLimits } from "./model-catalog.js";
7
7
  export { restrictToPlatformTools, catalogViolation } from "./catalog-gate.js";
8
8
  export { harnessEventsFromSessionEvent, harnessEventFromStreamFrame, cmaMessageEvent, cmaEventType } from "./events.js";
@@ -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 for the
24
- * most recent TOOL_IMAGE_CALLS calls of a session and sent with those results
25
- * only; older ones, and all of them after a restart, are left out (the result
26
- * text stays). Basis: Anthropic's computer-use reference loop keeps only the N
27
- * most recent screenshots in the request (only_n_most_recent_images, default
28
- * 3) — screenshots are large and only the latest describe the screen.
27
+ * Tool result images (computer_observe screenshots) are kept in memory per
28
+ * session and sent with their results; pruned ones, and all of them after a
29
+ * restart, are left out (the result text stays). Pruning is in batches: once
30
+ * more than TOOL_IMAGE_KEEP + TOOL_IMAGE_INTERVAL calls have images, the oldest
31
+ * TOOL_IMAGE_INTERVAL drop out together, so the request prefix stays
32
+ * byte-identical between two such steps and the provider's prompt cache keeps
33
+ * hitting (a sliding window changes the prefix on every request). Same rule as
34
+ * the Go brain (server/gobrain/application/toolimages.go), shared vectors
35
+ * test/brain-conformance/tool-image-pruning.vectors.json. Basis: Anthropic,
36
+ * "Best practices for computer and browser use with Claude" (rolling buffer,
37
+ * cache-aware: keep_n = 3, interval = 25).
29
38
  */
30
- export declare const TOOL_IMAGE_CALLS = 3;
39
+ export declare const TOOL_IMAGE_KEEP = 3;
40
+ export declare const TOOL_IMAGE_INTERVAL = 25;
31
41
  export declare class RecentToolImages {
32
42
  private readonly bySession;
33
43
  remember(sessionId: string, callId: string, images: readonly {
@@ -45,6 +55,26 @@ export declare class RecentToolImages {
45
55
  * we use 1 retry and 1-2s (Lead ruling). Once any content arrived nothing is retried.
46
56
  */
47
57
  export declare const DEFAULT_IDLE_RETRY_BACKOFF_MS: readonly [number, number];
58
+ /**
59
+ * A transient failure before any content is retried up to TRANSIENT_RETRIES times on a
60
+ * fresh request: HTTP 502/503/504, an error body with `retryable: true`, or a connection
61
+ * that failed before any response. The pause doubles from the first value up to the cap,
62
+ * less up to 25% jitter. Basis: the official OpenAI and Anthropic SDKs (max_retries=2,
63
+ * 0.5s doubling to 8s, jitter). Example: a rolling release of the model gateway refuses
64
+ * connections for a moment (BeeWork tsk_4ec607d9, 2026-11-14: one 503 ended the turn).
65
+ * A failure after content arrived is never retried.
66
+ *
67
+ * A `retry-after-ms` or `Retry-After` header (seconds or an HTTP date) on such a failure
68
+ * lengthens the pause when it is longer than the backoff (same rule as the Go brain,
69
+ * server/gobrain/domain/retry.go). One longer than the backoff cap is not waited for: the
70
+ * failure ends the turn as before, so a pause never exceeds the cap.
71
+ */
72
+ export declare const TRANSIENT_RETRIES = 2;
73
+ export declare const DEFAULT_TRANSIENT_RETRY_BACKOFF_MS: readonly [number, number];
74
+ /** retry-after-ms, then Retry-After as seconds or an HTTP date; undefined when absent, malformed or not in the future. */
75
+ export declare function retryAfterMs(headers: Headers, now?: number): number | undefined;
76
+ /** The pause before transient retry `n` (0-based): first * 2^n up to cap, less up to 25% jitter. */
77
+ export declare function transientBackoffMs(n: number, [first, cap]: readonly [number, number]): number;
48
78
  /**
49
79
  * Default stream idle limit. Same value as the Beework Desktop brain's model
50
80
  * stream guard (behaviour description only); no industry basis. Any received
package/lib/model.js CHANGED
@@ -3,26 +3,36 @@
3
3
  // ModelPort: each session carries its own platform-issued token, so the
4
4
  // platform attributes each request to exactly one session. A request without
5
5
  // a session is never sent (fail closed). No provider key lives in the brain.
6
- import { LlmAdapter, LlmError, CONTEXT_WINDOW_EXCEEDED_CODE, attributionHeaders, isContextWindowExceededError, offloadedImageText, projectOffloadedImages, } from "@deepseek-ai/dsh-llm";
6
+ import { LlmAdapter, LlmError, CONTEXT_WINDOW_EXCEEDED_CODE, QUOTA_EXCEEDED_CODE, attributionHeaders, isContextWindowExceededError, offloadedImageText, projectOffloadedImages, } from "@deepseek-ai/dsh-llm";
7
7
  import { requestMaxTokens } from "./model-catalog.js";
8
8
  export const PROVIDER = "bma";
9
9
  /** Error code of a model stream that sent no data for the idle limit (typed stop model_stream_idle). */
10
10
  export const MODEL_STREAM_IDLE = "MODEL_STREAM_IDLE";
11
+ /** Error code of a model request whose connection failed before any response (refused, reset, DNS). */
12
+ export const MODEL_CONNECTION = "MODEL_CONNECTION";
11
13
  /**
12
- * Tool result images (computer_observe screenshots) are kept in memory for the
13
- * most recent TOOL_IMAGE_CALLS calls of a session and sent with those results
14
- * only; older ones, and all of them after a restart, are left out (the result
15
- * text stays). Basis: Anthropic's computer-use reference loop keeps only the N
16
- * most recent screenshots in the request (only_n_most_recent_images, default
17
- * 3) — screenshots are large and only the latest describe the screen.
14
+ * Tool result images (computer_observe screenshots) are kept in memory per
15
+ * session and sent with their results; pruned ones, and all of them after a
16
+ * restart, are left out (the result text stays). Pruning is in batches: once
17
+ * more than TOOL_IMAGE_KEEP + TOOL_IMAGE_INTERVAL calls have images, the oldest
18
+ * TOOL_IMAGE_INTERVAL drop out together, so the request prefix stays
19
+ * byte-identical between two such steps and the provider's prompt cache keeps
20
+ * hitting (a sliding window changes the prefix on every request). Same rule as
21
+ * the Go brain (server/gobrain/application/toolimages.go), shared vectors
22
+ * test/brain-conformance/tool-image-pruning.vectors.json. Basis: Anthropic,
23
+ * "Best practices for computer and browser use with Claude" (rolling buffer,
24
+ * cache-aware: keep_n = 3, interval = 25).
18
25
  */
19
- export const TOOL_IMAGE_CALLS = 3;
26
+ export const TOOL_IMAGE_KEEP = 3;
27
+ export const TOOL_IMAGE_INTERVAL = 25;
20
28
  export class RecentToolImages {
21
29
  bySession = new Map();
22
30
  remember(sessionId, callId, images) {
31
+ if (!images.length)
32
+ return;
23
33
  const list = this.bySession.get(sessionId) ?? [];
24
34
  list.push({ callId, images: images.map((i) => ({ mediaType: i.mediaType, data: i.data })) });
25
- this.bySession.set(sessionId, list.slice(-TOOL_IMAGE_CALLS));
35
+ this.bySession.set(sessionId, list.length > TOOL_IMAGE_KEEP + TOOL_IMAGE_INTERVAL ? list.slice(TOOL_IMAGE_INTERVAL) : list);
26
36
  }
27
37
  get(sessionId, callId) {
28
38
  return this.bySession.get(sessionId)?.find((e) => e.callId === callId)?.images;
@@ -39,6 +49,63 @@ export class RecentToolImages {
39
49
  * we use 1 retry and 1-2s (Lead ruling). Once any content arrived nothing is retried.
40
50
  */
41
51
  export const DEFAULT_IDLE_RETRY_BACKOFF_MS = [1_000, 2_000];
52
+ /**
53
+ * A transient failure before any content is retried up to TRANSIENT_RETRIES times on a
54
+ * fresh request: HTTP 502/503/504, an error body with `retryable: true`, or a connection
55
+ * that failed before any response. The pause doubles from the first value up to the cap,
56
+ * less up to 25% jitter. Basis: the official OpenAI and Anthropic SDKs (max_retries=2,
57
+ * 0.5s doubling to 8s, jitter). Example: a rolling release of the model gateway refuses
58
+ * connections for a moment (BeeWork tsk_4ec607d9, 2026-11-14: one 503 ended the turn).
59
+ * A failure after content arrived is never retried.
60
+ *
61
+ * A `retry-after-ms` or `Retry-After` header (seconds or an HTTP date) on such a failure
62
+ * lengthens the pause when it is longer than the backoff (same rule as the Go brain,
63
+ * server/gobrain/domain/retry.go). One longer than the backoff cap is not waited for: the
64
+ * failure ends the turn as before, so a pause never exceeds the cap.
65
+ */
66
+ export const TRANSIENT_RETRIES = 2;
67
+ export const DEFAULT_TRANSIENT_RETRY_BACKOFF_MS = [500, 8_000];
68
+ const transientErrors = new WeakMap();
69
+ function transient(err, info) {
70
+ transientErrors.set(err, info);
71
+ return err;
72
+ }
73
+ function transientInfo(err) {
74
+ return err instanceof LlmError ? transientErrors.get(err) : undefined;
75
+ }
76
+ function parseBody(body) {
77
+ try {
78
+ const json = JSON.parse(body);
79
+ return json && typeof json === "object" ? json : undefined;
80
+ }
81
+ catch {
82
+ return undefined;
83
+ }
84
+ }
85
+ /** An error code from the body, only when it looks like an identifier (it goes to logs). */
86
+ function errorCode(json) {
87
+ const code = json?.error?.code ?? json?.error?.type;
88
+ return typeof code === "string" && /^[\w.-]{1,64}$/.test(code) ? code : undefined;
89
+ }
90
+ /** retry-after-ms, then Retry-After as seconds or an HTTP date; undefined when absent, malformed or not in the future. */
91
+ export function retryAfterMs(headers, now = Date.now()) {
92
+ const ms = Number(headers.get("retry-after-ms") ?? NaN);
93
+ if (Number.isFinite(ms) && ms > 0)
94
+ return ms;
95
+ const value = headers.get("retry-after")?.trim();
96
+ if (!value)
97
+ return undefined;
98
+ if (/^\d+(\.\d+)?$/.test(value)) {
99
+ const seconds = Number(value);
100
+ return seconds > 0 ? seconds * 1_000 : undefined;
101
+ }
102
+ const at = Date.parse(value);
103
+ return Number.isFinite(at) && at > now ? at - now : undefined;
104
+ }
105
+ /** The pause before transient retry `n` (0-based): first * 2^n up to cap, less up to 25% jitter. */
106
+ export function transientBackoffMs(n, [first, cap]) {
107
+ return Math.min(first * 2 ** n, cap) * (1 - Math.random() * 0.25);
108
+ }
42
109
  /**
43
110
  * Default stream idle limit. Same value as the Beework Desktop brain's model
44
111
  * stream guard (behaviour description only); no industry basis. Any received
@@ -115,11 +182,18 @@ async function toOpenAi(input, options, sessionId, system, signal) {
115
182
  flushToolImages();
116
183
  return out;
117
184
  }
118
- function failure(status, body) {
185
+ function failure(status, body, headers) {
119
186
  // The canonical overflow code lets dsh compact and retry (compaction-basic reacts to it).
187
+ // The others name the failure class, which stop.ts reports as the contract's model failure stop code.
120
188
  const code = isContextWindowExceededError(body) ? CONTEXT_WINDOW_EXCEEDED_CODE
121
- : status === 401 || status === 403 ? "AUTH" : status === 429 ? "RATE_LIMIT" : "PROVIDER_HTTP";
122
- return new LlmError(`model endpoint HTTP ${status}: ${body.slice(0, 300)}`, code, { status });
189
+ : status === 401 || status === 403 ? "AUTH" : status === 402 ? QUOTA_EXCEEDED_CODE : status === 429 ? "RATE_LIMIT"
190
+ : status >= 500 ? "SERVER" : "PROVIDER_HTTP";
191
+ const err = new LlmError(`model endpoint HTTP ${status}: ${body.slice(0, 300)}`, code, { status });
192
+ const json = parseBody(body);
193
+ if (status !== 502 && status !== 503 && status !== 504 && json?.error?.retryable !== true && json?.retryable !== true)
194
+ return err;
195
+ const after = headers ? retryAfterMs(headers) : undefined;
196
+ return transient(err, { reason: `HTTP ${status}${errorCode(json) ? ` ${errorCode(json)}` : ""}`, ...(after !== undefined ? { retryAfterMs: after } : {}) });
123
197
  }
124
198
  export class ChatCompletionsAdapter extends LlmAdapter {
125
199
  port;
@@ -151,7 +225,10 @@ export class ChatCompletionsAdapter extends LlmAdapter {
151
225
  // caller (loop or compaction) asked for is never above the ceiling, the model's real output limit.
152
226
  const maxTokens = Math.min(request.maxTokens ?? requestMaxTokens(limits), limits.maxOutputTokens);
153
227
  const [minPause, maxPause] = this.options.idleRetryBackoffMs ?? DEFAULT_IDLE_RETRY_BACKOFF_MS;
154
- for (let attempt = 0;; attempt++) {
228
+ const transientBackoff = this.options.transientRetryBackoffMs ?? DEFAULT_TRANSIENT_RETRY_BACKOFF_MS;
229
+ let idleRetried = false;
230
+ let transientRetries = 0;
231
+ for (;;) {
155
232
  const idle = new IdleGuard(this.options.streamIdleMs, request.signal);
156
233
  let content = false;
157
234
  try {
@@ -159,24 +236,41 @@ export class ChatCompletionsAdapter extends LlmAdapter {
159
236
  content = true; // the first chunk is a block-start, only ever produced by a content delta
160
237
  yield chunk;
161
238
  }
162
- if (attempt > 0)
239
+ if (idleRetried)
163
240
  this.port.idleRetry?.(sessionId, "recovered");
241
+ if (transientRetries > 0)
242
+ this.port.transientRetry?.(sessionId, "recovered");
164
243
  return;
165
244
  }
166
245
  catch (err) {
167
- if (!idle.fired)
246
+ if (idle.fired) {
247
+ const stop = new LlmError(`model stream idle: no data for ${this.options.streamIdleMs} ms`, MODEL_STREAM_IDLE, { cause: err });
248
+ if (content || request.signal?.aborted)
249
+ throw stop;
250
+ if (idleRetried) {
251
+ this.port.idleRetry?.(sessionId, "exhausted");
252
+ throw stop;
253
+ }
254
+ idleRetried = true;
255
+ this.port.idleRetry?.(sessionId, "retry");
256
+ await pause(minPause + Math.random() * (maxPause - minPause), request.signal);
257
+ if (request.signal?.aborted)
258
+ throw stop; // cancelled while waiting: give up, no new request
259
+ continue;
260
+ }
261
+ const info = transientInfo(err);
262
+ if (content || request.signal?.aborted || !info)
263
+ throw err;
264
+ const wait = Math.max(transientBackoffMs(transientRetries, transientBackoff), info.retryAfterMs ?? 0);
265
+ if (transientRetries >= TRANSIENT_RETRIES || wait > transientBackoff[1]) {
266
+ this.port.transientRetry?.(sessionId, "exhausted", info.reason);
168
267
  throw err;
169
- const stop = new LlmError(`model stream idle: no data for ${this.options.streamIdleMs} ms`, MODEL_STREAM_IDLE, { cause: err });
170
- if (content || request.signal?.aborted)
171
- throw stop;
172
- if (attempt > 0) {
173
- this.port.idleRetry?.(sessionId, "exhausted");
174
- throw stop;
175
268
  }
176
- this.port.idleRetry?.(sessionId, "retry");
177
- await pause(minPause + Math.random() * (maxPause - minPause), request.signal);
269
+ transientRetries++;
270
+ this.port.transientRetry?.(sessionId, "retry", info.reason);
271
+ await pause(wait, request.signal);
178
272
  if (request.signal?.aborted)
179
- throw stop; // cancelled while waiting: give up, no new request
273
+ throw err; // cancelled while waiting: give up, no new request
180
274
  }
181
275
  finally {
182
276
  idle.stop();
@@ -185,7 +279,7 @@ export class ChatCompletionsAdapter extends LlmAdapter {
185
279
  }
186
280
  async *run(request, sessionId, route, maxTokens, idle, started) {
187
281
  const messages = await toOpenAi(request.messages, this.options, sessionId, request.system, idle.signal);
188
- const response = await fetch(`${route.baseUrl.replace(/\/$/, "")}/chat/completions`, {
282
+ const response = await connect(`${route.baseUrl.replace(/\/$/, "")}/chat/completions`, {
189
283
  method: "POST",
190
284
  signal: idle.signal,
191
285
  headers: { ...attributionHeaders(), "content-type": "application/json", authorization: `Bearer ${route.token}` },
@@ -202,7 +296,7 @@ export class ChatCompletionsAdapter extends LlmAdapter {
202
296
  }),
203
297
  });
204
298
  if (!response.ok || !response.body)
205
- throw failure(response.status, await response.text().catch(() => ""));
299
+ throw failure(response.status, await response.text().catch(() => ""), response.headers);
206
300
  let next = 0;
207
301
  let textIdx;
208
302
  let reasoningIdx;
@@ -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
- ...(u.prompt_tokens_details?.cached_tokens !== undefined ? { cacheReadTokens: u.prompt_tokens_details.cached_tokens } : {}),
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
@@ -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. Files meant for the user go under /mnt/session/outputs.",
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
- res.write(`data: ${JSON.stringify({ choices: [], usage: { prompt_tokens: 11, completion_tokens: 7, total_tokens: 18 } })}\n\n`);
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.2.2",
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",