@beeos-ai/bma-dsh-adapter 0.1.0 → 0.2.0

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`、流空闲守卫 | `model-limits.test.ts` |
14
+ | `model.ts`、`model-catalog.ts` | OpenAI Chat 适配器:按模型取 max_tokens / 窗口(声明 > 目录文件 > 保守默认,记录)、图片 `image_url`、流空闲守卫(首个内容增量前空闲:退避 1–2 s 自动重试 1 次,已有内容后不重试) | `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
@@ -6,6 +6,8 @@ export interface DshAdapterOptions {
6
6
  maxParallelToolCalls?: number;
7
7
  /** Model stream idle limit in ms (0 disables); default DEFAULT_STREAM_IDLE_MS. */
8
8
  streamIdleMs?: number;
9
+ /** Pause range (ms) before the one retry of a stream that idled before any content; default 1000..2000. */
10
+ idleRetryBackoffMs?: readonly [number, number];
9
11
  }
10
12
  export declare class DshAdapter implements HarnessAdapter {
11
13
  readonly id = "dsh";
@@ -14,7 +16,9 @@ export declare class DshAdapter implements HarnessAdapter {
14
16
  private readonly sessions;
15
17
  private tools;
16
18
  private readonly streamIdleMs;
19
+ private readonly idleRetryBackoffMs;
17
20
  private port;
21
+ private readonly toolImages;
18
22
  private constructor();
19
23
  static mount(options: DshAdapterOptions): Promise<DshAdapter>;
20
24
  capabilities(): HarnessCapabilities;
@@ -28,6 +32,12 @@ export declare class DshAdapter implements HarnessAdapter {
28
32
  submitInput(sessionId: string, input: HarnessInput, signal: AbortSignal): AsyncIterable<HarnessEvent>;
29
33
  /** Text-only input only: the host queues an input with images as the next turn instead. */
30
34
  appendInput(sessionId: string, input: HarnessInput): void;
35
+ /**
36
+ * Whether this build can take image input: the attachment service decodes
37
+ * images with sharp (a native module), which a single-file build may lack.
38
+ * Probed with a 1x1 PNG (content-addressed, so it is stored once).
39
+ */
40
+ probeImageInput(): Promise<boolean>;
31
41
  /** The user message content; images are validated, normalized and stored by the attachment service first. */
32
42
  private content;
33
43
  /**
package/lib/adapter.js CHANGED
@@ -3,10 +3,11 @@ import { SessionId } from "@deepseek-ai/dsh-session";
3
3
  import {} from "./spi.js";
4
4
  import { AsyncQueue } from "./async-queue.js";
5
5
  import { restrictToPlatformTools } from "./catalog-gate.js";
6
+ import { requestMaxTokens } from "./model-catalog.js";
6
7
  import { harnessEventFromStreamFrame, harnessEventsFromSessionEvent } from "./events.js";
7
8
  import { CONTINUE_NOTE, assertResumable, continuationId, hasRecordedInput } from "./recovery.js";
8
9
  import { mountKernel } from "./kernel.js";
9
- import { ChatCompletionsAdapter, DEFAULT_STREAM_IDLE_MS, PROVIDER } from "./model.js";
10
+ import { ChatCompletionsAdapter, DEFAULT_STREAM_IDLE_MS, PROVIDER, RecentToolImages } from "./model.js";
10
11
  import { stopForTurnEnd } from "./stop.js";
11
12
  /**
12
13
  * Target size of an image in a model request (no industry basis): long edge
@@ -15,6 +16,7 @@ import { stopForTurnEnd } from "./stop.js";
15
16
  * endpoint answers an oversized request with an error rather than dropping it.
16
17
  */
17
18
  const REQUEST_IMAGE_TARGET = { width: 2048, height: 2048, maxBytes: 3_932_160 };
19
+ const PROBE_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
18
20
  export class DshAdapter {
19
21
  id = "dsh";
20
22
  /** The dsh kernel (exposed for the fail-closed gate tests). */
@@ -22,14 +24,17 @@ export class DshAdapter {
22
24
  sessions = new Map();
23
25
  tools = [];
24
26
  streamIdleMs;
27
+ idleRetryBackoffMs;
25
28
  port;
26
- constructor(ctx, streamIdleMs) {
29
+ toolImages = new RecentToolImages();
30
+ constructor(ctx, streamIdleMs, idleRetryBackoffMs) {
27
31
  this.ctx = ctx;
28
32
  this.streamIdleMs = streamIdleMs;
33
+ this.idleRetryBackoffMs = idleRetryBackoffMs;
29
34
  }
30
35
  static async mount(options) {
31
36
  const ctx = await mountKernel({ home: options.home, ...(options.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: options.maxParallelToolCalls } : {}) });
32
- return new DshAdapter(ctx, options.streamIdleMs ?? DEFAULT_STREAM_IDLE_MS);
37
+ return new DshAdapter(ctx, options.streamIdleMs ?? DEFAULT_STREAM_IDLE_MS, options.idleRetryBackoffMs);
33
38
  }
34
39
  capabilities() {
35
40
  return { resume: true, deltas: true, midTurnInput: true, imageInput: true };
@@ -39,6 +44,8 @@ export class DshAdapter {
39
44
  const attachments = this.ctx.attachments;
40
45
  this.ctx.llm.registerAdapter([PROVIDER], new ChatCompletionsAdapter(port, {
41
46
  streamIdleMs: this.streamIdleMs,
47
+ ...(this.idleRetryBackoffMs ? { idleRetryBackoffMs: this.idleRetryBackoffMs } : {}),
48
+ toolImages: (sessionId, callId) => this.toolImages.get(sessionId, callId),
42
49
  readImage: async (block, signal) => {
43
50
  const image = await attachments.readImageRequest(block.attachment, REQUEST_IMAGE_TARGET, signal);
44
51
  return { mediaType: image.mediaType, data: Buffer.from(image.data).toString("base64") };
@@ -62,7 +69,7 @@ export class DshAdapter {
62
69
  const state = { init };
63
70
  const setup = (scope) => {
64
71
  scope.systemPrompt.section({ name: "bma", order: 0, complete: true, interpolate: false, text: () => state.init.systemPrompt });
65
- restrictToPlatformTools(scope, init.sessionId, this.tools);
72
+ restrictToPlatformTools(scope, init.sessionId, this.tools, (callId, images) => this.toolImages.remember(init.sessionId, callId, images));
66
73
  scope.on("session/event", (session, event) => {
67
74
  if (session.id === sessionId)
68
75
  this.onSessionEvent(state, event);
@@ -109,7 +116,8 @@ export class DshAdapter {
109
116
  const reason = end?.data?.reason;
110
117
  if (!reason)
111
118
  throw new Error("dsh turn ended without a turn/end event");
112
- const stop = stopForTurnEnd(reason, { maxOutputTokens: this.port?.limits(state.init.model).maxOutputTokens, streamIdleMs: this.streamIdleMs });
119
+ const limits = this.port?.limits(state.init.model);
120
+ const stop = stopForTurnEnd(reason, { maxOutputTokens: limits && requestMaxTokens(limits), streamIdleMs: this.streamIdleMs });
113
121
  if (stop)
114
122
  throw stop;
115
123
  }
@@ -119,6 +127,20 @@ export class DshAdapter {
119
127
  throw new Error("appendInput does not take images");
120
128
  this.get(sessionId).handle.agent.followup(userMessage(input.id, [{ type: "text", text: input.text }]));
121
129
  }
130
+ /**
131
+ * Whether this build can take image input: the attachment service decodes
132
+ * images with sharp (a native module), which a single-file build may lack.
133
+ * Probed with a 1x1 PNG (content-addressed, so it is stored once).
134
+ */
135
+ async probeImageInput() {
136
+ try {
137
+ await this.ctx.attachments.admitPromptContent([{ type: "image", mediaType: "image/png", data: PROBE_PNG }]);
138
+ return true;
139
+ }
140
+ catch {
141
+ return false;
142
+ }
143
+ }
122
144
  /** The user message content; images are validated, normalized and stored by the attachment service first. */
123
145
  async content(input) {
124
146
  if (!input.images?.length)
@@ -161,6 +183,7 @@ export class DshAdapter {
161
183
  if (!state)
162
184
  return;
163
185
  this.sessions.delete(sessionId);
186
+ this.toolImages.forget(sessionId);
164
187
  try {
165
188
  await this.ctx.sessions.flush(state.handle.agent.session);
166
189
  }
@@ -1,5 +1,7 @@
1
1
  import type { Context } from "@deepseek-ai/cordis";
2
- import type { PlatformTool } from "./spi.ts";
3
- export declare function restrictToPlatformTools(scope: Context, sessionId: string, tools: readonly PlatformTool[]): void;
2
+ import type { InputImage, PlatformTool } from "./spi.ts";
3
+ /** Receives the images of a tool result (they are not part of the stored result; see model.ts). */
4
+ export type ToolImageSink = (callId: string, images: readonly InputImage[]) => void;
5
+ export declare function restrictToPlatformTools(scope: Context, sessionId: string, tools: readonly PlatformTool[], onImages?: ToolImageSink): void;
4
6
  /** Why a session must be refused, or undefined when the catalog is exactly the expected tools. */
5
7
  export declare function catalogViolation(harnessId: string, expected: readonly string[], actual: readonly string[]): string | undefined;
@@ -1,4 +1,4 @@
1
- export function restrictToPlatformTools(scope, sessionId, tools) {
1
+ export function restrictToPlatformTools(scope, sessionId, tools, onImages) {
2
2
  scope.tools.restrict({ allow: [] });
3
3
  for (const tool of tools) {
4
4
  scope.tools.register({
@@ -11,6 +11,8 @@ export function restrictToPlatformTools(scope, sessionId, tools) {
11
11
  const result = await tool.invoke({ sessionId, callId: exec.callId, input: (args ?? {}), signal: exec.signal });
12
12
  if (result.isError)
13
13
  throw new Error(result.text);
14
+ if (result.images?.length)
15
+ onImages?.(exec.callId, result.images);
14
16
  return result.text;
15
17
  },
16
18
  });
@@ -17,6 +17,7 @@ import { last, textOf, toolNames } from "../testing/scripted-model.js";
17
17
  import { composeSystemPrompt, BASE_SYSTEM_PROMPT } from "../system-prompt.js";
18
18
  import { registerShellConformance } from "./shell.js";
19
19
  export { CANCEL_ACK_BUDGET_MS } from "./shell.js";
20
+ const ONE_PIXEL_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
20
21
  const init = (sessionId) => ({ sessionId, model: "m-1", systemPrompt: "You are a BMA agent.", cwd: "/workspace" });
21
22
  async function run(adapter, sid, id, text, signal = new AbortController().signal) {
22
23
  const events = [];
@@ -64,6 +65,18 @@ export function registerConformance(name, factory, options = {}) {
64
65
  await run(adapter, "sesn_cat", "in_1", "hi");
65
66
  assert.deepEqual(toolNames(model.requests[0]), [...FIXTURE_TOOL_NAMES].sort());
66
67
  });
68
+ test(`[conformance:${name}] image input: an image of the user input reaches the model as an image part`, async (t) => {
69
+ const { adapter, model } = await mount(t, { script: () => ({ text: "seen" }) });
70
+ if (!adapter.capabilities().imageInput)
71
+ return t.skip("the harness does not take image input");
72
+ await adapter.createSession(init("sesn_img"));
73
+ const events = [];
74
+ for await (const e of adapter.submitInput("sesn_img", { id: "in_1", text: "what is it?", images: [{ mediaType: "image/png", data: ONE_PIXEL_PNG }] }, new AbortController().signal))
75
+ events.push(e);
76
+ const content = last(model.requests[0]).content;
77
+ assert.ok(Array.isArray(content) && content.some((p) => p.type === "image_url" && /^data:image\//.test(p.image_url?.url ?? "")), `the model got ${JSON.stringify(content).slice(0, 200)}`);
78
+ assert.ok(events.some((e) => e.type === "message" && e.text === "seen"));
79
+ });
67
80
  test(`[conformance:${name}] system prompt: base + agent.system, no harness identity`, async (t) => {
68
81
  const { adapter, model } = await mount(t, { script: () => ({ text: "ok" }) });
69
82
  for (const [sid, system] of [["sesn_sp1", undefined], ["sesn_sp2", "Answer in French."]]) {
@@ -123,6 +136,18 @@ export function registerConformance(name, factory, options = {}) {
123
136
  const idle = await mount(t, { streamIdleMs: 300, script: () => ({ text: "partial", hang: true }) });
124
137
  await idle.adapter.createSession(init("sesn_s3"));
125
138
  await assert.rejects(run(idle.adapter, "sesn_s3", "in_1", "x"), typed("model_stream_idle"));
139
+ // Idle before any content is retried once on a fresh request (official SDK practice); after content it is not.
140
+ let seen = 0;
141
+ const retried = await mount(t, { streamIdleMs: 300, script: () => (seen++ === 0 ? { hang: true } : { text: "recovered" }) });
142
+ await retried.adapter.createSession(init("sesn_s5"));
143
+ const events = await run(retried.adapter, "sesn_s5", "in_1", "x");
144
+ assert.equal(retried.model.requests.length, 2, "one retry");
145
+ assert.ok(events.some((e) => e.type === "message"));
146
+ const twice = await mount(t, { streamIdleMs: 200, script: () => ({ hang: true }) });
147
+ await twice.adapter.createSession(init("sesn_s6"));
148
+ await assert.rejects(run(twice.adapter, "sesn_s6", "in_1", "x"), typed("model_stream_idle"));
149
+ assert.equal(twice.model.requests.length, 2, "exactly one retry, then the typed stop");
150
+ assert.equal(idle.model.requests.length, 1, "content had arrived: not retried");
126
151
  const failed = await mount(t, { script: () => ({ status: 401 }) });
127
152
  await failed.adapter.createSession(init("sesn_s4"));
128
153
  await assert.rejects(run(failed.adapter, "sesn_s4", "in_1", "x"), (err) => !(err instanceof TurnStopError));
package/lib/index.d.ts CHANGED
@@ -1,8 +1,8 @@
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_STREAM_IDLE_MS, MODEL_STREAM_IDLE, PROVIDER, type ModelAdapterOptions, type RequestImage } from "./model.ts";
5
- export { ModelCatalog, DEFAULT_LIMITS, loadCatalogFile, parseLimits, type CatalogDefaults, type LimitsInput } from "./model-catalog.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";
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";
8
8
  export { approvalId, permissionRequest, refusalFor, type PermissionAnswer, type PermissionRequest } from "./approval.ts";
package/lib/index.js CHANGED
@@ -2,8 +2,8 @@
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_STREAM_IDLE_MS, MODEL_STREAM_IDLE, PROVIDER } from "./model.js";
6
- export { ModelCatalog, DEFAULT_LIMITS, loadCatalogFile, parseLimits } from "./model-catalog.js";
5
+ export { ChatCompletionsAdapter, DEFAULT_IDLE_RETRY_BACKOFF_MS, DEFAULT_STREAM_IDLE_MS, MODEL_STREAM_IDLE, PROVIDER, RecentToolImages, TOOL_IMAGE_CALLS } from "./model.js";
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";
9
9
  export { approvalId, permissionRequest, refusalFor } from "./approval.js";
@@ -15,6 +15,22 @@ export interface CatalogDefaults {
15
15
  * as output_limit_reached rather than failing obscurely.
16
16
  */
17
17
  export declare const DEFAULT_LIMITS: CatalogDefaults;
18
+ /**
19
+ * What an ordinary model request asks for as max_tokens, at most: the lower of
20
+ * this and the model's output ceiling (ModelLimits.maxOutputTokens, what the
21
+ * model CAN produce). Asking for the ceiling on every call is wrong for
22
+ * upstreams that prepay: OpenRouter holds input + max_tokens against the
23
+ * balance and refuses a request whose maximum it cannot cover (402), even
24
+ * though the reply would have been short. 32000 is Claude Code's default for a
25
+ * model it does not know (CLAUDE_CODE_MAX_OUTPUT_TOKENS) and leaves room for
26
+ * the reasoning that counts against max_tokens (OpenAI advises 25k+). A reply
27
+ * that still hits it ends the turn as output_limit_reached. The compaction
28
+ * summary asks for its own, larger amount (COMPACTION_SUMMARY_MAX_TOKENS) and
29
+ * is only bounded by the ceiling.
30
+ */
31
+ export declare const DEFAULT_REQUEST_MAX_TOKENS = 32000;
32
+ /** The max_tokens an ordinary request carries for a model with these limits. */
33
+ export declare function requestMaxTokens(limits: ModelLimits): number;
18
34
  export declare function parseLimits(raw: unknown, where: string): LimitsInput;
19
35
  /** Reads the operator catalog: {"<model id>": {"context_window": N, "max_output_tokens": N}, "*": {...}}. */
20
36
  export declare function loadCatalogFile(path: string): Record<string, LimitsInput>;
@@ -18,6 +18,24 @@ import { readFileSync } from "node:fs";
18
18
  * as output_limit_reached rather than failing obscurely.
19
19
  */
20
20
  export const DEFAULT_LIMITS = { contextWindow: 128_000, maxOutputTokens: 8192 };
21
+ /**
22
+ * What an ordinary model request asks for as max_tokens, at most: the lower of
23
+ * this and the model's output ceiling (ModelLimits.maxOutputTokens, what the
24
+ * model CAN produce). Asking for the ceiling on every call is wrong for
25
+ * upstreams that prepay: OpenRouter holds input + max_tokens against the
26
+ * balance and refuses a request whose maximum it cannot cover (402), even
27
+ * though the reply would have been short. 32000 is Claude Code's default for a
28
+ * model it does not know (CLAUDE_CODE_MAX_OUTPUT_TOKENS) and leaves room for
29
+ * the reasoning that counts against max_tokens (OpenAI advises 25k+). A reply
30
+ * that still hits it ends the turn as output_limit_reached. The compaction
31
+ * summary asks for its own, larger amount (COMPACTION_SUMMARY_MAX_TOKENS) and
32
+ * is only bounded by the ceiling.
33
+ */
34
+ export const DEFAULT_REQUEST_MAX_TOKENS = 32_000;
35
+ /** The max_tokens an ordinary request carries for a model with these limits. */
36
+ export function requestMaxTokens(limits) {
37
+ return Math.min(limits.maxOutputTokens, DEFAULT_REQUEST_MAX_TOKENS);
38
+ }
21
39
  function positive(value, where) {
22
40
  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0)
23
41
  throw new Error(`${where} must be a positive integer`);
package/lib/model.d.ts CHANGED
@@ -14,7 +14,37 @@ export interface ModelAdapterOptions {
14
14
  streamIdleMs: number;
15
15
  /** Encodes one stored image as a request version for this route. */
16
16
  readImage: (block: ImageBlock, signal?: AbortSignal) => Promise<RequestImage>;
17
+ /** Pause before the one idle retry, uniform in [min, max] ms; default DEFAULT_IDLE_RETRY_BACKOFF_MS. */
18
+ idleRetryBackoffMs?: readonly [number, number];
19
+ /** The images of a tool result the model still sees (RecentToolImages), by session and call. */
20
+ toolImages?: (sessionId: string, callId: string) => readonly RequestImage[] | undefined;
17
21
  }
22
+ /**
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.
29
+ */
30
+ export declare const TOOL_IMAGE_CALLS = 3;
31
+ export declare class RecentToolImages {
32
+ private readonly bySession;
33
+ remember(sessionId: string, callId: string, images: readonly {
34
+ mediaType: string;
35
+ data: string;
36
+ }[]): void;
37
+ get(sessionId: string, callId: string): readonly RequestImage[] | undefined;
38
+ forget(sessionId: string): void;
39
+ }
40
+ /**
41
+ * Idle before any content delta (no text / reasoning / tool-call delta yet) is retried
42
+ * once on a fresh request after this pause. Basis: the official Anthropic and OpenAI SDKs
43
+ * retry connection errors and timeouts automatically only while no response content has
44
+ * been received (max_retries=2 by default, exponential backoff 0.5s..8s with jitter);
45
+ * we use 1 retry and 1-2s (Lead ruling). Once any content arrived nothing is retried.
46
+ */
47
+ export declare const DEFAULT_IDLE_RETRY_BACKOFF_MS: readonly [number, number];
18
48
  /**
19
49
  * Default stream idle limit. Same value as the Beework Desktop brain's model
20
50
  * stream guard (behaviour description only); no industry basis. Any received
package/lib/model.js CHANGED
@@ -4,9 +4,41 @@
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
6
  import { LlmAdapter, LlmError, CONTEXT_WINDOW_EXCEEDED_CODE, attributionHeaders, isContextWindowExceededError, offloadedImageText, projectOffloadedImages, } from "@deepseek-ai/dsh-llm";
7
+ import { requestMaxTokens } from "./model-catalog.js";
7
8
  export const PROVIDER = "bma";
8
9
  /** Error code of a model stream that sent no data for the idle limit (typed stop model_stream_idle). */
9
10
  export const MODEL_STREAM_IDLE = "MODEL_STREAM_IDLE";
11
+ /**
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.
18
+ */
19
+ export const TOOL_IMAGE_CALLS = 3;
20
+ export class RecentToolImages {
21
+ bySession = new Map();
22
+ remember(sessionId, callId, images) {
23
+ const list = this.bySession.get(sessionId) ?? [];
24
+ list.push({ callId, images: images.map((i) => ({ mediaType: i.mediaType, data: i.data })) });
25
+ this.bySession.set(sessionId, list.slice(-TOOL_IMAGE_CALLS));
26
+ }
27
+ get(sessionId, callId) {
28
+ return this.bySession.get(sessionId)?.find((e) => e.callId === callId)?.images;
29
+ }
30
+ forget(sessionId) {
31
+ this.bySession.delete(sessionId);
32
+ }
33
+ }
34
+ /**
35
+ * Idle before any content delta (no text / reasoning / tool-call delta yet) is retried
36
+ * once on a fresh request after this pause. Basis: the official Anthropic and OpenAI SDKs
37
+ * retry connection errors and timeouts automatically only while no response content has
38
+ * been received (max_retries=2 by default, exponential backoff 0.5s..8s with jitter);
39
+ * we use 1 retry and 1-2s (Lead ruling). Once any content arrived nothing is retried.
40
+ */
41
+ export const DEFAULT_IDLE_RETRY_BACKOFF_MS = [1_000, 2_000];
10
42
  /**
11
43
  * Default stream idle limit. Same value as the Beework Desktop brain's model
12
44
  * stream guard (behaviour description only); no industry basis. Any received
@@ -34,10 +66,20 @@ async function userContent(blocks, options, signal) {
34
66
  }
35
67
  return parts;
36
68
  }
37
- async function toOpenAi(input, options, system, signal) {
69
+ async function toOpenAi(input, options, sessionId, system, signal) {
38
70
  const messages = projectOffloadedImages(input, (ref) => offloadedImageText(ref));
39
71
  const out = system ? [{ role: "system", content: system }] : [];
72
+ // Chat Completions tool messages carry text only: the images of a run of
73
+ // tool results follow it as one user message (text naming the call + image).
74
+ let toolImages = [];
75
+ const flushToolImages = () => {
76
+ if (toolImages.length)
77
+ out.push({ role: "user", content: toolImages });
78
+ toolImages = [];
79
+ };
40
80
  for (const m of messages) {
81
+ if (m.role !== "tool")
82
+ flushToolImages();
41
83
  switch (m.role) {
42
84
  case "system":
43
85
  case "developer": {
@@ -58,11 +100,19 @@ async function toOpenAi(input, options, system, signal) {
58
100
  });
59
101
  break;
60
102
  }
61
- case "tool":
62
- out.push({ role: "tool", tool_call_id: m.toolCallId, content: text(m.content) });
103
+ case "tool": {
104
+ const images = options.toolImages?.(sessionId, m.toolCallId) ?? [];
105
+ out.push({ role: "tool", tool_call_id: m.toolCallId, content: text(m.content) + (images.length ? `\n[${images.length} image(s) of this result follow]` : "") });
106
+ if (images.length) {
107
+ toolImages.push({ type: "text", text: `Image(s) returned by tool call ${m.toolCallId}:` });
108
+ for (const image of images)
109
+ toolImages.push({ type: "image_url", image_url: { url: `data:${image.mediaType};base64,${image.data}` } });
110
+ }
63
111
  break;
112
+ }
64
113
  }
65
114
  }
115
+ flushToolImages();
66
116
  return out;
67
117
  }
68
118
  function failure(status, body) {
@@ -82,7 +132,7 @@ export class ChatCompletionsAdapter extends LlmAdapter {
82
132
  /** Window and output cap come from the host's model catalog, never from constants here. */
83
133
  async resolveModel(provider, model) {
84
134
  const limits = this.port.limits(model);
85
- return { provider, id: model, name: model, context: { contextWindow: limits.contextWindow }, defaultMaxTokens: limits.maxOutputTokens };
135
+ return { provider, id: model, name: model, context: { contextWindow: limits.contextWindow }, defaultMaxTokens: requestMaxTokens(limits) };
86
136
  }
87
137
  async *stream(request) {
88
138
  const sessionId = request.sessionId;
@@ -97,23 +147,44 @@ export class ChatCompletionsAdapter extends LlmAdapter {
97
147
  }
98
148
  const started = performance.now();
99
149
  const limits = this.port.limits(route.model);
100
- // Never above the model's real output cap, whatever the caller (loop or compaction) asked for.
101
- const maxTokens = Math.min(request.maxTokens ?? limits.maxOutputTokens, limits.maxOutputTokens);
102
- const idle = new IdleGuard(this.options.streamIdleMs, request.signal);
103
- try {
104
- yield* this.run(request, sessionId, route, maxTokens, idle, started);
105
- }
106
- catch (err) {
107
- if (idle.fired)
108
- throw new LlmError(`model stream idle: no data for ${this.options.streamIdleMs} ms`, MODEL_STREAM_IDLE, { cause: err });
109
- throw err;
110
- }
111
- finally {
112
- idle.stop();
150
+ // An ordinary request asks for the per-request cap, not the model's ceiling; whatever the
151
+ // caller (loop or compaction) asked for is never above the ceiling, the model's real output limit.
152
+ const maxTokens = Math.min(request.maxTokens ?? requestMaxTokens(limits), limits.maxOutputTokens);
153
+ const [minPause, maxPause] = this.options.idleRetryBackoffMs ?? DEFAULT_IDLE_RETRY_BACKOFF_MS;
154
+ for (let attempt = 0;; attempt++) {
155
+ const idle = new IdleGuard(this.options.streamIdleMs, request.signal);
156
+ let content = false;
157
+ try {
158
+ for await (const chunk of this.run(request, sessionId, route, maxTokens, idle, started)) {
159
+ content = true; // the first chunk is a block-start, only ever produced by a content delta
160
+ yield chunk;
161
+ }
162
+ if (attempt > 0)
163
+ this.port.idleRetry?.(sessionId, "recovered");
164
+ return;
165
+ }
166
+ catch (err) {
167
+ if (!idle.fired)
168
+ 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
+ }
176
+ this.port.idleRetry?.(sessionId, "retry");
177
+ await pause(minPause + Math.random() * (maxPause - minPause), request.signal);
178
+ if (request.signal?.aborted)
179
+ throw stop; // cancelled while waiting: give up, no new request
180
+ }
181
+ finally {
182
+ idle.stop();
183
+ }
113
184
  }
114
185
  }
115
186
  async *run(request, sessionId, route, maxTokens, idle, started) {
116
- const messages = await toOpenAi(request.messages, this.options, request.system, idle.signal);
187
+ const messages = await toOpenAi(request.messages, this.options, sessionId, request.system, idle.signal);
117
188
  const response = await fetch(`${route.baseUrl.replace(/\/$/, "")}/chat/completions`, {
118
189
  method: "POST",
119
190
  signal: idle.signal,
@@ -246,6 +317,16 @@ export class ChatCompletionsAdapter extends LlmAdapter {
246
317
  yield { type: "finish", reason };
247
318
  }
248
319
  }
320
+ /** Resolves after ms, or at once when the signal aborts. */
321
+ function pause(ms, signal) {
322
+ return new Promise((resolve) => {
323
+ if (signal?.aborted)
324
+ return resolve();
325
+ const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", done); resolve(); };
326
+ const timer = setTimeout(done, ms);
327
+ signal?.addEventListener("abort", done, { once: true });
328
+ });
329
+ }
249
330
  /** Aborts the request when nothing arrived for `ms`; touch() on every received chunk. Chains the caller's signal. */
250
331
  class IdleGuard {
251
332
  #ms;
package/lib/spi.d.ts CHANGED
@@ -13,6 +13,8 @@ export interface ToolCall {
13
13
  export interface ToolResult {
14
14
  readonly text: string;
15
15
  readonly isError: boolean;
16
+ /** Images the model sees with the result (for example a computer_observe screenshot). */
17
+ readonly images?: readonly InputImage[];
16
18
  }
17
19
  /**
18
20
  * A tool the platform provides. invoke() runs the whole platform path: the
@@ -20,7 +22,8 @@ export interface ToolResult {
20
22
  * gateway and the agent.tool_result event. The adapter only forwards calls.
21
23
  */
22
24
  export interface PlatformTool {
23
- readonly name: ToolName;
25
+ /** One of the six ToolName, or a tool the host declares for its machine (such as computer_action). */
26
+ readonly name: string;
24
27
  readonly description: string;
25
28
  /** JSON Schema of the input object. */
26
29
  readonly parameters: Readonly<Record<string, unknown>>;
@@ -46,7 +49,7 @@ export interface ModelUsage {
46
49
  export interface ModelLimits {
47
50
  /** Combined request + response context, in tokens. */
48
51
  readonly contextWindow: number;
49
- /** Largest completion the model may produce; the cap sent as max_tokens. */
52
+ /** Largest completion the model can produce (a ceiling). An ordinary request asks for less: requestMaxTokens(). */
50
53
  readonly maxOutputTokens: number;
51
54
  /** declared: the platform said so in turn.start; catalog: operator catalog; default: neither knew the model (conservative values). */
52
55
  readonly source: "declared" | "catalog" | "default";
@@ -60,6 +63,13 @@ export interface ModelPort {
60
63
  /** The first streamed model chunk of a request arrived, ms after it was sent. */
61
64
  firstChunk(sessionId: string, ms: number): void;
62
65
  usage(sessionId: string, usage: ModelUsage): void;
66
+ /**
67
+ * The model stream went idle before any content and the adapter reacted:
68
+ * "retry" (a fresh request follows), "recovered" (the retry delivered content),
69
+ * "exhausted" (the retry idled too; the turn fails with model_stream_idle).
70
+ * Hosts count it as model_stream_idle_retry_total{result} and log it.
71
+ */
72
+ idleRetry?(sessionId: string, result: "retry" | "recovered" | "exhausted"): void;
63
73
  }
64
74
  export interface HarnessCapabilities {
65
75
  /** Continues a session from the harness's own durable state in a fresh process. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@beeos-ai/bma-dsh-adapter",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
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",
@@ -9,7 +9,7 @@
9
9
  "acp",
10
10
  "managed-agents"
11
11
  ],
12
- "homepage": "https://bma.beeos.ai",
12
+ "homepage": "https://staging.bma.beeos.ai",
13
13
  "repository": {
14
14
  "type": "git",
15
15
  "url": "git+https://github.com/beeos-ai/beeos-managed-agents.git",