@beeos-ai/bma-dsh-acp 0.1.0 → 0.2.1

package/README.md

@@ -7,7 +7,7 @@ It has no DSH dependency of its own (test `pins`), runs the shared conformance s
 ## Install and run (npm)
 
 ```sh
-npx --yes @beeos-ai/bma-dsh-acp@0.1.0      # one-off; or: npm install -g @beeos-ai/bma-dsh-acp
+npx --yes @beeos-ai/bma-dsh-acp@0.2.1      # one-off; or: npm install -g @beeos-ai/bma-dsh-acp
 BMA_DSH_ACP_HOME=$HOME/.bma-dsh-acp bma-dsh-acp   # ACP (JSON-RPC, newline-delimited) on stdin/stdout
 ```
 
@@ -29,10 +29,10 @@ Using it from the BMA executor SDK (`bma-executor-sdk`, Go `ACPAgent`; the SDK n
 
 ```go
 agent, err := bmaexecutor.NewACPAgent(ctx, bmaexecutor.ACPAgentOptions{
-    // installed once with `npm install -g @beeos-ai/bma-dsh-acp@0.1.0` (the `bma-dsh-acp` bin of that prefix):
+    // installed once with `npm install -g @beeos-ai/bma-dsh-acp@0.2.1` (the `bma-dsh-acp` bin of that prefix):
     Command: []string{"/usr/local/bin/bma-dsh-acp"},
     // or fetched on first use (slow first start; the cache keeps it afterwards):
-    // Command: []string{"/usr/local/bin/npx", "--yes", "@beeos-ai/bma-dsh-acp@0.1.0"},
+    // Command: []string{"/usr/local/bin/npx", "--yes", "@beeos-ai/bma-dsh-acp@0.2.1"},
     StateDir: stateDir, // becomes BMA_DSH_ACP_HOME
     Core:     core,
     Upstream: bmaexecutor.ACPModelUpstream{BaseURL: "https://api.example.com/v1", Model: "my-model"},
@@ -45,14 +45,16 @@ Standard ACP v1 (`@agentclientprotocol/sdk`), plus BMA additions under the `bma`
 
 | ACP | bma-dsh-acp |
 |---|---|
-| `initialize` | `loadSession`, image prompts; `_meta.bma` = `{dsh, tools, streaming: "token", permissionRelay: "full", modes}` |
-| `session/new`, `session/load` | `_meta.bma` = `{sessionId?, systemPrompt?, model: {baseUrl, token, model, contextWindow?, maxOutputTokens?}}` (required: no model request without an attributable route). `sessionId` = platform session id = DSH session id. Response `_meta.bma.toolCatalog` (the six CMA tools; anything else is refused, fail-closed). `load` replays the conversation as `session/update`; an unknown session is `-32002` |
+| `initialize` | `loadSession`, image prompts; `_meta.bma` = `{dsh, tools, hostTools, streaming: "token", permissionRelay: "full", modes}`. Request `_meta.bma.hostTools` = `[{name, description, parameters, readOnly, kind, permission?}]`: tools the client's machine adds to the six (for example `computer_observe`, `computer_action`, `ask_user_question`); registered for every session, asked for by `permission` (`ask` by default, `allow`), run by the client like the six |
+| `session/new`, `session/load` | `_meta.bma` = `{sessionId?, systemPrompt?, model: {baseUrl, token, model, contextWindow?, maxOutputTokens?}}` (required: no model request without an attributable route). `sessionId` = platform session id = DSH session id. Response `_meta.bma.toolCatalog` (the six CMA tools plus the declared host tools; anything else is refused, fail-closed). `load` replays the conversation as `session/update`; an unknown session is `-32002` |
 | `session/set_mode` | `default` (ask before bash/write/edit) or `accept_edits` (ask before bash); read/glob/grep never ask |
 | `session/prompt` | `_meta.bma` = `{inputId?, toolPolicy?}` (`toolPolicy`: per-tool allow/ask/deny for this prompt, e.g. from turn.start `tool_policy`). Streams `agent_message_chunk` / `agent_thought_chunk` with a `messageId`; the durable text of that message is the notification `_bma/message {sessionId, messageId, kind, text}` |
-| tool call | `tool_call` (`kind`, full `rawInput`, `_meta.bma {name, permission}`) → `session/request_permission` (full input; `allow_once` / `reject_once`) when the policy says ask → request `_bma/tools/call {sessionId, toolCallId, name, input}` → `{text, isError}` (the client runs it) → `tool_call_update` completed/failed with the result |
+| tool call | `tool_call` (`kind`, full `rawInput`, `_meta.bma {name, permission}`) → `session/request_permission` (full input; `allow_once` / `reject_once`) when the policy says ask → request `_bma/tools/call {sessionId, toolCallId, name, input}` → `{text, isError, images?: [{mimeType, data}]}` (the client runs it; images are shown to the model after the tool message, as a user message — Chat Completions tool messages carry text only) → `tool_call_update` completed/failed with the result |
 | `session/cancel` | the turn ends with `stopReason: cancelled`; a pending permission or tool call is abandoned (`$/cancel_request` is sent for it) |
 | stops | `output_limit_reached` → `stopReason: max_tokens` + `_meta.bma {stopCode, detail}`; `context_too_large`, `model_stream_idle` → JSON-RPC error `-32603` with `data.bma {stopCode, detail}`; other failures → `-32603` |
-| `session/close` | releases the session (its JSONL stays for a later load) |
+| `session/close` | releases the session's agent scope (its memory; its JSONL stays, so `session/load` brings the whole conversation back); advertised as `agentCapabilities.sessionCapabilities.close`. A client that keeps many sessions (the executor SDK's `ACPAgent` keeps at most `MaxResidentSessions` and closes the least recently used idle one) is what bounds the memory of this process: it holds every session that was opened and not closed. Closing a session that is not open answers `-32002`, which the ACP SDK treats as closed |
+
+Sessions share one DSH kernel in the process; each session is its own agent scope (conversation, tool catalog, model route, permissions): session-level isolation, not one DSH context per session.
 
 Environment: `BMA_DSH_ACP_HOME` (state directory, required), `BMA_DSH_ACP_STREAM_IDLE_MS`, `BRAIN_MODEL_CATALOG`. stdout carries ACP only (console output goes to stderr).
 

package/lib/agent.js

@@ -1,8 +1,11 @@
 // bma-dsh-acp: the shared DSH adapter served as an ACP agent (ADR 0027).
 //
 //   ACP                       shared adapter / client
-//   initialize                capabilities + _meta.bma facts (dsh version, tools, streaming, permission relay)
+//   initialize                capabilities + _meta.bma facts (dsh version, tools, streaming, permission relay);
+//                             request _meta.bma.hostTools adds the client machine's own tools to the six
 //   session/new | load        createSession | resumeSession (+ history replay); _meta.bma carries the model route
+//   session/close            releases the session's agent scope (memory); its JSONL stays for session/load. Advertised as
+//                             sessionCapabilities.close, so a client can keep many sessions by closing the least recently used
 //   session/set_mode          per-session tool policy (default | accept_edits)
 //   session/prompt            submitInput: deltas -> agent_*_chunk (messageId), durable -> _bma/message
 //   tool call                 tool_call -> [request_permission] -> _bma/tools/call (client runs it) -> tool_call_update
@@ -20,6 +23,8 @@ import { TOOL_SPECS } from "./tools.js";
 export const VERSION = shellPkg.version;
 const SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
 const MEDIA = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+const HOST_TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/;
+const KINDS = new Set(["read", "edit", "delete", "move", "search", "execute", "think", "fetch", "switch_mode", "other"]);
 export class DshAcpShell {
     app;
     client;
@@ -27,12 +32,16 @@ export class DshAcpShell {
     declared = new Map();
     adapter;
     catalog;
+    /** This build decodes images (DshAdapter.probeImageInput); without it image prompts are refused. */
+    imageInput = false;
+    /** The client machine's tools (initialize _meta.bma.hostTools). */
+    hostTools = [];
     constructor(adapter, catalog) {
         this.adapter = adapter;
         this.catalog = catalog;
         this.app = acpAgent({ name: "bma-dsh-acp" })
             .onConnect((conn) => { this.client = conn.client; })
-            .onRequest("initialize", () => this.initialize())
+            .onRequest("initialize", ({ params }) => this.initialize(params))
             .onRequest("session/new", ({ params }) => this.open(params, false))
             .onRequest("session/load", ({ params }) => this.open(params, true))
             .onRequest("session/set_mode", ({ params }) => this.setMode(params))
@@ -52,9 +61,13 @@ export class DshAcpShell {
                 return { baseUrl: s.model.baseUrl, token: s.model.token, model: s.model.model };
             },
             firstChunk: () => { },
+            idleRetry: (sid, result) => { process.stderr.write(`bma-dsh-acp: model stream idle before any content (session ${sid}): ${result}\n`); },
             usage: () => { }, // metered by the client's model proxy
         });
-        adapter.registerTools(TOOL_SPECS.map((spec) => shell.tool(spec)));
+        shell.registerTools();
+        shell.imageInput = await adapter.probeImageInput();
+        if (!shell.imageInput)
+            process.stderr.write("bma-dsh-acp: image input is unavailable in this build (the image decoder could not be loaded); image prompts are refused\n");
         return shell;
     }
     async dispose() {
@@ -62,13 +75,23 @@ export class DshAcpShell {
             s.running?.abort();
         await this.adapter.dispose();
     }
-    initialize() {
+    registerTools() {
+        this.adapter.registerTools([...TOOL_SPECS, ...this.hostTools].map((spec) => this.tool(spec)));
+    }
+    toolNames() {
+        return [...TOOL_NAMES, ...this.hostTools.map((t) => t.name)];
+    }
+    initialize(params) {
+        if (this.sessions.size)
+            throw RequestError.invalidRequest(undefined, "initialize after a session was opened");
+        this.hostTools = hostToolsMeta(params._meta);
+        this.registerTools();
         return {
             protocolVersion: PROTOCOL_VERSION,
-            agentCapabilities: { loadSession: true, promptCapabilities: { image: true, audio: false, embeddedContext: false }, mcpCapabilities: { http: false, sse: false } },
+            agentCapabilities: { loadSession: true, sessionCapabilities: { close: {} }, promptCapabilities: { image: this.imageInput, audio: false, embeddedContext: false }, mcpCapabilities: { http: false, sse: false } },
             agentInfo: { name: "bma-dsh-acp", title: "BMA DSH", version: VERSION },
             authMethods: [],
-            _meta: { [META]: { dsh: DSH_VERSION, tools: TOOL_NAMES, streaming: "token", permissionRelay: "full", modes: Object.keys(MODES) } },
+            _meta: { [META]: { dsh: DSH_VERSION, tools: TOOL_NAMES, hostTools: this.hostTools.map((t) => t.name), streaming: "token", permissionRelay: "full", modes: Object.keys(MODES) } },
         };
     }
     async open(params, load) {
@@ -86,7 +109,7 @@ export class DshAcpShell {
             open.model = meta.model; // a reload in the same process: new route, same conversation
         }
         else {
-            const s = { id, model: meta.model, mode: "default", policy: modePolicy("default"), ids: freshIds(), chain: Promise.resolve() };
+            const s = { id, model: meta.model, mode: "default", policy: modePolicy("default", this.hostTools), ids: freshIds(), chain: Promise.resolve() };
             this.sessions.set(id, s); // the route must exist before the first model request
             const init = { sessionId: id, model: meta.model.model, systemPrompt: meta.systemPrompt ?? "", cwd: params.cwd };
             try {
@@ -103,7 +126,7 @@ export class DshAcpShell {
             }
         }
         const catalog = [...this.adapter.toolCatalog(id)];
-        const violation = catalogViolation("dsh", TOOL_NAMES, catalog);
+        const violation = catalogViolation("dsh", this.toolNames(), catalog);
         if (violation) {
             await this.close(id);
             throw RequestError.internalError(undefined, violation);
@@ -131,16 +154,18 @@ export class DshAcpShell {
             throw RequestError.invalidParams(undefined, `unknown mode ${params.modeId}`);
         s.mode = params.modeId;
         if (!s.running)
-            s.policy = modePolicy(s.mode);
+            s.policy = modePolicy(s.mode, this.hostTools);
         return {};
     }
     async prompt(params) {
         const s = this.get(params.sessionId);
         if (s.running)
             throw RequestError.invalidRequest(undefined, "a prompt is already running in this session");
-        const meta = promptMeta(params._meta);
-        s.policy = { ...modePolicy(s.mode), ...meta.toolPolicy };
+        const meta = promptMeta(params._meta, this.toolNames());
+        s.policy = { ...modePolicy(s.mode, this.hostTools), ...meta.toolPolicy };
         const input = { id: meta.inputId ?? randomUUID(), ...promptInput(params.prompt) };
+        if (input.images && !this.imageInput)
+            throw RequestError.invalidParams(undefined, "image input is unavailable in this build of bma-dsh-acp");
         const ctl = new AbortController();
         s.running = ctl;
         try {
@@ -166,7 +191,7 @@ export class DshAcpShell {
         }
         finally {
             s.running = undefined;
-            s.policy = modePolicy(s.mode);
+            s.policy = modePolicy(s.mode, this.hostTools);
             s.ids = freshIds();
         }
     }
@@ -211,7 +236,7 @@ export class DshAcpShell {
     async invoke(spec, call) {
         const s = this.get(call.sessionId);
         const client = this.client;
-        const permission = s.policy[spec.name];
+        const permission = s.policy[spec.name] ?? "ask";
         // Let the turn's queued message events go out first (they were produced before this call).
         await new Promise((resolve) => setImmediate(resolve));
         s.ids = freshIds();
@@ -247,7 +272,9 @@ export class DshAcpShell {
             const result = await untilAborted(client.request(TOOLS_CALL, { sessionId: s.id, toolCallId: call.callId, name: spec.name, input: call.input }, { cancellationSignal: call.signal }), call.signal);
             if (!result)
                 return finish(aborted());
-            return finish({ text: String(result.text ?? ""), isError: Boolean(result.isError) });
+            const images = (result.images ?? []).filter((i) => MEDIA.has(i.mimeType) && typeof i.data === "string" && i.data)
+                .map((i) => ({ mediaType: i.mimeType, data: i.data }));
+            return finish({ text: String(result.text ?? ""), isError: Boolean(result.isError), ...(images.length ? { images } : {}) });
         }
         catch (err) {
             if (call.signal.aborted)
@@ -317,7 +344,35 @@ function sessionMeta(raw) {
         model: { baseUrl: String(model.baseUrl), token: model.token, model: model.model, ...(contextWindow ? { contextWindow } : {}), ...(maxOutputTokens ? { maxOutputTokens } : {}) },
     };
 }
-function promptMeta(raw) {
+function hostToolsMeta(raw) {
+    const tools = bmaMeta(raw)?.hostTools;
+    if (tools === undefined)
+        return [];
+    if (!Array.isArray(tools))
+        throw RequestError.invalidParams(undefined, "_meta.bma.hostTools must be an array");
+    const seen = new Set(TOOL_NAMES);
+    return tools.map((t, i) => {
+        const at = `_meta.bma.hostTools[${i}]`;
+        if (typeof t !== "object" || t === null)
+            throw RequestError.invalidParams(undefined, `${at} must be an object`);
+        if (typeof t.name !== "string" || !HOST_TOOL_NAME.test(t.name) || seen.has(t.name))
+            throw RequestError.invalidParams(undefined, `${at}.name must be a new snake_case tool name`);
+        seen.add(t.name);
+        if (typeof t.description !== "string" || !t.description)
+            throw RequestError.invalidParams(undefined, `${at}.description is required`);
+        const p = t.parameters;
+        if (typeof p !== "object" || p === null || p.type !== "object")
+            throw RequestError.invalidParams(undefined, `${at}.parameters must be an object JSON Schema`);
+        if (typeof t.readOnly !== "boolean")
+            throw RequestError.invalidParams(undefined, `${at}.readOnly must be a boolean`);
+        if (typeof t.kind !== "string" || !KINDS.has(t.kind))
+            throw RequestError.invalidParams(undefined, `${at}.kind must be an ACP tool kind`);
+        if (t.permission !== undefined && t.permission !== "allow" && t.permission !== "ask")
+            throw RequestError.invalidParams(undefined, `${at}.permission must be allow or ask`);
+        return { name: t.name, description: t.description, parameters: p, readOnly: t.readOnly, kind: t.kind, ...(t.permission ? { permission: t.permission } : {}) };
+    });
+}
+function promptMeta(raw, names) {
     const meta = bmaMeta(raw) ?? {};
     const out = {};
     if (meta.inputId !== undefined) {
@@ -330,7 +385,7 @@ function promptMeta(raw) {
         if (typeof policy !== "object" || policy === null)
             throw RequestError.invalidParams(undefined, "_meta.bma.toolPolicy must be an object");
         for (const [name, value] of Object.entries(policy)) {
-            if (!TOOL_NAMES.includes(name) || !["allow", "ask", "deny"].includes(value)) {
+            if (!names.includes(name) || !["allow", "ask", "deny"].includes(value)) {
                 throw RequestError.invalidParams(undefined, `_meta.bma.toolPolicy.${name} must be allow, ask or deny for a known tool`);
             }
         }

package/lib/protocol.js

@@ -7,8 +7,11 @@ export const MODES = {
     default: { name: "Ask before changes", description: "Ask before bash, write and edit; read, glob and grep run without asking." },
     accept_edits: { name: "Accept edits", description: "Ask before bash; write, edit and the read-only tools run without asking." },
 };
-export function modePolicy(mode) {
+export function modePolicy(mode, hostTools = []) {
     const ask = "ask";
     const edits = mode === "accept_edits" ? "allow" : "ask";
-    return { bash: ask, write: edits, edit: edits, read: "allow", glob: "allow", grep: "allow" };
+    const policy = { bash: ask, write: edits, edit: edits, read: "allow", glob: "allow", grep: "allow" };
+    for (const tool of hostTools)
+        policy[tool.name] = tool.permission ?? "ask";
+    return policy;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeos-ai/bma-dsh-acp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "bma-dsh-acp: the shared DSH adapter served as an Agent Client Protocol (stdio) agent, driven by the BMA executor's ACP client.",
   "keywords": [
     "dsh",
@@ -10,7 +10,7 @@
     "agent-client-protocol",
     "managed-agents"
   ],
-  "homepage": "https://bma.beeos.ai",
+  "homepage": "https://staging.bma.beeos.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/beeos-ai/beeos-managed-agents.git",
@@ -27,7 +27,7 @@
   "dependencies": {
     "@agentclientprotocol/sdk": "2.2.0",
     "zod": "4.6.7",
-    "@beeos-ai/bma-dsh-adapter": "0.1.0"
+    "@beeos-ai/bma-dsh-adapter": "0.2.1"
   },
   "devDependencies": {
     "esbuild": "0.28.2"