@beeos-ai/bma-dsh-acp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,11 @@
+@beeos-ai/bma-dsh-acp
+Copyright 2026 BeeOS
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This package contains original BeeOS code (it is not derived from the
+Omnara-based platform sources). It does not contain code from the BeeOS
+desktop application or any other code under an internal license.
+
+The DSH libraries (@deepseek-ai/*, MIT) and the other dependencies are not
+bundled: they are installed from the npm registry under their own licenses.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# bma-dsh-acp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared DSH adapter (`@beeos-ai/bma-dsh-adapter`) served as an [Agent Client Protocol](https://agentclientprotocol.com) agent on stdio ([ADR-0027](../../../docs/adr/0027-one-dsh-kernel-many-host-shells.md)). The BMA executor (bma-executor-sdk, Go) starts it and drives it with its ACP client; it replaces `dsh --profile acp` on users' computers and in sandboxes. Apache-2.0.
+
+It has no DSH dependency of its own (test `pins`), runs the shared conformance suite through a real child process over ACP (`test/conformance.test.ts`), and never runs a tool itself: tools run on the executor's machine (its execution core), so the hands are the same as for a platform brain.
+
+## Install and run (npm)
+
+```sh
+npx --yes @beeos-ai/bma-dsh-acp@0.2.0      # 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
+```
+
+- **Node >= 24** (the package ships JavaScript; no TypeScript flags needed). Tested on Linux x64 and macOS arm64 (the ACP and conformance suites run against the npm-installed bin, `scripts/check-npm.sh`); Windows is untested.
+- `BMA_DSH_ACP_HOME` is required (the agent's state directory, see Environment below). stdout carries ACP only.
+- **DSH is not bundled.** npm installs the official [`@deepseek-ai/*`](https://www.npmjs.com/org/deepseek-ai) packages. Their versions are pinned exactly by `@beeos-ai/bma-dsh-adapter` (today DSH `0.2.2-rc.1`, also reported as `_meta.bma.dsh` by `initialize`), including the transitive ranges DSH leaves open (cosmokit, schemastery, the flock addon), so one package version always installs the same DSH. The native parts come from those dependencies: the flock Node-API addon from the per-platform `@deepseek-ai/node-addon-system-<platform>-<arch>` package (installed through `optionalDependencies`, so do not install with `--omit=optional`), the JSONL verification worker as a plain file of `dsh-session-persistence-jsonl`.
+- Pin the version in your launcher (`@0.1.0` above): `npx` without a version takes the newest release.
+
+Which form to use:
+
+| | npm package (this section) | Single-file bundle (`scripts/build.ts`) |
+|---|---|---|
+| For | developers, CLI, a local brain on your own computer | BMA Desktop, the sandbox machine templates |
+| DSH | official npm packages, exact-pinned, installed by npm | inlined into `bma-dsh-acp.mjs` / SEA, sha256-pinned by the template |
+| Needs | Node >= 24 and network access to npm at install | Node >= 24 (`.mjs`) or nothing (SEA) |
+| Releases | tag `dsh-acp-vX.Y.Z` (`.github/workflows/dsh-acp-release.yaml`), versions of the two packages move together | built with the host application / template |
+
+Using it from the BMA executor SDK (`bma-executor-sdk`, Go `ACPAgent`; the SDK never looks the command up on `PATH`, so `Command[0]` is an absolute path):
+
+```go
+agent, err := bmaexecutor.NewACPAgent(ctx, bmaexecutor.ACPAgentOptions{
+    // installed once with `npm install -g @beeos-ai/bma-dsh-acp@0.2.0` (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.2.0"},
+    StateDir: stateDir, // becomes BMA_DSH_ACP_HOME
+    Core:     core,
+    Upstream: bmaexecutor.ACPModelUpstream{BaseURL: "https://api.example.com/v1", Model: "my-model"},
+})
+```
+
+## Protocol
+
+Standard ACP v1 (`@agentclientprotocol/sdk`), plus BMA additions under the `bma` `_meta` key and `_bma/` methods (ACP extensibility). Shapes: `src/protocol.ts`.
+
+| ACP | bma-dsh-acp |
+|---|---|
+| `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, 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) |
+
+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).
+
+## Build (bundle and npm form)
+
+```sh
+node scripts/build.ts            # dist/bma-dsh-acp.mjs + dist/bma-dsh-acp (SEA; needs an official Node >= 25.5 with --build-sea)
+node scripts/build.ts --no-sea   # dist/bma-dsh-acp.mjs only (run with node >= 24)
+BMA_DSH_ACP_BIN=/somewhere/else/bma-dsh-acp node --test --test-concurrency=1 'test/**/*.test.ts'   # the suites against a build
+BMA_DSH_ACP_BIN=$PWD/dist/bma-dsh-acp node scripts/measure.ts                              # startup and RSS
+```
+
+`pnpm --filter @beeos-ai/bma-dsh-adapter run build && pnpm --filter @beeos-ai/bma-dsh-acp run build:npm` produces the npm form (`lib/`, JavaScript; `bash scripts/check-npm.sh` packs, installs and tests it).
+
+The bundle builds are for the build host's OS/arch. The DSH JSONL verification worker and the flock Node-API addon are embedded and written once to `$BMA_DSH_ACP_HOME/.runtime/` (see `scripts/build.ts`).
+
+Measured on macOS arm64 (2026-11-09, scripted model, `scripts/measure.ts`):
+
+| Build | Size | Start → initialized | RSS idle | RSS 1 session + turn | RSS 10 sessions |
+|---|---|---|---|---|---|
+| `src/main.ts` (node 26.7) | — | 340–470 ms | 125–131 MiB | 130–134 MiB | 144–150 MiB |
+| `dist/bma-dsh-acp.mjs` (node 26.7) | 2.97 MB | 300–325 ms | 84 MiB | 90 MiB | 114 MiB |
+| `dist/bma-dsh-acp` SEA (node 26.13) | 148.7 MB | 260–350 ms | 91–92 MiB | 102 MiB | 124 MiB |
+
+For comparison, `dsh --profile acp` measured about 280 MB per process (LB0 spike).

package/lib/agent.js

@@ -0,0 +1,409 @@
+// 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);
+//                             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/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
+//   session/cancel            aborts the turn: pending permission / tool call are abandoned, stopReason cancelled
+//   stops                     output_limit_reached -> max_tokens; other typed stops -> JSON-RPC error data.bma
+//
+// Tools never run in this process: the executor runs them on its machine
+// (its execution core), so the hands are the same as for a platform brain.
+import { randomUUID } from "node:crypto";
+import { agent as acpAgent, PROTOCOL_VERSION, RequestError } from "@agentclientprotocol/sdk";
+import { DSH_VERSION, DshAdapter, ModelCatalog, SessionNotFoundError, TurnStopError, catalogViolation, refusalFor, } from "@beeos-ai/bma-dsh-adapter";
+import shellPkg from "../package.json" with { type: "json" };
+import { MESSAGE, META, MODES, TOOLS_CALL, TOOL_NAMES, modePolicy, } from "./protocol.js";
+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;
+    sessions = new Map();
+    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", ({ 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))
+            .onRequest("session/prompt", ({ params }) => this.prompt(params))
+            .onRequest("session/close", ({ params }) => this.close(params.sessionId))
+            .onNotification("session/cancel", ({ params }) => { this.sessions.get(params.sessionId)?.running?.abort(); });
+    }
+    static async create(options) {
+        const adapter = await DshAdapter.mount({ home: options.home, ...(options.streamIdleMs !== undefined ? { streamIdleMs: options.streamIdleMs } : {}) });
+        const shell = new DshAcpShell(adapter, options.catalog ?? new ModelCatalog());
+        adapter.configureModel({
+            limits: (model) => shell.declared.get(model) ?? shell.catalog.resolve(model),
+            route: (sessionId) => {
+                const s = shell.sessions.get(sessionId);
+                if (!s)
+                    throw new Error(`no model route for session ${sessionId}`);
+                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
+        });
+        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() {
+        for (const s of this.sessions.values())
+            s.running?.abort();
+        await this.adapter.dispose();
+    }
+    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: 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, hostTools: this.hostTools.map((t) => t.name), streaming: "token", permissionRelay: "full", modes: Object.keys(MODES) } },
+        };
+    }
+    async open(params, load) {
+        const meta = sessionMeta(params._meta);
+        const id = load ? params.sessionId : (meta.sessionId ?? randomUUID());
+        if (!SESSION_ID.test(id))
+            throw RequestError.invalidParams(undefined, "session id");
+        const open = this.sessions.get(id);
+        if (open && !load)
+            throw RequestError.invalidParams(undefined, `session ${id} is already open`);
+        if (meta.model.contextWindow && meta.model.maxOutputTokens) {
+            this.declared.set(meta.model.model, { contextWindow: meta.model.contextWindow, maxOutputTokens: Math.min(meta.model.maxOutputTokens, Math.floor(meta.model.contextWindow / 2)), source: "declared" });
+        }
+        if (open) {
+            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", 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 {
+                if (load)
+                    await this.adapter.resumeSession(init);
+                else
+                    await this.adapter.createSession(init);
+            }
+            catch (err) {
+                this.sessions.delete(id);
+                if (err instanceof SessionNotFoundError)
+                    throw RequestError.sessionNotFound(id);
+                throw err;
+            }
+        }
+        const catalog = [...this.adapter.toolCatalog(id)];
+        const violation = catalogViolation("dsh", this.toolNames(), catalog);
+        if (violation) {
+            await this.close(id);
+            throw RequestError.internalError(undefined, violation);
+        }
+        if (load)
+            await this.replay(this.sessions.get(id));
+        const s = this.sessions.get(id);
+        return {
+            sessionId: id,
+            modes: { currentModeId: s.mode, availableModes: Object.entries(MODES).map(([modeId, m]) => ({ id: modeId, name: m.name, description: m.description })) },
+            _meta: { [META]: { toolCatalog: catalog } },
+        };
+    }
+    /** ACP session/load: the agent MUST stream the whole conversation back before answering. */
+    async replay(s) {
+        for (const item of this.adapter.history(s.id)) {
+            const sessionUpdate = item.role === "user" ? "user_message_chunk" : item.type === "thinking" ? "agent_thought_chunk" : "agent_message_chunk";
+            this.send(s, "session/update", { sessionId: s.id, update: { sessionUpdate, content: { type: "text", text: item.text } } });
+        }
+        await s.chain;
+    }
+    setMode(params) {
+        const s = this.get(params.sessionId);
+        if (!(params.modeId in MODES))
+            throw RequestError.invalidParams(undefined, `unknown mode ${params.modeId}`);
+        s.mode = params.modeId;
+        if (!s.running)
+            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, 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 {
+            try {
+                for await (const event of this.adapter.submitInput(s.id, input, ctl.signal))
+                    this.emit(s, event);
+            }
+            finally {
+                await s.chain;
+            }
+            return { stopReason: ctl.signal.aborted ? "cancelled" : "end_turn" };
+        }
+        catch (err) {
+            if (ctl.signal.aborted)
+                return { stopReason: "cancelled" };
+            if (err instanceof TurnStopError) {
+                const stop = { stopCode: err.code, detail: err.message.slice(err.code.length + 2) };
+                if (err.code === "output_limit_reached")
+                    return { stopReason: "max_tokens", _meta: { [META]: stop } };
+                throw new RequestError(-32603, err.message, { [META]: stop });
+            }
+            throw new RequestError(-32603, err.message);
+        }
+        finally {
+            s.running = undefined;
+            s.policy = modePolicy(s.mode, this.hostTools);
+            s.ids = freshIds();
+        }
+    }
+    async close(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            throw RequestError.sessionNotFound(sessionId);
+        s.running?.abort();
+        this.sessions.delete(sessionId);
+        await this.adapter.close(sessionId);
+        return {};
+    }
+    get(sessionId) {
+        const s = this.sessions.get(sessionId);
+        if (!s)
+            throw RequestError.sessionNotFound(sessionId);
+        return s;
+    }
+    send(s, method, params) {
+        const client = this.client;
+        s.chain = s.chain.then(() => client.notify(method, params)).catch(() => { });
+    }
+    emit(s, event) {
+        if (event.type === "delta") {
+            const sessionUpdate = event.kind === "message" ? "agent_message_chunk" : "agent_thought_chunk";
+            this.send(s, "session/update", { sessionId: s.id, update: { sessionUpdate, messageId: s.ids[event.kind], content: { type: "text", text: event.text } } });
+            return;
+        }
+        this.send(s, MESSAGE, { sessionId: s.id, messageId: s.ids[event.type], kind: event.type, text: event.text });
+        s.ids[event.type] = randomUUID();
+    }
+    tool(spec) {
+        return {
+            name: spec.name,
+            description: spec.description,
+            parameters: spec.parameters,
+            readOnly: spec.readOnly,
+            invoke: (call) => this.invoke(spec, call),
+        };
+    }
+    /** tool_call -> [request_permission] -> _bma/tools/call -> tool_call_update. Every outcome is a result the model reads. */
+    async invoke(spec, call) {
+        const s = this.get(call.sessionId);
+        const client = this.client;
+        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();
+        const toolCall = { toolCallId: call.callId, title: spec.name, kind: spec.kind, status: "pending", rawInput: call.input };
+        this.send(s, "session/update", { sessionId: s.id, update: { sessionUpdate: "tool_call", ...toolCall, _meta: { [META]: { name: spec.name, permission } } } });
+        const finish = async (result) => {
+            this.send(s, "session/update", {
+                sessionId: s.id,
+                update: { sessionUpdate: "tool_call_update", toolCallId: call.callId, status: result.isError ? "failed" : "completed", content: [{ type: "content", content: { type: "text", text: result.text } }] },
+            });
+            await s.chain;
+            return result;
+        };
+        const aborted = () => ({ text: "The tool call was cancelled.", isError: true });
+        if (permission === "deny")
+            return finish({ text: `The ${spec.name} tool is not allowed in this session.`, isError: true });
+        if (permission === "ask") {
+            await s.chain;
+            const answer = await untilAborted(client.request("session/request_permission", {
+                sessionId: s.id,
+                toolCall,
+                options: [{ optionId: "allow", name: "Allow", kind: "allow_once" }, { optionId: "reject", name: "Reject", kind: "reject_once" }],
+            }, { cancellationSignal: call.signal }), call.signal);
+            if (!answer || answer.outcome.outcome === "cancelled")
+                return finish(aborted());
+            const refusal = refusalFor(spec.name, { outcome: answer.outcome.optionId === "allow" ? "allow" : "deny" });
+            if (refusal)
+                return finish(refusal);
+        }
+        this.send(s, "session/update", { sessionId: s.id, update: { sessionUpdate: "tool_call_update", toolCallId: call.callId, status: "in_progress" } });
+        await s.chain;
+        try {
+            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());
+            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)
+                return finish(aborted());
+            return finish({ text: `The tool call failed on the executor: ${err.message}`, isError: true });
+        }
+    }
+}
+function freshIds() {
+    return { message: randomUUID(), thinking: randomUUID() };
+}
+/** Resolves undefined once signal aborts; the request's own settlement is then ignored. */
+function untilAborted(p, signal) {
+    if (signal.aborted) {
+        p.catch(() => { });
+        return Promise.resolve(undefined);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => resolve(undefined);
+        signal.addEventListener("abort", onAbort, { once: true });
+        p.then((v) => { signal.removeEventListener("abort", onAbort); resolve(v); }, (e) => { signal.removeEventListener("abort", onAbort); if (signal.aborted)
+            resolve(undefined);
+        else
+            reject(e); });
+    });
+}
+// --- validation at the protocol boundary ---
+function bmaMeta(meta) {
+    const value = meta?.[META];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw RequestError.invalidParams(undefined, "_meta.bma must be an object");
+    return value;
+}
+function sessionMeta(raw) {
+    const meta = bmaMeta(raw);
+    const model = meta?.model;
+    if (!model || typeof model.model !== "string" || !model.model || typeof model.token !== "string" || !model.token) {
+        throw RequestError.invalidParams(undefined, "_meta.bma.model {baseUrl, token, model} is required");
+    }
+    let url;
+    try {
+        url = new URL(String(model.baseUrl));
+    }
+    catch {
+        throw RequestError.invalidParams(undefined, "_meta.bma.model.baseUrl must be an http(s) URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw RequestError.invalidParams(undefined, "_meta.bma.model.baseUrl must be an http(s) URL");
+    const count = (v, name) => {
+        if (v === undefined)
+            return undefined;
+        if (!Number.isSafeInteger(v) || v <= 0)
+            throw RequestError.invalidParams(undefined, `_meta.bma.model.${name} must be a positive integer`);
+        return v;
+    };
+    const contextWindow = count(model.contextWindow, "contextWindow");
+    const maxOutputTokens = count(model.maxOutputTokens, "maxOutputTokens");
+    if (meta.sessionId !== undefined && typeof meta.sessionId !== "string")
+        throw RequestError.invalidParams(undefined, "_meta.bma.sessionId must be a string");
+    if (meta.systemPrompt !== undefined && typeof meta.systemPrompt !== "string")
+        throw RequestError.invalidParams(undefined, "_meta.bma.systemPrompt must be a string");
+    return {
+        ...(meta.sessionId !== undefined ? { sessionId: meta.sessionId } : {}),
+        ...(meta.systemPrompt !== undefined ? { systemPrompt: meta.systemPrompt } : {}),
+        model: { baseUrl: String(model.baseUrl), token: model.token, model: model.model, ...(contextWindow ? { contextWindow } : {}), ...(maxOutputTokens ? { maxOutputTokens } : {}) },
+    };
+}
+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) {
+        if (typeof meta.inputId !== "string" || !meta.inputId)
+            throw RequestError.invalidParams(undefined, "_meta.bma.inputId must be a non-empty string");
+        out.inputId = meta.inputId;
+    }
+    if (meta.toolPolicy !== undefined) {
+        const policy = meta.toolPolicy;
+        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 (!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`);
+            }
+        }
+        out.toolPolicy = policy;
+    }
+    return out;
+}
+function promptInput(blocks) {
+    const text = [];
+    const images = [];
+    for (const b of blocks) {
+        if (b.type === "text")
+            text.push(b.text);
+        else if (b.type === "image") {
+            if (!MEDIA.has(b.mimeType))
+                throw RequestError.invalidParams(undefined, `image type ${b.mimeType} is not supported`);
+            images.push({ mediaType: b.mimeType, data: b.data });
+        }
+        else
+            throw RequestError.invalidParams(undefined, `prompt content ${b.type} is not supported`);
+    }
+    return { text: text.join("\n"), ...(images.length ? { images } : {}) };
+}

