examples/acp-agent/README.md

# acp-agent example

English | [中文](README.zh.md)

Automation-oriented [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. It is intended for parent agents, subagent providers, and other programmatic clients, not as the product UI.

```sh
pnpm run demo:acp             # needs DEEPSEEK_API_KEY (repo-root .env or env)
pnpm run demo:code-mode       # same protocol with the Code Mode tool transport
```

The leaf loads the ACP app, DeepSeek adapter, sandboxed bash and filesystem stacks, one-shot approval policy, compaction, subagents, workflows, hooks, a derived session-query index, and repeat guard. The app creates one fresh agent per `session/new`, persists sessions to JSONL, and keeps stdout protocol-pure. Optional overlays add session queries, filesystem spill storage, Code Mode, or web fetching.

## Protocol channel

Stdout carries only newline-delimited ACP JSON-RPC. `@deepseek-ai/dsh-acp-demo` installs no stdout logger; leaf additions must use stderr for diagnostics.

The automation contract — supported methods, baseline prompt content, committed-text output, and the intentionally absent UI surfaces — lives in [`@deepseek-ai/dsh-acp`](../../packages/acp/acp/README.md).

## Session workspaces and permissions

Each `session/new` supplies an absolute `cwd`. Sandboxed bash and filesystem mutations resolve `workspace-write` against that session cwd, so concurrent sessions can use separate project roots; platform temporary roots remain shared writable scratch space ([sandbox contract](../../packages/sandbox/sandbox/README.md)). `DSH_PERMISSION_MODE` selects `workspace-write` or `danger-full-access` for the deployment.

Under `workspace-write`, a model retry requesting wider sandbox access triggers `session/request_permission` with `allow_once` and `reject_once`. The client decides programmatically; dismissal or an unavailable answer fails closed. The selected outcome applies only to that retry and is recorded through the normal tool-result/audit path. The server never exposes a permission picker or persists client policy.
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00			`# acp-agent example`

docs: translate remaining READMEs 2026-07-26 05:03:53 +08:00			`English \| [中文](README.zh.md)`

refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			`Automation-oriented [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. It is intended for parent agents, subagent providers, and other programmatic clients, not as the product UI.`
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00
			```sh
refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			`pnpm run demo:acp # needs DEEPSEEK_API_KEY (repo-root .env or env)`
fix(cli): close shared config review gaps 2026-07-30 14:56:39 +08:00			`pnpm run demo:code-mode # same protocol with the Code Mode tool transport`
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00			```

docs: apply hierarchy across the corpus 2026-08-04 00:54:19 +08:00			The leaf loads the ACP app, DeepSeek adapter, sandboxed bash and filesystem stacks, one-shot approval policy, compaction, subagents, workflows, hooks, a derived session-query index, and repeat guard. The app creates one fresh agent per `session/new`, persists sessions to JSONL, and keeps stdout protocol-pure. Optional overlays add session queries, filesystem spill storage, Code Mode, or web fetching.
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00
refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			`## Protocol channel`
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00
refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			Stdout carries only newline-delimited ACP JSON-RPC. `@deepseek-ai/dsh-acp-demo` installs no stdout logger; leaf additions must use stderr for diagnostics.
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00
docs: repair rewritten rationale and stale claims from the ACP reduction 2026-07-24 22:12:23 +08:00			The automation contract — supported methods, baseline prompt content, committed-text output, and the intentionally absent UI surfaces — lives in [`@deepseek-ai/dsh-acp`](../../packages/acp/acp/README.md).
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00
refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			`## Session workspaces and permissions`
feat(acp): ACP bridge — drive the coding agent from an editor over JSON-RPC stdio 2026-06-16 11:10:25 +08:00
docs: apply hierarchy across the corpus 2026-08-04 00:54:19 +08:00			Each `session/new` supplies an absolute `cwd`. Sandboxed bash and filesystem mutations resolve `workspace-write` against that session cwd, so concurrent sessions can use separate project roots; platform temporary roots remain shared writable scratch space ([sandbox contract](../../packages/sandbox/sandbox/README.md)). `DSH_PERMISSION_MODE` selects `workspace-write` or `danger-full-access` for the deployment.
refactor(examples): fold the sandbox composition into acp-agent as its variant 2026-07-12 19:57:33 +08:00
refactor(acp): reduce bridge to automation protocol 2026-07-24 01:40:25 +08:00			Under `workspace-write`, a model retry requesting wider sandbox access triggers `session/request_permission` with `allow_once` and `reject_once`. The client decides programmatically; dismissal or an unavailable answer fails closed. The selected outcome applies only to that retry and is recorded through the normal tool-result/audit path. The server never exposes a permission picker or persists client policy.