@monotykamary/dsh-acp 0.1.0-rc.5

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: 3cb8aa44decb5829a0a6794e3c4f39c99f12808e
+README.zh.md: 9f4610354d7443f288397b3227f0abb79594a683

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 prompts, collect committed assistant text, 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 and advertises baseline-only prompts (no image, audio, or embedded-context capability). 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` | Concatenates text blocks, renders baseline resource links as bracketed textual references, rejects empty or beyond-baseline input, permits one in-flight request per session, and waits for the whole agent to become idle. Normal quiescence reports `end_turn`; explicit ACP cancellation, disposal, or a prompt whose admission was discarded (a turnless slot) reports `cancelled`. |
+| `session/cancel` | Cancels only the addressed agent and settles its pending prompt as `cancelled`; unknown ids are no-ops. |
+| `session/update` | Emits one `agent_message_chunk` per non-empty text block in a committed `assistant/message`. 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; reasoning and tool activity remain in the session log for observability through other interfaces.
+
+## Lifecycle
+
+Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, settles pending prompts, 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. Committed assistant messages stream across the owned activity, and steering or injected work may contribute before idle. Token-limit turn endings therefore do not become prompt-level ACP stop reasons (they settle as `end_turn`); a model error on the correlated turn rejects the prompt immediately.
+
+## 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
+
+#### What the model sees
+
+`session/prompt` text blocks are concatenated verbatim into one user message; a baseline resource link appears in that message as a bracketed `[resource_link name=… uri=…]` reference the model may open with its own tools. Protocol metadata, client capabilities, permission choices, and session ids never enter the model request.
+
+#### Token effect
+
+Prompt tokens 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.
+- **Baseline prompts and one workspace only** — images, 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` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
+| `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
+| `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
+| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入空闲状态。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（无轮次槽位）时报告 `cancelled`。 |
+| `session/cancel` | 仅取消指定的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 |
+| `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 |
+| `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
+
+一个连接可以拥有多个会话。桥接层以带品牌的会话 id 作为记录键，并在路由事件或权限请求前检查 agent 是否为同一对象。每个会话都有独立的提示词槽位、工作区、取消路径和资源释放器。
+
+已提交消息输出有意牺牲逐 token 输出的低延迟，以换取干净的自动化结果。未提交的提供方分片和重试尝试无法泄漏部分文本；推理与工具活动仍保留在会话日志中，以便其他界面观测。
+
+## 生命周期
+
+客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
+
+ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入空闲状态前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `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=…]` 引用，模型可以使用自身工具打开它。协议元数据、客户端能力、权限选择和会话 id 绝不进入模型请求。
+
+#### Token 影响
+
+提示词 token 取决于数据，并保留在该会话的历史中直到上下文压缩（context compaction）。并发 ACP 会话保留独立上下文。
+
+#### KV Cache 影响
+
+仅追加；新用户消息位于可复用请求前缀之后，不会使先前缓存条目失效。
+
+### 权限决策
+
+#### 模型看到的内容
+
+不会直接看到任何内容。所属工具通过常规工具结果路径记录其结果：允许、拒绝、取消或不可用。
+
+#### Token 影响
+
+只有所属工具的结果会贡献 token。
+
+#### KV Cache 影响
+
+仅通过所属工具的结果追加。
+
+## 已知限制与暂缓事项
+
+- **仅新会话**：不支持加载、列出、恢复、删除和 fork。
+- **仅基线提示词和一个 workspace**：图像、音频、嵌入资源、非空附加目录和 MCP 服务器都会被拒绝；资源链接只会展平为文本引用，不会获取其内容。
+- **仅已提交答案**：实时进度、推理、工具活动、计划、标题和用量不会通过协议传输。
+- **由连接管理的生命周期**：一个连接会释放其所有会话；尚未实现单个会话关闭功能。

package/lib/index.js