package/lib/main.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// bma-dsh-acp: ACP agent on stdio. stdout carries ACP messages only, so every
+// console method is sent to stderr before anything else loads.
+//
+// Environment:
+//   BMA_DSH_ACP_HOME             DSH state directory (required)
+//   BMA_DSH_ACP_STREAM_IDLE_MS   model stream idle limit (ms, 0 disables)
+//   BRAIN_MODEL_CATALOG          operator model catalog file (limits per model)
+import { format } from "node:util";
+import { Readable, Writable } from "node:stream";
+const toStderr = (...args) => { process.stderr.write(`${format(...args)}\n`); };
+console.log = console.info = console.debug = console.warn = console.error = console.trace = toStderr;
+const { ndJsonStream } = await import("@agentclientprotocol/sdk");
+const { ModelCatalog, loadCatalogFile } = await import("@beeos-ai/bma-dsh-adapter");
+const { DshAcpShell } = await import("./agent.js");
+const home = process.env.BMA_DSH_ACP_HOME;
+if (!home) {
+    process.stderr.write("bma-dsh-acp: BMA_DSH_ACP_HOME is required\n");
+    process.exit(2);
+}
+const idle = process.env.BMA_DSH_ACP_STREAM_IDLE_MS;
+if (idle !== undefined && !/^\d{1,9}$/.test(idle)) {
+    process.stderr.write("bma-dsh-acp: BMA_DSH_ACP_STREAM_IDLE_MS must be a non-negative integer\n");
+    process.exit(2);
+}
+const catalogFile = process.env.BRAIN_MODEL_CATALOG;
+const shell = await DshAcpShell.create({
+    home,
+    ...(idle !== undefined ? { streamIdleMs: Number(idle) } : {}),
+    ...(catalogFile ? { catalog: new ModelCatalog({ entries: loadCatalogFile(catalogFile), onDefault: (m) => process.stderr.write(`bma-dsh-acp: model ${m} is not in the catalog; conservative limits\n`) }) } : {}),
+});
+const conn = shell.app.connect(ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin)));
+const stop = async () => {
+    await shell.dispose();
+    process.exit(0);
+};
+process.once("SIGTERM", () => void stop());
+await conn.closed;
+await stop();

