@monotykamary/dsh-acp 0.1.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/acp/acp/README.md
+README.md: 7da6bfee41fec98329753d7b6eb6825f66499c14
+README.zh.md: 64026389d67351b2ad444306d9dc5008c2e5543a

package/README.md

@@ -0,0 +1,81 @@
+# @monotykamary/dsh-acp
+
+English | [中文](README.zh.md)
+
+Automation-only [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. Programmatic clients create fresh harness agents, send text/image prompts, collect committed assistant text/images, resolve one-shot permission requests by policy, and cancel work. The primary in-repository client is [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md).
+
+This package is a transport adapter, not a UI integration or a capability seam. It does not expose editor navigation, transcript replay, commands, modes, configuration pickers, elicitation, reasoning, plans, titles, or tool presentation. Interactive rendering and human questions belong to the Web host and client modules.
+
+## Plugin
+
+`apply(ctx, config)` opens an `AgentSideConnection` on stdin/stdout and drives `ctx.agents`. Stdout is reserved for protocol frames.
+
+| Config | Default | Meaning |
+|---|---|---|
+| `provider` | — | Initial provider route for every created agent. |
+| `model` | — | Initial model for every created agent. |
+
+Both fields are optional so another agent/request listener may supply the target. The runnable ACP composition requires both.
+
+## Protocol contract
+
+| Method | Behavior |
+|---|---|
+| `initialize` | Negotiates the supported version. Image prompts are advertised only when a durable attachment store is mounted and the configured exact provider/model resolves with explicit image input; audio and embedded context stay false. No session, editor, terminal, filesystem, or MCP capability is advertised. |
+| `authenticate` | No-op because the server advertises no authentication methods. |
+| `session/new` | Creates a fresh agent with an absolute primary `cwd`; empty `additionalDirectories` and `mcpServers` are accepted, non-empty values reject. |
+| `session/prompt` | Preserves ordered text and supported inline image blocks, renders resource links as bracketed textual references, and rejects audio, embedded resources, malformed/empty input, or an image when capability was not advertised. It validates the whole image batch and rechecks the session's latest exact route before any save, commits every image before the user event, permits one in-flight request per session, and waits for admission plus, once queued, whole-Agent idle and ordered output delivery. Normal quiescence reports `end_turn`; explicit ACP cancellation, disposal, or a prompt whose admission was discarded (a turnless slot) reports `cancelled`. |
+| `session/cancel` | Marks and aborts any in-progress admission without cancelling or waiting for unrelated Agent work; once this prompt has entered the Agent inbox, it cancels the addressed Agent and waits for the owned interval to quiesce. No late user message is published and the prompt settles as `cancelled`. With no in-flight prompt it cancels autonomous work; unknown ids are no-ops. |
+| `session/update` | Emits one `agent_message_chunk` per non-empty text or image block in a committed `assistant/message`, preserving order. Images are re-read and integrity-verified before inline base64 delivery. Raw deltas and non-message events are omitted. |
+| `session/request_permission` | Offers one-shot allow/reject choices for bridge-owned approval requests carrying a tool call id. Clients may answer automatically. |
+
+One connection may own several sessions. The bridge keys records by branded session id and checks exact agent identity before routing events or permission requests. Each session has an independent prompt slot, workspace, cancellation path, and disposer.
+
+Committed-message output intentionally trades token-by-token latency for a clean automation result. Uncommitted provider chunks and retry attempts cannot leak partial text or images; reasoning and tool activity remain in the session log for observability through other interfaces. Per-session delivery is serialized because attachment reads are asynchronous, and a missing or corrupt committed image fails the prompt response instead of emitting a placeholder.
+
+## Lifecycle
+
+Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, cancels and quiesces prompt admission, agent activity, and ordered output delivery, then drains continuable descendants only below this connection's exact owned Agents before disposing those handles in parallel and awaiting every result before reporting any failure. Other frontends sharing the Context retain their continuable forests and admission. An ACP-only plugin reload therefore leaves no orphan agent.
+
+ACP requires each prompt response to carry a `stopReason`, but the bridge does not claim a prompt-specific turn outcome. The operation interval starts when the prompt enters the Agent inbox and ends after admission, whole-Agent idle, and ordered output delivery all quiesce; failures from unrelated Agent work before that inbox receipt are not attributed to the prompt. Committed assistant messages stream across the owned interval, and steering or injected work may contribute before idle. Settlement precedence is explicit cancellation, output-delivery failure, interval-wide Agent failure, then the correlated turn ending. Token-limit endings settle as `end_turn`; a correlated model error rejects only at the same quiescence boundary.
+
+## Running
+
+`pnpm --dir /path/to/deepseek-harness run demo:acp` boots the repository's automation server composition. A parent harness can spawn it through [`@monotykamary/dsh-subagent-acp`](../../subagent/subagent-acp/README.md); other ACP clients need only the core methods above.
+
+## Model Experience
+
+### Prompt text and images
+
+#### What the model sees
+
+`session/prompt` preserves text/image order in one user message; adjacent text is concatenated, and a resource link appears as a bracketed `[resource_link name=… uri=…]` reference the model may open with its own tools. Inline image base64 is discarded after batch admission, so the durable message contains only verified attachment references. Protocol metadata, client capabilities, permission choices, and session ids never enter the model request.
+
+#### Token effect
+
+Prompt tokens and image charges are data-dependent and remain in that session's history until compaction. Concurrent ACP sessions retain independent contexts.
+
+#### KV Cache effect
+
+Append-only; the new user message follows the reusable request prefix and does not invalidate prior cache entries.
+
+### Permission decisions
+
+#### What the model sees
+
+Nothing directly. The owning tool records its allowed, rejected, cancelled, or unavailable outcome through the normal tool-result path.
+
+#### Token effect
+
+Only the owning tool result contributes tokens.
+
+#### KV Cache effect
+
+Append-only through the owning tool result.
+
+## Known Limitations and Deferred Work
+
+- **Fresh sessions only** — load, list, resume, delete, and fork are unsupported.
+- **Raster images and one workspace only** — image prompts require a durable store plus an exact route that declares image input; only PNG, JPEG, WebP, and GIF are accepted. Audio, embedded resources, non-empty additional directories, and MCP servers reject; resource links flatten to textual references rather than fetched content.
+- **Committed answers only** — live progress, reasoning, tool activity, plans, titles, and usage stay off the wire.
+- **Connection-owned lifetime** — one connection releases all of its sessions; per-session close is not implemented.

package/README.zh.md

@@ -0,0 +1,81 @@
+# @monotykamary/dsh-acp
+
+[English](README.md) | 中文
+
+通过 JSON-RPC stdio 提供的仅面向自动化的 [ACP（Agent Client Protocol）](https://agentclientprotocol.com) 服务器。程序化客户端可以创建新 harness agent（智能体）、发送文本／图片提示词、收集已提交的 assistant 文本／图片、按策略响应一次性权限请求并取消工作。仓库中的主要客户端是 [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)。
+
+此包是传输适配器，而非 UI 集成或能力 seam。它不公开编辑器导航、transcript（文本记录）回放、命令、模式、配置选择器、信息征集、推理（reasoning）、计划、标题或工具展示。交互式渲染与向用户提问属于 Web 宿主和客户端模块。
+
+## 插件
+
+`apply(ctx, config)` 在 stdin/stdout 上打开 `AgentSideConnection` 并驱动 `ctx.agents`。Stdout 专用于协议帧。
+
+| 配置 | 默认值 | 含义 |
+|---|---|---|
+| `provider` | 无 | 每个已创建 agent 的初始提供方路由。 |
+| `model` | 无 | 每个已创建 agent 的初始模型。 |
+
+两个字段都是可选的，以便由另一个 agent/request 监听器提供目标。可运行的 ACP 组合同时要求两者。
+
+## 协议约定
+
+| 方法 | 行为 |
+|---|---|
+| `initialize` | 协商受支持的版本。只有挂载持久附件存储，且配置的确切提供方／模型解析后明确支持图片输入时，才公布图片提示词能力；音频与嵌入上下文保持 false。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
+| `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
+| `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
+| `session/prompt` | 保留文本与受支持内联图片块的顺序，将资源链接渲染为带方括号的文本引用，并拒绝音频、嵌入资源、格式错误／空输入，或在未公布能力时提交图片。它会先校验完整图片批次并重新检查会话的最新确切路由，再保存任一成员；在用户事件前提交全部图片；每个会话只允许一个正在处理的请求，并等待准入，以及消息入队后的整个 Agent 空闲和有序输出交付全部停稳。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（无轮次槽位）时报告 `cancelled`。 |
+| `session/cancel` | 标记并中止正在进行的准入，但不会取消或等待同一 Agent 上无关的既有工作；该提示词进入 Agent inbox 后，才会取消指定的 Agent 并等待自有区间停稳。不发布迟到的用户消息，提示词以 `cancelled` 结算。没有进行中的提示词时会取消自主工作；未知 id 为空操作。 |
+| `session/update` | 为已提交 `assistant/message` 中的每个非空文本或图片块发出一个 `agent_message_chunk`，并保留顺序。图片在以内联 base64 交付前会重新读取并校验完整性。省略原始增量和非消息事件。 |
+| `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
+
+一个连接可以拥有多个会话。桥接层以带品牌的会话 id 作为记录键，并在路由事件或权限请求前检查 agent 是否为同一对象。每个会话都有独立的提示词槽位、工作区、取消路径和资源释放器。
+
+已提交消息输出有意牺牲逐 token 输出的低延迟，以换取干净的自动化结果。未提交的提供方分片和重试尝试无法泄漏部分文本或图片；推理与工具活动仍保留在会话日志中，以便其他界面观测。由于附件读取是异步的，每个会话会串行交付内容；已提交图片缺失或损坏时，提示词响应会失败，而不会发出占位符。
+
+## 生命周期
+
+客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，取消并等待提示词准入、agent 活动和有序输出交付全部停稳，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
+
+ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。操作区间从提示词进入 Agent inbox 开始，在准入、整个 Agent 空闲和有序输出交付全部停稳后结束；inbox 接收前无关 Agent 工作的失败不会归因给该提示词。已提交的 assistant 消息会在自有区间内流式输出，Agent 进入空闲状态前发生的 steering（中途引导）或注入工作也可能参与其中。结算优先级依次为显式取消、输出交付失败、区间内 Agent 失败、关联轮次结束。因 token 上限而结束时以 `end_turn` 结算；关联模型错误也只会在同一个完全停稳边界拒绝提示词。
+
+## 运行
+
+`pnpm --dir /path/to/deepseek-harness run demo:acp` 启动仓库的自动化服务器组合。父 harness 可以通过 [`@monotykamary/dsh-subagent-acp`](../../subagent/subagent-acp/README.md) spawn 它；其他 ACP 客户端只需上述核心方法。
+
+## 模型体验
+
+### 提示词文本与图片
+
+#### 模型看到的内容
+
+`session/prompt` 会在一条用户消息中保留文本／图片顺序；相邻文本会拼接，资源链接则表示为带方括号的 `[resource_link name=… uri=…]` 引用，模型可以使用自身工具打开它。内联图片 base64 在批量准入后即被丢弃，因此持久消息只包含经过校验的附件引用。协议元数据、客户端能力、权限选择和会话 id 绝不进入模型请求。
+
+#### Token 影响
+
+提示词 token 与图片费用取决于数据，并保留在该会话的历史中直到上下文压缩（context compaction）。并发 ACP 会话保留独立上下文。
+
+#### KV Cache 影响
+
+仅追加；新用户消息位于可复用请求前缀之后，不会使先前缓存条目失效。
+
+### 权限决策
+
+#### 模型看到的内容
+
+不会直接看到任何内容。所属工具通过常规工具结果路径记录其结果：允许、拒绝、取消或不可用。
+
+#### Token 影响
+
+只有所属工具的结果会贡献 token。
+
+#### KV Cache 影响
+
+仅通过所属工具的结果追加。
+
+## 已知限制与暂缓事项
+
+- **仅新会话**：不支持加载、列出、恢复、删除和 fork。
+- **仅光栅图片和一个 workspace**：图片提示词要求持久存储以及明确声明支持图片输入的确切路由；只接受 PNG、JPEG、WebP 和 GIF。音频、嵌入资源、非空附加目录和 MCP 服务器都会被拒绝；资源链接只会展平为文本引用，不会获取其内容。
+- **仅已提交答案**：实时进度、推理、工具活动、计划、标题和用量不会通过协议传输。
+- **由连接管理的生命周期**：一个连接会释放其所有会话；尚未实现单个会话关闭功能。

package/lib/index.js

@@ -0,0 +1,566 @@
+import { randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { Readable, Writable } from "node:stream";
+import Schema from "@monotykamary/schemastery";
+import { createUserMessage, errorChain } from "@monotykamary/dsh-llm";
+import { AgentSideConnection, PROTOCOL_VERSION, RequestError, ndJsonStream } from "@agentclientprotocol/sdk";
+import { SessionId } from "@monotykamary/dsh-session";
+import { isImageAdmissionError } from "@monotykamary/dsh-attachment";
+//#region lib/types/content.js
+/** ACP wire-content admission and projection owned by the ACP adapter. @module */
+/** Raster formats shared by ACP image blocks and the core attachment vocabulary. */
+const IMAGE_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+];
+/** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/** Error with a stable ACP request-failure category and no raw binary payload. */
+var AcpContentError = class extends Error {
+	/** Whether the bridge should report invalid params or an internal failure. */
+	kind;
+	/**
+	* @param message - safe protocol-facing detail without inline binary data.
+	* @param kind - request-failure category.
+	* @param options - optional causal chain for diagnostics.
+	*/
+	constructor(message, kind, options) {
+		super(message, options);
+		this.name = "AcpContentError";
+		this.kind = kind;
+	}
+};
+/** Narrow a wire MIME string to the durable raster vocabulary. */
+function imageMediaType(value) {
+	return IMAGE_MEDIA_TYPES.includes(value) ? value : void 0;
+}
+/** Strictly decode one ACP inline image without accepting base64 aliases. */
+function decodeImage(block) {
+	const mediaType = imageMediaType(block.mimeType);
+	if (mediaType === void 0) throw new AcpContentError("image mimeType must be image/png, image/jpeg, image/webp, or image/gif", "invalid");
+	if (!CANONICAL_BASE64.test(block.data)) throw new AcpContentError("image data must be canonical base64", "invalid");
+	const data = Buffer.from(block.data, "base64");
+	if (data.toString("base64") !== block.data) throw new AcpContentError("image data must be canonical base64", "invalid");
+	return {
+		data,
+		mediaType
+	};
+}
+/** Resolve the exact current route and require explicit image input support. */
+async function assertImageRoute(ctx, agent, signal) {
+	const routed = agent.session.requestHeader()?.config;
+	const provider = routed?.provider ?? agent.options.provider;
+	const model = routed?.model ?? agent.options.model;
+	const llm = ctx.get("llm");
+	if (provider === void 0 || model === void 0 || llm === void 0) throw new AcpContentError("the current model route could not be resolved for image input", "invalid");
+	let info;
+	try {
+		info = await llm.resolveModelInfo(provider, model, signal);
+	} catch (error) {
+		throw new AcpContentError("the current model route could not be verified for image input", "internal", { cause: error });
+	}
+	if (info.inputModalities === void 0 || !info.inputModalities.includes("image")) throw new AcpContentError(`model "${model}" does not declare image input`, "invalid");
+}
+/**
+* Determine whether initialization may truthfully advertise inline image prompts.
+* Unknown service, route, capability, or deployment media support is negative.
+* @param ctx - bridge context carrying optional attachment and model services.
+* @param provider - configured provider route used for newly created sessions.
+* @param model - configured exact model id used for newly created sessions.
+* @returns whether this bridge can admit images at initialization time.
+*/
+async function supportsAcpImagePrompts(ctx, provider, model) {
+	const attachments = ctx.get("attachments");
+	const llm = ctx.get("llm");
+	if (attachments === void 0 || llm === void 0 || provider === void 0 || model === void 0) return false;
+	if (!attachments.imageLimits.mediaTypes.some((mediaType) => IMAGE_MEDIA_TYPES.includes(mediaType))) return false;
+	try {
+		return (await llm.resolveModelInfo(provider, model)).inputModalities?.includes("image") === true;
+	} catch {
+		return false;
+	}
+}
+/** Render one baseline resource link into the core's current text vocabulary. */
+function resourceLinkText(block) {
+	return `\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`;
+}
+/**
+* Admit one ACP prompt into ordered durable core content.
+* Every wire block and image is validated before the ordered image batch starts
+* writing; cancellation after a successful content-addressed write may leave an
+* unreachable object but never queues a late user message.
+* @param ctx - bridge context carrying attachment and model services.
+* @param agent - destination agent whose latest exact route controls admission.
+* @param prompt - untrusted ACP prompt blocks in wire order.
+* @param imageEnabled - capability result advertised during initialization.
+* @param signal - admission cancellation signal.
+* @returns core content with durable image references in wire order.
+*/
+async function admitAcpPrompt(ctx, agent, prompt, imageEnabled, signal) {
+	const images = [];
+	for (const block of prompt) switch (block.type) {
+		case "text":
+		case "resource_link": break;
+		case "image":
+			if (!imageEnabled) throw new AcpContentError("inline image prompts were not advertised by this connection", "invalid");
+			images.push(decodeImage(block));
+			break;
+		case "audio": throw new AcpContentError("audio prompt content is not supported", "invalid");
+		case "resource": throw new AcpContentError("embedded resource prompt content is not supported", "invalid");
+		/* v8 ignore next 2 -- ACP ContentBlock is a closed generated union. */
+		default: throw new AcpContentError("unsupported ACP prompt content", "invalid");
+	}
+	let refs = [];
+	if (images.length > 0) {
+		const attachments = ctx.get("attachments");
+		if (attachments === void 0) throw new AcpContentError("no attachment store is mounted", "invalid");
+		await assertImageRoute(ctx, agent, signal);
+		signal.throwIfAborted();
+		try {
+			refs = await attachments.saveImages(images);
+		} catch (error) {
+			if (isImageAdmissionError(error)) throw new AcpContentError(error.message, "invalid", { cause: error });
+			throw new AcpContentError("unable to persist the prompt image batch", "internal", { cause: error });
+		}
+		signal.throwIfAborted();
+	}
+	const content = [];
+	let pendingText = "";
+	let imageIndex = 0;
+	const flushText = () => {
+		if (pendingText.length === 0) return;
+		content.push({
+			type: "text",
+			text: pendingText
+		});
+		pendingText = "";
+	};
+	for (const block of prompt) switch (block.type) {
+		case "text":
+			pendingText += block.text;
+			break;
+		case "resource_link":
+			pendingText += resourceLinkText(block);
+			break;
+		case "image": {
+			flushText();
+			const ref = refs[imageIndex++];
+			content.push({
+				type: "image",
+				attachment: ref
+			});
+			break;
+		}
+		/* v8 ignore start -- the validation pass above rejects both tags before reconstruction. */
+		case "audio":
+		case "resource": break;
+		/* v8 ignore stop */
+		/* v8 ignore next 2 -- validated by the first closed-union switch. */
+		default: break;
+	}
+	flushText();
+	if (!content.some((block) => block.type === "image" || block.type === "text" && block.text.trim().length > 0)) throw new AcpContentError("empty prompt", "invalid");
+	return content;
+}
+/**
+* Translate one committed assistant block to ACP wire content.
+* Images are re-read and integrity-verified before inline base64 delivery;
+* unsupported core output blocks stay off the automation wire.
+* @param ctx - bridge context carrying the authoritative attachment store.
+* @param block - committed core assistant block.
+* @returns ACP text/image content, or undefined for non-output blocks.
+*/
+async function assistantBlockToAcp(ctx, block) {
+	if (block.type === "text") return block.text.length === 0 ? void 0 : {
+		type: "text",
+		text: block.text
+	};
+	if (block.type !== "image") return void 0;
+	const attachments = ctx.get("attachments");
+	if (attachments === void 0) throw new AcpContentError("cannot deliver assistant image: no attachment store is mounted", "internal");
+	let stored;
+	try {
+		stored = await attachments.readImage(block.attachment);
+	} catch (error) {
+		throw new AcpContentError("cannot deliver assistant image: the attachment is unavailable or corrupt", "internal", { cause: error });
+	}
+	return {
+		type: "image",
+		data: Buffer.from(stored.data).toString("base64"),
+		mimeType: stored.ref.mediaType
+	};
+}
+//#endregion
+//#region lib/types/codec.js
+/**
+* Pure translation between the harness lifecycle and the automation-only ACP wire.
+* @module @monotykamary/dsh-acp/codec
+*/
+/**
+* Map a harness turn ending to ACP's terminal reason vocabulary.
+* @param reason - harness turn outcome.
+* @returns the closest legal ACP stop reason.
+*/
+function turnEndToStopReason(reason) {
+	switch (reason.kind) {
+		case "completed": return "end_turn";
+		case "max-tokens": return "max_tokens";
+		case "aborted": return "end_turn";
+		case "interrupted": return "cancelled";
+		case "blocked":
+		case "error": return "end_turn";
+		/* v8 ignore next 2 -- TurnEndReason is closed and every member is handled above */
+		default: return "end_turn";
+	}
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Automation-only Agent Client Protocol server over JSON-RPC stdio.
+*
+* The bridge exposes fresh harness sessions to trusted programmatic clients. It
+* carries prompt text/images, committed assistant text/images, cancellation,
+* and one-shot permission decisions; presentation and human-interaction
+* features stay with the harness's UI modules.
+*
+* @module @monotykamary/dsh-acp
+*/
+const name = "acp";
+/** The bridge creates and owns agents; every other concern is carried by the agent composition. */
+const inject = ["agents"];
+/** Preserve invalid-parameter detail in the SDK wire error message. */
+function invalidParams(detail) {
+	return RequestError.invalidParams(void 0, detail);
+}
+/** Preserve failed-turn detail; plain handler errors become a generic wire internal error. */
+function internalError(detail) {
+	return RequestError.internalError(void 0, detail);
+}
+const Config = Schema.object({
+	provider: Schema.string(),
+	model: Schema.string()
+});
+/**
+* Mount the automation-only ACP server.
+* @param ctx - Cordis context carrying the agent factory and session events.
+* @param config - Initial provider/model selection and optional test transport.
+*/
+function apply(ctx, config) {
+	const agents = ctx.agents;
+	const logger = ctx.logger;
+	const sessions = /* @__PURE__ */ new Map();
+	let closed = false;
+	let conn;
+	let imagePromptEnabled = false;
+	/** Return the bridge-owned record for an agent, rejecting same-id impostors. */
+	const ownedRecord = (agent) => {
+		const record = sessions.get(agent.session.id);
+		return record?.agent === agent ? record : void 0;
+	};
+	const assertOpen = () => {
+		if (closed) throw internalError("the ACP bridge has been disposed");
+	};
+	const requireSession = (sessionId) => {
+		const record = sessions.get(sessionId);
+		if (record === void 0) throw invalidParams(`unknown session: ${sessionId}`);
+		return record;
+	};
+	/** Send one ordered protocol update while containing transport-only failure. */
+	const notify = async (notification) => {
+		try {
+			await conn.sessionUpdate(notification);
+		} catch (error) {
+			logger.warn(`acp: session/update failed: ${String(error)}`);
+		}
+		/* v8 ignore stop */
+	};
+	const rejectFromError = (inflight, reason) => {
+		inflight.reject(internalError(`turn failed: ${reason.error.message}`));
+	};
+	/**
+	* Settle one exact prompt only after admission, agent activity, and ordered
+	* assistant delivery have all reached quiescence.
+	*/
+	const settleAfterQuiescence = (record, inflight) => {
+		if (inflight.settlementStarted) return;
+		inflight.settlementStarted = true;
+		(async () => {
+			await inflight.admissionDone;
+			if (inflight.messageQueued) {
+				await record.agent.whenIdle();
+				await record.outputTail;
+			}
+			/* v8 ignore next -- this prompt owns the slot until this exact settlement clears it. */
+			if (record.inflight !== inflight) return;
+			record.inflight = void 0;
+			if (inflight.cancelRequested) {
+				inflight.resolve("cancelled");
+				return;
+			}
+			if (inflight.outputError !== void 0) {
+				inflight.reject(internalError(`assistant output delivery failed: ${inflight.outputError.message}`));
+				return;
+			}
+			if (inflight.agentError !== void 0) {
+				inflight.reject(internalError(`turn failed: ${inflight.agentError.message}`));
+				return;
+			}
+			const end = inflight.endReason;
+			if (end === void 0) inflight.resolve("cancelled");
+			else if (end.kind === "error") rejectFromError(inflight, end);
+			else inflight.resolve(end.kind === "max-tokens" ? "end_turn" : turnEndToStopReason(end));
+		})().catch((error) => {
+			if (record.inflight !== inflight) return;
+			record.inflight = void 0;
+			inflight.reject(internalError(`prompt settlement failed: ${errorChain(error)}`));
+		});
+		/* v8 ignore stop */
+	};
+	ctx.on("session/event", (session, event) => {
+		const record = sessions.get(session.header.id);
+		if (record === void 0 || record.agent.session !== session) return;
+		try {
+			if (event.type === "assistant/message") {
+				const inflight = record.inflight?.turn === event.data.turn ? record.inflight : void 0;
+				record.outputTail = record.outputTail.then(async () => {
+					for (const block of event.data.message.content) {
+						const content = await assistantBlockToAcp(ctx, block);
+						if (content === void 0) continue;
+						await notify({
+							sessionId: record.agent.session.id,
+							update: {
+								sessionUpdate: "agent_message_chunk",
+								content
+							}
+						});
+					}
+				}).catch((error) => {
+					const failure = error;
+					if (inflight !== void 0) inflight.outputError ??= failure;
+					logger.warn(`acp: assistant output conversion failed: ${errorChain(error)}`);
+				});
+			}
+		} finally {
+			const inflight = record.inflight;
+			if (inflight !== void 0 && event.type === "turn/end" && inflight.turn === event.data.turn) inflight.endReason = event.data.reason;
+		}
+	});
+	ctx.on("agent/inbox/claimed", ({ agent, message, turn }) => {
+		const inflight = ownedRecord(agent)?.inflight;
+		if (inflight !== void 0 && inflight.messageId === message.id) inflight.turn = turn;
+	});
+	ctx.on("agent/error", ({ agent, turn, error }) => {
+		const record = ownedRecord(agent);
+		const inflight = record?.inflight;
+		if (record === void 0 || inflight === void 0 || !inflight.messageQueued || inflight.turn === turn) return;
+		inflight.agentError = new Error(errorChain(error));
+		settleAfterQuiescence(record, inflight);
+	});
+	ctx.on("approval/request", (request, next) => {
+		const record = ownedRecord(request.agent);
+		if (record === void 0 || request.callId === void 0) return next();
+		return conn.requestPermission({
+			sessionId: record.agent.session.id,
+			toolCall: { toolCallId: request.callId },
+			options: [{
+				optionId: "allow-once",
+				name: "Allow once",
+				kind: "allow_once"
+			}, {
+				optionId: "reject-once",
+				name: "Reject",
+				kind: "reject_once"
+			}]
+		}).then(({ outcome }) => {
+			if (outcome.outcome === "cancelled") return "cancelled";
+			return outcome.optionId === "allow-once" ? "allowed-once" : "rejected";
+		});
+	});
+	const makeAgent = (connection) => {
+		conn = connection;
+		return {
+			async initialize(_params) {
+				imagePromptEnabled = await supportsAcpImagePrompts(ctx, config.provider, config.model);
+				return {
+					protocolVersion: PROTOCOL_VERSION,
+					agentInfo: {
+						name: "deepseek-harness-acp",
+						version: "0.0.1"
+					},
+					agentCapabilities: { promptCapabilities: {
+						image: imagePromptEnabled,
+						audio: false,
+						embeddedContext: false
+					} },
+					authMethods: []
+				};
+			},
+			authenticate(_params) {
+				return Promise.resolve();
+			},
+			async newSession(params) {
+				assertOpen();
+				validateSessionParams(params);
+				const sessionId = SessionId(randomUUID());
+				const handle = await agents.create({
+					sessionId,
+					meta: { cwd: params.cwd },
+					agentOptions: agentOptions(config)
+				});
+				/* v8 ignore next 4 -- a real stdio close can race an in-flight create. */
+				if (closed) {
+					await handle.dispose();
+					throw internalError("connection closed during session/new");
+				}
+				sessions.set(sessionId, {
+					agent: handle.agent,
+					dispose: () => handle.dispose(),
+					outputTail: Promise.resolve(),
+					inflight: void 0
+				});
+				return { sessionId };
+			},
+			async prompt(params) {
+				assertOpen();
+				const record = requireSession(SessionId(params.sessionId));
+				if (record.inflight !== void 0) throw invalidParams("a prompt is already in flight for this session");
+				const completion = Promise.withResolvers();
+				const admission = Promise.withResolvers();
+				const admissionController = new AbortController();
+				const inflight = {
+					resolve: completion.resolve,
+					reject: completion.reject,
+					messageId: void 0,
+					messageQueued: false,
+					turn: void 0,
+					endReason: void 0,
+					admissionDone: admission.promise,
+					finishAdmission: admission.resolve,
+					admissionController,
+					cancelRequested: false,
+					settlementStarted: false,
+					outputError: void 0,
+					agentError: void 0
+				};
+				record.inflight = inflight;
+				let admissionFailed = false;
+				let admissionFailure;
+				try {
+					if (ctx.agents.get(record.agent.id) !== record.agent) throw internalError("prompt was not queued: the agent was disposed outside the bridge");
+					const content = await admitAcpPrompt(ctx, record.agent, params.prompt, imagePromptEnabled, admissionController.signal);
+					admissionController.signal.throwIfAborted();
+					if (ctx.agents.get(record.agent.id) !== record.agent) throw internalError("prompt was not queued: the agent was disposed outside the bridge");
+					const message = createUserMessage({
+						content,
+						source: { kind: "user" }
+					});
+					inflight.messageId = message.id;
+					inflight.messageQueued = true;
+					try {
+						record.agent.followup(message);
+					} catch (error) {
+						inflight.messageQueued = false;
+						throw error;
+					}
+				} catch (error) {
+					admissionFailed = true;
+					admissionFailure = error;
+				} finally {
+					inflight.finishAdmission();
+				}
+				if (inflight.cancelRequested) {
+					settleAfterQuiescence(record, inflight);
+					return { stopReason: await completion.promise };
+				}
+				if (admissionFailed) {
+					record.inflight = void 0;
+					if (admissionFailure instanceof AcpContentError) throw admissionFailure.kind === "invalid" ? invalidParams(admissionFailure.message) : internalError(admissionFailure.message);
+					if (admissionFailure instanceof RequestError) throw admissionFailure;
+					const detail = admissionFailure.message;
+					throw internalError(`prompt was not queued: ${detail}`);
+				}
+				settleAfterQuiescence(record, inflight);
+				return { stopReason: await completion.promise };
+			},
+			cancel(params) {
+				const record = sessions.get(SessionId(params.sessionId));
+				if (record === void 0) return Promise.resolve();
+				const inflight = record.inflight;
+				if (inflight !== void 0) {
+					inflight.cancelRequested = true;
+					inflight.admissionController.abort(/* @__PURE__ */ new Error("ACP prompt cancelled"));
+					settleAfterQuiescence(record, inflight);
+				}
+				if (inflight === void 0 || inflight.messageQueued) record.agent.cancel({ kind: "user" });
+				return Promise.resolve();
+			}
+		};
+	};
+	conn = new AgentSideConnection(makeAgent, config.stream ?? ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin)));
+	let quiescing;
+	const quiesce = () => {
+		if (quiescing !== void 0) return quiescing;
+		closed = true;
+		const records = [...sessions.values()];
+		sessions.clear();
+		for (const record of records) {
+			const inflight = record.inflight;
+			if (inflight !== void 0) {
+				inflight.cancelRequested = true;
+				inflight.admissionController.abort(/* @__PURE__ */ new Error("ACP bridge disposed"));
+				settleAfterQuiescence(record, inflight);
+			}
+			record.agent.cancel({ kind: "user" });
+		}
+		quiescing = (async () => {
+			await Promise.all(records.map(async (record) => {
+				await record.inflight?.admissionDone;
+				await record.agent.whenIdle();
+				await record.outputTail;
+			}));
+			const subagents = ctx.get("subagents");
+			if (subagents !== void 0) try {
+				await subagents.drainContinuableDescendants(records.map((record) => record.agent));
+			} catch (error) {
+				logger.warn(`acp: continuable subagent teardown failed: ${String(error)}`);
+			}
+			const disposals = await Promise.allSettled(records.map((record) => record.dispose()));
+			const failures = [];
+			for (const result of disposals) if (result.status === "rejected") failures.push(result.reason);
+			if (failures.length > 0) {
+				const detail = failures.map((failure) => errorChain(failure)).join("; ");
+				throw new AggregateError(failures, `ACP agent teardown failed for ${failures.length} session(s): ${detail}`);
+			}
+		})();
+		return quiescing;
+	};
+	/* v8 ignore start -- production transport rejection and teardown failure. */
+	conn.closed.catch((error) => {
+		logger.warn(`acp: connection closed with an error: ${String(error)}`);
+	}).then(quiesce).catch((error) => {
+		logger.warn(`acp: connection-close teardown failed: ${String(error)}`);
+	});
+	/* v8 ignore stop */
+	ctx.effect(() => quiesce, "acp.connection");
+}
+/**
+* Build per-agent options from plugin config without assigning absent optional fields.
+* @param config - ACP provider/model configuration.
+* @returns the configured fields only.
+*/
+function agentOptions(config) {
+	return {
+		...config.provider !== void 0 ? { provider: config.provider } : {},
+		...config.model !== void 0 ? { model: config.model } : {}
+	};
+}
+/** Reject session features outside the automation contract. */
+function validateSessionParams(params) {
+	if (!isAbsolute(params.cwd)) throw invalidParams(`cwd must be an absolute path: ${params.cwd}`);
+	if (params.additionalDirectories !== void 0 && params.additionalDirectories.length > 0) throw invalidParams("additionalDirectories is not supported");
+	if (params.mcpServers.length > 0) throw invalidParams("mcpServers is not supported");
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-acp`.
+* @module @monotykamary/dsh-acp/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-acp";
+/** Cordis companion plugin name. */
+const name = "acp-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this transport owns no durable package-local event stream;
+* protocol and lifecycle tests cover its mapping.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/codec.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pure translation between the harness lifecycle and the automation-only ACP wire.
+ * @module @monotykamary/dsh-acp/codec
+ */
+import type { StopReason } from '@agentclientprotocol/sdk';
+import type { TurnEndReason } from '@monotykamary/dsh-session';
+/**
+ * Map a harness turn ending to ACP's terminal reason vocabulary.
+ * @param reason - harness turn outcome.
+ * @returns the closest legal ACP stop reason.
+ */
+export declare function turnEndToStopReason(reason: TurnEndReason): StopReason;
+//# sourceMappingURL=codec.d.ts.map

package/lib/types/content.d.ts

@@ -0,0 +1,50 @@
+/** ACP wire-content admission and projection owned by the ACP adapter. @module */
+import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk';
+import type { Context } from '@monotykamary/cordis';
+import type { Agent } from '@monotykamary/dsh-agent';
+import type { ContentBlock } from '@monotykamary/dsh-llm';
+/** Content-admission failure category used by the protocol handler. */
+export type AcpContentFailureKind = 'invalid' | 'internal';
+/** Error with a stable ACP request-failure category and no raw binary payload. */
+export declare class AcpContentError extends Error {
+    /** Whether the bridge should report invalid params or an internal failure. */
+    readonly kind: AcpContentFailureKind;
+    /**
+     * @param message - safe protocol-facing detail without inline binary data.
+     * @param kind - request-failure category.
+     * @param options - optional causal chain for diagnostics.
+     */
+    constructor(message: string, kind: AcpContentFailureKind, options?: ErrorOptions);
+}
+/**
+ * Determine whether initialization may truthfully advertise inline image prompts.
+ * Unknown service, route, capability, or deployment media support is negative.
+ * @param ctx - bridge context carrying optional attachment and model services.
+ * @param provider - configured provider route used for newly created sessions.
+ * @param model - configured exact model id used for newly created sessions.
+ * @returns whether this bridge can admit images at initialization time.
+ */
+export declare function supportsAcpImagePrompts(ctx: Context, provider: string | undefined, model: string | undefined): Promise<boolean>;
+/**
+ * Admit one ACP prompt into ordered durable core content.
+ * Every wire block and image is validated before the ordered image batch starts
+ * writing; cancellation after a successful content-addressed write may leave an
+ * unreachable object but never queues a late user message.
+ * @param ctx - bridge context carrying attachment and model services.
+ * @param agent - destination agent whose latest exact route controls admission.
+ * @param prompt - untrusted ACP prompt blocks in wire order.
+ * @param imageEnabled - capability result advertised during initialization.
+ * @param signal - admission cancellation signal.
+ * @returns core content with durable image references in wire order.
+ */
+export declare function admitAcpPrompt(ctx: Context, agent: Agent, prompt: readonly AcpContentBlock[], imageEnabled: boolean, signal: AbortSignal): Promise<ContentBlock[]>;
+/**
+ * Translate one committed assistant block to ACP wire content.
+ * Images are re-read and integrity-verified before inline base64 delivery;
+ * unsupported core output blocks stay off the automation wire.
+ * @param ctx - bridge context carrying the authoritative attachment store.
+ * @param block - committed core assistant block.
+ * @returns ACP text/image content, or undefined for non-output blocks.
+ */
+export declare function assistantBlockToAcp(ctx: Context, block: ContentBlock): Promise<AcpContentBlock | undefined>;
+//# sourceMappingURL=content.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Automation-only Agent Client Protocol server over JSON-RPC stdio.
+ *
+ * The bridge exposes fresh harness sessions to trusted programmatic clients. It
+ * carries prompt text/images, committed assistant text/images, cancellation,
+ * and one-shot permission decisions; presentation and human-interaction
+ * features stay with the harness's UI modules.
+ *
+ * @module @monotykamary/dsh-acp
+ */
+import type { Context } from '@monotykamary/cordis';
+import Schema from '@monotykamary/schemastery';
+import { type Stream } from '@agentclientprotocol/sdk';
+export declare const name = "acp";
+/** The bridge creates and owns agents; every other concern is carried by the agent composition. */
+export declare const inject: string[];
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
+export interface AcpConfig {
+    /** Provider route for created agents. */
+    provider?: string;
+    /** Model name for created agents. */
+    model?: string;
+    /** Runtime-only transport override; production uses stdio. */
+    stream?: Stream;
+}
+export declare const Config: Schema<AcpConfig>;
+/**
+ * Mount the automation-only ACP server.
+ * @param ctx - Cordis context carrying the agent factory and session events.
+ * @param config - Initial provider/model selection and optional test transport.
+ */
+export declare function apply(ctx: Context, config: AcpConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-acp`.
+ * @module @monotykamary/dsh-acp/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "acp-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@monotykamary/dsh-acp",
+  "description": "Automation-only Agent Client Protocol server for driving DeepSeek Harness agents over JSON-RPC stdio",
+  "version": "0.1.0-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/acp/acp"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/sdk": "0.25.1",
+    "@monotykamary/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@monotykamary/dsh-attachment": "^0.1.0-rc.10",
+    "@monotykamary/dsh-agent": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/dsh-llm": "^0.1.0-rc.10",
+    "@monotykamary/dsh-session": "^0.1.0-rc.10",
+    "@monotykamary/dsh-user-approval": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@monotykamary/dsh-agent": "^0.1.0-rc.10",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.10",
+    "@monotykamary/dsh-llm": "^0.1.0-rc.10",
+    "@monotykamary/dsh-session": "^0.1.0-rc.10",
+    "@monotykamary/dsh-tools": "^0.1.0-rc.10",
+    "@monotykamary/dsh-agent-loop-testkit": "^0.1.0-rc.10",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/dsh-user-approval": "^0.1.0-rc.10",
+    "@monotykamary/dsh-agent-loop": "^0.1.0-rc.10",
+    "@monotykamary/dsh-attachment": "^0.1.0-rc.10"
+  }
+}