@@ -0,0 +1,530 @@
+import { createRequire } from "node:module";
+import { randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { Readable, Writable } from "node:stream";
+import Schema from "@monotykamary/schemastery";
+import "@monotykamary/cordis";
+import { AgentSideConnection, PROTOCOL_VERSION, RequestError, ndJsonStream } from "@agentclientprotocol/sdk";
+import { SessionId } from "@monotykamary/dsh-session";
+//#region ../../llm/llm/src/brand.ts
+/**
+* Brand a message identifier.
+* @param id - the opaque message identifier.
+* @returns the same string, branded; no validation is performed.
+*/
+function MessageId(id) {
+	return id;
+}
+//#endregion
+//#region ../../llm/llm/src/call-config.ts
+/**
+* Deep-freeze a value in place with an iterative traversal, guarding cycles,
+* so later mutation throws without imposing a JavaScript call-stack depth cap.
+* {@link AbortSignal} objects are deliberately skipped because they are the
+* request's live cancellation channel and freezing them breaks abort.
+* @param value - the value to freeze in place.
+* @returns the same value, frozen.
+*/
+function deepFreeze(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const pending = [{
+		kind: "visit",
+		node: value
+	}];
+	while (pending.length > 0) {
+		const task = pending.pop();
+		/* v8 ignore next -- the loop condition guarantees one pending task. */
+		if (task === void 0) continue;
+		if (task.kind === "property") {
+			pending.push({
+				kind: "visit",
+				node: task.source[task.key]
+			});
+			continue;
+		}
+		const node = task.node;
+		if (node === null || typeof node !== "object") continue;
+		if (node instanceof AbortSignal) continue;
+		if (seen.has(node)) continue;
+		seen.add(node);
+		Object.freeze(node);
+		const keys = Object.keys(node);
+		for (let index = keys.length - 1; index >= 0; index--) {
+			const key = keys[index];
+			/* v8 ignore next -- the loop is bounded by the captured key count. */
+			if (key === void 0) continue;
+			pending.push({
+				kind: "property",
+				source: node,
+				key
+			});
+		}
+	}
+	return value;
+}
+//#endregion
+//#region ../../llm/llm/src/message.ts
+/** Message value types, identity, and immutable construction helpers. */
+/**
+* Detach and deep-freeze a message whose identity already exists.
+* @param message - complete message, including its stable identity.
+* @returns an immutable snapshot that preserves the identity.
+*/
+function freezeMessage(message) {
+	return deepFreeze(structuredClone(message));
+}
+/**
+* Create one identified message and freeze it before publication.
+* @param input - complete role, content, and source for a new message.
+* @returns an immutable message with a fresh stable identity.
+*/
+function createMessage(input) {
+	return freezeMessage({
+		...input,
+		id: MessageId(crypto.randomUUID())
+	});
+}
+/**
+* Create one identified user-role message and freeze it before publication.
+* @param input - complete content and source for a new user message.
+* @returns an immutable user message with a fresh stable identity.
+*/
+function createUserMessage(input) {
+	return createMessage({
+		...input,
+		role: "user"
+	});
+}
+//#endregion
+//#region ../../util/timeout/src/index.ts
+/** Largest delay Node schedules without clamping it to one millisecond. */
+const MAX_TIMER_DELAY_MS = 2147483647;
+//#endregion
+//#region ../../llm/llm/src/error.ts
+/**
+* Canonical provider-neutral code for a response that completed normally but
+* carried no content blocks at all. Providers occasionally emit a degenerate
+* completion (a terminal stop with zero output); adapters classify it as this
+* failure instead of yielding an empty assistant message, because an empty
+* message silently ends the turn with nothing for the user or the loop to act
+* on. The attempt produced nothing durable, so retry policy treats it as safe
+* to repeat.
+*/
+const EMPTY_RESPONSE_CODE = "EMPTY_RESPONSE";
+new RegExp(String.raw`(?:^|[^a-z0-9])context[\s_-](?:length|window)[\s_-]` + String.raw`(?:exceed(?:ed|s)?|overflow(?:ed)?|limit[\s_-]exceeded)(?:$|[^a-z0-9])`, "i");
+new RegExp(String.raw`\b(?:request|prompt|input|messages?)\s+(?:is\s+|are\s+)?` + String.raw`too\s+(?:large|long)\s+for\s+(?:(?:this|the)\s+)?` + String.raw`(?:model(?:'s)?\s+)?context(?:\s+window)?\b`, "i");
+new RegExp(String.raw`\b(?:input|prompt|request|messages?)\b.{0,40}` + String.raw`\b(?:exceed(?:s|ed)?|overflows?|is\s+larger\s+than)\b.{0,40}` + String.raw`\b(?:the\s+)?(?:model(?:'s)?\s+)?context(?:\s+(?:length|window))?\b`, "i");
+/**
+* Render a thrown value with its full `cause` chain and AggregateError
+* members, so transport wrappers like undici's `TypeError: fetch failed`
+* surface the underlying failure instead of masking it. Plain structured
+* failures render their own data-backed `message`. Diagnostic-surface
+* rendering only (messages, notices, logs) — never parse the result; route on
+* {@link HarnessError.code}.
+* @param value - the caught value (`unknown` in catch clauses).
+* @returns the outermost message first, each cause appended with `: ` (skipped
+* when it repeats the wrapper message verbatim), and AggregateError members
+* bracketed and `; `-joined.
+*/
+function errorChain(value) {
+	const path = /* @__PURE__ */ new Set();
+	const render = (current) => {
+		if (path.has(current)) return "<circular cause>";
+		path.add(current);
+		try {
+			if (!(current instanceof Error)) {
+				if (typeof current === "object" && current !== null) {
+					const descriptor = Object.getOwnPropertyDescriptor(current, "message");
+					if (descriptor !== void 0 && "value" in descriptor && typeof descriptor.value === "string") return descriptor.value;
+				}
+				return String(current);
+			}
+			const message = current.message === "" ? current.name : current.message;
+			const members = current instanceof AggregateError && current.errors.length > 0 ? ` [${current.errors.map(render).join("; ")}]` : "";
+			const causeText = current.cause === void 0 || current.cause === null ? "" : render(current.cause);
+			return `${message}${members}${causeText === "" || causeText === message ? "" : `: ${causeText}`}`;
+		} catch {
+			return "<unrenderable value>";
+		} finally {
+			path.delete(current);
+		}
+	};
+	return render(value);
+}
+//#endregion
+//#region ../../llm/llm/src/retry-policy.ts
+/**
+* Provider-owned request-retry policy configuration and resolution.
+*
+* Adapters expose one resolved policy per registered provider route; the
+* optional dsh-llm-retry plugin executes it on the agent's failed-step extension point.
+*
+* @module @monotykamary/dsh-llm/retry-policy
+*/
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_INITIAL_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 1e4;
+const DEFAULT_JITTER_RATIO = .1;
+const DEFAULT_RETRYABLE_CODES = Object.freeze([
+	EMPTY_RESPONSE_CODE,
+	"RATE_LIMIT",
+	"SERVER",
+	"TIMEOUT",
+	"TRANSPORT"
+]);
+const backoffSchema = Schema.object({
+	initialDelayMs: Schema.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_INITIAL_DELAY_MS),
+	maxDelayMs: Schema.number().max(MAX_TIMER_DELAY_MS).default(DEFAULT_MAX_DELAY_MS),
+	jitterRatio: Schema.number().min(0).max(1).default(DEFAULT_JITTER_RATIO)
+});
+const normalPolicySchema = Schema.object({
+	mode: Schema.const("normal").required(),
+	maxRetries: Schema.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_RETRIES),
+	retryableCodes: Schema.array(Schema.string()).default([...DEFAULT_RETRYABLE_CODES]),
+	backoff: backoffSchema
+});
+const alwaysPolicySchema = Schema.object({
+	mode: Schema.const("always").required(),
+	backoff: backoffSchema
+});
+Schema.union([normalPolicySchema, alwaysPolicySchema]);
+//#endregion
+//#region ../../llm/llm/src/attribution.ts
+/**
+* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
+* adapters from drifting. See
+* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+*
+* App-attribution vocabulary for provider requests.
+* @module @monotykamary/dsh-llm/attribution
+*/
+const { version } = createRequire(import.meta.url)("../package.json");
+//#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";
+	}
+}
+/**
+* Flatten an ACP prompt's baseline blocks to text. Text blocks concatenate
+* verbatim; resource links become explicit textual references so a baseline
+* client can point at files without the bridge silently dropping that context.
+* @param prompt - supported ACP prompt blocks.
+* @returns text in wire order, with resource links rendered as bracketed references.
+*/
+function acpPromptToText(prompt) {
+	return prompt.flatMap((block) => {
+		switch (block.type) {
+			case "text": return [block.text];
+			case "resource_link": return [`\n[resource_link name=${JSON.stringify(block.name)} uri=${JSON.stringify(block.uri)}]\n`];
+			default: return [];
+		}
+	}).join("");
+}
+/**
+* Whether a prompt carries content beyond the ACP baseline. The spec requires
+* every agent to accept `text` and `resource_link`; richer inline payloads
+* (image, audio, embedded resource) are optional capabilities this bridge does
+* not advertise, so they are rejected rather than silently dropped.
+* @param prompt - ACP prompt blocks to inspect.
+* @returns `true` when any block is neither `text` nor `resource_link`.
+*/
+function promptHasUnsupportedContent(prompt) {
+	return prompt.some((block) => block.type !== "text" && block.type !== "resource_link");
+}
+//#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, committed assistant text, 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;
+	/** 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 a protocol update without letting a disconnected client fail an agent turn. */
+	const notify = (notification) => {
+		/* v8 ignore next 3 -- only a transport write failure reaches this guard. */
+		conn.sessionUpdate(notification).catch((error) => {
+			logger.warn(`acp: session/update failed: ${String(error)}`);
+		});
+	};
+	const settlePrompt = (record, reason) => {
+		const inflight = record.inflight;
+		if (inflight === void 0) return;
+		record.inflight = void 0;
+		inflight.resolve(reason);
+	};
+	const rejectFromError = (inflight, reason) => {
+		inflight.reject(internalError(`turn failed: ${reason.error.message}`));
+	};
+	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") {
+				for (const block of event.data.message.content) if (block.type === "text" && block.text.length > 0) notify({
+					sessionId: record.agent.session.id,
+					update: {
+						sessionUpdate: "agent_message_chunk",
+						content: {
+							type: "text",
+							text: block.text
+						}
+					}
+				});
+				else if (block.type === "image") notify({
+					sessionId: record.agent.session.id,
+					update: {
+						sessionUpdate: "agent_message_chunk",
+						content: {
+							type: "text",
+							text: `[image attachment ${block.attachment.attachmentId}]`
+						}
+					}
+				});
+			}
+		} finally {
+			const inflight = record.inflight;
+			if (inflight !== void 0 && event.type === "turn/end" && inflight.turn === event.data.turn) if (event.data.reason.kind === "error") {
+				record.inflight = void 0;
+				rejectFromError(inflight, event.data.reason);
+			} else 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.turn === turn) return;
+		record.inflight = void 0;
+		inflight.reject(internalError(`turn failed: ${errorChain(error)}`));
+	});
+	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 {
+			initialize(_params) {
+				return Promise.resolve({
+					protocolVersion: PROTOCOL_VERSION,
+					agentInfo: {
+						name: "deepseek-harness-acp",
+						version: "0.0.1"
+					},
+					agentCapabilities: { promptCapabilities: {
+						image: false,
+						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(),
+					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");
+				if (promptHasUnsupportedContent(params.prompt)) throw invalidParams("only text and resource_link prompt content is supported");
+				const text = acpPromptToText(params.prompt);
+				if (text.trim().length === 0) throw invalidParams("empty prompt");
+				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: [{
+						type: "text",
+						text
+					}],
+					source: { kind: "user" }
+				});
+				return { stopReason: await new Promise((resolve, reject) => {
+					const inflight = {
+						resolve,
+						reject,
+						messageId: message.id,
+						turn: void 0,
+						endReason: void 0
+					};
+					record.inflight = inflight;
+					try {
+						record.agent.followup(message);
+					} catch (error) {
+						record.inflight = void 0;
+						throw internalError(`prompt was not queued: ${error instanceof Error ? error.message : String(error)}`);
+					}
+					/* v8 ignore stop */
+					record.agent.whenIdle().then(() => {
+						if (record.inflight !== inflight) return;
+						record.inflight = void 0;
+						const end = inflight.endReason;
+						if (end === void 0) inflight.resolve("cancelled");
+						else inflight.resolve(end.kind === "max-tokens" ? "end_turn" : turnEndToStopReason(end));
+					});
+				}) };
+			},
+			cancel(params) {
+				const record = sessions.get(SessionId(params.sessionId));
+				if (record === void 0) return Promise.resolve();
+				record.agent.cancel({ kind: "user" });
+				settlePrompt(record, "cancelled");
+				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) {
+			record.agent.cancel({ kind: "user" });
+			settlePrompt(record, "cancelled");
+		}
+		quiescing = (async () => {
+			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,30 @@
+/**
+ * Pure translation between the harness lifecycle and the automation-only ACP wire.
+ * @module @monotykamary/dsh-acp/codec
+ */
+import type { ContentBlock as AcpContentBlock, 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;
+/**
+ * Flatten an ACP prompt's baseline blocks to text. Text blocks concatenate
+ * verbatim; resource links become explicit textual references so a baseline
+ * client can point at files without the bridge silently dropping that context.
+ * @param prompt - supported ACP prompt blocks.
+ * @returns text in wire order, with resource links rendered as bracketed references.
+ */
+export declare function acpPromptToText(prompt: readonly AcpContentBlock[]): string;
+/**
+ * Whether a prompt carries content beyond the ACP baseline. The spec requires
+ * every agent to accept `text` and `resource_link`; richer inline payloads
+ * (image, audio, embedded resource) are optional capabilities this bridge does
+ * not advertise, so they are rejected rather than silently dropped.
+ * @param prompt - ACP prompt blocks to inspect.
+ * @returns `true` when any block is neither `text` nor `resource_link`.
+ */
+export declare function promptHasUnsupportedContent(prompt: readonly AcpContentBlock[]): boolean;
+//# sourceMappingURL=codec.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, committed assistant text, 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,56 @@
+{
+  "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.5",
+  "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-agent": "^0.1.0-rc.5",
+    "@monotykamary/dsh-user-approval": "^0.1.0-rc.5",
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.5",
+    "@monotykamary/dsh-session": "^0.1.0-rc.5",
+    "@monotykamary/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@monotykamary/dsh-invariants": "^0.1.0-rc.5",
+    "@monotykamary/dsh-llm": "^0.1.0-rc.5",
+    "@monotykamary/dsh-session": "^0.1.0-rc.5",
+    "@monotykamary/dsh-tools": "^0.1.0-rc.5",
+    "@monotykamary/dsh-agent": "^0.1.0-rc.5",
+    "@monotykamary/cordis": "^4.0.1",
+    "@monotykamary/dsh-user-approval": "^0.1.0-rc.5",
+    "@monotykamary/dsh-agent-loop-testkit": "^0.1.0-rc.5",
+    "@monotykamary/dsh-agent-loop": "^0.1.0-rc.5"
+  }
+}