package/lib/protocol.js

@@ -0,0 +1,17 @@
+export const META = "bma";
+export const TOOLS_CALL = "_bma/tools/call";
+export const MESSAGE = "_bma/message";
+export const TOOL_NAMES = ["bash", "read", "write", "edit", "glob", "grep"];
+/** Session modes (ACP session/set_mode). Ids follow the executor contract's permission_mode examples. */
+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, hostTools = []) {
+    const ask = "ask";
+    const edits = mode === "accept_edits" ? "allow" : "ask";
+    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/lib/tools.js

@@ -0,0 +1,78 @@
+export const MAX_TOOL_TIMEOUT_MS = 600_000;
+export const DEFAULT_BASH_TIMEOUT_MS = 120_000;
+const object = (required, properties) => ({ type: "object", properties, required, additionalProperties: false });
+const str = (description) => ({ type: "string", description });
+const int = (description, minimum, maximum) => ({ type: "integer", description, minimum, maximum });
+const bool = (description) => ({ type: "boolean", description });
+export const TOOL_SPECS = [
+    {
+        name: "bash",
+        kind: "execute",
+        readOnly: false,
+        description: "Run a shell command with bash in the working directory on this computer and return its output and exit code.",
+        parameters: object(["command"], {
+            command: str("The command to run."),
+            timeout: int(`Stop the command after this many milliseconds (default ${DEFAULT_BASH_TIMEOUT_MS}).`, 1, MAX_TOOL_TIMEOUT_MS),
+        }),
+    },
+    {
+        name: "read",
+        kind: "read",
+        readOnly: true,
+        description: "Read a text file under the working directory.",
+        parameters: object(["file_path"], {
+            file_path: str("Absolute path of the file."),
+            offset: int("First line to return (1-based).", 1, 2147483647),
+            limit: int("Maximum number of lines to return.", 1, 2147483647),
+        }),
+    },
+    {
+        name: "write",
+        kind: "edit",
+        readOnly: false,
+        description: "Create or overwrite a file under the working directory; parent directories are created.",
+        parameters: object(["file_path", "content"], {
+            file_path: str("Absolute path of the file."),
+            content: str("The full file content."),
+        }),
+    },
+    {
+        name: "edit",
+        kind: "edit",
+        readOnly: false,
+        description: "Replace text in a file under the working directory. old_string must match exactly once unless replace_all is true.",
+        parameters: object(["file_path", "old_string", "new_string"], {
+            file_path: str("Absolute path of the file."),
+            old_string: str("The exact text to replace."),
+            new_string: str("The replacement text."),
+            replace_all: bool("Replace every occurrence (default false)."),
+        }),
+    },
+    {
+        name: "glob",
+        kind: "search",
+        readOnly: true,
+        description: "List files under the working directory matching a glob pattern.",
+        parameters: object(["pattern"], {
+            pattern: str("The glob pattern, such as *.go or src/*.ts."),
+            path: str("Absolute directory to search (default: the working directory)."),
+        }),
+    },
+    {
+        name: "grep",
+        kind: "search",
+        readOnly: true,
+        description: "Search file contents under the working directory with a regular expression.",
+        parameters: object(["pattern"], {
+            pattern: str("The regular expression."),
+            path: str("Absolute file or directory to search (default: the working directory)."),
+            glob: str("Only search files whose name matches this glob, such as *.go."),
+            output_mode: {
+                type: "string",
+                enum: ["content", "files_with_matches", "count"],
+                description: "content (default) shows matching lines; files_with_matches lists files; count counts matches per file.",
+            },
+            case_insensitive: bool("Ignore case."),
+        }),
+    },
+];

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@beeos-ai/bma-dsh-acp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "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",
+    "deepseek",
+    "agent",
+    "acp",
+    "agent-client-protocol",
+    "managed-agents"
+  ],
+  "homepage": "https://staging.bma.beeos.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beeos-ai/beeos-managed-agents.git",
+    "directory": "brain-host/packages/dsh-acp"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "bma-dsh-acp": "./lib/main.js"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "2.2.0",
+    "zod": "4.6.7",
+    "@beeos-ai/bma-dsh-adapter": "0.2.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  },
+  "files": [
+    "lib",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 'test/**/*.test.ts'",
+    "build": "node scripts/build.ts",
+    "build:npm": "node scripts/build-npm.ts"
+  }
 }